Running a workflow with an API step

A workflow that contains an API step can be triggered in the same way as other workflows. During the workflow execution, the API calls are made using the service account that is configured in each step.

An ION API call from Workflow is successful if these conditions are met:

  • There is a response code and this code is greater than or equal to 200 and less than 400. Codes less than 200, and codes greater than or equal to 400, are interpreted as an error calling the API.
  • The execution of the XPath or JSON Path gives no error. See the table for details.

This table shows the error handling when an incorrect path is specified in output mapping:

Situation Generates runtime error Behavior
The specified path is correct, but the value for this path is not found (null).

This mapping is set as Optional (checked).

 Success icon

No error

 Workflow continues and the workflow parameter that is used in this mapping is not changed.
The specified path is correct, but the value for this path is not found (null).

This mapping is not set as Optional (unchecked).

 Error icon

This situation generates an error at runtime.

Workflow continues or fails, depending on the settings.
The specified path is correct, but the value that is found for this path is an empty string.

The workflow parameter that is used in the mapping is of compatible type String.

Success icon

No error

 Workflow continues and the workflow parameter that is used in this mapping is set with the empty string "" value.
The specified path is correct. The value that is retrieved does not have the same data type as the workflow parameter in which it should be saved. Error icon

This situation always generates an error at runtime, even if this parameter mapping is marked as optional.

 Workflow continues or fails, depending on the settings.
The specified path is not correct: wrong syntax, for example, missing a closing bracket. Error icon

This situation always generates an error at runtime, even if this parameter mapping is marked as optional.

 Workflow continues or fails, depending on the settings.

If execution errors are encountered, these are handled according to the workflow configuration in the How to handle errors section on the Settings tab:

  • If the Continue workflow without changing parameters option was selected, the workflow continues to the next step. The workflow parameter values, as they were before the API step, are used.

    Optionally, you can select the Response status code check box and specify a workflow parameter. If the API call fails, the error response code is saved in this workflow parameter and can be verified in the next step in the workflow.

    The error response codes:

    • 503 or 504 in case the API has retried the maximum number of times configured in the Advanced Settings section. The last error code from a series of unsuccessful retries is returned.

    • A workflow specific error code "-1" if there was an exception trying to connect to the ION API.

    • Any other code less than 200 or higher than 399 which the API could return.

  • If the The workflow fails option was selected, the workflow gets status Failed. The remaining steps are not performed anymore. The reason for failure is visible in one of these places:
    • An error alert sent for business process errors, if this was configured in the Error Reporting section.

      For details, see Receiving alerts for business process errors.

    • The Reason column in the Manage Workflow Instances page in ION Desk. To open this page, select Monitors & Workflows > Active Workflows. Select the workflow name and click Workflow Instances.
    • The ProcessWorkflow.log log file.