IBM Netcool Integration



Configure xMatters On-Demand

Configure xMatters Integration Agent

Configure Netcool

Download resources

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.


This article provides technical details for the implementation of the xMatters On-Demand service for use with IBM Netcool.

xMatters On-Demand becomes the voice and interface of an automation engine and when Netcool detects something that requires attention, xMatters places phone calls, send emails or notifies your mobile app.  xMatters On-Demand gives the notified person instant two-way communication with Netcool.  Responses are processed and executed on Netcool enabling remote resolution of the event.

This version of the integration is outbound only, although it does write a note to the incident detailing that an event was sent to xMatters. It does not contain the event ID.

This integration supports alert notifications (from Netcool to xMatters On-Demand). It also supports inbound actions (from xMatters On-Demand to Netcool).

Integration created and supplied by Peter Read

Download integration package

The first step in preparing for this integration is to download the attached integration package ( and save it to your local machine. Make sure you download the appropriate package for your operating system, and then extract the contents. The following sections may refer to specific locations within this extracted integration archive.

Configure xMatters On-Demand

Before configuring anything in Netcool, you'll need to configure xMatters.

Create a REST API user

The first step in configuring xMatters is to create a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. The best way to create a user for this integration is to have a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, you will need to create it, or ask your xMatters Client Success Manager to create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named "REST Web Service User".

To create a REST API user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
  • Make a note of these details; you will need them when configuring the Netcool side of the integration.

Create users and groups that will receive notifications

When you assign a ticket to a user or queue in Netcool, the integration will send a notification to the corresponding user or group in xMatters. You will need to create a user or group in xMatters for each Netcool user or queue you want to be able to notify.  

Import the communication plan

The next step is to import the Netcool communication plan.

To import the Netcool communication plan:

  1. Log in to the target xMatters system.
  2. Click the Developer tab, and then click Import Plan.
  3. Click Browse, and then locate the following file from the extracted integration archive:
  1. Click Import Plan.
  2. Click Plan Disabled to enable the plan.
  3. In the Edit drop-down list, select Forms.
  4. For the group form, in the Not Deployed drop-down list, click Create Event Web Service.
    • After you create the web service, the drop-down list label will change to Web Service Only.

  5. In the Web Service Only drop-down list, click Permissions.
  6. Enter the REST API user you created above, and then click Save Changes.

Accessing web service URLs

To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.

  • Note: The Access Web Service URL option appears twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service.

Configure the event domain

The next step is to configure the applications event domain

To configure the applications event domain:

  1. Download the attached .zip or tar.gz file to your system, and then extract the contents.
  2. In the target xMatters system, on the Developer tab, click Event Domains.
  3. Click the applications link.
  4. Scroll to the bottom of the screen until you see Integration Services and click Add New.
  5. In the Name field type: ibmnetcool and click save.


Configure xMatters integration agent

Now that you've configured xMatters On-Demand, it's time to configure the integration agent

The installation instructions below assume you already have a working xMatters integration agent.  If this is a new installation and you have not yet deployed the integration agent please follow this link to download, deploy and configure:

Integration Agent for xMatters 5.x & xMatters On-Demand

Install the package

The installation package contains all that you need to configure the Netcool integration.

To install the package:

  1. Within the extracted integration archive, navigate to:
  2. Copy the contents of this folder to the installation directory of the integration agent: for example: C:\integrationagent-5.1.5
    • This folder is referred to as <IAHOME> in the remainder of the instructions.
  3. Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
  4. Save and close the file.
  5. Open the ibmnetcool-config.js file found in the <IAHOME>\integrationservices\ibmnetcool folder and add or set the values for the following variables:
    WEB_SERVICE_URL The web service URL of the communication plan form (see Accessing web service URLs, above).
    INITIATOR The User ID of the REST API user you created in xMatters.

    Path and filename of the password file containing the encrypted REST API user's password.

    For instructions on how to configure this file, see "Setting password files", below.


    This must be set to null for outbound-only integrations.


    Must be set to "ibmnetcool" for this integration.


     Name or IP address of the server hosting the Netcool/OMNIbus ObjectServer


     Port on which the Netcool/OMNIbus ObjectServer is running


     Method used to communicate with the ObjectServer's Sybase database


     The name of the ObjectServer xMatters user.


    The ObjectServer password for the ObjectServer xMatters user


    Password for OMNI_NetcoolUser
    annotationPrefix Annotation to be used for prefix within Netcool
  6. Note: The OMNI_NetcoolUser and OMNI_UID, and OMNI_netcool_password variables are set in the installation SQL. Use the default values if the user information has not been changed.
  7. Save and close the file.
  8. Open the deduplicator-filter.xml file found in the <IAHOME>\integrationservices\conf folder and add the duplicator filter (everything from <filter name="ibmnetcool"> to and including </filter>) found in the deduplicator-filter.IbmNetcoolExample.xml file in the same folder.
  9. Save and close the file.
  10. Restart the integration agent

Setting password files

This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the REST API user. You will need to update (or create) the file with the correct password for the REST API user you created above.

To configure the REST API user password:

  1. Open a command prompt and navigate to <IAHOME>\bin.
  2. Run the following command, where <new_password> is the password for the INITIATOR user specified in the <IAHOME>\integrationservices\directory\configuration.js file, and <old_password> is the existing password (the default passowrd for a newly installed integration is "password"):
iapassword.bat --new &lt;new_password&gt; --old &lt;old_password&gt; --file conf/.initiatorpasswd

For more information about working with the iapassword command, and creating password files, refer to the xMatters integration agent guide.

Configure Netcool

Now that you've configured xMatters, it's time to configure Netcool; the archive attached to this article contains all that you need.

Event Viewer

This integration includes an xmatters.elc file, which is a replacement version of the default Netcool Event List. The new version includes the fields used by the integration to identify alert information required by the integration settings.

To install the event viewer:

  1. Within the download package locate the following file and copy it to a location on the classpath of the Netcool machine: 

Event Injection Wrapper

The Netcool-APClient.bat (or .sh) file is used to send either a "Del" injection to the del Integration Service or an alert injection to the 'ibmnetcool' Integration Service on the Integration Agent.

To install the event injection wrapper:

  1. Within the download package, locate the following file and copy it to the <IAHOME>/bin directory: 

On Windows:


On Unix:


Connection watch triggers

This integration creates connection watch alerts whenever the integration agent uses JDBC to access the Netcool/OMNIbus Sybase database. These alerts can be turned off in the Netcool/OMNIbus Administrator.

To disable the connection watch triggers:

  1. In Netcool/OMNIbus Administrator, click Automation > Triggers.
  2. In the Triggers list, open the connection_watch_connect trigger.
  3. In the Edit Signal Trigger dialog box, clear the Enabled check box, and then click OK.
  4. Repeat the previous step for the connection_watch_disconnect trigger.

Checking the process agent

If the Netcool/OMNIbus server cannot access the Process Agent, check the Process Agent name and password settings to ensure they are correctly configured.

To check the Process Agent:

  1. Open the Netcool/OMNIbus Administrator and click System > Properties.
  2. Locate the following settings:
    • PA.Name
    • PA.Password
    • PA.Username
  3. Ensure that these settings are the same as the user who starts and runs the NCO_PA application.

Setting environment variables 

After you complete the pre-configuration steps, the first task is to configure the environment variables on your Netcool/OMNIbus machine.

On Windows:

  • Add a global environment variable named IA_HOME set to the integration agent installation directory.
  • Append the IA_HOME environment to the system PATH environment variable.
  • If it does not already exist in the Global or PATH variable, create a global environment variable named JAVA_HOME
  • and set it to the \jre directory within the integration agent installation folder. Note that when adding to the path, it must include the bin directory: path=...….%IA_HOME%\bin;%JAVA_HOME%\bin;
    • This is used for the Data Synchronization portion of the integration.
  • Append JAVA_HOME to the system PATH environment variable.

On Unix:

  • For each user running Netcool/OMNIbus, add an environment variable named IA_HOME and set it to the integration agent installation directory.
    • As an alternative, you could set a global environment variable accessible to all Users.
  • Append the IA_HOME environment variable to the PATH environment variable of the user under which Netcool/OMNIbus runs.
  • Add an environment variable named OMNIHOME set to the Netcool/OMNIbus installation directory.
  • Append $OMNIHOME/bin to the PATH environment variable of the user under which Netcool/OMNIbus runs.
  • If it does not already exist in the Global or PATH variable, create a global environment variable named JAVA_HOME and set it to the /jre directory within the integration agent installation folder.
    Note: when adding to the path, it must include the bin directory: path=...….%IA_HOME%\bin;%JAVA_HOME%\bin;
  • Append JAVA_HOME to the PATH environment variable of the user under which Netcool/OMNIbus runs.

Updating the database

The first required step to configure Netcool/OMNIbus for this integration is to update the database.

To update the Netcool/OMNIbus database:

  1. Back up the %OMNIHOME%\db\<ObjectServerName> directory (optional).
  2. Change your working directory to %OMNIHOME%\bin.
  3. Run the %OMNIHOME%\bin\Netcool-updates.bat script, passing the following parameters:
    • ObjectServer name
    • ObjectServer user name (must have ISQL Writer permissions)
    • Password for ObjectServer user name (can be null)
  • For example:

    Netcool-updates.bat NCOMS user password

If the update is successful, you should see a message indicating that 31 rows were affected, and you should be able to verify that the database was updated correctly based on the changes in the SQL file.

Configuring procedures

The procedures created by the integration need to be updated to include the IP address of the Netcool/OMNIbus server.

To edit the procedures:

  1. Open the Netcool/OMNIbus Administrator.
  2. Connect to the ObjectServer to use for xMatters events.
    • This ObjectServer must have the xMatters SQL installed.
  3. Expand the Automation section in the left menu, and then select Procedures.
  4. Double-click xMattersEvent.
  5. In the  Host field, replace “localhost” with the IP address of the Netcool/OMNIbus server:


  1. Double-click xMattersDelEvent .
  2. In the Host field, replace “localhost” with the IP address of Netcool/OMNIbus server:

Configuring event trigger

The default integration trigger is configured to send events into xMatters if an alert has a Severity of 4 (Major) or higher, is not "acknowledged", and has an XMState of "0" (which equals new). The trigger is also configured to target the "xMattersUsers" group created in the Netcool/OMNIbus database.

You can edit this trigger to change when alerts are sent into xMatters for notification.

To configure the event trigger:

  1. In the Netcool/OMNIbus Administrator, expand the  Automation section in the left menu, and then select  Triggers.
  2. Double-click xMatters_auto_dispatch_trigger.
  3. Edit the trigger to modify the conditions under which alerts are sent to xMatters.
  4. To change the targeted recipient, change "xMattersUsers" to a valid xMatters User or Group ID.


  1. Click OK.

Adding users and groups

Use the following steps to create a user or group inside Netcool/OMNIbus that can be targeted by xMatters notifications.

To create a target user:

  1. Open the Netcool/OMNIbus Administrator Application.
  2. Log into the Object Server.
  3. Open the User section and click Users > Add User.
  4. Specify a Username and Full Name for the user.
  5. Select the xMattersUsers group and add it to the user’s Assigned Groups.
  6. Click OK.

To create a target group:

  1. In the User section of the Object Server, click Groups > Add Group.
  2. Type a Group Name and Description for the new Group.
  3. Select the xMattersGroup role and add it to the group’s Applied Roles.
  4. Click OK.

Download resources


Have more questions? Submit a request


  • 1
    Kevin Akey

    The jconn2.jar file contained in the integrationservices/netcool/lib directory will need to be placed in the /integrationagent/lib folder for the callbacks to be processed correctly.  This is not identified anywhere in the instructions nor is it a natural byproduct of unzipping the provided integration file.  

  • 0
    Kevin Akey

    If you find that your Omnibus journal entries are not posting the delivery status correctly and you see 'undefined', the following change will correct the issue.

    In the netcool.js file you will need to update the DeliveryStatusHandler:

    FROM: var journalMessage = "xM event ID " + msg.incident_id + " has a delivery status of " + msg.deliveryStatus + " for recipient " + msg.recipient + "(" + msg.device + ") at " +;

    TO: var journalMessage = "xM event ID " + msg.incident_id + " has a delivery status of " + msg.deliverystatus + " for recipient " + msg.recipient + "(" + msg.device + ") at " +;

    Edited by Kevin Akey
  • 0
    Kevin Akey

    In the event, you are leveraging a multi-database multi-server architecture for NetCool, you will also want to ensure that the xMatters added database fields are setup to be replicated.

    Example File:/opt/IBM/tivoli/netcool/omnibus/etc/



    # xmatters integration custom replication fields


    'XMLastUpdated'         = '@XMLastUpdated',

    'XMResponder'           = '@XMResponder',

    'XMState'               = '@XMState',

    'XMTarget'              = '@XMTarget',


    'ServerName'       =    '@ServerName'           ON INSERT ONLY,


  • 0
    Kevin Akey

    Another option to backup the Netcool Omnibus database is to run nco_osreport which will create back SQL statements to restore/recreate the database.

    Sample command: nco_osreport - server <Object Server Instance Name> -user <Root> -password <if not root>

    This creates

    1. alertsdata.sql 
    2. application.sql
    3. automation.sql
    4. desktop.sql
    5. security.sql
    6. system.sql
  • 0
    Kevin Akey

    This integration does not currently support delete functionality.  As released, any Omnibus triggered deletes to terminate event activity in xMatter will not work.

    In reviewing this, a couple of changes were needed:

    1. serverserial is used as the unique identifier, unfortunately ServerSerial is not unique in failover scenarios between multiple databases.  So, in my case, we leveraged the Alert Identifier which guarentees uniqueness across primary and backup databases.  If you do not require this, then you should leverage ServerSerial.  Using this requires several levels of modification across the workflow.

    2. The xMatters REST API supports a Delete by Property call, which will need to be added to the integration and delete calls will need to be vectored to a function within the integfration that calls this.  To do this, we will need to ensure we know what is coming across from netcool (Is this an add event or del event action).  I added an "action" property and set the value to "add" for an xMatters event and "del" for termination of an event.  


    So, a couple of things:

    1. You will need to add an action parameter to your ibmnetcool.xml, I also recommend shifting your unique id (what you are going to delete using) up to the second parameter.
      <mapped-input method="add">
    2. You will need to update the or NetcoolAPClient.bat file
      - add a new second parameter to hold action (after client)
      - shift your serverserial (or other unique identifier) to the third parameter (after action)
    3. You will need a new constant in the configuration.js file to point to the REST API
      REST_SERVICE_URL = "";
    4. You will need the following function in the ibmnetcool.js
      * ---------------------------------------------------------------------------------------------------------------------
      * terminateEventByProperty
      * Terminates the first event found by property key/value
      * @input field name, field value
      * @retun null
      * ---------------------------------------------------------------------------------------------------------------------
      function terminateEventByProperty(fieldName, fieldValue)
      //get event by property value
      var response = XMIO.get(REST_SERVICE_URL + "/events?status=ACTIVE&properties=" + encodeURIComponent(fieldName) + "%23en%3D" + encodeURIComponent(fieldValue)
      + "%2C" + encodeURIComponent("notify_type") + "%23en%3D" + encodeURIComponent("groupnotify"));
      IALOG.debug("terminateEventByProperty - XMIO.get response.body: " + response.body);

      //set match string for a single record
      var matchStr = '{"total":1,';
      var noMatchStr = '{"total":0,';

      if (response.body.substring(0, matchStr.length).equalsIgnoreCase(matchStr)) {

      IALOG.debug("terminateEventByProperty - Found record for termination!");

      //setup match string and event base URL
      matchStr = '"records":[{"href":"';
      var eventUrl = response.body.substring(response.body.indexOf(matchStr)+matchStr.length);

      //build event url for REST API call
      eventUrl = eventUrl.substring(0, eventUrl.indexOf('"'));
      eventUrl = eventUrl.substring(eventUrl.indexOf("/events/"));
      IALOG.debug("terminateEventByProperty - Event URL: " + REST_SERVICE_URL + eventUrl);

      //terminate event
      response = XMIO.put(JSON.stringify({ status: 'terminated' }), REST_SERVICE_URL + eventUrl);

      if (response.status == 200) {"terminateEventByProperty - Event associated with '" + fieldName + "' = '" + fieldValue + "' has been terminated.");
      else {"terminateEventByProperty - Event associated with '" + fieldName + "' = '" + fieldValue + "' has failed to terminate.");"terminateEventByProperty - response.status: " + response.status.toString());
      IALOG.debug("terminateEventByProperty - XMIO.put response.body: " + response.body);
      else if (response.body.substring(0, noMatchStr.length).equalsIgnoreCase(noMatchStr)) {
      IALOG.debug("terminateEventByProperty - No event found for termination.");
      else {
      IALOG.debug("terminateEventByProperty - Multiple matches found, unable to identify a record for termination.");
      catch (err) {
      IALOG.error("terminateEventByProperty - Error querying xMOD for '" + fieldName + "' = '" + fieldValue + "' (message): " + err.message);
      IALOG.error("terminateEventByProperty - Error querying xMOD for '" + fieldName + "' = '" + fieldValue + "' (stack): " + err.stack);
    5. You will need to call the function, this should happen at the top of your entry function, in this case apia_event(), below any proxy setup you may have.

      if ( == "del") {
      var id =;
      IALOG.debug("Terminate event with id: " + id);
      terminateEventByProperty("serverserial", id);
      return null;
      else {
      //cleanup form properties: action
    6. In Netcool, you will need to ensure you adjust your xMattersEvent Procedures to pass an "add", you can replace the "NETCOOL" currently being passed.  I also recommend moving your netcool unique identifier (serverserial by default) to the position immediately after the "add".

    This will allow the Netcool -> xMatters delete functionality to work correctly and the xMattersDelEvent procedure to function in this integration.

  • 0
    Kevin Akey

    As there are no equivalent shell executable files to the windows batch fill outlined above, on unix a different approach is necessary.

    $OMNIHOME/bin/nco_sql -user root -password  "*****" -server <ObjectServerName>  -input <InstallerFiles>/xM-IBMNetcoolRest20/components/netcool-omnibus/unix/AP_Update_Unix.sql



Please sign in to leave a comment.
Powered by Zendesk