Property description
The callRestApi action type calls an external REST API once for every object in the stream, for example to create a ticket in an ITSM tool or to register a published data product in an internal portal.
The target host and the credentials come only from a connection of the REST API provider. The action contains a reference to the connection, a relative path, the method, headers and an optional body.
Never write a password or token into the package JSON. Credentials are stored only in the REST API connection.
Minimal JSON
{
"key": "",
"type": "callRestApi",
"connectionKey": "",
"method": "",
"urlExpression": ""
}
Nested properties
| Property | Description | Values | Mandatory |
|---|---|---|---|
key | Key of the action. | string | Yes |
type | callRestApi | string | Yes |
connectionKey | connectionKey of a REST API connection that has Allow use in automation actions switched on. | string | Yes |
method | HTTP method. | GET, POST, PUT, PATCH, DELETE | Yes |
urlExpression | Relative path without a leading /, joined to the base URL of the connection. Supports Dynamic Expressions. | string | Yes |
bodyExpression | Request body. Ignored for GET. | string | No |
contentType | Content type of the request body. | string, default application/json | No |
headers | Additional request headers as pairs of name and valueExpression. The authentication header is added by the connection. | array | No |
retryCount | Number of repeated attempts after the first one. | integer 0-5, default 0 | No |
timeoutSeconds | Timeout of a single attempt. | integer 1-120, default 30 | No |
Example
{
"key": "call_servicenow",
"type": "callRestApi",
"connectionKey": "servicenow_cmdb",
"method": "POST",
"urlExpression": "api/now/table/u_data_product",
"headers": [
{
"name": "X-Dawiso-Object-Id",
"valueExpression": "{{currentObject}.id()}"
}
],
"contentType": "application/json",
"bodyExpression": "{'{'}\"name\":\"{{currentObject}.name().jsonEscape()}\",\"state\":\"{{toWorkflowState}.name().jsonEscape()}\",\"publishedBy\":\"{{creator}.email().jsonEscape()}\"{'}'}",
"timeoutSeconds": 30,
"retryCount": 0
}
Writing a JSON body
In expressions every { starts a dynamic expression and a } outside an expression is an error. A literal brace is therefore written as {'{'} and {'}'}. The body above evaluates, for an object named Customer "Gold", to:
{"name":"Customer \"Gold\"","state":"Published","publishedBy":"jane.doe@example.com"}
Wrap every dynamic text inside a JSON string in .jsonEscape(). It escapes quotes, backslashes and control characters and adds no surrounding quotes. When contentType is application/json, the evaluated body must be valid JSON, otherwise the request is not sent and the object is counted as failed.
The variable {{creator}} is the user who triggered the event. It does not exist for a rule started by a schedule trigger: every object then fails with an expression error, nothing is sent, and installing the package does not warn about it. {{creator}.email()} also fails for a user without an email address.
{{toWorkflowState}} is available only for the single-object workflow state change trigger. With the bulk variant every object fails with an expression error. On {{fromWorkflowState}} and {{toWorkflowState}} only .name() is supported. .id() fails with an expression error.
Connection setup
An administrator creates the connection manually on the connections screen, see REST API connection. Fields:
| Field | Description |
|---|---|
| Connection key | Mandatory. Letters, digits, underscore and hyphen only, at most 100 characters. Unique regardless of letter case among REST API connections, and cannot be changed after the connection is created. The action refers to the connection by this key. An inactive connection keeps its key reserved. The key of a deleted connection can be used again. |
| Base URL | Complete https:// address including host and an optional common path prefix. An address without a scheme or with http:// is rejected when the connection is saved, and so are addresses with user info and loopback, link-local and cloud metadata hosts. Do not put a secret into the URL: a query string or fragment is stored and returned as plain text. |
| Authentication type | API key / static token (apiKey) or OAuth2 client credentials (oauth2ClientCredentials). |
| Header name, API key / token, Value prefix | For API key / static token. The header is sent as prefix plus value, for example Authorization with the prefix Bearer . |
| Token endpoint, Client ID, Client secret, Scope | For OAuth2 client credentials. The token endpoint must be HTTPS. The token is cached for its validity and renewed before it expires. |
| Allow use in automation actions | Off by default. While off, no request is sent. |
Secret values are stored encrypted and are never returned by the API or shown in the UI. Entering a new value replaces the secret. An empty value during editing keeps it.
If the connection does not exist, is inactive, belongs to another provider or is not allowed for automation actions, every object is skipped without any HTTP request. The run log only counts the skipped objects and gives no reason. Check the connection when the end entry shows skipped objects: Automation Preview names the cause.
Installing a package shows a warning in two cases only: no connection of the REST API provider with that key exists in the target environment (a deleted connection counts as missing), or the key belongs to a connection of another provider. There is no warning for an inactive connection or for a connection with Allow use in automation actions switched off. The warning is a snapshot taken at installation and stays on the package version after the missing connection is created.
Security rules
urlExpressionmust be relative and without a leading/. Absolute URLs,//host, user-info (user@host),..segments and any result leaving the origin or path prefix of the connection are not sent. The check runs after the expressions are evaluated, before each attempt.- Redirects are never followed.
baseUrlandtokenEndpointmust use HTTPS. Private network addresses are allowed for internal APIs. Loopback, link-local and cloud metadata addresses are always blocked, including when the host name resolves to them.- Header values must not contain CR or LF after evaluation. A header from the action cannot replace the authentication header managed by the connection, whatever the letter case of its name.
- The header names
Host,Connection,Transfer-EncodingandContent-Lengthcannot be set. The package installs, but every object fails with an invalid header error and no request is sent.
Retries and result
Any 2xx response is a success. The response body is not read or stored.
With the default retryCount of 0 no request is repeated. With a higher value only timeouts, network errors and responses 408, 429, 500, 502, 503 and 504 are repeated, at most retryCount times. Other 4xx and 3xx responses are final.
With OAuth, a 401 response discards the token, obtains a new one, and repeats the request once. This does not count towards retryCount. A second 401 and any 403 are final. With apiKey a 401 is final.
Object-level failures come from an expression error, an invalid JSON body, a header with a line break, an unsafe path, or an HTTP error response for that object. An object-level failure affects only that object, and processing continues for the rest.
Connection-level failures happen when the OAuth token cannot be obtained, credentials are invalid, the target address is blocked, or the connection cannot be read. A connection-level failure stops the action for the remaining objects. Those objects are counted as failed with a single log entry, because every one of them would fail the same way.
The run status does not show these failures. The run stays Success in the audit log run list even when every object failed or the action stopped at a connection-level failure. Check the end entry of the run log for the number of failed objects.
Logging
The action writes to the standard automation run log, which you can open in Settings > Automation > Audit Logs:
- one entry at the start: action key, method, connection key, number of objects,
timeoutSecondsandretryCount, - an entry for each of the first 9 failed objects: object id, attempt number, safe error category and HTTP status,
- when more than 9 objects failed, one entry with the text
N further object failures were not logged individually, - when a connection-level failure stops the action, one entry with the text
REST API calls stopped after a connection-level failure: <category>; N remaining objects failed without being called, - one entry at the end: duration and the numbers of input, successful, skipped and failed objects.
A run in which 50 objects failed, for example, writes 12 entries for the action: the start, 9 failed objects, the entry counting the other 41, and the end.
The log never contains secrets, header values, connection data other than the connection key, access tokens, the full URL, the query string or the request body.
Preview
Automation Preview does not send any request and records no run. To open it, go to Settings > Admin tools > Automation preview, select the package, enter a specific object and click Run preview.
For each object the preview shows the action key and the address that would be called, for example call_servicenow: -> would call REST API at https://example.com/api. The address is the origin and the path prefix from the connection, without a query string or fragment. The connection key and the path of the action are not part of it.
If the connection cannot be used, the preview shows a warning for the object instead of the address:
| Warning | Meaning |
|---|---|
REST API connection '<key>' not found | No active connection of the REST API provider has this key. The connection is missing, deleted or inactive, or the key belongs to another provider. |
REST API connection '<key>' is not allowed for automation actions | Allow use in automation actions is switched off on the connection. |
REST API connection '<key>' has no valid base URL | The base URL of the connection is not a valid HTTPS address, for example it uses http://, targets a loopback or metadata address, or contains user info. |
When the stream holds too many objects, the preview does not list action impacts. Run it for a specific object.