Skip to main content
Skip to content

Build a connector with Owlie

In the Connector Builder you can ask Owlie to build or fix an HTTP connector for you. Owlie reads the vendor's official documentation, proposes what the connector will do, edits your draft, and checks it. You approve the plan, run any live tests yourself, and publish. You do not need to write code, but you do need to know the system well enough to judge what Owlie proposes.

Owlie never sees your credentials and cannot publish, install or delete a connector.

Before you start​

  • The connector must be an HTTP connector, and you must be on its draft. Owlie edits only the draft of an HTTP connector. A published version opens read-only, and for the other kinds the chat is the general Owlie assistant: it does not edit the draft.
  • You need the custom_connector.modify permission, which the owner, admin and operator roles have by default. If you lose it while Owlie is working, the build pauses and Owlie says so. It resumes from where it stopped once you have the permission back.
  • Have a test account in the vendor's system. Owlie builds from the documentation and can be wrong about behavior the documentation leaves out, so run the reads it offers to test on a sandbox or test tenant.

Ask Owlie​

  1. Open Admin > Integrations > Connectors, then the Custom tab, and open the connector's draft. To start from nothing, select New connector and choose Blank and the HTTP kind.
  2. Open the Owlie chat and describe what you want. For example: "Build this connector for Acme Projects. Sync users and teams, and let Owlie add and remove team membership." For a repair, name the one thing to fix: "Read handlers for user stop after the first page."

Each connector has its own conversation. Opening the builder switches the chat to it, and leaving the builder returns you to the conversation you were in. For a repair, Owlie changes only what you name and does not restart the research or propose the plan again.

What Owlie does​

It researches the vendor's documentation. Owlie works from the vendor's official documentation and the pages you give it. If it needs documentation and has no address, the chat shows Owlie wants to read the vendor's documentation at an address such as docs.acme.example/api, with Allow and Don't allow. Allow lets Owlie read that address and the pages beneath it, for this connector only, over HTTPS and without any credentials. You can also paste documentation into the chat, or the address of a page, and Owlie reads that. Owlie does not search the web by itself.

It proposes a brief. Before it writes anything, Owlie shows Review the connector brief: what the connector will do, what will sync, the access Owlie can manage (each Grant kind is marked Owlie can grant and revoke or Read-only), how Owlie signs in, whether each entity can be read incrementally (Changes only or Full re-read), what is not managed, the assumptions to confirm (marked Unverified), and the sources it used. Select Accept to go ahead. Select Discuss to say what should change, with an optional note, and Owlie proposes again.

It edits your draft. Owlie changes the manifest and the files in the builder you have open, in coherent batches, and the builder autosaves them as it does your own edits. You see the selection move to what Owlie is working on. If you edit the draft while Owlie is working, Owlie's change is refused as out of date, and it reads the draft again before trying. Owlie can undo its most recent batch if nothing has changed since.

It checks the draft. After each batch Owlie validates and compiles the exact current content, unsaved edits included. This check uses no credentials and no network, and it does not save or publish anything. Owlie fixes what it reports and looks up each issue code in Validation issues.

It offers tests you run yourself. At useful points, such as after the connection test or the first list handler, Owlie can set up the Test tab for you: it opens the handler with an input filled in and tells you what the run may do. Nothing runs until you review the hosts the run may contact and select Run (Test your connector). Choose Continue without testing to skip it. You can also tell Owlie to stop offering tests, and it builds without them.

It hands over. Owlie writes the connector's README.md and CHANGELOG.md, and tells you what is finished and what is unproven. Publishing is yours (Publish, install and upgrade).

Long builds run in several turns. When a turn stops before Owlie is done and the draft changed during it, Owlie continues by itself. Otherwise the chat offers Continue.

Credentials​

Owlie never sees credential values. It can see which Run config fields exist and whether they are filled in, and nothing else about them. Enter credentials in Run config in the Test tab, never in the chat. If you paste a secret into the chat anyway, rotate it: it is now part of the conversation.

A test also does not give Owlie your data. After a run you started, Owlie sees the status, how long it took, the error text with credentials removed, the hosts the run tried to reach, the shape of the data (its type, how many records and their top-level field names), and the identifiers of up to three records. It does not see the records themselves or the run's log lines. You see the full result, with credentials removed, in the Test tab.

One tab controls Owlie's edits​

Only one browser tab carries out Owlie's edits at a time. If you open the builder in a second tab, that tab shows Owlie is working in another tab. with Take control, and Owlie's edits then appear in the tab you took control in. Two more messages can appear in the chat:

  • Owlie is building <name> in another tab. with Switch here, when the conversation is bound to a different connector than the one this tab shows.
  • Owlie is not building this connector in this conversation. with Build here, when the chat is on a general conversation while you are on an HTTP draft.

Opening or reconnecting a tab never changes any of this by itself; only these buttons do.

What "untested" means​

Owlie's checks and your live tests answer different questions.

  • Checked means the draft validates and compiles, and Owlie compared the design with the vendor's documentation. The connector is well formed. It does not mean the vendor's system answers the way the connector expects.
  • Tested means a run you started on the current draft succeeded and Owlie compared its result with the design.
  • Untested is everything else: never run, run and failed, skipped, unclear (the request may have been sent and no answer came back), or run before the draft last changed. A change to the draft makes earlier results stale, and Owlie does not count a stale result as evidence for the new content.

Owlie does not call something tested without a recorded result, and it reports a failed or skipped run as failed or skipped. A missing live test does not stop you from publishing. A failing check does, and Publish stays disabled until the draft has no problems. Read the handover, and run the reads and the writes it lists as unproven on a test account before you publish. A write handler changes the real system its credentials belong to.

What Owlie does not do​

  • Owlie does not run a test on its own. Every live run is your click, on the exact operation, input and hosts you saw.
  • Owlie does not build LDAP, SCIM, SQL or flat-file connectors.
  • Owlie does not publish, install or delete a connector.

Next: Test your connector