Reviewing and editing connectors

A connector is code a Coworker writes, together with its Supervisor, to reach one of your organization's own systems, such as a database or an internal API. Connectors belong to the whole company: every Coworker can find them, and a Coworker can use one only after its Supervisor enables it. See Connecting a Coworker to one of your systems and Connectors for a Coworker.

Connector code runs against your real systems with the credentials you give it, so review a connector before you enable it on more Coworkers.

Opening the Connectors page#

Open Settings and select Connectors under Your account. The item is shown to administrators and to anyone who supervises at least one Coworker, because they can enable connectors on their own Coworkers.

The page lists your SharePoint connections first, then the outside systems an administrator has connected (such as GitHub), then the connectors Coworkers have built. Administrators manage the SharePoint connection here; see Connecting SharePoint. Supervisors who are not administrators see each SharePoint connection by name and the Knowledge Bases that use it. Administrators also see Add a connection at the top of the page. Its list holds the outside systems and SharePoint (tagged For Knowledge Bases); choosing SharePoint opens the SharePoint form instead of the outside-system form; that form shows the Redirect URI to enter when you register the Microsoft Entra application. See Connecting outside systems like GitHub. The rest of this page describes the connectors Coworkers have built.

When there are no other connectors, the page reads "No other connectors." For an administrator it continues "Add a connection to an outside system, or have a Coworker build one with its Supervisor in conversation." For everyone else it continues "A Coworker can build one with its Supervisor in conversation."

What each connector shows#

Each connector has a card with:

• its name, a Built for your organization label, and a Read or Write label. Read means the connector only looks things up and never changes anything in another system; Write means it can create, update, delete or send. The Coworker that builds a connector declares which it is when it registers the connector, and a connector without a declaration counts as Write. The declaration stands as given, so check it here: a Read connector is never reviewed;
• its slug, the name Coworkers call it by in scripts (wi.custom. followed by the slug);
• its description;
• Built by the Coworker that built it, with the person in that conversation, and the date;
• Enabled on: each Coworker it is enabled for, linked to that Coworker's details page, with who enabled it and when. "No Coworkers." means it is not enabled anywhere. This list is shown while Coworkers is on in Features.

Select View details to review the rest, and Hide details to collapse it:

• Guidance: the usage notes every Coworker reads before using the connector, rendered as formatted text. They describe the real tables or endpoints, value formats, example requests and safety rules.
• Secrets it uses: the secret names the connector reads. A connector stores names only; values live in Secrets and are supplied for each Coworker when the connector is enabled.
• Dependencies: the Python packages the connector installs when it runs, for example psycopg[binary]>=3.1. Each one is a package name with optional extras and version constraints; links, file paths and archives are refused.
• Source: the connector's full code.

Read or Write, and what happens on use#

Administrators see When a coworker uses it under View details on every connector, with two controls that save as soon as you change them:

• Allow, Review, Ask or Block. Allow runs it without asking. Review lets it run unless the automatic check finds the action risky, in which case the person is asked and the request shows the reason. Ask asks every time. Block refuses. A connector that changes things starts on Review; one that only reads starts on Allow. A Read connector built for your organization, or a function of a connected outside service that the service's own catalogue lists as a read, runs without a check when set to Review. A function that syncs from a connected system is always checked on Review, even if the system calls it read-only.
• Changes things in other systems: tick it for a Write connector, clear it for a Read one. Only an administrator can mark a connector as read-only, including the person who built it. The person who built it, or a Coworker that maintains it, can move it toward Write, and doing so moves Allow to Review; a request to mark a connector read-only is refused and the Coworker tells the person to ask an administrator. When a connector's source code changes, it becomes Write again and Allow moves to Review, until an administrator marks it read-only again.

Both changes are recorded in the audit log, with the old and new value. People can still make the setting stricter for themselves under Connecting your accounts, never looser.

Review appears as a choice only while Review risky writes is turned on in Features, and it needs a small model; see Default models. If you turn the setting off, Review is no longer offered, anything already set to Review shows as Ask and asks for approval (the saved setting is kept, so it works as Review again when you turn the setting back on), and a new write function starts on Ask instead of Review. If the check cannot be completed, a function on Review asks for approval instead. When a run has nobody to ask, such as a trigger or a workflow, an Ask or Review that needs approval is refused.

Built-in Coworker actions#

Sharing a file, publishing an artifact, saving or updating a Coworker's own memories and editing a document are the Coworker's own work for the person who asked, so they always run without a prompt and are never reviewed. Three consequential actions can be controlled for the whole company. At the bottom of the Connectors page, Coworker actions lists each with the same Allow, Review, Ask and Block choices as a connector, and a change saves as soon as you make it:

• Create a trigger (the Coworker starts runs on its own later), Register a custom connector and Update a custom connector (code that later runs with the company's secrets).
• Every action starts on Allow. Choosing Allow again returns an action to its standard setting.
• Ask and Review work as they do for connectors: the Coworker's work stops at that action, the person who asked is shown an approval card in the chat, and the work picks up where it left off once they approve. Actions earlier in the same piece of work are not repeated. Block refuses the action. When a run has nobody to ask, such as a trigger or a workflow, an Ask or Review that needs approval is refused.
• Asking for a secret, a connection or to enable a connector is not listed: each already waits for the person to answer.
• People cannot choose "Don't ask again" on these approvals.

Only administrators can see or change this section. Every change is recorded in the audit log with the action and its old and new setting.

Functions from connected outside systems#

Functions that sync from a connected system are classed Read only when the system marks them read-only; a function that does not say counts as Write. The class is shown on the function and suggests its starting setting, but a function on Review is checked whichever it is. New functions start off. When you turn one on in Settings > Connectors, it is set to Allow if it is a read and Review if it is a write (Ask while Review risky writes is off), and you can change that straight away.

Editing a connector#

The person who built a connector sees Edit on its card. Nobody else can change its name, description, keywords or guidance, including other supervisors and admins.

1. Select Edit.
2. Change any of these fields:
   • Name.
   • Slug: lowercase letters, digits and underscores, starting with a letter. The field shows how Coworkers call it.
   • Description.
   • Keywords: comma-separated words people use when they ask for this. Coworkers find connectors by name, description and keywords.
   • Changes things in other systems: tick it for a Write connector, clear it for a Read one. Only an administrator can clear it; for everyone else it stays ticked once the connector is a Write. An administrator should clear it only if the connector just reads or looks things up; anything that creates, updates, deletes or sends counts as a write.
   • Guidance: Markdown. A Guidance preview shows how it reads.
3. Select Save changes, or Cancel to discard your edits.

The source code, dependencies and secret names are not edited on this page. To change them, ask a Coworker to update the connector in a conversation you are having with it, as the connector's builder. The Coworker changes the existing connector in place rather than building a new one. Work a Coworker does on its own from a trigger cannot change a connector.

Renaming a connector#

Changing the slug renames the connector in scripts. A note under the field, and a dialog that asks Rename to followed by the new name, explain that anything calling the old name must be updated. Select Rename and save to continue.

When you rename a connector:

• Every Coworker it is enabled on keeps it, with the same secrets, and uses the new name from its next reply.
• References to the old name in the connector's own guidance and description are rewritten to the new name.
• Saved scripts and workflows that call the old name are not changed. Update them yourself, or ask the Coworker that owns them.

A slug must be unique in your company; a taken slug shows "That slug is already used by another connector." After a rename, the card shows "Renamed." with the same reminder.

You can also ask the Coworker to rename a connector in conversation; it gives the same reminder.