Skip to main content

Connection Guide

This guide covers the settings that let an agent reach an outside service, and the settings that tell a person something has happened.

What to give an agent is covered in the Design Guide, and how much to allow is covered in the Execution Rules Guide.

Where a section has a place on screen, you will find where to set or check what it asks you to decide at the end of it.

A connector is something this project connects to​

Writing it into a goal does not by itself put an outside service that needs authentication within an agent's reach. That service has to be added as a connector and authenticated.

There are two kinds of connector: external services, and agent-to-agent integrations. They are added and authenticated the same way, and neither is stopped by the basic rules. To stop one you name it as a forbidden operation, but how you name it differs by kind (Execution Rules Guide).

The authentication belongs to the project. It is stored separately from your personal connections under Settings. Even where you have authenticated it yourself, it is authenticated again as a connector on the project.

Only an owner can add or authenticate one. Members cannot change them (Who decides what).

You are asked to confirm before removing a connector from the project. Once removed, the agents in this project can no longer use it. The connection (authentication) is not undone.

You cannot add to the candidates. What you can pick from is the set that has been made available. Where the service you want is not among them, talk to a system administrator.

There are two ways to authenticate, depending on the service: following the prompts on screen, and entering a token.

The authentication status is shown on screen. “Authenticated”, “Re-authentication required” and “Not connected” appear there, so check that no “Re-authentication required” is left before you run anything. “Status unavailable” can also appear. That is not the same as “Not connected” — the status simply could not be read — so look again a little later.

“Authenticated” is no guarantee that future runs will succeed. The permissions it has at the time are checked when the run happens. When it was last used appears in a separate field from the authentication status.

Where on screen The Settings tab ＞ “Connectors” ＞ “Add connector”. Authentication and status are in the same place

Use as ledger​

Joining the stages of a cycle needs a shared record (Design Guide). On the connector you are using as that record, put “Use as ledger”.

More than one connector can carry it.

Putting it there, however, makes nothing happen on its own. It is a mark, and the following do not follow from it.

  • No reading or writing begins. What to read and write is written into each agent's goal (instructions)
  • No permission is added. It does not let anything be done beyond what the authentication allows
  • No duplication or conflict is prevented. Keeping several agents off the same subject at once is expressed through the marks on the record and each agent's goal (Design Guide)

What putting it there does is show that the team has settled on this as the shared record. It is there so that whoever writes an agent's goal knows where to read and write.

Where on screen The Settings tab ＞ “Connectors” ＞ the connector ＞ the “Ledger” switch

A review is notified to the reviewers on its own​

A review request, and word that a review deadline has passed, reach the reviewers without anything being set up. They arrive both inside the product and as mail, with a link of the reviewer's own. To stop them, turn them off event by event (next section). How reviewers are settled is covered in the Review Guide.

These two are things that happen in a workflow. A cycle cannot have a review step, so on a project that is only a cycle they do not arrive (Review Guide).

Word that the deadline has passed arrives where “Notify and keep waiting” was chosen. Under the settings that proceed, send back or reject automatically at the deadline, nobody is told so long as that goes through (Review Guide).

What arrives takes you to the screen where you decide. Both the notice inside the product and the link in the reviewer's mail open the request itself under “Review requests” on the left, and that is where it is decided (Review Guide).

Where the reviewer's own link in the mail is still valid at the moment of deciding, the decision is recorded as having been made by mail. Even where the link has expired, anyone named as a reviewer can still decide on the screen — that decision is not recorded as made by mail, though.

In some environments mail is not sent at all. These are environments where mail delivery is not set up. There, the review request's activity keeps “Notification failed” (see a later section).

Where on screen “Review requests” on the left ＞ pick one. What arrives — the notice or the link in the mail — opens the same screen

Turning notifications off​

Notifications are turned on and off event by event. There are two events, Review requested and Review overdue, and both are on by default. A run starting, finishing or failing cannot be announced.

Turn one off and neither the notice inside the product nor the mail is sent. There is no switching to the product only, or to mail only. Turning Review overdue off also stops it reaching the escalation contact.

You cannot add a recipient. What arrives goes to the reviewers, and, when overdue, to the escalation contact — no one else. There is no setting for adding an address other than theirs.

Only an owner can switch them. This section appears for workflows only.

Where on screen The Settings tab ＞ “Triggers and notifications” ＞ “Notifications” ＞ the switches for “Review requested” and “Review overdue”

Checking whether it was sent​

The result of trying to send the review mail is kept in that review request's activity. It is not confirmation that it reached anyone, though. What is mostly kept is “Notification queued for sending”, “Notification was sent” or “Notification failed”.

Where it could not be sent — no address, or the recipient has opted out — that is kept here too. Look at this first when something does not arrive.

Where on screen “Review requests” on the left ＞ pick one ＞ “Activity”

Connectors on a project you copied​

The list of connectors carries over, but the connections (authentication) do not. Where you copied the project from another one, connect them again in the copied project. The screen says so.

This is because authentication carries permissions. It would be a problem if whoever copied it could go on using the original project's authentication, so it does not carry over.

The “Ledger” marks carry over too.

Whether notifications are on or off does not carry over either. The copy starts with both Review requested and Review overdue on, so turn off again whatever you had turned off.

Distinctions worth keeping straight​

These are the distinctions that cut across the sections above.

  • Thinking that “Use as ledger” starts the reading and writing. It is only a mark. What to read and write is written into each agent's goal. No permission is added either
  • Thinking that notifications can tell you about anything. Only two things can be announced: “Review requested” and “Review overdue”. A run starting, finishing or failing cannot be
  • Thinking it can be sent to addresses other than the reviewers'. A review request and a passed deadline reach the reviewers without anything being set up. But there is no setting for adding a recipient — all you can do is turn each event on or off
  • Taking “Notification was sent” in the record as proof it arrived. It is not confirmation of arrival. It holds the result of trying to send, no more
  • Thinking your personal connection can be used as it is. A project's connectors are authenticated separately from your personal connections
  • Thinking you can add the service you want yourself. You cannot add to the candidates. You pick from the set made available