- 18 Oct 2024
-
DarkLight
-
PDF
Triggers
- Updated on 18 Oct 2024
-
DarkLight
-
PDF
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
Creating and Editing Triggers
To create a trigger:
- 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.
- Enter a name for the trigger.
- Enter a brief description for the trigger, if desired.
- Use the Type dropdown to select the trigger type you want to create.
- Complete the appropriate fields for the trigger type that was selected. More detail on each trigger type is presented below.
- 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
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:
- Click the Run Now button at the top of the Automation Properties panel; the Run Automation panel will display.
- Use the dropdown to select the manual trigger that will run the automation.
- Optionally, edit the trigger's JSON Form data.
- 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.
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
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 thelogin
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 thejob_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": {} } }
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.
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
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.
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:
- 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
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 . |
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
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.
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.