Skip to main content

How to Export Catalog assets to Collibra

Setup takes about 10 minutes.

Introduction

Connecting Collibra to Foundational allows Foundational to export your catalog assets into your Collibra data catalog: the tables, columns and BI reports in your lineage, with Foundational's AI descriptions, in its own community.

The connection process has three parts:

  • Part 1: Register the integration in Collibra
    ​

  • Part 2: Configure the destination in Foundational
    ​

  • Part 3: Verify the assets

How it works

Foundational connects with an OAuth integration you register. Foundational signs in to your Collibra instance's REST API with the integration's Client ID and Client Secret.

Foundational writes only into its own community. On every export, it creates or updates assets in two domains, inside the Foundational community or the community you name:

  • Foundational Catalog: warehouse tables
    ​

  • Foundational BI Catalog: BI reports

Your own assets stay yours. Foundational never deletes or renames an asset it did not create. The only change it makes to one is to fill an empty Description, and only when Fill missing descriptions is on.

Exports repeat on your Export Interval. Each export brings the assets in line with your current lineage. The connector's card in Foundational shows the time and status of the last export.

What each export writes

Element

Details

New assets

Foundational creates Database, Schema, Table and Column assets in the Foundational Catalog domain for the tables in your lineage that your catalog does not have yet.

BI reports and their fields

Foundational writes them to the Foundational BI Catalog domain, linked to their source tables.
​
They appear on the asset page and in the Diagram view, but not in the Technical Lineage viewer. The Lineage to S3 export does not include BI reports.

Assets that leave your lineage

Foundational keeps them. When a table leaves your lineage, Foundational sets its asset's status to Missing from source and does not delete it.
​
If the table returns, Foundational sets the status back to Candidate.

Renamed dashboards

A renamed dashboard is a new asset. Its old asset becomes Missing from source, and Foundational creates a new one under the new name.

Descriptions

Every description Foundational writes ends with the line Generated by Foundational.

  • If you edit a description Foundational wrote, Foundational leaves it alone from then on, on its own assets and on yours.
    ​

  • With Fill missing descriptions on, Foundational also writes its AI description onto your own tables and columns that have no Description yet, under the same rule. It never changes text you wrote or edited.
    ​

  • If you delete a description Foundational wrote, the next export writes it back. To keep your own version, edit the description instead.

Prerequisites

Ensure you have:

  • A Collibra user with System administration rights, to register the integration.

  • Your Collibra instance URL, for example https://acme.collibra.com.
    ​

  • (Optional) The Lineage to S3 destination's OpenLineage capability set up in Collibra Edge. See the article How to Export Lineage to Collibra. This destination reads it. See How Databases join a System.
    ​

  • Added Foundational IP addresses to the allowlist. See the article Allowing IP access to Foundational.

Access permissions

The integration signs in as its own system user and has access to your catalog. You don't need to pick scopes, assign roles, or change your operating model or asset layouts.

Foundational uses that access to:

  • Create and update assets, and their relations and attributes, in its own community and domains.
    ​

  • Read your catalog, to find the tables, columns, Systems and BI reports you already have, so it does not create duplicates.
    ​

  • Fill an empty Description on your own tables and columns, when Fill missing descriptions is on.
    ​

  • Read your Edge capabilities, to find the Systems your OpenLineage capability files your lineage under. Foundational never changes a capability.

Store the Client Secret like an administrator credential. To rotate it, see Keep the secret safe.

Part 1: Register the integration in Collibra

  1. In Collibra, go to Settings > OAuth applications, or open https://<your-instance>.collibra.com/settings/oauth-applications/manage-oauth. For details, see the Collibra article OAuth Applications settings page.
    ​

  2. Click + New Application.
    ​

  3. Under Integration, click Register integration. Do not choose Platform, which is for Collibra components such as Edge, or User Application.
    ​

  4. Enter an Application name, for example Foundational, and click Register.
    ​

  5. In Registration Confirmation, copy the Client ID and the Client Secret with the copy buttons next to each.

    Warning: Collibra shows the Client Secret only once. If you lose it, register a new integration.

  6. Click Close.

Save the Client ID and Client Secret. You'll need them to connect Foundational to Collibra.

Part 2: Configure the destination in Foundational

  1. In Foundational, open the Integrations page.
    ​

  2. In Catalogs, select the Collibra card.

  3. Click Add Destination.
    ​

  4. In Choose an export destination, on the Catalog assets card, click Set up.
    ​


    The wizard has three steps: Connect Foundational to your Collibra catalog, Connected, and What Foundational writes to Collibra.
    ​

  5. The Set Up New Connection screen opens.
    ​

    ​
    In Connect Foundational to your Collibra catalog, enter the details:
    ​

    • Collibra URL: Your instance's address, https:// and the host only, with no path. For example, https://acme.collibra.com.
      ​

    • Client ID: The Client ID from Collibra's Registration Confirmation.
      ​

    • Client Secret (Write-only): The Client Secret from the same screen. When you edit the destination later, leave it blank to keep the stored secret.
      ​

    • Collibra community (optional): Where Foundational creates its domains. Leave it empty to use a community named Foundational.
      ​

    • Fill missing descriptions (optional): On by default. Also writes Foundational's AI description onto your own tables and columns that have no Description yet. See Descriptions.
      ​

    • Export Interval (days): How often Foundational re-exports. Minimum and default is 14.
      ​

  6. Click Next.
    ​

  7. The Connected step opens. To complete the connection, click Next then Save.
    ​


    - Before it stores the configuration, Foundational signs in with the credentials and runs a test import that Collibra validates and discards, so Foundational writes nothing. If the check fails, the error appears in the form. Correct the field and save again.
    ​
    - Foundational starts the first export. The card shows its time and status once it finishes.
    ​

  8. After you save, the wizard opens What Foundational writes to Collibra. Click Done to leave the wizard.
    ​

Part 3: Verify the assets

  1. In Collibra, open Catalog > Communities > Foundational, or the community you entered.
    ​

  2. Open the Foundational Catalog domain and its Tables. Each table shows Foundational's AI description under Description.
    ​

  3. To see BI reports and their fields, open the Foundational BI Catalog domain. They link to their source tables on the asset page and in the Diagram view.
    ​

  4. If you also use Lineage to S3, open one of these tables and select the Technical Lineage tab. The table opens its own node in the lineage graph. If it does not, see How Databases join a System.

Foundational is now connected to Collibra.

How Databases join a System

Collibra's lineage harvester links technical lineage to a catalog asset only when their full paths match: System › database › schema › table. So every Database Foundational creates joins a System:

  • The System your OpenLineage capability maps its namespace to. The Lineage to S3 destination's setup gives the Technical Lineage for OpenLineage (Cloud) capability a Source configuration. It maps each OpenLineage namespace Foundational exports to a System (collibraSystemName). You may rename any of those Systems there. On every export, Foundational reads that mapping from the capability that harvests the Lineage to S3 bucket and prefix, so the Databases it creates follow your changes.
    ​

  • Otherwise, Collibra's default System name for the namespace: The namespace with every / replaced by _. For example, snowflake://BANK_DW becomes snowflake:__BANK_DW. The harvester itself files an unmapped namespace under this name. Foundational uses it for every namespace when you don't use Lineage to S3, and for a namespace the capability does not map.

If exactly one System with that name already exists in your catalog, the Database joins it. Otherwise, Foundational creates a System with exactly that name in the Foundational Catalog domain.

For Foundational to read the mapping, the integration must be able to read Edge capabilities. If it cannot, Foundational uses the default System names, and the destination's card says why.

Keep the secret safe

The Client Secret signs in as the integration's own system user, with access to your catalog.
​

To rotate it:

  1. Register a new integration (Part 1).
    ​

  2. Save its Client ID and Client Secret on the Catalog assets destination in Foundational.
    ​

  3. Only then delete the old integration in Collibra. Go to Settings > OAuth applications and click ⋮ > Delete.

Deleting an integration invalidates its credentials. Access tokens Collibra already issued to it expire within five minutes. Foundational then no longer refreshes the descriptions that the old integration filled on your own assets.

To manage integrations through the API, see the Collibra reference OAuth client management API.

Validation and troubleshooting

Review the following issues if the connection fails or an export doesn't behave as expected.

Saving fails with "Could not authenticate with …"

Cause / fix

The Collibra URL, Client ID or Client Secret is wrong. Check that the URL is your instance's address with no path, and that both values come from the same integration's Registration Confirmation.

Saving fails with "Authenticated with …, but the integration is not allowed to import assets"

Cause / fix

The credentials work, but Collibra refused the test import. Check that you registered an Integration (not a Platform or User Application), and check the community name.

The card says "Collibra Systems use default names: …"

Cause / fix

Foundational could not use your OpenLineage capability's System mapping. The message says why: no capability harvests the Lineage to S3 bucket and prefix, the integration may not read Edge capabilities, or the capability's Source configuration is not readable. Fix the cause. The next export uses the mapping.

The export fails with "Could not read Collibra's Edge capabilities …"

Cause / fix

Foundational could not use your OpenLineage capability's System mapping. The message says why: no capability harvests the Lineage to S3 bucket and prefix, the integration may not read Edge capabilities, or the capability's Source configuration is not readable. Fix the cause. The next export uses the mapping.

A table Foundational created does not open its node in the Technical Lineage tab

Cause / fix

The table's Database and its lineage sit under different Systems. Check that its namespace is in the capability's Source configuration. Also check that no two capabilities that harvest the same bucket and prefix map it to different Systems. If they do, Foundational uses the default System name for it.

Foundational's descriptions stopped updating on some assets

Cause / fix

Someone edited them in Collibra, and Foundational leaves an edited description alone. To get Foundational's description back, delete the edited one. The next export writes Foundational's again (on your own assets, only while Fill missing descriptions is on).

Useful links

Related Articles
Did this answer your question?