Each integration template consists of 2 major sections that hold the template's business logic, settings, and field mapping.

General Section

This section contains the template's general configuration divided into sub-sections, like the integrated systems, the integrated entities, and the correlation.

Integrated Systems

This sub-section allows you to select the connected systems you would like to integrate. We consider System 1 a source of the integration from where ZigiOps collects the data and System 2 as a target of the integration to where ZigiOps sends the data.

Integrated Entities

This sub-section allows you to select the entities (or types of records) that you would like to integrate, like alerts, events, incidents, tasks, bugs, or topology (configuration items) such as nodes, routers, printers, and so on.

Operations

This sub-section displays a list of all available operations in the integration template. Clicking any of the operations in this list will drill down to the corresponding operation's configuration page.

Correlation

This sub-section allows you to define unique fields from your connected systems that ZigiOps will use to correlate the integrated entities (or records), so the integration will synchronize any changes from either system with the other. For example, when ZigiOps receives an event from OBM and creates an incident in ServiceNow, it will use the event's {id} to populate the incident's {correlation_id} field. Then it will populate the event's {external_id} field with the incident's {number} field. From this point onward, ZigiOps will use these correlation details to continuously synchronize these entities (or records) whenever there is a change in either system. We recommend sticking with the default correlation configuration unless you're familiar with the specifics' integrated systems and their respective APIs.

The sub-section is divided into two parts; source and target. You could define the desired fields by writing the field's name on the left and specify the source field to take the correlation information as a variable ( {} ) on the right.

Source Section

This section is available after selecting a single operation (or action). It contains the action's general configuration divided into sub-sections, like the trigger, the trigger conditions, and the expressions.

Triggers

This sub-section allows you to choose the action's trigger, either Polling or Listener, depending on the integration.

Polling

This trigger allows you to select a scheduled interval that ZigiOps follows to collect data from the source system by querying its API.

Listener

This trigger registers a daemon that continuously "listens" for incoming data and executes the actions as soon as ZigiOps receives new data. It allows you to select the accepted method(s), set a custom URL context path, port, and protocol, like "HTTP" and "HTTPS."

The available methods are:

  • GET
  • HEAD
  • POST
  • PUT

Trigger Condition

This sub-section allows you to specify a trigger condition (or filter) that ZigiOps applies to filter the data collected from the current action source system.

You could use any available source system's fields to set conditions. For example, we've configured a single condition that requires the source record's "state" to be "resolved," i.e., ZigiOps will collect only records whose "state" is "resolved."

The available operators are:

  • is
  • is not
  • is one of
  • is not one of
  • is empty
  • contains
  • does not contain
  • less than
  • less than or equals
  • greater than
  • greater than or equals

Related Records

Some fields are nested under a parent field; hence, they're not available for direct selection, and we call them "Related Records." This sub-section allows you to create trigger conditions for such fields.

For example, the {work_notes} is a related record to the ServiceNow incident entity. This means that the related (or child) record is {work_notes} and the work note's {sys_created_on} and {sys_created_by} trigger conditions are related to the work notes and not to the incident.

Expressions

This sub-section allows you to define a variable that you could use later in the trigger conditions or the field mapping. An expression enables you to manipulate the source system's data. Note that the expressions you define are available only within the current integration template. There are multiple types of expressions that are available for selection.

Build Array

This type of expression allows you to build an array of objects by specifying a separator. For example, you could use any field as a source that will put all source values in a comma-separated array.

Date and Time Format

This type of expression allows you to transform an epoch-formatted time into a human-readable string. For example, you could use any time/date field as a source that will convert this field's value as per the selected Time Zone into a human-readable string, e.g., "25/03/2021 14:00:00."

Extract from Array

This type of expression allows you to extract objects from an array by specifying the object's index. For example, you could use any field of type "array" as a source that will extract the source field's value with index "0."

First n Characters

This type of expression allows you to extract the first "n" number of characters from a field's value. For example, you could use any field as a source to extract the first 40 characters of its value.

Last n Characters

This type of expression allows you to extract the last "n" number of characters from a field's value. For example, you could use any field as a source to extract the last 40 characters of its value.

Last Time

This type of expression allows you to store the value of any date/time field and auto-increment on each action run. For example, if two records have been collected in a single action run and they were created at 14:00 and 14:02, respectively, the expression will store "14:02" as a value.

Pattern

This expression type allows you to extract a value based on a regular expression pattern. For example, you could use this pattern "\[ERROR\]\s(.*)" to extract "This is a sample log message!" from this value "2021-02-25 10:01 [ERROR] This is a sample log message."

Replace Text

This type of expression allows you to replace a value with a predefined value. For example, you could replace the value "ASAP" with "as soon as possible."

To Lower Case

This expression allows you to transform all characters from a value to lower case characters. For example, you could transform "AS SOON AS POSSIBLE" to "as soon as possible."

To Upper Case

This expression allows you to transform all characters from a value to upper case characters. For example, you could transform "as soon as possible" to "AS SOON AS POSSIBLE."

Field Map Section

This section is available after selecting a single operation (or action). It contains the action's field mapping configuration divided into sub-sections, like the Mapping and Respond Field Map.

Mapping

The field mapping configuration allows you to map a field of the target system (on the left) to contain the value of the source system's field (on the right). Mapping a source field's value requires using {variables} (the source field in curly brackets). In the example below, you could see how the OBM event's {title} field (source) is mapped to the ServiceNow incident's {short_description} field (target). You're allowed to use hard-coded text to populate the target's fields.

Conditions

The field mapping supports the usage of conditions or conditional mapping. For example, you could set a condition on the ServiceNow incident's {impact} field, so when the OBM event's {priority} is "low", the integration will send "small" for the ServiceNow incident's {impact}. Analogically, when the OBM event's {priority} is "medium", the integration will send "wide" for the ServiceNow incident's {impact}, etc.

Multiple Conditions

The field mapping also supports the usage of logical operators (AND/OR) to create multiple conditions for a single field. For example, you could set a condition on the ServiceNow incident's {impact} field, so when the OBM event's {priority} is "low" AND the the OBM event's {severity} is "critical", the integration will send "small" for the ServiceNow incident's {impact}.