Trigger Workflow API

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

Please note that the Trigger API is asynchronous and does not wait for the workflow execution to be completed. It submits the workflow for execution and returns the 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.

The following 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 represention of the workflow execution status: Generate Launch-in context URL

Use the following details to configure Trigger Workflow API:

Capture the tenant access token created during the Automation tenant provisioning. This Bearer token is sent as the Header to the API. Header - Authorization: Bearer <Tenant Access Token>
You can also useRegenerate Tenant Access TokenRegenerate Tenant Access Token API to regenerate and fetch the tenant access token.
Send Content-Type: application/json as the Header to the API.
URI: /gateway/api/v1/workflow/trigger
HTTP Method for the operation: POST
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) and -4 (for ISM) 
  "initiationInfo": {
    "lumaChannelAccountId": "e54b080f-b306-4946-b9cc-4eb58034618f" // Populate this for integration with Luma/VSA. This is a mandatory parameter
    "ticketIdentifier": "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.
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.

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
}