API Triggers for Workflows in Service Automation

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

Note

A new option API is introduced in the drop-down field of Module, Tenant, Trigger Event, and Filters section.

Figure: New Drop-down value API

3. In the WORKFLOW CONFIGURATION pop-up. Enter Workflow Name, Workflow Category and 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.

   Note

   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.

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 part of Request body. Typically if body parameters are being sent, make sure that headers are also being sent for API to process 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"

   Note

   This token is used in other API calls for authentication. Keep this handy.

   

   Figure: Sample Postman screenshot where user authentication token is generated

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."
}

Note

Value of APITriggerRID in the response is used as Reference ID to track the status of the API trigger. Keep it handy.

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.

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

   Parameter Name	Type	Description	Mandatory
   Module	String	As the Trigger type is API for this feature. Module value is API.	True
   TicketID	Integer	The value is API Reference ID received in previous step.	True

   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

   Parameter Name	Type	Description
   WorkflowOutputList	JSON Array	Provides details about Workflow name, Execution status and Execution completed time.
   ActionOutputList	JSON Array	Provides details about the list of scripts executed in the Workflow with its Execution Status, output and execution date.
   TargetOutputList	JSON Array	Provides details about the Target CI details where script is executed.
   ParameterDetailsList	JSON Array	Provides details about the parameter name, values passed as input to the script.
   OutputVariablesList	JSON Array	Provides details about the list of output variables and its values.

Note

The following changes are made to the Automation Dashboard screen.

Automation Dashboard

Figure: API option is added for drop-down Module and Tenant drop-down

Automation Dashboard - Live Feed

Figure: Ticket ID is renamed to Ticket ID/Ref ID in Automation Dashboard Live feed