omni-embed

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Omni Embed

Omni 嵌入功能

Embed Omni dashboards in external applications using signed iframe URLs. The

@omni-co/embed

SDK handles URL signing and theme customization. Omni's postMessage events enable two-way communication between the parent app and embedded iframe.

Tip: Use
omni-content-explorer
to find dashboards to embed, and
omni-admin
to manage embed user permissions and user attributes for row-level security.

使用签名的iframe URL将Omni仪表板嵌入外部应用程序。

@omni-co/embed

SDK负责处理URL签名和主题自定义。Omni的postMessage事件支持父应用与嵌入的iframe之间的双向通信。

提示：使用
omni-content-explorer
查找要嵌入的仪表板，使用
omni-admin
管理嵌入用户权限和行级安全的用户属性。

Prerequisites

前置条件

bash

npm install @omni-co/embed

bash

undefined

bash

npm install @omni-co/embed

bash

undefined

Verify the Omni CLI is installed — if not, ask the user to install it

See: https://github.com/exploreomni/cli#readme

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

Show available profiles and select the appropriate one

omni config show

If multiple profiles exist, ask the user which to use, then switch:

omni config use <profile-name>

export OMNI_EMBED_SECRET="your-embed-secret" # Admin → Embed (for URL signing)


The embed secret is found in **Admin → Embed** in your Omni instance. The `OMNI_BASE_URL` for embedding uses the `.embed-omniapp.co` domain, not the standard `.omniapp.co` domain.

omni config use <profile-name>

export OMNI_EMBED_SECRET="your-embed-secret" # Admin → Embed (for URL signing)


嵌入密钥可在您的Omni实例的**Admin → Embed**中找到。用于嵌入的`OMNI_BASE_URL`使用`.embed-omniapp.co`域名，而非标准的`.omniapp.co`域名。

Discovering Commands

命令探索

bash

omni scim --help        # Embed user lookup
omni documents --help   # Document listing
omni folders --help     # Folder listing

Tip: Use
-o json
to force structured output for programmatic parsing, or
-o human
for readable tables. The default is
auto
(human in a TTY, JSON when piped).

bash

omni scim --help        # Embed user lookup
omni documents --help   # Document listing
omni folders --help     # Folder listing

提示：使用
-o json
强制输出结构化内容以便程序化解析，或使用
-o human
输出易读的表格。默认值为
auto
（在TTY中输出人类可读格式，管道传输时输出JSON）。

Signing Embed URLs

签名嵌入URL

Use

embedSsoDashboard()

from the

@omni-co/embed

SDK to generate a signed URL server-side, then load it in an iframe client-side.

typescript

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

const embedUrl = await embedSsoDashboard({
  contentId: "dashboard-uuid",
  secret: process.env.OMNI_EMBED_SECRET,
  host: "yourorg.embed-omniapp.co",       // Hostname only, no https://
  externalId: "user@example.com",
  name: "Jane Doe",
  userAttributes: { brand: ["Acme"] },     // For row-level security
  mode: EmbedSessionMode.SingleContent,
  prefersDark: "false",
});

使用

@omni-co/embed

SDK中的

embedSsoDashboard()

在服务端生成签名URL，然后在客户端将其加载到iframe中。

typescript

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

const embedUrl = await embedSsoDashboard({
  contentId: "dashboard-uuid",
  secret: process.env.OMNI_EMBED_SECRET,
  host: "yourorg.embed-omniapp.co",       // Hostname only, no https://
  externalId: "user@example.com",
  name: "Jane Doe",
  userAttributes: { brand: ["Acme"] },     // For row-level security
  mode: EmbedSessionMode.SingleContent,
  prefersDark: "false",
});

Parameters

参数说明

Parameter	Required	Description
`contentId`	Yes	Dashboard UUID (from URL or Admin → Dashboards)
`secret`	Yes	Embed secret from Admin → Embed
`host`	Yes	Embed hostname only — no protocol, no port
`externalId`	Yes	Unique user identifier (typically email)
`name`	Yes	Display name for the user
`userAttributes`	No	`Record<string, string[]>` for row-level security
`mode`	No	`SingleContent` (default) or `Application` (enables create)
`prefersDark`	No	`"true"` or `"false"` — controls light/dark mode
`customTheme`	No	Theme object (see Custom Themes below)
`entity`	No	Entity name for workspaces (see Entity Workspaces below)

Gotcha: The

host

parameter must be a bare hostname (e.g.,

yourorg.embed-omniapp.co

). Including a protocol (

https://

) or port (

:3000

) causes Omni to return 400.

参数	是否必填	描述
`contentId`	是	仪表板UUID（来自URL或Admin → Dashboards）
`secret`	是	来自Admin → Embed的嵌入密钥
`host`	是	仅嵌入主机名——无协议、无端口
`externalId`	是	唯一用户标识符（通常为邮箱）
`name`	是	用户的显示名称
`userAttributes`	否	用于行级安全的 `Record<string, string[]>` 类型数据
`mode`	否	`SingleContent` （默认）或 `Application` （启用创建功能）
`prefersDark`	否	`"true"` 或 `"false"` ——控制明暗模式
`customTheme`	否	主题对象（见下方自定义主题）
`entity`	否	工作区的实体名称（见下方实体工作区）

注意事项：

host

参数必须是纯主机名（例如

yourorg.embed-omniapp.co

）。包含协议（

https://

）或端口（

:3000

）会导致Omni返回400错误。

Custom Themes

自定义主题

Pass a

customTheme

object to

embedSsoDashboard()

to style the embedded dashboard content (tile backgrounds, text colors, controls, buttons). This controls what's inside the iframe — parent app styling is separate.

typescript

const embedUrl = await embedSsoDashboard({
  // ...signing params
  prefersDark: "false",
  customTheme: {
    "dashboard-background": "#FEF2F2",
    "dashboard-tile-background": "#FFF5F5",
    "dashboard-key-color": "#E60000",
    "dashboard-key-text-color": "#ffffff",
    // ...
  },
});

向

embedSsoDashboard()

传递

customTheme

对象，以设置嵌入仪表板内容的样式（磁贴背景、文本颜色、控件、按钮）。这控制iframe内部的样式——父应用的样式是独立的。

typescript

const embedUrl = await embedSsoDashboard({
  // ...签名参数
  prefersDark: "false",
  customTheme: {
    "dashboard-background": "#FEF2F2",
    "dashboard-tile-background": "#FFF5F5",
    "dashboard-key-color": "#E60000",
    "dashboard-key-text-color": "#ffffff",
    // ...
  },
});

Property Reference

属性参考

Page:

Property	Description
`dashboard-background`	Dashboard page background
`dashboard-page-padding`	Dashboard page padding

Tiles:

Property	Description
`dashboard-tile-margin`	Spacing around tiles
`dashboard-tile-background`	Tile background color
`dashboard-tile-shadow`	Tile box shadow
`dashboard-tile-text-body-color`	Primary text color in tiles
`dashboard-tile-text-secondary-color`	Secondary text color in tiles
`dashboard-tile-border-color`	Tile border color
`dashboard-tile-border-radius`	Tile border radius
`dashboard-tile-border-style`	Tile border style
`dashboard-tile-border-width`	Tile border width
`dashboard-tile-title-font-size`	Title font size
`dashboard-tile-title-font-weight`	Title font weight
`dashboard-tile-title-text-color`	Title text color
`dashboard-tile-title-font-family`	Custom title font (woff2 URL)
`dashboard-tile-text-body-font-family`	Custom body font
`dashboard-tile-text-code-font-family`	Custom code font

Controls (filter dropdowns):

Property	Description
`dashboard-control-background`	Filter control background
`dashboard-control-radius`	Filter control border radius
`dashboard-control-border-color`	Filter control border color
`dashboard-control-text-color`	Filter control text color
`dashboard-control-placeholder-color`	Placeholder text color
`dashboard-control-label-color`	Label text above controls
`dashboard-control-outline-color`	Focus outline color

Control Popovers (dropdown menus):

Property	Description
`dashboard-control-popover-background`	Popover background
`dashboard-control-popover-text-color`	Popover text color
`dashboard-control-popover-secondary-text-color`	Secondary text in popovers
`dashboard-control-popover-link-color`	Link color in popovers
`dashboard-control-popover-divider-color`	Divider color
`dashboard-control-popover-radius`	Popover border radius
`dashboard-control-popover-border-color`	Popover border color
`dashboard-filter-input-background`	Filter input background
`dashboard-filter-input-radius`	Filter input border radius
`dashboard-filter-input-border-color`	Filter input border color
`dashboard-filter-input-text-color`	Filter input text color
`dashboard-filter-input-placeholder-color`	Placeholder text
`dashboard-filter-input-icon-color`	Icon color in filter inputs
`dashboard-filter-input-outline-color`	Focus outline for filter inputs
`dashboard-filter-input-accent-color`	Checkbox, radio, and toggle color
`dashboard-filter-input-accent-invert-color`	Checkmark/dot color inside inputs
`dashboard-filter-input-token-color`	Multi-select token background
`dashboard-filter-input-token-text-color`	Multi-select token text color

Buttons:

Property	Description
`dashboard-key-color`	Primary action color (Update buttons)
`dashboard-key-text-color`	Text color on primary buttons
`dashboard-button-radius`	Button border radius
`dashboard-button-transparent-text-color`	Transparent button text color
`dashboard-button-transparent-interactive-color`	Transparent button hover color
`dashboard-menu-item-interactive-color`	Menu item hover background

页面：

属性	描述
`dashboard-background`	仪表板页面背景
`dashboard-page-padding`	仪表板页面内边距

磁贴：

属性	描述
`dashboard-tile-margin`	磁贴周围间距
`dashboard-tile-background`	磁贴背景颜色
`dashboard-tile-shadow`	磁贴阴影
`dashboard-tile-text-body-color`	磁贴中的主要文本颜色
`dashboard-tile-text-secondary-color`	磁贴中的次要文本颜色
`dashboard-tile-border-color`	磁贴边框颜色
`dashboard-tile-border-radius`	磁贴边框圆角
`dashboard-tile-border-style`	磁贴边框样式
`dashboard-tile-border-width`	磁贴边框宽度
`dashboard-tile-title-font-size`	标题字体大小
`dashboard-tile-title-font-weight`	标题字体粗细
`dashboard-tile-title-text-color`	标题文本颜色
`dashboard-tile-title-font-family`	自定义标题字体（woff2 URL）
`dashboard-tile-text-body-font-family`	自定义正文字体
`dashboard-tile-text-code-font-family`	自定义代码字体

控件（筛选下拉框）：

属性	描述
`dashboard-control-background`	筛选控件背景
`dashboard-control-radius`	筛选控件边框圆角
`dashboard-control-border-color`	筛选控件边框颜色
`dashboard-control-text-color`	筛选控件文本颜色
`dashboard-control-placeholder-color`	占位符文本颜色
`dashboard-control-label-color`	控件上方的标签文本颜色
`dashboard-control-outline-color`	聚焦时的轮廓颜色

控件弹出框（下拉菜单）：

属性	描述
`dashboard-control-popover-background`	弹出框背景
`dashboard-control-popover-text-color`	弹出框文本颜色
`dashboard-control-popover-secondary-text-color`	弹出框中的次要文本颜色
`dashboard-control-popover-link-color`	弹出框中的链接颜色
`dashboard-control-popover-divider-color`	分隔线颜色
`dashboard-control-popover-radius`	弹出框边框圆角
`dashboard-control-popover-border-color`	弹出框边框颜色
`dashboard-filter-input-background`	筛选输入框背景
`dashboard-filter-input-radius`	筛选输入框边框圆角
`dashboard-filter-input-border-color`	筛选输入框边框颜色
`dashboard-filter-input-text-color`	筛选输入框文本颜色
`dashboard-filter-input-placeholder-color`	占位符文本颜色
`dashboard-filter-input-icon-color`	筛选输入框中的图标颜色
`dashboard-filter-input-outline-color`	筛选输入框聚焦时的轮廓颜色
`dashboard-filter-input-accent-color`	复选框、单选框和切换按钮的颜色
`dashboard-filter-input-accent-invert-color`	输入框内勾选标记/圆点的颜色
`dashboard-filter-input-token-color`	多选标签的背景颜色
`dashboard-filter-input-token-text-color`	多选标签的文本颜色

按钮：

属性	描述
`dashboard-key-color`	主要操作按钮颜色（更新按钮）
`dashboard-key-text-color`	主要按钮上的文本颜色
`dashboard-button-radius`	按钮边框圆角
`dashboard-button-transparent-text-color`	透明按钮的文本颜色
`dashboard-button-transparent-interactive-color`	透明按钮的悬停颜色
`dashboard-menu-item-interactive-color`	菜单项的悬停背景颜色

Supported CSS Values

支持的CSS值

Hex colors:
```
"#FEF2F2"
```
,
```
"#E60000"
```
Box shadows with rgba:
```
"0 2px 8px rgba(230, 0, 0, 0.1)"
```

Custom fonts via URL:

"url(https://fonts.gstatic.com/...) format('woff2')"

Empty strings to clear defaults:
```
""
```
```
linear-gradient()
```
and
```
rgba()
```
for backgrounds work in Omni's UI theme editor but may fail when passed via the SDK — use solid hex colors for reliability

十六进制颜色：
```
"#FEF2F2"
```
,
```
"#E60000"
```
使用rgba的阴影：
```
"0 2px 8px rgba(230, 0, 0, 0.1)"
```

通过URL引入自定义字体：

"url(https://fonts.gstatic.com/...) format('woff2')"

空字符串用于清除默认值：
```
""
```
```
linear-gradient()
```
和
```
rgba()
```
可在Omni的UI主题编辑器中用于背景，但通过SDK传递时可能失效——建议使用纯色十六进制颜色以确保可靠性

Theming Tips

主题设置技巧

For effective branding, tint backgrounds throughout rather than only coloring buttons:

```
dashboard-background
```
→ light brand tint (like Tailwind's color-50)
```
dashboard-tile-background
```
→ slightly lighter than page background
```
dashboard-tile-title-text-color
```
→ brand primary (titles in brand color)
```
dashboard-control-label-color
```
→ brand primary (labels in brand color)
```
dashboard-tile-border-color
```
→ medium-light brand tint (like color-200)
```
dashboard-key-color
```
→ brand primary
```
dashboard-filter-input-accent-color
```
→ brand primary (checkboxes, toggles)

为实现有效的品牌化，应全面调整背景色调，而非仅设置按钮颜色：

```
dashboard-background
```
→ 浅品牌色调（类似Tailwind的color-50）
```
dashboard-tile-background
```
→ 比页面背景稍浅的颜色
```
dashboard-tile-title-text-color
```
→ 品牌主色（标题使用品牌色）
```
dashboard-control-label-color
```
→ 品牌主色（标签使用品牌色）
```
dashboard-tile-border-color
```
→ 中浅品牌色调（类似color-200）
```
dashboard-key-color
```
→ 品牌主色
```
dashboard-filter-input-accent-color
```
→ 品牌主色（复选框、切换按钮）

Embed Events

嵌入事件

Omni communicates with the parent app via

postMessage

. All Omni events have

source: "omni"

Omni通过

postMessage

与父应用通信。所有Omni事件均包含

source: "omni"

。

Listening for Events

监听事件

javascript

window.addEventListener("message", (event) => {
  if (event.data?.source !== "omni") return;

  switch (event.data.name) {
    case "dashboard:loaded":
      // Dashboard ready
      break;
    case "error":
      // Handle error
      break;
    case "dashboard:tile-drill":
      // Handle drill action
      break;
  }
});

javascript

window.addEventListener("message", (event) => {
  if (event.data?.source !== "omni") return;

  switch (event.data.name) {
    case "dashboard:loaded":
      // Dashboard ready
      break;
    case "error":
      // Handle error
      break;
    case "dashboard:tile-drill":
      // Handle drill action
      break;
  }
});

Event Reference

事件参考

dashboard:loaded
— Fired when the embedded dashboard finishes loading.

json

{ "source": "omni", "name": "dashboard:loaded" }

dashboard:filters
— Fired when filter state changes inside the embedded dashboard.

json

{
  "source": "omni",
  "name": "dashboard:filters",
  "payload": { /* filter state */ }
}

error
— Fired when a detectable error occurs on the embedded page.

json

{
  "source": "omni",
  "name": "error",
  "payload": {
    "href": "https://...",
    "message": "Error description"
  }
}

dashboard:tile-drill
— Fired when a user drills on any dashboard tile (charts, tables, maps). No Omni-side configuration required.

json

{
  "source": "omni",
  "name": "dashboard:tile-drill",
  "payload": {
    "userId": "string",
    "dashboard": {
      "filters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      },
      "href": "string",
      "urlId": "string",
      "path": "string",
      "title": "string"
    },
    "tile": {
      "id": "string",
      "title": "string",
      "appliedFilters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      }
    },
    "drill": {
      "field": "string",
      "fieldLabel": "string",
      "drillQueryLabel": "string",
      "rowToDrill": { "field_name": "value" }
    }
  }
}

Use

drill.rowToDrill

for the data from the drilled row. Use

asJsonUrlSearchParam

from

tile.appliedFilters

dashboard.filters

to sign and embed a different dashboard with those filters applied.

page:changed
— Fired when the URL changes inside the iframe (including after saving a new dashboard).

json

{
  "source": "omni",
  "name": "page:changed",
  "payload": {
    "pathname": "string",
    "type": "string"
  }
}

Custom visualization events — Fired when a user clicks a configured table row or markdown link. Requires setup in Omni: set the table column's Display to Link → Embed event and enter an event name. For markdown, use

<omni-message>

tags.

json

{
  "source": "omni",
  "name": "<your-event-name>",
  "payload": {
    "data": "comma-separated values"
  }
}

Table setup: field dropdown → Display tab → Display as: Link → URL: Embed event → enter event name.

Markdown setup:

html

<omni-message event-name="product-click" event-data="{{products.name.raw}},{{products.retail_price.raw}}">
  Click here
</omni-message>

dashboard:loaded
— 嵌入的仪表板加载完成时触发。

json

{ "source": "omni", "name": "dashboard:loaded" }

dashboard:filters
— 嵌入仪表板内的筛选状态变化时触发。

json

{
  "source": "omni",
  "name": "dashboard:filters",
  "payload": { /* filter state */ }
}

error
— 嵌入页面发生可检测错误时触发。

json

{
  "source": "omni",
  "name": "error",
  "payload": {
    "href": "https://...",
    "message": "Error description"
  }
}

dashboard:tile-drill
— 用户对任意仪表板磁贴（图表、表格、地图）执行钻取操作时触发。无需在Omni端进行配置。

json

{
  "source": "omni",
  "name": "dashboard:tile-drill",
  "payload": {
    "userId": "string",
    "dashboard": {
      "filters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      },
      "href": "string",
      "urlId": "string",
      "path": "string",
      "title": "string"
    },
    "tile": {
      "id": "string",
      "title": "string",
      "appliedFilters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      }
    },
    "drill": {
      "field": "string",
      "fieldLabel": "string",
      "drillQueryLabel": "string",
      "rowToDrill": { "field_name": "value" }
    }
  }
}

使用

drill.rowToDrill

获取钻取行的数据。使用

tile.appliedFilters

或

dashboard.filters

中的

asJsonUrlSearchParam

来签名并嵌入应用了这些筛选条件的其他仪表板。

page:changed
— iframe内的URL发生变化时触发（包括保存新仪表板后）。

json

{
  "source": "omni",
  "name": "page:changed",
  "payload": {
    "pathname": "string",
    "type": "string"
  }
}

自定义可视化事件 — 用户点击配置好的表格行或markdown链接时触发。需要在Omni中进行设置：将表格列的显示方式设置为链接 → 嵌入事件并输入事件名称。对于markdown，使用

<omni-message>

标签。

json

{
  "source": "omni",
  "name": "<your-event-name>",
  "payload": {
    "data": "comma-separated values"
  }
}

表格设置：字段下拉菜单 → 显示标签页 → 显示为：链接 → URL：嵌入事件 → 输入事件名称。

Markdown设置：

html

<omni-message event-name="product-click" event-data="{{products.name.raw}},{{products.retail_price.raw}}">
  Click here
</omni-message>

Sending Events to the Iframe

向iframe发送事件

dashboard:filter-change-by-url-parameter
— Push a filter from the parent app into the embedded dashboard.

javascript

iframe.contentWindow.postMessage({
  source: "omni",
  name: "dashboard:filter-change-by-url-parameter",
  payload: {
    filterUrlParameter: 'f--<filter_id>={"values":["value1","value2"]}'
  }
}, iframeOrigin);

Get the

filterUrlParameter

string by opening the dashboard in Omni, changing filter values, and copying the

f--

parameter from the URL.

dashboard:filter-change-by-url-parameter
— 将父应用的筛选条件推送到嵌入的仪表板中。

javascript

iframe.contentWindow.postMessage({
  source: "omni",
  name: "dashboard:filter-change-by-url-parameter",
  payload: {
    filterUrlParameter: 'f--<filter_id>={"values":["value1","value2"]}'
  }
}, iframeOrigin);

获取

filterUrlParameter

字符串的方法：在Omni中打开仪表板，更改筛选值，然后从URL中复制

f--

参数。

Entity Workspaces

实体工作区

Entity workspaces let embed users create and save their own dashboards within a scoped folder.

typescript

import {
  embedSsoDashboard,
  EmbedSessionMode,
  EmbedEntityFolderContentRoles,
  EmbedUiSettings,
  EmbedConnectionRoles,
} from "@omni-co/embed";

const embedUrl = await embedSsoDashboard({
  // ...standard signing params
  entity: "acme",
  entityFolderContentRole: EmbedEntityFolderContentRoles.EDITOR,
  mode: EmbedSessionMode.Application,
  uiSettings: {
    [EmbedUiSettings.SHOW_NAVIGATION]: false,
  },
  connectionRoles: {
    "connection-uuid": EmbedConnectionRoles.RESTRICTED_QUERIER,
  },
});

Parameter	Description
`entity`	Entity name — scopes the user's folder (e.g., derived from email domain)
`entityFolderContentRole`	`EDITOR` lets users create/edit dashboards in their entity folder
`mode`	Must be `Application` to enable create features
`uiSettings`	Control Omni's built-in UI (e.g., hide Omni's sidebar if you provide your own)
`connectionRoles`	Grant query access: `RESTRICTED_QUERIER` for data exploration

实体工作区允许嵌入用户在限定的文件夹内创建并保存自己的仪表板。

typescript

import {
  embedSsoDashboard,
  EmbedSessionMode,
  EmbedEntityFolderContentRoles,
  EmbedUiSettings,
  EmbedConnectionRoles,
} from "@omni-co/embed";

const embedUrl = await embedSsoDashboard({
  // ...标准签名参数
  entity: "acme",
  entityFolderContentRole: EmbedEntityFolderContentRoles.EDITOR,
  mode: EmbedSessionMode.Application,
  uiSettings: {
    [EmbedUiSettings.SHOW_NAVIGATION]: false,
  },
  connectionRoles: {
    "connection-uuid": EmbedConnectionRoles.RESTRICTED_QUERIER,
  },
});

参数	描述
`entity`	实体名称——限定用户的文件夹范围（例如从邮箱域名派生）
`entityFolderContentRole`	`EDITOR` 允许用户在其实体文件夹内创建/编辑仪表板
`mode`	必须设置为 `Application` 才能启用创建功能
`uiSettings`	控制Omni的内置UI（例如如果您提供了自己的侧边栏，则隐藏Omni的侧边栏）
`connectionRoles`	授予查询权限： `RESTRICTED_QUERIER` 用于数据探索

Embed Users and Permissions

嵌入用户与权限

When building permission-aware experiences (e.g., a sidebar that only shows dashboards a user can access), use these REST API calls. Note: API calls use the

.omniapp.co

domain, not the

.embed-omniapp.co

embed domain.

构建权限感知体验（例如仅显示用户可访问仪表板的侧边栏）时，请使用以下REST API调用。注意：API调用使用

.omniapp.co

域名，而非

.embed-omniapp.co

嵌入域名。

Look Up an Embed User

查询嵌入用户

bash

omni scim embed-users-list --filter 'embedExternalId eq "user@example.com"'

Returns the Omni user ID for the given

externalId

. If no user is found, the user hasn't accessed any embedded dashboards yet.

bash

omni scim embed-users-list --filter 'embedExternalId eq "user@example.com"'

返回给定

externalId

对应的Omni用户ID。如果未找到用户，则表示该用户尚未访问过任何嵌入的仪表板。

List Documents by User Permission

按用户权限列出文档

bash

omni documents list --userid <omniUserId>

Response uses

records

array (not

documents

json

{
  "pageInfo": {
    "hasNextPage": false,
    "nextCursor": null,
    "pageSize": 20,
    "totalRecords": 5
  },
  "records": [
    {
      "identifier": "fb007aa3",
      "name": "Sales Dashboard",
      "hasDashboard": true,
      "folder": {
        "id": "...",
        "name": "Sales",
        "path": "sales/regional"
      }
    }
  ]
}

Use

identifier

as the

contentId

for embed signing. Filter for

hasDashboard: true

to get embeddable dashboards only.

bash

omni documents list --userid <omniUserId>

响应使用

records

数组（而非

documents

）：

json

{
  "pageInfo": {
    "hasNextPage": false,
    "nextCursor": null,
    "pageSize": 20,
    "totalRecords": 5
  },
  "records": [
    {
      "identifier": "fb007aa3",
      "name": "Sales Dashboard",
      "hasDashboard": true,
      "folder": {
        "id": "...",
        "name": "Sales",
        "path": "sales/regional"
      }
    }
  ]
}

使用

identifier

作为嵌入签名的

contentId

。筛选

hasDashboard: true

以仅获取可嵌入的仪表板。

List Folders for Friendly Names

列出文件夹以获取友好名称

Entity folders have technical paths like

omni-system-sso-embed-entity-folder-poc

. Map paths to display names:

bash

omni folders list

Build a

path → name

mapping from the response to display user-friendly folder names.

实体文件夹的技术路径类似

omni-system-sso-embed-entity-folder-poc

。将路径映射为显示名称：

bash

omni folders list

从响应中构建

路径 → 名称

的映射关系，以显示用户友好的文件夹名称。

Domain Mapping

域名映射

The embed domain (

.embed-omniapp.co

) and API domain (

.omniapp.co

) are different:

Embed: yourorg.embed-omniapp.co  →  used for iframe URLs
API:   yourorg.omniapp.co        →  used for REST API calls

When your app stores the embed domain, convert it for API calls by replacing

.embed-omniapp.co

with

.omniapp.co

嵌入域名（

.embed-omniapp.co

）和API域名（

.omniapp.co

）不同：

嵌入域名: yourorg.embed-omniapp.co  →  用于iframe URL
API域名:   yourorg.omniapp.co        →  用于REST API调用

当您的应用存储嵌入域名时，可通过将

.embed-omniapp.co

替换为

.omniapp.co

来转换为API调用域名。

Docs Reference

文档参考

Embed Overview · Custom Themes · Embed Events · AI Chat in Embeds · Embed Users API · Documents API

嵌入概述 · 自定义主题 · 嵌入事件 · 嵌入中的AI聊天 · 嵌入用户API · 文档API

omni-embed

Original

Translation

Omni Embed

Omni 嵌入功能

Prerequisites

前置条件

Verify the Omni CLI is installed — if not, ask the user to install it

Verify the Omni CLI is installed — if not, ask the user to install it

See: https://github.com/exploreomni/cli#readme

See: https://github.com/exploreomni/cli#readme

Show available profiles and select the appropriate one

Show available profiles and select the appropriate one

If multiple profiles exist, ask the user which to use, then switch:

If multiple profiles exist, ask the user which to use, then switch:

Discovering Commands

命令探索

Signing Embed URLs

签名嵌入URL

Parameters

参数说明

Custom Themes

自定义主题

Property Reference

属性参考

Supported CSS Values

支持的CSS值

Theming Tips

主题设置技巧

Embed Events

嵌入事件

Listening for Events

监听事件

Event Reference

事件参考

Sending Events to the Iframe

向iframe发送事件

Entity Workspaces

实体工作区

Embed Users and Permissions

嵌入用户与权限

Look Up an Embed User

查询嵌入用户

List Documents by User Permission

按用户权限列出文档

List Folders for Friendly Names

列出文件夹以获取友好名称

Domain Mapping

域名映射

Docs Reference

文档参考

Related Skills

相关技能