Using Parameters in API Tasks
Use input and output parameters in API tasks to allow for more flexibility.
Input Parameters
You can define input parameters in an API task and use them to for example flexibly adjust the endpoint path based on your scenarios or to pass a job id.
-
Open the properties panel of your API task, go to Input Parameters and click .
-
On the Input Parameters dialog, add an input parameter by completing the following properties:
Property
Description
Input Parameter
Enter a name for your input parameter. The parameter name must be alphanumeric and digits are only allowed from the second position onwards.
Action
Choose from the following:
-
Map To - Map the source input parameter to the task chain.
-
Set Value - Enter a value to resolve the input parameter.
Value
Enter or select the value depending on what action you selected.
For more information, see Create Input Parameters in Task Chains step 5.
-
-
You can now use parameter references in the API Path using the following syntax: {{<parameter_name>}}, for example:
Method Used for API Invocation
Example API Path with Parameter Reference
POST
/v1/invoke/{{resourceId}}/action/actionName
GET
/v1/status/{{jobId}}
-
Parameter references are not automatically replaced in the request body. You must reference parameters in the JSON request body using the following syntax: "$ref": "#/user/<parameter_name>.
On the top right above the request body, click the info button to open a list of the parameter references, and click the copy button for the one that you want to use to copy it with the correct syntax to the request body.
-
When doing an API test run, you will be prompted to enter the values for the parameters you're using.
During runtime, the parameter reference will get replaced if the parameter exists. If it doesn't exist, the system will show a validation error.
Output Parameters
You can define output parameters in an API task to pass information returned by the API to the next task in the task chain. This only works for APIs that return content type `application/json`.
-
Open the properties panel of your API task, go to Output Parameters and click .
-
On the Output Parameters dialog, add an output parameter by completing the following properties:
Property
Description
Output Parameter
Enter a name for your output parameter.
JSON Path
Enter the JSON path used to extract the output parameter from the API response.
The path requires the following syntax: It needs to begin with $, use dots to navigate the structure, and use explicit array indexing.
Unsupported syntax:-
Wildcards (*)
-
Filters (?())
-
Deep scanning (..)
If a JSON path is invalid or it doesn't match anything, the task will fail. A message will appear in the task log with information about the related issue.
Data Type
Choose a JSON type that will be used to check the value of the output parameter:
-
String
-
Number
-
Boolean
-
Object
-
Array
-
Null
-
[default] Any
If the value doesn't match the selected type, the task will fail. If you select Any, the type check won't be performed.
Task Chain Parameter
Map the output parameter to a task chain parameter by entering the required parameter name. The mapped output parameter of the API task can then be used as an input parameter for the following task.
-