Trigger Workflow API

Owned by sneha.tripathi
Last updated: Aug 18, 2022 by Kishore Surisetty
4 min read

The Luma Automation API ‘Trigger Workflow API’ is used to trigger a Luma Automation workflow. Based on the Workflow name, and input parameter details, the workflow is triggered in Luma Automation. The web service returns the trigger status as the response.

The Trigger API is asynchronous and does not wait for the workflow execution to be completed. It submits the workflow for execution and returns a Trigger ID. Using the “Trigger Id” the status of the workflow execution or step level execution information can be retrieved using the APIs Get Workflow History , Get Workflow Step History Records , Get Detailed Workflow Step History Record .

Additionally, The Generate Launch-in context URL API can be used to retrieve a Launch-in Context URL which can be used to launch a screen (in IFrame or new browser window) that provides a graphical representation of the workflow execution status:

Use the following details to configure Trigger Workflow API:

  1. Capture the tenant access token created during the Automation tenant provisioning. This token is sent as the Header to the API. Header → itas-api-access-key: <Tenant Access Token>
    You can also use Regenerate Tenant Access Token API to regenerate and fetch the tenant access token.

  2. Send Content-Type: application/json as the Header to the API.

  3. URI: /gateway/api/v1/workflow/trigger

  4. HTTP Method for the operation: POST

  5. Pass the following as Outbound Payload or Request to the Web Service. The request is passed in the following JSON format.

    { "workflowIdentifier": " sample_workflow", "variables": { "sample_workflow_input_parameter1": "sample_input_value1", "sample_workflow_input_parameter2": "sample_input_value2" }, "initiatorContactId": 1, // Consumer Application Contact Id "initiatorApplicationId": -2, // Consumer Application Id Registered in Automation Tenant. Possible values are -2 (for Luma/VSA), -4 (for ISM), -7 (for Change Gear) and -8 (for POB) "initiationInfo": { // Send this node only if there are any default parameters for the initiator application. This is application only for Luma and ISM, but not for Change Gear and POB "lumaChannelAccountId": "e54b080f-b306-4946-b9cc-4eb58034618f" // Populate this for integration with Luma/VSA. This is a mandatory parameter "ismTicketIdentifier": "100-1" // Populate this for integration with ISM. This is a mandatory parameter } }

    1. ‘workflowIdentifier’ represents the Automation Workflow name to be executed.

    2. ‘variables’ are the input parameters required to execute the workflow. In the above example:

      1. sample_workflow_input_parameter1 is the Parameter name.

      2. sample_input_value1 is the parameter value.

    3. ‘initiatorContactId’ represents the Workflow initiator's contact Id in the application/system from which the Automation workflow is executed.

    4. ‘initiatorApplicationId’ represents the application/system from which the workflow is executed.

    5. ‘initiationInfo’ represents the Luma Channel id through which the workflow is executed. In the above example:

      1. ‘lumaChannelAccountId’ represents the Luma Channel Account Id created for the channel through which the workflow is executed.

  6. For a successful workflow execution, the web service returns the response in the following format:

    { "status": "Success", "statusCode": 0, "statusLine": "Successfully submitted workflow trigger request.", "errors": null, "resultData": { "executionConfig": { "triggerId": "7e9a3842-b0ca-484c-8971-3ec2a4744b93", // Trigger ID will be used further to retrieve the status of the workflow and the history information "identifier": "sample_workflow", "name": "Name of the Sample Workflow" }, "statusInfo":{ "status":"SUBMITTED" } }, "warnings": null, "timestamp": 1641460724098, "reasonPhrase": null, "metaInfo": null }

    1. status represents the execution status of the API call. Success represents that the web service operation was successfully executed.

    2. statusCode represents the status code.

    3. statusLine represents the response message received from the web service. The message "Successfully retrieved Workflow definition." represents that the workflow is successfully executed.

    4. errors indicate the error received in case the workflow execution fails.

    5. resultData section contains workflow executionConfig details. The following details are received from the web service:

      1. triggerId represents the Workflow trigger id in Luma Automation. Trigger ID is used to retrieve the status of the workflow and history information.

      2. identifier represents the executed workflow identifier in Luma Automation.

      3. name represents the Name of the Workflow executed in Luma Automation.

    6. warnings field contains any warning received from web service execution. For successful execution, the warning field usually holds ‘null’ as a value.

    7. timestamp represents the time (Epoch time) of web service execution.

    8. reasonPhrase represents the error, in case web service execution fails.

  7. In case of any input parameter validation errors or rejections due to , the workflow execution may fail. In such a case, the web service returns a response in the following format.
    Note: When workflow execution fails, no trigger id is generated, instead the errors are returned in the “errors” field in the response.

    {Note "status": "DataValidationError", "statusCode": 1, "statusLine": "Failed to submit workflow trigger request due to validation errors.", "errors": [ "Sample workflow input parameter is required" ], "resultData": { "executionConfig": { // Observe that no Trigger ID is available in the error case "identifier": "sample_workflow", "name": "Name of the Sample Workflow" } }, "warnings": null, "timestamp": 1641482688265, "reasonPhrase": null, "metaInfo": null }