xm bmc controlm v201

xMatters (IT) enginefor 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 ofxMatters. 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 IntegrationAgent is now the xMatters integration agent; AlarmPoint Enterprise is now xMatters enterprise; and so on. You can learn moreabout why we changed our name at www.xmatters.com. During the ongoing transition to the new naming conventions, legacycorporate and product names will still appear in some parts of our products, such as directory paths, logs, and messages. Thisdocument 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, xMattersworkgroup, xMatters enterprise, xMatters service provider, xMatters on demand, and xMatters Notification Server aretrademarks 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 theCustomer Support Site from the main web page. In this protected area, you will find current product releases, patches, releasenotes, a product knowledge base, trouble ticket submission areas and other tools provided by xMatters, inc.

xMatters, inc.Corporate Headquarters4457 Willow Road, Suite 220Pleasanton, CA 94588

Sales and Technical Support:

Telephone: 925-226-0300Facsimile: 925-226-0310

[email protected]@xmatters.comCustomer Support Site: http://community.xMatters.com

This integration was designed and tested on an unmodified version of BMCControl-M Workload Automation, and thisdocument describes how to configure xMatters to integrate with the default installation. If you have customized or altered yourinstance of BMC Control-M, this integration may need to be modified for your deployment. Please note that these integrationchanges are not part of the services offered by xMatters Technical Support, but can be performed through xMatterssProfessional Services department. For more information, contact your xMatters Sales representative.

Proprietary and Confidential 2013 xMatters, inc

iTable of Contents

Chapter 1: Introduction 11.1 Summary 1

1.1.1 Benefits 1

1.1.2 Integration Architecture 1

1.2 System Requirements 2

1.2.1 Operating Systems 3

1.3 Conventions and Terminology 3

1.3.1 Conventions 3

1.3.2 Terminology 4

Chapter 2: Installation and Configuration 52.1 Installing the integration 5

2.1.1 Installing the integration service and updating the integration agent 5

2.1.2 Installing Control M/EMAPIserver properties files 6

2.1.3 Updating the user password 7

2.1.4 Installing voice files 7

2.2 Configuring BMCControl-M Workload Automation 7

2.2.1 Define shout destinations 7

2.2.2 Using shout destinations 8

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 143.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 184.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

ii

4.6 Terminating existing events 22

4.7 Troubleshooting 22

4.7.1 Installing the BMC Control-M APIServer 22

4.8 Uninstalling 23

Chapter 5: Configuration Variable Reference 245.1 Global configuration variables 24

Chapter 1: Introduction

1

Chapter 1: IntroductionWelcome to xMatters (IT) for BMCControl-MWorkload Automation; this document describes how to install andconfigure xMatters and BMCControl-M Workload Automation software for integration. The intended audience forthis document is experienced consultants, system administrators and other technical readers.

1.1 SummaryxMatters is an interactive alerting application, designed to capture and enrich important events, to route those eventsto the right person on any communication device, and to give that person the ability to solve, escalate, or enlistothers to resolve the events remotely.

xMatters allows you to take critical business information and contact the right people via voice phone, SMS, two-way pagers, instant message, and email.

Through integration modules, xMatters can become the voice and interface of an automation engine or intelligentapplication (the Management System, such as BMCControl-M Workload Automation). When BMC Control-Mdetects something that requires attention, xMatters places phone calls, sends pages, messages, or emails to theappropriate personnel, vendors or customers.

xMatters is also persistent, escalating through multiple devices and personnel until someone accepts responsibility orresolves the problem. Once contacted, xMatters gives the notified person instant two-way communication withBMCControl-M Workload Automation. Responses are executed immediately on BMC Control-M, enabling remoteresolution of the event.

This integration supports job notifications (from BMC Control-M to xMatters) via web services. It also supportsinbound actions (from xMatters to BMC Control-M).

1.1.1 BenefitsWith 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 canbe made in real-time.

Once a response is selected on the recipients remote device, xMatters will update the BMC Control-Mjob in real-time. The benefit is that this process is immediate significantly faster than the time required for staff to notice thefailures or malfunctions, determine who is on call, and manually notify the right person. In addition, the ability totake simple actions on the event from any device gives the event resolver a quick way to deal with many issues andcommunicate to other team members the current state of the event.

During the process, every notification, response, and action is logged in xMatters. In addition, xMattersautomatically 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 personnelfor each job.

1.1.2 Integration ArchitectureThis integration integrates xMatters and BMC Control-M via Shout Destinations and the BMC Control-M API andcommand line interface.


Chapter 1: Introduction | 2

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 Controlm-APClient.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 commandline interface requests are sent back to xMatters via FYInotifications (note that these FYInotifications are configuredby 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 expectedloads. For example, the default integration features automatic status annotations to the original job that indicate each stage ofdelivery; in a high-volume production system, this can significantly affect performance. Consider your expected volume ofinjected 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 RequirementsThe following products must be installed and operating correctly prior to integration:

xMatters:

l xMatters (IT) engine5.0 (patch 009 or later)l xMatters integration agent5.0 (patch 007 or later)l xMatters Developer IDE



BMC Control-M:

l BMCControl-M Workload Automationv8l 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 SystemsThe 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

Microsoft Windows 2008 R2(validated)

Oracle 11g

SQLServer 2008(validated)

xMatters integration agent 5.0 patch 007 Linux CentOS 5.3

Microsoft Windows 2008 R2(validated)

BMCControl-M WorkloadAutomation

v8 Microsoft Windows 2008 R2(validated)

All operating systems supportedby the xMatters integration agent

(validated withMicrosoft SQLServer2008)

For more information about the supported operating systems for xMatters, refer to the xMatters installation andadministration guide and xMatters integration agent guide.

1.3 Conventions and TerminologyThis section describes how styles are used in the document, and provides a list of definitions.

1.3.1 ConventionsSome 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 computerl directory and file namesl code samples

Directory pathsExcept where explicitly stated, the directory paths in this document are listed in Windows format. Unix users must substitutethe given paths with the Unix equivalents.

The xMatters installation folder is referred to throughout the documentation as .

l On Windows systems, the default is C:\Program Files\xMattersl On Unix systems, the default is /opt/xmatters



The xMatters integration agent installation folder is referred to throughout the documentation as .

l On Windows systems, the default is C:\Program Files\xmatters\integrationagent.l On Unix systems, the default is /opt/xmatters/integrationagent.

1.3.2 TerminologyThe following terms are used through the xMatters documentation.

Term Meaning

Event An event refers to any situation or item of interest detected by the management system, and whichrequires attention. Event is also used to refer to the incident or situation as it progresses through thexMatters system, from injection to notification to resolution. Each event must generate at least onealert or notification.

Event can also be a generic term used to refer to an incident, change request, message, or otherspecific item within the management system. Whenever possible, these situations are referred tousing 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, andwith 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 xMatterssystem is defined by a set of User details, including IDnumber, user name, login password, and soon.

Group Groups are used to collect and organize Users and Devices into notification schedules. For acomplete explanation of Groups in xMatters, see the xMatters user guide.

Documentation terminology


Chapter 2: Installation and Configuration | 5

Chapter 2: Installation and ConfigurationThis 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 integrationcomponents.

2.1 Installing the integrationThis 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 agentTo configure the integration agent for the BMC Control-M integration, you must copy the integration components into theintegration 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 identicalto the existing integration agent installation, so copying the folder's contents automatically installs the required files to theirappropriate locations. Copying these files will not overwrite any existing integrations.

This integration includes the following components:

Component Description

bin/Controlm-APClient.bat

bin/Controlm-APClient-Del.bat

Batch files targeted by the SHOUT destinations from within Control-M. They take theSHOUT message and call APClient.bin.exe with the correct map-data for eitherthe controlm20 service or the del service, depending on which SHOUTdestination was used.

conf/deduplicator-filter.xml The filtering mechanism used to suppress duplicate messages. By default, the filterchecks the job_name, status and run_num values; if they are all the same within a twominute window, only the first message will be sent through to xMatters.

controlm-config.js The main configuration file for the integration; includes API connection informationand user information.

bmccontrolm.pwd Stores the password for the Control-M APIuser used by the integration service. If youchange the name of this file, you must also update the controlm-config.js files to pointto 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 tosuit your deployment configuration.

Note: If you have more than one integration agent providing the BMC Control-M service, repeat the following steps foreach one.

To install the integration service:

1. Copy all of the contents of the \components\integration-agent\ folder from the extracted integration archive tothe folder.

2. Open the IAConfig.xml file found in \conf and add the following line to the service-configs section:controlm20/controlm.xml

3. Open the controlm-config.js file (now located in \integrationservices\controlm20\ folder, and setthe values for the following variables:



Variable Description

CONTROL_M_USER The user name to be used for the BMC Control-M API Server; defaultvalue 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 aSHOUTMessage and making the callback to the BMCControl-MAPIfor the job details. (Default is 3000, or three seconds.)

DEDUPLICATOR_FILTER Name of the deduplicator filter; i.e., the attribute name for the elementfilter in the deduplicator-filter.xml file. The default value iscontrolm20.

4. Save and close the file.5. Open the Controlm-APClient.bat and Controlm-APClient-Del.bat files (now located in \bin) in a text

editor, and change the value for the "IAHOME"variable to the location of the \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 filesWhen you install the Control-M/EMAPIserver, it creates two properties files within its installationfolder:ctmemapi.properties and jacorb.properties. Both of these files are required by the integration to access andcommunicate 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 tothe \integrationservices\controlm20 folder.

l Update the CTMEMAPI_PROPERTIES_FILE and JACORB_PROPERTIES_FILE parameters in the controlm-config.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 passwordThe 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 thedatabase 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 thexMatters integration agent guide.

To change the encrypted password:

1. Navigate to the /bin subfolder, and then run the following command, replacing with thepassword of the BMC Control-M user:

./iapassword.sh --new "" --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 theexisting password.

2.1.4 Installing voice filesThese files must be installed into any xMatters deployment running a voice Device Engine. For more information, refer to thexMatters 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:\node\phone-engine\Datastore\\

For example, if you were installing the integration for the Default Company on an out-of-the-box deployment, the installationpaths for the voice files would be as follows:\node\phone-engine\Datastore\1\controlm20\recordings\english\phrases

Note that if this is the first custom Event Domain you have created, the directory will not have beencreated yet. You can create it manually or log into xMatters and use the web user interface to add a new voice recording. Ifthe 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 AutomationThe following sections describe how to configure BMC Control-M to combine with xMatters.

2.2.1 Define shout destinationsThe first step in configuring BMC Control-M is to specify the destinations for the xMatters and xMattersDel shoutdestinations.



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: xMattersl Address: Serverl Destination: Programl 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: xMattersDell Address: Serverl Destination: Programl 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 destinationsOnce .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 jobwhen the notification is sent. The xMattersDel shout (Controlm-APClient-Del.bat) is used to clean up outstandingnotifications; 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 theshout 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;,;

Note that you must use semi-colons (;)to separate the components in the message field, and commas (,)to separate thexMatters 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 theshout 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 %%ORDERID7. Click OKto save the action.

2.3 Configuring xMattersConfiguring xMatters to combine with BMCControl-M Workload Automation requires the following steps:

l Import the Event Domain packagel Configure the Event Domain, including Integration Service and Event Domain Constants

2.3.1 Importing Event Domain and scriptsThe integration package includes an XMLfile that was created using the xMatters "Export Integration" feature; this greatlysimplifies the xMatters configuration process by enabling you to create the integration Event Domain, configure thepredicates 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 serviceFor the installation to be successful, the integration service name must match the name specified in the controlm-config.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: controlm20l Description: BMC Control-M Integration Service

Specifying connection parametersOnce you have imported the Event Domain package and configured the Integration Service, you must specify an xMattersaddress 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):



Constant Name Default Value Description

XMATTERSURL http://localhost:8888 Used to specify the address of the xMatters web server. The linksprovided in notification content use the xmattersurl constant valueto locate the xMatters web server which would process the response.For these links to work, this address must be reachable from theDevice where the User will receive the notification; normally, this isthe IPaddress or fully-qualified host name of the xMatters webserver.

BESPUSHURL http://localhost:8888/static Used to specify the address of the BES device server.

Event Domain Constants

Note: For more information about the Event Domain Constants included in the integration and how to configure them tosuit your deployment, see "Defining Event Domain Constants" on page 19.

2.3.2 Subscribing to AlertsThe 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 astatus of "Ended not OK".

To allow Users to subscribe to specific criteria on injected events, you must configure the Subscription using the followingsteps:

n Update the Event Domain predicatesn Define a Subscription Domainn Create a Subscriptionn Create a Fail-Safe Group

Updating Event Domain predicatesThe Event Domain predicates are created as part of importing the Event Domain. You can add more predicates or removeexisting 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 controlm20-job-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:

Predicate Type Important Description

job_name Text Yes Name of the job for which notifications are being sent.

controlm_server Text Yes

Event Domain predicates



Predicate Type Important Description

order_id Text Yes

message Text

task_type Text

application Text

job_status Text The status of the job in BMC Control-M; default values are:

l Ended OKl Ended not OKl Executingl Wait Conditionl Wait Resourcel Wait Userl Not in AJFl Unknown

Note: For more information about predicates and how they work in xMatters, see the xMatters installation andadministration guide.

Defining a Subscription DomainThe Subscription Domain is the reference point of the Subscription panel and allows you to control who can createSubscriptions, how recipients can respond to Subscription notifications, and which Event Domain predicates can be used tocreate 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.3. In the Event Domain drop-down list, select controlm20, and then click Continue.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 Rerunl Force OKl Confirml Killl Request Job Logs By Emaill Request Job Output By Emaill Request Job Statistics By Email

8. On the Select Appropriate Predicates page, add all of the predicates to the Applied Predicates list, and then clickContinue.

9. On the Select Roles page, specify the Roles you want to be able to create Subscriptions on the Domain, and then clickSave.



Note: For more information about working with Event and Subscription Domains, see the xMatters installation andadministration guide.

Creating a SubscriptionOnce you have created a Subscription Domain, you can create and assign Subscriptions to notify recipients about jobs thatmatch 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 GroupIf an event is submitted to xMatters when the fail-safe functionality is enabled, and there is no Device or User that matchesthe event, xMatters sends the notification to the fail-safe recipient. The fail-safe recipient is typically a Group, but can beconfigured 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 EventDomain Constant, as explained in "Configuring the Event Domain" on page 18.

Chapter 3: Integration Validation

14

Chapter 3: Integration ValidationThe following sections will test the combination of xMatters and BMC Control-M for notification delivery andresponse.

After configuring xMatters and BMC Control-M, you can validate that communication is properly configured. It isrecommended that you start the components in the following order:

l BMC Control-Ml xMatters integration agentl xMatters

3.1 Triggering a notificationTo trigger a notification, run a new job in BMC Control-M, and cause it to enter astate for which you have definedan xMatters Shout Message:

3.2 Responding to a notificationThis section describes how to respond to a notification from xMatters. In the following example, the notification isreceived 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:


15

2. The list of possible replies is located at the bottom of the notification. For email notifications, click one of theresponse 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 aboutthe job from BMC Control-M.

Chapter 3: Integration Validation

16

Job logs:

Job output:


17

Job Statistics:

3.3 Viewing response resultsTo view the results of the response, view the job report details in BMC Control-M. In the following image, you cansee that the notified user selected the "Rerun"response option, causing the job to be rerun:


Chapter 4: Optimizing and Extending the Integration | 18

Chapter 4: Optimizing and Extending the IntegrationThis section describes some of the available methods you can use to optimize or extend the xMatters (IT) for BMCControl-MWorkload Automation integration.

4.1 Manually configuring xMattersThis integration includes an exported version of the xMatters script package and Event Domain, including Event Domainconstants and predicates. If you do not want to use the included XMLfile to create and configure the required Event Domainand Action Scripts, the following sections describe how to manually configure these components.

4.1.1 Importing the script packageThis integration includes a script package specific to BMC Control-M. To install the script package, you need to import itinto 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 OnlineDeveloper'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 DomainBy default this integration is set up to use an Event Domain of controlm20; it is strongly recommended that you use thisdefault 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.4. Enter the following information into the form:

l Name: controlm20l Description: BMCControl-Ml Script Package: BMCControl-M Integration

5. Click Save.



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

Defining an Integration ServiceFor the installation to be successful, the integration service name must match the service specified in the controlm.xml fileinstalled 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: controlm20l Description: BMC Control-M Integration Service

4. Click Save.

Defining Event Domain ConstantsCompany Administrators and Developers can create Event Domain Constants that will be available in scripting for all eventobjects associated with an Event Domain. This integration uses Event Domain Constants to define custom values for theintegration script package.

The integration script package uses the names of the constants defined in the table below to look up the values; it is stronglyrecommended that you use the names specified. Note that the values for the webserverurl and bespushurl constants shouldbe modified to specify the address of the xMatters web server (to enable the HTML response options) and the BES deviceserver.

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 DomainConstants.

2. In the Event Domain drop-down list, select controlm20, and then click Continue.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 theDefault 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 webserver. The links provided in notification content use thisconstant value to locate the web server which would processthe response. For these links to work, this address must bereachable from the Device where the User will receive thenotification; normally, this is the IPaddress or fully-qualifiedhost 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 moreinformation about the parameters referenced in the Description column, see "Configuration Variable Reference" onpage 24.

4.2 Adding new parametersAdditional parameters (data elements or tokens that exist in BMC Control-M) can be added to notification content forDevices. You do not need to modify the integration to add the parameters to injected events because the default integrationpasses 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 issimilar 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. )

The new parameter should now appear in your notification content for email Devices.

4.3 Response choicesThis integration allows recipients to respond to notifications with several default choices, some of which are injected back tothe BMC Control-M server, updating the original incident. Users notified on email Devices also have the ability to respondwith 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 thexMatters event and the BMC Control-Mjob. Note that in the xMatters scripts, "job control" refers to the controls that affectthe lifecycles of notifications within xMatters; for a definition of the xMatters job control terms, see the list below the table.

Response Description xMatters Job Control

Ignore Adds an annotation to the job indicating it hasbeen 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 beforecontinuing 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 Logsby Email

Retrieves the job logs via email. Mark as delivered

Request JobOutput by Email

Retrieves the job output via email. Mark as delivered

Request JobStatistics by Email

Retrieves the job statistics via email. Mark as delivered

Default response choices



Note: All job responses that are sent back from the Control-M command-line interface are sent via FYI messages. Bydefault, this integration is configured to use only email Devices for FYI notifications.This means that any requestedjob 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 definitionsThe xMatters job controls defined in the above table are implemented as follows:

l Delivered: marks the notification as delivered.l Notify next: notifies the next recipient in the Group according to the defined escalation in xMatters.l Delink responder: marks the notification as delivered. Stops any further action on the notification by the responder.l 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.l 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 aboutxMatters 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 choicesChanging 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" onpage 12).

l Update the xMatters script to forward the response choice to the integration agent.l 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 newELSE-IFstatement to the handleApsResponses function:if (responseAction.equalsIgnoreCase("be there in ten minutes" ) ){// Implement functionality to issue a new sendevent commandlog.debug("About to start 'be there in ten minutes functionality');

}

The above is intended only as a brief overview of the required components. For more information about responses andscripting, refer to the xMatters Action Scripts and the xMatters Online Developer's Guide.



4.4 Delivery AnnotationsThis integration annotates the integration agent logs for all delivery annotations, but this may not be desirable in allenvironments. 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 eventsYou can modify the amount of time xMatters will send out notifications for a particular event before it times out by changingthe timeout Event Domain Constant. This constant stores the number of seconds the notifications will be allowed to continuebefore timing out.

For example, if you wanted to change the event duration to two hours, you could change the value for the timeout constantto 7200.

For more information about working with Event Domain Constants, see "Configuring the Event Domain" on page 18.

4.6 Terminating existing eventsAs mentioned in "Triggering a notification" on page 14, before an event is injected the integration checks whether anexisting xMatters event is already associated with the BMC Control-Mjob. If an event already exists, the integrationterminates 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 certaincircumstances, 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 TroubleshootingThis section identifies and addresses any known or potential issues with the integration that may be encountered duringinstallation, configuration, or validation.

4.7.1 Installing the BMC Control-M APIServerThe integration agent uses the BMCControl-M API,an optional component of the BMCControl-M system, to communicatewith the BMC Control-M server. If the APIis not working correctly, or is misconfigured, the integration agent log file willreport errors that contain the following messages:Failed to establish connection with server - no server registered under this hostname.

andInvalid 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 (InvalidName) - 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:



l Consult the BMC Control-M Workload Automation APIGuide (available on the BMC Control-M installation DVD) toensure that all installation steps are executed correctly.

l Note that the path for the API installer files indicated in the current installation document is incorrect; the correct pathis Setup_files\TOOLS\emapi_files.

l The current document also refers to an incorrect target installation folder for the API, emapi-700; the correct name ofthe API installation folder is emapi-800.

l 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.

l Ensure that you have installed Oracle JDK1.6 or higher BEFOREattempting to install the API.l 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 andconfirm 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 nameresolves to the correct IPaddress. Note also that the hostname setting is case-sensitive, and that you may need to add anentry to the server's hosts file.

4.8 UninstallingFor instructions on removing an xMatters deployment, refer to the xMatters installation and administration guide.


Chapter 5: Configuration Variable Reference | 24

Chapter 5: Configuration Variable ReferenceThis section outlines and describes the configuration variables available in the initial PROCESS Action Script.

5.1 Global configuration variablesThese variables are available throughout the script package, and are parameters of the main object. The value assigned toeach variable is its default value within the script.

Note that many of the configuration variables are configurable using the Event Domain Constants described in "DefiningEvent Domain Constants" on page 19. Those variables are not listed here.

$main.use_logFile = false Specify whether to use an alternate log file for debuggingmessages. This variable is ignored unless $main.debug is also set totrue.

$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 ProcessNotification Response JSP form, used by HTML email and BES toinject responses through the system.

$main.logo = $xmatters_URL &"/static/images/logos/xmatters_email.gif"

Specifies the path to the graphic displayed on HTML (email andBES) notifications.

$main.logo_alt_text = [If the logo does not appearyou may be blocking images or you may be outsidea firewall. If the latter, the links will not work forresponding and you should respond by replying tothis email as described below.]

The alternate text to display if the HTML email logo isunavailable.

Note: If the logo does not display, it is unlikely that the HTML_form_url is valid and responses will not be injected from HTMLDevices (email and BES).

$main.numeric_pager_number = 555-1212 The phone number to display for calling in to retrieve eventinformation. This variable has a non-existent number as a defaultvalue; a real call-in number must be supplied, or a messageindicating that an xMatters event has occurred.

Gobal variables

Copyright 2013 xMatters. All rights reserved. All other products and brand names are trademarks or registered trademarks of their respective holders.

12647 AlCostA blvd., suite #425 sAn rAMon CA 94583 usA | p: 1-877-xMattrs + 1 .877.962.8877

CentrAl Court 25 southAMpton buildings, london WC2A 1Al uK | p: +44 (0) 800 652 7711

www.xMatters.com

xMatters (IT) for BMC Control-M Workload AutomationChapter 1: Introduction1.1 Summary1.1.1 Benefits1.1.2 Integration Architecture

1.2 System Requirements1.2.1 Operating Systems

1.3 Conventions and Terminology1.3.1 Conventions1.3.2 Terminology

Chapter 2: Installation and Configuration2.1 Installing the integration2.1.1 Installing the integration service and updating the integration agent2.1.2 Installing Control M/EM API server properties files2.1.3 Updating the user password2.1.4 Installing voice files

2.2 Configuring BMC Control-M Workload Automation2.2.1 Define shout destinations2.2.2 Using shout destinations

2.3 Configuring xMatters2.3.1 Importing Event Domain and scripts2.3.2 Subscribing to Alerts

Chapter 3: Integration Validation3.1 Triggering a notification3.2 Responding to a notification3.3 Viewing response results

Chapter 4: Optimizing and Extending the Integration4.1 Manually configuring xMatters4.1.1 Importing the script package4.1.2 Configuring the Event Domain

4.2 Adding new parameters4.3 Response choices4.3.1 Changing and adding response choices

4.4 Delivery Annotations4.5 Altering the duration of events4.6 Terminating existing events4.7 Troubleshooting4.7.1 Installing the BMC Control-M API Server

4.8 Uninstalling

Chapter 5: Configuration Variable Reference5.1 Global configuration variables

xm bmc controlm v201

Documents