BMC Control-M delivers is business automation solution that simplifies and automates diverse batch application workloads. When events meet predetermined criteria, this integration with xMatters relays critical BMC Control-M insight data to the correct people and systems to help coordinate and resolve incidents faster. xMatters leverages your group on-call schedules and rotations, escalation rules, and user device preferences to quickly engage the right resources with customizable response and collaboration options.
Integrating xMatters with your other tools allows you to automatically transfer key BMC Control-M alert data throughout your systems and drive workflows forward. Notifications and collaboration invites embedded with BMC Control-M insights allow your resolution teams to take immediate action.
- Create a service management ticket with the BMC Control-M insights
- Invite people across multiple teams to a conference call with context from BMC Control-M
- Initiate a targeted chat room via Slack, HipChat or Hubot
- Record chat room activity back into a service management ticket
- BMC Control-M Workload Automation v9
- BMC CONTROL-M/EM API v9
- xMatters OnDemand
- xMatters integration agent 5.x (5.0 patch 007 or later)
The Control-M integration leverages shout destinations which submit events to xMatters Integration Agent via the Apclient.bin submission mechanism. Once the Integration Agent receives the events, the event information is POST'd to xMatters via a REST API.
This document provides information about installing the xMatters (IT) for BMC Control-M Workload Automation integration. This document also contains complete instructions on how to configure xMatters, BMC Control-M, and the integration components.
Installing the integration service and updating the integration agent
To configure the integration agent for the BMC Control-M integration, you must copy the integration components into the integration agent; this process is similar to patching the application, where instead of copying files and folders one by one, you copy the contents of a single folder directly into the integration agent folder (). The folder structure is identical to the existing integration agent installation, so copying the folder's contents automatically installs the required files to their appropriate locations. Copying these files will not overwrite any existing integrations. This integration includes the following components:
-
bin/Controlm-APClient.bat & bin/Controlm-APClient-Del.bat Batch files targeted by the SHOUT destinations from within Control-M. They take the SHOUT message and call APClient.bin.exe with the correct map-data for either the controlm20 service or the del service, depending on which SHOUT destination was used
-
conf/deduplicator-filter.xml The filtering mechanism used to suppress duplicate messages. By default, the filter checks the job_name, status and run_num values; if they are all the same within a two minute window, only the first message will be sent through to xMatters.
-
controlm-config.js: The main configuration file for the integration; includes API connection information and user information.
-
bmccontrolm.pwd: Stores the password for the Control-M API user used by the integration service. If you change the name of this file, you must also update the controlm-config.js files to point to the correct password file.
Once you have installed the files and folders, you will need to modify the controlm-config.js and IAConfig.xml files to suit your deployment configuration.
Note: If you have more than one integration agent providing the BMC Control-M service, repeat the following steps for each one.
To install the integration service:
-
Copy all of the contents of the /components/integration-agent/ folder from the extracted integration archive to the folder.
-
Open the IAConfig.xml file found in /conf and add the following line to the “service-configs” section: controlm20/controlm.xml
-
Open the controlm-config.js file (now located in /integrationservices/controlm20/ folder, and set the values for the following variables:
- CONTROL_M_USER: The user name to be used for the BMC Control-M API Server; default value is "username".
- CONTROL_M_HOST_NAME: Hostname of the BMC Control-M API Server; default value is "localhost".
- CONTROLM_PASSWORD_FILE: Location of the password file for the API user; default value is "conf/bmccontrolm.pwd".
- CTMEMAPI_PROPERTIES_FILE: Location of the CTMEMAPI_PROPERTIES_FILE; default value is "integrationservices/controlm20/ctmemapi.properties". For more information about this setting, see the following section, "Installing Control M/EM API server properties files"
- JACORB_PROPERTIES_FILE: Location of the JACORB_PROPERTIES_FILE; default value is "integrationservices/controlm20/jacorb.properties". For more information about this setting, see the following section, "Installing Control M/EM API server properties files".
- SLEEP_PERIOD_BETWEEN_CALLBACK: The amount of time (in milliseconds) to sleep between receiving a SHOUT Message and making the callback to the BMC Control-M API for the job details. (Default is 3000, or three seconds.)
- DEDUPLICATOR_FILTER: Name of the deduplicator filter; i.e., the attribute name for the element filter in the deduplicator-filter.xml file. The default value is controlm20.
-
Save and close the file.
-
Open the Controlm-APClient.bat and Controlm-APClient-Del.bat files (now located in
<IAHOME>/bin) in a text editor, and change the value for the "IAHOME" variable to the location of the<IAHOME>/binfolder on your machine. (The default isC:/PROGRA~1/xmatters/integrationagent/bin). -
Save and close the files.
-
Restart the integration agent.
On Windows, the integration agent runs as a Windows Service; on Unix, it runs as a Unix daemon
This procedure describes how to install Control-M/EM API on Windows and UNIX.
Due to Java limitations, BMC Software recommends that you do not install Control-M/EM API in a directory with a path that contains spaces or other special characters. If you install Control-M/EM API on an account where an earlier version of Control-M/EM API is installed, see attached Control-M/EM API pdf (on page 19) before continuing.
Before you begin Ensure the following is installed:
- Control-M/EM in your network environment
- Java Developer's Kit (JDK) version 1.6.x or later or Java Runtime Environment (JRE) version 1.6.x or later on the computer hosting your project's working directory.
JAVA_HOMEenvironment variable should point to the JDK/JRE directory/library.
_Note: The JAVA_HOME environment refers to the directory where the JRE is installed. The JDK contains the JRE, but at a different level in the file hierarchy. For example, if the Java 2 SDK or JRE was installed in /ctm_em/user1, JAVA_HOME would be either:/ctm_em/user1/jdk1.6.x/jre [JDK] or /ctm_em/user1/jre1.6.x [JRE].
To Install Control-M/EM API:
Do one of the following to create the emapi-900 directory:
- Microsoft Windows: Unzip the
emapi-900-nt.zipfile from the cdPath/Setup_files/TOOLS/EMAPI_FILESdirectory on the Control-M/EM installation CD to any location. - UNIX:
- Solaris, AIX, HP-UX or HP-UX Itanium: Locate the
emapi-900-UNIX.TAR.Ztar file in thecdPath/Setup_files/TOOLS/EMAPI_FILESdirectory on the Control-M/EM installation CD and type the following command to open and uncompress the file to any directory: uncompress-c cdPath/TOOLS/EMAPI_FILES/emapi-900-UNIX.TAR.Z | tar xvf - RedHat or Suse: Locate the
emapi-900-UNIX.TAR.gztar file in thecdPath/Setup_files/TOOLS/EMAPI_FILESdirectory on the Control-M/EM installation CD and type the following command to open and uncompress the file to any directory:
- Solaris, AIX, HP-UX or HP-UX Itanium: Locate the
-gunzip -c cdPath/TOOLS/EMAPI_FILES/emapi-900-UNIX.TAR.gz | tar xvf-
All Control-M/EM API files and sub-directories are located in this directory. See attached Control-M/EM API primary subdirectories (on page 12).
NOTE: To uninstall Control-M/EM, delete the Control-M/EM API directory according to your version. For example, for version 9.0.00 delete the emapi-900 directory. Do not copy the Control-M/EM API version 9.0.00 files directly over the previous installation This may cause unpredictable behavior.
When you install the Control-M/EM API server, it creates two properties files within its installation folder: ctmemapi.properties and jacorb.properties . Both of these files are required by the integration to access and communicate with the API server.
To ensure that the integration can access these properties files, do one of the following:
- Copy both ctmemapi.properties and jacorb.properties from the Control-M/EM API server installation folder to the
<IAHOME>/integrationservices/controlm20folder. - The files are located in the following location:
- ctmemapi.properties:
<API Directory>/emapi-900/ - jacorb.properties:
<API Directory>/emapi-900/etc
- ctmemapi.properties:
- Copy the emapi.jar and jacorb.jar from the Control-M API to the
integrationservices/libdirectory.- Both files can be found here:
<API Directory>/emapi-900/classes
- Both files can be found here:
- Update the
CTMEMAPI_PROPERTIES_FILEandJACORB_PROPERTIES_FILEparameters in thecontrolmconfig.jsfile to point to the location of the files within the API server folder.
The password for the BMC Control-M user is stored in an encrypted password file, stored in the /conf subfolder. For the integration to connect to the API, you will have to replace the default value ("password") with the password of the database user specified in the controlm-config.js file (as described in the table above.)
Note: For more information about the integration agent's IAPassword feature used to encrypt the password, see the xMatters integration agent guide.
To change the encrypted password:
- Navigate to the /bin subfolder, and then run the following command, replacing with the password of the BMC Control-M user:
./iapassword.sh --new "<newPassword>" --old password --file conf/bmccontrolm.pwd
Note: that if you want to change this password again, you will have to replace "password" in the above command with the existing password.
The following sections describe how to configure BMC Control-M to combine with xMatters.
The first step in configuring BMC Control-M is to specify the destinations for the xMatters and xMattersDel shout destinations.
To define shout destinations:
-
In the BMC Control-M Workload Automation Configuration Manager, open the Shout Destinations Manager.
-
Select Actions > Add Shout table (or Update Shout Table to modify an existing table).
-
Add a Shout Destination with the following properties:
- Logical Name: xMatters
- Address: Server
- Destination: Program
- Value: Type the location of the integration agent's bin folder where the Controlm-APClient.bat file was installed; for example:
C:/PROGRA~1/xmatters/integrationagent/bin/Controlm-APClient.bat
-
Add another Shout Destination with the following properties:
- Logical Name: xMattersDel
- Address: Server
- Destination: Program
- Value: Type the location of the integration agent's bin folder where the Controlm-APClient-Del.bat file was installed; for example:
C:/PROGRA~1/xmatters/integrationagent/bin/Controlm-APClient-Del.bat
Once you have defined the shout destinations, you can add them to a job in your system. The xMatters shout (Controlm-APClient.bat) sends notifications into xMatters, and allows users to take actions depending on the current state of the job when the notification is sent. The xMattersDel shout (Controlm-APClient-Del.bat) is used to clean up outstanding notifications; you can use this when a job ends with an OK state to remove any outdated notifications from xMatters.
To use the xMatters shout destination for a job:
-
In the BMC Control-M Workload Automation Configuration Manager, open the job to which you want to add the shout destination.
-
Open the Actions tab, and add an On-Do Action for the job.
-
In the On drop-down list, select the action you want to use as the trigger for the notification.
-
In the Do drop-down list, select Notify.
-
In the Destination field, select xMatters, and select an Urgency.
-
In the Message field, type
%%ORDERIDand then use the following syntax to specify the recipients and any custom message you want to add:
%%ORDERID;<userID>,<userID2>;<message>
Note that you must use semi-colons (;) to separate the components in the message field, and commas (,) to separate the xMatters User IDs that identify the recipients. For example:
%%ORDERID;bsmith,cogrady,admin;The job was completed and assigned.
- Click OK to save the action.
To use the xMattersDel shout destination for a job:
-
In the BMC Control-M Workload Automation Configuration Manager, open the job to which you want to add the shout destination.
-
Open the Actions tab, and add an On-Do Action for the job.
-
In the On drop-down list, select the action you want to use as the trigger.
-
In the Do drop-down list, select Notify .
-
In the Destination field, select xMattersDel , and select an Urgency .
-
In the Message field, type
%%ORDERID -
Click OK to save the action.
Configuring xMatters to combine with BMC Control-M Workload Automation requires the following step:
- Import of Communication plan
- Access Inbound Integration URL's
- REST API User
- Permissions
- Login to xMatters OnDemand
- Navigate to the Developer tab
- Import the Control-M Communication Plan
To successfully configure the controlm-config.js navigate to xMatters OnDemeand to retrieve the inbound integration URL's.
- Login to xMatters OnDemand
- Navigate to the Developer tab
- Find the newly imported Control-M communication plan
- Select Edit > Integration Builder
- From within the Integration Builder, open Inbound Integrations
- From within the Inbound Integrations, individually select the link for each inbound integration, and map accordingly to the controlm-config.js file.
- The Inbound Integration URL's should be mapped to
XMATTERS_IB_INBOUND_INTEGRATIONSin the controlm-config.js
To successfully integration and submit to xMatters OnDemand, it is necessary to configure a REST API User in xMatters.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in the reports and Communication Center, you may want to identify the user as specific to Control-M; for example:
- First Name: Control-M
- Last Name: Integration
- User ID: controlm.rest
- Assign the user to the REST Web Service User, Group Supervisor, and Person Supervisor roles.
- Set the user ID and password.
- Make a note of these details; you will need them when configuring other parts of the integration.
- Click Save.
In the Edit drop-down list for the plan, select Forms. For the Incident Alerts form, click the Not Deployed drop-down list, and then select Create Event Web Service (in some deployments, Enable for Web Service). In the Web Service Only drop-down list, click Permissions. Add the REST API user you created above, and then click Save Changes. Repeat steps 6-8 for the Engage with xMatters and Conference Bridge forms.
- Login to xMatters OnDemand
- Navigate to the Developer tab
- Find the newly imported Control-M communication plan.
- From the Edit dropdown select Access Permisssions
- Add the following role:
- Rest Web Services User
To configure the endpoints:
- On the communication plan, click the Integration Builder tab, and then click the Edit Endpoints button to display the endpoints for the integrations.
- Click the xMatters endpoint, assign the endpoint to the integration user you created in step 5.3 and then click Save Changes.
The following sections will test the combination of xMatters and BMC Control-M for notification delivery and response.
After configuring xMatters and BMC Control-M, you can validate that communication is properly configured. It is recommended that you start the components in the following order:
- BMC Control-M
- xMatters integration agent
- xMatters
To trigger a notification, run a new job in BMC Control-M, and cause it to enter a state for which you have defined an xMatters Shout Message:
This section describes how to respond to a notification from xMatters. In the following example, the notification is received in an email, but the process is similar for all Devices.
To respond to a notification:
- When a notification arrives for the User, open it to view the details:
- The list of possible replies is located at the bottom of the notification. For email notifications, click one of the response option to send your response to BMC Control-M. Note that in the default integration configuration, you can also select response options to retrieve information about the job from BMC Control-M.
- To view the results of the response, view the job report details in BMC Control-M. In the following image, you can see that the notified user selected the "Rerun" response option, causing the job to be rerun:
- Consult the Control-M EM API Documentation if experiencing any issues related to the Control-M API Installation.
- Consult the Integration Agent Documentation if experiencing any issues related to configuring the Integration Agent
- Consult xMatters Help if experiencing any issues within xMatters OnDemand.