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.

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.

Document image

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.  

Document image

Step 4: Click on Call API (not configured) card to go to the configurations steps.

Step 5: Call API configuration - the Request builder.

Document image

  1. Verb: in this dropdown list you will find several methods that can be used to send different types of requests.
  2. 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 between "{ }" to complete your request resource URL/endpoint. Any information provided in the Query Params tab will be added in the URL.
  3. 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 as well);
    • 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 as well);
    • 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" and then click on "Insert Value".  This will expand you the area for typing and editing a larger value for your keys.

Document image

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 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.

Test the Call API Action

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.

Document image

Test Output: will display the Status of the test in Test Status (if it passed or failed) and also the response outputs. 

If the returned Test Status is "Successful"  but HTTP status code (Status Output) is 400/500 (meaning that the server did not return an actual response for some reason), this usually means that the action configuration passed the test. However, it may be the server that encountered an unexpected condition that prevented it from fulfilling the request.

An API response may consist of status code, body or files.

Document image

Status output: status code received from 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.

Updated 27 Apr 2022
Did this page help?