@omni-co/embed v0.4.7

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 Example

import { embedSsoDashboard, embedSsoWorkbook } 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: "wile.e@coyote.co",
  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: "wile.e@coyote.co",
  name: "Wile E",
  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: "wile.e@coyote.co",
  host: "omni.example.com",
  name: "Wile E",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
});

Kitchen Sink Example

import { embedSsoDashboard, embedSsoWorkbook } 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: "wile.e@coyote.co",
  entity: "cartoon",
  name: "Wile E",
  organizationName: "acme",
  secret: "abcdefghijklmnopqrstuvwxyz123456",
  prefersDark: "system",
  theme: "vibes",
  userAttributes: { tool: "anvil" },
});

embedSsoDashboard

This is the type signature for the embedSsoDashboard function:

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

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

  // Optional identifier to associate the user with an external
  // organization or system.
  entity?: string;

  // 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;

  /**
   * 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;

  // 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 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[]>;

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

  // 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 EmbedSsoProps = {
  // Short GUID of the workbook. Can be obtained via the workbook's share -> embed -> iframe url or via the dashboard url (will embed the workbook associated with the dashboard id)
  contentId: string;

  // Optional identifier to associate the user with an external
  // organization or system.
  entity?: string;

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  externalId: 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;

  // 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 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[]>;

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

  // 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;
};