Omni Embed SSO Typescript SDK for Server (Node, etc)

Server Side Only

This SDK is intented to be used in a server context.

Your embed secret should never be shipped to a client or browser.

Anyone with access to the secret can craft an embed url and potentially gain access to your Omni instance. Guard your embed secret in the same way you would a private key.

Install

npm:

npm install @omni-co/embed

yarn:

yarn add @omni-co/embed

Basic Examples

import {
  embedSsoDashboard,
  embedSsoWorkbook,
  embedSsoContentDiscovery,
} from "@omni-co/embed";

// This creates a signed embed sso link for a dashboard
// in the omni account named Acme.
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "[email protected]",
  name: "Wile E",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

// Alternatively, you can create a signed embed sso link for a workbook.
const iframeUrl = await embedSsoWorkbook({
  contentId: "miU0hL6z",
  externalId: "[email protected]",
  name: "Wile E",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

// You can also create a signed embed sso link for a content discovery page.
const iframeUrl = await embedSsoContentDiscovery({
  externalId: "[email protected]",
  name: "Wile E",
  path: "root",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

Using Vanity Domains

// Use `host` to create a link to a vanity domain.
// Note: `organizationName` and `domain` are incompatible with `host`
const iframeUrl = await embedSsoDashboard({
  contentId: "miU0hL6z",
  externalId: "[email protected]",
  host: "omni.example.com",
  name: "Wile E",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

embedSsoDashboard

This is the type signature for the embedSsoDashboard function:

type EmbedSsoDashboardProps = {
  // Optional boolean property that toggles the dashboard's Access Boost setting.
  accessBoost?: boolean;

  // Optional object that determines the connection permissions for the embed user.
  connectionRoles?: Record<string, EmbedConnectionRoles>;

  // Short GUID of the dashboard. Can be obtained via the dashboard's url.
  contentId: string;

  // Optional custom theme object that styles the embedded dashboard.
  customTheme?: CustomThemeProperties;

  /**
   * Optional custom theme ID setting that styles the embedded dashboard.
   * This ID should be from a theme created within the Omni application.
   */
  customThemeId?: string;

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string;

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string;

  /**
   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles;

  // Required identifier to associate the external user with an automatically generated internal Omni user.
  externalId: string;

  /**
   * Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
   * Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
   *
   */
  filterSearchParam?: string;

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[];

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `domain` or `organizationName` are provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string;

  /**
   * Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
   * all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
   *
   * "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
   * "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
   * undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
   */
  linkAccess?: string;

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode;

  // Required name of the external user.
  name: string;

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string;

  // Port of host.
  port?: number;

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string;

  // Signing secret available to Omni admins.
  secret: string;

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string;

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>;

  // DEPRECATED

  /**
   * @deprecated Introduced for internal testing only. For vanity domains, use the `host`
   * prop instead. Will be dropped in a v1.0.0 release.
   *
   * @throws Error if `host` is provided.
   */
  domain?: string;
};

embedSsoWorkbook

This is the type signature for the embedSsoWorkbook function:

type EmbedSsoWorkbookProps = {
  // Optional object that determines the connection permissions for the embed user.
  connectionRoles?: Record<string, EmbedConnectionRoles>;

  /**
   * Short GUID of the workbook.
   *
   * Can be obtained via the workbook's share -> embed -> iframe url or via the dashboard url.
   * This will embed the workbook associated with the dashboard id.
   */
  contentId: string;

  /**
   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customTheme?: CustomThemeProperties;

  /**
   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customThemeId?: string;

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string;

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string;

  /**
   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles;

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  externalId: string;

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[];

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `domain` or `organizationName` are provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string;

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode;

  // Required name of the external user.
  name: string;

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string;

  // Port of host.
  port?: number;

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string;

  // Signing secret available to Omni admins.
  secret: string;

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string;

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>;

  // DEPRECATED

  /**
   * @deprecated Introduced for internal testing only. For vanity domains, use the `host`
   * prop instead. Will be dropped in a v1.0.0 release.
   *
   * @throws Error if `host` is provided.
   */
  domain?: string;
};

embedSsoContentDiscovery

This is the type signature for the embedSsoContentDiscovery function:

type EmbedSsoContentDiscoveryProps = {
  // Optional object that determines the connection permissions for the embed user.
  connectionRoles?: Record<string, EmbedConnectionRoles>;

  /**
   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customTheme?: CustomThemeProperties;

  /**
   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customThemeId?: string;

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string;

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string;

  /**
   * Optional content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles;

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  externalId: string;

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[];

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `domain` or `organizationName` are provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string;

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode;

  // Required name of the external user.
  name: string;

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string;

  /**
   * Required path property. The path value determines the starting content discovery page
   * for the generated embed session. Can be one of "my", "entity-folder", or "root".
   *
   * my: "My Content" page
   * entity-folder: embed entity folder
   * root: "Hub" page
   */
  path: EmbedSsoContentDiscoveryPath;

  // Port of host.
  port?: number;

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string;

  // Signing secret available to Omni admins.
  secret: string;

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string;

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>;

  // DEPRECATED

  /**
   * @deprecated Introduced for internal testing only. For vanity domains, use the `host`
   * prop instead. Will be dropped in a v1.0.0 release.
   *
   * @throws Error if `host` is provided.
   */
  domain?: string;
};