Skip to main content
Skip to content

Publish, install and upgrade

Building a connector, step 9 of 10. Previous: Test your connector, or Upload files and run ingestion for a flat-file connector.

Publishing turns your draft into a numbered, immutable version. Installing a version creates an integration: the connector connected to one system with its own configuration and credentials, which Sync and provisioning then use. Each integration keeps the version it installed until someone upgrades it, so publishing a new version never changes a running integration by itself.

Publishing needs the custom_connector.publish permission, which the owner and admin roles have by default. Installing needs both custom_connector.install and integration.modify (the owner and admin roles have both), and upgrading an integration needs integration.modify.

Publish​

In the Connector Builder​

  1. Select Publish in the top bar. The button is disabled, with a tooltip saying why, while the draft has problems.
  2. The Publish v<N>? dialog lists any requirements the draft does not meet yet, and shows what changes: Initial contents for a first version, or Diff vs. v<N>, with each file marked Added, Removed or Modified and manifest changes under Manifest.
  3. Under Hosts, the dialog lists the hosts the saved draft declares: the domains in its egress and the hosts of literal URLs in its authentication. Compared with the latest published version, each new host is marked and listed as Added, each dropped one as Removed, and an unchanged list says No host changes since v<N>. An added host is one more place the connector can send requests, so check it before you publish.
  4. Select Publish v<N>. Owlie validates the manifest and your files together and packages the version.

Published runs may contact the listed hosts and their subdomains: after publishing, acmeprojects.example covers acme.acmeprojects.example, although a test run in the builder reaches only the exact hosts it lists (Test your connector). Installs can add hosts of their own through egress_domains in the install configuration, and those are not in the dialog. Nor is a host built from configuration by an expression: declare its parent domain in egress so installs can reach it.

When it finishes, Published v<N> confirms it, and Owlie creates a fresh draft from the published content so you can keep working. If publishing fails, the dialog lists each problem and links to where to fix it; Validation issues explains every code.

Through the API​

mutation {
  publishCustomConnectorVersion(versionId: "<draft version id>", connectorId: "<connector id>", expectedRevision: 12) {
    published {
      id
      version_number
    }
    new_draft {
      id
      draft_revision
    }
  }
}

expectedRevision is the draft's draft_revision as you last read it. If the draft changed since, the call fails with CUSTOM_CONNECTOR_REVISION_CONFLICT and publishes nothing: read the draft again and retry.

Install​

In the Connector Builder​

  1. Open Admin > Integrations > Connectors and the Custom tab.
  2. Open the connector's row menu and select Install.
  3. In Install <connector name>, choose the Version (the picker appears once more than one version is published; the newest is selected), choose the gateway if the connector runs on one, and select Install.

Inside the editor, a published version you are viewing has its own Install button in the top bar. It opens Install Integration and installs that version.

Then connect the integration: enter its configuration and credentials, run its connection test, and set up Sync, as for any integration. LDAP and SQL integrations also need a private-network gateway assigned, and its operator must have approved the connector.

Through the API​

mutation {
  installIntegration(
    input: {
      catalog_source: custom
      catalog_key: "<connector id>"
      catalog_version: 1
      gateway_id: "<gateway id, for LDAP and SQL>"
    }
  ) {
    id
  }
}

Leave out catalog_version to install the latest published version.

Upgrade an integration​

When a newer version exists, the integration's page shows Upgrade available: v<N> for the newest published version. Select Review to see, before anything changes, how the upgrade affects the integration's entity schemas, its resources and its sync jobs. Upgrade to v<N> applies it.

Through the API, call reconcileIntegrationManifest, first with dry_run: true to see the effect, then without it to apply:

mutation {
  reconcileIntegrationManifest(
    input: { integration_id: "<integration id>", target_catalog_version: 3, dry_run: true }
  ) {
    catalog_version_before
    catalog_version_after
    entity_schemas_replaced
    sync_jobs_created
    sync_jobs_updated
    sync_jobs_unscheduled
    grant_kinds_installed
    grant_kinds_retired
    grant_kinds_updated
  }
}

The review and the dry run do not check the Grants the integration already holds. The upgrade itself is refused, and changes nothing, when a Grant kind the integration holds Grants of would change in a way those Grants cannot survive:

  • its membership or hierarchy flag, a narrowed principal or target entity type of a membership or hierarchy kind, or its membership_context, while Sync has recorded Grants of that kind;
  • its qualifiers, while Owlie intends Grants of that kind (from policies or approved requests).

Upgrades are one integration at a time and always explicit. To go back to an earlier version, call reconcileIntegrationManifest with that version as target_catalog_version; the integration's page offers only the newest version.

Engine-based connectors keep improving​

For LDAP, SCIM, SQL and flat-file connectors, your content (the definition, scripts and overrides) is fixed in each published version, but the engine underneath is Owlie's. When Owlie improves an engine, your published versions are rebuilt with the new engine on their next run, with your content unchanged. If a rebuild would change what your connector declares, or fails, the version keeps running as it was published and your admins are alerted.

Next: Maintain it