Using the alert functions defined in servicenow.notification.js

Use the alert functions defined in the servicenow.notification.js file to perform a variety of operations on Tivoli Netcool/OMNIbus ObjectServer alerts. The alert functions are called by the Java Gateway for ServiceNow.

Overview

The servicenow.notification.js file defines a variety of alert functions that operate on ObjectServer alerts and the journal table (default value alerts.journal). The file also imports functionality from several modules. The alert functions supplied in the servicenow.notification.js file define a basic default behavior for each of those functions. The servicenow.notification.js file is written in JavaScript and you can modify these alert functions to suit your requirements.

The following sections discuss each of the imported modules and alert functions defined in the servicenow.notification.js file.

Imported modules

The servicenow.notification.js file uses the require function to load the following modules:

Gateway log manager service -- Made available through the logger variable
Simple OMNIbus Gateway (SOG) interface module -- Made available through the sog variable
dateformat module -- Made available through the dateformat variable

The SOG interface module exposes the following method:

newrow -- Returns an empty row that is ready to be populated.

The addJournal function

The gateway calls the addJournal function to add a journal entry in the ObjectServer alerts.journal table for the ObjectServer alert specified in alert.

The addJournal function is defined as follows:

function addJournal(alert, message)

alert -- Specifies the ObjectServer alert for which you want to add a journal entry in the alerts.journal table.
message -- Specifies a message to be concatenated after the following string:
```
Generated by ServiceNow Gateway: message
```

The logDebug function

The gateway calls the logDebug function to log debug messages associated with the ObjectServer alert specified in alert. The logDebug function actually calls the debug method, which is implemented as part of the Tivoli Netcool/OMNIbus Logger interface. The gateway writes debug messages to the gateway log file.

The logDebug function is defined as follows:

function logDebug(alert, msg)

alert -- Specifies the ObjectServer alert to which the debug message specified in msg applies.
msg -- Specifies a message to be concatenated after the following string:
```
Alert [ server_name, server_serial ] : msg
```

Where:

server_name -- Specifies the name of the server on which the ObjectServer alert was generated.
server_serial -- Specifies the serial number of the alert in the alerts.status table.

The logError function

The gateway calls the logError function to log errors associated with the ObjectServer alert specified in alert. The logError function actually calls the error method, which is implemented as part of the Tivoli Netcool/OMNIbus Logger interface. The gateway writes errors to the gateway log file.

The logError function is defined as follows:

function logError(alert, msg)

alert -- Specifies the ObjectServer alert to which the error message specified in msg applies.
msg -- Specifies a message to be concatenated after the following string:
```
Alert [ServerName, ServerSerial]: msg
```

Where:

server_name -- Specifies the name of the server on which the ObjectServer alert was generated.
server_serial -- Specifies the serial number of the alert in the alerts.status table.

The update functions

The servicenow.notification.js file defines three update functions:

update -- The gateway calls the update function whenever it:
- Receives an IDUC (specifically, an Insert or Update) notification from the ObjectServer
- Polls ServiceNow and needs to perform an update operation on an alert
If the gateway receives an IDUC (specifically, an Insert or Update) notification from the ObjectServer, the update function provides the entry point to invoke the internalUpdate function. If the gateway performs an update operation on an alert following a ticket modification in ServiceNow, the update function provides the entry point to invoke the inboundUpdate function. Thus, in effect, the update function is a wrapper function that calls either the internalUpdate or the inboundUpdate function.
internalUpdate -- Processes the IDUC (specifically, the Insert or Update) notification from the ObjectServer.
inboundUpdate -- The update function calls the inboundUpdate function as a result of the gateway performing an update operation on an alert following a ticket modification in ServiceNow.

The following sections describe each of these functions.

The update function

The gateway calls the update function whenever it:

Receives an IDUC (specifically, an Insert or Update) notification from the ObjectServer
Polls ServiceNow and needs to perform an update operation on an alert

The update function is defined as follows:

function update(alert, inputs)

alert -- Specifies the alert within Tivoli Netcool/OMNIbus that is being updated.
inputs -- Determines which update function to call. If inputs contains the value ServiceNowErrorCode, then the gateway knows that a set of data was provided in the IDUC notification from the ObjectServer. The update function then calls the internalUpdate function to process the IDUC (specifically, the Insert or Update) notification.
Otherwise, if the inputs parameter does not contain the value ServiceNowErrorCode, then the gateway knows that this is an update operation resulting from the gateway reading a ticket update in ServiceNow. In this case, the update function calls the inboundUpdate function to perform the update operation.

The internalUpdate function

The update function calls the internalUpdate function as a result of the processing of the IDUC (Insert or Update) notification in the main gateway code. More specifically, the internalUpdate function sets the ServiceNowErrorCode value in the ObjectServer alerts.status table when it gets an error trying to perform an action on ServiceNow. For example, the gateway would update the ServiceNowErrorCode in the ObjectServer if it tried to update a ticket in ServiceNow and received an error back indicating that the ticket is not there anymore. In this example, the gateway would update the ServiceNowErrorCode to the value 2 (unrecoverable error) in the alerts.status table.

The internalUpdate function is defined as follows:

function internalUpdate(alert, inputs)

alert -- Specifies the ObjectServer alert that is being updated with a ServiceNow error code.
inputs -- Specifies a name value pair as follows:
- The name of the ObjectServer column in the alerts.status table to be used for storing ServiceNow error codes. The default name of this column is ServiceNowErrorCode.
- The ServiceNow error code to be written to the specified column in the alerts.status table.
This is the example provided in the servicenow.notification.js file. The function can handle other items.

Note:

The reason that the internalUpdate function creates a new row (by calling the sog.newrow method) is to set only the ServiceNowErrorCode and not set all the other variables that might be present in the inputs parameter.

The internalUpdate function calls the logDebug function to log the following debug message in the gateway log file:

Alert [ server_name, server_serial ] : 
       updating with ServiceNowErrorCode ServiceNowErrorCode

Where:

server_name -- Specifies the name of the server on which the ObjectServer alert was generated.
server_serial -- Specifies the serial number of the alert in the alerts.status table.
ServiceNowErrorCode -- Specifies a ServiceNow error code. For example: error code 1 (TRANSIENT_ERROR) and error code 2 (NON_RECOVERABLE_ERROR).

The internalUpdate function calls the logError function to log the following error message in the gateway log file if the gateway cannot update the ObjectServer alert specified in alert:

Alert [ServerName, ServerSerial]:
       Unable to update alert in OMNIbus: err

err -- Specifies a message indicating why the gateway could not update the ObjectServer alert specified in alert with the ServiceNow error code.

The inboundUpdate function

The gateway calls the inboundUpdate function to process an update as a result of a ticket modification on ServiceNow. Note that the gateway does not receive notifications from ServiceNow. Instead, the gateway regularly polls ServiceNow for updates. An update is the result of a ticket modification in ServiceNow.

Note: You specify the frequency with which the gateway polls ServiceNow by specifying an appropriate value in the Gate.ServiceNow.PollingInterval property defined in the G_SERVICENOW.props properties file.

The inboundUpdate function is defined as follows:

function inboundUpdate(alert, inputs)

alert -- Specifies the alert within Tivoli Netcool/OMNIbus that is being updated.
inputs -- Specifies the actual update from the target system (in this case, ServiceNow). This parameter takes a name/value map of updated values. These names are in the target system namespace, which might not correspond to the names of columns in the Tivoli Netcool/OMNIbus, so values need to be converted from one namespace to the other. This requires creating an empty update row (by calling the sog.newrow method).

Note: It is possible to customize the inboundUpdate function to provide logic to cater for a ticket state being set to Resolved.

The clear function

The gateway does not currently make use of the clear function. The main reason is that when a ticket gets closed or deleted in ServiceNow, the gateway does not get notified. By default, the only way for the gateway to discover when a ticket gets closed or deleted in ServiceNow is when the gateway tries to update a ticket and gets back an error indicating that the ticket cannot be found.

The error function

The gateway calls the error function whenever an error occurs when the gateway tries to manipulate the corresponding ticket in the target system (in this case, ServiceNow). The error function is defined as follows:

function error(alert, inputs, message)

alert -- Specifies the alert within Tivoli Netcool/OMNIbus.
inputs -- Specifies the actual values from the ServiceNow ticket.
message -- Specifies the error message text. This error message text can be added to a journal entry for the alert (by calling the addJournal method), for example, to identify the problem to the end user.

The setTargetId function

The gateway calls the setTargetId function whenever the alert is associated with a destination target system ticket. Typically, the gateway calls setTargetId after the user creates a ServiceNow ticket. The setTargetId function sets the target ID in the underlying alert and adds the target ID details to a journal entry for the alert (by calling the addJournal method).

The setTargetId function is defined as follows:

function setTargetId(alert, targetid)

alert -- Specifies the alert within Tivoli Netcool/OMNIbus.
targetid -- Specifies a string representation of the id. In the case of ServiceNow, this string is the sys_id associated with the ticket.