omni.OmniDashboardEmbedder

Factory class for building and signing dashboard embedding URLs.

Parameters:

Name	Type	Description	Default
organization_name	str | None	organization_name: Omni organization name. OMNI_ORGANIZATION_NAME environment variable will be used as a fallback.	None
embed_secret	str | None	Omni embed secret. OMNI_EMBED_SECRET environment variable will be used as a fallback.	None
vanity_domain	str | None	Vanity domain configured with Omni. Should not be fully qualified. OMNI_VANITY_DOMAIN environment variable will be used as a fallback.	None

Attributes:

Name	Type	Description
embed_login_url		Base url of embedded dashboard urls.
embed_secret		Omni embed secret.

Source code in src/omni/embed.py

class OmniDashboardEmbedder:
    """Factory class for building and signing dashboard embedding URLs.

    Args:
        organization_name: organization_name: Omni organization name. OMNI_ORGANIZATION_NAME environment variable will
            be used as a fallback.
        embed_secret: Omni embed secret. OMNI_EMBED_SECRET environment variable will be used as a fallback.
        vanity_domain: Vanity domain configured with Omni. Should not be fully qualified. OMNI_VANITY_DOMAIN
            environment variable will be used as a fallback.

    Attributes:
        embed_login_url: Base url of embedded dashboard urls.
        embed_secret: Omni embed secret.
    """

    class AccessMode(Enum):
        """AccessMode options

        Attributes:
            application: APPLICATION
            single_content: SINGLE_CONTENT
        """

        application = "APPLICATION"
        single_content = "SINGLE_CONTENT"

    class ContentRole(Enum):
        """ContentRole options

        Attributes:
            viewer: VIEWER
            editor: EDITOR
            manager: MANAGER
            no_access: NO_ACCESS
        """

        viewer = "VIEWER"
        editor = "EDITOR"
        manager = "MANAGER"
        no_access = "NO_ACCESS"

    class PrefersDark(Enum):
        """PrefersDark options

        Attributes:
            yes: true
            no: false
            system: system
        """

        yes = "true"
        no = "false"
        system = "system"

    class Theme(Enum):
        """Theme options

        Attributes:
            dawn: dawn
            vibes: vibes
            breeze: breeze
            blank: blank
        """

        dawn = "dawn"
        vibes = "vibes"
        breeze = "breeze"
        blank = "blank"

    def __init__(
        self,
        organization_name: str | None = None,
        embed_secret: str | None = None,
        vanity_domain: str | None = None,
    ):
        omni_config = OmniConfig(
            required_attrs=["embed_secret"],
            organization_name=organization_name,
            embed_secret=embed_secret,
            vanity_domain=vanity_domain,
        )
        if not omni_config.vanity_domain and not omni_config.organization_name:
            raise OmniConfigError(
                "You must pass the vanity_domain or organization_name arguments OR "
                "set the OMNI_ORGANIZATION_NAME or OMNI_VANITY_DOMAIN environment variables."
            )
        embed_host = (
            omni_config.vanity_domain
            or f"{omni_config.organization_name}.embed-omniapp.co"
        )
        self.embed_login_url = f"https://{embed_host}/embed/login"

        # Required to appease mypy. If embed_secret is missing an OmniConfigError will have already been raised by the OmniConfig class.
        assert omni_config.embed_secret

        self.embed_secret = omni_config.embed_secret

    def build_url(
        self,
        content_path: str,
        external_id: str,
        name: str,
        access_boost: bool | None = None,
        connection_roles: dict | None = None,
        custom_theme: dict | None = None,
        custom_theme_id: str | None = None,
        email: str | None = None,
        entity: str | None = None,
        entity_folder_content_role: ContentRole | None = None,
        entity_folder_group_content_role: ContentRole | None = None,
        entity_folder_label: str | None = None,
        entity_group_label: str | None = None,
        filter_search_params: str | dict | None = None,
        groups: list[str] | None = None,
        link_access: bool | list[str] | None = None,
        mode: AccessMode | None = None,
        model_roles: dict | None = None,
        prefers_dark: PrefersDark | None = None,
        preserve_entity_folder_content_role: bool | None = None,
        theme: Theme | None = None,
        ui_settings: dict | None = None,
        user_attributes: dict | None = None,
    ) -> str:
        """
        Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs:
        https://docs.omni.co/embed/setup/url-parameters

        Args:
            access_boost (bool, optional): Enables AccessBoost for the embedded dashboard.
            connection_roles (dict, optional): Level of access for all models in a connection.
            content_path (str): Path pointing to the dashboard you wish to embed.
            custom_theme (dict, optional): Custom theme properties for styling embedded dashboards.
            custom_theme_id (str, optional): Theme ID from your Omni instance to stylize embedded dashboards.
            email (str, optional): Email for entity users when sharing content or sending deliveries.
            entity (str, optional): User group identifier to associate the embed user with a larger group.
            entity_folder_content_role (str, optional): Content role for the embed user's shared entity folder.
            entity_folder_group_content_role (str, optional): Content role for the embed entity group shared folder.
            entity_folder_label (str, optional): Label for the embed user's associated entity folder.
            entity_group_label (str, optional): Label for the embed user's associated entity group.
            external_id (str): Unique ID for the embed user.
            filter_search_params (str | dict, optional): Filters to apply for the embedded content.
            groups (list[str], optional): Associate embed user with existing user groups in your Omni instance.
            link_access (bool | list[str], optional): Controls which Omni dashboards can be linked to from the embedded dashboard.
            mode (AccessMode, optional): Type of access users will have to Omni in the iframe.
            model_roles (dict, optional): Level of access for individual models in a connection.
            name (str): Name for the embed user's name property.
            prefers_dark (PrefersDark, optional): Light or dark mode appearance.
            preserve_entity_folder_content_role (bool, optional): Retains the embed user's existing entity folder content role.
            theme (Theme, optional): Built-in Omni application theme.
            ui_settings (dict, optional): General settings of the application in embed.
            user_attributes (dict, optional): User attributes to apply to the embed user.

        Returns:
            str: Signed dashboard embedding URL.
        """

        # Preprocess some values before passing to URL object.
        if link_access is True:
            _link_access = "__omni_link_access_open"
        elif isinstance(link_access, list):
            _link_access = ",".join(link_access)
        elif not link_access:
            _link_access = None
        else:
            raise ValueError(
                "link_access must be a list of dashboard IDs or True to allow links to all dashboards."
            )

        # Convert empty dicts and strings to None.
        filter_search_params = filter_search_params or None
        if isinstance(filter_search_params, dict):
            filter_search_params = urllib.parse.urlencode(
                filter_search_params, doseq=True
            )

        url = DashboardEmbedUrl(
            base_url=self.embed_login_url,
            contentPath=content_path,
            externalId=external_id,
            name=name,
            accessBoost="true" if access_boost else None,
            connectionRoles=(
                compact_json_dump(connection_roles) if connection_roles else None
            ),
            customTheme=compact_json_dump(custom_theme) if custom_theme else None,
            customThemeId=custom_theme_id,
            email=email,
            entity=entity,
            entityFolderContentRole=(
                entity_folder_content_role.value if entity_folder_content_role else None
            ),
            entityFolderGroupContentRole=(
                entity_folder_group_content_role.value
                if entity_folder_group_content_role
                else None
            ),
            entityFolderLabel=entity_folder_label,
            entityGroupLabel=entity_group_label,
            filterSearchParam=filter_search_params,
            groups=compact_json_dump(groups) if groups else None,
            linkAccess=_link_access,
            mode=mode.value if mode else None,
            modelRoles=compact_json_dump(model_roles) if model_roles else None,
            prefersDark=prefers_dark.value if prefers_dark else None,
            preserveEntityFolderContentRole=(
                "true" if preserve_entity_folder_content_role else None
            ),
            theme=theme.value if theme else None,
            uiSettings=compact_json_dump(ui_settings) if ui_settings else None,
            userAttributes=(
                compact_json_dump(user_attributes) if user_attributes else None
            ),
            nonce=uuid.uuid4().hex,
        )

        self._sign_url(url)
        return str(url)

    def _sign_url(self, url: DashboardEmbedUrl) -> None:
        """Creates a signature and adds it to the URL object."""

        # IMPORTANT: These must be in the correct order as documented here
        # https://docs.omni.co/embed/setup/standard-sso#manual-generation

        blob_items = [
            url.base_url,
            url.contentPath,
            url.externalId,
            url.name,
            url.nonce,
            url.accessBoost,
            url.connectionRoles,
            url.customTheme,
            url.customThemeId,
            url.email,
            url.entity,
            url.entityFolderContentRole,
            url.entityFolderGroupContentRole,
            url.entityFolderLabel,
            url.entityGroupLabel,
            url.filterSearchParam,
            url.groups,
            url.linkAccess,
            url.mode,
            url.modelRoles,
            url.prefersDark,
            url.preserveEntityFolderContentRole,
            url.theme,
            url.uiSettings,
            url.userAttributes,
        ]
        blob = "\n".join([i for i in blob_items if i is not None])
        hmac_hash = hmac.new(
            self.embed_secret.encode("utf-8"), blob.encode("utf-8"), hashlib.sha256
        ).digest()
        url.signature = base64.urlsafe_b64encode(hmac_hash).decode("utf-8")

AccessMode

Bases: Enum

AccessMode options

Attributes:

Name	Type	Description
application		APPLICATION
single_content		SINGLE_CONTENT

Source code in src/omni/embed.py

class AccessMode(Enum):
    """AccessMode options

    Attributes:
        application: APPLICATION
        single_content: SINGLE_CONTENT
    """

    application = "APPLICATION"
    single_content = "SINGLE_CONTENT"

ContentRole

Bases: Enum

ContentRole options

Attributes:

Name	Type	Description
viewer		VIEWER
editor		EDITOR
manager		MANAGER
no_access		NO_ACCESS

Source code in src/omni/embed.py

class ContentRole(Enum):
    """ContentRole options

    Attributes:
        viewer: VIEWER
        editor: EDITOR
        manager: MANAGER
        no_access: NO_ACCESS
    """

    viewer = "VIEWER"
    editor = "EDITOR"
    manager = "MANAGER"
    no_access = "NO_ACCESS"

PrefersDark

Bases: Enum

PrefersDark options

Attributes:

Name	Type	Description
yes		true
no		false
system		system

Source code in src/omni/embed.py

class PrefersDark(Enum):
    """PrefersDark options

    Attributes:
        yes: true
        no: false
        system: system
    """

    yes = "true"
    no = "false"
    system = "system"

Theme

Bases: Enum

Theme options

Attributes:

Name	Type	Description
dawn		dawn
vibes		vibes
breeze		breeze
blank		blank

Source code in src/omni/embed.py

class Theme(Enum):
    """Theme options

    Attributes:
        dawn: dawn
        vibes: vibes
        breeze: breeze
        blank: blank
    """

    dawn = "dawn"
    vibes = "vibes"
    breeze = "breeze"
    blank = "blank"

build_url(content_path, external_id, name, access_boost=None, connection_roles=None, custom_theme=None, custom_theme_id=None, email=None, entity=None, entity_folder_content_role=None, entity_folder_group_content_role=None, entity_folder_label=None, entity_group_label=None, filter_search_params=None, groups=None, link_access=None, mode=None, model_roles=None, prefers_dark=None, preserve_entity_folder_content_role=None, theme=None, ui_settings=None, user_attributes=None)

Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs: https://docs.omni.co/embed/setup/url-parameters

Parameters:

Name	Type	Description	Default
access_boost	bool	Enables AccessBoost for the embedded dashboard.	None
connection_roles	dict	Level of access for all models in a connection.	None
content_path	str	Path pointing to the dashboard you wish to embed.	required
custom_theme	dict	Custom theme properties for styling embedded dashboards.	None
custom_theme_id	str	Theme ID from your Omni instance to stylize embedded dashboards.	None
email	str	Email for entity users when sharing content or sending deliveries.	None
entity	str	User group identifier to associate the embed user with a larger group.	None
entity_folder_content_role	str	Content role for the embed user's shared entity folder.	None
entity_folder_group_content_role	str	Content role for the embed entity group shared folder.	None
entity_folder_label	str	Label for the embed user's associated entity folder.	None
entity_group_label	str	Label for the embed user's associated entity group.	None
external_id	str	Unique ID for the embed user.	required
filter_search_params	str | dict	Filters to apply for the embedded content.	None
groups	list[str]	Associate embed user with existing user groups in your Omni instance.	None
link_access	bool | list[str]	Controls which Omni dashboards can be linked to from the embedded dashboard.	None
mode	AccessMode	Type of access users will have to Omni in the iframe.	None
model_roles	dict	Level of access for individual models in a connection.	None
name	str	Name for the embed user's name property.	required
prefers_dark	PrefersDark	Light or dark mode appearance.	None
preserve_entity_folder_content_role	bool	Retains the embed user's existing entity folder content role.	None
theme	Theme	Built-in Omni application theme.	None
ui_settings	dict	General settings of the application in embed.	None
user_attributes	dict	User attributes to apply to the embed user.	None

Returns:

Name	Type	Description
str	str	Signed dashboard embedding URL.

Source code in src/omni/embed.py

def build_url(
    self,
    content_path: str,
    external_id: str,
    name: str,
    access_boost: bool | None = None,
    connection_roles: dict | None = None,
    custom_theme: dict | None = None,
    custom_theme_id: str | None = None,
    email: str | None = None,
    entity: str | None = None,
    entity_folder_content_role: ContentRole | None = None,
    entity_folder_group_content_role: ContentRole | None = None,
    entity_folder_label: str | None = None,
    entity_group_label: str | None = None,
    filter_search_params: str | dict | None = None,
    groups: list[str] | None = None,
    link_access: bool | list[str] | None = None,
    mode: AccessMode | None = None,
    model_roles: dict | None = None,
    prefers_dark: PrefersDark | None = None,
    preserve_entity_folder_content_role: bool | None = None,
    theme: Theme | None = None,
    ui_settings: dict | None = None,
    user_attributes: dict | None = None,
) -> str:
    """
    Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs:
    https://docs.omni.co/embed/setup/url-parameters

    Args:
        access_boost (bool, optional): Enables AccessBoost for the embedded dashboard.
        connection_roles (dict, optional): Level of access for all models in a connection.
        content_path (str): Path pointing to the dashboard you wish to embed.
        custom_theme (dict, optional): Custom theme properties for styling embedded dashboards.
        custom_theme_id (str, optional): Theme ID from your Omni instance to stylize embedded dashboards.
        email (str, optional): Email for entity users when sharing content or sending deliveries.
        entity (str, optional): User group identifier to associate the embed user with a larger group.
        entity_folder_content_role (str, optional): Content role for the embed user's shared entity folder.
        entity_folder_group_content_role (str, optional): Content role for the embed entity group shared folder.
        entity_folder_label (str, optional): Label for the embed user's associated entity folder.
        entity_group_label (str, optional): Label for the embed user's associated entity group.
        external_id (str): Unique ID for the embed user.
        filter_search_params (str | dict, optional): Filters to apply for the embedded content.
        groups (list[str], optional): Associate embed user with existing user groups in your Omni instance.
        link_access (bool | list[str], optional): Controls which Omni dashboards can be linked to from the embedded dashboard.
        mode (AccessMode, optional): Type of access users will have to Omni in the iframe.
        model_roles (dict, optional): Level of access for individual models in a connection.
        name (str): Name for the embed user's name property.
        prefers_dark (PrefersDark, optional): Light or dark mode appearance.
        preserve_entity_folder_content_role (bool, optional): Retains the embed user's existing entity folder content role.
        theme (Theme, optional): Built-in Omni application theme.
        ui_settings (dict, optional): General settings of the application in embed.
        user_attributes (dict, optional): User attributes to apply to the embed user.

    Returns:
        str: Signed dashboard embedding URL.
    """

    # Preprocess some values before passing to URL object.
    if link_access is True:
        _link_access = "__omni_link_access_open"
    elif isinstance(link_access, list):
        _link_access = ",".join(link_access)
    elif not link_access:
        _link_access = None
    else:
        raise ValueError(
            "link_access must be a list of dashboard IDs or True to allow links to all dashboards."
        )

    # Convert empty dicts and strings to None.
    filter_search_params = filter_search_params or None
    if isinstance(filter_search_params, dict):
        filter_search_params = urllib.parse.urlencode(
            filter_search_params, doseq=True
        )

    url = DashboardEmbedUrl(
        base_url=self.embed_login_url,
        contentPath=content_path,
        externalId=external_id,
        name=name,
        accessBoost="true" if access_boost else None,
        connectionRoles=(
            compact_json_dump(connection_roles) if connection_roles else None
        ),
        customTheme=compact_json_dump(custom_theme) if custom_theme else None,
        customThemeId=custom_theme_id,
        email=email,
        entity=entity,
        entityFolderContentRole=(
            entity_folder_content_role.value if entity_folder_content_role else None
        ),
        entityFolderGroupContentRole=(
            entity_folder_group_content_role.value
            if entity_folder_group_content_role
            else None
        ),
        entityFolderLabel=entity_folder_label,
        entityGroupLabel=entity_group_label,
        filterSearchParam=filter_search_params,
        groups=compact_json_dump(groups) if groups else None,
        linkAccess=_link_access,
        mode=mode.value if mode else None,
        modelRoles=compact_json_dump(model_roles) if model_roles else None,
        prefersDark=prefers_dark.value if prefers_dark else None,
        preserveEntityFolderContentRole=(
            "true" if preserve_entity_folder_content_role else None
        ),
        theme=theme.value if theme else None,
        uiSettings=compact_json_dump(ui_settings) if ui_settings else None,
        userAttributes=(
            compact_json_dump(user_attributes) if user_attributes else None
        ),
        nonce=uuid.uuid4().hex,
    )

    self._sign_url(url)
    return str(url)