Omni

Catalog offers a native Omni connector in beta to bring workbook, dashboard, and query metadata into your Workspace. Coverage and how Omni objects map into Catalog may change. Onboarding is coordinated with Coalesce Support.

Requirements

Warehouse Integration Required

A warehouse integration must already be configured in Catalog before the first Omni ingestion completes.

Before you contact support, confirm:

• You have access to an Omni organization API key, or ask your Omni admin to create one. See Omni API authentication for how Omni issues API keys.
• You know your Omni instance base URL: the hostname you use to sign in, for example https://yourorg.omniapp.co.
• If Omni sits behind a firewall and Catalog runs extraction for you, your network team can allow outbound HTTPS from Catalog infrastructure to that host. See Allowlist Catalog IP for fixed egress IPs.

How Omni Objects Appear in Catalog

Catalog ingests three Omni asset types. Each maps to a Catalog asset type as follows:

Omni object	Catalog asset type
Workbook	Viz model
Query	Tile
Dashboard	Dashboard

Workbook and dashboard names in Catalog match the Omni document name. Query names come from Omni as well.

Supported Today

The following capabilities are available.

Metadata

Capability	Workbook	Query	Dashboard
Asset name	Yes, same as Omni document	Yes	Yes, same as Omni document
External description	No	Yes, for published queries	No
Tags from Omni	Yes, inherited from document	No	Yes
Link back to Omni	Yes, opens the workbook through the query URL	Yes	Yes
Editors	Yes, document owner	Yes, document owner	Yes, document owner
Field descriptions	Yes	Not applicable	Not applicable

Lineage

Catalog builds asset-level lineage, not column-level lineage, when your warehouse integration and Omni metadata allow it:

Relationship	Supported
Warehouse table, workbook, and query	Yes
Workbook, query, and dashboard	Yes
Warehouse table, query, and dashboard	Yes
Query and dashboard	Yes
Column- or field-level lineage	No

Behind the Scenes

Catalog also extracts Omni connections, view definitions from model YAML, and users to support lineage and ownership. Coalesce Support configures these paths during onboarding.

Not Supported Today

The following are not available for Omni in Catalog today:

• Popularity metrics such as view counts
• Frequent users
• External descriptions on workbooks or dashboards
• Tags on queries
• Column- or field-level lineage
• Chrome extension metadata for Omni assets
• Sync back to Omni

Folder paths from Omni are not surfaced in Catalog today. Browse assets by type after onboarding.

Get Started

Email Coalesce Support and ask to connect Omni to Catalog. Include your Catalog Workspace name, Omni base URL, and whether you prefer Catalog-managed extraction or a client-managed upload path.

Coalesce Support will confirm prerequisites, validate that the connector fits your Omni usage, enable the integration on your Workspace, and walk you through credentials and timing for the first sync. Allow up to 48 hours for the initial ingestion after configuration is complete.

Allowlist Catalog IP

When Omni sits behind a firewall and Catalog runs extraction for you, allow outbound HTTPS from Catalog infrastructure to your Omni host.

Catalog uses these fixed egress IPs:

• For instances on app.us.castordoc.com: 34.42.92.72
• For instances on app.castordoc.com: 35.246.176.138

Share your Catalog region and Omni base URL with Support so the allowlist matches your deployment.

Catalog Managed

Coalesce Support configures Catalog-managed sync for your Workspace. Support enables the integration and applies credentials on your behalf.

When your Workspace is enabled, provide:

• Base URL - Your Omni instance root URL, the hostname you use to sign in.
• Token - Bearer token from an Omni organization API key.

Example credential shape:

{
    "base_url": "https://yourorg.omniapp.co",
    "token": "*****"
}

Field names may vary. Use the names Support confirms for your Workspace.

Catalog calls Omni's /api/v1/... endpoints under that host. Do not add /api to the base URL unless that matches how you reach your deployment.

If you are not comfortable sharing credentials with Catalog operations, ask Support about Client Managed instead.

Client Managed

Use this path when your organization runs extraction and upload on your own schedule. Coalesce Support provides your Catalog source_id and upload token during onboarding.

Doing a One-Shot Extract

For a trial, you can supply a one-time extract of your Omni BI assets. To run the package quickly, use this Google Colab notebook.

Running the Extraction Package

Install the PyPI Package

Install the Omni extractor from PyPI:

pip install castor-extractor[omni]

For further details, see the castor-extractor installation instructions.

Run the Package

After installation, run:

castor-extract-omni [arguments]

Example:

castor-extract-omni -u "https://yourorg.omniapp.co" -t "*****" -o "/output/directory"

Credentials

Pass your Omni host and API token with these flags:

• -u, --base-url: Omni instance root URL, the hostname you use to sign in.
• -t, --token: Bearer API token from an Omni organization API key.

Other Arguments

Set the output location with:

• -o, --output: Target folder for extracted JSON files.

Run castor-extract-omni --help to list all arguments.

Scheduling and Push to Catalog

When you move out of trial, schedule extraction and upload so Omni content stays current in Catalog. You need:

• Your source_id from Catalog.
• Your Catalog token from the Catalog team.

Use the castor-upload command:

castor-upload [arguments]

Arguments

castor-upload accepts these flags:

• -k, --token: Token provided by Catalog.
• -s, --source_id: Source id provided by Catalog.
• -t, --file_type: Source type to upload. Use VIZ for Omni visualization extracts.

Target Files

Provide exactly one of the following:

• -f, --file_path: Push a single file.
• -d, --directory_path: Push every file in a directory.

Directory Contents

The tool uploads all files in the given directory. Confirm the directory contains only Omni extract outputs before you push.

Schedule the extractor run and upload on your preferred scheduler.

API Limits and Scope

API Access

Catalog only ingests objects and fields your API token can read. Restricted workbooks or documents stay out of sync until Omni grants the integration account access.

Rate Limits

Omni enforces per-key API rate limits. Omni documents a limit of 60 requests per minute per API key. Heavy workspaces can return 429 Too Many Requests during sync. Retry after the limit window or reduce parallel activity against the same key.

For Omni API reference material, see Omni REST APIs and Omni API authentication.

Troubleshooting

First Ingestion Fails with No Warehouse

See Requirements for the warehouse prerequisite. Catalog needs that integration before the first Omni ingestion can complete.

Resolution:

1. Connect the warehouse Omni queries use, such as Snowflake, BigQuery, or Databricks.
2. Contact Coalesce Support to re-run or wait for the scheduled Omni sync after the warehouse integration succeeds.

Authentication or Connection Errors

Incorrect base URL format or an expired token stops extraction before metadata collection.

Resolution:

1. Use the sign-in hostname only, for example https://yourorg.omniapp.co, without appending /api/v1 unless your deployment requires it.
2. Create a fresh organization API key in Omni and share the updated token with Support or update your extractor -t value.
3. For Catalog-managed sync behind a firewall, allowlist the IPs in Allowlist Catalog IP.

429 Too Many Requests

Omni returned a rate-limit response while Catalog or your extractor called the API.

Resolution:

1. Wait for the limit window to reset, then retry the sync.
2. Avoid running multiple large Omni extractions against the same API key at the same time.
3. For very large workspaces, prefer off-peak schedules for client-managed runs.

Workbooks Appear as Viz Models

Omni workbook documents are stored in Catalog as viz models so you can document semantic workbook content separately from dashboard presentations.

Resolution:

1. Open the asset from search or lineage and confirm the Omni link opens the expected workbook in Omni.
2. Use dashboard assets for document presentations flagged as dashboards in Omni.

Lineage Stops at Omni Without Warehouse Tables

View SQL lineage requires a matching warehouse integration and SQL that Catalog can parse in synced workbook views.

Resolution:

1. Confirm the warehouse that powers the Omni connection is integrated in Catalog.
2. Open the viz model or tile in Catalog and verify view SQL synced from Omni.
3. Contact Coalesce Support to re-sync after you add or fix the warehouse integration.

What's Next?

• Browse related BI setup on BI Tools.
• Install optional extractor extras in Castor Extractor.
• Review warehouse prerequisites on Data Warehouses.

---