Skip to content

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 
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
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 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,
        custom_theme: dict | None = None,
        entity: str | None = None,
        filter_search_params: str | dict | None = None,
        link_access: bool | list[str] | None = None,
        prefers_dark: PrefersDark | None = None,
        theme: Theme | 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/docs/embed/private-embedding#embed-url-customization-options)

        Args:
            content_path: Path pointing to the dashboard you wish to build a URL to embed.
            external_id: Required parameter creating a unique ID. This can be any alphanumeric value.
            name: Required parameter and can contain a non-unique name for the embed user's name property.
            custom_theme: Allows you to stylize your embedded dashboard to your preferred colors.
            entity: An id to reference the entity the user belongs to. Commonly is the customer name or other
                identifying organization for this user.
            filter_search_params: Encoded string or a dict representing dashboard filter values . This can be derived
                by copying the substring after the "?" from a dashboard URL with non-empty filter values or using the
                `OmniFilterSet` helper class.
            link_access: Allows you to customize which other Omni dashboards can be linked to from the embedded dashboard.
                If set to True, all links on the embedded dashboard are permissed and shown. Alternatively, a list of
                dashboard IDs can be passed (i.e. ["abcd1234", "efgh5678", "ijkl9999"]) to only permiss to specific
                dashboard IDs. Finally, if the parameter is None, all links to other Omni dashboards are
                restricted. Note that link URLs to anything other than an Omni Dashboard will be shown and permissed
                regardless of the linkAccess parameter.
            prefers_dark: Dark mode setting.
            theme: Visual theming options.
            user_attributes: Dictionary of attributes matching defined user attributes in your Omni account.

        Returns:
            : 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,
            customTheme=compact_json_dump(custom_theme) if custom_theme else None,
            entity=entity,
            filterSearchParam=filter_search_params,
            linkAccess=_link_access,
            prefersDark=prefers_dark.value if prefers_dark else None,
            theme=theme.value if theme 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/docs/embed/private-embedding#manually-generate-a-signature-and-url-hard-mode
        blob_items = [
            url.base_url,
            url.contentPath,
            url.externalId,
            url.name,
            url.nonce,
            url.customTheme,
            url.entity,
            url.filterSearchParam,
            url.linkAccess,
            url.prefersDark,
            url.theme,
            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")

PrefersDark

Bases: Enum

PrefersDark options

Attributes:

Name Type Description
yes

true
no

false
system

system
Source code in src/omni/embed.py 
57
58
59
60
61
62
63
64
65
66
67
68
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 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
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, custom_theme=None, entity=None, filter_search_params=None, link_access=None, prefers_dark=None, theme=None, user_attributes=None)

Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs

Parameters:

Name Type Description Default
content_path str

Path pointing to the dashboard you wish to build a URL to embed.

 required
external_id str

Required parameter creating a unique ID. This can be any alphanumeric value.

 required
name str

Required parameter and can contain a non-unique name for the embed user's name property.

 required
custom_theme dict | None

Allows you to stylize your embedded dashboard to your preferred colors.

 None
entity str | None

An id to reference the entity the user belongs to. Commonly is the customer name or other identifying organization for this user.

 None
filter_search_params str | dict | None

Encoded string or a dict representing dashboard filter values . This can be derived by copying the substring after the "?" from a dashboard URL with non-empty filter values or using the OmniFilterSet helper class.

 None
link_access bool | list[str] | None

Allows you to customize which other Omni dashboards can be linked to from the embedded dashboard. If set to True, all links on the embedded dashboard are permissed and shown. Alternatively, a list of dashboard IDs can be passed (i.e. ["abcd1234", "efgh5678", "ijkl9999"]) to only permiss to specific dashboard IDs. Finally, if the parameter is None, all links to other Omni dashboards are restricted. Note that link URLs to anything other than an Omni Dashboard will be shown and permissed regardless of the linkAccess parameter.

 None
prefers_dark PrefersDark | None

Dark mode setting.

 None
theme Theme | None

Visual theming options.

 None
user_attributes dict | None

Dictionary of attributes matching defined user attributes in your Omni account.

 None

Returns:

Type Description
str

Signed dashboard embedding URL.
Source code in src/omni/embed.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
def build_url(
    self,
    content_path: str,
    external_id: str,
    name: str,
    custom_theme: dict | None = None,
    entity: str | None = None,
    filter_search_params: str | dict | None = None,
    link_access: bool | list[str] | None = None,
    prefers_dark: PrefersDark | None = None,
    theme: Theme | 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/docs/embed/private-embedding#embed-url-customization-options)

    Args:
        content_path: Path pointing to the dashboard you wish to build a URL to embed.
        external_id: Required parameter creating a unique ID. This can be any alphanumeric value.
        name: Required parameter and can contain a non-unique name for the embed user's name property.
        custom_theme: Allows you to stylize your embedded dashboard to your preferred colors.
        entity: An id to reference the entity the user belongs to. Commonly is the customer name or other
            identifying organization for this user.
        filter_search_params: Encoded string or a dict representing dashboard filter values . This can be derived
            by copying the substring after the "?" from a dashboard URL with non-empty filter values or using the
            `OmniFilterSet` helper class.
        link_access: Allows you to customize which other Omni dashboards can be linked to from the embedded dashboard.
            If set to True, all links on the embedded dashboard are permissed and shown. Alternatively, a list of
            dashboard IDs can be passed (i.e. ["abcd1234", "efgh5678", "ijkl9999"]) to only permiss to specific
            dashboard IDs. Finally, if the parameter is None, all links to other Omni dashboards are
            restricted. Note that link URLs to anything other than an Omni Dashboard will be shown and permissed
            regardless of the linkAccess parameter.
        prefers_dark: Dark mode setting.
        theme: Visual theming options.
        user_attributes: Dictionary of attributes matching defined user attributes in your Omni account.

    Returns:
        : 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,
        customTheme=compact_json_dump(custom_theme) if custom_theme else None,
        entity=entity,
        filterSearchParam=filter_search_params,
        linkAccess=_link_access,
        prefersDark=prefers_dark.value if prefers_dark else None,
        theme=theme.value if theme else None,
        userAttributes=(
            compact_json_dump(user_attributes) if user_attributes else None
        ),
        nonce=uuid.uuid4().hex,
    )
    self._sign_url(url)
    return str(url)