REST integration
This chapter was written from the product's source code and has not yet been checked by a person on a running Cogneris. If what you see on screen differs, the screen is right — please tell your Cogneris contact so the chapter can be corrected.
Calls one of your systems' REST APIs through a connection, builds the request from the data of the process, classifies the answer and routes the process through Success, Not found or Error. The answer can be kept as a fact of the process and certified with a PDF.
| Palette | Nodes › REST integration. Connector presets, such as the VIES check, are added from Pre-configured as a REST integration with its settings filled in. |
| Outputs | Success — the call (or a check before the call) produced an answer. Not found — the destination said there is nothing for this lookup. Error — a permanent failure, or a transient failure whose retries ran out. See What happens in a run. |
| Content status | From source; not observed (workflow-fe f88c5c1, workflow-be 6703373, 2026-10-22) |
The REST integration has more settings than any other phase, so its reference is split into several pages:
| Page | What it covers |
|---|---|
| Overview and VIES tutorial | When to use it, Connections, the tabs at a glance, checks before the call, and a worked example with the VIES preset |
| Request | The Request tab: connection, method, path and path parameters, query parameters, headers, timeout, retries, success status codes |
| Schemas and mapping | The Schemas, Request mapping and Response mapping tabs, sources, and every transform |
| Result, Test and Publication | The Result, Test and Publication tabs |
| Messages | Every message the REST integration can show, with cause and fix |
When to use it
- To look something up in a system of yours or of a public body — a customer record, a tax number, a registry — and branch on the answer.
- To push data from the process into a system of yours (create or update a record) and continue only when it accepted it.
- To keep the answer of an external consultation as evidence of the process, with a PDF certificate.
To send the final result of a workflow to your system, the Send phase with a webhook is usually simpler — see Connect your systems.
What happens in a run
-
The connection is resolved. The phase reads its connection — base URL, authentication, default headers, timeout. A deleted connection, or one of another company, is an error of kind
connection. -
The request is built from the input of the phase (the output of the previous phase) and, where the mapping asks for them, from the process data: form answers (
$form), process metadata ($process), documents by type ($doc) and run metadata ($run). For POST, PUT and PATCH the Request mapping builds the JSON body; GET and DELETE send no body. Path and query parameters are filled in the same way. -
Checks before the call (the Checks before the call of the Result tab) are evaluated on the request. The first one that matches decides without calling the destination.
-
The request is validated against the Request schema, when there is one.
-
The call is made once, with the connection's credentials applied last, so nothing in the phase can replace them. The timeout is the phase's Timeout (seconds), capped by the connection's. With Send an Idempotency-Key that stays the same across retries on, every attempt of the same run and phase carries the same
Idempotency-Key; a correction round uses a new one. Redirects are not followed. For OAuth2 connections a rejected token (HTTP 401) is refreshed once, without counting as an attempt. -
The answer is classified:
Answer Result A Success status codes status, and no rule of Rules on the response body matched Success. The body, translated by the Response mapping (or the raw body without rules), becomes the answer. A rule of Rules on the response body matched What the rule says: Success, Not found, Transient (retried) or Permanent (error) A status listed in Not-found status codes (4xx) (404 by default) Not found 5xx, 408, 429, no answer within the timeout, a host that cannot be resolved, a connection failure Transient: retried Any other status, a redirect, a body larger than 5 MB, a success body that is not JSON or does not match the Response schema Permanent: error -
Retries. A transient failure is retried up to Retries times. The process waits Wait between retries (seconds), or longer when the destination asks for it with
Retry-After, never more than 600 seconds. No worker is kept busy while it waits. -
Routing.
- Success → Success.
- Not found → Not found when that output is connected. When it is not, the result goes to Error, never to Success.
- Permanent failure or exhausted retries → Error when it is connected. When Error is not connected either, the step fails and the process fails with it.
-
Publication. On the outcomes chosen in the Publication tab, the mapped answer is published as a fact of the process under its document type, and a PDF certificate is stored with the process documents. A later execution that no longer qualifies withdraws the fact and the certificate published before.
The phase adds its result to the data the next phase receives, under restCall and the phase's node id, keeping everything it received:
| Path | Content |
|---|---|
restCall. node id .ok | true for Success and Not found, false for Error |
.found | false for a not-found result, true for every other success |
.status | The HTTP status, when the destination was called |
.data | The mapped answer, on Success only |
.attempts, .durationMs | How many attempts were made, and how long the last one took |
.error.kind | On Error: transient, permanent, request_schema, response_schema, ssrf, connection, not_found or preflight |
.error.message, .error.status, .error.bodyExcerpt | On Error: the explanation, the status and up to 2 KB of the response body, with the connection's secrets removed |
A Conditional placed after the phase offers these paths in its field picker.
Configuration
The panel shows Description (the name of the phase on the canvas) and then seven tabs, in this order. Each field is documented on the page linked.
| Tab | What it holds | Page |
|---|---|---|
| Request | Connection, Method, Path, Path parameters, Query parameters, Headers, Timeout (seconds), Retries, Wait between retries (seconds), the Idempotency-Key option, Success status codes | Request |
| Schemas | Request schema, Response schema, Input example | Schemas and mapping |
| Request mapping | How the request body is built | Schemas and mapping |
| Response mapping | How the answer is translated into data | Schemas and mapping |
| Result | Not-found status codes (4xx), Rules on the response body, Checks before the call | Result, Test and Publication |
| Publication | Publish as a process fact, Proof of the query | Result, Test and Publication |
| Test | One real call with the current settings | Result, Test and Publication |
Above the tabs, a list shows every problem the editor finds in the settings while you edit — see Messages. A phase added from a preset also shows a preset banner — see the VIES tutorial in Overview and VIES tutorial.
A workflow can have at most 20 REST integration phases; publication refuses more.
Buttons and actions
| Button | What happens | Reversible? |
|---|---|---|
| Manage connections | Opens Connections | — |
| Load from a run | Loads up to five recent outputs of the phase that feeds this one, to use as Input example | Yes |
| Test the call › Call now | Makes one real call to the destination | No — the destination receives the call |
| Preset parameters › Apply parameters | Replaces the whole configuration of a preset phase with the preset's, for the new parameters; the phase keeps its links to other phases | Only by editing again |
Common problems
| Message | Cause | What to do |
|---|---|---|
| Choose a connection. | No connection selected | Select one in Connection, or create it in Connections. |
| The process fails at this phase | An error with Error unconnected, or a not-found result with neither Not found nor Error connected | Connect Error (and Not found if the lookup can find nothing). |
| A not-found answer continued on Error | Not found is not connected | Connect Not found. |
| Publishing fails although the problem list is empty | The service refused a setting the editor cannot check, for example a connection deleted meanwhile or a document type that is the name of one of your templates. The service's message names the phase and the field. | See Refused by the service in Messages. |
Every other message is in Messages.
Related
- Overview and VIES tutorial
- Connect your systems — webhooks and Connections
- Conditional — branch on
restCall.node id.data - Cross-check — compare a published fact with the documents of the process
- KYB — the phase the VIES preset replaced
- Design and publish a workflow
Last reviewed 2026-10-22 · Version 1.0.0 · Owner: product-documentation