Mapping

Mapping defines how the Gateway for CEM maps fields in ObjectServer tables to fields in a CEM event. The mapping is used during replication of ObjectServer to CEM data.

The map definition file

The mapping of fields in ObjectServer tables to fields in a CEM event is defined in the map definition file. The gateway is supplied with a map definition file named cem.map in the directory $OMNIHOME/gates/cem. 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 CEM event.

The information that follows describes the cem.map 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 CEM.

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 exists in the cache.

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

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 CEM event. The CREATE MAPPING command has the following syntax:

CREATE MAPPING mappingname
(
'CEMFieldId' = 'value' [ ON INSERT ONLY ] [ CONVERT TO type ]
[ , 'CEMFieldId' = '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 CEM event.
  • 'CEMNowFieldId' specifies the destination field in the CEM event.
  • '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 CEM event.

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

The optional ON INSERT ONLY controls the updating of the CEM field during the life of its associated ObjectServer alert; when omitted, the CEM field is updated for any change in the state of the alert. When included, the CEM 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 cem.map map definition file delivered with the gateway contains the following default maps:

  • StatusMap - Is the map for the ObjectServer alerts.status table, and maps Tivoli Netcool/OMNIbus alert fields to their corresponding CEM event fields.
Note: The map definition file (cem.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 (cem.rdrwtr.tblrep.def).
See Table Replication for more information.

Explanation of the StatusMap

The StatusMap is one of the maps contained in the cem.map map definition file delivered with the gateway. As discussed previously, the StatusMap is the main map for ObjectServer alerts.status table entries, and maps Tivoli Netcool/OMNIbus alert fields to their corresponding CEM event fields. The StatusMap is defined as follows:

CREATE MAPPING StatusMap
(
    'Identifier'        = '@Identifier'       ON INSERT, UPDATE ONLY,  1 
    'Serial'            = '@Serial'           ON INSERT, UPDATE ONLY,
    'Node'              = '@Node'             ON INSERT, UPDATE ONLY,
    'NodeAlias'         = '@NodeAlias'        ON INSERT, UPDATE ONLY,
    'Manager'           = '@Manager'          ON INSERT, UPDATE ONLY,
    'Agent'             = '@Agent'            ON INSERT, UPDATE ONLY,
    'AlertGroup'        = '@AlertGroup'       ON INSERT, UPDATE ONLY,
    'AlertKey'          = '@AlertKey'         ON INSERT, UPDATE ONLY,
    'Severity'          = '@Severity'         ON INSERT, UPDATE ONLY,
    'Summary'           = '@Summary'          ON INSERT, UPDATE ONLY,
    'StateChange'       = '@StateChange'      ON INSERT, UPDATE ONLY,
    'FirstOccurrence'   = '@FirstOccurrence'  ON INSERT, UPDATE ONLY,
    'LastOccurrence'    = '@LastOccurrence'   ON INSERT, UPDATE ONLY,
    'InternalLast'      = '@InternalLast' ON INSERT, UPDATE ONLY,
    'Poll'              = '@Poll'         ON INSERT, UPDATE ONLY,
    'Type'              = '@Type'         ON INSERT, UPDATE ONLY,
    'Tally'             = '@Tally'        ON INSERT, UPDATE ONLY,
    'Class'             = '@Class'        ON INSERT, UPDATE ONLY,
    'Grade'             = '@Grade'        ON INSERT, UPDATE ONLY,
    'Location'          = '@Location'     ON INSERT, UPDATE ONLY,
    'OwnerUID'          = '@OwnerUID'     ON INSERT, UPDATE ONLY,
    'OwnerGID'          = '@OwnerGID'     ON INSERT, UPDATE ONLY,
    'Acknowledged'      = '@Acknowledged' ON INSERT, UPDATE ONLY,
    'Flash'             = '@Flash'        ON INSERT, UPDATE ONLY,
    'EventId'           = '@EventId'      ON INSERT, UPDATE ONLY,
    'ExpireTime'        = '@ExpireTime'   ON INSERT, UPDATE ONLY,
    'ProcessReq'        = '@ProcessReq'   ON INSERT, UPDATE ONLY,
    'SuppressEscl'      = '@SuppressEscl' ON INSERT, UPDATE ONLY,
    'Customer'          = '@Customer'     ON INSERT, UPDATE ONLY,
    'Service'           = '@Service'      ON INSERT, UPDATE ONLY,
    'PhysicalSlot'      = '@PhysicalSlot' ON INSERT, UPDATE ONLY,
    'PhysicalPort'      = '@PhysicalPort' ON INSERT, UPDATE ONLY,
    'PhysicalCard'      = '@PhysicalCard' ON INSERT, UPDATE ONLY,
    'TaskList'          = '@TaskList'     ON INSERT, UPDATE ONLY,
    'NmosSerial'        = '@NmosSerial'        ON INSERT, UPDATE ONLY,
    'NmosObjInst'       = '@NmosObjInst'       ON INSERT, UPDATE ONLY,
    'NmosCauseType'     = '@NmosCauseType'     ON INSERT, UPDATE ONLY,
    'NmosDomainName'    = '@NmosDomainName'    ON INSERT, UPDATE ONLY,
    'NmosEntityId'      = '@NmosEntityId'      ON INSERT, UPDATE ONLY,
    'NmosManagedStatus' = '@NmosManagedStatus' ON INSERT, UPDATE ONLY,
    'NmosEventMap'      = '@NmosEventMap'      ON INSERT, UPDATE ONLY,
    'LocalNodeAlias'    = '@LocalNodeAlias'    ON INSERT, UPDATE ONLY,
    'LocalPriObj'       = '@LocalPriObj'       ON INSERT, UPDATE ONLY,
    'LocalSecObj'       = '@LocalSecObj'       ON INSERT, UPDATE ONLY,
    'LocalRootObj'      = '@LocalRootObj'      ON INSERT, UPDATE ONLY,
    'RemoteNodeAlias'   = '@RemoteNodeAlias'   ON INSERT, UPDATE ONLY,
    'RemotePriObj'      = '@RemotePriObj'      ON INSERT, UPDATE ONLY,
    'RemoteSecObj'      = '@RemoteSecObj'      ON INSERT, UPDATE ONLY,
    'RemoteRootObj'     = '@RemoteRootObj'     ON INSERT, UPDATE ONLY,
    'X733EventType'     = '@X733EventType'     ON INSERT, UPDATE ONLY,
    'X733ProbableCause' = '@X733ProbableCause' ON INSERT, UPDATE ONLY,
    'X733SpecificProb'  = '@X733SpecificProb'  ON INSERT, UPDATE ONLY,
    'X733CorrNotif'     = '@X733CorrNotif'     ON INSERT, UPDATE ONLY,
    'ServerName'        = '@ServerName'   ON INSERT, UPDATE ONLY,
    'ServerSerial'      = '@ServerSerial' ON INSERT, UPDATE ONLY,
    'URL'               = '@URL'          ON INSERT, UPDATE ONLY,
    'ExtendedAttr'      = '@ExtendedAttr' ON INSERT, UPDATE ONLY,
    'OldRow'            = '@OldRow'       ON INSERT, UPDATE ONLY,
    'ProbeSubSecondId'  = '@ProbeSubSecondId'   ON INSERT, UPDATE ONLY,
    'BSM_Identity'      = '@BSM_Identity'       ON INSERT, UPDATE ONLY,
    'gwServerName'      = '@ServerName'          INTERNAL ONLY,
            # DO NOT UPDATE OR REMOVE
    'gwServerSerial'    = '@ServerSerial'        INTERNAL ONLY,    
            # DO NOT UPDATE OR REMOVE
    'gwSeverity'        = '@Severity'            INTERNAL ONLY,    
            # DO NOT UPDATE OR REMOVE
    'gwLastoccurrence'  = '@LastOccurrence'      INTERNAL ONLY,    
            # DO NOT UPDATE OR REMOVE
    'gwTally'           = '@Tally'               INTERNAL ONLY,    
            # DO NOT UPDATE OR REMOVE
    'gwAck'             = '@Acknowledged'        INTERNAL ONLY
) DEDUPLICATE ('gwSeverity','gwLastoccurrence','gwTally','gwAck');  2 

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

  1. Used as the identifier of the CEM event.
  2. The DEDUPLICATE clause specifies the fields to be included in the row hash used for deduplication. As specified in the DEDUPLICATE clause above, these fields are: gwSeverity, gwLastoccurrence, gwTally, and gwAck'

Specifying alternative values in the map definition file

When specifying alternative values for fields in the cem.map map definition file, ensure that the field does not exceed the maximum length of the target field in the CEM event.