Triggers
  • 18 Oct 2024
  • Dark
    Light
  • PDF

Triggers

  • Dark
    Light
  • PDF

Article summary

Triggers enable you to run automations in four different ways, each described in the table below. You can assign as many triggers as you like to an automation and have more than one of each type. You can find more details about each trigger type in the sections that follow.

Trigger Types

Functional details about each trigger type are presented in the table below.

Trigger Type Function
Manual Runs the automation manually (user invoked). A JSON Form providing additional runtime data may optionally be assigned to the trigger.
API Endpoint Runs the automation from a unique endpoint using an HTTP POST call, optionally using the request body of the HTTP POST call as the assigned workflow's input.
Schedule Runs the automation at some point in the future at an optional repeating frequency. Also includes an optionally assigned JSON Form.
Event Runs the automation when a system event occurs.

Workflows initiated by triggers will mention Operations Manager in the job description.

Figure 1: Operations Manager in Job Description

12_triggers_job_manager3


Creating and Editing Triggers

To create a trigger:

  1. Click the Create Trigger button (plus "+" sign) in the Triggers toolbar on the Automation Details page; the Create Trigger panel will appear on the left.
  2. Enter a name for the trigger.
  3. Enter a brief description for the trigger, if desired.
  4. Use the Type dropdown to select the trigger type you want to create.
  5. Complete the appropriate fields for the trigger type that was selected. More detail on each trigger type is presented below.
  6. Click the Save Changes button at the bottom-left of the Create Trigger panel to save the trigger.

You can edit existing triggers from the Trigger Cards UI by clicking on the trigger name at the top of a card.

Manual Triggers

Manual triggers run the related automation only when invoked by the user. A JSON Form may optionally be assigned to the trigger, providing runtime data to the underlying workflow.

Figure 2: Create Manual Trigger

01_create_manual_trigger_23.2

Label UI Element Function
1 Name Add or change the trigger name.
2 Description Optional. Add or change a description for the trigger.
3 Type Dropdown menu to select or change the type of trigger to create.
4 Form Optional. Dropdown menu to select the JSON Form to run the assigned workflow with.
5 Create New Form Click the plus (+) sign icon to open the Automation Studio create modal in a new tab to create a new JSON Form.
6 Legacy Workflow Compatibility Make the trigger compatible with workflows created using legacy versions of IAP (< 2023.2).
7 Form Data View and edit the contents of the selected JSON Form.
8 Save Changes Save the trigger and, if applicable, any assigned JSON Form data and its inputs.

Running Automations from Manual Triggers

To run an automation with a manual trigger:

  1. Click the Run Now button at the top of the Automation Properties panel; the Run Automation panel will display.
  2. Use the dropdown to select the manual trigger that will run the automation.
  3. Optionally, edit the trigger's JSON Form data.
  4. Click the Run Now button at the bottom-left corner of the Run Automation panel.

Figure 3: Run Automation Panel

Run Automation Panel

API Endpoint Triggers

API endpoint triggers run the automation they are assigned to whenever the API endpoint they are configured to listen on receives an HTTP POST request. When an API endpoint associated with an API endpoint trigger receives an HTTP POST request:

  • The body of the HTTP POST request (represented as a JSON object) is validated against the POST body schema defined in the API endpoint trigger.
  • If the body of the HTTP POST request is validated, it is sent to an optional JST defined in the API endpoint trigger.
  • After the JST is applied (if relevant), the keys and values of the HTTP POST request body are made available to the workflow and the automation is run.
  • The API endpoint that triggered the automation will respond to the client with information about the workflow that was started.
Note:

If you wish to use keys and values from the body of the HTTP POST request in a workflow, you must reference them as job variables within the workflow itself. See Variables for further information.


Each API trigger requires a unique route name. URLs for endpoint triggers use the following format:

/operations-manager/triggers/endpoint/:routeName


Figure 4: Create API Endpoint Trigger

15_create_api_trigger_22.1

Label UI Element Function
1 Name Add or change the trigger name.
2 Description Optional. Add or change a description for the trigger.
3 Type Dropdown menu to select or change the type of trigger to create.
4 Action The HTTP type will always be POST.
5 Route Required. The unique route name for the endpoint.
6 JST (Optional) Select the JST to transform the HTTP POST request body to the input schema of the assigned workflow.
7 POST Body Schema The JSON schema the HTTP POST request body must match.
8 Save Changes Button to retain changes and save the trigger.

POST Body Schema

The POST body schema is a JSON schema against which the body of the HTTP POST request is validated. If the HTTP POST request body is validated, the API trigger continues its preparations to run the automation. If the HTTP POST request body is not validated, the automation is not run.

The POST body schema uses the following syntax:

{
    "type": "object",
    "properties": {},
    "additionalProperties": true
}
Property Description
type Refers to the HTTP POST request body, which is represented as a JSON object.
properties This is where the variables the HTTP POST request body should be validated against are defined.
additionalProperties Allows variables not defined in the properties key of the POST body schema to be present in the HTTP POST request body without affecting validation. Default is true.

Example

The following example outlines how to trigger a Velocloud Edge Provisioning Automation using an API Endpoint Trigger.

Create API Endpoint Trigger

Create an API Endpoint Trigger with the following:

  • Endpoint - Use the following endpoint to trigger the automation. As a suggestion, use Postman to view your data.

    https://example.iap-prod.itential.io/operations-manager/triggers/endpoint/velocloud-edge-provisioning-v2
    

  • Authentication – IAP uses a token for API calls, and the token is passed to the endpoint via the token query parameter. In on-premises IAP environments, this token can be retrieved by making a call to the login endpoint. Refer to the API documentation for additional reference. For SaaS customers with Itential Cloud environments, it is provided by the Product Support Team.

    https://example.iap-prod.itential.io/operations-manager/triggers/endpoint/velocloud-edge-provisioning-v2?token={{IAP-static-token}}
    

  • Payload Body – The values in the payload body are used by the automation for edge provisioning in Velocloud.

    {
        "iapPayload": {
            "disableGe3InterfaceWanOverlay": true,
            "vco": "vco109-usca1",
            "enterpriseId": "935",
            "configurationId": "12285",
            "name": "sampleEdge",
            "vpcCidr": "10.100.100.0/22",
            "publicSubnetCidr": "10.100.101.0/24",
            "privateSubnetCidr": "10.100.102.0/24",
            "managementIp": "10.100.101.10/32",
            "ge3Ip": "10.100.101.4/24",
            "terraformPrivateIp": "10.100.102.4",
            "availabilityZone": "us-west-2c",
            "awsAccessKey": "EXAMPLE1A6DYSQ8LXGNV",
            "awsSecretKey": "EXAMPLE+O0sVH22k6mwbHddceygaXAdx4St0k/KB"
    
        }
    
    }
    

  • Postman Call - An example of what the API call looks like in Postman is shown below.

    Figure 5: Data View in Postman
    04_create_api_trigger_23.2

Check Automation Status

Users will have to make another call to IAP to check on the status of the automation (job). When triggering automations via API, IAP will return a 200-status code if the automation was started successfully.

  • GET Call - Use the following URL in a GET call to check the job status.

    https://example.iap-prod.itential.io/operations-manager/jobs/{{job_id}}?token={{IAP-static-token}}&include=status
    

    Figure 6: Checking the Automation Status
    05_api_trigger_status_23.2


  • Response Body - The job_id value can be found in the response body of the POST call ( _id) used to start the automation. See below for an example of this response and where to get the job_id.


    Figure 7: Locating the Job ID
    06_api_trigger_job_id_23.2


  • Response Status - The response from the GET job status call should look like the example below. The "status" field indicates if the job is still running or complete.

    {
        "message": "Successfully retrieved item",
        "data": {
            "_id": "847a683ac25a486e99f04fe3",
            "status": "complete"
        },
        "metadata": {}
    }
    }
    

Note:

Operations Manager API Triggers are intended to cause the start of an automation job. For this reason, the only appropriate HTTP verb supported by the application is POST. HTTP verbs are used to denote the impact the request has on the target resource. In the case of Operations Manager, the target resource is the referenced API Trigger itself. Supporting other HTTP verbs, such as DELETE, would imply that an API trigger is being deleted rather than implying that the API triggers an automation whose purpose is to delete some configuration from an external service or device.

Additional Resource

For more information related to API Triggers, watch this Itential Learn video on How to Create API Triggers, Define & Map Job Variables in IAP.

Schedule Triggers

Schedule triggers run the automation at some point in the future at an optional repeating frequency.

Note:

The Start time selected in the Create Trigger panel and shown in the trigger card after saving is based on the user's current time and date.


Figure 8: Create Schedule Trigger

02_create_schedule_trigger_23.2

Label UI Element Function
1 Name Add or change the trigger name.
2 Description Optional. Add or change a description for the trigger.
3 Type Dropdown menu to select or change the type of trigger to create.
4 Start Required. Calendar icon to choose the date and time to start running the automation.
5 Repeat Every Optional. Check the Repeat checkbox and select the frequency (how often) the trigger should run the automation.
6 Process Missed Runs Required. Should a scheduled item fail to run, this option sets whether or not Operations Manager should run the most recently missed scheduled run.
7 Form Optional. Select the JSON Form to run the assigned workflow with.
8 Legacy Workflow Compatibility Make the trigger compatible with workflows created using legacy versions of IAP (< 2023.2).
9 Form Data View and edit the contents of the selected JSON Form.
10 Save Changes Save the trigger and, if applicable, any assigned JSON Form data and its inputs.

Event Triggers

Event triggers run the automation they are assigned to whenever the event they are configured to listen for occurs. When an event occurs in IAP:

  • The event system of IAP publishes an event object, which is a representation of that event as a JSON object.
  • The payload key of the event object is validated against the payload schema filter defined in the event trigger.
  • If the payload passes validation, it is extracted from the event object and sent to an optional JST defined in the event trigger.
  • After the JST is applied (if relevant), the payload is made available to the workflow and the automation is run.
Note:

If you wish to use keys and values from the payload in a workflow, you must reference them as job variables within the workflow itself.

For more information:


Figure 9: Create Event Trigger

03_create_event_trigger_23.2

Label UI Element Function
1 Name Add or change the trigger name.
2 Description Optional. Add or change a description for the trigger.
3 Type Dropdown menu to select or change the type of trigger to create.
4 Event Required. Select the event that should run the automation.
5 JST Optional. Select the JST to transform the event payload.
6 Legacy Workflow Compatibility Make the trigger compatible with workflows created using legacy versions of IAP (< 2023.2).
7 Payload Schema Filter The JSON schema the event payload must conform to.
8 Save Changes Button to retain changes and save the trigger.

Payload Schema Filter

The payload schema filter is a JSON schema against which the payload key of an event object is validated. If the payload is validated, the event trigger continues its preparations to run the automation. If the payload is not validated, the automation is not run.

The payload schema filter uses the following syntax:

{
    "type": "object",
    "properties": {},
    "additionalProperties": true
}
Property Description
type Refers to the payload key of the event object, which is itself a JSON object.
properties This is where the event variables the payload should be validated against are defined.
additionalProperties Allows variables not defined in the properties key of the payload schema filter to be present in the payload without affecting validation. Default is true.
  Warning:

It is possible to create an infinite job execution loop if an automation can activate its own event trigger. This is especially applicable when using the following events in an event trigger:

  • jobStart
  • jobCancel
  • jobError

When using an event trigger to run an automation, be sure the workflow executed by the automation cannot generate an event that will activate that event trigger.


Trigger Cards UI

You can also manage the triggers for a current automation through a collection of trigger cards on the Automation Details page. In this collection, each automation trigger is represented by a card.

Figure 10: Trigger Cards

Trigger Cards

Label UI Element Function
1 Triggers Toolbar Action icons (from left to right) to create a new trigger, run a trigger, or delete triggers.
2 Toggle Switch Enables or disables the trigger.
3 Select Trigger Checkbox to select the trigger.
4 Action Icons Used to perform operations against the trigger. The action icons available will vary depending on the trigger's type.

Trigger Card Actions

From a trigger card, you can:

  • View information about a trigger (i.e., name, type, and description).
  • Create a trigger.
  • Enable or disable a trigger.
  • Run, edit, or delete a trigger.

To enable or disable a trigger, click the toggle switch at the top-right corner of the trigger card.

  • When the toggle switch is blue and displays a check mark (✓), the trigger is enabled.
  • When the toggle switch is gray and displays a cross (X), the trigger is disabled. A disabled trigger will not run its automation.

To run or delete a trigger, click the Run (right-arrow) or Delete (trash can) button at the bottom-right corner of the trigger card, respectively.

Note:

Triggers can also be deleted in bulk. To do this, check the select box at the bottom-left corner of any trigger you wish to delete, then click the Delete button in the Triggers Toolbar.


Was this article helpful?

Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.