Properties and command line options

You use properties to define the operational environment of the gateway. You can override the default values by editing the properties file or by using the command line options.

The following tables describe the properties available with the Gateway for IBM Maximo IT. For more information about generic and Inter-Process Communication (IPC) properties and command line options, see the IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide.

The following sections describe the properties used to configure the gateway:

Common Tivoli Netcool/OMNIbus properties

Table 1 lists the available common properties.

Table 1. Common Tivoli Netcool/OMNIbus properties
Property name Command line option Description

ConfigCryptoAlg string

-configcryptoalg string

Use this property to specify the encryption algorithm that the gateway uses.

The default is AES.

ConfigKeyFile string

-configkeyfile string

Use this property to specify the encryption key used with the encrypted data.

The default is "".

Connections integer

-connections integer

Use this property to specify the maximum number of client connections that can be made to the gateway server.

The default is 30.

Help boolean

-help boolean

Use this property to instruct the gateway to display application help information on startup and exit.

The default is FALSE.

MaxLogFileSize integer

-maxlogfilesize integer

Use this property to specify the size (in bytes) that the gateway allocates for the log file. When the log file reaches this size, the gateway renames the log file by appending the suffix .old and creates a new log file.

The default is 1024.

MessageLevel string

-messagelevel string

Use this property to specify the reporting level of the log file messages.

The default is warn.

MessageLog string

-messagelog string

Use this property to specify the location of the message log file.

The default is $OMNIHOME/log/NCO_GATE.log.

Name string

-name string

Use this property to specify the name of the current gateway instance. If you want to run multiple gateways on one machine, you must use a different name for each instance.

The default is GAT_TSRM.

Props.CheckNames boolean

No command line equivalent.

Use this property to instruct the gateway to shut down if any property in the properties file is set to an invalid value.

The default is TRUE.

PropsFile string

-propsfile string

Use this property to specify the location of the gateway properties file.

The default is $OMNIHOME/etc/NCO_GATE.props.

UniqueLog boolean

-uniquelog boolean

Use this property to specify that log file names are made unique by adding the Process ID (PID) of the gateway to the file name.

The default is FALSE.

Version boolean

-version boolean

Use this property to instruct the gateway to display information about the application version on startup and shutdown.

The default is FALSE.

Generic gateway properties

Table 2 lists the available generic gateway properties.

Table 2. Generic gateway properties
Property name Command line option Description
Gate.CacheHashTblSize integer -cachehtblsize integer

Use this property to specify the number of elements the gateway allocates for the hash table cache.

The default is 5023.
Gate.MapFile string -mapfile string

Use this property to specify the mapping file for the gateway to use.

The default is $OMNIHOME/gates/tsrm/tsrm.map.
Gate.NGtkDebug boolean -ngtkdebug boolean

Use this property to enable the logging of NGTK library debug messages.

The default is TRUE.
Gate.PAAware integer -paaware integer

This property indicates whether the gateway is PA aware.

The default is 0 (not PA aware).

Note: This property is maintained by the PA server and is included in the properties file for information only.
Gate.PAAwareName string -paname string

This property indicates the name of the PA controlling the gateway.

The default is "".

Note: This property is maintained by the PA server and is included in the properties file for information only.
Gate.UnixAdminGrp string -unixadmingrp string

Use this property to specify the administration group to which the gateway must belong if standard UNIX authentication is used.

The default is ncoadmin.
Gate.UsePamAuth boolean -usepamauth boolean

Use this property to specify whether PAM authentication is used.

The default is FALSE.

Note: To run the gateway in FIPS 140-2 mode, you must set this property to TRUE.

Java properties

Table 3 lists the available Java™ properties.

Table 3. Java properties
Property name Command line option Description

Gate.Java.Arguments string

-javaarguments string

Use this property to specify the arguments to use when starting Java.

The default is "".

Gate.Java.ClassPath string

-javaclasspath string

Use this property to specify the environment variable used to store the location of the Java libraries.

The default is $CLASSPATH.

Gate.Java.Debug boolean

-javadebug boolean

Use this property to enable the logging of Java debug messages.

The default is TRUE.

Gate.Java.LibraryPath string

-javalibrarypath string

Use this property to specify the location of the Java libraries that will be set in the environment variable specified by the Gate.Java.ClassPath property.

The default is "".

Mapping properties

Table 4 lists the available mapping properties.

Table 4. Mapping properties
Property name Command line option Description

Gate.Mapper.Debug boolean

-mapperdebug boolean

Use this property to enable the logging of mapper debug messages.

The default is TRUE.
Gate.Mapper. ForwardHistoricJournals boolean -mapperforhistjrnl boolean

Use this property to specify whether the gateway forwards all historic journals on converted update.

The default is FALSE.

Gateway Reader-Writer properties

Table 5 lists the available gateway reader-writer properties.

Table 5. Gateway Reader-Writer properties
Property name Command line option Description

Gate.RdrWtr.Debug boolean

-debug boolean

Use this property to enable the logging of gateway reader debug messages.

The default is TRUE.

Gate.RdrWtr.Description string

-description string

Use this property to specify the application description for the reader connection. This description is used in triggers and allows you to determine which component of the gateway attempted to perform an action.

The default is ticket_gate.

Gate.RdrWtr. FailbackEnabled boolean

-readerfailbackenabled boolean

Use this property to specify whether the gateway attempts to fail back to the primary ObjectServer following a ObjectServer failover.

The default is FALSE.

Note: The gateway attempts to fail back with the frequency specified by the Gate.RdrWtr. FailbackTimeout property.

Gate.RdrWtr. FailbackTimeout integer

-readerfailbacktimeout integer

Use this property to specify the frequency (in seconds) with which the gateway attempts to fail back to the primary system following a system failover.

The default is 30 seconds.

Note: The gateway attempts to fail back to the primary ObjectServer only if the Gate.RdrWtr. FailbackEnabled property is set to TRUE.

Gate.RdrWtr.IducFlushRate integer

-iducflushrate integer

Use this property to specify the rate (in seconds) of the granularity of the reader.

If you set this property to 0, the reader gets its updates at the same granular rate as that of the ObjectServer to which it is connected.

The default is 0.

Note: If you set this property to a value greater than 0, the reader issues automatic IDUC flush requests to the ObjectServer with this frequency. This enables the reader to run at a faster granularity than that of the ObjectServer, thus enabling the gateway to capture more detailed event changes in systems where the ObjectServer itself has high granularity settings.

Gate.RdrWtr.
IgnoreStatusFilter

-ignorestatusfilter boolean

Use this property to enable or disable the passing through of journal entries from the ObjectServer to IBM Control Desk.

This property takes the following values:

FALSE: The gateway passes through journal entries.

TRUE: The gateway ignores the status filter, and so does not pass through journal entries.

The default is FALSE.

Gate.RdrWtr.LogOSSql boolean

-logossql boolean

Use this property to specify whether the gateway logs all SQL commands sent to the ObjectServer in debug mode.

The default is FALSE.

Gate.RdrWtr.Password string

-password string

Use this property to specify the password associated with the user specified by the Gate.RdrWtr.Username property.

The default is "".

Note: You must encrypt this password using the nco_g_crypt utility. For more information, see the IBM Tivoli Netcool/OMNIbus Administration Guide.

Gate.RdrWtr. ReconnectTimeout integer

-reconntimeout integer

Use this property to specify the time (in seconds) between each reconnection poll attempt that the gateway makes if the connection to the ObjectServer is lost.

The default is 30 seconds.

Gate.RdrWtr.Server string

-server string

Use this property to specify the name of the ObjectServer from which the gateway reads alerts

The default is NCOMS.

Gate.RdrWtr. TblReplicateDefFile string

-tblrepdeffile string

Use this property to specify the path to the table replication definition file.

The default is $OMNIHOME/gates/tsrm/tsrm.rdrwtr.tblrep.def.

Gate.RdrWtr.Username string

-username string

Use this property to specify the user name used to authenticate the ObjectServer connection.

The default is root.

Ticket Abstraction Layer (TAL) properties

Table 6 lists the available TAL properties.

Table 6. TAL properties
Property name Command line option Description

Gate.TAL.ForwardClear UpdatesOnly boolean

-forwardclearupdates boolean

Use this property to specify whether the gateway only sends update events to IBM Maximo IT if they are clear events.

The default is FALSE.

Gate.TAL.NBScriptFileName string

-nbscriptfilename string

Use this property to specify the name of the scripting file used for sending notification data to the ObjectServer.

The default is $OMNIHOME/gates/tsrm/tsrm.script.

Note: If you want to stop the gateway polling requests, you must leave this property blank.

Gate.TAL.TTFilterClause string

-ttfilterclause string

Use this property to specify the filter clause used in the table replication definition file for the status table.

The default is LogTicket=1.

Note: You must specify this value in the form of the SQL condition of the WITH FILTER clause. For example, if the definition file uses the filter WITH FILTER LogTicket=1, set this property to LogTicket =1.

Gate.TAL.TTJournal ChronoFieldName string

-ttjournalchronofieldname string

Use this property to specify the target field name to use in the map for the journal Chrono field.

The default is Chrono.

Gate.TAL.TTJournal ServerNameFieldName string

-ttjournalservername fieldname string

Use this property to specify the target field name to use in the map for the journal ServerName field.

The default is ServerName.

Gate.TAL.TTJournal ServerSerialFieldName string

-ttjournalserverserial fieldname string

Use this property to specify the target field name to use in the map for the journal ServerSerial field.

The default is ServerSerial.

Gate.TAL.TTNumber FieldName string

-ttnumberfieldname string

Use this property to specify the name of the field in the ObjectServer alerts.status table that stores the trouble ticket number.

The default is TTNumber.

Note: You will need to create the field that you specify with this property within Tivoli Netcool/OMNIbus. For details about how to do this, see Adding a field to the ObjectServer.

Gate.TAL.TTStateFieldName string

-ttstatefieldname string

Use this property to specify the name of the integer field in the ObjectServer alerts.status table that stores the trouble ticket state.

The default is TTState.

Gateway-specific properties

Table 7 lists the available gateway-specific properties.

Table 7. Gateway-specific properties
Property name Command line option Description

Gate.TSRM.ApiKey string

-tsrmapikey string

Use this property to specify the API key used to authenticate with IBM Maximo IT 9.1 and later. API key authentication provides enhanced security for machine-to-machine integrations.

To generate an API key, log in to the IBM Maximo Application Suite, navigate to your user profile, and create a new API key under the API Keys section.

The default is "".

Note:

When this property is set, it takes precedence over all other authentication methods regardless of the value of Gate.TSRM.MaximoAuthentication. The gateway supports three authentication methods with the following priority order:

API Key > MAXAUTH > Basic Auth.

Gate.TSRM.Attribute TokenSeparator string

-attributetokenseparator string

Use this property to specify a default separator for naming XML attribute-based tokens when processing the northbound IBM Maximo IT response.

The default is _ATTR_.

Gate.TSRM. CloseOnDeleteList string

-closeondeletelist string

Use this property to specify whether a ticket in IBM Maximo IT is closed if the Tivoli Netcool/OMNIbus event for which it was originally created is deleted.

Specify the values for this property as comma-delimited name-value pairs in the following format: "Name1='Value1', ... ,NameN='ValueN'".

For example: 
"CLASS='INCIDENT',
STATUS='RESOLVED'"

The default is "". The function is not enabled by default.

Gate.TSRM. CreateTicketTemplate string

-tsrmcreatetickettemplate string

Use this property to specify the name of the XML template used to create the ticket within IBM Maximo IT.

The default is $OMNIHOME/gates/tsrm/create.xml.template.

Gate.TSRM.DateTimeFormat string

-tsrmdatetimeformat string

Use this property to specify the date time format the gateway uses to process ticket updates sent by IBM Maximo IT to the gateway.

The default is yyyy-MM-dd\'T\'HH:mm:ssZ.

Gate.TSRM.ErrorCode FieldName string

-errorcodefieldname string

Use this property to specify the ObjectServer field to which the gateway sends the error code that identifies the nature of the IBM Maximo IT error. The Gate.TSRM.ErrorCode FieldName property is used in conjunction with the Gate.TSRM.NonApplication ErrorTitles property to work out what category the errors belong to. Any IBM Maximo IT error responses that match the regular expression in the Gate.TSRM.NonApplication ErrorTitles property will map to error code 1.

This property takes the following values:

0: the operation is successful.

1: the error is due to an intermittent issue, such as the server being down, so the operation can be retried.

2: the error is such that the operation cannot be retried, such as an invalid field value.

The default is TSRMErrorCode.

Gate.TSRM. FilterRepeatedValues boolean

-tsrmfilterrepeatedvalues boolean

Use this property to specify whether the gateway sends only event data that has changed since the last polling. The filtering will be based on the mapped values in the tsrm.map file and will omit the mapped values specified by the Gate.TSRM. FilterExclusionList property.

The default is TRUE.

Gate.TSRM. FilterExclusionList string

-tsrmfilterexclusionlist string

Use this property to specify a list of properties that are not filtered by the gateway if the Gate.TSRM. FilterRepeatedValues is set to true.

The default is 'TTNumber'.

Gate.TSRM.JournalTemplate string

-tsrmjournaltemplate string

Use this property to specify the name of the XML template used to create work logs in IBM Maximo IT.

The default is $OMNIHOME/gates/tsrm/journal.xml.template.

Gate.TSRM.Language string

-tsrmlanguage string

Use this property to specify the language code for the language used by IBM Maximo IT to process incoming data.

The default is EN.

Gate.TSRM.MapObject StructureSeparator string

-mapobjectstructure separator string

Use this property to specify the separator that the gateway uses between sub-objects when generating the XML code that it sends to IBM Maximo IT to create or update tickets. See Adding sub-object structures for more information.

The default is "".

Gate.TSRM.MaximoAuthentication Boolean

maximoauthentication- Boolean

Use this property to specify whether the gateway uses native Maximo authentication or LDAP authentication when authenticating with IBM Maximo IT using username and password credentials.

When set to TRUE, the gateway uses native Maximo authentication by sending credentials in the MAXAUTH header.

When set to FALSE, the gateway uses LDAP authentication by sending credentials in the Authorization: Basic header.

The default is TRUE.

Note: This property is only applicable when Gate.TSRM.ApiKey is not set. If an API key is configured, it takes precedence and this property is ignored. See Gate.TSRM.ApiKey for the full authentication priority order.

Gate.TSRM.MaxRetries integer

-tsrmmaxretries integer

Use this property to specify the number of times that the gateway retries polling IBM Maximo IT after the occurrence of an error, an HTTP timeout, or a socket-related exception, before shutting down.

The default is 5.

Gate.TSRM.NonApplication ErrorTitles string

-nonapplicationerrortitles string

Use this property to specify a comma-delimited list of application error titles (sent by IBM Maximo IT) that the gateway should interpret as connection errors.

The default is .*500 Internal Server Error.*

Gate.TSRM.Optional UpdateURLList string

-optionalupdurllist string

If your IBM Maximo IT implementation requires two URLs (one for creating tickets and one for updating tickets), use this property to specify the URL needed to communicate with IBM Maximo IT for updating tickets. Otherwise, leave this property blank.

The default is "".

Gate.TSRM.Password string

-tsrmpassword string

Use this property to specify the IBM Maximo IT password associated with the user name specified by the Gate.TSRM.Username property.

The default is maxadmin.

Gate.TSRM.PollTime integer

-tsrmpolltime integer

Use this property to specify the frequency (in seconds) with which the gateway polls IBM Maximo IT.

The default is 30 seconds.

Gate.TSRM. PollTimeIntervalWindow integer

-tsrmpolltime intervalwindow integer

Use this property to specify a different CHANGEDATE format for the gateway to use to determine new events in IBM Maximo IT.

The default is -1 : This function is disabled.

Gate.TSRM. QueryRetrieveList string

-tsrmqueryretrievelist string

Use this property to specify a comma-separated list of IBM Maximo IT ticket attributes that the gateway sends back to the ObjectServer for further processing.

The default is STATUS.

Note: If you add any IBM Maximo IT fields to this list, you must add the XML structure for that field to that of the IBM Maximo IT incident or service request. For details of how to do this, see Retrieving additional fields from IBM Maximo IT.

Gate.TSRM. QueryTicketTemplate string

-tsrmquerytickettemplate string

Use this property to specify the name of the XML template used to query the ticket within IBM Maximo IT.

The default is $OMNIHOME/gates/tsrm/query.xml.template.

Gate.TSRM.RetryInterval integer

-tsrmretryinterval integer

Use this property to specify the interval (in seconds) between successive polls of the IBM Maximo IT.

The default is 15 seconds.

Gate.TSRM.SocketTimeout integer

-tsrmsockettimeout integer

Use this property to specify the length of time (in seconds) that the gateway waits for a response to a requested operation from IBM Maximo IT.

The default is 15 seconds.

Gate.TSRM.SourceName string

-tsrmsourcename string

Use this property to specify the name used to tag incidents and work log objects. This allows you to indicate that the incident was created by the gateway.

The default is NETCOOL.

Gate.TSRM.StatusFieldName string

-tsrmstatusfieldname string

Use this property to specify the name of the mapper field used to populate the STATUS workflow attribute in IBM Maximo IT tickets.

The default is STATUS.

Note: If the value of the mapper field is empty, the alert is not forwarded to the IBM Maximo IT server. This is useful in a scenario where you might want to set the alert to RESOLVED if the severity of the alert is clear (or for any other reason you may not want to forward it). That is why the following lookup definition is included in the tsrm.map file:
CREATE LOOKUP StatusTable (
	{0, 'RESOLVED'})
DEFAULT= '';

Gate.TSRM.ThreadPoolSz integer

-tsrmthreadpoolsz integer

Use this property to specify the number of concurrent threads that the gateway uses to communicate with IBM Maximo IT.

The default is 5.

Note: In most cases, you will not need to change this value.

Gate.TSRM. TicketObjectName string

-tsrmticketobjectname string

Use this property to specify the object name for the IBM Maximo IT incident or service request object.

The default is MXINCIDENT.

Note: If you are using the gateway to generate service requests instead of incidents, set this property to MXSR.

Gate.TSRM. TicketObjectType string

-tsrmticketobjecttype string

Use this property to specify the object type created by the gateway within IBM Maximo IT.

The default is INCIDENT.

Note: If you are using the gateway to generate service requests instead of incidents, set this property to SR.

Gate.TSRM.TimeZone string

-tsrmtzdiff string

Use this property to specify the timezone used by the IBM Maximo IT server relative to GMT. For example, to specify four hours behind GMT, set this property to GMT-4.

The default is "".

Note: If the gateway is being run in the same timezone as the IBM Maximo IT server, leave this property blank.

Gate.TSRM. UpdateTicketTemplate string

-tsrmupdatetickettemplate string

Use this property to specify the name of the XML template used to update the ticket within IBM Maximo IT.

The default is $OMNIHOME/gates/tsrm/update.xml.template.

Gate.TSRM.URLList string

-tsrmurllist string

Use this property to specify a comma-delimited string consisting of the URLs required to communicate with IBM Maximo IT.

The default is http://<targethost>/meaweb/os/MXINCIDENT.

Note: If you are using the IBM Maximo IT server failover function, you must specify each URL separated by commas.

Gate.TSRM.UserName string

-tsrmusername string

Use this property to specify the name of the user authorized to log on to IBM Maximo IT.

The default is maxadmin.

Gate.TSRM.Version string

-tsrmversion string

Use this property to specify the version of IBM Maximo IT with which the gateway can communicate.

The default is 7.5.

Gate.TSRM. WorkLogObjectName string

-tsrmworklogobjectname string

Use this property to specify the object name of the IBM Maximo IT work log object name.

The default is WORKLOG.