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 (xM-IBMNetcoolRest20.zip) 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.
Before configuring anything in Netcool, you'll need to configure xMatters.
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:
- Log in to the target xMatters system.
- On the Users tab, click the Add New User icon.
- Enter the appropriate information for your new user.
- Assign the user to the REST Web Service User role.
- Click Save.
- 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.
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.
The next step is to import the Netcool communication plan.
To import the Netcool communication plan:
- Log in to the target xMatters system.
- Click the Developer tab, and then click Import Plan.
- Click Browse, and then locate the following file from the extracted integration archive:
- Click Import Plan.
- Click Plan Disabled to enable the plan.
- In the Edit drop-down list, select Forms.
- 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.
- In the Web Service Only drop-down list, click Permissions.
- Enter the REST API user you created above, and then click Save Changes.
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.
The next step is to configure the applications event domain
To configure the applications event domain:
- Download the attached .zip or tar.gz file to your system, and then extract the contents.
- In the target xMatters system, on the Developer tab, click Event Domains.
- Click the applications link.
- Scroll to the bottom of the screen until you see Integration Services and click Add New.
- 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:
The installation package contains all that you need to configure the Netcool integration.
To install the package:
- Within the extracted integration archive, navigate to:
- 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.
- Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
- Save and close the file.
- 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. PASSWORD
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
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.
- Save and close the file.
- 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.
- Save and close the file.
- Restart the integration agent
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:
- Open a command prompt and navigate to <IAHOME>\bin.
- 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 <new_password> --old <old_password> --file conf/.initiatorpasswd
For more information about working with the iapassword command, and creating password files, refer to the xMatters integration agent guide.
Now that you've configured xMatters, it's time to configure Netcool; the archive attached to this article contains all that you need.
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:
- 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:
- Within the download package, locate the following file and copy it to the <IAHOME>/bin directory:
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:
- In Netcool/OMNIbus Administrator, click Automation > Triggers.
- In the Triggers list, open the connection_watch_connect trigger.
- In the Edit Signal Trigger dialog box, clear the Enabled check box, and then click OK.
- 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:
- Open the Netcool/OMNIbus Administrator and click System > Properties.
- Locate the following settings:
Ensure that these settings are the same as the user who starts and runs the NCO_PA application.
After you complete the pre-configuration steps, the first task is to configure the environment variables on your Netcool/OMNIbus machine.
- 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.
- 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.
The first required step to configure Netcool/OMNIbus for this integration is to update the database.
To update the Netcool/OMNIbus database:
- Back up the %OMNIHOME%\db\<ObjectServerName> directory (optional).
- Change your working directory to %OMNIHOME%\bin.
- 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)
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.
The procedures created by the integration need to be updated to include the IP address of the Netcool/OMNIbus server.
To edit the procedures:
- Open the Netcool/OMNIbus Administrator.
- Connect to the ObjectServer to use for xMatters events.
- This ObjectServer must have the xMatters SQL installed.
- Double-click xMattersDelEvent .
- In the Host field, replace “localhost” with the IP address of Netcool/OMNIbus server:
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:
- In the Netcool/OMNIbus Administrator, expand the Automation section in the left menu, and then select Triggers.
- Double-click xMatters_auto_dispatch_trigger.
- Edit the trigger to modify the conditions under which alerts are sent to xMatters.
- To change the targeted recipient, change "xMattersUsers" to a valid xMatters User or Group ID.
- Click OK.
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:
- Open the Netcool/OMNIbus Administrator Application.
- Log into the Object Server.
- Open the User section and click Users > Add User.
- Specify a Username and Full Name for the user.
- Select the xMattersUsers group and add it to the user’s Assigned Groups.
- Click OK.
To create a target group:
- In the User section of the Object Server, click Groups > Add Group.
- Type a Group Name and Description for the new Group.
- Select the xMattersGroup role and add it to the group’s Applied Roles.
- Click OK.