xmatters (IT) engine FOR CA WORKLOAD AUTOMATION AE (FORMERLY CA AUTOSYS)

xmatters (IT) engine FOR CA WORKLOAD AUTOMATION AE (FORMERLY CA AUTOSYS)

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. Friday, January 30, 2015 Copyright 1994-2014. 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. Corporate Headquarters 12647 Alcosta Blvd, Suite 425 San Ramon, CA 94583 Telephone: 925.226.0300 Facsimile: 925-226-0310 Client Assistance: International: +1 925.226.0300 and press 2 US/CAN Toll Free: +1 877.XMATTRS (962.8877) EMEA: +44 (0) 20 3427 6333 Australia/APJ Support: +61-2-8038-5048 opt 2 Customer Support Site: http://support.xmatters.com This integration was designed and tested on an unmodified version of CA Workload Automation AE, and this document describes how to configure xmatters to integrate with the default installation. If you have customized or altered your instance of CA Workload Automation, 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 the xmatters Professional Services department. For more information, contact your xmatters Sales representative. Proprietary and Confidential 2014 xmatters, inc

Table of Contents Chapter 1: Introduction 1 1.1 Summary 1 1.1.1 Benefits 1 1.1.2 xmatters mobile access 1 1.1.3 Integration Architecture 2 1.2 System Requirements 2 1.3 Conventions and Terminology 2 1.3.1 Conventions 2 1.3.2 Terminology 3 Chapter 2: Installation and Configuration 4 2.1 Installing the integration 4 2.1.1 Creating database table and trigger 4 2.1.2 Installing the integration service and updating the integration agent 5 2.1.3 Updating password files 7 2.1.4 Configuring the Job Status Filter 8 2.1.5 Terminating notifications 8 2.1.6 Installing voice files 9 2.1.7 Installing the mobile access component files 9 2.2 Configuring the integration agent 9 2.3 Configuring xmatters 10 2.3.1 Importing event domain and scripts 10 2.3.2 Subscribing to alerts 12 Chapter 3: Integration Validation 15 3.1 Triggering a notification 15 3.2 Responding to a notification 15 3.3 Viewing response results 16 3.4 Viewing jobs 17 Chapter 4: Optimizing and Extending the Integration 22 4.1 Manually configuring xmatters 22 4.1.1 Importing event domain and scripts 22 4.1.2 Configuring the Event Domain 22 4.2 Adding new parameters 24 4.2.1 Adding new tokens to notification content 24 4.3 Response choices 25 i

4.3.1 Adding annotation messages 26 4.3.2 Changing and adding response choices 26 4.4 Delivery annotations 27 4.5 Altering the duration of events 27 4.6 Filtering and suppression 27 4.7 Optimizing the xmatters mobile access integration 27 4.7.1 Add a custom query to the home page 28 4.7.2 Creating a URL alias 28 4.8 Troubleshooting 28 4.8.1 Windows configuration issues 28 4.9 Uninstalling 29 ii

Chapter 1: Introduction Chapter 1: Introduction Welcome to xmatters (IT) for CA Workload Automation AE; this document describes how to install and configure xmatters and CA Workload Automation AE 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 CA Workload Automation AE). When CA Workload Automation 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 CA Workload Automation AE. Responses are executed immediately on CA Workload Automation, enabling remote resolution of the event. This integration supports job notifications (from CA Workload Automation to xmatters) via web services. It also supports inbound actions (from xmatters to CA Workload Automation). 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 recipient s remote device, xmatters will update the CA Workload Automation job in real-time. 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 CA Workload Automation job 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 xmatters mobile access This version of xmatters also includes the xmatters mobile access application. With the mobile access component, the appropriate technician can create, view, and update CA Workload Automation messages directly via a mobile device s web browser. Information about CA Workload Automation events can be displayed on the mobile device and updated in real-time. The benefit is that this process is immediate and may be done remotely providing users with an efficient method of handling CA Workload Automation jobs from any mobile device. In addition, the CA Workload Automation 1

integration can be updated to notify xmatters users on their mobile device with a link to the mobile view of the event, allowing the user to update the event remotely. 1.1.3 Integration Architecture This integration integrates xmatters and CA Workload Automation via the creation of a custom table and trigger in the CA Workload Automation database. CA Workload Automation job status change events are inserted into the custom table. The xmatters integration agent periodically polls this table for status change events, and processes them. Configuration controls which job status event are injected into xmatters, which will send out subscription based notifications. When a response from an xmatters notification is received, the integration agent sends the corresponding event to CA Workload Automation using the Autosys Java SDK. 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 CA Workload Automation. 1.2 System Requirements The following component versions are supported by this integration. Integration Component xmatters (IT) engine xmatters integration agent CA Workload Automation AE Version 5.1 (patch 003 or later) 5.1 (patch 003 or later) r11.3.5 For more information about the supported operating systems for xmatters components, 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: 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. Chapter 1: Introduction 2

The xmatters installation folder is referred to throughout the documentation as <xmhome>. On Windows systems, the default location is C:\Program Files\xMatters On Unix systems, the default location is /opt/xmatters The xmatters integration agent installation folder is referred to throughout the documentation as <IAHOME>. On Windows systems, the default location is C:\Program Files\xmatters\integrationagent On Unix systems, the default location is /opt/xmatters/integrationagent 1.3.2 Terminology The following terms are used through the xmatters documentation. Documentation terminology Term Event Management system Device User Group Meaning 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. 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 CA Workload Automation. The medium through which a recipient is contacted by xmatters; i.e., email, pager, phone, SMS, etc. 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 ID number, user name, login password, and so on. 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 1: Introduction 3

Chapter 2: Installation and Configuration This chapter provides information about installing the xmatters (IT) for CA Workload Automation AE integration. This chapter also contains complete instructions on how to configure xmatters, CA Workload Automation, and the integration components. 2.1 Installing the integration This section describes the installation process for the xmatters (IT) for CA Workload Automation AE integration. 2.1.1 Creating database table and trigger This integration requires that you create a custom table and trigger in the CA Workload Automation database. Note that the default database on which the trigger and table are created varies with the database product you are using: Database Oracle SQL Server Default Schema Name AEDBADMIN AEDB In the following sections, the name of the schema is represented as <SCHEMA>. If the schema is different from the default, you must also edit <IAHOME>\integrationservices\cawaae-1-2-1\cawaae-job-sql-server.js or <IAHOME>\integrationservices\cawaae-1-2-1\cawaae-job-oracle.js, depending on the database product you are using. Note that this file contains SQL statements where the object names are fully qualified; i.e., they specify the default values. Replace the defaults with the values appropriate for your deployment. Oracle To perform this step, you will need to have the credentials for a database user with administrative access to the schema. Extract the components\workload-automation-ae\oracle\create_db_objects_xmatters.sql file from the integration archive, and copy it to a location where you can run it against the target database. Using SQL*Plus, execute the following command: SQL> @create_db_objects_xmatters.sql The script will create a new trigger, named <SCHEMA>.JOB_STATUS_XMATT_TRIG_INS_UP, on the <SCHEMA>.UJO_ JOB_STATUS table a new table named <SCHEMA>.UJO_JOB_STATUS_XMATTERS, and a new sequence named <SCHEMA>.JOB_STATUS_XMATTERS_SEQ. SQL Server 2008 Extract the components\workload-automation-ae\sqlserver\create_sqlserver_db_objects_xmatters.sql file from the integration archive, and copy it to a location where you can run it against the target database. The script must be run by the SQL Server Administrator (default is "sa"), and can be run from the command line or in the SQL Server user interface. Installing the SQL script requires the following syntax: osql -U<user> -P<password> -S<serverName> -d<database> < create_sqlserver_db_objects_xmatters.sql For example, if you are using the "sa" account on the "cawaae" server's "AEDB" database, the command line would be as follows: osql -Usa -Psapassword -Scawaae -daedb < create_sqlserver_db_objects_xmatters.sql Chapter 2: Installation and Configuration 4

This command adds the <SCHEMA>.dbo.ujo_job_status_xmatters table and <SCHEMA>.job_status_xmatt_trig_ins_up trigger, and grants SELECT, INSERT, UPDATE, and DELETE permissions to the ujoadmin role. 2.1.2 Installing the integration service and updating the integration agent To configure the integration agent for the CA Workload Automation 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 bin/start_console_cawaae.sh bin/start_daemon_cawaae.sh Description These files wrap the out-of-box integration agent scripts, start_console.sh and start_daemon.sh. These new scripts try to source the CA Workload Automation environment variables before starting the integration agent. These scripts need to be updated with the deployment-specific location of the CA Workload Automation script. By default, the scripts contain the following lines which assume the default location and naming convention: machine=`uname -n` file=/opt/ca/workloadautomationae/autouser.ace/autosys.sh.$machine Check with your CA Workload Automation AE admin to determine whether this location and name matches your deployment. conf/cawaae_db.pwd conf/wrapper.conf The password of the CA Workload Automation AE database user, encrypted using the integration agent IAPassword utility; the default value in the file is "password". Replaces the default wrapper.conf installed by the integration agent. By default, this file identifies the CA Workload Automation installation folder as: set.autosys=c:\progra~1\ca\worklo~1\autosys If your deployment uses a different installation folder, edit the file in a text editor to identify the correct location. Note: The wrapper.conf file may be overwritten during the installation process whenever you upgrade your xmatters integration agent. Ensure that you follow the recommendation in the xmatters integration agent guide to create a back up of the entire integration agent installation folder before applying a patch. You can then compare your backup with the latest version to ensure that your customizations and integration settings are preserved. conf/deduplicator-filter.xml configuration.js 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. You can customize these settings by adding or removing predicates in the filter, changing the suppression period or the number of messages that are compared by the IA. For more information about this feature, see "Filtering and suppression" on page 27. The main configuration file for the integration; includes database connection information, notification filters, and user information. Chapter 2: Installation and Configuration 5

Once you have installed the files and folders, you will need to modify the configuration.js and IAConfig.xml files to suit your deployment configuration. Note: If you have more than one integration agent providing the CA Workload Automation 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>cawaae-1-2-1/cawaae.xml</path> 3. Open the configuration.js file (now located in <IAHOME>\integrationservices\cawaae-1-2-1\ folder, and set the values for the following variables: Variable CAWAAE_SERVER_NODE_NAME CAWAAE_SERVER_PORT CAWAAE_SERVER_ENCRYPTION_TYPE CAWAAE_API_USER CAWAAE_API_PASSWORD_FILE DB_USER DB_PASSWORD_FILE DB_CONNECTION_URL DB_MIN_CONNECTIONS DB_MAX_CONNECTIONS DB_TYPE Description The name of the CA Workload Automation Application Server Host. For CA Workload Automation version 11.3 and higher, this name should match the CA Workload Automation machine name definition for the agent on the application server machine. You can verify the machine name using the "autorep" command; e.g., autorep -M ALL The port on the CA Workload Automation server. Encryption Type in use by CA Workload Automation server (AsConstant value from Autosys SDK) The ID of the user that will be interacting with CA Workload Automation (default is autosys). The location of the file containing the password for the CAWAAE_API_ USER (default is conf/cawaae_api.pwd). For instructions on changing the password, see "Updating password files" on page 7. The user name of the CA Workload Automation database user. The location of the encrypted password file for the CA Workload Automation database user; the default is conf\cawaae_db.pwd. For instructions on changing the password, see "Updating password files" on page 7. The URL at which the user can access the CA Workload Automation database. Minimum number of database connections in use by the integration's database connection pool; default is 5. Maximum number of database connections in use by the integration's database connection pool; default is 10. Database type. Supported values are ORACLE and SQL-SERVER. Chapter 2: Installation and Configuration 6

Variable POLLING_INTERVAL_MS DEDUPLICATOR_FILTER DELETE_EXISTING_EVENTS Description How often, in milliseconds, the integration should poll the custom xmatters table in the CA Workload Automation database; default is 5. Name of the deduplicator filter; i.e., the attribute name for the element filter in the deduplicator-filter.xml file. The default is cawaae. Sends a "delete" prior to creating the new event, which will clear any existing events for the incident ID. 4. Set any additional filter values within the "FILTER" variable. For more information about this option, see "Configuring the Job Status Filter" on page 8. 5. Set any additional filter values with END_NOTIFY_STATUSES variable. For more information about this option, see "Terminating notifications" on page 8. 6. Save and close the file. 7. Restart the integration agent. On Windows, the integration agent runs as a Windows Service; on Unix, it runs as a Unix daemon. Note: The integration agent must be started by a CA Workload Automation sourced user; i.e., one who has loaded the CA Workload Automation environment variables required to run the SDK. For information on how to do this, consult your CA Workload Automation AE documentation. 2.1.3 Updating password files The passwords for the CA Workload Automation database user and the API user are stored in encrypted password files, located in the <IAHOME>\conf subfolder. The location of the password files, and the relevant user IDs, is specified in the configuration.js file, as described in the table above. For the integration to connect to the database, you will have to replace the default value ("password") specified in the conf\cawaae_db.pwd file with the password of the database user specified by the DB_USER parameter. For the integration to interact with the CA Workload Automation API, you must replace the default value specified in the conf\cawaae_api.pwd file with the password of the API user specified by the CAWAAE_API_USER parameter. For more information about the integration agent's IAPassword utility used to encrypt the password, see the xmatters integration agent guide. To change an encrypted password: 1. To change the password of the database user, navigate to the <IAHOME>\bin subfolder, and then run the following command, replacing <newpassword> with the password of the database user: iapassword.bat --new "<newpassword>" --old password --file conf\cawaae_db.pwd 2. To change the password of the API user, navigate to the <IAHOME>\bin subfolder, and then run the following command, replacing <newpassword> with the password of the API user: iapassword.bat --new "<newpassword>" --old password --file conf\cawaae_api.pwd If you want to change these passwords again, you will have to replace "password" in the above commands with the existing password. Note: The above instructions are for Windows deployments. The process is the same for Unix systems, but you must replace the.bat extension with the.sh extension of the Unix script, and use Unix path conventions. Chapter 2: Installation and Configuration 7

2.1.4 Configuring the Job Status Filter The "jobfilter" section within the configuration.js file identifies when the integration should inject an event into xmatters, based on the status of the jobs within CA Workload Automation. For example, the default integration configuration will inject an event from any job with a status of FAILURE or TERMINATED. The following is the default jobfilter section from the configuration.js file installed with the integration: <jobfilter> <statuses> <status>failure</status> <status>terminated</status> </statuses> <run_machines> <!-- <run_machine>machine_name</run_machine> --> </run_machines> <job_types> <!-- <job_type>fw</job_type> --> </job_types> <job_names> <!-- <job_name>name_of_job</job_name> --> </job_names> <box_names> <!-- <box_name>name_of_box</box_name> --> </box_names> <owners> <!-- <owner>owner</owner> --> </owners> <groups> <!-- <group>group</group> --> </groups> </jobfilter>; To further refine the injection of events, you could add elements for run_machine, job_type, job_name, box_name, owner and group. Examples of the syntax for each of these elements are provided in the comment lines. Each element value can also be further refined and filtered after this configuration step using the Subscription page within the xmatters web user interface. The Subscription page also provides subscribers with the ability to use regex to match against job attribute values. For more information, see "Subscribing to alerts" on page 12. 2.1.5 Terminating notifications You can configure the integration to terminate existing xmatters notifications based on the job status. This is controlled by the "end_notify_statuses" section of the configuration.js file: <end_notify_statuses> <status>on_ice</status> <status>on_hold</status> </end_notify_statuses>; By default, the integration is configured to terminate existing notifications when the job state changes to "ON_ICE" or "ON_ HOLD". For example, consider the following use case: An open job fails, and the state changes to "FAILURE". When this happens, the filter is configured to inject an event into xmatters, which sends out notifications relating to that job. Before any recipients respond, an administrator uses the CA Workload Automation web console to put the job into an "ON_ICE" state. Because the job changed states, from "FAILURE" to "ON_ICE", the existing xmatters notifications should cease. Any existing notifications will be terminated, preventing users from submitting further responses to the event. Chapter 2: Installation and Configuration 8

2.1.6 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. 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\cawaae-1-2-1\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.1.7 Installing the mobile access component files To enable the mobile access component, you must copy the folders containing the installation files into the xmatters mobile access folder on the xmatters web server. If you have more than one web server, copy the folders into the indicated folder on each web server. Note that these steps also install the latest images, styles, and resources for the mobile access component. To install the mobile access component files: 1. Copy the contents of the \components\xmatters\mobilegateway folder from the extracted integration archive to the <xmhome>\webserver\webapps\mobilegateway folder on the xmatters server. Note that this change will overwrite several files and directories on the xmatters server; if you have made any changes to these files, ensure that you create backups before overwriting your existing files. 2. Restart the xmatters web server. 2.2 Configuring the integration agent This integration requires that you configure the CA Workload Automation user to have the permissions required to run the integration agent service. The integration agent must be run by a CA Workload Automation user with the proper permissions to modify jobs. This will allow the user to run the integration agent, and allow the integration agent to modify jobs in CA Workload Automation. Unix This user will need to update the folder permissions for the integration agent; for example: chown R <USER>:<GROUP> /opt/alarmpointsystems/integrationagent chmod 755 -R /opt/alarmpointsystems/integrationagent Chapter 2: Installation and Configuration 9

where <USER> is an appropriate CA Workload Automation user and <GROUP> the CA Workload Automation group to which the user belongs. Windows If the integration agent installer does not create the Windows Service, you may need to create the service manually. To do this, run the <IAHOME>\bin\install_service.bat file. The created service defaults to run as the local System account. For this integration to function, the service must be updated to run as the CA Workload Automation user; generally, this user is called "autosys". To update the service definition, rightclick the "AlarmPoint Integration Service" in the Windows Services list, and then select Properties. Click the Log On tab, and then change the Log on as section to use the This account option, and then specify the CA Workload Automation user name and password. Click OK to apply the changes, and then restart the service. Note that the Windows Administrator account may need to update the Windows folder permissions for the integration agent to allow the CA Workload Automation user the ability to execute files within the <IAHOME> directory. 2.3 Configuring xmatters Configuring xmatters to combine with CA Workload Automation AE requires the following steps: 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 XML file 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-ca-workload-automation.xml file extracted from the integration archive. 4. Click Open, and then click Upload. xmatters imports the integration configuration settings and displays the new cawaae-1-2-1 event domain. Defining the integration service The mobile access component for this integration uses a default integration service of cawaae-1-2-1 ; it is strongly recommended that you use this default integration service. For the installation to be successful, the integration service name must match the name specified in the configuration.js file and the cawaae.xml file installed on the integration agent. To define an integration service: 1. In xmatters, on the Event Domains page, click the cawaae-1-2-1 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: Name: cawaae-1-2-1 Description: CA Workload Automation Integration Service Path: cawaae-1-2-1/menu.jsp Chapter 2: Installation and Configuration 10

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. Note: A known issue in xmatters version 5.0 requires that all event domain constants be defined in UPPERCASE. 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 cawaae-1-2-1, and then click Continue. 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 IP address 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. SUBSCRIPTIONANNOTATE true Enables submission of subscription annotations back to the management system. TRACKSUBSCRIPTIONDELIVERY true Track when each device is delivered to for subscriptions. MAINLOGO /static/images/xmatters/logos/xmatters_ email.gif Specifies the location of the xmatters logo displayed in email notifications. Note: This optional field not added as part of the event domain import process. You must add this constant using the tools on the Event Domain Constants page to have the xmatters logo appear as expected. 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 23. Chapter 2: Installation and Configuration 11

2.3.2 Subscribing to alerts The subscriptions feature in xmatters determines who should receive notifications about CA Workload Automation jobs. 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 "FAILED", or whenever the status for an existing job was changed to "On Ice". To allow users to subscribe to specific criteria on injected events, you must configure the subscription using the following steps: Update the event domain predicates Define a subscription domain Create a subscription Create a fail-safe group Updating event domain predicates Two event domain predicates are created as part of importing the event domain: job_name and status. 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 CA Workload Automation, such as "job_name", "server", or "machine". To see where the tokens in your deployment are set, view the "polling_method" function in the cawaae-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 cawaae-1-2-1. 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 Event domain predicates job_name Text Name of the job for which notifications are being sent. status List The status of the job in CA Workload Automation; default values are: FAILURE TERMINATED The above values are required for the out-of-box integration; if you change the filter in the configuration.js file on the integration agent, you will need to modify this list to match all of the states defined in the file. For more information about the filter, see "Installing the integration service and updating the integration agent" on page 5. Note: 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. Chapter 2: Installation and Configuration 12

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 cawaae-1-2-1, and then click Continue. 4. On the Subscription Domain Details page, in the Name field, type CA Workload Automation AE. 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. Ignore Start Force Start Kill On Hold Off Hold On Ice Off Ice Release Resources Comment Send Signal Change Priority Change Status 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 for which 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 CA Workload Automation AE 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. Chapter 2: Installation and Configuration 13

To create a fail-safe group: 1. In xmatters, click the Groups tab. 2. Create a new group named CA Workload Automation AE Fail-Safe, 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 22. Chapter 2: Installation and Configuration 14

Chapter 3: Integration Validation The following sections will test the combination of xmatters and CA Workload Automation for notification delivery and response. This section also includes an explanation and demonstration of how to query CA Workload Automation via the xmatters mobile access component. After configuring xmatters and CA Workload Automation, you can validate that communication is properly configured. It is recommended that you start the components in the following order: CA Workload Automation xmatters integration agent xmatters Starting the integration agent This integration requires that you use the included wrapper scripts to start the integration agent. To start the integration agent on Unix systems: 1. Switch to the user configured in "Configuring the integration agent " on page 9: su - <USER> 2. Run the following command: <IAHOME>/bin/start_daemon_cawaae.sh To start the integration agent on Windows: 1. Open the CA Unicenter Autosys JM Command Prompt. 2. Navigate to the <IAHOME>\bin folder. 3. Run the start_daemon.bat file. 3.1 Triggering a notification To trigger a notification, ensure that you have created a subscription (for more information, see "Creating a subscription" on page 13). Trigger a notification that matches the criteria that you have configured your subscription to match.by running a new job in CA Workload Automation, and cause it to enter one of the states defined in the jobfilter section of the configuration.js file, as described in "Installing the integration service and updating the integration agent" on page 5. Note that the integration checks to see whether an event already exists in xmatters that is associated with the job. Any xmatters event that is already associated with the job is terminated before a new event is injected. 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 HTML email format, but the process is similar for all devices. To respond to a notification: 1. When a notification arrives, open it to view its details: Chapter 3: Integration Validation 15

2. To respond to the notification, click a response choice, and xmatters sends the response: For more information about response choices, and changing the options available to users, see "Response choices" on page 25. 3.3 Viewing response results To view the results of the response, view the job report details in CA Workload Automation: Chapter 3: Integration Validation 16

3.4 Viewing jobs The mobile access component has a default access URL of: http://<xmatters>:8888/mg Where <xmatters> is the IP address of the xmatters web server where the mobile access component is configured. To view a list of failed jobs: 1. Using a browser-enabled smart phone (such as a BlackBerry), open a browser and navigate to the mobile access component IP address: 2. Log in to view the list of available integration services. If more than one integration service is available, select the cawaae-1-2-1 service: Chapter 3: Integration Validation 17

3. If your xmatters User ID and password do not match an authorized CA Workload Automation user, you will be prompted for credentials: 4. On successful login, you will see a list of jobs that have failed within the last five minutes. You can use this page to see all the jobs that have failed up to 30 minutes ago: Chapter 3: Integration Validation 18

5. Click a job name to view the job details page (scroll down to view all of the job details): 6. Click the Run Time tab to view the status time and run machine Chapter 3: Integration Validation 19

7. Click the Upstream tab to view all the jobs on which this job depends: 8. Click the Downstream tab to view all jobs that are dependent on this job: Chapter 3: Integration Validation 20

9. From within any tab on the screen, select and action and then click Go to send an event to a job: Note that CA Workload Automation may not action the event immediately, depending on load. To view the current status of the job, click the Reload link at the bottom of the page. Chapter 3: Integration Validation 21

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 CA Workload Automation AE 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 XML file 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 event domain and scripts The integration package includes an XML file 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-ca-workload-automation.xml file extracted from the integration archive. 4. Click Open, and then click Upload. xmatters imports the integration configuration settings and displays the new cawaae-1-2-1 event domain. 4.1.2 Configuring the Event Domain By default this integration is set up to use an event domain of cawaae-1-2-1 ; 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. 4. Enter the following information into the form: Name: cawaae-1-2-1 Description: CA Workload Automation Integration Script Package: CA Workload Automation 5. Click Save. 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 "cawaae-1-2-1" event domain, as described in "Updating event domain predicates" on page 12. Chapter 4: Optimizing and Extending the Integration 22

Defining an integration service The mobile access component portion of this integration uses a default integration service of cawaae-1-2-1 ; it is strongly recommended that you use this default integration service. For the installation to be successful, the integration service name must match the service specified in the cawaae.xml file installed on the integration agent. To define an integration service: 1. In xmatters, on the Event Domains page, click the cawaae-1-2-1 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: Name: cawaae-1-2-1 Description: CA Workload Automation Integration Service Path: cawaae-1-2-1/menu.jsp 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 XMATTERSURL 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. 2. In the Event Domain drop-down list, select cawaae-1-2-1, 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. 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 IP address 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. Chapter 4: Optimizing and Extending the Integration 23

Constant Name Default Value Description failsafegroup CA Workload Automation AE Fail-Safe The fail-safe recipient to notify, typically a group. The failsafegroup identifies the recipient that will be notified if an event is injected to xmatters and no Subscriptions exist that match the event. Set this constant if you want to change the fail-safe group from CA Workload Automation AE Fail- Safe to another group defined in xmatters. failsafe enabled Controls fail-safe functionality, notifying the fail-safe recipient via EMAIL under certain circumstances. Possible values: enabled: Notify if no subscriptions match or no notifiable recipients. for-subscriptions: Notify if subscription functionality is enabled AND no subscriptions match. for-recipients: Notify if no notifiable recipients. disabled: Disable fail-safe functionality. subscriptionannotate true Enables submission of subscription annotations back to the management system. tracksubscriptiondelivery true Track when each device is delivered to for subscriptions. 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 1. 4.2 Adding new parameters Additional parameters (data elements or tokens that exist in CA Workload Automation) can be forwarded to xmatters by adding them to the event injected from CA Workload Automation. The following steps explain how to add a new event token to the event injected to xmatters. To add an event token: 1. In the cawaae-job.js file, add a new select statement to the two default statements. 2. Add a new function modeled after getjobs() and getjobdetails() that opens a database connection, executes the query, parses the results and returns the data. 3. In the cawaae-job-poller-thread.js file, locate the following line: var job_name = jobdetails.get("job_name"); 4. Following the above, line, add a new line that sets a javascript variable with the collection created in the previous step. 5. Locate the following line: apxml.settoken("run_priority", run_priority); 6. After the above line, add new lines that set more APXML tokens based on the data in the new collection. 4.2.1 Adding new tokens to notification content Once you have injected the new data elements, you can add the token as a parameter to the notification content for devices. The following steps explain how to add the custom parameter to email notifications; adding content for other device types is Chapter 4: Optimizing and Extending the Integration 24

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 CA Workload Automation (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> ) Your custom 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 CA Workload Automation 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 "Adding annotation messages", 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 CA Workload Automation job. 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 Start Force Start Adds an annotation to the job indicating it has been ignored by the user/device. Starts the job; the starting conditions must be satisfied before this response can be successful. Starts the job, regardless of whether its starting conditions are satisfied. Notify next, delink responder. Delink all except responder. Delink all except responder. Kill Kills the job. Delink all except responder. On Hold Places the job on hold, and prevents any downstream jobs from starting. Any job that has already started cannot be placed on hold. Delink all except responder. Off Hold Removes the job from on hold. Delink all except responder. On Ice Places the job on ice; for the effects of this state, including downstream jobs, consult the CA Workload Automation documentation. Any job that has already started cannot be placed on ice. Notify next, delink responder. Off Ice Removes the job from on ice. Delink all except responder. Release Resource Releases renewable resources held by the job. Delink all. Comment Attaches a message to the job. Delivered. Send Signal Sends a signal to a running job. Delink all except responder. Chapter 4: Optimizing and Extending the Integration 25

Response Description xmatters Job Control Change Priority Change Status Modifies the queue priority for the job. The priority is represented by an integer where 0 means the job should run immediately. Changes the job status. Note that using this command is not recommended. Delink all except responder. Delink all except responder. xmatters job control definitions The xmatters job controls defined in the above table are implemented as follows: 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 Adding annotation messages Two-way email device notifications (not FYI) can add extra annotations that will be added to the CA Workload Automation job status change. To add an extra annotation, respond to an email notification with the following format in the subject line: RESPONSE <Choice> <Message> <Choice> can be any of the response choices listed in the table above, and <Message> can be any content you want to add as the annotation. 4.3.2 Changing and adding response choices Changing or adding a response choice to the integration requires the following steps: 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 CA Workload Automation 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 Chapter 4: Optimizing and Extending the Integration 26

To send the response choice from the integration agent into CA Workload Automation, open the cawaae.js file, and add a new ELSE-IF statement to the handleapsresponses function: if ( responseaction.equalsignorecase( "be there in ten minutes" ) ) { // Implement functionality to use the CA WAAE SDK 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 extensively annotates the originating CA Workload Automation job for each device to which a notification is delivered, but this may not be desirable in all environments. To prevent the delivery annotation of an incident, change the "annotatedelivery" event domain constant to false. For more information, see "Defining event domain constants" on page 23. 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 22. 4.6 Filtering and suppression The xmatters integration agent's Portable Filtering and Suppression Module is a built-in module that maintains a rolling record of previously injected events, and allows for the suppression of duplicates (also referred to as "deduplication"). This helps avoid disruption of traffic due to inadvertent loads that can result when, for example, improperly configured management systems inject duplicated events. The deduplicator-filter.xml file is installed in the <IAHOME>\conf folder and is configured to suppress duplicate events for two minutes (up to a maximum of 100 events in that period). This filter can be modified to extend the time period over which an event is considered to be a duplicate, the number of events in that period and the tokens that are used to determine what makes the event unique. For example, to add REQUESTOR_NAME to the tokens, open the deduplicator-filter.xml file in a text editor and add the following line to the <predicates> collection: <predicate>requestor_name</predicate> Save the file and restart the integration agent for the changes to take effect. Note: To see a complete list of predicates available in the integration, review the event data in the Event Summary Report in the xmatters web user interface. 4.7 Optimizing the xmatters mobile access integration This section describes some of the ways you can optimize or extend the mobile access component portion of the xmatters (IT) for CA Workload Automation AE integration. Chapter 4: Optimizing and Extending the Integration 27

4.7.1 Add a custom query to the home page To add a custom query and link to the home page, add the following to the <XMHOME>\webservices\webapps\ mobilegateway\jsp\cawaae-1-2-1\configuration.jsp file installed on the mobile access component: MAIN_MENU_OPTIONS.put("Query Label", "Query"); For more information about constructing queries for CA Workload Automation, consult the CA Workload Automation documentation. 4.7.2 Creating a URL alias The urlalias.jsp page in the mobile access component is used to drive directly from an xmatters notification to the Create Incident or Update Incident screens. It supports the following parameters: urlalias.jsp parameters Name newincident IncidentID Field Name Description If this parameter is set, a new incident will be created and you will be taken to the Create Incident screen. If it is not set, you will be taken to the Update Incident screen for the specified incident. The incident number of the incident to update. If the newincident parameter is not set, this field must be set to a valid incident number. The name of an API Caption of a field for the incident. For each parameter set, it will update the field on the incident with that value. For more information about the urlalias method in the xmatters Action Script, refer to the xmatters Online Developer's Guide. 4.8 Troubleshooting This section identifies and explains some issues with the integration that may be encountered during installation, configuration, or validation. 4.8.1 Windows configuration issues The integration includes an asapi.jar file that is copied to the correct location within the integration agent when installing the integration components. In some cases, however, the included version of the asapi.jar file may not be the correct one required by your version of CA Workload Automation. In these cases, you can replace the asapi.jar file located in <IAHOME>\integrationservices\cawaae\lib with the version located in your CA Workload Automation installation's bin folder. The integration also includes an apijni.dll file that must be copied during the installation of the integration components to the following folders: <IAHOME>\lib\integrationservices If you encounter a exception error indicating that this file could not be found, ensure that you copied the entire contents of the folders from the extracted integration archive to their correct locations within the integration agent directory, and that the apijni.dll file exists in the appropriate location. You should also review the PATH environment variables specified in "Configuring the integration agent " on page 9, as the lack of appropriate permissions can cause the integration agent to fail, or to not start correctly. Chapter 4: Optimizing and Extending the Integration 28

4.9 Uninstalling For instructions on removing an xmatters deployment, refer to the xmatters installation and administration guide. Chapter 4: Optimizing and Extending the Integration 29

30