Gateway operation

Use this information to learn how the Java Gateway for BMC Remedy ARS interacts with the BMC Remedy Action Request System. This includes information on how the gateway interacts with BMC Remedy ARS with regard to request operations.

This section covers the following subject areas:

Creating, updating, and deleting requests in BMC Remedy ARS

When a new alert is created in the ObjectServer, the gateway creates a corresponding request in BMC Remedy ARS. The mapping file defines how the fields in the BMC Remedy ARS request are filled with data from the ObjectServer. Mapping contains more information on the mapping file and its content.

When an alert in the ObjectServer is updated, the gateway updates the corresponding BMC Remedy ARS request. The gateway updates fields in the request depending on their definition in the mapping file. Fields with map entries qualified with ON INSERT ONLY are set only when the gateway creates the original request. Those fields are not updated when the ObjectServer alert is updated.

You set the action of the gateway when an alert is deleted from the ObjectServer through the value of the Gate.Remedy.DeleteEntries property. When the value of the property is true, the gateway deletes the request in BMC Remedy ARS. When the value of the property is false, the gateway sets the status of the request to Clear.

Avoiding duplicate requests in BMC Remedy ARS

As discussed, when a new alert is created in the ObjectServer, the gateway creates a corresponding request in BMC Remedy ARS. When the request creation operation succeeds BMC Remedy ARS assigns a unique request ID. However, there are situations when the gateway creates duplicate requests in BMC Remedy ARS, that is, requests with identical field values, but different request IDs. These duplicate requests result from the fact that the gateway makes two calls to the create request function in BMC Remedy ARS with the same set of data, when in fact, the gateway should have created only one request.

The following describes an example scenario where the gateway calls the create request function twice, thus causing duplicate requests with the same set of data to be created:

  • A new alert is created in the ObjectServer.
  • The gateway creates a corresponding request in BMC Remedy ARS by calling the create request function in BMC Remedy ARS.
  • BMC Remedy ARS creates a request ID.
  • The gateway crashes before it can receive the request ID from BMC Remedy ARS. (Receiving the request ID from BMC Remedy ARS indicates that the create request operation succeeded.)
  • After the gateway restarts, the ObjectServer sends the gateway an update request on the alert that was created prior to the crash. The ObjectServer indicates that no request was created for this alert.
  • The gateway creates a corresponding request in BMC Remedy ARS by calling the create request function in BMC Remedy ARS. This request has the same data as specified for the previous request. This action results in the creation of duplicate requests because the create request that occurred prior to the crash was successful. Thus, there are two requests in BMC Remedy ARS with the same data and different IDs.

Use the Gate.Remedy.ReclaimARS and Gate.Remedy.CreationErrorCode properties to control how the gateway handles request create and update operations to avoid duplicate requests in BMC Remedy ARS. The Gate.Remedy.ReclaimARS property allows you to specify whether and how to reclaim a request ID from BMC Remedy ARS when creating and updating an alert. The property takes one of the following values:

0: Never query BMC Remedy ARS for a request ID.

1: Query BMC Remedy ARS for a request ID when an error occurs during the creation of the BMC Remedy ARS request.

2: Always query BMC Remedy ARS for a request ID.

The Gate.Remedy.CreationErrorCode property sets the error code used to indicate failure to create a request in BMC Remedy ARS. If the gateway cannot create a request, it stores this value in the TargetIdField of the corresponding ObjectServer alert. The default value for the error code is CREATION_FAILURE.

Note: Use the Gate.TargetIdField property to specify the alerts.status column to use for target identifier tracking (that is, the identifier in BMC Remedy ARS). The default is 'Location'

Forwarding Journals

Once the request exists in BMC Remedy ARS, updates to the journal data are handled by the table replication mechanism, in a similar way to updates in the fields of the request itself.

Table Replication contains more information about table replication between the ObjectServer and BMC Remedy ARS.

Retrieving events

Alert Events is a standard form in BMC Remedy ARS that allows the gateway to retrieve update notifications from the BMC Remedy ARS server. For example, whenever a user updates the severity of a request in BMC Remedy ARS, a notification will be created in the Alert Events form to indicate the specific modification that has been made. The contents of this notification is specified in the filters Omnibus-Close and Omnibus-Modify (as defined in the omnibus.def configuration file). The gateway regularly queries BMC Remedy ARS for new notifications. The gateway uses the Gate.Remedy.UpdateForm property to identify the BMC Remedy ARS form (which is always Alert Events) to use to retrieve update notifications from the BMC Remedy ARS server.

The gateway uses the following properties in event retrieval operations:

  • Gate.Remedy.NotificationQuery

    The gateway uses this property to identify the set of updates on which to report. The default event qualifier is '7'<\"X\" AND '2'=\"USER\" AND '701'=\"FORM\"'.

    The default qualifier has three parts, as follows:

    • '7'<\"X\" - Specifies that the gateway has not yet read the notification.
    • '2'=\"USER\" - Specifies that the notification results from a modification of a request that was originally created by the user identified by USER. This qualifier ensures that notifications come only from requests that the gateway creates. The gateway automatically substitutes USER with the value specified for the Gate.Remedy.Username property.
    • '701'=\"FORM\" - Specifies that the notification is the result of an action on the form identified by FORM. The gateway automatically substitutes FORM with the value specified for the Gate.Remedy.Form property.
  • Gate.Remedy.UpdateQueryInterval

    The gateway uses this property to determine how often (in seconds) to query BMC Remedy ARS for updates. The default query interval is 3 seconds.

  • Gate.Remedy.DeleteUpdates

    The gateway uses this property to delete a notification from the Alert Events form. If set to true, the gateway deletes a notification from the Alert Events form after it reads the notification. If set to false, the gateway leaves the notification in the Alert Events form even after it reads the notification and marks it as read. The default value is false.

Controlling how the gateway handles notifications

The gateway typically discards notifications that are generated by its own actions. For example, if the gateway updates a request to Critical, it discards the notification for this request. The gateway identifies notifications that result from its own actions by checking the user information contained in the notification. If the user in the notification matches the value of the Gate.Remedy.Username property, then the gateway generally discards it.

You can use the Gate.Remedy.OwnNotifications property to control how the gateway handles notifications that are generated by its own actions. If the Gate.Remedy.OwnNotifications property is set to FIRST (the default), the gateway processes the first notification associated with a BMC Remedy ARS request, even if the gateway user modifies the request. To instruct the gateway to process all notifications associated with a BMC Remedy ARS request, regardless of which user performs the update action on that BMC Remedy ARS request, set this property to ALL. To instruct the gateway to process no notifications associated with this BMC Remedy ARS request even if the user performs an update action on that BMC Remedy ARS request, set this property to NONE.

Resynchronization

The gateway can perform two types of resynchronization: unidirectional and bidirectional. The Gate.Cache.ResyncMode property provides three resynchronization modes to control how the gateway performs resynchronization operations.

Note: The gateway resynchronizes the alerts (alerts.status table) as well as journals and details (alerts.journal and alerts.details tables) if enabled in the table replication definition file.

The following resynchronization modes are available:

  1. Unidirectional (UNI)

    The gateway performs a resynchronization operation from Tivoli Netcool/OMNIbus to BMC Remedy ARS.

  2. Bidirectional (BI)

    The gateway operates in bidirectional resynchronization mode. In this mode the gateway retrieves open requests from BMC Remedy ARS and compares them with the open requests on the ObjectServer.

  3. Automatic (AUTO)

    This is the default resynchronization mode. In this mode, the gateway operates in unidirectional resynchronization mode by default. However, if the gateway cache is empty on startup (which normally only occurs the first time that the gateway is run), it causes the gateway to operate in bidirectional resynchronization mode.

Resynchronization and Deduplication

The gateway deduplicates updates to alerts and journals. This results in efficient resynchronization, because only alerts that have changed are forwarded to BMC Remedy ARS. It also means that updates to fields that are not included in the map definition file, or fields that are not required in BMC Remedy ARS are ignored.

See Explanation of the StatusMap for an example of the DEDUPLICATE command used in the StatusMap (one of the maps contained in the bmc_remedy_v9.map delivered with the gateway).