XM BMC Controlm v201

xMatters (IT) engine
for BMC Control-M Workload Automation
This manual provides information about xMatters. Every effort has been made to make it as complete and accurate as possible;
however, the information it contains is subject to change without notice and does not represent a commitment on the part of
xMatters. No part of this document may be reproduced by any means without the prior written consent of xMatters.
AlarmPoint Systems, Inc. is now xMatters, inc. This change extends to how we name our products: the AlarmPoint Integration
Agent is now the xMatters integration agent; AlarmPoint Enterprise is now xMatters enterprise; and so on. You can learn more
about why we changed our name at www.xmatters.com. During the ongoing transition to the new naming conventions, legacy
corporate and product names will still appear in some parts of our products, such as directory paths, logs, and messages. This
document reflects the new names whenever possible, while respecting the need for clarity when referring to older products,
legacy issues, existing knowledge base articles, etc.
Wednesday, September 11, 2013
Copyright 1994-2013. All rights reserved.
xMatters, xMatters, xMatters Java Client, xMatters mobile access, xMatters integration agent, xMatters lite, xMatters
workgroup, xMatters enterprise, xMatters service provider, xMatters on demand, and xMatters Notification Server are
trademarks of xMatters, inc.
All other products and brand names are trademarks of their respective companies.
Contacting xMatters
You can visit the xMatters Web site at: http:///www.xmatters.com
From this site, you can obtain information about the company, products, support, and other helpful tips. You can also visit the
Customer Support Site from the main web page. In this protected area, you will find current product releases, patches, release
notes, a product knowledge base, trouble ticket submission areas and other tools provided by xMatters, inc.
xMatters, inc.
Corporate Headquarters
4457 Willow Road, Suite 220
Pleasanton, CA 94588
Sales and Technical Support:
Telephone: 925-226-0300
Facsimile: 925-226-0310
support@xmatters.com
sales@xmatters.com
Customer Support Site: http://community.xMatters.com
This integration was designed and tested on an unmodified version of BMCControl-M Workload Automation, and this
document describes how to configure xMatters to integrate with the default installation. If you have customized or altered your
instance of BMC Control-M, this integration may need to be modified for your deployment. Please note that these integration
changes are not part of the services offered by xMatters Technical Support, but can be performed through xMatterss
Professional Services department. For more information, contact your xMatters Sales representative.
Proprietary and Confidential 2013 xMatters, inc
Table of Contents
Chapter 1: Introduction
1.1 Summary
1
1
1.1.1 Benefits
1.1.2 Integration Architecture
1.2 System Requirements

1.2.1 Operating Systems
1.3 Conventions and Terminology
2
3
3
1.3.1 Conventions
1.3.2 Terminology
Chapter 2: Installation and Configuration

2.1 Installing the integration
5
5
2.1.1 Installing the integration service and updating the integration agent
2.1.2 Installing Control M/EMAPIserver properties files
2.1.3 Updating the user password
2.1.4 Installing voice files
2.2 Configuring BMCControl-M Workload Automation
2.2.1 Define shout destinations
2.2.2 Using shout destinations
2.3 Configuring xMatters
10
2.3.1 Importing Event Domain and scripts
10
2.3.2 Subscribing to Alerts
11
Chapter 3: Integration Validation
14
3.1 Triggering a notification
14
3.2 Responding to a notification
14
3.3 Viewing response results
17
Chapter 4: Optimizing and Extending the Integration
18
4.1 Manually configuring xMatters
18
4.1.1 Importing the script package
18
4.1.2 Configuring the Event Domain
18
4.2 Adding new parameters
20
4.3 Response choices
20
4.3.1 Changing and adding response choices
21
4.4 Delivery Annotations
22
4.5 Altering the duration of events
22
xMatters (IT) for BMCControl-MWorkload Automation
4.6 Terminating existing events
22
4.7 Troubleshooting
22
4.7.1 Installing the BMC Control-M APIServer

4.8 Uninstalling
Chapter 5: Configuration Variable Reference

5.1 Global configuration variables
ii
22
23
24
24
Welcome to xMatters (IT) for BMCControl-MWorkload Automation; this document describes how to install and
configure xMatters and BMCControl-M Workload Automation software for integration. The intended audience for
this document is experienced consultants, system administrators and other technical readers.
1.1 Summary
xMatters is an interactive alerting application, designed to capture and enrich important events, to route those events
to the right person on any communication device, and to give that person the ability to solve, escalate, or enlist
others to resolve the events remotely.
xMatters allows you to take critical business information and contact the right people via voice phone, SMS, twoway pagers, instant message, and email.
Through integration modules, xMatters can become the voice and interface of an automation engine or intelligent
application (the Management System, such as BMCControl-M Workload Automation). When BMC Control-M
detects something that requires attention, xMatters places phone calls, sends pages, messages, or emails to the
appropriate personnel, vendors or customers.
xMatters is also persistent, escalating through multiple devices and personnel until someone accepts responsibility or
resolves the problem. Once contacted, xMatters gives the notified person instant two-way communication with
BMCControl-M Workload Automation. Responses are executed immediately on BMC Control-M, enabling remote
resolution of the event.
This integration supports job notifications (from BMC Control-M to xMatters) via web services. It also supports
inbound actions (from xMatters to BMC Control-M).
1.1.1 Benefits
With the xMatters integration, the appropriate technician can be notified directly via voice, email, pager,
BlackBerry, or other device. Information about the failure will be presented to the event resolver and decisions can
be made in real-time.
Once a response is selected on the recipients remote device, xMatters will update the BMC Control-Mjob in realtime. The benefit is that this process is immediate significantly faster than the time required for staff to notice the
failures or malfunctions, determine who is on call, and manually notify the right person. In addition, the ability to
take simple actions on the event from any device gives the event resolver a quick way to deal with many issues and
communicate to other team members the current state of the event.
During the process, every notification, response, and action is logged in xMatters. In addition, xMatters
automatically annotates the original BMC Control-Mjob with status information.
The xMatters product features a self-service web user interface to allow accurate assignment of responsible personnel
for each job.
1.1.2 Integration Architecture

This integration integrates xMatters and BMC Control-M via Shout Destinations and the BMC Control-M API and
command line interface.
The following steps identify the numbered steps in the above diagram:
1. BMC Control-M jobs, which are associated with xMatters Shout Destinations, send Shout Messages to the ControlmAPClient.bat file.
2. The Shout Messages are then sent to the xMatters integration agent via the APClient.bin.exe.
3. The integration agent parses the Shout Message to retrieve the ORDER_ID, recipients, and custom message, and then
uses the request_act_retrieve_jobs call in the APIto retrieve the job details from BMC Control-M.
4. The job details are then sent along with the recipients via the integration agent to xMatters. Once they receive a
notification, the recipients have the ability to respond to xMatters.
5. These responses return to the integration agent, which uses the command line interface to interact with the BMC
Control-M server. The requests from xMatters are sent to the command line interface, and the responses to the command
line interface requests are sent back to xMatters via FYInotifications (note that these FYInotifications are configured
by default in the xMatters scripts to be sent back to only email Devices).
You may need to modify this configuration to suit your particular business requirements and adjust it to suit your expected
loads. For example, the default integration features automatic status annotations to the original job that indicate each stage of
delivery; in a high-volume production system, this can significantly affect performance. Consider your expected volume of
injected events and your server capacity when designing your own integration with xMatters.
Note:
The xMatters integration agent must be installed on the same server as BMC Control-M.
1.2 System Requirements

The following products must be installed and operating correctly prior to integration:
xMatters:
l
xMatters (IT) engine5.0 (patch 009 or later)
xMatters integration agent5.0 (patch 007 or later)
xMatters Developer IDE
Chapter 1: Introduction | 2
BMC Control-M:
l
BMCControl-M Workload Automationv8
BMCControl-M/EMAPIServer v8
l
For more information about installing and configuring this component to work with this integration, see
"Troubleshooting" on page 22.
1.2.1 Operating Systems

The following component versions, operating systems and databases are supported by this integration.
Integration Component
Version
Operating System
Database
xMatters (IT) engine
5.0 patch 009
Linux CentOS 5.3
Oracle 11g
Microsoft Windows 2008 R2

(validated)
SQLServer 2008
(validated)
xMatters integration agent
5.0 patch 007
Linux CentOS 5.3

(validated)
BMCControl-M Workload
Automation
v8

(validated)
All operating systems supported
by the xMatters integration agent
(validated with
Microsoft SQLServer
2008)
For more information about the supported operating systems for xMatters, refer to the xMatters installation and
administration guide and xMatters integration agent guide.
1.3 Conventions and Terminology

This section describes how styles are used in the document, and provides a list of definitions.
1.3.1 Conventions
Some instructions appear in the following format: MENU > OPTION; for example, File > Open means click the File menu,
and then click the Open menu option.
Words in bold typically reference text that appears on the screen. Words in monospace font represent the following:
l
text that must be typed into the computer
directory and file names
code samples
Directory paths
Except where explicitly stated, the directory paths in this document are listed in Windows format. Unix users must substitute
the given paths with the Unix equivalents.
The xMatters installation folder is referred to throughout the documentation as <xMHOME>.
l
On Windows systems, the default is C:\Program Files\xMatters
On Unix systems, the default is /opt/xmatters
The xMatters integration agent installation folder is referred to throughout the documentation as <IAHOME>.
l
On Windows systems, the default is C:\Program Files\xmatters\integrationagent.
On Unix systems, the default is /opt/xmatters/integrationagent.
1.3.2 Terminology
The following terms are used through the xMatters documentation.
Documentation terminology
Term
Meaning
Event
An event refers to any situation or item of interest detected by the management system, and which
requires attention. Event is also used to refer to the incident or situation as it progresses through the
xMatters system, from injection to notification to resolution. Each event must generate at least one
alert or notification.
Event can also be a generic term used to refer to an incident, change request, message, or other
specific item within the management system. Whenever possible, these situations are referred to
using the management system's preferred terminology, but can also collectively be called events.
Management system A management system is any sort of monitoring or managing software that watches for events, and
with which xMatters can combine; i.e., a synonym for BMC Control-M.
Device
The medium through which a recipient is contacted by xMatters; i.e., email, pager, phone,
BlackBerry, etc.
User
In xMatters, people who can receive notifications are called "Users". Each person in the xMatters
system is defined by a set of User details, including IDnumber, user name, login password, and so
on.
Group
Groups are used to collect and organize Users and Devices into notification schedules. For a
complete explanation of Groups in xMatters, see the xMatters user guide.
Chapter 2: Installation and Configuration

This chapter provides information about installing the xMatters (IT) for BMCControl-MWorkload Automation integration.
This chapter also contains complete instructions on how to configure xMatters, BMC Control-M, and the integration
components.
2.1 Installing the integration

This section describes the installation process for the xMatters (IT) for BMCControl-MWorkload Automation integration.
2.1.1 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 (<IAHOME>). 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:
Component
Description
bin/Controlm-APClient.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.
bin/Controlm-APClient-Del.bat
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 APIuser 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:

1. Copy all of the contents of the \components\integration-agent\ folder from the extracted integration archive to
the <IAHOME> folder.
2. Open the IAConfig.xml file found in <IAHOME>\conf and add the following line to the service-configs section:
<path>controlm20/controlm.xml</path>
3. Open the controlm-config.js file (now located in <IAHOME>\integrationservices\controlm20\ folder, and set
the values for the following variables:
Chapter 2: Installation and Configuration | 5
Variable
Description
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 APIServer; 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/EMAPIserver 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/EMAPIserver properties files".
SLEEP_PERIOD_BETWEEN_CALLBACK
The amount of time (in milliseconds) to sleep between receiving a

SHOUTMessage and making the callback to the BMCControl-M
APIfor 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.
4. Save and close the file.

5. 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>\bin folder on your machine.
(The default is C:\PROGRA~1\xmatters\integrationagent\bin).
6. Save and close the files.
7. Restart the integration agent.
l
On Windows, the integration agent runs as a Windows Service; on Unix, it runs as a Unix daemon.
2.1.2 Installing Control M/EMAPIserver properties files

When you install the Control-M/EMAPIserver, 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 APIserver.
To ensure that the integration can access these properties files, do one of the following:
l
Copy both ctmemapi.properties and jacorb.properties from the Control-M/EMAPIserver installation folder to
the <IAHOME>\integrationservices\controlm20 folder.
Update the CTMEMAPI_PROPERTIES_FILE and JACORB_PROPERTIES_FILE parameters in the controlmconfig.js file to point to the location of the files within the APIserver folder.
Note:
For more information about installing the BMC Control-M API, refer to "Troubleshooting" on page 22.
2.1.3 Updating the user password

The password for the BMC Control-M user is stored in an encrypted password file, stored in the <IAHOME>/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:

1. Navigate to the <IAHOME>/bin subfolder, and then run the following command, replacing <newPassword> 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.
2.1.4 Installing voice files

These files must be installed into any xMatters deployment running a voice Device Engine. For more information, refer to the
xMatters installation and administration guide.
This integration provides a complete set of English voice files.
To install the voice files:
1. Determine the value of the File Identifier associated with your Company.
l
To find your Company's File Identifier, log into the xMatters web user interface as the Super Administrator, and
view the target Company's Details page (Admin tab >Companies >Company name).
2. Copy the contents of the \components\xmatters\vox\ folder from the extracted integration archive to the following
node installs folder:
<xMHOME>\node\phone-engine\Datastore\<FILE_IDENTIFIER>\
For example, if you were installing the integration for the Default Company on an out-of-the-box deployment, the installation
paths for the voice files would be as follows:
<xMHOME>\node\phone-engine\Datastore\1\controlm20\recordings\english\phrases
Note that if this is the first custom Event Domain you have created, the <FILE_IDENTIFIER> directory will not have been
created yet. You can create it manually or log into xMatters and use the web user interface to add a new voice recording. If
the Phone Device Engine is running, xMatters will create the directory structure and place the new voice recording in it.
2.2 Configuring BMCControl-M Workload Automation

The following sections describe how to configure BMC Control-M to combine with xMatters.
2.2.1 Define shout destinations

The first step in configuring BMC Control-M is to specify the destinations for the xMatters and xMattersDel shout
destinations.
To define shout destinations:

1. In the BMCControl-M Workload Automation Configuration Manager, open the Shout Destinations Manager.
2. Select Actions >Add Shout table (or Update Shout Table to modify an existing table).
3. Add a Shout Destination with the following properties:
l
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
4. Add another Shout Destination with the following properties:

l
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
2.2.2 Using shout destinations

Once .you have defined the shout destinations, you can add them to a job in your system. The xMatters shout (ControlmAPClient.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 anOK state to remove any outdated notifications from xMatters.
To use the xMatters shout destination for a job:

1. In the BMCControl-M Workload Automation Configuration Manager, open the job to which you want to add the
shout destination.
2. Open the Actions tab, and add an On-Do Action for the job.
3. In the On drop-down list, select the action you want to use as the trigger for the notification.
4. In the Do drop-down list, select Notify.
5. In the Destination field, selectxMatters, and select an Urgency.
6. In the Message field, type %%ORDERID and 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.
7. Click OKto save the action.

To use the xMattersDel shout destination for a job:
1. In the BMCControl-M Workload Automation Configuration Manager, open the job to which you want to add the
shout destination.
2. Open the Actions tab, and add an On-Do Action for the job.
3. In the On drop-down list, select the action you want to use as the trigger.
4. In the Do drop-down list, select Notify.

5. In the Destination field, selectxMattersDel, and select an Urgency.
6. In the Message field, type %%ORDERID
7. Click OKto save the action.
2.3 Configuring xMatters

Configuring xMatters to combine with BMCControl-M Workload Automation requires the following steps:
l
Import the Event Domain package
Configure the Event Domain, including Integration Service and Event Domain Constants
2.3.1 Importing Event Domain and scripts

The integration package includes an XMLfile that was created using the xMatters "Export Integration" feature; this greatly
simplifies the xMatters configuration process by enabling you to create the integration Event Domain, configure the
predicates and Event Domain Constants, and import the integration script package in a single step.
To import the integration Event Domain package:
1. Log in to xMatters as a Company Administrator, and click the Developer tab.
2. On the Event Domains page, click Import New.
3. On the Import Integration page, click Browse, and then locate the xM-BMC-Control-M.xml file extracted from the
integration archive.
4. Click Open, and then click Upload.
xMatters imports the integration configuration settings and displays the new controlm20 Event Domain.
Defining the integration service

For the installation to be successful, the integration service name must match the name specified in the controlmconfig.js file and the controlm.xml file installed on the integration agent.
To define an Integration Service:
1. In xMatters, on the Event Domains page, click the controlm20 Event Domain.
2. On the Event Domain Details page, in the Integration Services area, click Add New.
3. Enter the following information into the form:
l
Name: controlm20
Description: BMC Control-M Integration Service
Specifying connection parameters

Once you have imported the Event Domain package and configured the Integration Service, you must specify an xMatters
address that is reachable from within a notification so that responses can be processed.
To specify the connection constants:
1. On the Event Domains page, in the Domains menu, click Event Domain Constants.
2. In the Event Domain drop-down list, select controlm20, and then click Continue.
l
xMatters displays the pre-configured Event Domain Constants for the integration:
3. In the Event Domain Constants list, specify the correct values for the following constants (click the name of a constant
to edit its value and description):
Event Domain Constants

Constant Name
Default Value
Description
XMATTERSURL
http://localhost:8888
Used to specify the address of the xMatters web server. The links
provided in notification content use the xmattersurl constant value
to locate the xMatters web server which would process the response.
For these links to work, this address must be reachable from the
Device where the User will receive the notification; normally, this is
the IPaddress or fully-qualified host name of the xMatters web
server.
BESPUSHURL
http://localhost:8888/static
Used to specify the address of the BES device server.
Note:
For more information about the Event Domain Constants included in the integration and how to configure them to
suit your deployment, see "Defining Event Domain Constants" on page 19.
2.3.2 Subscribing to Alerts

The Subscriptions feature in xMatters determines who should receive notifications about BMC Control-Mjobs. For example,
you could configure a subscription that would send an informational notification to a specific User for each job that had a
status of "Ended not OK".
To allow Users to subscribe to specific criteria on injected events, you must configure the Subscription using the following
steps:
n
Update the Event Domain predicates
Define a Subscription Domain
Create a Subscription
Create a Fail-Safe Group
Updating Event Domain predicates

The Event Domain predicates are created as part of importing the Event Domain. You can add more predicates or remove
existing ones to suit your deployment; this section describes how to modify predicates.
Each predicate in xMatters must match the name of an event token in BMC Control-M, such as "job_name", "server", or
"machine". To see where the tokens in your deployment are set, view the "polling_method" function in the controlm20job-polling-thread.js file installed on the integration agent.
To define the Event Domain predicates:
1. In xMatters, click the Developer tab.
2. On the Event Domains page, click controlm20.
3. On the Event Domain Details page, click the Add New link beside the Predicates heading.
4. Add the following predicates to the Event Domain:
Event Domain predicates
Predicate
Type
Important Description
job_name
Text
Yes
controlm_server
Text
Yes
Name of the job for which notifications are being sent.
Predicate
Type
Important Description
order_id
Text
Yes
message
Text
task_type
Text
application
Text
job_status
Text
Note:
The status of the job in BMC Control-M; default values are:

l
Ended OK
Ended not OK
Executing
Wait Condition
Wait Resource
Wait User
Not in AJF
Unknown
For more information about predicates and how they work in xMatters, see the xMatters installation and
administration guide.
Defining a Subscription Domain

The Subscription Domain is the reference point of the Subscription panel and allows you to control who can create
Subscriptions, how recipients can respond to Subscription notifications, and which Event Domain predicates can be used to
create a Subscription. You must create a Subscription Domain before you can create Subscriptions with the new panel.
To create a Subscription Domain:
1. On the Developer tab, in the Domains menu, click Subscription Domains.
2. On the Subscription Domains page, click Add New.
4. On the Subscription Domain Details page, in the Name field, type BMCControl-M.
5. In the Type of Management drop-down list, select Both.
6. Click Continue.
7. On the Select Appropriate Response Choices page, add the following response choices, and then click Continue.
l
Rerun
Force OK
Confirm
Kill
Request Job Logs By Email
Request Job Output By Email
Request Job Statistics By Email
8. On the Select Appropriate Predicates page, add all of the predicates to the Applied Predicates list, and then click
Continue.
9. On the Select Roles page, specify the Roles you want to be able to create Subscriptions on the Domain, and then click
Save.
Note:
For more information about working with Event and Subscription Domains, see the xMatters installation and
administration guide.
Creating a Subscription
Once you have created a Subscription Domain, you can create and assign Subscriptions to notify recipients about jobs that
match specific criteria.
To create a Subscription:
1. On the Alerts tab, in the Alerts menu, click Assign Alerts.
2. Select the BMCControl-M Subscription Domain, and click the Add New link.
3. On the Subscription Details page, specify a name for the Subscription, and set the Subscription criteria.
4. In the Recipients area, specify the Users that should receive notifications for this Subscription.
5. When you are satisfied with the criteria, click Save to create the Subscription.
Creating a fail-safe Group

If an event is submitted to xMatters when the fail-safe functionality is enabled, and there is no Device or User that matches
the event, xMatters sends the notification to the fail-safe recipient. The fail-safe recipient is typically a Group, but can be
configured as a User.
To create a fail-safe Group:
1. In xMatters, click the Groups tab.
2. Create a new Group named BMCCTRLM FailSafe, with at least one User as a Team member to receive notifications.
For more information about creating Groups and Teams, see the xMatters user guide.
Note:
If you want to use an existing Group or a different Group name, modify the value for the failsafegroup Event
Domain Constant, as explained in "Configuring the Event Domain" on page 18.

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:
l
BMC Control-M
xMatters integration agent
xMatters
3.1 Triggering a notification

To trigger a notification, run a new job in BMC Control-M, and cause it to enter astate for which you have defined
an xMatters Shout Message:
3.2 Responding to a notification

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:
1. When a notification arrives for the User, open it to view the details:
14
2. 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.
15
Job logs:
Job output:
16
Job Statistics:
3.3 Viewing response results

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:
17
Chapter 4: Optimizing and Extending the Integration

This section describes some of the available methods you can use to optimize or extend the xMatters (IT) for BMCControlMWorkload Automation integration.
4.1 Manually configuring xMatters

This integration includes an exported version of the xMatters script package and Event Domain, including Event Domain
constants and predicates. If you do not want to use the included XMLfile to create and configure the required Event Domain
and Action Scripts, the following sections describe how to manually configure these components.
4.1.1 Importing the script package

This integration includes a script package specific to BMC Control-M. To install the script package, you need to import it
into the database, and configure the xMatters scripts to enable callout annotations.
Note:
This step requires the xMatters Developer IDE. For installation instructions, refer to the xMatters Online
Developer's Guide.
To import and configure the script package:

1. Launch the IDE, and then configure the database connection.
2. Click Workspace > Import.
3. Select the xM-BMC-Control-M\components\xmatters\scripts\xM-BMC-Control-M.xml file extracted from the
integration archive, click Open, and then click OK.
4. When the script has finished importing, click OK.
5. Right-click the BMCControl-M (BUSINESS) folder, and then select Validate.
6. Right-click the DefaultCompany folder, and then select Check In.
7. In the Create Script Package dialog box, click Create.
8. In the Check In dialog box, click Close.
4.1.2 Configuring the Event Domain

By default this integration is set up to use an Event Domain of controlm20; it is strongly recommended that you use this
default Event Domain.
Note:
The xMatters web server must be running to perform this portion of the integration.
To define an Event Domain:

1. Sign on to xMatters as a Company Administrator, and click the Developer tab.
2. In the Developer menu on the left side of the screen, click Event Domains.
3. On the Event Domains page, click Add New.
l
Name: controlm20
Description: BMCControl-M
Script Package: BMCControl-M Integration
5. Click Save.
Chapter 4: Optimizing and Extending the Integration | 18
Defining Event Domain predicates

This integration uses the Subscriptions feature of xMatters to target notification recipients. You must configure the Event
Domain predicates for the "controlm20" Event Domain, as described in "Updating Event Domain predicates" on page 11.
Defining an Integration Service

For the installation to be successful, the integration service name must match the service specified in the controlm.xml file
installed on the Integration Agent.
To define an Integration Service:
1. In xMatters, on the Event Domains page, click the controlm20 Event Domain.
2. On the Event Domain Details page, in the Integration Services area, click Add New.
l
Name: controlm20
Description: BMC Control-M Integration Service
4. Click Save.
Defining Event Domain Constants

Company Administrators and Developers can create Event Domain Constants that will be available in scripting for all event
objects associated with an Event Domain. This integration uses Event Domain Constants to define custom values for the
integration script package.
The integration script package uses the names of the constants defined in the table below to look up the values; it is strongly
recommended that you use the names specified. Note that the values for the webserverurl and bespushurl constants should
be modified to specify the address of the xMatters web server (to enable the HTML response options) and the BES device
server.
To add an Event Domain Constant:
1. In xMatters, click the Developer tab, and then, in the menu on the left side of the screen, click Event Domain
Constants.
3. On the Event Domain Constants page, click Add New.
4. Define a Constant Name, Value, and Description for the new constant, according to the table below.
5. Click Save.
6. Repeat the above steps for each of the constants you want to add.
l
Note that if the constants are not defined in the web user interface, the scripts will use the values listed in the
Default Value column of the following table.
Constant Name
Default Value
Description
xmattersurl
http://localhost:8888
Used to specify the address of the xMatters (IT) engine web

server. The links provided in notification content use this
constant value to locate the web server which would process
the response. For these links to work, this address must be
reachable from the Device where the User will receive the
notification; normally, this is the IPaddress or fully-qualified
host name of the xMatters web server.
bespushurl
http://localhost:8888/static
Used to specify the address of the BES device server.

Populates the $main.bes_pushurl parameter.
Note:
Event Domain Constant values are case-sensitive; Boolean values must be lowercase true or false. For more
information about the parameters referenced in the Description column, see "Configuration Variable Reference" on
page 24.
4.2 Adding new parameters

Additional parameters (data elements or tokens that exist in BMC Control-M) can be added to notification content for
Devices. You do not need to modify the integration to add the parameters to injected events because the default integration
passes all of the available content into the integration agent.
The following steps explain how to add a new parameter to email notifications; adding content for other Device types is
similar and requires the presentation script to be modified for the specific Devices.
To add a new token to email notification content:
1. Open the xMatters Developer IDE and check out the BMCControl-M (BUSINESS) Script Package.
2. In the deviceContentEmail Presentation Action Script, add the following line to the email content creation section:
@messageContent::put("My New Token", $event.<new_token_name> )
The new parameter should now appear in your notification content for email Devices.
4.3 Response choices

This integration allows recipients to respond to notifications with several default choices, some of which are injected back to
the BMC Control-M server, updating the original incident. Users notified on email Devices also have the ability to respond
with an extra annotation message which will be logged in the original job, as described in "Response choices", below.
The following is a list of the default response choices available with the integration and their associated actions on the
xMatters event and the BMC Control-Mjob. Note that in the xMatters scripts, "job control" refers to the controls that affect
the lifecycles of notifications within xMatters; for a definition of the xMatters job control terms, see the list below the table.
Default response choices
Response
Description
xMatters Job Control
Ignore
Adds an annotation to the job indicating it has

been ignored by the User/Device.
Notify next, delink responder.
Kill
Terminates the Control-M job.
Delink all
Confirm
Confirms a job with status Wait User before

continuing with the job.
Delink all
Rerun
Reruns the Control-M job.
Delink all
Force OK
Change the job status to OK.
Delink all
Request Job Logs

by Email
Retrieves the job logs via email.
Mark as delivered
Request Job
Output by Email
Retrieves the job output via email.
Mark as delivered
Request Job
Statistics by Email
Retrieves the job statistics via email.
Mark as delivered
Note:
All job responses that are sent back from the Control-M command-line interface are sent via FYI messages. By
default, this integration is configured to use only email Devices for FYI notifications.This means that any requested
job logs, outputs, and statistics will be sent to your email devices. This also means that any response of Kill,
Confirm, Rerun, or Force OK will return the result of this response via FYI messages to your email devices.
xMatters job control definitions

The xMatters job controls defined in the above table are implemented as follows:
l
Delivered: marks the notification as delivered.
Notify next: notifies the next recipient in the Group according to the defined escalation in xMatters.
Delink responder: marks the notification as delivered. Stops any further action on the notification by the responder.
Delink all except responder: marks the notification as delivered, and stops any further action on the notification for all
recipients of the notification except for the responder.
Delink all: marks the notification as delivered, stops any further action on the notification for all recipients, and
terminates the event in xMatters
The job control defined for each response choice is the default configuration for this integration; for more information about
xMatters job control, and how to modify these actions in the scripts, see the xMatters Online Developer's Guide.
4.3.1 Changing and adding response choices

Changing or adding a response choice to the integration requires the following steps:
l
Add or modify the response choice on the Subscription Domain (as described in "Defining a Subscription Domain" on
page 12).
Update the xMatters script to forward the response choice to the integration agent.
Update the integration agent to send the response choice into BMC Control-M to perform the desired action on the
originating job.
As an example, the following code illustrates adding a response choice of "Be there in 10 minutes" to the integration:
To forward the response choice to the integration agent, launch the xMatters Developer IDE and open the Handler script;
make the following changes:
1. In the buildUserResponseMap script add:
@userResponseMap::put("be there in ten minutes", "be there in ten minutes")
2. In the processUserResponse script add:

IF ($actionToken == "be there in ten minutes" )
GOSUB prepareAndSendServiceMessage
CALL sendAPDeliveredResponse
To send the response choice from the integration agent into BMC Control-M, open the controlm.js file, and add a new
ELSE-IFstatement to the handleApsResponses function:
if (responseAction.equalsIgnoreCase("be there in ten minutes" ) )
{// Implement functionality to issue a new sendevent command
log.debug("About to start 'be there in ten minutes functionality');
<your code goes here>
}
The above is intended only as a brief overview of the required components. For more information about responses and
scripting, refer to the xMatters Action Scripts and the xMatters Online Developer's Guide.
4.4 Delivery Annotations

This integration annotates the integration agent logs for all delivery annotations, but this may not be desirable in all
environments. To prevent the delivery annotation of a job, change the "annotatedelivery" Event Domain Constant to false.
For more information, see "Defining Event Domain Constants" on page 19.
4.5 Altering the duration of events

You can modify the amount of time xMatters will send out notifications for a particular event before it times out by changing
the timeout Event Domain Constant. This constant stores the number of seconds the notifications will be allowed to continue
before timing out.
For example, if you wanted to change the event duration to two hours, you could change the value for the timeout constant
to 7200.
For more information about working with Event Domain Constants, see "Configuring the Event Domain" on page 18.
4.6 Terminating existing events

As mentioned in "Triggering a notification" on page 14, before an event is injected the integration checks whether an
existing xMatters event is already associated with the BMC Control-Mjob. If an event already exists, the integration
terminates the pre-existing event and injects the new event.
You may want to disable this feature to allow for possible enhancements to the integration where, under certain
circumstances, an injected event may not necessarily be related to existing events already in the system.
To disable this feature:
1. Open the controlm-config.js file and locate the following line:
var deleteExistingEvents = true;
2. Change the boolean to false, and then save and close the file.
4.7 Troubleshooting
This section identifies and addresses any known or potential issues with the integration that may be encountered during
installation, configuration, or validation.
4.7.1 Installing the BMC Control-M APIServer

The integration agent uses the BMCControl-M API,an optional component of the BMCControl-M system, to communicate
with the BMC Control-M server. If the APIis not working correctly, or is misconfigured, the integration agent log file will
report errors that contain the following messages:
Failed to establish connection with server - no server registered under this hostname.
and
Invalid component type - hostname was not assigned!!
In addition, you may encounter a stack trace with the following error:
2013-08-27 13:06:16,818 [WrapperSimpleAppMain] ERROR - exception during resolve XMLInvoker (Inval
idName) - Indi_invokerFactory.cates the name does not identify a binding
Use the following recommendations to ensure the correct installation and configuration of the BMCControl-M API:
Consult the BMC Control-M Workload Automation APIGuide (available on the BMC Control-M installation DVD) to
ensure that all installation steps are executed correctly.
Note that the path for the API installer files indicated in the current installation document is incorrect; the correct path
is Setup_files\TOOLS\emapi_files.
The current document also refers to an incorrect target installation folder for the API, emapi-700; the correct name of
the API installation folder is emapi-800.
When installing the BMCControl-M API and the Oracle JDK, avoid using paths or folder names that include spaces;
ie., use C:\emapi-800 and not C:\Program Files\emapi-800.
Ensure that you have installed Oracle JDK1.6 or higher BEFOREattempting to install the API.
Ensure that you have configured the operating system with a global "JAVA_HOME"environment variable that points
to the location of the Oracle JDK. To check whether the configuration is correct, type the following command and
confirm that the correct Java version is returned:
%JAVA_HOME%\bin\java -version
l
When configuring the API, use the server's network name (i.e., not the IPaddress), and ensure that the server name
resolves to the correct IPaddress. Note also that the hostname setting is case-sensitive, and that you may need to add an
entry to the server's hosts file.
4.8 Uninstalling
For instructions on removing an xMatters deployment, refer to the xMatters installation and administration guide.
Chapter 5: Configuration Variable Reference

This section outlines and describes the configuration variables available in the initial PROCESS Action Script.
5.1 Global configuration variables

These variables are available throughout the script package, and are parameters of the main object. The value assigned to
each variable is its default value within the script.
Note that many of the configuration variables are configurable using the Event Domain Constants described in "Defining
Event Domain Constants" on page 19. Those variables are not listed here.
Gobal variables
$main.use_logFile = false
Specify whether to use an alternate log file for debugging

messages. This variable is ignored unless $main.debug is also set to
true.
$main.logFile = "../logs/"
Defines the file used to log debugging information (only if

$main.use_logfile is set to true).
$main.HTML_form_url = $xmatters_URL &

"/jsp/ProcessNotificationResponse.jsp"
Specifies the URL of the xMatters web servers Process

Notification Response JSP form, used by HTML email and BES to
inject responses through the system.
$main.logo = $xmatters_URL &

"/static/images/logos/xmatters_email.gif"
Specifies the path to the graphic displayed on HTML (email and

BES) notifications.
$main.logo_alt_text = [If the logo does not appear

you may be blocking images or you may be outside
a firewall. If the latter, the links will not work for
responding and you should respond by replying to
this email as described below.]
The alternate text to display if the HTML email logo is

unavailable.
$main.numeric_pager_number = 555-1212
The phone number to display for calling in to retrieve event

information. This variable has a non-existent number as a default
value; a real call-in number must be supplied, or a message
indicating that an xMatters event has occurred.
Note: If the logo does not display, it is unlikely that the HTML_
form_url is valid and responses will not be injected from HTML
Devices (email and BES).
Chapter 5: Configuration Variable Reference | 24
www.xMatters.com
1 2 647 alcosta blvd., suite # 4 25 san ram on ca 945 83 usa
p : 1-87 7-xM attr s + 1. 87 7. 9 6 2 . 8 87 7
C e n t r al Co u rt 25 Southam pton Build i n g s , Lon d on WC2 A 1A L U K
p : + 44 (0 ) 80 0 6 52 7 7 1 1
Copyright 2013 xMatters. All rights reserved. All other products and brand names are trademarks or registered trademarks of their respective holders.

XM BMC Controlm v201

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

XM BMC Controlm v201

Încărcat de

Drepturi de autor:

Formate disponibile

xMatters (IT) engine

for BMC Control-M Workload Automation

Proprietary and Confidential 2013 xMatters, inc

1.1.2 Integration Architecture

1.2 System Requirements

Chapter 2: Installation and Configuration

2.1.2 Installing Control M/EMAPIserver properties files

2.1.3 Updating the user password

2.1.4 Installing voice files

2.2 Configuring BMCControl-M Workload Automation

2.2.1 Define shout destinations

2.2.2 Using shout destinations

2.3 Configuring xMatters

2.3.1 Importing Event Domain and scripts

2.3.2 Subscribing to Alerts

Chapter 3: Integration Validation

3.1 Triggering a notification

3.2 Responding to a notification

3.3 Viewing response results

Chapter 4: Optimizing and Extending the Integration

4.1 Manually configuring xMatters

4.1.1 Importing the script package

4.1.2 Configuring the Event Domain

4.2 Adding new parameters

4.3 Response choices

4.3.1 Changing and adding response choices

4.4 Delivery Annotations

4.5 Altering the duration of events

xMatters (IT) for BMCControl-MWorkload Automation

4.6 Terminating existing events

4.7.1 Installing the BMC Control-M APIServer

Chapter 5: Configuration Variable Reference

1.1.2 Integration Architecture

xMatters (IT) for BMCControl-MWorkload Automation

1.2 System Requirements

xMatters (IT) engine5.0 (patch 009 or later)

xMatters integration agent5.0 (patch 007 or later)

xMatters Developer IDE

xMatters (IT) for BMCControl-MWorkload Automation

BMCControl-M Workload Automationv8

1.2.1 Operating Systems

xMatters (IT) engine

5.0 patch 009

Linux CentOS 5.3

Microsoft Windows 2008 R2

xMatters integration agent

5.0 patch 007

Linux CentOS 5.3

Microsoft Windows 2008 R2

1.3 Conventions and Terminology

text that must be typed into the computer

directory and file names

On Windows systems, the default is C:\Program Files\xMatters

On Unix systems, the default is /opt/xmatters

xMatters (IT) for BMCControl-MWorkload Automation

On Windows systems, the default is C:\Program Files\xmatters\integrationagent.

On Unix systems, the default is /opt/xmatters/integrationagent.

xMatters (IT) for BMCControl-MWorkload Automation

Chapter 2: Installation and Configuration

2.1 Installing the integration

To install the integration service:

Chapter 2: Installation and Configuration | 5

xMatters (IT) for BMCControl-MWorkload Automation