Maintain your connector

Building a connector, step 10 of 10. Previous: Publish, install and upgrade.

A connector keeps changing after its first version: the vendor's API moves, you model more access, you fix what a real tenant revealed. This page covers changing a published connector safely, keeping its source in your own version control, and working from a fork of one of Owlie's connectors.

Change it through new versions

Edit the draft, test it, and publish. Every publish is a new immutable version; integrations keep theirs until they are upgraded. Before an upgrade, the review shows its effect on that integration's entity schemas, resources and sync jobs (Upgrade an integration).

Some changes are safe for every integration that upgrades. Others change what existing data means:

Safe to publish	Needs care before integrations upgrade
A new entity, Grant kind, custom operation or optional property	Removing or renaming an entity, a Grant kind, a qualifier or a custom operation
Making a read-only Grant kind writable, once its add and remove are tested	Changing an entity's identifiers or their order
New titles, descriptions and examples	Changing a qualifier's meaning, or whether it is a slot key
Handler fixes that keep the same behavior	Changing a Grant kind's principal types, target or inheritance flags
A new authentication option	Removing an authentication option, or changing its credential fields

Never change what a published name means. A qualifier whose meaning changes gets a new name, and a Grant kind whose endpoints change becomes a new Grant kind. When an integration holds Grants that depend on the old meaning, Owlie refuses some of these changes at upgrade time: the upgrade fails and changes nothing. The review does not predict this, so check the cases in Upgrade an integration before you publish such a change.

Record every change that reaches integrations in CHANGELOG.md, newest dated entry first. For a new scope or permission, say what admins must grant and that OAuth connections need to reconnect to consent to it. Admins read this file under Updates when they install the connector, and connectors forked from yours show it under Updates to <base>….

Keep the source in your own version control

A connector's files are the connector. Export a version or the draft, commit the pack to your repository, and import it back after you edit it:

• In the Connector Builder, the export and import menu in the top bar exports what you are viewing: Export the draft, or Export version <N> while you view that published version. On the draft it also has Import a connector export…, which replaces the draft with a pack. New connector, then A connector export, creates a new connector from a pack.
• Through the API, customConnectorExport returns the pack document and its digest, and customConnectorImport validates a pack and writes it as a new connector or over a draft. Use "dry_run": true to validate without writing.

An import that would overwrite a draft someone changed since you read it is refused. Importing unchanged content changes nothing. The pack format is in Pack format.

Start from one of Owlie's connectors

Owlie connectors can be opened read-only: on the Owlie tab of Admin > Integrations > Connectors, choose View source from a connector's menu (this needs the integration.read permission). To build on one, choose Fork. A fork is your connector, stacked on Owlie's: you change or add files, and every file you did not touch follows Owlie's later updates to that version. A connector that connects only through Owlie's own app registration cannot be forked, because a copy could never sign in; its Fork action says so, and you install the Owlie connector instead. You can also fork a published version of one of your own connectors with Copy and customize.

A fork's status is shown in the builder. The base is the connector the fork is stacked on:

Status	Means
Up to date with base	The base has not changed.
Base updated — rebuilds on next run	The base changed; your published fork is built on it the next time it runs.
Following base v<N> since <date>	Your published fork runs on the base's current content.
Base update conflicts with this version — <n> conflicts	The base changed files or values your fork also changed. Your published fork already runs on the new base, keeping your copy of each of those paths. Resolve each conflict in the draft (keep yours or take the base's) and publish to settle them.
Base update failed to build — the published version keeps running	Building your fork on the new base failed. The published version keeps running as it was, and your admins are alerted.

From the fork's menu, Updates to <base>… shows the base's changelog, Update base to v<N>… moves your draft onto a newer version of the base (anything both of you changed becomes a conflict to resolve before publishing), and Detach from base… turns the draft into an ordinary draft that stops following the base for good. Detaching is refused while conflicts are open, and versions you already published keep following the base. Through the API, the same actions are createCustomConnectorFork, resolveCustomConnectorForkConflicts, rebaseCustomConnectorFork and flattenCustomConnectorFork.

To copy a connector without following it, use Duplicate (duplicateCustomConnector): the copy is independent from the start.

Values each integration can change

In LDAP, SCIM, SQL and flat-file connectors, some values are install-editable: each integration gets its own copy, seeded from your definition, and its admins edit it in place (search bases, field lists, file columns). Publishing a version that changes a seed changes no integration. When an integration upgrades to that version, it keeps its own value and shows a per-field notice: Use Owlie's value takes the new seed, Keep mine keeps the integration's value. A value the new version no longer declares is dropped. New integrations start from the new value. Your track's pages explain which values can be install-editable.

Deleting a connector

Deleting removes the connector and all its versions, and needs custom_connector.modify. Owlie refuses it while:

• the connector is installed in any integration (uninstall it everywhere first);
• other connectors are forks of it (delete the forks that have published versions, and flatten or delete the ones that have only a draft).

Through the API, deleteCustomConnector answers success: false with the reason, not an error, when it refuses. A deleted connector's key is never available again.

Owlie limits how many custom connectors an organization can have; Plan & Usage shows your limit as Custom connectors.