Table of Contents

Cisco Info Server Reader
Cisco Info Server Writer

Mapping

Example
Writer Attributes
Example

Remedy ARS Writer

Remedy Compatibility
Initial Setup
Mapping

Example

Writer Attributes

Example

Notes

Flat File Writer

Mapping

Example

Writer Attributes

Example

Informix Writer

Informix Compatibility
Initial Setup
Mapping

Example

Writer Attributes

Example

Notes

Connecting to Informix
Time Handling Between the Info Gateway and Informix

Socket Writer

Mapping

Example

Writer Attributes

Example

Sybase Writer

Sybase Compatibility
Initial Setup
Mapping

Example

Writer Attributes

Example

Notes

Connecting to Sybase
Time Handling Between the Info Gateway and Sybase

SNMP Compatibility
Initial Setup
Mapping

Example

Writer Attributes
Example
Notes

ServiceView Writer

Mapping

Example

Writer Attributes

Example

Notes

Oracle Writer

Oracle Compatibility
Initial Setup
Mapping

Example

Writer Attributes

Example

Notes

Connecting to Oracle
Time Handling Between the Info Gateway and Oracle

Peregrine ServiceCenter Gateway

ServiceCenter Compatibility
Info Gateway Operation

Reader, Writer, and Route
OS-SC and SC-OS Routes
R/W Modules
SCAuto (Integration Server)
Event Queues
Event Services
Problem Management System
ServiceCenter Record Category
Sequence Numbers
R/W Module Log Files

Peregrine ServiceCenter Users
Info Gateway Configuration
Create the Info Gateway Configuration File

Writer Attributes
ServiceCenter Writer Mapping
Create Open Map Example
Create Update Map Example
Create Close Map
Create Journal Map

Create the Info Gateway Conversions Table

The Conversion Table Utility
Manually Editing the Conversion Table
Changes to SQL Definition File

Edit the Info Gateway Action SQL Files

Open Action SQL File
Update Action SQL File
Close Action SQL File

Register ServiceCenter Event Types

PMO Input Event
PMO Output Event

Create ServiceCenter Mappings

Problem Open Mapping Input Fields
Problem Open Mapping Output Fields
Problem Update Mapping Input Fields
Problem Update Mapping Output Fields
Problem Close Mapping Input Fields
Problem Close Mapping Output Fields

Configure ServiceCenter Format Control Subroutines

Format Control Subroutine - Update
Format Control Subroutine - Close

Peregrine Info Gateway Error Messages

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

• Cisco Info Server Writer

• Remedy ARS Writer

• Flat File Writer

• Informix Writer

• Socket Writer

• Sybase Writer

• SNMP (Forwarder) Writer

• ServiceView Writer

• Oracle Writer

• Peregrine ServiceCenter Gateway

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 ] ]...

) ;

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.

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 following 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 following versions of Remedy ARS:

• Remedy ARS 2.x and above.

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>

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.

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.

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'
);

Writer Attributes

The creation of a Writer for Remedy ARS requires the following 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]]...
) ;
 

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 following attributes:

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:

• Informix 7.1x Online

• Informix 7.1x SE

• Informix 7.2x Online

• Informix 7.2x SE

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 ]]...
) ;
 

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".

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 following 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'
);
 

Notes

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.

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]]...
);

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 following 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:

• Sybase SQL Server 10.x

• Sybase SQL Server 11.x

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 ]]...
);
 

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".

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 following 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'
);
 

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.

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>

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 following 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>

Example

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

Writer Attributes

The creation of a Writer for ServiceView requires the following 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.

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

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 ]]...
);
 

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.

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 following 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'
);
 

Notes

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.

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:

• Problem Management Open (PMO)

• Problem Management Update (PMU)

• Problem Management Close (PMC)

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-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, "Edit 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, "Register 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.

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:

• open map (for PMO event types)

• update map (for PMU event types)

• close map (for PMC event types)

• journal map (for all event types)

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

CREATE MAPPING <mappingname>

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

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, "Changes to 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.

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

Changes to 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);

Edit 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:

• Serial

• ServerSerial

• ServerName

• PROBLEM_NUMBER

Open 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);

Update 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);

Close 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)';

Register ServiceCenter Event Types

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

• axces.apm

• axces.write

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.

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.

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

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.

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 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.

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

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

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.

• Insufficient memory available for the Writer to perform an operation.

• Release memory by stopping unnecessary processes. Increase the machine's available swap space or add more physical memory.

• The Info Gateway was unable to acquire the necessary data for its cache when it received a notification for an event not in the cache. This occurs when the Info Gateway is stopped.

• The problem number feedback field was found not to be a character field.

• Specify a feedback field which is of type character.

• An insert into the Cisco Info Server with the same serial number occurred. This should not occur, therefore, the record can not be added to the cache.

• An event update/delete failed to find the necessary alert details in the Writer's serial cache.

• Failed to determine the path to the Peregrine read/write module executable.

• Failed to access the Peregrine read/write module executable in $OMNIHOME/bin/arch.

• Verify the existence and location of the module.

• The Peregrine read/write module was found, however, it does not have execution or read permissions.

• Apply the correct permissions to the file.

• Failed to construct the launch request for the Peregrine read/write module due to memory limitations.

• Release memory by stopping unnecessary processes. Increase the machine's available swap space or add more physical memory.

• The Cisco Info Server to ServiceCenter Writer module failed to start.

• Examine the Writer module log file for further messages.

• The ServiceCenter to Cisco Info Server Reader module failed to start.

• Examine the Reader module log file for further messages.

• Failed to construct the data protection structure due to insufficient memory resources.

• Release memory by stopping unnecessary processes. Increase the machine's available swap space or add more physical memory.

• The main Peregrine Writer failed to start the ServiceCenter to Cisco Info Server handler thread. This is due to insufficient memory resources.

• Release memory by stopping unnecessary processes. Increase the machine's available swap space or add more physical memory.

• Failed to stop the ServiceCenter Writer module. This may result in the Info Gateway port being locked.

• Find the process in the process list and halt it.

• Failed to stop the ServiceCenter Reader module. This may result in the Info Gateway port being locked.

• Find the process in the process list and halt it.

• The special mapping name JOURNAL_TEXT was contained within a map that was not specified to be the journal map. The mapping name references the position at which journal text should be positioned in the journal PMU event.

• Remove the names from the incorrect map.

• A problem was detected with the connection to the ServiceCenter Writer module.

• Examine the ServiceCenter Writer module log file for further messages.

• Examine the ServiceCenter Writer module log file to determine the module error.

• Examine the ServiceCenter Writer module log file to determine the module error.

• Examine the ServiceCenter Writer module log file to determine the module error.

• Unexpected error occurred when the ServiceCenter Writer module terminated.

• Examine the ServiceCenter Writer module log file to determine the module error.

• The ServiceCenter Writer was unable to construct the fast access jump index for the Serial index.

• Check the alerts.status table definitions and ensure the field exists.

• The ServiceCenter Writer was unable to construct the fast access jump index for the ServerSerial index.

• Check the alerts.status table definitions and ensure the field exists.

• The ServiceCenter Writer was unable to construct the fast access jump index for the ServerName index.

• Check the alerts.status table definitions and ensure the field exists.

• The field specified in the action SQL could not be found.

• Check the full numbers in the returned event map. Specifying the 25th field in a 24 field list also generates this error, as the 25th field does not exist.

• An unknown field name was specified in the action SQL for expansion that was neither Serial, ServerSerial, ServerName, or PROBLEM_NUMBER.

• Correct action SQL.

• An unenclosed field expansion was found in the action SQL.

• This is an expansion not ended with a close parenthesis. Supply the parenthesis.

• An error occurred when a SQL statement was sent to the feed back Cisco Info Server.

• When the feed back involved the sending of user defined action SQL, check complete syntax of the action SQL.

• The Info Gateway could not successfully extract the problem number for the returned ServiceCenter PMO event.

• The field index, specified as the field containing the problem number in the returned ServiceCenter PMO event, contained an invalid problem number.

• Examine the PMO output event mapping and check which field contains the problem number.

• An error occurred when constructing the open action SQL or the expansion definitions.

• Check the SQL syntax and expansion definitions in the open action SQL.

• An error occurred in the creation of the ServiceCenter event due to insufficient resources.

• Release memory by stopping unnecessary processes. Increase the machine's available swap space or add more physical memory.

• Examine the ServiceCenter Writer module log file for further details on this error.

• The COUNTER_PART attribute is a mandatory attribute that was not specified in the Writer definition.

• Add the correct attribute to the Writer definition and restart the Info Gateway.

• The name specified in the FEEDBACK_SERVER attribute was not the name of an object server Reader.

• Add the correct attribute to the Writer definition and restart the Info Gateway.

• The specified counter part Reader was not found in the Info Gateway configuration.

• Add the correct Reader name in the configuration file and restart the Info Gateway.

• The Writer failed to read the conversion table.

• Check whether the conversion files exists. Check the file has the correct field definitions.

• The system sequence number could not be read or accessed.

• Check the existence of the file and that it has read permissions in $OMNIHOME/var.

• Corrupted sequence file.

• Delete the sequence file and restart the Info Gateway.

• A ServiceCenter event was received that contained an invalid value for the evusrseq field.

• Check the ServiceCenter format control settings for the generation of output events.

• Received and returned a PMO event, sent by the Info Gateway for an opened problem, that was not in the cache and could not be obtained again.

• A second return PMO event was received for the same serial number. The problem ticket has already been received.

• Configure ServiceCenter to only send one PMO return.

• A PMU event was received for a problem that no longer is in the cache and could not be obtained again.

• The alert may no longer exist in the Cisco Info Server. Check the Cisco Info Server.

• An error occurred while attempting to feed back update details to the Cisco Info Server.

• Examine error messages previous to this message to determine cause of problem.

• A PMC event was received for a problem that is no longer in the cache and could not be obtained again.

• The alert may no longer exist in the Cisco Info Server. Check the Cisco Info Server.

• An error occurred while attempting to feed back close details to the Cisco Info Server.

• Examine error messages previous to this message to determine cause of problem.

• Examine the ServiceCenter Reader module log file for further details on this error.

• An unexpected event was read by the ServiceCenter Writer module.

• The Writer module should only read PMO, PMU, and PMC event types. The event returned is ignored.

• Examine the ServiceCenter Reader module log file for further details on this error.

• Could not write the current event out sequence number.

• Check the write permissions on the sequence file in $OMNIHOME/var.

• Examine the ServiceCenter Reader/Writer module log files for further details on this error.

• This is a warning message.

• No action is required.

• This is a warning message.

• No action is required.

Posted: Wed Mar 24 13:47:43 PST 1999
Copyright 1989-1999©Cisco Systems Inc.