API Trigger Example

Table of Contents

• API Trigger Example
  • Table of Contents
  • Overview
  • Supported IAP Versions
  • Getting Started
    • Prerequisites
    • Capabilities
    • How to Install
    • Testing
  • Using this Pre-Built
    • Running in verbose mode
    • Input Schema
    • Output Schema
  • Additional Information
    • Helpful Links

Overview

This Pre-Built consists of a Operations Manager automation that has an API Endpoint trigger. The API Endpoint trigger uses a JST to map the JSON payload inputted to the API endpoint from the client/system to the job variables required by the workflow associated with this Operations Manager automation.

Supported IAP Versions

Itential pre-builts are built and tested on particular versions of IAP. In addition, pre-builts that work with devices are often dependent on certain orchestration systems (e.g. NSO and IAG). As such, these pre-builts will have dependencies on these other systems. This version of the IAG Update Device Details pre-built has been tested with:

• IAP 2023.1.x

Getting Started

These instructions will help you get a copy of the pre-built in your IAP instance for testing in your environment. Reading this section is also helpful for deployments as it provides you with pertinent information on prerequisites and capabilities.

Prerequisites

Users must satisfy the following prerequisites to install and run this pre-built:

• Itential Automation Platform
  • ^2023.1.x

Capabilities

• Sending HTTP POST Requests to the API Endpoint.
• Validation of the API Payload against the post body schema defined in the API Trigger.
• Map the JSON payload input to the job variables required for the workflow execution.
• Select either verbose or non-verbose options in the input JSON payload for viewing the device details.

How to Install

To install the Pre-Built:

• Verify you are running a supported version of the Itential Automation Platform (IAP) as listed above in the Prerequisites section in order to install the Pre-Built.
• The Pre-Built can be installed from within App-Admin_Essential. Simply search for the name of your desired Pre-Built and click the install button (as shown below).

Testing

While Itential tests this pre-built and its capabilities, it is often the case the customer environments offer their own unique circumstances. Therefore, it is our recommendation that you deploy this pre-built into a development/testing environment in which you can test the pre-built.

Using this Pre-Built

Download the provided postman collection (Itential.postman_collection.json) and postman environment variables (Variables.postman_environment.json). Import both files into your postman application. Click on the environment dropdown in the top right to select the Variables environment. Click on the eye to configure the variables according to the environment you are using.

Using Postman to make calls to the API Endpoint:

1. Get Token: Click on the call getLoginToken. Select “send”. You will get a token returned, which will be updated as an environment variable. This token will expire after 30 minutes of inactivity. You must have this token before you can make any other postman calls to IAP.
2. POST Call: Click on the call API Trigger. Must follow the POST Body Schema defined in the API Trigger in the Operations Manager Automation [API Trigger Automation]. Select "send". The postman response viewer will show job details for the automation that was kicked off via API.

Refer to the below image for the POST Body Schema.

Running in verbose mode

During Execution In IAP, if verbose option is selected find and open the running job.

Work the manual task to view the variables sent in the API call.

Input Schema

HTTP POST request with JSON Payload. This can be sent through postman.

Example:

{
    "formData": {
        "device": [
            {
                "deviceName": "CSR123",
                "deviceType": "CSR",
                "location": "ATL",
                "isActive": true
            }
        ],
        "options": {
            "verbose": true
        }
    }
}

The following table details the property keys of the input object.

| key | type | required | description | |-------------------------------|---------|----------|--------------------| | formData.device | array | yes | list of devices | | formData.device[x].deviceName | string | yes | device name | | formData.device[x].deviceType | string | yes | device type | | formData.device[x].location | string | yes | device location | | formData.device[x].isActive | boolean | yes | device status | | options | object | yes | additional options | | options.verbose | boolean | yes | verbose |

Output Schema

Array of JSON object with the device details. This is the output of the API Trigger Workflow.

Example:

[
    {
        "deviceName": "CSR123",
        "deviceType": "CSR",
        "location": "ATL",
        "isActive": "true"
    }
]

The following table details the property keys of the output object.

| key | type | description | |----------------|--------|-----------------| | [x].deviceName | string | device name | | [x].deviceType | string | device type | | [x].location | string | device location | | [x].isActive | string | device status |

Postman Examples

Success Example

Input:

{
    "formData": {
        "device": [
            {
                "deviceName": "CSR123",
                "deviceType": "CSR",
                "location": "ATL",
                "isActive": true
            }
        ],
        "options": {
            "verbose": true
        }
    }
}

Example Postman output for successful run where the workflow is succesfully started by the API Trigger and the current job data is returned:

{
    "message": "OK",
    "data": {
        "_id": "1e7cdc34e1ed4e16b45ffcb8",
        "name": "API Trigger Workflow",
        "type": "automation",
        ...
    "metadata": {}
}

Failure Example 1

This example is missing the key formData.device[0].isActive which causes the API Trigger schema validation to throw an error.

Input:

{
    "formData": {
        "device": [
            {
                "deviceName": "CSR123",
                "deviceType": "CSR",
                "location": "ATL"
            }
        ],
        "options": {
            "verbose": true
        }
    }
}

Output:

{
    "message": "The provided POST body is not valid for this endpoint.",
    "data": null,
    "metadata": {
        "schemaErrors": [
            {
                "keyword": "required",
                "dataPath": "/formData/device/0",
                "schemaPath": "#/properties/formData/properties/device/items/required",
                "params": {
                    "missingProperty": "isActive"
                },
                "message": "should have required property 'isActive'"
            }
        ]
    }
}

Failure Example 2

HTTP POST Request to an incorrect API Endpoint.

Input:

{{pronghorn_url}}/operations-manager/triggers/endpoint/incorrect_endpoint

Output:

{
    "message": "Could not find an API Trigger defined for POST <IAP>/operations-manager/triggers/endpoint/incorrect_endpoint",
    "data": null,
    "metadata": {}
}

Additional Information

Please use your Itential Customer Success account if you need support when using this pre-built.

Helpful Links:

• Triggers and API Endpoint Triggers: https://docs.itential.com/docs/automations-3#triggers
• Postman: https://www.postman.com/downloads/
• JSON Schema Documentation: https://json-schema.org/
• JST User Guide: https://docs.itential.com/docs/jst-to...
• JST Designer Tool: http://jst-designer.itential.io/