Mapping

Mapping defines how the Java Gateway for BMC Remedy ARS maps fields in ObjectServer tables to fields in a BMC Remedy ARS request. The mapping is used during replication of ObjectServer to BMC Remedy ARS data.

The map definition file

The mapping of fields in ObjectServer tables to fields in a BMC Remedy ARS request is defined in the map definition file. The gateway is supplied with a map definition file named bmc_remedy.map in the directory $OMNIHOME/gates/bmc_remedy. You can modify this file to tailor the data mapping to suit your environment.

The map definition file contains a number of CREATE MAPPING commands each of which maps specific ObjectServer table fields to fields in a BMC Remedy ARS request.

The information that follows describes the bmc_remedy.map definition file. See the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide for more information, including information on the structure of the map definition file, the CREATE MAPPING command, and the optional CREATE MAPPING command clauses.

DEDUPLICATION

Deduplication is a mechanism by which the gateway reduces the amount of redundant updates sent to BMC Remedy ARS.

The gateway computes a cryptographic hash (SHA1) based on fields selected for deduplication in the specified map, and stores the resulting hash in the history of the alert in the gateway cache. If subsequent data results in a hash already stored in the alert history, the gateway drops this data because it existed in the hash.

The gateway maintains the main alert values (values from alerts.status) as a current hash, with no other history maintained.

The gateway maintains alert journals and details (from alerts.journal and alerts.details respectively) as a history, with multiple hashes per alert. This allows the gateway to record multiple journals and details for each alert.

Note: Without a DEDUPLICATE clause, all fields in a map are considered for deduplication purposes. The DEDUPLICATE clause specifies the fields to be included in the row hash used for deduplication in the specified map. Conversely, the DO NOT DEDUPLICATE clause means ignore the listed fields when computing the row hash used for deduplication.

See Explanation of the StatusMap for an example of how to use the DEDUPLICATE clause.

The CREATE MAPPING command

The CREATE MAPPING command creates a map that defines how the gateway maps fields in ObjectServer tables to fields in a BMC Remedy ARS request. The CREATE MAPPING command has the following syntax:

CREATE MAPPING mappingname
(
'ArsFieldId' = 'value' [ ON INSERT ONLY ] [ CONVERT TO type ]
[ , 'ARSFieldId' = 'value' [ ON INSERT ONLY ] [ CONVERT TO type ] ]...
) ;

where:

mappingname specifies the name of the map to be created for a specific mapping of ObjectServer table fields to fields in a BMC Remedy ARS request.
'ArsFieldId' specifies the integer field ID for the destination field in the BMC Remedy ARS request.
Note: Non-integer field IDs, such as Chrono and UID in the journal map, are used to include the corresponding ObjectServer alerts fields in the deduplication. ObjectServer alerts fields that do not resolve to BMC Remedy ARS field IDs are dropped by the gateway.
value specifies the name of a field in the ObjectServer table.

Note: It is assumed that you are familiar with the fields in the ObjectServer tables and the corresponding fields in a BMC Remedy ARS request.

At a minimum, the gateway must pass across the @Serial and @Severity fields to BMC Remedy ARS in order for the replication to take place.

The optional ON INSERT ONLY controls the updating of the BMC Remedy ARS field during the life of its associated ObjectServer alert; when omitted, the BMC Remedy ARS field is updated for any change in the state of the alert. When included, the BMC Remedy ARS field is only set when the alert is created.

The optional CONVERT TO type allows the mapping to define a forced conversion for situations where a source field may not match the type of the destination field. The type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string, or date type.

Default maps supplied with the map definition file

The bmc_remedy.map definition file delivered with the gateway contains the following default maps:

StatusMap - Is the map for alerts.status entries, and maps Tivoli Netcool/OMNIbus alert fields to their corresponding BMC Remedy ARS request fields.
JournalMap - Contains the mapping from alerts.journal journal entries to BMC Remedy ARS diary fields. By default, only a single diary field is set, which appends the journal text to a BMC Remedy ARS diary field. The JournalMap also contains meta-data fields for the journal entry (user and timestamp of the journal entry in Tivoli Netcool/OMNIbus) for the purpose of deduplication.
DetailsMap - Contains the mapping of alert details from the fields in the alerts.details table to BMC Remedy ARS request fields. By default, adds an entry to the same BMC Remedy ARS diary field as journals, with an entry per name/value pair in the details for an alert.

Note: The mapping file (bmc_remedy.map) defines the maps, but does not determine whether the maps are used. You specify which maps to use in the table replication definition file (bmc_remedy.rdrwtr.tblrep.def).

See Table Replication for more information.

Explanation of the StatusMap

The StatusMap is one of the maps contained in the bmc_remedy.map delivered with the gateway. As discussed previously, the StatusMap is the main map for alerts.status entries, and maps Tivoli Netcool/OMNIbus alert fields to their corresponding BMC Remedy ARS request fields. The StatusMap is defined as follows:

CREATE MAPPING StatusMap  1 
(
        '536870914' = '@Identifier'       ON INSERT ONLY, 2 
        '536870913' = '@Serial'           ON INSERT ONLY,
        '536870944' = '@Node'             ON INSERT ONLY,
        '536870915' = '@NodeAlias'        ON INSERT ONLY,
        '536870932' = '@Manager'          ON INSERT ONLY,
        '536870939' = '@Agent'            ON INSERT ONLY,
        '536870918' = '@AlertGroup'       ON INSERT ONLY,
        '536870931' = '@AlertKey'         ON INSERT ONLY,
                '7' = '@Severity',  3 
        '536870916' = '@Summary'          ON INSERT ONLY,
        '536870946' = '@StateChange',  3 
        '536870912' = '@FirstOccurrence'  ON INSERT ONLY,
        '536870917' = '@LastOccurrence',
        '536870935' = '@InternalLast',  3 
        '536870938' = '@Poll'             ON INSERT ONLY,
        '536870941' = '@Type'             ON INSERT ONLY,
        '536870940' = '@Tally',  3 
        '536870945' = '@Class'            ON INSERT ONLY,
        '536870942' = '@Grade'            ON INSERT ONLY,
        '536870934' = '@Location'         ON INSERT ONLY,
        '536870933' = '@Acknowledged',  3 
        '536870922' = '@ServerSerial'     ON INSERT ONLY,
        '536870923' = '@ServerName'       ON INSERT ONLY
) DEDUPLICATE ('7','536870917','536870940','536870933'); 4

The following list describes each of the numbered items in the StatusMap:

Uses the CREATE MAPPING command to create a map called StatusMap. As described previously, the StatusMap is the main map for alerts.status entries, and maps Tivoli Netcool/OMNIbus alert fields to their corresponding BMC Remedy ARS fields.
Maps the BMC Remedy ARS field identifier (the string value 536870914) to the ObjectServer table field called @Identifier. The BMC Remedy ARS field id is defined for the form in the provided omnibus.def file.
The string value on the left side of the expression in each mapping clause is the BMC Remedy ARS field identifier. Most fields are written to specially defined records within the BMC Remedy ARS alert form, with the exception of Severity (written to the ARS core field Status) and Summary (written to the ARS core field Summary Description).

The string value on the right side of the expression in each mapping clause refers to a field in the ObjectServer table. The string values on the right side of the expressions use the format @fieldname. For example, in this mapping clause @Identifier is used.

The use of ON INSERT ONLY instructs the gateway to set the @Identifier field only when the ObjectServer creates the corresponding alert.
These mapping clauses define fields that do not use ON INSERT ONLY. In this case, because ON INSERT ONLY is omitted, the gateway updates these fields during the life of their associated ObjectServer alerts.
The DEDUPLICATE clause specifies the fields to be included in the row hash used for deduplication. Conversely, the DO NOT DEDUPLICATE clause means ignore the listed fields when computing the row hash used for deduplication.
The StatusMap shows that the following fields are included in the row hash used for deduplication:
- BMC Remedy ARS field '7' ('@Severity')
- BMC Remedy ARS field '536870917' ('@LastOccurrence')
- BMC Remedy ARS field '536870940' ('@Tally' )
- BMC Remedy ARS field '536870933' ('@Acknowledged')
Should any of these fields change, the resulting hash will also change, and the gateway knows the update should be forwarded. If the hash remains the same, then the update has not changed any of these fields, and the update will be dropped.

Explanation of the JournalMap

The JournalMap is one of the maps contained in the bmc_remedy.map delivered with the gateway. As discussed previously, the JournalMap contains the mapping from alerts.journal journal entries to BMC Remedy ARS diary fields. The JournalMap is defined as follows:

CREATE MAPPING JournalMap  1 
(
        'UID'           = JOURNAL.UID INTERNAL ONLY, 2 
        'Chrono'        = JOURNAL.CHRONO INTERNAL ONLY, 2 
        '536870921'     = JOURNAL.TEXT  3 

);

The following list describes each of the numbered items in the JournalMap:

Uses the CREATE MAPPING command to create a map called JournalMap. As described previously, the JournalMap contains fields that are included for deduplication purposes.
Fields marked INTERNAL ONLY are not sent to BMC Remedy ARS, but included for deduplication. If not included, journal entries with the same text, but made at different times, will be deduplicated and the latter entries dropped.
Maps the BMC Remedy ARS field identifier 536870921 to the ObjectServer alerts.journal table fields Text1...Text16.

Explanation of the DetailsMap

The DetailsMap is one of the maps contained in the bmc_remedy.map definition file delivered with the gateway. As discussed previously, the DetailsMap contains the mapping of alert details from the fields in the alerts.details table to BMC Remedy ARS request fields. The DetailsMap is defined as follows:

CREATE MAPPING DetailsMap  1 
(
        '536870921'     = '@Name' + ':' + '@Detail'  2 

);

The following list describes each of the numbered items in the DetailsMap:

Uses the CREATE MAPPING command to create a map called DetailsMap.
Maps the BMC Remedy ARS field identifier (the integer value 536870921) to the ObjectServer table fields called @Name and @Detail. The BMC Remedy ARS field id is defined for the form in the provided omnibus.def file.
Note: You must uncomment the REPLICATE command clauses for the DetailsMap specified in the bmc_remedy.rdrwtr.tblrep.def file. Otherwise, the gateway ignores the DetailsMap.
See Table Replication for more information.

Specifying alternative values in the map definition file

When specifying alternative values for fields in the bmc_remedy.map file, ensure that the field does not exceed the maximum length of the target field in the BMC Remedy ARS request.

Controlling the types of data to forward in the map definition file

You can control which types of data that the gateway forwards to the BMC Remedy ARS server. For example, you might want to only create a request in BMC Remedy ARS and ignore further update and delete field activity related to that request. You can accomplish this by using the DEDUPLICATE clause. The following example shows how to specify the fields in the StatusMap to suppress all update and delete field activity after the gateway creates the request:

CREATE MAPPING StatusMap
(
.
.
.
'536870922' = '@ServerSerial',
'536870923' = '@ServerName'
) DEDUPLICATE ('536870922','536870923')

In this example, because all update and delete events will have matching values for @ServerSerial and @ServerName, they will be deduplicated with the original alert. This ensures that the gateway creates a request in BMC Remedy ARS, and all subsequent events will be dropped.