Open Connector
Synchronize a service catalog

Synchronize a service catalog

Read a complete approved inventory snapshot into a local catalog without publishing partial pages or mixing grant revisions.

Build a catalog worker that reads approved Infra or Guard resources and writes one complete local JSON snapshot. The example preserves qualified resource keys and replaces the previous file only after every page succeeds.

Before you begin

You need the following integration and host configuration:

  • A custom integration connection has an active native-to-custom grant for the required inventory or security categories.
  • A service-account key has connections:read and resources:read on that connection.
  • The integration host has Node.js 20 or later and a writable catalog directory.
  • Its secret manager supplies the environment variables in the following table.

Configure these values for the worker process:

VariableValue
CONNECTOR_API_URLAPI origin from Developer settings plus /api/v1/connector
CONNECTOR_ORGANIZATION_IDOwning Solarius organization ID
CONNECTOR_CONNECTION_IDApproved custom connection ID
CONNECTOR_API_KEYBounded worker key from its secret manager
CATALOG_FILELocal output path; defaults to ./catalog.json

Run the first synchronization

  1. Download , a Node.js source file, to the integration host. Open a terminal in the directory containing the file.

  2. On that host, start the worker with its configured environment:

    Shell
    node catalog-pull.mjs

    The output is similar to the following:

    Plain text
    Committed 12 resources to the catalog.

  3. Open the configured catalog file. Confirm its snapshot_id, grant_revision, and source resource keys against Connection → Activity and Resources.

  4. Compare the resource count and project or group IDs with the active selection in Connection → Grants. A complete empty selection produces an empty resources array; a failed read leaves the previous file unchanged.

The script uses List shared resources. It requests 100 records per page, follows opaque cursors, and rejects a changed snapshot, changed grant revision, duplicate resource key, or repeated cursor.

Keep the catalog current

Schedule the command through the integration host's job scheduler. Run one worker per output file. The worker exits with a nonzero status on any read or validation failure, so the scheduler can preserve the prior catalog and report the failure.

For 410 cursor_expired or 409 scope_changed, restart from the first page. For 429, delay the next run by Retry-After. For 401 or 403, correct the key or grant rather than increasing retries. The example performs no automatic retries.

Apply catalog changes downstream

Use resource_key as the catalog key. Update names and summaries in place when the key stays the same. A replacement workload has a different key and needs its own mapping review.

Treat a resource absent from a completed replacement snapshot as no longer visible through that connection. Apply the catalog's own retention policy to its previous copy. Absence does not establish that the source resource was deleted; the grant or your permissions might have narrowed.

To receive changes between full reads, add a signed event receiver. Use events to trigger another read; do not use delivery order as a source revision order.