After setting up the global configuration of the Service Management Connector by changing the config.xml file, the way data is written to the service management tool can be configured.
Configuring this connection is done by modifying a mapping file. Each link, a connection between the source- and target system, is configured in one mapping file. Based on the number of links, one or more mapping files should be used.
The mapping file describes how information from the source system flows to the target system.
The name of the mapping file is specified with a path and a name in the configuration of the service, with no restrictions to file names. There is a reference in the config.xml to the mapping file.
Mapping File templates are provided for SCOM and are located in the installation folder.
The code section below shows the file structure to be used.
<?xml version="1.0" encoding="utf-8" ?>
<mappingConfiguration>
<mappings connectorId="id">
<mapping applyOnUpdate="true">
<source name="namex" type="property|query" regex="" value="property or query" />
<source name="namey" type="property|query" regex="" value="XPath query" timeZone="W. Europe Standard Time" />
<target name="Description" skipIfEmpty="true|false" regex="" value="{namex} {namey}" />
</mapping>
<mapping>
<source name="namez" type="property|query" regex="" value="property or query" />
<transform original="source value" target="target value" />
<transform regex="value1|value2" target="target value" />
<target name="ProcessingStatus" value="{namez}" />
</mapping>
</mappings>
</mappingConfiguration>
| Name | Description | Count | InnerText | Attributes |
|---|---|---|---|---|
| mappingConfiguration | Root element in the file | 1 | – timezone: the time zone where date fields should be written in. | |
| mappings | Specification of the information of connection | 1 or more | – connectorId: the id of the connection defined for this link using this mapping. | |
| mapping | Specification of the information to be added in one target field | 1 or more | – applyOnUpdate: true or false. | |
| source | Specification of the information that should be written in the target field | 1 or more | The name of an alert property or a valid XPath expression | – name – type – regex |
| target | Specification where the information should be written | 1 | Formatted string to build the information, {source name} are placeholders to specify a declared source | – name: the name of the field in the target where the information should be written – skipIfEmpty – regex |
| transform | Specification of the information that explains how to transform the source value to the target value | 1 | The transform element can handle static values or values that are the outcome from a query | – original – target – regex |
Refer to Microsoft .NET XPath Reference for more information about the XPath syntax.
| Name | Description | Type | Mandatory |
|---|---|---|---|
| connectorId | The id of the connection defined in the configuration file which should use this mapping | String | Yes |
| applyOnUpdate | This attribute defines the usage of bidirectional behavior (true = check for update on the alert/ticket, false = not used). | Boolean | No |
| name | Descriptive name of an attribute. |
String | Yes |
| type | Property: read data from the alert context. Query: read data from a named alert field |
String | Yes |
| regex | Regular expression for filtering data. This is done after the value is read. The use of regex is possible in the |
String | No |
| skipIfEmpty | Mark a target element to be skipped for processing if empty. (true = skip, false = process). Default value is false |
Boolean | No |
| original | This is the original value of the source application which is described in the element line above | String | No |
| target | Fill in the value that corresponds with the targetted application value in the element line below | String | No |
| timezone | The name of the Time Zone where date time fields should be converted to. Value is specified in english. By default all date time information is in UTC timezone. It can be configured on the folowing element: |
String | No |
Refer to Default Time Zones for a list of valid timezone names.
As mentioned above, in the mapping file the source- and target property fields are specified. The connector service reads a specific set of SCOM alert property fields and stores them in a Connector alert field. In addition all SCOM alert properties are consolidated in an XML structure are stored as well.
Please read Connector Alert Field for information about SCOM alert property fields.
In this mapping file examples SCOM alert properties are used.
An example of how to compose the description field in a service management tool. The connector alert fields Name and Path are used. In the XML target name attribute called description, the value of both source elements, AlertTime, AlertName and AlertPath will be stored separated by a colon and a space. The AlertTime is converted to the West Europe Standard time zone.
<mapping>
<source name="AlertTime" type="property" value="CreationDate" timeZone="W. Europe Standard Time"/>
<source name="AlertName" type="property" value="Name" />
<source name="AlertPath" type="property" value="Path" />
<target name="Description" value="{AlertTime}: {AlertName}: {AlertPath}" />
</mapping>
In this sample the value of the source attribute name ObjectID is stored in the service management target attribute called Object.Name. The query //MonitoringObjectPath filters the connector alert field Context so only the value of MonitoringObjectPath is used. skipIfEmpty=”true” can be used to skip the target field if it is empty. true/false should be in lower case.
<mapping>
<source name="ObjectID" type="query" value="//MonitoringObjectPath" />
<target name="Object.Name" skipIfEmpty="true" value="{ObjectID}" />
</mapping>
In the next sample a static value is stored in the service management target name attribute called status.
<mapping>
<target name="Status" value="SecondLine" />
</mapping>
The last sample shows how to use the transform element. It is used for transforming a source value to a target value. The goal in this example is, when an Alert is closed, to set the linked TOPdesk ticket to the ready status. In SCOM the closed state has resolution state 255. In TOPdesk the ready status in this example has 123456789. If the resolution state is not 255, then the regex is verified and the corresponding target status is used. In this example 987654321. The first transform that matches the condition is used.
<mapping applyOnUpdate="true">
<source name="TicketState" type="query" value="//ResolutionState" >
<transform original="255" target="123456789" />
<transform regex="[0-9]+" target="987654321" />
</source>
<target name="ProcessingStatus.Id" skipIfEmpty="true" value="{TicketState}" />
</mapping>
All samples together will configure 3 mappings and should look like this.
<?xml version="1.0" encoding="utf-8" ?>
<mappingConfiguration>
<!-- SCOM to TOPdesk -->
<mappings connectorId="2">
<mapping>
<source name="AlertTime" type="property" value="CreationDate" timeZone="W. Europe Standard Time"/>
<source name="AlertName" type="property" value="Name" />
<source name="AlertPath" type="property" value="Path" />
<target name="Description" value="{AlertTime}: {AlertName}: {AlertPath}" />
</mapping>
<mapping>
<source name="ObjectID" type="query" value="//MonitoringObjectPath" />
<target name="Object.Name" skipIfEmpty="true" value="{ObjectID}" />
</mapping>
<mapping>
<target name="Status" value="SecondLine" />
</mapping>
<mapping applyOnUpdate="true">
<source name="TicketState" type="query" value="//ResolutionState" >
<transform original="255" target="123456789" />
</source>
<target name="ProcessingStatus.Id" skipIfEmpty="true" value="{TicketState}" />
</mapping>
</mappings>
</mappingConfiguration>
