Mapping Data

Configuration Structure 

An integration is a connection of two systems, and each connected system is defined by a target in the Clip configuration. Underneath the target XMl element, there is a create as well as an update element which defines how an artifact of the system should be created or updated, respectively. The name of the element is specific to the system, e.g. <createCherwell/> and <updateCherwell/>. Underneath the create and update element, a list of fields or attributes defines which fields should be created or updated, and with which data ( set value ). The general structure of a field definition includes

• name : the name of the field
• expressionlist : the optional expressionlist allows to evaluate additional "helper" variables which can be used in the default and conditions element
• default : the optional default value which will be applied if no conditionlist is present or no condition matches
• conditionlist : the optional conditionlist allows to evaluate a "set value" dependent on variables

A "set value" can include static text as well as variables. A variable is written in square brackets ("[]") and refers to data of the peer target. As an example, the field definition below in the create element of a Cherwell target maps the severity and the title into the "ShortDescription" field per default - severity and title are variables that refer to an event of the peer target, an Operations Bridge system:

<!-- a field definition for the "Short description" field with a default value, showing the category, if present-->
<field name="ShortDescription">
	<default>[severity]: [title]</default> 
</field>

Conditions and Condition Lists

Very often, attributes of a source event are supposed to be mapped to an attribute of a destination incident or vice versa. For example, the severity of an event should be mapped to an incident's impact or urgency, or a state of an event should be mapped to an according incident state. Besides, automatic closure of an incident may be desired only in cases when an incident is not currently assigned and work is in progress – all this is accomplished by means of conditions and condition lists.
A single condition evaluates to either "true" or "false", and can optionally provide a result. Basically, a given value is compared against a compare value by a given "compare function". Compare functions in CLIP include:

• "equals" : the condition evaluates to "true" if the value is identical to the compare value
• "notEquals" : the condition evaluates to "true" if the value is different than the compare value
• "startsWith" : the condition evaluates to "true" if the value string starts with the compare value as prefix
• "endsWith" : the condition evaluates to "true" if the value string ends with the compare value as postfix
• "isEmpty" : the condition evaluates to "true" if the value string is empty
• "notEmpty" : the condition evaluates to "true" if the value string is not empty
• "matches" : the condition evaluates to "true" if the value string matches the compare value, CLIP uses Java regular expression syntax

Clip uses <conditionlists/> to provide conditional mapping capabilities, here is an example:

<field name="severity">  <!--  Severity: 1 - Critical, 2 - Major, 3 - Minor, 4 - Warning, 5 - Info -->
	<default>3</default>
	<conditionlist pattern="[severity]">
			<condition compareValue="normal"   compareFunction="equals">5</condition>
			<condition compareValue="warning"  compareFunction="equals">4</condition>
			<condition compareValue="minor"    compareFunction="equals">3</condition>
			<condition compareValue="major"    compareFunction="equals">2</condition>
			<condition compareValue="critical" compareFunction="equals">1</condition>
	</conditionlist>
</field>

First, the pattern in the <conditionlist/> tag is resolved by CLIP so all variables in the pattern are resolved before evaluation, in this example, the current event severity replaces the variable \[severity\]. Then, the conditions are evaluated in order until the first one matches, and this one gives the result of the evaluation. In the example above, an event with severity "major" would match the fourth condition and have a result value of "2" for the given conditionlist.

Conditionlists in the <conditionlist/> tag are evaluated until the first match and provide a return value – if no condition matches, CLIP provides the possibility to provide default values:

			<attribute name="CA" key="ServiceNow Assignment">
				<default>Assigned group : [assignment_group], Assigned to : [assigned_to]</default>
				<conditionlist pattern="[assignment_group]::[assigned_to]">
					<condition compareFunction="equals" compareValue="::">No assignment yet.</condition>
					<condition compareFunction="endsWith" compareValue="::">Assigned Group : [assignment_group], nobody assigned yet.</condition>
					<condition compareFunction="startsWith" compareValue="::">No Assigned group, Assigned to : [assigned_to]</condition>
				</conditionlist>
			</attribute>

In this example, the OMi custom attribute „ServiceNow Assignment" results in a string to show the assignment group and assignee, but one of these two values are missing, one of the conditions in the conditionlist matches to result in a customized string. In this <conditionlist/> example, the same pattern applies to all conditions, but the pattern can also be defined on the "condition level" individually so it overrides the pattern in the <conditionlist/> pattern attribute.

In contrast to the <conditionlist/> tag, the <conditions/> tag is used in <suppress/> and <attach/> sections, it does not provide a result value and ALL conditions contained in this tag must evaluate to "true" so the whole <conditions/> tag evaluates to "true": 

				<conditions>
					<condition pattern="[severity]"  compareFunction="equals" compareValue="normal"/>
					<condition pattern="[control_transferred_to.ruleName]"  compareFunction="matches" compareValue=".*manual.*"/>
				</conditions>

Each condition in this example has its individual pattern.

Expressions

This optional section allows you to manipulate source data or to define additional variables that you could use later in the field mappings, conditions or even other expressions following its definition in the expression list. The name of the new variable is specified in the "name" attribute of an expression. There are different types of expressions available for selection, all of them take a source and evaluate a value according to its type ( or more values for the type "pattern" ).

toUpperCase

toLowerCase

firstNCharacters

lastNCharacters

pattern

The following code block illustrates some use cases for expressions, please note that expressions are defined in the source target right before the create/update section, and the variables defined can then be used in the destination target:

• the "severity" of a source event is capitalized and store in a  defined in an MF OBM target new variable "severityUC", e.g. "critical" will be converted to "CRITICAL"
• the result of the first expression is further processed and its first three characters stored in "severityUC3"
• the "title" of a source event is applied to a regExp pattern that removes information about the "Policy" is removed from it ( replaced with an empty string )
• the result of the last expression available in variable "titleNoPolicy" is further cut to 20 characters
• the field's default value is defined by using two expression variables
• the variable "timeChangedInMS" obtains its value from an expression of type "dateTimeStringToMS". It converts the "timeChanged" attribute from the OBM event, e.g.  "06/27/2022 18:32:43" (local time) and parses it according to the given pattern "MM/dd/yyyy HH:mm:ss". As a result, the new variable "timeChangedInMS" would be set to 1656347458000. To test the parse pattern, please visit https://javadevtools.com/datetimeformatterparse.
• the variable "timeChangedStringFromMS" obtains its value from an expression of type "dateTimeInMStoString" It converts a date/timestamp in milliseconds from another expression variable "timeChangedInMS" according to the given pattern "LLLL dd,yyyy hh:mm:ss a zzz". As a result, the new variable "timeChangedStringFromMS" would be set to "Juni 27,2022 06:30:58 nachm. MESZ". To test the format pattern, please visit https://javadevtools.com/datetimeformatter .

...
  <expressions>
	<toUpperCase          name="severityUC"              source="[severity]"  />
	<firstNCharacters     name="severityUC3"             source="[severityUC]" count="3"  />
   	<replaceAll           name="titleNoPolicy"           source="[title]" pattern="\[Policy:.+\]" to="" />
	<pattern              name="title20"                 source="[titleNoPolicy]" pattern="(.{1,20})" />
	<dateTimeStringToMS   name="timeChangedInMS"         source="[timeChanged]" pattern="MM/dd/yyyy HH:mm:ss" /> 
	<dateTimeInMStoString name="timeChangedStringFromMS" source="[timeChangedInMS]" pattern="LLLL dd,yyyy hh:mm:ss a zzz" />  
  </expressions>

  <updateOMi>
...