References

Mapping File

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.

File name

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.

File structure

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>

Explanation of elements

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.

Explanation of attributes

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.
Name of the field in the monitoring application where the information should be read from.
Name of the field in the target system where the information should be written.
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 , and element
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.

Source property fields

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.

Mapping file example – SCOM

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>

Meer weten?

Neem vrijblijvend contact op en vraag naar de mogelijkheden.

Copyright © TheBackbone | Part of INVINITIV