Call API
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.
How to configure the Call API action?
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.
- Tabs:
- 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 or simply press "Esc". ย This will expand the area for typing and editing a larger value for your keys to a full screen editor.
The request can contain process variables in Query Params, Headers, and Body. ย To open the variables selector and start using process variables, press the Insert key (for Windows) or Shift+Tab (for Mac). All process variables used in the 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, the 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 the HTTP request, as an Integer.
- Body Output: stores the HTTP request response body as aย String or JSON.
- File Output: if the response contains a file, it is stored as a File.
5. Time out
You can specify how long to wait for an API call to complete before a timeout occurs. The minimum setting is 60 seconds, and the maximum is 3600.
