Triggers

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.

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

Figure 1: Operations Manager in Job Description

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

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

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.

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

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
}

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
  

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
  

  
  

• 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
  

  
  

• 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": {}
  }
  }
  

  
  

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.

Figure 8: Create Schedule Trigger

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.

For more information:

• Refer to Variable Types Used in Reference Tasks.
• Refer to Event System in the IAP Developer Guide to learn more about event objects.

Figure 9: Create Event 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
}

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