Documentation › Call an API
Call an API from a step
A Task step can call an external service (REST, SOAP or GraphQL): the person who does the task clicks a button, the service answers, and the values of the response go into variables of the process.
How it works
- The designer opens the Task step in the editor and defines the call in the API call tab: where to call, with what, how to sign in, what to expect back and which values to keep.
- The definition is stored with the process. Nothing is called when the process is published.
- In a process instance, the person who does the task sees an API call panel and clicks Call the API.
- The response is shown, and the values kept are written into the outcomes (Outcomes) of the task, so into the variables of the process.
Define the call (API call tab)
In the form of the Task step, open the API call tab and click Add an API call. The Remove the API call button takes the call off the step, and the Documentation link opens this page. In front of each field, the (i) button explains what to type, with an example, and links to the matching section of this page.
The request
- Kind of call: REST (a simple HTTP request), SOAP (an XML message sent to a web service) or GraphQL (a query sent to a single address).
- Method (REST): GET reads, POST creates, PUT replaces, PATCH changes, DELETE removes, HEAD and OPTIONS. SOAP and GraphQL always use POST.
- Address (URL): the full address, starting with
http://orhttps://. - Time to wait for an answer (seconds): from 1 to 120, 30 by default.
Path parameters: /{id}/{name}
Write the parts of the address that change between curly braces, for example https://www.site.com/{id}/{name}. In Path parameters, the Add the parameters of the address button creates one row per part; give each its value, typed here or taken from a variable (link button). The value is encoded for you: spaces and slashes do not break the address.
- Each part between curly braces must have its row, and each row must be used by the address: otherwise the publication is refused with a message that says so.
- Do not mix them up with a variable of the process, which is written
${VariableName}(see Use the variables).
Query parameters and headers
Query parameters (added to the address: ?page=2&size=10) and Headers are “name / value” rows. Untick Send to keep a row without sending it. Content-Type is set from the type of body: write it only to use another one.
For each header, query parameter or body value, the Secret checkbox encrypts the value: it is then never shown in clear nor written in the logs. Without the box, names such as password, token, key or secret are treated as secrets. See Encryption and your own key.
The body
- REST (Body): none, JSON, text, XML, form (URL encoded) or form (multipart). In a text,
${Variable}is replaced by the value, escaped for the type:{"customer": "${Customer}", "quantity": ${Quantity}}(a variable that holds a number is written without quotes). - SOAP (SOAP message): the version (1.1 or 1.2, the one of the WSDL of the service), the action (SOAPAction, for example
http://tempuri.org/GetPrice) and the message: the whole envelope, or only the content of itsBody(the envelope is then added). - GraphQL (GraphQL document): the query, for example
query GetUser($id: ID!) { user(id: $id) { name } }, its variables as JSON ({"id": "${UserId}"}) and the operation name when the document holds several.
Authorization
Authorization: secrets are hidden while typed and can come from a variable.
- Basic: user name and password.
- Bearer token: a token, sent after the word
Bearer(or the prefix you give). - API key: the name of the key (for example
X-Api-Key), its value, and where to send it (in a header or in the query parameters). - OAuth 2.0: the call first gets a token from the token service (Address of the token service, often ending with
/token) with the client id and secret (Client id, Client secret) and, as you choose, the Scope asked or a user name and a password. Tick the box to send them in the body if the service does not want a header. - Digest: the service challenges the call, the hashed answer is sent automatically.
User authentication
When a service asks the person to log in, tick This call logs the user in (User authentication section). Draw this call, or these calls (one per step), according to the authorization of the service: token, session, etc.
- In the process instance, the person who does the task sees a user name, a password and the Log in button instead of Call the API.
- Write
${Login.Username}and${Login.Password}in the address, headers, body or authorization (for example the user and password of a Basic authorization). - Extract the token (JsonPath) or the session (
Set-Cookieheader) into variables: the next calls use them (Bearer token,Cookieheader). - The user name and the password are never stored, and the response of the login is not shown: only the values kept in the variables are.
The expected response
- Response type: what the body of the response is (JSON, XML or text). Choose it to be warned when the service answers something else. It also decides the ways to read a value: a JSON path for JSON, an XPath for XML; Any (not checked) checks nothing.
- Status codes: the codes that mean success, for example
200-299,404. Any other response makes the call fail. - Example of a response: a reminder for you, not checked.
A call also fails when the service answers with a SOAP Fault or GraphQL errors, even with a 200 status.
Values to extract from the response
Values to extract from the response: each row reads a value in the response and puts it in a variable of the process. An outcome (Outcomes) is added to the step for each variable.
- Read from: JSON path, XPath, Response header, Status code or Whole body. The choices follow the type of the response.
- Path or name:
- JSON path:
$.data.id,$.items[0].name(first element),$.items[-1](last),$.items[*].id(every element),$..id(anywhere),$['a b'](a name with a space). - XPath:
//GetPriceResult,//Item[1]/@id,count(//Item). Namespaces are ignored. - Header: its name, for example
ETag.
- JSON path:
- Variable: the variable that receives the value. A number, a date (
2030-03-15), a yes/no (true,yes,1), an email address or the name of an option (list variable) must fit the type of the variable. - Required: when the value is missing or does not fit, the call fails (otherwise the value is skipped).
- Secret: for an access token, a session cookie or any value nobody should see. The variable (a text one) keeps it encrypted with the key of your organization: it shows neither in the outcomes of the task (read-only Encrypted value field) nor in the response on the screen (body and headers hidden, Kept encrypted instead of the value), and only the next API calls read it in clear.
Use the variables of the process
- For the value of a row or a secret, click the link-shaped button: the value is then taken from a variable when the call is made (a Process or Global variable).
- In an address or a text (body, SOAP message, GraphQL query), write
${VariableName}, or use Insert a variable in the text. The value is escaped for where it goes (JSON, XML, address). - A variable without a value when the call is made stops it: nothing is sent and the message names the missing variables.
- A call can use what an earlier call kept: for example a token got by a first task and used as the Bearer token of the next one.
Make the call in a process instance
On the page of a task of a Task step that has a call, the API call panel sums the call up (kind, method, address, authentication, expected statuses) and lists the Extracted values. Click Call the API:
- The Response card shows Succeeded or Failed, the status, the duration, the body (JSON is formatted) and the headers.
- Values from the response tells, for each value, Applied or Not applied (with the reason). The outcomes of the task and the variables are updated.
- When the call fails (service unreachable, unexpected status, SOAP fault, GraphQL errors, required value not found, value that does not fit the type of the variable), no variable is changed.
- You can make the call again: the values are replaced.
Security and limits
- The secrets typed in the definition (password, token, key, client secret, and the headers, parameters or fields whose name says they carry a secret, such as Authorization or X-Api-Key) are encrypted with a key of your organization as soon as the process is saved. They are never sent back to the people who do the task, nor shown again in the editor: the field stays empty with Saved and encrypted. Leave it empty to keep the secret, type a new value to replace it.
- A value that holds
${Login.Username}or${Login.Password}is not encrypted: it holds no secret, only the place of what the person types. - The call is made by the SerenForce server: addresses of a private network (localhost, 10.x, 192.168.x, cloud metadata services…) are refused, unless the administrator allows them.
- The body of the response is cut beyond about 1 MB; a value can then no longer be read reliably.
- A Secret value is decrypted for the API calls only: its variable can be used in the API calls only. If a condition, the formula of a calculated variable, an Output Box or the values a Link process step gives to its linked process use it, the process is not saved and a message says which variable to remove and from where. In a document or an email generated from a template, its placeholder (
{{Token}}) stays as it is: the value never shows there, neither in clear nor encrypted. Tick Secret then publish the process: the process instances started from an earlier version keep the value as it was.
Tips
- Try your service with a tool such as Postman before defining it here: the fields are the same.
- Pick a response format (JSON or XML) to be warned when the service answers something else.
- A value for a list variable (simple list, multi-choice list) must be the name of one of its options.