Gateway operation

Use this information to learn how the Java Gateway for ServiceNow interacts with ServiceNow. This includes information on how the gateway interacts with ServiceNow with regard to ticket operations.

Table 1 identifies some of the operations related to how the gateway interacts with ServiceNow, including those related to ticket operations. For each operation, the table lists the properties you use to control how the gateway performs the operation, and the section of the guide that provides details about the operation and the valid values for the associated properties. For each operation, set the properties to the correct values or verify that their default values are suitable for your environment.

Note: The table references the following categories of properties that are defined in the G_SERVICENOW.props properties file:

Gateway Framework properties
ServiceNow gateway specific properties

For reference information and command line options on these properties, see Properties and command line options.

Table 1. Configuring gateway operation
Configure gateway operation tasks	Properties	See
Controlling synchronization between the gateway and ServiceNow	None	Controlling synchronization between the gateway and ServiceNow
Controlling which ServiceNow target table the gateway uses	Gate.ServiceNow.TableName	Controlling which ServiceNow target table the gateway uses
Controlling how the gateway queries the ServiceNow instance database	Gate.ServiceNow.QueryPolicy	Understanding how the gateway queries the ServiceNow instance database
Controlling when and how many times the gateway should retry an operation that fails	Gate.ServiceNow.RetryLimit Gate.ServiceNow.RetryWait	Controlling when and how many times the gateway should retry an operation that fails
Controlling how the gateway handles the alternate index policy	Gate.ServiceNow.AlternateIndexField Gate.ServiceNow.AlternateIndexPolicy	Controlling how the gateway handles the alternate index policy
Controlling how the gateway handles outbound data management	Gate.ServiceNow.DateAndTimeFormat Gate.ServiceNow.OutboundManagedTypes Gate.ServiceNow.OutboundManagement	Controlling how the gateway handles outbound data management
Controlling how the gateway handles notifications	Gate.ServiceNow.DropFirstNotification Gate.ServiceNow.ModifCounterField Gate.ServiceNow.PollingInterval	Controlling how the gateway handles first notifications of created tickets
Controlling where the gateway stores error codes	Gate.ServiceNow.ErrorCodeColumn	Controlling where the gateway stores error codes
Controlling how the gateway performs checks before it creates a ticket	Gate.ServiceNow.PreCreateChecks	Controlling how the gateway performs checks before it creates a ticket
Controlling how the gateway handles ServiceNow tickets	Gate.ServiceNow.PollingInterval	Controlling how the gateway handles processing of ServiceNow tickets
Controlling how the gateway handles operations related to ticket fields	Gate.ServiceNow.SysIdField Gate.ServiceNow.TicketIdField Gate.ServiceNow.UpdateFields Gate.ServiceNow.UpdateQueryStartTime	Controlling how the gateway handles operations related to ServiceNow ticket fields

The topics that follow make use of the following terms:

Outbound -- Specifies the data flow sent from the gateway to the ServiceNow instance database.
Inbound -- Specifies the data flow received by the gateway from the ServiceNow instance database.

Controlling synchronization between the gateway and ServiceNow

You need to ensure that the server on which the gateway is running and the server on which ServiceNow is running are on the same system time. Specifically, the clocks on the gateway server and the ServiceNow server need to be synchronized.

Also, to prevent miscommunication of ticket details, the time zones of the ObjectServer, the gateway server, and the ServiceNow server must be synchronized at all times.

See your operating system documentation for information on how to synchronize the server clocks.

Controlling which ServiceNow target table the gateway uses

The gateway communicates with a ServiceNow instance database to create tickets and to retrieve data about these tickets. The ServiceNow instance database consists of tables each of which is a collection of records. Specifically, the gateway needs to know which table in the ServiceNow instance database it should use to create tickets and to retrieve data about these tickets. The gateway uses the Gate.ServiceNow.TableName property to identify the table (referred to as the target table) in the ServiceNow instance database it should use to create tickets and to retrieve data about these tickets. The default name for the target table in the Gate.ServiceNow.TableName property is incident.

Edit this property if you want the gateway to access a different target table in the ServiceNow instance database.

Note: In addition to editing the Gate.ServiceNow.TableName property to target an alternative table, you will also need to configure accordingly the servicenow.rdrwtr.tblrep.def table definition file, the servicenow.map map definition file, the notification.js file, and other properties.

Controlling when and how many times the gateway should retry an operation that fails

Following successful completion of the initial REST GET requests during the gateway startup sequence, you can control how the gateway handles failed operations by using the Gate.ServiceNow.RetryLimit and Gate.ServiceNow.RetryWait properties as follows:

Use the Gate.ServiceNow.RetryLimit property to specify the maximum number of retries the gateway should make on an operation that failed. The default value of 3 means the gateway will make up to three attempts for a failed operation.
Use the Gate.ServiceNow.RetryWait property to specify the number of seconds the gateway should wait before retrying an operation that failed. The default value is 7 seconds.

The following example shows that the Gate.ServiceNow.RetryLimit property is set to its default value of 3 and the Gate.ServiceNow.RetryWait property is set to the value of 5 seconds:

.
.
.
Gate.ServiceNow.RetryWait    : 5
Gate.ServiceNow.RetryLimit   : 3
.
.
.

Given the above settings, if the gateway operation to forward an event to the ServiceNow instance fails, the gateway waits five seconds and then retries the event forwarding operation. The gateway waits five seconds each time it performs the event forwarding operation until it succeeds.

Understanding how the gateway queries the ServiceNow instance database

The gateway communicates with the ServiceNow instance database by adhering to the policy specified in the Gate.ServiceNow.QueryPolicy property. Specifically, the gateway performs all queries on the ServiceNow instance database using a scoping clause that includes the following:

sys_create_by=sngw_user

Where sngw_user is the value specified in the Gate.ServiceNow.Username property.

Thus, the only tickets in the ServiceNow instance database that are of interest to the gateway are those tickets that the gateway itself creates.

The default query policy value is Account.

Note: Currently, this property supports only a query policy with the value Account.

Controlling how the gateway handles the alternate index policy

It is very important that you configure the gateway with an alternate index field (in the Gate.ServiceNow.AlternateIndexField property) whenever possible. An alternate index field allows the gateway to enforce end-to-end correlation integrity. The gateway, by default, is configured to use an alternate index field of correlation_id, which is a column in the ServiceNow incident table.

As discussed in Controlling which ServiceNow target table the gateway uses the gateway uses the ServiceNow target table specified in the Gate.ServiceNow.TableName property to create tickets and to retrieve data about these tickets. You control how the gateway handles the alternate index policy behavior through the Gate.ServiceNow.AlternateIndexField and Gate.ServiceNow.AlternateIndexPolicy properties. Specifically, you use the Gate.ServiceNow.AlternateIndexField to specify the name of the column in the ServiceNow target table that the gateway uses as an alternate index. You use the Gate.ServiceNow.AlternateIndexPolicy property to instruct the gateway on how to set the alternate index field.

The default column name in the ServiceNow target table is correlation_id. This column name implies that the values in the ServiceNow instance database are unique within the scope of records that the gateway queries. More specifically, the correlation_id must be unique across all tickets with the same value for sys_created_by equal to that of the user name of the dedicated ServiceNow gateway account. Note that the Gate.ServiceNow.QueryPolicy property (discussed in Understanding how the gateway queries the ServiceNow instance database) controls how the gateway queries the ServiceNow instance database by using a scoping clause.

The default behavior for the way the gateway sets the alternate index field value is specified by the value internal.

Specifically, the operational behavior for how the gateway sets the alternate index field value in the Gate.ServiceNow.AlternateIndexField property is specified by the following values:

internal: Instructs the gateway to internally set the alternate index for the ServiceNow target table to the name of the originating ObjectServer and the serial number of the alert on the originating ObjectServer. Specifying internal causes the gateway to generate a value that can be used for the column specified in the Gate.ServiceNow.AlternateIndexField property. An example of an internally set alternate index value might be Correlation ID: NCOMS/2421
Note: If the Gate.ServiceNow.AlternateIndexField property is an empty string and Gate.ServiceNow.AlternateIndexPolicy is set to internal, the value that is generated cannot be included in the outbound data because there is no column specified to hold the value.
custom:
Indicates that the value of the Gate.ServiceNow.AlternateIndexPolicy property should be set in the StatusMap (defined in the servicenow.map map definition file). You must ensure a unique value for each ticket in the Gate.ServiceNow.AlternateIndexField.

Specifying custom means that the user takes responsibility for the value used within the Gate.ServiceNow.AlternateIndexField property by specifying the alternate index field in the servicenow.map definition file as described above.

Note: If the Gate.ServiceNow.AlternateIndexField property is an empty string and Gate.ServiceNow.AlternateIndexPolicy is set to custom, the gateway reports an error and shuts down.

The combination that must be used to effectively disable alternate index functionality is to specify internal for the Gate.ServiceNow.AlternateIndexPolicy property and "" for the Gate.ServiceNow.AlternateIndexField property.

Controlling how the gateway handles outbound data management

Outbound data management refers to the data flow sent from the gateway to the ServiceNow instance database. Conversely, inbound data management refers to the data flow received by the gateway from the ServiceNow instance database. You control how the gateway handles outbound data management through the Gate.ServiceNow.OutboundManagedTypes and Gate.ServiceNow.OutboundManagement properties. Specifically, you use the Gate.ServiceNow.OutboundManagedTypes property to specify which types of data the gateway should use as part of its outbound data management operations. For example, type1;type2;type3. Note that the semicolon (;) is used to separate the data types. The default value for the types of data is "". Note that the Gate.ServiceNow.OutboundManagedTypes property is active only if you specify the value custom for the Gate.ServiceNow.OutboundManagement property.

You use the Gate.ServiceNow.OutboundManagement property to instruct the gateway on how to perform outbound data management operations. The default operational behavior for outbound data management operations is specified by the value default.

Specifically, you control how the gateway performs outbound data management by specifying one of the following values:

default: The gateway performs the default outbound data management behavior. Currently, this behavior is limited to field width checking for specified types.
disable: Switches off all outbound data management.
custom: The gateway performs the custom outbound data management behavior. Currently, this is limited to field width checking for the types specified by the Gate.ServiceNow.OutboundManagedTypes property.
The following are the built in types for which the gateway performs field width checking operations:
- integer
- string
- journal
- journal_input
- journal_list

If a field width is breached for a managed outbound type, the gateway logs a warning message and the data will be truncated in the ServiceNow instance database. There is one exception to this rule that occurs if you enable pre-create checks (using the Gate.ServiceNow.PreCreateChecks property) and outbound management (using the Gate.ServiceNow.OutboundManagement property) and the outbound field is the alternate index field (specified by the Gate.ServiceNow.AlternateIndexField property) whose type is managed. In this case, if the field width is breached then the gateway aborts the create ticket operation because truncation of data on the ServiceNow instance database could cause duplicate alternate index field values.

Another property related to how the gateway handles outbound data is the Gate.ServiceNow.DateAndTimeFormat property. This property specifies the format for the outbound date and time data so that it is compatible with the format specified for the associated ServiceNow system properties. The default value is yyyy-MM-dd HH:mm:ss.

Note: If this date and time format is not compatible with how ServiceNow is configured, the outbound date and time data will be ignored by ServiceNow.

Controlling how the gateway handles first notifications of created tickets

The gateway periodically sends HTTP polling requests to the ServiceNow instance. As a result of these HTTP polling requests, the gateway retrieves recent changes, for example, that the ServiceNow instance has created a new ticket. You can control whether the gateway should process the first notification of a created ticket through the Gate.ServiceNow.DropFirstNotification property.

The property takes one of the following values:

true: The gateway should not process the first notification that it receives following the creation of a ticket by the ServiceNow instance.
false: The gateway should process the first notification that it receives following the creation of a ticket by the ServiceNow instance.

The default value is true.

The gateway identifies the first update to a ticket by checking the value of the Gate.ServiceNow.ModifCounterField property (default value of sys_mod_count). If sys_mod_count is equal to 0 (zero), then the gateway knows that the ticket has not yet been updated on ServiceNow. Thus, the gateway determines that the ticket is newly created. If sys_mod_count is equal to a value greater than 0 (zero) in the values received from the HTTP polling request, the gateway evaluates the notification as not resulting from a ticket creation operation.

Controlling where the gateway stores error codes

When the gateway encounters an error during some operation, it writes a gateway specific error code to a column in an ObjectServer alerts.status table. You can specify the name of the column in the ObjectServer alerts.status table where the gateway stores these error codes using the Gate.ServiceNow.ErrorCodeColumn property.

The default name of the column is ServiceNowErrorCode.

Note: The column in the ObjectServer alerts.status table is created when you run the default servicenow.sql that is provided with the gateway.

Table 2 identifies some of the possible gateway specific error codes.

Table 2. Gateway specific error codes
Gateway error code	Description	Action
`1`	The gateway reported a transient error when performing the specified operation. The following list identifies some of these operations: The gateway was unable to perform a check on the pre-create operation. A CREATE operation fails and an HTTP error gets generated (that is, there is a communication problem). In this case, the CREATE operation should be attempted again when the communication is restored.	No action required. The next time the gateway resynchronizes with the ObjectServer the gateway attempts the action again.
`2`	The gateway reported an unrecoverable error when performing the specified operation. The following list identifies some of these operations: The gateway was unable to update the specified ticket because it could not locate the ticket in the ServiceNow instance database.	For this particular operation, if you want to discard further updates on the original alert, update the `FILTER BY` clause in the servicenow.rdrwtr.tblrep.def table replication definition file to filter out events on alerts when the `ServiceNowErrorCode` is set to the value `2`.

Controlling how the gateway performs checks before it creates a ticket

The gateway can perform a variety of checks before it creates a record in the ServiceNow target table.

Note: You specify the name of the ServiceNow target table using the Gate.ServiceNow.TableName property, as described in Controlling which ServiceNow target table the gateway uses.

You control the pre-create record checking behavior by specifying one of the following values for the Gate.ServiceNow.PreCreateChecks property:

default: The gateway performs, where possible, default pre-create record check operations. Currently, the default behavior centers around checking the integrity of the Gate.ServiceNow.AlternateIndexField property and any associated value presented as part of a create record request.
Note: If the Gate.ServiceNow.AlternateIndexField property is an empty string, then it effectively disables any pre-create record check operations associated with that property. The gateway supplies a warning message associated with this condition during gateway start up.
disable: Disables any pre-create check. In other words, the gateway is prevented from performing any pre-create check operations.

If the Gate.ServiceNow.AlternateIndexField is active, the gateway performs the following pre-create record check operations as part of the default pre-create record check functionality:

Checks the ServiceNow target table for any records that have the same alternate index value. If duplicate alternate index values are found, the gateway reports an error condition and aborts the create record operation.
Checks if the alternate index value is empty. This is assumed to be an error condition and the gateway reports an appropriate error and aborts the create record operation.
Checks if the Gate.ServiceNow.OutboundManagement property is set to default and that the Gate.ServiceNow.AlternateIndexField property has a type that is being managed, then the gateway checks the alternate index value to determine that the data will fit (that is, not too wide). If it is too wide, the gateway reports an error condition and aborts the create record operation.

Note: The default value for the Gate.ServiceNow.AlternateIndexField property is correlation_id, which is of type string and is one of the default managed types. Therefore, by default, the gateway checks the width of the alternate index values and aborts the create record operation if they are too wide.

See Controlling how the gateway handles the alternate index policy for information about the Gate.ServiceNow.AlternateIndexField property and Controlling how the gateway handles outbound data management for information about the Gate.ServiceNow.OutboundManagement property.

Controlling how the gateway handles processing of ServiceNow tickets

You can control the following characteristics of how the gateway handles the processing of ServiceNow records by using the specified gateway specific property:

The gateway periodically queries the ServiceNow instance to check for updates to records. You use the Gate.ServiceNow.PollingInterval property to specify how often (in seconds) the gateway should query the ServiceNow instance to check for updates to records. The default query interval is 17 seconds.

Controlling how the gateway handles operations related to ServiceNow ticket fields

You can control the following characteristics of how the gateway handles the processing of ServiceNow record fields by using the specified gateway specific property:

The gateway core framework needs to know which column in the ServiceNow target table serves as the internal ticket identifier. You use the Gate.ServiceNow.TicketIdField property to specify the column in the ServiceNow target table that serves as the internal ticket identifier. This column name must be a unique record identifier. The default column name is sys_id.
Note: You specify the name of the ServiceNow target table using the Gate.ServiceNow.TableName property, as described in Controlling which ServiceNow target table the gateway uses.
When polling for updates, the gateway retrieves record field information from the ServiceNow target table by accessing specific columns from that table. You use the Gate.ServiceNow.UpdateFields property to specify which columns to use to retrieve record field information. The default columns are state;number. Note that you separate column names using the semicolon (;).
In addition to the columns specified in this property there are six other default columns that the gateway retrieves when polling for updates. The following list identifies these six other default columns:
- sys_created_by
- sys_created_on
- sys_updated_on
- sys_id
- sys_updated_by
- sys_mod_count
Note: The queried fields will be a combination of the six previously listed default columns plus update fields and, if configured, the alternate index field. The queried fields are merely returned to the gateway as part of the polling REST GET request. In order to persist fields back to the ObjectServer, you will need to configure the functions defined in the servicenow.notification.js file accordingly.
When the gateway begins to check for updates on the ServiceNow instance can be controlled using the Gate.ServiceNow.UpdateQueryStartTime property. You specify the initial date and time (in minutes) that the gateway uses to check for these updates. If the default value of 0 (zero) is used, the gateway will poll for changes that have occurred since the time the gateway was started.
To specify a value other than 0 (zero), use the command line option for this property. For example:
```
-servicenowupdatequerystarttime 15
```
In the previous example, if the gateway, following its startup sequence, is ready to perform its first poll at 13:00 GMT, the query would look for updates after 12:45 GMT.
The gateway uses the globally unique identifier (GUID) for each ServiceNow record to form the URLs that it uses to communicate with the ServiceNow instance. You use the Gate.ServiceNow.SysIdField property to specify the name for the ServiceNow target table column that holds the globally unique identifier (GUID) for each ServiceNow record. The default value for the GUID column name is sys_id.
This specifies the field in the response body from a create ticket request (HTTP POST) that will be used in future request URLs to update the respective ticket.

Controlling how the gateway handles resynchronization

The gateway can perform unidirectional resynchronization. To enable unidirectional resynchronization, the Gate.Cache.ResyncMode property is set to the default value of UNI in the G_SERVICENOW.props properties file. The gateway performs a resynchronize operation from Tivoli Netcool/OMNIbus to ServiceNow.