Integration
Overview
Every integration has a configuration and business logic that defines its use case. You may integrate a particular pair of systems and entities for these systems. Each integration has one or more actions. An action consists of two configuration views called Source and Field Map, representing a set of trigger conditions (or filters), expressions, and field mapping configuration. The Integration View contains the integrated systems, the integrated entities, and the correlation settings (if any). The Action Source Tab (available after selecting an action) contains the action's general settings, like the trigger, the trigger conditions, and the expressions. The Action Field Map Tab (available after selecting an action) contains the action's field mapping configuration.
Integration View
This view contains the template's general configuration. Clicking the upper part of an Integration displays the Integration View on the right side of the screen.
Integrated Systems
An integrated system is a connected system that ZigiOps accesses to collect or insert data. The Integrated Systems component holds the configuration based on which the ZigiOps determines your integrating products. The System 1 and System 2 boxes hold the systems this integration will integrate.
Clicking on the System box displays the existing connected systems available for selection for this integration.
Integrated Entities
An integration will always collect a particular type of record from one system and create a particular type of data on the other system; we call these types of records - entities. Such entities could be ITSM records, like incidents and problems; ITOM records, like events, alerts, etc.; CMDB records, like configuration items, hosts, nodes, applications, etc. The Integrated Entities component holds the configuration based on which the ZigiOps determines the entities it will integrate for the selected integrated systems.
Clicking on the Integrated Entities box displays a list of available entities from the selected integrated system. This is how ZigiOps knows which entities an integration template integrates. If an integrated entity is missing from the list, you may need to review the integration user's permissions to connect to the corresponding system.
Correlation
The correlation is a set of rules that describes how the ZigiOps relates a pair of entities. All integrations support a one-to-one correlation type, meaning that the ZigiOps can correlate one record to another. The correlation process starts with populating the "ID" of one of the records to a field in the other record and occurs during the record creation. The field could be from the source or the target entity. Later, when the integration updates an entity, it uses the correlation configuration to look up the corresponding entity and synchronize the changes.
This component holds the configuration based on which the ZigiOps determines how to correlate the integrated entities.
Action Source View
This tab contains the action's general configuration. Clicking an action displays the Action Source View (highlighted in yellow) on the right side of the screen by default.
Action Details
This component provides helpful information for the selected action. It's located below the name of the action. The action details consist of two parts; the upper part displays details for the target entity, while the second part displays details for the source entity. Using this object allows a quick peek at the action details; the alternative is returning to the Integration View, where these details originally reside.
Hovering your mouse cursor on the action details object displays the selected integrated system, integrated entity, and the type of the action.
Clicking on the action details object displays a pop-up to manage the action details.
Trigger
This component holds the configuration based on which the ZigiOps executes an action. Two types of triggers are available, each providing a different way of triggering an action.
Polling Trigger
This trigger type makes the ZigiOps the "active" side of integration since it initiates the data collection. It's based on a scheduled interval that ZigiOps follows to collect data from the source system by querying its API. It supports customizing the scheduled interval of the action.
Listener Trigger
This trigger type registers a web server endpoint (or a web server listener) that continuously "listens" for incoming HTTP requests. This trigger type makes the ZigiOps the "passive" side of integration since it waits for incoming data. The available integration templates have a predefined configuration for the method path, port, and protocol.
For example, suppose a listener has the below configuration:
Enabling the action starts the webserver listener, and it listens for incoming data at the https://zigiops.example.com:9090/listener/omi/event endpoint and accepts POST HTTP requests.
Trigger Condition
This component serves as a filter for the data collection by setting conditions that must be met. The conditions are based on source entity attributes.
Clicking the Add new OR condition box adds a new trigger condition and displays a list of the available attributes of the source entity.
Clicking the Operator box displays a list of available operators for the condition. The available operators are: is, is not, is one of, is not one of, is empty, is not empty, contains, does not contain, less than, less than or equals, greater than, greater than, or equals.
Adding a value for the selected source entity attribute in the Value box finalizes the condition's configuration.
The component also supports building more complex conditions or combining conditions by using logical operators.
Clicking the AND button adds a new "AND" condition to an existing trigger condition. All the conditions unified under the AND operator must be met in such a case.
Clicking the OR button adds a new "OR" condition to an existing trigger condition. In such a case, the data must meet either of the conditions unified under the OR operator.
Clicking the Add new OR condition under the "OR" separator adds a new alternative condition.
In such a case, the data must meet either of the alternative conditions.
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 component allows the creation of trigger conditions based on related (or child) fields.
Expressions
The expressions are custom-defined variables that allow modifying (or manipulating) the source data and further using the result field mapping, conditional mapping, or another expression. The expressions are based on the source data, and multiple expressions are available for selection. Each type of expression allows different approaches to manipulate the source (or target) entity's data.
There’s an option to enable the Respond Expression (2) setting (disabled by default).
Build from Extract (default) → If this option is selected, the default behavior applies, and the source fields will be available for the “source” of the expression.
Build from Respond (additionally enabled) → If this option is selected, then the fields from the target system will be available for the “source” of the expression. It will be processed as part of the “respond phase” of the integration workflow.
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 transforms an epoch-formatted time into a human-readable string. For example, you could use any time/date field as a source to convert this field's value 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 were collected in a single action run and 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
The replace expression is a versatile feature designed to replace substrings or characters within the value of an input field. This functionality is particularly useful for manipulating and refining text data. The expression accommodates the Unicode U+<number> format, enabling users to input custom characters seamlessly. Importantly, the expression handles dots intelligently by escaping them, ensuring they are not treated as regular expression metacharacters. 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 a lowercase. 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 an upper-case character. For example, you could transform "as soon as possible" to "AS SOON AS POSSIBLE."
JS Mapping Script
This expression allows you to use custom JavaScript code to transform one or more objects' value(s) per your requirements. You may input multiple source fields by adding them as comma-separated values.
You should enable the expression from the General Settings page, as it's disabled by default.
Action Field Map View
This tab contains the action's field mapping configuration.
Clicking an action displays the Action Source Tab on the right side of the screen by default. Clicking the Field Map button at the screen's upper-right displays the Action Field Map Tab. You may switch between the Action Source Tab and the Action Field Map Tab from the upper-right part of the screen by clicking on the corresponding button.
Mapping
The field mapping defines how ZigiOps maps the data between the integrated entities. The mapping component allows for modifying the mapping configuration to match specific requirements.
Clicking the target field placeholder (left) shows a list of suggestions for all available target system fields.
Analogically, the source field placeholder (right) and inputting an opening curly bracket ( { ) will show a list with all available fields that you could take the value of. After selecting the desired field, the ZigiOps will automatically close the curly brackets. The object that we see in curly brackets ( {examplefield} ) is a dynamic variable that holds the value of a field from the integrated source entity.
The mapping configuration is not limited to sending only the value of a single attribute, but it also supports mapping multiple attributes and possibly combining attribute(s) with static text. For example, you could add additional source attribute(s) and some static text, as shown below. ZigiOps will send the value as a whole in such a case, and the result will be "This is an incident with high priority that affects John Doe". Clicking the Recycle Bin button deletes an entry from the mapping.
Conditions
The field map configuration supports using conditions (or conditional mappings). The conditions are based on source system fields. Adding a condition to a mapped field requires that the source record meets for the ZigiOps to process the configured mapping. If none of the conditions are met, ZigiOps will discard the field.
Clicking the Gear button displays the condition's configuration.
The configuration is separated into two sections; the condition's requirement is on the left (highlighted in red), and the value will be sent if the condition is met on the right (highlighted in blue).
The ZigiOps supports building complex conditions with logical operators, as shown below.
Condition
In this example, if the impact attribute of the source system is "1", then the integration will send "Highest" for the priority attribute of the target system.
Combination of Conditions
In this example, if the impact attribute of the source system is "1" AND the urgency attribute of the source system is "1", then the integration will send "Highest" for the priority attribute of the target system.
Alternative Conditions
The field map configuration also supports adding alternative conditions. The conditions are evaluated from top to bottom. Hence, the first condition met will report the configured value and not evaluate the rest of the conditions. ZigiOps will continue checking the next available condition if a condition is not met. If none of the conditions are met, ZigiOps will discard the field.
In the example below, if the impact attribute of the source system is "1" AND the urgency attribute of the source system is "1." The integration will send "Highest" for the priority attribute of the target system. If the impact or the urgency isn't equal to "1", the ZigiOps will continue checking the next alternative condition. Suppose the impact attribute of the source system is "2" AND the urgency attribute of the source system is "2". In that case, The integration will send "High" for the priority attribute of the target system.
Respond Field Map
The respond field map allows the definition of a predefined response back to the source system upon successfully executing an integration action. Note that not all systems support the usage of this feature.
Clicking the source field placeholder (it’s on the left for this feature) shows a list of suggestions for all available source fields.
