cc/td/doc/product/rtrmgmt/info_ctr/1_1
hometocprevnextglossaryfeedbacksearchhelp
PDF

Table of Contents

Using Info Gateways

Using Info Gateways

This section contains reference information about each of the Cisco Info Center Info Gateways. Each section contains all of the information you need about the Info Gateway mappings and Writer attributes.

This chapter contains the following sections:

Cisco Info Server Reader

The Cisco Info Server Reader is created and controlled by the START READER command. See Section, "START READER", in Appendix H for details of this command.

Cisco Info Server Writer

The Cisco Info Server Writer allows for the replication of alerts between Cisco Info Servers. When a route is established between an Cisco Info Server Reader and an Cisco Info Server Writer, alerts are forwarded to the destination Cisco Info Server. Changes in the Cisco Info Server that is written to, are not reflected in the Cisco Info Server being read.

Mapping

Mappings for use with the Cisco Info Server Writer must follow this syntax:

CREATE MAPPING <mappingname>
(
' <dest_fieldname>' = ('@<src_fieldname>' | integer) [ON INSERT ONLY]
[CONVERT TO type]
[, 'dest_fieldname' = ('@<src_fieldname>' | integer) [ON INSERT ONLY]
[CONVERT TO type]]...
);

Where <mappingname> is the name of the mapping to be created.

<dest_fieldname> is the integer value for the field to be written to in destination Cisco Info Server.

<src_fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

The optional ON INSERT ONLY controls the updating of the field during the life of the alert; when omitted, the field is updated for any change in the state of the alert. When included, the field is set only 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. type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string, or date type.

Note The ordering of the fields in the mapping must exactly match the ordering of the fields in the Cisco Info Server table being written to. When this is not the case, values are written to the incorrect fields.

Example

This is an example mapping file:

CREATE MAPPING SERVER_MAP
(
	'Identifier'		= '@Identifier'		ON INSERT ONLY,
	'Serial' 		= 0 		ON INSERT ONLY,
	'Node'		= '@Node' 		ON INSERT ONLY,
	'NodeAlias'		= '@NodeAlias' 		ON INSERT ONLY,
	'Manager'		= '@Manager' 		ON INSERT ONLY,
	'Agent'		= '@Agent' 		ON INSERT ONLY,
	'AlertGroup'		= '@AlertGroup' 		ON INSERT ONLY,
	'AlertKey'		= '@AlertKey' 		ON INSERT ONLY,
	'Severity'		= '@Severity',
	'Summary'		= '@Summary' 		ON INSERT ONLY,
	'StateChange'		= '@StateChange',
	'FirstOccurrence'		= '@FirstOccurrence' 		ON INSERT ONLY,
	'LastOccurrence'		= '@LastOccurrence',
	'InternalLast'		= '@InternalLast',
	'Poll'		= '@Poll' 		ON INSERT ONLY,
	'Type'		= '@Type' 		ON INSERT ONLY,
	'Tally'		= '@Tally' 		ON INSERT ONLY,
	'Class'		= '@Class'	 	ON INSERT ONLY,
	'Grade'		= '@Grade'	 	ON INSERT ONLY,
	'Location'		= '@Location' 		ON INSERT ONLY,
	'OwnerUID'		= '@OwnerUID',
	'Acknowledged'		= '@Acknowledged',
	'ServerName' 		= SRC_SERVER 		ON INSERT ONLY,
	'ServerSerial'		= '@ServerSerial' 		ON INSERT ONLY
);

Writer Attributes

The creation of a Cisco Info Server Writer requires the attributes described in Table 6-1.


Table 6-1:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of OBJECT_SERVER.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Name of mapping for Writer to use.

SERVER

Name of Cisco Info Server to write alerts to.

FORWARD_DELETES

Optional: Should deletes be forwarded. The default is YES/TRUE. When set to NO/FALSE, no deletes are propagated to the destination Cisco Info Server.

COUNTERPART

Optional: Name of the counterpart Reader in a bidirectional Info Gateway configuration. The Reader must be running for the command to function.

STORE_AND_FORWARD

Optional: The default is 1 (on). When the Cisco Info Server is unavailable, store and forward stores all events until the Cisco Info Server is available, then it forwards the alerts to the Cisco Info Server.

CONSECUTIVE_SAF_ERRORS

Optional: The number of consecutive errors to forward to the Cisco Info Server. When more than one consecutive error exists in the store and forward file, the Writer checks this figure to see how many of them to forward to the Cisco Info Server. The default is: 1.

RESYNC_FILTER

Optional: Defines a filter to use in the event this Writer becomes the master Writer during a resynchronization.

Cisco Info Server Info Gateway Attributes

Example

START WRITER CUSTOMER_WRITE
(
	TYPE = OBJECT_SERVER,
	REVISION = 1,
	SERVER = DENCO,
	MAP = SERVER_MAP,
	STORE_AND_FORWARD = 1
);

Remedy ARS Writer

The Remedy ARS (Action Request System) allows alerts to become help desk trouble tickets in Remedy ARS. When a route is established between an Cisco Info Server Reader and an ARS Writer, new alerts become trouble tickets in the AR system and the trouble tickets are updated, according to the mapping, throughout the life-span of the alert.

Remedy Compatibility

The Remedy ARS Writer is compatible with the Remedy ARS 2.x and above versions of Remedy ARS.

Initial Setup

Before using the ARS Writer, it is necessary to import a schema into the running Remedy ARS. This schema then acts as the schema where new alerts become trouble tickets. It is possible to configure the Info Gateway to write into any schema by modifying the standard mapping, but for simplicity, it is easiest to allow it to write into the supplied schema and use Remedy ARS's active link and filter facilities to despatch the new trouble tickets to the help desk.

In Remedy ARS, the administrator should create the Cisco Info Center schema by importing the supplied schema.

The Remedy ARS supports the importing of schemas and a pre-configured schema is supplied in the $OMNIHOME/gates/alerts.schema file. Use this file with the import schema in the ARS Administration tool. This creates a new schema called "Omnibus 3.3" in the ARS.

Mapping

Mappings for use with the Remedy ARS Writer must use this syntax:

CREATE MAPPING <mappingname>

(
<ARSFieldId> = '@<fieldname>' [ON INSERT ONLY] [CONVERT TO type]
[ , <ARSFieldId> = '@<fieldname>' [ON INSERT ONLY] [CONVERT TO type]]...
) ;

where <mappingname> is the name of the mapping to be created.

<ARSFieldId> is the integer value for the field to be written to in the ARS system.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

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

Note, you cannot use ON INSERT ONLY with the following fields:

When you use ON INSERT ONLY with these fields, the Info Gateway does not work.

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. type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string, or date type.

The Writer must pass across serial and severity fields to ARS to function correctly.

Example

The default mapping as supplied in the $OMNIHOME/gates/ars.conf file is designed for the supplied schema in $OMNIHOME/gates/ars.schema.

CREATE MAPPING ARS_MAP
(
	536870914 = '@Identifier'       ON INSERT ONLY,
	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',
	536870916 = '@Summary'          ON INSERT ONLY,
	536870946 = '@StateChange',
	536870912 = '@FirstOccurrence' ON INSERT ONLY,
	536870917 = '@LastOccurrence',
	536870935 = '@InternalLast',
	536870938 = '@Poll'             ON INSERT ONLY,
	536870941 = '@Type'             ON INSERT ONLY,
	536870940 = '@Tally',
	536870945 = '@Class'            ON INSERT ONLY,
	536870942 = '@Grade'            ON INSERT ONLY,
	536870934 = '@Location'         ON INSERT ONLY,
	536870933 = '@Acknowledged'
);

The integer value is the Remedy ARS field identifier. Most fields are written to specially defined records within the schema, with the exception of Severity (written to the ARS core field Status) and Summary (written to the ARS core field Short Description). The Severity, InternalLast, StateChange, Tally, and Acknowledged fields are updated in the trouble ticket as the alert is updated.

The string value must currently be set to @fieldname values which refer to fields in the alerts.status table.

Writer Attributes

The creation of a Writer for Remedy ARS requires the attributes described in Table 6-2.


Table 6-2:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of ARS.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Map file for the Writer to use.

SERVER

Name of server where the Remedy ARS is running.

SCHEMA

Name of schema in Remedy ARS where the Writer should generate trouble tickets using the specified map file.

USER

Name of Remedy ARS user to be used to submit and update alerts to the ARS system.

PASSWORD

Password of user specified in the USER attribute.

JOURNAL

ID number of the Journal field in the ARS schema.

FEEDBACK

Set to TRUE, activates the feedback mechanism (requires FEEDBACK_SERVER and FEEDBACK_FIELD attributes to be set). Set to FALSE, disables the feedback mechanism.

FEEDBACK_SERVER

Name of Cisco Info Server where the feedback mechanism should write the trouble ticket number.

FEEDBACK_FIELD

Name of field in FEEDBACK_SERVER where the feedback mechanism should write the trouble ticket number.

Remedy ARS Writer Attributes

The feedback mechanism allows for the trouble ticket number to be written back into the alert's entry in the Cisco Info Server. This allows for better co-ordination between users of Cisco Info Center and the Remedy ARS system.

Example

The example configuration contains the following configuration for an ARS Writer:

START WRITER ARS_WRITER
(
	TYPE = ARS,
	REVISION = 1,
	MAP = ARS_MAP,
	SERVER = 'orac',
	SCHEMA = 'Omnibus 3.3',
	USER = 'Demo',
	PASSWORD = '',
	FEEDBACK = TRUE,
	FEEDBACK_SERVER = NCOMS,
	FEEDBACK_FIELD = 'Location'
);

This example creates a Writer, using the map on page 13, which logs into the Remedy ARS, as a user called Demo with no password, to create alerts. When alerts are created, the feedback settings indicate that the trouble ticket number allocated is written to an Cisco Info Server named NCOMS and into a field in the alerts.status table named Location.

Notes

When using a filter with an Info Gateway, existing alerts that are excluded by the Info Gateway do not have a trouble ticket. When the alert changes and is no longer excluded by the filter, the Info Gateway creates a new trouble ticket.

Flat File Writer

The flat file Writer allows alerts to be written into a flat file. You can configure the format of the file using the Writer attributes.

Mapping

Mappings for use with the flat file Writer must be in the following format:

CREATE MAPPING <mappingname> 
(
'' = '@<fieldname>' [ON INSERT ONLY],
[ , ''= '@<fieldname>' [ON INSERT ONLY]]...
) ;

Where <mappingname> is the name of the mapping to be created.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

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

Example

CREATE MAPPING SERVER_MAP
(
	'Identifier' 		= '@Identifier',		ON INSERT ONLY,
	'Node' 		='@Node',		ON INSERT ONLY,
	'NodeAlias' 		= '@NodeAlias',		ON INSERT ONLY,
	'Manager' 		= '@Manager',		ON INSERT ONLY,
	'Agent' 		= '@Agent'		ON INSERT ONLY,
	'AlertGroup' 		= '@AlertGroup'		ON INSERT ONLY,
	'AlertKey' 		= '@AlertKey'		ON INSERT ONLY,
	'Severity' 		= '@Severity'		ON INSERT ONLY,
	'Summary' 		= '@Summary'		ON INSERT ONLY,
	'StateChange' 		= '@StateChange'		ON INSERT ONLY,
	'FirstOccurrence' 		= '@FirstOccurrence 		ON INSERT ONLY,
	'LastOccurrence' 		= '@LastOccurence 		ON INSERT ONLY,
	'InternalLast' 		= '@InternalLast'		ON INSERT ONLY,
	'Poll' 		= '@Poll'		ON INSERT ONLY,
	'Type' 		= '@Type'		ON INSERT ONLY,
	'Tally' 		= '@Tally'		ON INSERT ONLY,
	'Class' 		= '@Class'		ON INSERT ONLY,
	'Grade' 		= '@Grade'		ON INSERT ONLY,
	'Location'		= '@Location'		ON INSERT ONLY,
	'OwnerUID' 		= '@OwnerUID'		ON INSERT ONLY,
	'Acknowledged' 		= '@Acknowledged'		ON INSERT ONLY,
	'ServerSerial' 		= '@ServerSerial'		ON INSERT ONLY,
);

Writer Attributes

The creation of a Writer for Flat File requires the attributes described in Table 6-3.


Table 6-3: Flat File Info Gateway Writer Attributes
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of FILE.

FILE

The name of the file to write to.

REVISION

The version number of the Writer. Should be 1.

TRUNCATE

Should the file be truncated on startup, or should the Writer continue to append to the end of the file. The default is: FALSE.

SYNC

Synchronous write. The default is: FALSE.

MODE

File permissions. The default is: 0644.

MAP

The name of the mapping to use.

START_STRING

When the field is a string, the value of this attribute is prepended to the field before it is written to the file. The default is: ".

END_STRING

When the field is a string, the value of this attribute is append to the field before it is written to the file. The default is: ".

SEPERATOR

The value of this attribute is inserted between the fields written to the file. The default is: |.

INSERT_HEADER

The value of this attribute is prepended to each insert alert written to the file. The default is: '\nStart of insert line\n'.

INSERT_TRAILER

The value of this attribute is appended to each insert alert written to the file. The default is: '\nEnd of insert line\n'.

UPDATE_HEADER

The value of this attribute is prepended to each update alert written to the file. The default is: '\nStart of update line\n'.

UPDATE_TRAILER

The value of this attribute is appended to each update alert written to the file. The default is: '\nEnd of update line\n'.

DELETE_HEADER

The value of this attribute is prepended to each delete alert written to the file. The default is: '\nStart of delete line\n'.

DELETE_TRAILER

The value of this attribute is appended to each delete alert written to the file. The default is: '\nEnd of delete line\n'.

DATE_FORMAT

The format to use for any date fields written to the file. The default is: %C.

Example

START WRITER REMOTE_WRITER
(
	TYPE = FILE,
	REVISION = 1,
	FILE = '/opt/Omnibus/log/gates.out
	TRUNCATE = TRUE,
	SYNC = FALSE,
	MODE = 0644
	MAP = SERVER_MAP,
	START_STRING = '"',
	END_STRING = '"',
	SEPERATOR = '|'
	INSERT_HEADER = '\nStart of insert line\n',
	INSERT_TRAILER = '\nStart of insert line\n',
	UPDATE_HEADER = '\nStart of update line\n',
	UPDATE_TRAILER = '\nStart of update line\n',
	DELETE_HEADER = '\nStart of delete line\n',
	DELETE_TRAILER = '\nStart of delete line\n',
	DATE_FORMAT = '%C'
);

Informix Writer

The Informix Writer creates a single table of all transactions that have occurred within the alerts selected by a Cisco Info Server Reader. When a route is created between a Cisco Info Server Reader and an Informix Writer, for each change made to any record in the Cisco Info Server, a new record is created in the Informix database in a specified table. This can also include an action type (insert, update, or delete) and an action time. Reporting tools can be applied on the destination table to produce an audit trail.

Informix Compatibility

The Informix Writer is compatible with the following versions of Informix:

Initial Setup

Before running the Informix Writer, you must create tables in the Informix database for the alerts to be written into. A script (infoinstall) has been provided to do this automatically. Note, you must run the Info Gateway and the script as a user who is a member of the informix user group, otherwise the Info Gateway is denied access to the Informix database.

To run the script, specify:

host% $OMNIHOME/gates/infoinstall

The script executes Informix SQL statements to create and configure the necessary tables using a default template (INFORMIX.SQL). As the script is executed, you are prompted to specify names for the status, journal and details tables.

Mapping

Mappings for use with the Informix Writer must be in the following format:

CREATE MAPPING <mappingname> 
(
<InformixFieldName> = [ '@<fieldname>' | <special_value>] [CONVERT TO type]
[ , <InformixFieldName> = [ '@<fieldname>' | <special_value>] 
[CONVERT TO type]]...
) ;

where <mappingname> is the name of the mapping to be created.

<InformixFieldName> is the field name for the field to be written to in the Informix system.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

<special_value> may be one of a predefined set of keywords which map the field to a specific internal value. The keywords are:


Table 6-4:
ACTION_CODE

The type of action occurring on the alert. Values are I for Insert, U for Update, D for Delete.

ACTION_TIME

The time the action occurred. See Section, "Time Handling Between the Info Gateway and Informix", for details about time and date handling within the Info Gateway.

Informix Info Gateway Writer Keywords

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. type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string, or date type. This is particularly relevant when adding extra time fields in the Cisco Info Server to map to Informix. See Section, "Time Handling Between the Info Gateway and Informix".

Note The ordering of the fields in the mapping must exactly match the ordering of the fields in the Informix table being written to. When this is not the case, values are written to incorrect fields.

Example

The default mapping as supplied in the $OMNIHOME/gates/informix.conf file is designed for the supplied database/table created by the $OMNIHOME/gates/infoinstall script. The following example shows the default mapping:

CREATE MAPPING Informix_MAP
(
	'ActionTime'	= ACTION_TIME,
	'ActionCode'	= ACTION_CODE,
	'Identifier'	= '@Identifier',
	'Serial' 	= '@Serial',
	'Node'	= '@Node',
	'NodeAlias'	= '@NodeAlias',
	'Manager'	= '@Manager',
	'Agent'	= '@Agent',
	'AlertGroup'	= '@AlertGroup',
	'AlertKey'	= '@AlertKey',
	'Severity'	= '@Severity',
	'Summary'	= '@Summary',
	'StateChange'	= '@StateChange' 	CONVERT TO DATE,
	'FirstOccurrence'	= '@FirstOccurrence' 	CONVERT TO DATE,
	'LastOccurrence'	= '@LastOccurrence' 	CONVERT TO DATE,
	'InternalLast'	= '@InternalLast' 	CONVERT TO DATE,
	'Poll'	= '@Poll',
	'Type'	= '@Type',
	'Tally'	= '@Tally',
	'Class'	= '@Class',
	'Grade'	= '@Grade',
	'Location'	= '@Location',
	'OwnerUID'	= '@OwnerUID',
	'Acknowledged'	= '@Acknowledged',
	'ServerName'	= '@ServerName'
);

Note the use of CONVERT TO DATE; this usage is mandatory for these fields.

Writer Attributes

The creation of a Writer for an Informix database requires the attributes described in Table 6-5.


Table 6-5:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of INFORMIX.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Name of mapping for Writer to use.

FORWARD_DELETES

Optional: Should deletes be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE D (deletes) appear in the Informix table.

FORWARD_INSERTS

Optional: Should inserts be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE I (inserts) appear in the Informix table.

FORWARD_UPDATES

Optional: Should updates be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE U (updates) appear in the Informix table.

STATUS_TABLE

Name of the status table. The default is: status.

JOURNAL_TABLE

Name of the journal table. The default is: journal.

DETAILS_TABLE

Name of the details table. The default is: details.

DATABASE

Name of the database table. The default is: alerts.

HAS_TRANSACTIONS

Specifies whether to use transactions or not. The default is: FALSE.

INFORMIX_SERVER

The name of the Informix server.

Informix Info Gateway Writer Attributes

Example

The following example shows a possible configuration for an Informix Writer:

START WRITER Informix_WRITE
(
	TYPE = Informix,
	REVISION = 1,
	MAP = Informix_MAP,
	FORWARD_DELETES = TRUE,
	FORWARD_UPDATES = FALSE,
	FORWARD_INSERTS = FALSE,
	STATUS_TABLE = 'status',
	JOURNAL_TABLE = 'journal',
	DETAILS_TABLE = 'details',
	DATABASE = 'alerts'
	HAS_TRANSACTIONS = FALSE,
	INFORMIX_SERVER = 'DB_SERVER1'
);

This example creates a Writer which forwards deleted alerts to the Informix server DB_SERVER1 using the map defined in Informix_MAP.

Connecting to Informix

The host running the Info Gateway must be able to connect to either a local or a remote Informix server. When the server is not local to the host running the Info Gateway, you must add the necessary definitions to:

$INFORMIXDIR/etc/sqlhosts

Ask your Informix administrator to do this for you.

Time Handling Between the Info Gateway and Informix

Date/time fields are stored as an integer within the Cisco Info Center Cisco Info Server. This means that when a date/time field is to be mapped, it must be followed by the CONVERT TO DATE modifier.

CONVERT TO DATE forces the value to be internally printed in a format specified by the Writer attribute DATE_FORMAT. This string is then sent to Informix where it is assumed the destination field is a datetime type field; when this is true, the string is then converted into Informix's internal datetime format. When the destination field is a string field, a string representation of the date is inserted. When the destination field is an integer, the entire insert for the alert fails.

The DATE_FORMAT defaults to: %B %d, %Y %I:%M:%S%p. Details of this format are available by examining the manual page for the strftime call (man strftime). The default format is appropriate for english (C) locales but is inappropriate for other locales and must be overridden to the appropriate format for that locale.

Socket Writer

The Socket Writer forwards alerts to a remote TCP socket. Any process listening to that socket receives the alerts.

Mapping

Mappings for use with the Socket Writer must be in the following format:

CREATE MAPPING <mappingname> 
(
'' = '@<fieldname>' [ON INSERT ONLY],
[,'='@<fieldname>' [ON INSERT ONLY]]...
);

Where <mappingname> is the name of the mapping to be created. <fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

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

Example

CREATE MAPPING SERVER_MAP
(
	'Identifier'		= '@Identifier',		ON INSERT ONLY,
	'Serial' 		= '@Serial',	ON INSERT ONLY,
	'Node' 		= '@Node',	ON INSERT ONLY,
	'NodeAlias' 		= '@NodeAlias',	ON INSERT ONLY,
	'Manager' 		= '@Manager',	ON INSERT ONLY,
	'Agent' 		= '@Agent'	ON INSERT ONLY,
	'AlertGroup' 		= '@AlertGroup'	ON INSERT ONLY,
	'AlertKey' 		= '@AlertKey'	ON INSERT ONLY,
	'Severity' 		= '@Severity'	ON INSERT ONLY,
	'Summary' 		= '@Summary'	ON INSERT ONLY,
	'StateChange' 		= '@StateChange'	ON INSERT ONLY,
	'FirstOccurrence' 		= '@FirstOccurrence ON INSERT ONLY,
	'LastOccurrence' 		= '@LastOccurence 	ON INSERT ONLY,
	'InternalLast' 		= '@InternalLast'	ON INSERT ONLY,
	'Poll' 		= '@Poll'	ON INSERT ONLY,
	'Type' 		= '@Type'	ON INSERT ONLY,
	'Tally' 		= '@Tally'	ON INSERT ONLY,
	'Class' 		= '@Class'	ON INSERT ONLY,
	'Grade' 		= '@Grade'	ON INSERT ONLY,
	'Location' 		= '@Location'	ON INSERT ONLY,
	'OwnerUID' 		= '@OwnerUID'	ON INSERT ONLY,
	'Acknowledged' 		= '@Acknowledged'	ON INSERT ONLY,
	'ServerSerial' 		= '@ServerSerial'	ON INSERT ONLY,
);

Writer Attributes

The creation of a Socket Writer requires the attributes described in Table 6-6.


Table 6-6:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of SOCKET.

REVISION

The version number of the Writer. Should be: 1.

HOST

The name of the host to send data to.

PORT

The TCP port number.

MAP

The name of the mapping to use.

START_STRING

When the field is a string, the value of this attribute is prepended to the field before it is written to the socket. The default is: ".

END_STRING

When the field is a string, the value of this attribute is append to the field before it is written to the socket. The default is: ".

SEPERATOR

The value of this attribute is inserted between the fields written to the socket. The default is: |.

INSERT_HEADER

The value of this attribute is prepended to each insert alert written to the socket. The default is: '\nStart of insert line\n'.

INSERT_TRAILER

The value of this attribute is appended to each insert alert written to the socket. The default is: '\nEnd of insert line\n'.

UPDATE_HEADER

The value of this attribute is prepended to each update alert written to the socket. The default is: '\nStart of update line\n'.

UPDATE_TRAILER

The value of this attribute is appended to each update alert written to the socket. The default is: '\nEnd of update line\n'.

DELETE_HEADER

The value of this attribute is prepended to each delete alert written to the socket. The default is: '\nStart of delete line\n'.

DELETE_TRAILER

The value of this attribute is appended to each delete alert written to the socket. The default is: '\nEnd of delete line\n'.

DATE_FORMAT

The format to use for any date fields written to the socket. The default is: %C.

Socket Info Gateway Writer Attributes

Example

START WRITER REMOTE_WRITER
(
	TYPE = FILE,
	REVISION = 1,
	HOST = 'hostname',
	PORT = 4242
	MAP = SERVER_MAP,
	START_STRING = '"',
	END_STRING = '"',
	SEPERATOR = '|'
	INSERT_HEADER = '\nStart of insert line\n',
	INSERT_TRAILER = '\nStart of insert line\n',
	UPDATE_HEADER = '\nStart of update line\n',
	UPDATE_TRAILER = '\nStart of update line\n',
	DELETE_HEADER = '\nStart of delete line\n',
	DELETE_TRAILER = '\nStart of delete line\n',
	DATE_FORMAT = '%C'
);

Sybase Writer

The Sybase Writer creates a single table of all transactions that have occurred within the alerts selected by a Cisco Info Server Reader. When a route is created between a Cisco Info Server Reader and a Sybase Writer, for each change made to any record in the Cisco Info Server, a new record is created in the Sybase database, in a specified table. This can also include an action type (insert, update, or delete) and an action time. Using this "audit trail", reporting tools can be applied to the table to produce additional data.

Sybase Compatibility

The Sybase Writer is compatible with the following versions of Sybase:

Initial Setup

Before running the Sybase Writer, you must create tables in the Sybase database for the alerts to be written into. A script (sybinstall) has been provided to do this automatically. To run the script, specify:

host% $OMNIHOME/gates/sybinstall

The script executes Sybase SQL statements to create and configure the necessary tables using a default template (SYBASE.SQL). As the script is executed, you are prompted to specify names for the status, journal, and details tables.

Mapping

Mappings for use with the Sybase Writer must follow this format:

CREATE MAPPING <mappingname> 
(
<SybaseFieldName> = [ '@<fieldname>' | <special_value>] [CONVERT TO type]
[ , <SybaseFieldName> = [ '@<fieldname>' | <special_value>] [CONVERT TO type]]...
);

Where <mappingname> is the name of the mapping to be created.

<SybaseFieldName> is the field name for the field to be written to in the Sybase system.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

<special_value> may be one of a predefined set of keywords which map the field to a specific internal value. The keywords are:


Table 6-7:

ACTION_CODE

The type of action occurring on the alert. Values are I for Insert, U for Update, D for Delete.

ACTION_TIME

The time the action occurred. See Section, "Time Handling Between the Info Gateway and Sybase", for details about time and date handling within the Info Gateway.

Sybase Info Gateway Writer Keywords

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. type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string, or date type. This is particularly relevant when adding extra time fields in the Cisco Info Server to map to Sybase. See Section, "Time Handling Between the Info Gateway and Sybase".

Note The ordering of the fields in the mapping must exactly match the ordering of the fields in the Sybase table being written to. When this is not the case, values are written to incorrect fields.

Example

The default mapping as supplied in the $OMNIHOME/gates/sybase.conf file is designed for the supplied database/table created by the $OMNIHOME/gates/sybinstall script.

CREATE MAPPING SYBASE_MAP
(
	'ActionTime'	= ACTION_TIME,
	'ActionCode'	= ACTION_CODE,
	'Identifier'	= '@Identifier',
	'Serial' 	= '@Serial',
	'Node'	= '@Node',
	'NodeAlias'	= '@NodeAlias',
	'Manager'	= '@Manager',
	'Agent'	= '@Agent',
	'AlertGroup'	= '@AlertGroup',
	'AlertKey'	= '@AlertKey',
	'Severity'	= '@Severity',
	'Summary'	= '@Summary',
	'StateChange'	= '@StateChange' 	CONVERT TO DATE,
	'FirstOccurrence'	= '@FirstOccurrence' 	CONVERT TO DATE,
	'LastOccurrence'	= '@LastOccurrence' 	CONVERT TO DATE,
	'InternalLast'	= '@InternalLast' 	CONVERT TO DATE,
	'Poll'	= '@Poll',
	'Type'	= '@Type',
	'Tally'	= '@Tally',
	'Class'	= '@Class',
	'Grade'	= '@Grade',
	'Location'	= '@Location',
	'OwnerUID'	= '@OwnerUID',
	'Acknowledged'	= '@Acknowledged',
	'ServerName'	= '@ServerName'
);

Note the use of CONVERT TO DATE; this usage is mandatory for these fields.

Writer Attributes

The creation of a Writer for Sybase system requires the attributes described in Table 6-8.


Table 6-8:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of SYBASE.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Name of mapping for Writer to use.

SERVER

Name of Sybase server to write alerts to.

USERNAME

Name of user to log into the Sybase system as.

PASSWORD

Password of user being used to log into Sybase.

FORWARD_DELETES

Optional: should deletes be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE D (deletes) appear in the Sybase table.

FORWARD_INSERTS

Optional: should inserts be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE I (inserts) appear in the Sybase table.

FORWARD_UPDATES

Optional: should updates be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE U (updates) appear in the Sybase table.

DATE_FORMAT

Optional: format for dates to be written to Sybase. See Section, "Time Handling Between the Info Gateway and Sybase".

STATUS_TABLE

Name of the status table. The default is: status.

JOURNAL_TABLE

Name of the journal table. The default is: journal.

DETAILS_TABLE

Name of the details table. The default is: details.

DATABASE

Name of the database table. The default is: alerts.

Sybase Info Gateway Writer Attributes

Example

The example configuration contains the following configuration for a Sybase Writer:

START WRITER Sybase_WRITE
(
	TYPE = Sybase,
	REVISION = 1,
	MAP = Sybase_MAP,
	USERNAME = 'sybase_user1'
	PASSWORD = 'password12'
	FORWARD_DELETES = TRUE,
	FORWARD_UPDATES = FALSE,
	FORWARD_INSERTS = FALSE,
	STATUS_TABLE = 'status',
	JOURNAL_TABLE = 'journal',
	DETAILS_TABLE = 'details',
	DATABASE = 'alerts'
	SERVER = 'DB_SERVER1'
);

This example creates a Writer which forwards deleted alerts to the Sybase server DB_SERVER1 using the map defined in Sybase_MAP.

Notes

Connecting to Sybase

In order for the Info Gateway to communicate with Sybase, you must add the Sybase server to the configuration of the servers editor (nco_xigen). The server must have a unique name and port number. See the Cisco Info Center Administrator Reference guide for more information about nco_xigen.

Time Handling Between the Info Gateway and Sybase

Date/time fields are stored as an integer within the Cisco Info Server. This means that when a date/time field is to be mapped, it must be followed by the CONVERT TO DATE modifier.

CONVERT TO DATE forces the value to be internally printed in a format specified by the Writer attribute DATE_FORMAT. This string is then sent to Sybase where it is assumed the destination field is a datetime type field; when this is true, the string is then converted into Sybase's internal datetime format. When the destination field is a string field, a string representation of the date is inserted. When the destination field is an integer, the entire insert for the alert fails.

The DATE_FORMAT defaults to: %B %d, %Y %I:%M:%S%p. Details of this format are available by examining the manual page for the strftime call (man strftime). The default format is appropriate for english (C) locales but is inappropriate for other locales and must be overridden to the appropriate format for that locale.

SNMP (Forwarder) Writer

The SNMP Writer allows alerts in the system to be forwarded as SNMP traps. This allows Cisco Info Center to generate traps which are forwarded to another management platform such as SunNet Manager or HP Network Node Manager.

SNMP Compatibility

The SNMP Writer forwards SNMP version 1 traps.

Initial Setup

Before using the Info Gateway, it is essential that the target management platform is configured to receive the Cisco Info Center traps. Traps from the SNMP forwarder, by default, arrive with an OID value of 1.3.6.1.4.1.1279, a generic-trap value of 6 and specific-trap value of 1. These values can be overridden when the Writer is started.

Mapping

Mappings for use with the SNMP (forwarder) Writer must use the following syntax:

CREATE MAPPING <mappingname>

(

<varbindint> = '@<fieldname>'

[,<varbindint> = '@<fieldname>' [ ON INSERT ONLY ] ]...

) ;

Where <mappingname> is the name of the mapping to be created.

<varbindint> is the integer value for the varbind field to be written to in the SNMP trap.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

Example

CREATE MAPPING SNMP_MAP
(
	0 = '@Summary',
	1 = '@Severity',
	2 = '@Location',
	3 = '@Node',
	4 = '@AlertGroup'
);

Writer Attributes

The creation of a Writer for the SNMP trap forwarder requires the attributes described in Table 6-9.


Table 6-9:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of SNMP.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Map file for the Writer to use.

INFO GATEWAY

Name of machine to forward SNMP traps to.

COMMUNITY

Optional: community string from SNMP traps. When not specified, defaults to public.

RETRIES

Optional: integer value for number of retries to attempt to send the SNMP trap. The default is: 4.

TIMEOUT

Optional: integer value for the timeout for each attempt to send the SNMP traps. The default is: 1 second.

PORT

Optional: port address for snmpd on the Info Gateway system. The default is: 162.

OID

Optional: Object Identifier for traps. The default is: 1.3.6.1.4.1.1279 (enterprise number). Can also be defined as @NodeGroup to forward the value of the NodeGroup column in the status table.

TRAP

Optional: integer value for the generic-trap field in SNMP traps forwarded. The default is: 6. Can also be defined as @Severity to forward the value of the Severity column in the status table.

SPECIFIC

Optional: integer value for the specific-trap field in SNMP traps forwarded. The default is: 1. Can also be defined as @Class to forward the value of the Class column in the status table.

FORWARD_UPDATES

Optional: allows the Writer to forward alert updates as well as new alerts. The default is: FALSE.

SNMP (Forwarder) Info Gateway Writer Attributes

Example

START WRITER SNMP_WRITER
(
	TYPE = SNMP,
	REVISION = 1,
INFO GATEWAY= 'penelope',
	MAP = SNMP_MAP
);

Notes

The SNMP Writer only forwards new (inserted) alerts unless the attribute FORWARD_UPDATES is set to TRUE. This in effect reduplicates alerts (as opposed to the Cisco Info Servers deduplication mechanism).

The SNMP Writer never forwards deletions of alerts.

ServiceView Writer

The ServiceView Writer forwards alerts into the ServiceView system. The Writer, given a host and a port, takes alerts and updates and sends them, in a simple hash delimited format, to the ServiceView system.

Mapping

Mappings for use with the ServiceView Writer must use the following syntax:

CREATE MAPPING <mappingname>

(

'' = '@<fieldname>'

[ , ''= '@<fieldname>' ]...

) ;

where <mappingname> is the name of the mapping to be created.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

Note, the target name is a null string. ServiceView does not have fields that can be mapped. When an alert is forwarded, the order of the mapping is used to determine the order the data is written.

Example

CREATE MAPPING SV_MAP
(
	'' = '@Summary',
	'' = '@Severity',
	'' = '@Location',
	'' = '@Node',
	'' = '@AlertGroup'
);

Writer Attributes

The creation of a Writer for ServiceView requires the attributes described in Table 6-10.


Table 6-10:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of SERVICE_VIEW.

REVISION

Revision of Writer; must have a value of 1.

MAP

Map file for the Writer to use.

HOST

Name of host to forward alerts to.

PORT

Optional: port to send alerts to on named host. The default is: 3200.

ServiceView Info Gateway Writer Attributes

Example

START WRITER SV_WRITER
(
	TYPE = SERVICE_VIEW,
	REVISION = 1,
	HOST = 'penelope',
	MAP = SV_MAP
);

Notes

When an alert appears in the Cisco Info Center system, all fields referred to in the mapping are forwarded, and are preceded by the tag NEWALERT.

For example, consider the following mapping:

CREATE MAPPING SV_MAP
(
	'' = '@Serial',
	'' = '@Node',
	'' = '@Severity',
);

When a new alert appears, for example, with a Serial of 2040, Node set to cortez, and Severity of 5, ServiceView receives (where

is a symbol for the new line character):

NEWALERT#2040#cortez#5#ø

When an update occurs on this alert, ServiceView receives an update. Updates are preceded with the tag ALERTUPDATE. In the example, where an update of Severity changed to 4, the ServiceView would be sent:

ALERTUPDATE#2040#cortez#4#ø

Deletions of alerts are not sent to ServiceView.

Oracle Writer

The Oracle Writer creates a single table of all transactions that have occurred within the alerts selected by an Cisco Info Server Reader. When a route is created between a Cisco Info Server Reader and an Oracle Writer, for each change made to any record in the Cisco Info Server, a new record is created in the Oracle database, in a specified table. This can also include an action type (insert, update, or delete) and an action time. Using this "audit trail", reporting tools can be applied to the table to produce additional data.

Oracle Compatibility

The Oracle Writer is compatible with Oracle versions 7.3 and above.

Initial Setup

Before running the Oracle Writer, you must create tables in the Oracle database for the alerts to be written to. A script (orainstall) has been provided to do this automatically. To run the script, specify:

host% $OMNIHOME/gates/orainstall

The script executes Oracle SQL statements to create and configure the necessary tables using a default template (ORACLE.SQL). As the script is executed, you are prompted to specify names for the status, journal, and details tables.

Mapping

Mappings for use with the Oracle Writer must use the following syntax:

CREATE MAPPING <mappingname> 
(
<OracleFieldName> = [ '@<fieldname>' | <special_value> ] [ CONVERT TO type ]
[ , <OracleFieldName> = [ '@<fieldname>' | <special_value> ] [ CONVERT TO type ]]...
);

where <mappingname> is the name of the mapping to be created.

<OracleFieldName> is the field name for the field to be written to in the Oracle database.

<fieldname> must be the name of a field in the Cisco Info Server alerts.status table.

<special_value> may be one of a predefined set of keywords which map the field to a specific internal value. The keywords are:


Table 6-11:
ACTION_CODE

The type of action occurring on the alert. Values are I for Insert, U for Update, and D for Delete.

ACTION_TIME

The time the action occurred.

Oracle Info Gateway Writer Keywords

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. type can be INTEGER, STRING, or DATE to force the source field to be converted to an integer, string or date type. This is particularly relevant when adding extra time fields in the Cisco Info Server to map to Oracle.

Note The ordering of the fields in the mapping must exactly match the ordering of the fields in the Oracle table being written to. When this is not the case, values are written to incorrect fields.

Example

The default mapping as supplied in the $OMNIHOME/gates/oracle.conf file is designed for the supplied database/table created by the $OMNIHOME/gates/orainstall script.

CREATE MAPPING ORACLE_MAP
(
	'ActionTime'	= ACTION_TIME,
	'ActionCode'	= ACTION_CODE,
	'Identifier'	= '@Identifier',
	'Serial' 	= '@Serial',
	'Node'	= '@Node',
	'NodeAlias'	= '@NodeAlias',
	'Manager'	= '@Manager',
	'Agent'	= '@Agent',
	'AlertGroup'	= '@AlertGroup',
	'AlertKey'	= '@AlertKey',
	'Severity'	= '@Severity',
	'Summary'	= '@Summary',
	'StateChange'	= '@StateChange' 	CONVERT TO DATE,
	'FirstOccurrence'	= '@FirstOccurrence' 	CONVERT TO DATE,
	'LastOccurrence'	= '@LastOccurrence' 	CONVERT TO DATE,
	'InternalLast'	= '@InternalLast' 	CONVERT TO DATE,
	'Poll'	= '@Poll',
	'Type'	= '@Type',
	'Tally'	= '@Tally',
	'Class'	= '@Class',
	'Grade'	= '@Grade',
	'Location'	= '@Location',
	'OwnerUID'	= '@OwnerUID',
	'Acknowledged'	= '@Acknowledged',
	'ServerName'	= '@ServerName'
);

Note the use of CONVERT TO DATE; this usage is mandatory for these fields.

Writer Attributes

The creation of a Writer for Oracle requires the attributes described in Table 6-12.


Table 6-12:
Attribute Name Description

TYPE

Type of Writer; must have a mandatory value of ORACLE.

REVISION

Revision of Writer; must have a mandatory value of 1.

MAP

Name of mapping for Writer to use.

SERVER

Name of Oracle server to write alerts to.

USERNAME

Name of user to log into the Oracle system as.

PASSWORD

Password of user being used to log into Oracle.

FORWARD_DELETES

Optional: should deletes be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE D (deletes) appear in the Oracle table.

FORWARD_INSERTS

Optional: should inserts be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE I (inserts) appear in the Oracle table.

FORWARD_UPDATES

Optional: should updates be forwarded. The default is YES/TRUE. When set to NO/FALSE, no ACTION_CODE U (updates) appear in the Oracle table.

DATE_FORMAT

Optional: format for dates to be written to Oracle. See Section, "Time Handling Between the Info Gateway and Sybase".

STATUS_TABLE

Name of the status table. The default is: status

JOURNAL_TABLE

Name of the journal table. The default is: journal

DETAILS_TABLE

Name of the details table. The default is: details

Oracle Info Gateway Writer Attributes

Example

The example configuration contains the following configuration for an Oracle Writer:

START WRITER ORACLE_WRITE
(
	TYPE = Oracle,
	REVISION = 1,
	MAP = Oracle_MAP,
	USERNAME = 'oracle_user1'
	PASSWORD = 'password12'
	FORWARD_DELETES = TRUE,
	FORWARD_UPDATES = FALSE,
	FORWARD_INSERTS = FALSE,
	STATUS_TABLE = 'status',
	JOURNAL_TABLE = 'journal',
	DETAILS_TABLE = 'details',
	SERVER = 'DB_SERVER1'
);

This example creates a Writer which forwards deleted alerts to the Oracle server DB_SERVER1 using the map defined in Oracle_MAP.

Connecting to Oracle

In order for the Info Gateway to communicate with Oracle, you must add the Oracle server to the configuration of the servers editor (nco_xigen). The server must have a unique name and port number. See the Cisco Info Center Administrator Reference guide for more information about nco_xigen.

Time Handling Between the Info Gateway and Oracle

Date/time fields are stored as an integer within the Cisco Info Server. This means that when a date/time field is to be mapped, it must be followed by the CONVERT TO DATE modifier.

CONVERT TO DATE forces the value to be internally printed in a format specified by the Writer attribute DATE_FORMAT. This string is then sent to Oracle where it is assumed the destination field is a datetime type field; when this is true, the string is then converted into Oracle's internal datetime format. When the destination field is a string field, a string representation of the date is inserted. When the destination field is an integer, the entire insert for the alert fails.

The DATE_FORMAT defaults to: %B %d, %Y %I:%M:%S%p. Details of this format are available by examining the manual page for the strftime call (man strftime). The default format is appropriate for English (C) locales but is inappropriate for other locales and must be overridden to the appropriate format for that locale.

Peregrine ServiceCenter Gateway

The Peregrine Info Gateway is a fully functional implementation of a Cisco Info Center bidirectional Info Gateway. Alerts are forwarded from the Cisco Info Server through the Info Gateway to form ServiceCenter Problem Management tickets. Both systems work together to create and update alerts and tickets. Any change made to a Cisco Info Center alert or a ServiceCenter Problem Management ticket is reflected in its associated alert or ticket.

ServiceCenter Compatibility

The Peregrine ServiceCenter Info Gateway is compatible with Peregrine ServiceCenter 2.0.

Info Gateway Operation

The Info Gateway manages three types of events, each of which performs a different ticket function:

The PMO event type creates a ServiceCenter ticket and forwards it to the ServiceCenter Problem Management System. The Problem Management System issues a response to the Cisco Info Server to confirm the ticket has been created.

The PMU event type updates a ticket when a change is made to an associated event in the Cisco Info Server. This ensures tickets and alerts are synchronized.

The PMC event type closes a ticket when the associated event is resolved.

When a ticket is created using PMO, the Info Gateway stores the serial number of the alert. When the Problem Management system responds, indicating the ticket has been created, the Info Gateway stores the number of the ticket. By storing the serial number of the alert and the Problem Management Problem ID together, the Info Gateway can track associated alerts and tickets. Figure 6-1 shows the relationship between the components of the Info Gateway and ServiceCenter.


Figure 6-1: Peregrine ServiceCenter Info Gateway Architecture


Figure 6-1shows the components of the Info Gateway and Peregrine ServiceCenter used to create and manage tickets and alerts. These components are described in the following sections.

Reader, Writer, and Route

The Info Gateway uses a standard Reader and route which are defined in the Info Gateway configuration file. The Writer defines four different mappings, one for each event type (PMO, PMU, PMC), and one for ServiceCenter journal entries. You must create an Info Gateway configuration file that contains these components. See Section, "Create the Info Gateway Configuration File", for more information.

OS-SC and SC-OS Routes

The OS-SC (Cisco Info Server to ServiceCenter) and SC-OS (ServiceCenter to Cisco Info Server) routes define the interaction between the Info Gateway and ServiceCenter. They work in conjunction to track tickets and alerts. To do this, they use the serial to Problem Management Problem ID cache to match alerts routed from the Cisco Info Server with tickets routed from ServiceCenter.

For the Info Gateway to map events to ServiceCenter correctly, you must define field conversions between the Info Gateway and ServiceCenter. See Section, "Create the Info Gateway Conversions Table", for more information.

ServiceCenter can feedback events through the Info Gateway into the Cisco Info Server. You must define how the Info Gateway should act when it receives an event using SQL. See Section, "Editing the Info Gateway Action SQL Files", for more information.

R/W Modules

The OS-SC and SC-OS routes also launch Read/Write modules (outside the Info Gateway) which read and write tickets and alerts to and from ServiceCenter. They do this by creating a TCP/IP connection to SCAuto.

Both of these modules produce a log file to record the information transferred through Info Gateway, as described in Section, "R/W Modules".

SCAuto (Integration Server)

SCAuto is the interface through which the Info Gateway connects to ServiceCenter using a TCP/IP connection. You must ensure you have SCAuto installed and licensed.

Event Queues

Event In and Event Out queue events passed to and from SCAuto and Event Services. You can look at the events currently in the queues.

Event Services

Event Services manages events received from the Info Gateway and sent from the Problem Management System. You must register the event types used by the Info Gateway so that ServiceCenter can interpret and process the events it receives and so it can feed back tickets to the Info Gateway. You also must create mappings so ServiceCenter can map events into tickets and tickets into events.

See Sections, "Registering ServiceCenter Event Types" and "Create ServiceCenter Mappings" for more information.

Problem Management System

The ServiceCenter Problem Management System is used to manage tickets. You must Configure ServiceCenter subroutines so ServiceCenter can feed back events into the Info Gateway. See Section, "Problem Update Mapping Output Fields", for more information.

ServiceCenter Record Category

By default, the ServiceCenter Info Gateway uses the equipment record category. This is defined in the Info Gateway mapping by the static variable equipment.

Sequence Numbers

When the Info Gateway is started, an internal sequence number is used to determine at what point in the ServiceCenter database the Reader module should start processing events. Between shutdowns of the Info Gateway, this sequence number is stored in an external file. When the Info Gateway is restarted, all events starting at this sequence number are processed. The sequence number is not configurable and is documented in the log files.

R/W Module Log Files

The R/W modules both produce a log file which records the operation of the Info Gateway. These log files are stored in the file:

$OMNIHOME/bin/arch/nco_prwmodule_<PID>.log

Where <PID> is the UNIX process identifier for either the Reader or Writer module.

Table 6-13 shows the format of the log files.


Table 6-13:
Field name Description

evtype

Event type being performed on this record. Can be pmo, pmu, or pmc.

evtime

The event time set and controlled by the ServiceCenter event manager.

evsysseq

Internal sequence number maintained by the Info Gateway.

evusrseq

User sequence number used by the Info Gateway to determine whether the event was generated by ServiceCenter, or is a return event from the Info Gateway.

evuser

The username used to read or write Cisco Info Center and ServiceCenter records.

evpswd

Application password for the event, when one is required.

evsepchar

Character used to separate ServiceCenter record fields.

evfields

Complete ServiceCenter record. Fields are delimited by the separator character.

ServiceCenter Record Log Format

Peregrine ServiceCenter Users

The ServiceCenter configuration must be performed by a user with Administration privileges.

Before you run the Info Gateway, you should create an operator named Omnibus. This operator is used in the configuration and allows you to track events that are generated by the Info Gateway.

Info Gateway Configuration

Before you can run the Info Gateway, you must configure the Info Gateway and Peregrine ServiceCenter. You must complete the following six steps:

Step 1 Create the Info Gateway configuration file.

Step 2 Create the Info Gateway conversions table.

Step 3 Edit the Info Gateway action SQL files.

Step 4 Register ServiceCenter event types.

Step 5 Create ServiceCenter mappings.

Step 6 Configure ServiceCenter format control subroutines.

Each of these steps is described in the following sections.

Create the Info Gateway Configuration File

The Peregrine ServiceCenter Info Gateway configuration file is similar to those for other Info Gateways. The main difference is the Info Gateway contains four different mappings, one for each type of event or ticket, and one to update ServiceCenter journals.

The Info Gateway Writer attributes and mappings are described in the following sections.

Writer Attributes

Table 6-14 shows the required ServiceCenter Writer attributes.


Table 6-14: Peregrine ServiceCenter Info Gateway Attributes
Attribute Name Mandatory Description

TYPE

Yes

Identifies the type of Writer, must be set to a value of PEREGRINE.

REVISION

Yes

Revision of Writer, with this release must be set to a value of 1.

OPEN_MAP

Yes

Name of the open mapping attribute configuration.

UPDATE_MAP

Yes

Name of the update mapping attribute configuration.

CLOSE_MAP

Yes

Name of the close mapping attribute configuration.

JOURNAL_MAP

Yes

Name of the journal mapping attribute configuration.

SCAUTO_SERVER

Yes

Name of the host server where the ServiceCenter SCAUTO server is running.

USER

Yes

Name of the user to be used when sending and retrieving events.

APPLICATION_PASSWORD

Yes

Password to access the application when one is required. Can be specified as a null.

FEEDBACK_SERVER

Yes

Name of the Cisco Info Server where the Info Gateway feedback mechanism writes the ServiceCenter problem record.

FEEDBACK_FIELD

Yes

Name of the field in the feed back Cisco Info Server where the ServiceCenter problem management problem ID should be written.

PROBNUM_FIELD_INDEX

Yes

The field index of the returned ServiceCenter PMO response event where the problem management problem ID can be found.

SEPARATOR_CHAR

No

Character used to separate fields in a ServiceCenter event record. The default is the ^ character.

CLOSE_PROBLEMS

Yes

Must have a value of TRUE or FALSE to specify whether or not Cisco Info Center can close problem records in ServiceCenter. TRUE enables problem closure, FALSE disables problem closure.

DATE_FORMAT

No

Format of date required. Defaults to "%B %d, %Y %I:%M:%S%p". Details of this format are available from the manual page for the strftime call.

COUNTERPART

Yes

Name of the counterpart Reader in the bidirectional Info Gateway configuration.

CONVERSIONS_TABLE

Yes

Name of the conversions table in the Cisco Info Server that holds the data values of required conversions between ServiceCenter and Cisco Info Center fields.

OPEN_ACTION_SQL

No

Name of the file containing the open action SQL to be performed at the Cisco Info Server. When no attribute is supplied, no action is taken.

UPDATE_ACTION_SQL

No

Name of the file containing the update action SQL to be performed at the Cisco Info Server. When no attribute is supplied, no action is taken.

CLOSE_ACTION_SQL

No

Name of the file containing the close action SQL to be performed at the Cisco Info Server. When no attribute is supplied, no action is taken.

The following example shows a configuration file complete with Info Gateway commands and Writer attributes:

#
# Start up the reader - connect to the Cisco Info Server SCNCOMS
#
# This example does not use filtering
#
START READER SERVER_READER CONNECT TO SCNCOMS;
 
#
# Start up the writer
#
START WRITER PEREGRINE_WRITER
(

    TYPE	= 	PEREGRINE,
    REVISION	= 	1,
    OPEN_MAP	= 	PEREGRINE_OPEN_MAP,
    UPDATE_MAP	= 	PEREGRINE_UPDATE_MAP,
    CLOSE_MAP	= 	PEREGRINE_CLOSE_MAP,    
JOURNAL_MAP	= 	PEREGRINE_JOURNAL_MAP
SCAUTO_SERVER	= 	`jfksys1.scauto1',
    USER	= 	'Omnibus',
    APPLICATION_PASSWORD	= 	'',
    FEEBDACK_SERVER	= 	'SCNCOMS',
    FEEDBACK_FIELD	= 	'Location',    
PROBNUM_FIELD_INDEX	=	2,
SEPARATOR_CHAR	= 	'^',
    CLOSE_PROBLEMS	= 	'TRUE',
    DATE_FORMAT	= 	'%m/%d/%y %T',    
COUNTERPART	= 	SERVER_READER,
    CONVERSIONS_TABLE	= 	'conversions.peregrine',
    OPEN_ACTION_SQL	= 	'/dev/peregrine/open_action.sql',
    UPDATE_ACTION_SQL	= 	'/dev/peregrine/open_action.sql',
    CLOSE_ACTION_SQL	= 	'/dev/peregrine/open_action.sql'    

);
 
#
# Add a route from the reader to the writer so the data is passed
#
ADD ROUTE FROM SERVER_READER TO PEREGRINE_WRITER
 
#
# End of file
#

ServiceCenter Writer Mapping

Mapping techniques define how the format of Cisco Info Server and ServiceCenter data should be changed so it is written in the correct format and to the correct field in the receiving application.

The ServiceCenter Info Gateway allows individual mapping configurations to be specified for the following functions:

Mapping configurations for use with the ServiceCenter Writer must use the following syntax:

CREATE MAPPING <mappingname>

(

<FieldId> = '<@fieldname>' [ CONVERT TO DATE ], ... ,

[ <FieldId> = '<fieldname>'], ... ,

[ <FieldId> = <variablename>], ...

) ;

where <mappingname> is the name of the map configuration to be created.

<FieldId> is an integer value assigned to this field. It does not have any sequencing value, it is used to enhance readability of the field list.

<@fieldname> is a string value which must be the name of a field in the Cisco Info Server alerts.status table.

<fieldname> is the value of a static variable that can not be changed by either Cisco Info Center or ServiceCenter.

<variablename> is the name of a system variable supplied by the Info Gateway. This can be either PROBLEM_NUMBER or JOURNAL_TEXT. When used, the current contents of these variables are substituted in the assigned fields. PROBLEM_NUMBER holds the ServiceCenter problem Problem Management Problem ID. It can only be used in update and close maps. JOURNAL_TEXT holds the journal text and can only be used in a journal map.

The optional CONVERT TO DATE allows the mapping to define a forced conversion to a date type field.

The position of Cisco Info Center and ServiceCenter field mappings is important, as the Info Gateway forwards events to ServiceCenter as a single string. Therefore, you must ensure the Info Gateway mapping fields are in the same order as the ServiceCenter mapping fields. As each record is processed, the corresponding field values are substituted. For example, the following assignment specifies the third ServiceCenter field must be substituted with the value of Cisco Info Center field ServerSerial:

3= '@ServerSerial'

As the mapping is positional, the sequencing of fields is effected by their placement. When you do not wish to use a particular ServiceCenter field, you must supply a separator character(s) to move to the next field.

For certain functions, you do not want values to be substituted. For example, when closing a ServiceCenter record you may only want to substitute certain values and leave the other fields with the value they previously contained. In this case you must assign a null value to the ServiceCenter record.

The ServiceCenter Info Gateway supports the use of static variables. This is a technique for supplying certain values that must not be changed by Cisco Info Center. The following assignment shows that ServiceCenter field number 10 has a value of equipment. This is a ServiceCenter record category that should not be changed, as it is only applicable to ServiceCenter. This value remains the same for the lifetime of the record.

10= 'equipment',

The following sections describe mapping techniques for each of the create, update, close, and journal mapping functions.

Create Open Map Example

The following mapping configuration is an example of data that is substituted when a record is opened. In this example, the tenth ServiceCenter field has been assigned the static variable, equipment, which indicates the Info Gateway uses the equipment ServiceCenter record category. All other fields are created and assigned Cisco Info Server values.

CREATE MAPPING PEREGRINE_OPEN_MAP
(
	1	= '@Identifier',
	2	= '@Server',
	3	= '@ServerSerial',
	4	= '@Node',
	5	= '@Manager',
	6	= '@Agent',
	7	= '@AlertGroup',
	8	= '@AlertKey',
	9	= '@Severity',
	10	= 'equipment',
	11	= '@StateChange'	CONVERT TO DATE,
	12	= '@FirstOccurrence'	CONVERT TO DATE,
	13	= '@LastOccurrence'	CONVERT TO DATE,
	14	= '@InternalLast'		CONVERT TO DATE,
	15	= '@Poll',
	16	= '@Type',
	17	= '@Tally',
	18	= '@Class',
	19	= '@Grade',
	20	= '@Location',
	21	= '@OwnerUID',
	22	= '@OwnerUID',
	23	= '@Acknowledged',
	24	= '@NodeAlias'
);

Create Update Map Example

The following mapping configuration is an example of data that is substituted when a record is updated. In this example, the third ServiceCenter field has been assigned the Info Gateway variable, PROBLEM_NUMBER. The tenth ServiceCenter field has been assigned the static variable equipment. All other fields are substituted with new Cisco Info Server values.

CREATE MAPPING PEREGRINE_UPDATE_MAP
(
	1	= '@Identifier',
	2	= '@Server',
	3	= PROBLEM_NUMBER,
	4	= '@Node',
	5	= '@Manager',
	6	= '@Agent',
	7	= '@AlertGroup',
	8	= '@AlertKey',
	9	= '@Severity',
	10	= 'equipment',
	11	= '@StateChange'	CONVERT TO DATE,
	12	= '@FirstOccurrence'	CONVERT TO DATE,
	13	= '@LastOccurrence'	CONVERT TO DATE,
	14	= '@InternalLast'		CONVERT TO DATE,
	15	= '@Poll',
	16	= '@Type',
	17	= '@Tally',
	18	= '@Class',
	19	= '@Grade',
	20	= '@Location',
	21	= '@OwnerUID',
	22	= '@OwnerUID',
	23	= '@Acknowledged',
	24	= '@Servername',
	25	= '@ServerSerial'
);

Create Close Map

The following mapping configuration is an example of data that is substituted when a record is closed. In this example, only the Cisco Info Center field @Serial is substituted. ServiceCenter field number three has been assigned the Info Gateway variable, PROBLEM_NUMBER. All other fields have a null value; they are not substituted with any new values.

CREATE MAPPING PEREGRINE_CLOSE_MAP
(
	1	= '',
	2	= '@Serial',
	3	= PROBLEM_NUMBER,
	4	= '',
	5	= '',
	6	= '',
	7	= '',
	8	= '',
	9	= '',
	10	= '',
	11	= '',
	12	= '',
	13	= '',
	14	= '',
	15	= '',
	16	= '',
	17	= '',
	18	= '',
	19	= '',
	20	= '',
	21	= '',
	22	= '',
	23	= '',
	24	= '',
	25	= '',
	22	= '',
	23	= '',
	24	= ''
);

Create Journal Map

The journal map facility allows you to maintain a textual history of an event with the Cisco Info Center journal information.

The create journal map command allows you to specify which Cisco Info Server fields must be populated in which ServiceCenter fields when updating journal information.

CREATE MAPPING PEREGRINE_JOURNAL_MAP
(
	1	= '',
	2	= '@Serial',
	3	= PROBLEM_NUMBER,
	4	= '',
	5	= JOURNAL_TEXT,
	6	= '',
	7	= '',
	8	= '',
	9	= '',
	10	= '',
	11	= '',
	12	= '',
	13	= '',
	14	= '',
	15	= '',
	16	= '',
	17	= '',
	18	= '',
	19	= '',
	20	= '',
	21	= '',
	22	= '',
	23	= '',
	24	= '',
	25	= '',
	22	= '',
	23	= '',
	24	= ''
);

Create the Info Gateway Conversions Table

The conversion table facility allows you to specify certain data conversions to take place between particular ServiceCenter and Cisco Info Server fields. For example, ServiceCenter users require a status field to be alphabetic and to have a particular value. Cisco Info Center may hold these as numeric values.

Note, the Cisco Info Server SQL definition file must be updated to include the conversions database. See Section, "Changing the SQL Definition File", for further information.

All conversions must be supplied before the Info Gateway can be operational.

The Conversion Table Utility

A graphical user interface utility has been provided to define the conversions. To run the utility, specify the command:

nco_gwconv

The Peregrine Conversion window is displayed, as shown in the Figure 6-2.


Figure 6-2: Peregrine Info Gateway Conversion Window


The Info Gateway Conversion window Title bar contains the server name and table name being used. The work area displays any existing conversions. Conversion details are displayed in three columns. The first column contains the Cisco Info Server table column name. The second column contains the values associated with the column. The third column contains the converted value.

To add a new conversion:

Step 1 Click on the New button.

Step 2 Click in the Column field then specify the Cisco Info Server column name.

Step 3 Specify the Cisco Info Server value in the OS Value field.

Step 4 Specify the conversion value in the Conversion field.

Step 5 Click on the Apply button, then click on the Close button.

To update an existing conversion:

Step 1 Highlight the conversion to be updated by clicking on the item in the conversion list. The conversion details are populated with the existing values.

Step 2 Update the values as required.

Step 3 Click on the Apply button, then click on the Close button.

To delete a conversion:

Step 1 Highlight the conversion to be updated by clicking on the item in the conversion list. The conversion details are populated with the existing values.

Step 2 Click on the Delete button. You can undo the delete by clicking on the Undo button.

Step 3 Click on the Apply button, then click on the Close button.

Manually Editing the Conversion Table

The conversion table is Cisco Info Server SQL based. This means you can make full use of the Cisco Info Server SQL. The conversion expects information to be supplied in columns, enclosed in parenthesis, where the columns indicate:

column 1 = key field name
column 2 = column name
column 3 = Cisco Info Server value
column 4 = conversion value

In the following example, the numeric value of the Cisco Info Server Severity field, either (0, 1, 2, 3, 4, or 5) is converted to ServiceCenter textual values, either (Clear, Indeterminate, Low, Routine, High, or Critical). User name values are also converted. They can be specified by using the SQL input script, nco_sql.

use database conversions;
go
 
insert into peregrine values ('Severity0','Severity','0','Clear');
insert into peregrine values ('Severity1','Severity','1','Indeterminate');
insert into peregrine values ('Severity2','Severity','2','Low');
insert into peregrine values ('Severity3','Severity','3','Routine');
insert into peregrine values ('Severity4','Severity','4','High');
insert into peregrine values ('Severity5','Severity','5','Critical');
go
 
insert into peregrine values ('OwnerUID0','OwnerUID','0','Root');
insert into peregrine values ('OwnerUID65534','OwnerUID','65534','Nobody');
 
go

Changing the SQL Definition File

You must make additions to the Cisco Info Center SQL definition file to create the conversions database and table. The following example shows the SQL statements required. Restart the Cisco Info Server to apply any SQL changes you make:

create database conversions;
use database conversions;
create table peregrine (
KeyField 		char(255),
Colname 		char(255),
OSValue 		char(255),
Conversion 		char(255),
unique		(KeyField),
permanent);

Editing the Info Gateway Action SQL Files

The Info Gateway action SQL files determine what actions should take place at the Cisco Info Server when there is new or changed ServiceCenter information. The files are Cisco Info Server SQL based, therefore, you have all of the language facilities available to you. You must specify action SQL for each of the event types, open, update, and close.

When the SQL is being processed, data fields are expanded, conversions are resolved, and Cisco Info Server fields are populated. The following example updates the Severity field:

update alerts.status set Severity = $(23:Severity);

In the previous statement, the data usage is resolved as follows:

    1. The $ symbol signifies an expansion statement and information enclosed within the parentheses must be resolved.

    2. The 23 statement specifies that ServiceCenter field number 23 is being used.

    3. The Severity statement specifies that severity conversions must be used and applied. The colon is a statement separator.

    4. The Cisco Info Server field is updated with the resolved value.

The Info Gateway makes extensive use of certain data fields that are kept in cache storage. One of the reasons this mechanism is provided is to ensure unique identification of Cisco Info Center alerts at all times. They may or may not be used in ServiceCenter records. These fields can be used in the SQL at any time and increase performance. The cache fields that are always available are:

Opening the Action SQL File

The open action SQL file determines what action should be taken at the Cisco Info Server when a problem ticket is opened.

The following example updates the Cisco Info Server and sets three data fields. All three fields are resolved, with Severity populated with ServiceCenter field number 23 and applied conversions. The Agent field is equivalent to ServiceCenter field number 9.

#
# The Peregrine Info Gateway Problem Open Action SQL file
#
update alerts.status set Severity = $(23:Severity), Agent = '$(9)'
where Serial = $(Serial);

Updating the Action SQL File

The update action SQL file determines what action should be taken at the Cisco Info Server when a problem ticket is updated.

The following example updates the Cisco Info Server and sets two data fields. The Agent field is resolved to a concatenation of ServiceCenter fields numbers 4 and 9.

#
# The Peregrine Info Gateway Problem Update Action SQL file
#
update alerts.status set Agent = '$(4) $(9)' where Serial = $(Serial);

Closing the Action SQL File

The close action SQL file determines what action should be taken at the Cisco Info Server when a problem ticket is closed.

The following example performs both an Cisco Info Server delete and update. The delete statement removes the associated event for the problem ticket.

The update statement updates any associated events on the same node as ServiceCenter field five with a severity of 1 (clear).

#
# The Peregrine Info Gateway Problem Close (Deletion) Action SQL file
#
delete from alerts.status where Serial = $(Serial);
 
update alerts.status set Severity = 1 where Node = '$(5)';

Registering ServiceCenter Event Types

Two ServiceCenter applications are used to pass events and tickets between ServiceCenter Event Services and ServiceCenter Problem Management:

The axces.apm application processes PMO, PMU, and PMC events passed into ServiceCenter from the Info Gateway. The axces.write application feeds back Problem Management Problem IDs of PMO events to the Info Gateway.

You must register four event types that use these two applications allowing ServiceCenter to interpret the events it receives from the Info Gateway, and then feed back the Problem Management Problem IDs of PMO events. The event types you must create are shown in Table 6-15. By default, these event types exist when you install ServiceCenter. This section is provided as a reference to the defaults required by the Info Gateway.


Table 6-15:
Event Type Mapping Application Description

PMO

Default problem open

axces.apm

Processes new PMO events received from the Info Gateway.

PMO

Default problem open

axces.write

Feeds back Problem IDs of PMO events to the Info Gateway.

PMU

Default problem update

axces.apm

Processes PMU events received from the Info Gateway.

PMC

Default problem close

axces.apm

Processes PMC events received from the Info Gateway.

ServiceCenter Event Types

Event types are created from the Event Registration window. To access this window, select the Utilities->Event Services->Administration->Register option, then click on the Application tab.

The following two sections provide examples on how to register event types using axces.apm and axces.write.

PMO Input Event

The axces.apm application processes an input PMO event when the execute condition resolves to true. Figure 6-3 shows the axces.apm application view of the Event Registration window. This example contains all of the required parameters. See Table 6-16 for a description of the parameters.


Figure 6-3: PMO Input Event Registration Example Window


The fields used in this example are described in Table 6-16.


Table 6-16:
Parameter Name Parameter Value Description

record

$axces

Represents the event-in record.

prompt

evmap in $axces.register

Name of the event map used in conversion.

string1

problem

Name of the file in ServiceCenter where data is stored.

text

open

Specifies the action to perform. In this case open.

query

$ax.query.passed

The query string to select existing ticket for update.

boolean1

evstatus in $axces~#"error"

This is the key field for the Info Gateway. The logical field specifies whether an event-out record should be written upon transaction completion. This example resolves to true when the transaction completes with no error, then an output event is written. This should always resolve to true.

cond.input

$ax.open.flag

Whether or not to process additional records when more than one is selected.

PMO Input Event Registration Example Fields

The PMO input event registration should already be defined within the ServiceCenter system. When problem IDs are not fed back to the Cisco Info Server it is usually because the boolean1 parameter in axces.apm has been set to False.

PMO Output Event

The axces.write application writes an output event when the execute condition resolves to true. It is this registration that enables the axces.apm application to write a PMO output event. Figure 6-4 shows the axces.write application view of the Event Registration window. This example has all of the required parameters. See Table 6-17 for a description of the parameters.


Figure 6-4: Peregrine Output Event Registration Example Window


The fields in the above figure are described in Table 6-17.


Table 6-17: PMO Output Event Registration Example Fields
Parameter Name Parameter Value Description

record

$axces

Represents the record to be written, in this case $axces.

name

pmo

pmo as this is the name of registration type.

string1

^

Defines the record field separator.

query

evuser in $axces

Uses the value held in the evuser field of the input PMO event to create the output event.

prompt

nullsub (evusrseq in $axces, evsysseq in $axces)

This parameter defines the value for the evusrseq of the output event. In this case, the nullsub function uses the evusrseq of the input event when one exists, if not, the evsysseq is used.

Note: The Info Gateway uses the evusrseq field to track returned output events as responses to its input events. This means that if the input event has an evusrseq, it must be copied to the output event evusrseq field.

For both the input and output PMO registrations, the event map is provided in the Event Registration - Basics window. The map definitions can then be found in the Event Maps utility within Event Services. This enables you to identify which field of the constructed ServiceCenter record is the relevant field in the problem record.

Create ServiceCenter Mappings

The fields of events passed between ServiceCenter and the Info Gateway must be mapped to each other so the applications can interpret the information they receive from one another. The mappings for the Info Gateway are described in Section, "Create the Info Gateway Configuration File". You also must create mappings within ServiceCenter.

You must create mappings for each field passed into and out of ServiceCenter for PMO, PMU, and PMC events. However, when you are using the default equipment problem category, you should use the default maps: problem open, problem update, and problem close. Each mapping contains input and output type fields. The following sections contain examples of the fields you must configure for each type of mapping, when you are not using the default equipment category.

Problem Open Mapping Input Fields

Table 6-18 shows the fields you would use to create an input map for PMO events for the default problem category equipment. Note that the fields are in the same order as the PMO fields in the Info Gateway PMO mapping.


Table 6-18: Example Problem Open Mapping Input Fields
Sequence Position File Name Field Name

1

1

problem

logical.name

1

2

problem

network.name

1

3

problem

reference.no

1

4

problem

cause.code

1

5

problem

$ax.field.name

1

6

problem

action,2

1

7

problem

action,3

1

8

problem

network.address

1

9

problem

type

1

10

problem

category

1

11

problem

domain

1

12

problem

objid

1

13

problem

version

1

14

problem

model

1

15

problem

serial.no.

1

16

problem

vendor

1

17

problem

location

1

18

problem

contact.name

1

19

problem

contact.phone

1

20

problem

resolution

1

21

problem

assignee.name

1

22

problem

priority.code

1

23

problem

failing.component

1

24

problem

system

Problem Open Mapping Output Fields

Table 6-19 shows the fields you would use to create an output map for PMU events for the default problem category equipment.


Table 6-19: Example Problem Update Mapping Output Fields
Sequence Position File Name Field Name

1

1

none

assignee.email

1

2

none

number

1

3

none

category

1

4

none

open.time

1

5

none

opened.by

1

6

none

actor

1

7

none

priority.code

1

8

none

severity.code

1

9

none

assignment

1

10

none

referred.to

1

11

none

alert.time

1

12

none

status

1

13

none

vendor

1

14

none

reference.no

1

15

none

contact.time

1

16

none

backup.start

1

17

none

cause.code

1

18

none

logical.name

1

19

none

group

1

20

none

job.name

1

21

none

location

1

22

none

version

1

23

none

type

1

24

none

abend.code

1

25

none

model

1

26

none

action

1

27

none

key.words

1

28

none

reference.no

1

29

none

id

1

30

none

downtime.start

1

31

none

assignee.name

1

32

none

contact.name

1

33

none

caller.id

1

34

none

contact.phone

1

35

none

network.name

1

36

none

open.group

1

37

none

update.action

Problem Update Mapping Input Fields

Table 6-20 shows the fields you use to create an input map for PMU events for the default problem category equipment. Note, the fields are in the same order as the PMU fields in the Info Gateway PMU mapping.


Table 6-20: Problem Update Mapping Input Fields
Sequence Position File Name Field Name

1

1

problem

logical.name

1

2

problem

network.name

1

3

problem

number

1

4

problem

cause.code

1

5

problem

update.action

1

6

problem

action,2

1

7

problem

action,3

1

8

problem

network.address

1

9

problem

key.words

1

10

problem

category

1

11

problem

domain

1

12

problem

objid

1

13

problem

version

1

14

problem

model

1

15

problem

serial.no.

1

16

problem

vendor

1

17

problem

location

1

18

problem

contact.name

1

19

problem

contact.phone

1

20

problem

reference.no

1

21

problem

assignee.name

1

22

problem

priority.code

1

23

problem

failing.component

1

24

problem

system

Problem Update Mapping Output Fields

Table 6-21 shows the fields you use to create an output map for PMU events for the default problem category equipment.


Table 6-21: Example Problem Update Mapping Output Fields
Sequence Position File Name Field Name

1

1

none

assignee.email

1

2

none

number

1

3

none

category

1

4

none

open.time

1

5

none

opened.by

1

6

none

actor

1

7

none

priority.code

1

8

none

severity.code

1

9

none

assignment

1

10

none

referred.to

1

11

none

alert.time

1

12

none

status

1

13

none

vendor

1

14

none

reference.no

1

15

none

contact.time

1

16

none

backup.start

1

17

none

cause.code

1

18

none

logical.name

1

19

none

group

1

20

none

job.name

1

21

none

location

1

22

none

version

1

23

none

type

1

24

none

abend.code

1

25

none

model

1

26

none

action

1

27

none

key.words

1

28

none

reference.no

1

29

none

id

1

30

none

downtime.start

1

31

none

assignee.name

1

32

none

contact.name

1

33

none

caller.id

1

34

none

contact.phone

1

35

none

network.name

1

36

none

open.group

1

37

none

update.action

Problem Close Mapping Input Fields

Table 6-22 shows the fields you use to create an input map for PMC events for the default problem category equipment. Note, the fields are in the same order as the PMC fields in the Info Gateway PMC mapping.


Table 6-22: Example Problem Close Mapping Input Fields
Sequence Position File Name Field Name

1

1

problem

logical.name

1

2

problem

network.name

1

3

problem

number

1

4

problem

resolution.code

1

5

problem

resolution

1

6

problem

resolution,2

1

7

problem

resolution,3

1

8

problem

network.address

1

9

problem

key.words

1

10

problem

category

1

11

problem

domain

1

12

problem

objid

1

13

problem

version

1

14

problem

model

1

15

problem

serial.no.

1

16

problem

vendor

1

17

problem

location

1

18

problem

contact.name

1

19

problem

contact.phone

1

20

problem

reference.no

1

21

problem

assignee.name

1

22

problem

priority.code

1

23

problem

failing.component

1

24

problem

system

Problem Close Mapping Output Fields

Table 6-23 shows the fields you use to create an output map for PMC events for the default problem category equipment.

Table 6-23: Example Problem Close Output Fields
Sequence Position File Name Field Name

1

1

none

assignee.email

1

2

none

number

1

3

none

category

1

4

none

close.time

1

5

none

closed.by

1

6

none

actor

1

7

none

priority.code

1

8

none

severity.code

1

9

none

assignment

1

10

none

referred.to

1

11

none

alert.time

1

12

none

status

1

13

none

vendor

1

14

none

reference.no

1

15

none

contact.time

1

16

none

backup.start

1

17

none

cause.code

1

18

none

logical.name

1

19

none

group

1

20

none

job.name

1

21

none

location

1

22

none

version

1

23

none

type

1

24

none

abend.code

1

25

none

model

1

26

none

resolution

1

27

none

key.words

1

28

none

reference.no

1

29

none

id

1

30

none

downtime.start

1

31

none

assignee.name

1

32

none

contact.name

1

33

none

caller.id

1

34

none

contact.phone

1

35

none

network.name

1

36

none

open.group

1

37

none

action

1

38

none

update.action

Configure ServiceCenter Format Control Subroutines

When problems are updated and closed by ServiceCenter operators, a record must be written to the Event Out queue. The record contains information as defined in the ServiceCenter output event map. The Format Control utilities generate these events for the Info Gateway. This is achieved by defining format control subroutines which execute the correct application and pass it the necessary parameters. In addition, problem management can have different problem categories. The subroutines must be defined for each problem category when they are to be used in the Info Gateway.

The Format Control subroutines must only be configured for problem management update and close. They need not be defined for problem open. The examples used here use a problem management category of equipment.

To configure Format Control, you must create an axces.write subroutine for the problem categories update and close. The configuration must be completed on the Format Control Maintenance - Subroutines window. The window view must be in Long View mode to complete the details. To access this window:

1. Select the Utilities->Tools->Format Control menu option.

2. Specify either problem.equipment.update or problem.equipment.close in the name field, then press Return. This example assumes you are using the default equipment category. The Format Control Maintenance window is displayed.

3. Select the Options menu's Subroutines option. The Format Control Maintenance - Subroutines window is displayed.

4. Select the Options menu's Show Expanded Form option.The subroutine entry fields are displayed.

5. Specify the field values as described in the following two sections.

Format Control Subroutine - Update

The format control update configuration defines what event must occur when a ServiceCenter problem ticket is updated.

Figure 6-5shows the Long View of the Format Control Maintenance Subroutines window. This example has all of the parameters required for a problem category of equipment.


Figure 6-5: Format Control Maintenance Subroutines Window


Table 6-24 describes the fields shown in this example.


Table 6-24: Format Control Subordinate - Update Fields
Field Name Description

Application Name

This must have a value of axces.write for all instances of the Info Gateway.

Names: record

This identifies the record to be written. $file specifies the complete problem record.

Names: name

The name of the registration type. For update it must have a value of pmu.

Names: prompt

Specifies the user sequence ID. In this example, str(number in $file) indicates the following:

1. The str function formats the contents of the specified field into a string.

2. The number statement is the name of the field when to obtain the value.

3. The in $file statement means use the $file value for the record parameter.

Names: query

Specifies the user name. ServiceCenter defaults to the operator name, however, the Info Gateway requires a user name of Omnibus. When Omnibus is not used, there may be event sequencing errors.

Error Message

When the record could not be written, this message is logged. This field is a free format text field.

Add

Specifies criteria for the action (pmu) to be taken. This statement must resolve to true, if not, the update does not occur.

Update

Same as Add. This must be specified with the same statement.

Format Control Subroutine - Close

The Format Control close configuration defines what event must occur when event services closes a problem ticket.

The following figure shows the Long View of the Format Control Maintenance Subroutines window. This example has all of the parameters required for a problem category of equipment.


Figure 6-6: Format Control Maintenance - Subordinates


Table 6-25 describes the fields shown in this example.


Table 6-25: Format Control Subordinates - Close Fields
Field Name Description

Application Name

This must have a value of axces.write for all instances of the Info Gateway.

Names: record

This identifies the record to be written. $file specifies the complete problem record.

Names: name

The name of the registration type. For close it must have a value of pmc.

Names: prompt

Specifies the user sequence ID. In this example, str(number in $file) indicates the following:

1. The str function formats the contents of the specified field into a string.

2. The number statement is the name of the field to obtain the value.

3. The in $file statement means use the $file value for the record parameter.

Names: query

Specifies the user name. ServiceCenter defaults to the operator name, however, the Info Gateway requires a user name of Omnibus. When Omnibus is not used, there may be event sequencing errors in the Info Gateway.

Error Message

When the record could not be written, this message is logged. This field is a free format text field.

Add

Specifies criteria for the action (pmu) to be taken. This statement must resolve to true, if not, the close does not occur.

Delete

Same as Add. This must be specified with the same statement.

Peregrine Info Gateway Error Messages

This section contains error messages that can be issued by the Info Gateway. Each message is usually followed by two bullet points. The first provides further details on the error. The second provides a problem resolution or some indication of where to look for further details on the error.


Error Message   Peregrine Writer <name>: Memory allocation failure.


Error Message   Peregrine Writer <name>: Failed to re-acquire alert details from OS.


Error Message   Peregrine Writer <name>: Invalid data type for problem number feedback field.


Error Message   Peregrine Writer <name>: Serial <serial_num> already in serial Cache. Cannot add.


Error Message   Peregrine Writer <name>: Serial <serial_num> not found in serial cache. Cannot Update/Delete.


Error Message   Peregrine Writer <name>: Failed to construct path to Peregrine Read/Write Module.


Error Message   Peregrine Writer <name>: Failed to find the Peregrine Read/Write Module <name>.


Error Message   Peregrine Writer <name>: Incorrect permissions on the Peregrine module binary <name>.


Error Message   Peregrine Writer <name>: Failed to construct the argument list for Peregrine Module.


Error Message   Peregrine Writer <name>: Failed to start the OS-SC Writer.


Error Message   Peregrine Writer <name>: Failed to start the SC-OS Reader.


Error Message   Peregrine Writer <name>: Failed to create the Serial Cache Mutex.


Error Message   Peregrine Writer <name>: Failed to start the SC-to-OS service thread.


Error Message   Peregrine Writer <name>: Failed to send a SIGTERM to shutdown SC Writer.


Error Message   Peregrine Writer <name>: Failed to send a SIGTERM to shutdown SC Reader.


Error Message   Peregrine Writer <name>: Map '<map name>' is not the journal map and cannot contain the 'JOURNAL_TEXT' map item in Peregrine Writer '<writer name>'.


Error Message   Peregrine Writer <name>: Failed to send SC Event to the SC Writer module.


Error Message   Peregrine Writer <name>: Failed to wait for return from the SC Writer module.


Error Message   Peregrine Writer <name>: Failed to read the status return message from the SC Writer module.


Error Message   Peregrine Writer <name>: Failed to send event to ServiceCenter.


Error Message   Peregrine Writer <name>: SC Writer Module experienced Fatal Error.


Error Message   Peregrine Writer <name>: Failed to build serial index.


Error Message   Peregrine Writer <name>: Failed to build server serial index.


Error Message   Peregrine Writer <name>: Failed to build server name index.


Error Message   Peregrine Writer <name>: Failed to find field <Field Number> in SC Event.


Error Message   Peregrine Writer <name>: Invalid field name for expansion on action SQL.


Error Message   Peregrine Writer <name>: Unenclosed field expansion request in action SQL <action sql>.


Error Message   Peregrine Writer <name>: Failed to send SQL command to Cisco Info Server. SC-to-OS Feedback failed.


Error Message   Peregrine Writer <name>: Failed to correctly extract the problem number for returned problem open event for serial <serial number>.


Error Message   Peregrine Writer <name>: Invalid problem number. Field empty.


Error Message   Peregrine Writer <name>: Error in the construction of the Open action SQL.


Error Message   Peregrine Writer <name>: Failed to create SCAuto Event for journal update.


Error Message   Peregrine Writer <name>: Failed to send journal update event to SC.


Error Message   Peregrine Writer <name>: Failed to find the COUNTER_PART attribute for the writer. This is necessary due to bi-directional nature.


Error Message   Peregrine Writer <name>: Is not a name for an Cisco Info Server reader.


Error Message   Peregrine Writer <name>: Reader <name>was not found for counter part.


Error Message   Peregrine Writer <name>: Failed to read the conversions table.


Error Message   Peregrine Writer <name>: Failed to read the system sequence file. Assuming 0000 start.


Error Message   Peregrine Writer <name>: Invalid system sequence number found in the sequence file <seq num>. Assuming 0 start.


Error Message   Peregrine Writer <name>: SC Event received with error in the evusrseq field.


Error Message   Peregrine Writer <name>: Failed to find serial <serial num> in cache for return PMO event.


Error Message   Peregrine Writer <name>: Problem number already determined for serial <serial num>.


Error Message   Peregrine Writer <name>: Failed to find PM <number> in cache for return PMU event.


Error Message   Peregrine Writer <name>: Update Feedback Failed.


Error Message   Peregrine Writer <name>: Failed to find PM <number> in cache for return PMC event.


Error Message   Peregrine Writer <name>: Close Feedback Failed.


Error Message   Peregrine Writer <name>: Failed to read SC event from SC Reader Module.


Error Message   Peregrine Writer <name>: Received event of type <event type> which was unexpected.


Error Message   Peregrine Writer <name>: Failed to block on data feed from SC Reader Module.


Error Message   Peregrine Writer <name>: Failed to save current eventout system sequence number.


Error Message   Peregrine Writer <name>: Failed to shutdown SCAuto Reader/Writer Modules.


Error Message   Peregrine Writer <name>: Failed to disconnect feedback connection.


Error Message   Peregrine Writer <name>: Failed to delete problem ticket from cache for serial <serial num>.


hometocprevnextglossaryfeedbacksearchhelp
Posted: Thu Apr 1 10:52:35 PST 1999
Copyright 1989-1999©Cisco Systems Inc.