chesterdocs

#Create a system, adapter and action

A system groups a service, an adapter says how to reach it, and an action is one operation a process can call.

You work through these in order, because each one hangs off the last.

#The order you build them in

The Northwind ERP system in Chester, with its Adapters tab open. The header shows the system name, an Active status, its software type and base address. Tabs across the page count what belongs to it: 1 adapter, 2 credentials and 3 environments. The adapter listed is "Northwind REST API" — the definition of how Chester connects to that system.

The three levels are separate on purpose: the system is named once, an adapter says how to reach it, and each action is one operation that adapter can perform.

Each one hangs off the last. The dotted line is the pairing a process task makes: an action plus the environment it runs against.

#Create a system

A system is the bracket around an external service. Give it a name, optionally a logo and tags. That is all it holds — deliberately. A system carries no address and no credentials, so the same system can be reached differently in production and in test.

#Add an adapter

An adapter is one way of connecting to that system. You choose:

  • A name. Unique within the system for its direction.
  • A type — HTTP / REST, HTTP Inbound / Webhook, GraphQL, E-Mail (SMTP) or LLM provider. It decides the direction — outbound (Chester calls out) or inbound (the system calls Chester) — and which fields the adapter and its actions offer. Email and LLM provider adapters have no actions: a send task uses the email adapter directly, and an agent runs on an LLM provider adapter (see Connect an LLM provider).

A system can have several adapters. A service with both a REST API and a webhook is two adapters on one system, not two systems.

An outbound HTTP or GraphQL adapter also has a request timeout: how long Chester waits for the system to answer before the step fails and is retried. ⚠️ For HTTP it limits the wait, not the call — a call that answers later may already have done its work when the retry runs. Leave it empty to use the default of 30 seconds. A timeout below 10 seconds is refused when you save the adapter.

#Give the adapter its path, not its host

An adapter also carries the path prefix its actions share — /v2, /odata/v2/ledger, /api. The host does not belong here: that comes from the environment the process selects, so one adapter serves the development, test and production servers of the same system.

An inbound adapter that registers a webhook works the same way: it has only a webhook base path, and the host comes from the environment. Every element that uses such an adapter must therefore select an environment — the modeller reports an error otherwise, just as it does for an outbound adapter.

Inbound adapters created before this still keep their full registration URL as a fallback for elements without an environment. On those, leave the webhook base path empty while the registration URL carries a path, and an element that selects an environment registers at the host without that path — the registration then usually fails at the other service rather than at Chester. But fill it in when the environment already carries the same path, and the registration gets that path twice. The modeller reads both together and tells you which of the two applies, naming the value to enter or the prefix that would result; it only ever warns, because a system genuinely split across the two places is unusual rather than wrong.

Either field rejects a full URL. The webhook base path says so at the field; the outbound base path and the GraphQL path only when you save, with a German message.

#Define actions

An action is a single operation: "create a task", "fetch an invoice". It carries the parameters, the request body and the response body, so a process can be modelled against it without anyone re-reading the external service's documentation.

You can create actions by hand, or import them while creating the adapter — from an OpenAPI description, from a GraphQL introspection result, or from a template in the Registry. ⚠️ A later import is not possible.

Once an action exists, a task in a process can select it, and the modeller offers its parameters as fields to fill in.

#Why the three levels are separate

A process refers to an action and an environment. It never refers to a URL or a password directly, so a server that moves, or a credential that is rotated, is corrected in one place and every process that uses it follows.

Changing which server a step talks to is still a change to the process: the environment is part of the model. See Environments and credentials.