API Triggers for Workflows

Overview

What is API trigger in Service Automation?

Triggers specify the conditions that starts the Workflows. With API triggers included in Service Automation; Workflows can be executed without depending on ITSM tool. SummitAI Automation receives the workflow triggers through any other third-party tool like Postman, HRMS, ITSM or monitoring tools.

The following Infographic summarizes the API triggers in Service Automation.

Why API triggers for Service Automation?

A new API trigger is added through which the workflow automation happens. Workflow is a combination of one or more tasks executed in a specific order on a Configuration Item (CI) to achieve a particular service to customer or team or individual. In Workflow, conditions are defined. If this condition is met, the defined Scripts are executed. This does not require any manual intervention. Using drag and drop, you can add a Script or Condition to the Workflow. The Workflow starts executing when a third-party tool like Postman sends a REST request to the instance.

The following detailed infographic illustrates the process flow of API triggers as source.

The description of the highlighted step numbers is listed as below:

1. API trigger or Summit ITSM triggers the Workflow. System creates an entry in the event queue to start the flow.
2. Listener Service loads event details from Event queue.
3. Event listener like Rabbit MQ processes the event and identifies the Workflow and insert details in the queue.
4. Execution service loads the script and target details. Executes and outputs data to database.
5. Loads Master data, Incident, SR, and Work order details.

Use case

The employee onboarding is the best example of service automation. This automated process is triggered with the HR Manager triggering the workflow with an API call from any third-party API generator tool or HRMS tool. The automated workflow must be triggered when HR manager or any IT Admin wants to trigger API for User creation. This process is now possible to trigger through APIs without depending on Service Request.

Feature Capabilities

• Plug and Play: The ease of integrating or using SummitAI orchestration is made simpler with this feature.

• Self Service adoption: This feature doesn’t depend on a Service Request, Incident or Work Order to kick start the automation Workflow.

• Increased Flexibility: Third party tools that can trigger API can be used to initiate the workflow.

• Eliminate repetitive tasks – Emulates user actions and avoids mundane tasks.

Procedure

The procedure to configure this API trigger is summarized in the following infographic.

Prerequisite:

Add RabbitMQ connection string in ~/Config/ConnectionStrings/Prod.config of Orchestration API Project.

<add name="RabbitConnector" connectionString="amqp://guest:guest@localhost:5672/"/>

Steps to configure:

1. Configure Workflow with trigger event as API.
2. Create user authentication token using Postman.
3. Call the API trigger with Workflow and inputs
4. Save API and retrieve the status of the API Trigger which includes Linking Status and Execution Status.
5. Retrieve API trigger status with API reference ID

Let us see the above mentioned steps in detail.

1.Configure Workflow with trigger event as API

In this step, configure the Workflow that must be triggered based on the API trigger. The Workflow trigger event will be selected as API.

Steps:

1.Navigate to Admin > Automation > Orchestration

2.In the Orchestration application, Navigate to Orchestration Workflows and create new Workflow.

Figure: Add new Orchestration Workflow

Figure: New Drop-down value API

3.In the WORKFLOW CONFIGURATION pop-up, Enter Workflow Name, Workflow Category, Description.

4. Select the Trigger Event as API from the drop-down.

    Figure: Workflow Configuration

5.On the Workflow Configuration screen, drag and drop the required Scripts.

6.In the script properties, Target Host Type can be set as SummitAI Proxy Server or Execution Server or Remote CI.

7.Case 1: Select Target Type as CI, Target Host Type as SummitAI Proxy Server / Execution Server.           Select the Proxy Server Host from the drop-down values of IP addresses of Orchestration Proxy Servers.

          Figure: SummitAI Proxy server as Target Host Type

Case 2: Select Target Type as CI, Target Host Type as Remote CI. In this case the IP address of the remote server must be entered manually. If the script must be executed on an AD machine enter the IP address of the same. 

Figure: Remote CI as Target Host Type

To connect to the specified Remote CI IP address mentioned, configure Username and Password in the Windows Credential Manager (Generic Credentials) of the SummitAI Proxy Server/ Execution Sever. Since the Orchestration Execution Service is running on Local System account, the credentials created by the logged in user on the proxy will not be accessible by the execution service. To configure credentials for Local System account, see Create Credentials in Windows Credential Manager           

8.Navigate to Parameter Details. For any Input Parameter Name select the Data Source as API to get the Parameter value from API Payload. In the Data field specify the Value configured against Parameter attribute in API Payload. from the API that must be mapped to Data Source to trigger this Workflow.

Example: To pass “Fredrick”, “Norton” to the script parameter, specify firstName and lastName as data field value against the Parameter in the Parameter details section.

9.Drag and drop other required scripts, specify mandatory field values, and click on Submit to create new workflow.

2.  Create user authentication token using Postman.  

Generate a unique User authentication token using Postman. This is required to call API that must trigger the Workflow configured in previous step. Enter the UserName and Password in the following API. This must be email ID and password that is used to login to the Orchestration Application.

Steps to create a Workspace and create a request API in postman

1. Login to the Postman
2. Click Workspaces > Create Workspace. Fill in the relevant details to create a new workspace.
3. In the newly created workspace, click New > HTTP Request
4. Each API request needs a URL. URL will typically be the base location plus path. Path is the endpoint of that request URL. Along with the URL, the type of request should also be selected.
   
   

   Figure: Generate user authentication token using Postman
   
   

5. Headers are used to specify some additional information on the request being sent. In the below screenshot, Content-tye: application/json means that the request body is in json format.
   
   

   Figure: Add Content type in postman

   Note

   The request parameters are sent as a part of Request body. Typically if body parameters re being sent, make sure that the headers are also being sent for the API to process the data correctly.

   Enter the following URL and request body to generate the user authentication token.

URL: <http://localhost/summit.api.orchestration>/api/account/generatetoken

Method type: POST

Content-type: application/json

Request: {"UserName":"<fredrick.norton@zacme.com>","Password":"test@123"}

Response: 
"ayJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IlJhbWVzaCBLdW1hciBDaGlubmFtYW5pY2thbSIsInBhcmFtIjoia21XampKNU5Vejl1UyUyYnJIOXE4azE1TlBqWmJsOFolMmJEOVVwNEt5clREUGxWWEt2bDVaOUlNbjVxY3BIUHpUTWk4UGtBVzMwVndYZW9CJTJmRjJoaXJHUjI2V09CTmVxV1cydWZLZFZyWW5UN1F0S3FaRW5tYXpEODVIU1pVUW4yZ3N2ekI4aXM5NCUyYjY2YmdhYUVOdmI5dUMxeDhJUU1MVVU1bFBBZGVrRjA3V1UlM2QiLCJuYmYiOjE2NDk3NjI5NDYsImV4cCI6MTY4MTM4NTM0NiwIaWF0IjoxNjQ5NzYyOTQ2fQ.V-Tj8LiXrmzXAJ69Ujg96_tfcw1nrW2UN8GhiHCuIzo"

Figure: Sample Postman screenshot where user authentication token is generated.

3.Trigger the API Workflow using below end point in Postman

The Workflow Name is passed as an input in this step to trigger the Workflow. Workflow ID can also be used but this information must be retrieved from Database. If both are specified, then workflow is triggered by Workflow ID.

In Postman, specify the below URL (change base URL) and request to trigger the workflow.

In Request inputs, specify the parameters which are mapped to “API” as data source in Workflow    configuration.

Example: append or replace API URL.

URL: <http://localhost/summit.api.orchestration>/api/serviceautomation/triggerworkflow

Method Type: POST

Headers:  Add following  key

KEY: token, VALUE : Enter the user authentication token generated in Step 2

Content-type: application/json

{
    "workflowID": "89C45920-936C-48FF-830B-E151A4291E70",
    "workflowName": "Employee On-boarding",
    "description":"",
    "workflowInputs": [
        {
            "parameter": " FirstName",
            "datatype": "string",
            "value": "Fredrick"
        },
        {
            "parameter": "lastName",
            "datatype": "string",
            "value": "Norton"
        },
        {
            "parameter": "doj",
            "datatype": "datetime",
            "value": "2022-01-01 10:10"
        },
        {
            "parameter": "experience",
            "datatype": "number",
            "value": "10"
        },
    ]
}

Request Parameters

Response
{
    "APITriggerRID": 1,
    "StatusCode": 200,
    "MessageType": "Success",
    "Message": "Successfully processed and sent to queue."
}

4.Retrieve the status of the API Trigger which includes Linking Status and Execution Status

In this step it is possible to retrieve and verify the Linking status(API Request is attached with specified Workflow) and execution status of the Workflow by passing the below API Request.

URL: http://localhost/summit.api.orchestration/api/serviceautomation/triggerstatus

Method Type: POST

Headers:  Add following key

      KEY: token, VALUE : Enter the user authentication token generated in Step 2

Content-type: application/json

Request:
{"APITriggerRID":"1","WorkflowID":"59C22838-5CD2-4F32-B2C0-7EFF648D7FC2"}

Request Parameters

Response:
{
    "Data": {
        "APIReferenceID": 182,
        "WorkflowName": "First API Trigger",
        "RequestReceived": "2022-04-27T18:57:59.913",
        "CurrentLinkingStatus": "Completed : Sent to Execution Queue",
        "LastUpdated": "2022-04-27T18:58:06.36",
        "CurrentExecutionStatus": "Failure",
        "ExecutionReceived": "2022-04-27T18:58:06.36",
        "ExecutionCompleted": "2022-04-27T19:19:13.467"
    },
    "Message": "Successfully Loaded",
    "MessageType": "Success",
    "StatusCode": 200
}

Response  Parameters

Event Linking Service receives the API Trigger details, process the Request, link to the triggered workflow, and save the Script, Target CI and Parameter details in the Execution Queue. Execution Service reads the same from the queue and executes the scripts on the target machine and updates the output and status in Orchestration queue.

5. API request to retrieve Workflow Execution Status and Output based on API Reference ID and Module ID

We can perform the verification of Workflow Execution Status and Output based on API Reference ID and Module ID. This is possible through Orchestration application UI and API request too.

To verify through Orchestration application:

1. Navigate to Admin > Automation > Orchestration
2. In the Orchestration application, Navigate to Orchestration Workflows.
3. Select the saved Orchestration Workflow > Action > Click Execution History.
   
   

   Figure: Execution History in Orchestration Workflow

   The field Ticket ID is renamed to Ticket ID/ Ref ID in the Orchestration Workflows.

   
   Figure: Execution History 
   

   To verify through API Request:

   The Workflow execution output and status can be verified through the following API request. This is an existing API request but in the Request parameters the value for Module is set to API for this feature.

    URL: http://localhost/summit.api.orchestration/api/report/ticket/workflowdetails

   Method Type: POST

   Headers:  Add following key

   KEY: token, VALUE : Enter the user authentication token generated in Step 2

   Content-type: application/json

Request:
{"Module":"API","TicketID":"182"}

Request Parameters

Response:

The Response consists of the Workflow that is referenced by the Request parameter. A sample Response is given below.

{
    "WorkflowOutputList": [
        {
            "QueueRID": 2516,
            "WorkflowID": "59C22838-5CD2-4F32-B2C0-7EFF648D7FC2",
            "WorkflowName": "First API Trigger",
            "WorkflowStatus": "Failure",
            "CreatedDate": "2022-04-27 18:58:06",
            "CompletedDate": "2022-04-27 19:19:13"
        }
    ],
    "ActionOutputList": [
        {
            "RefQueueRID": 2516,
            "ActionRID": 2760,
            "ScriptName": "Script 2",
            "Status": "Failure",
            "CreatedDate": "2022-04-27 18:58:06",
            "ExecutedDate": "2022-04-27 19:19:13",
            "Output": "",
            "Message": "Target not found",
            "IPAddress": null,
            "TargetID": 0
        }
    ],
    "TargetOutputList": [
        {
            "RefQueueRID": 0,
            "ActionRID": 2760,
            "ScriptName": "Script 2",
            "Status": "Failure",
            "CreatedDate": null,
            "ExecutedDate": "2022-04-27 19:19:13",
            "Output": "",
            "Message": "Target not found",
            "IPAddress": "192.168.50.107",
            "TargetID": 0
        }
    ],
    "ParameterDetailsList": [
        {
            "RefActionsRID": 2760,
            "ParameterName": "Input1",
            "ParameterValue": "Fredrick"
        }
    ],
    "OutputVariablesList": [
        {
            "RefActionsRID": 2760,
            "VariableName": "EO",
            "VariableValue": ""
        }
    ]
}

Response Parameters