Call API action
The Call API action enables you to perform REST/HTTP requests to a specified web API to query data from apps and services. You can retrieve, add, delete and update data.
PROCESIO integrates the Call API action with your API authentication credentials defined in Credentials Manager. This means that you have to create an API credentials configuration for the web service/app you want to connect to in Credentials Manager (check Working with Credentials Manager).
For example, if you want to connect to a JIRA REST API web service, you must once configure the authentication credentials of JIRA service in Credentials Manager and you can use this configuration in setting up Call API actions.
You can test the request and see the response received from the API server that helps you troubleshoot if needed.
Go to the Process Designers section and open a new or an existing process. Actions configuration can be performed once they are dragged and dropped on canvas.
Step 1: Drag the Call API action from Toolbar and drop it on canvas; click on the action to open the Properties Panel.
Step 2: You can edit the action name.
Step 3: Select first the API credentials configuration in Properties Panel. The API credentials configuration needs to be created upfront in Credentials Manager to be displayed in the list.
Step 4: Click on Call API (not configured) card to go to the configurations steps.
Step 5: Call API configuration - the Request builder.
- Verb: in this dropdown list you will find several methods that can be used to send different types of requests.
- Endpoint URL: in this field, the URL to request is already populated with details from the API credentials configuration selected at Step 1; you need to add the Method Name and IDs to complete your request resource URL/endpoint. Any information provided in the Query Params tab will be added to the URL.
- Query Params: this tab is used to specify any HTTP query parameters you may want to include with your request. A new line is added once the previous one is filled in. Query Params will be appended to the end of the request URL, following "?". You will not be allowed to add query params directly in the URL. To send a path parameter, enter the parameter name into the URL field, after a colon ":".
- Name: the name of the parameter;
- Value: the value of the parameter (can be a process variable, or text + variable);
- Headers: this tab is used to specify any optional HTTP request headers you may want to include with your request. A new line is added once the previous one is filled in.
- Name: the name of the header;
- Value: the value of the header (can be a process variable, or text + variable);
- Body: allows you to specify the data you need to send with the request; the editor supports the JSON format.
For Query Parameters and Headers use "Activate for multi-line editing" icon. This will expand the area for typing and editing a larger value for your keys.
The request can contain process variables in Query Params, Headers, Body. To open the variables selector and start using process variables, press Insert key (for Windows) or Shift+Tab (for Mac). All process variables used in Call API configuration will be displayed by default in Test Action > Test Values section.
Depending on the Authorization type defined in the selected API credentials configuration, API key and their values may be added in Headers or Query Params tabs to be passed along with the request.
4. Output Variables
In order to make use of the data that will be received in the Response further in the process flow, you need to map the outputs to process variables. There are 3 types of possible output that you can map:
- Status Output: stores the status code received from HTTP request, as an integer variable.
- Body Output: stores the response received from the HTTP request, as a string or JSON process variable.
- File Output: stores the file received from from the HTTP request, a file type process variable.
Once the Request builder is configured, you can Test the action. Click on "Test Action" on the bar and a new section dedicated to testing will open.
Test Values: in this table you will populated under "Variables" all the process variables used in the configuration of the Request. The "Type" of the process variable is also displayed, this helping you to assigned the correct test values to variables. Hit "Test Action" to test the configuration.
Consider that sending a test request with DELETE, PUT, UPDATE method may alter the data.
An API response may consist of status code, body or files.
Status output: status code received from the server.
Body Output: once the response has been returned in body, you can Download or Save to clipboard.
File Output: if the response returns a file, you can see the name of Download it as a JSON.