Integration steps

The Integration category has one step, Call Rest Api. It calls an operation of a service connection: a REST API described by an OpenAPI 3.0 or 3.1 specification, with its address and security configured once. The step offers the operations the specification defines, and gives you a branch for each response the operation can return.

Call Rest Api

Calls a REST API operation and uses its response.

Setting	What it does	Required
Service Connection	The connection to call.	Yes
Operation	One of the operations the connection’s specification defines.	Yes
Set Timeout (seconds)	How long to wait for a response.	No
Security Scheme	Which of the connection’s security schemes to use. Shown when the connection defines more than one.	No
Parameters	A value for each of the operation’s parameters, shown as “name (Path/Query/Header/Cookie)”.	Required parameters must be set

Branches

Call Rest Api contains other steps, in branches on the canvas:

Branch	When it runs	What you use there
Request	Before the call, to fill in the request body. Shown only when the operation has a body.	[<Step>][Request]: set its fields with Update Variable.
Response	One branch per status code the operation defines (for example 200, 201, 404). The branch for the returned code runs.	[<Step>][Response][<code>]: the parsed response body. Response Text: the raw response.
Unexpected Error	When the call fails: a timeout, a connection error, a status code the specification does not define, or a response that cannot be read. The step itself does not fail, so an enclosing Try / Catch does not see the error.	[<Step>][error]: the error.

Outputs: the variables in the table above. Handle a failed call in Unexpected Error.

Behavior:

• A status code that the specification defines but you added no steps for runs nothing; the flow continues. A status code the specification does not define counts as a failed call and runs Unexpected Error. Define every response you need to handle in the specification, including error responses such as 400 and 500.
• An empty Unexpected Error branch silently ignores failed calls.
• The error variable holds the full technical error text, not a short message. Keep it in a log or a note for support, and show users a message of your own.
• The step itself fails only when the request cannot be sent, for example when a required parameter has no value. Only that kind of error reaches an enclosing Try / Catch.
• To keep a value after the step, copy it into a variable declared before it with Update Variable, inside the branch.
• The connection’s security is applied for you. Only Api Key, HTTP Basic and OAuth 2.0 Client Credentials and Password work at run time. See Service connections.

Example: sync a new Account to the ERP.

1. Call Rest Api CreateErpCustomer, operation createCustomer, on the “ERP” connection.
2. In Request, Update Variable [CreateErpCustomer][Request]: set name to GetAccount.name and vatNumber to GetAccount.new_vatnumber.
3. In Response 201, Update Variable on the Account row: set ERP Customer Number to the id in [CreateErpCustomer][Response][201], then Save Entity.
4. In Response 409 (already exists), add a note to the Account.
5. In Unexpected Error, create a “Sync Error” row with the message from [CreateErpCustomer][error].

Related

• Service connections
• Configuration values
• Error handling