CA Spectrum (integration version 3.0)

Contents

Introduction

Prerequisites

Configure xMatters

Configure the Integration Agent

Configure CA Spectrum

How to use the integration

Extend and optimize your integration

Download resources

The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

Introduction

This article provides technical details for the implementation of the xMatters On-Demand service for use with CA Spectrum.

This integration uses the communication plan technology within xMatters On-Demand to become the voice and interface of an automation engine. When CA Spectrum detects something that requires attention, xMatters places phone calls, send emails, or notifies your mobile app.

Integration Version

This version of the integration (3.0) is compatible with CA Spectrum 10.2.0 and above, and is designed specifically for xMatters On-Demand. 

How it works

The integration adds functionality to the CA Spectrum Alarm Notifier scripts, which communicate via the xMatters Integration Agent. xMatters sends response information back via the CA Spectrum Web Services API, allowing users to own, acknowledge, escalate, and clear events remotely from their device.

When CA Spectrum detects an event, it invokes an Alarm Notifier Script, which uses a command-line interface (CLI) call to send the details to xMatters via the Integration Agent. xMatters notifies the correct recipients, and then uses a REST-based call to the CA Spectrum web services API to update the original event with response information.

You may need to customize some aspects of this integration to suit your specific requirements. For example, the default configuration has automatic status updates turned on, which can be a significant resource constraint on high-volume systems. 

Features and updates in this version

This version of the integration includes several updates and enhancements:

  • The integration now targets the inbound integrations included in the communication plan rather than the form itself. This provides access to all of the enhancement and options available in the Integration Builder, including the Activity Stream, transformation scripts, and authentication options.

Prerequisites

Before you get started configuring the integration, there are a couple of things you can do ahead of time to make it easier. 

Download the integration archive

The .zip file attached to this article contains all of the components required by xMatters and CA Spectrum. Download the attached .zip file to a location on your local machine, and extract the contents.

You may also notice that there is another .zip file within the extracted integration archive. This is the communication plan, which contains pre-configured integrations, forms, properties, and messages specifically designed for CA Spectrum. Do NOT extract the contents of the communication plan .zip file! You'll be able to import it directly into xMatters.

CA Spectrum API user

You'll need to provide the username and password for a user who can access and make REST calls to the CA Spectrum Web Services API.

For information about adding users and the Web Services API, refer to the CA Spectrum documentation.

Configure xMatters On-Demand

The first step in configuring this integration is to get your On-Demand environment ready, and set up the components on the xMatters side.

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the permissions and capabilities.

Note for trial: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.

To create an integration user:

  1. Log in to the target xMatters system.
  2. On the Users tab, click Add.
  3. Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients and how events will be displayed in reports and the Communication Center, you may want to identify the user as specific to this integration; for example:
    • First Name: CA Spectrum
    • Last Name: Integration
    • User ID: caspectrum
  4. Assign the user to the REST Web Service User role.
  5. Set the user ID and password.
    • Make a note of these details; you will need them when configuring other parts of the integration.
  6. Click Save.

Import the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In xMatters, click the Developer tab, and then click Import Plan.
  2. Click Browse, and then locate the plan you downloaded from this article (the .zip file).
  3. Click Import Plan.
    • Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user you created above, and then click Save Changes.
  6. In the Edit drop-down list for the plan, select Forms.
  7. For the first form in the list (Spectrum Incidents), click the Web Service Only drop-down list, and then select Sender Permissions.
  8. Add the integration user you created above, and then click Save Changes.
  9. Repeat steps 7-8 for each of the other forms in the plan.

Configure inbound integrations

You will need to configure the authentication and retrieve the URLs for each of the inbound integrations to configure CA Spectrum.

To configure an inbound integration:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the name of an integration to view its details.
  3. Under the Select authentication method step, select Basic from the drop-down list.
  4. Click Update Integration.
  5. Scroll down to the bottom of the page, and click Copy URL beside the field:

CopyURL.jpg

Create a web service user

This integration requires a web service user with specific permissions in xMatters to receive user responses and notifications about event status changes for the Integration Agent. ("Web service users" are a specific type of user in xMatters that can work with the SOAP web services used by the Integration Agent; this means you can't just use a regular user and assign them a specific role or permission, you have to create a dedicated user.)

To set up a web service user:

  1. In xMatters, click the Users tab, and then, in the menu on the left side of the page, click Add Web Service User.
  2. On the Add Web Service User page, enter a User ID and Password for the new web service user.
  3. In the Denied Web Services list, locate and select the following web services, and then click Add
    • Query User
    • Receive APXML
    • Register Integration Agent
    • Submit APXML
  4. Click Save.

Determine identifiers

Some configuration fields require a UUID (Universal Unique Identifier) for a specific component or property in a communication plan - usually the responses. To retrieve the identifier for an element, look for the API icon in the xMatters user interface:

Clicking this button will display the identifier for the component in a dialog box; you can copy and paste the string to the appropriate location in the configuration file.

As an example, the following instructions describe how to retrieve the UUID for a specific response choice; the process is similar for any identifier you want to determine.

To retrieve the identifier for a response choice:

  1. In xMatters, open the CA Spectrum communication plan.
  2. On the Spectrum Incidents form, click Edit > Responses.
  3. Beside the Acknowledged response, click the API icon.

Configure the xMatters Integration Agent

Now that you've configured xMatters On-Demand, it's time to configure the Integration Agent.

The installation instructions below assume you already have a working xMatters Integration Agent.  If this is a new installation and you have not yet deployed the Integration Agent, follow this link to download, deploy and configure it: Integration Agent for xMatters 5.x & xMatters On-Demand

Install the integration files

The installation package contains all that you need to configure the integration.

Note: As usual for our Integration Agent documentation, <IAHOME> refers to the installation folder of the Integration Agent on your system.

To install the integration files:

  1. Within the extracted integration archive, navigate to components/integration-agent/integrationservices, and copy the entire contents of the folder to the <IAHOME>/integrationservices directory.
  2. Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
    <path>caspectrum-3-0/caspectrum.xml</path>
  3. Save and close the file.
  4. Open the <IAHOME>/integrationservices/caspectrum/configuration.js file and add or set the values for the following variables:
CAS_HOME The CA Spectrum installation folder on your server.
XMATTERS_CASPECTRUM_ALERT_URL The URL for the "Spectrum Incidents" inbound integration.
RESPONSE_OPTIONS_WHEN_NOT_CLEARABLE The identifiers for the response options that you want to be available to the user for CA Spectrum events that can't be cleared. 
XMATTERS_CASPECTRUM_CONFERENCE_URL The URL for the "Spectrum Major Incident Conference" inbound integration.
XMATTERS_ENABLE_CONFERENCES When set to true, xMatters automatically creates conference bridges for events with Critical and Major severity (default is false).
INITIATOR The User ID of the integration (REST) user you created in xMatters.
PASSWORD

Path and filename of the password file containing the encrypted integration user's password.

CA_API_BASE_PATH

The location (URL) of the CA Spectrum Web Services API.
 

CA_API_USER

Specifies the user ID of the CA Spectrum Web Services API user.
 

CA_API_PASSWORD

Path and filename of the password file containing the encrypted Web Services API user's password.
DEDUPLICATION_FILTER_NAME Name of the filter used to suppress duplicate notifications for this integration. For more information, see Configure deduplication.
annotationPrefix Annotation to use as a prefix for xMatters entries within CA Spectrum.
 

LOGGING_ENABLED

When set to true, writes the integration logs to <IAHOME>/logs/xmatters_spectrum.txt
  1. Save and close the file.
  2. Restart the Integration Agent

Set the password files

This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the integration user and the CA Spectrum Web Services API user. You will need to update (or create) the files with the correct passwords for these users.

Password files:

  • "initiatorpasswd" stores the password for the integration user
  • "caapipasswd" stores the password for the CA Web Services API user

Note: If you store the passwords with a different file name or in a different location, you must update the <IAHOME>/integrationservices/caspectrum-3-0/configuration.js file with the correct name and path.

To configure the REST API user password:

  1. Open a command prompt and navigate to <IAHOME>\bin
  2. Run the following command, where <new_password> is the password for the INITIATOR (the integration user) specified in the<IAHOME>\integrationservices\caspectrum\configuration.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.initiatorpasswd
  1. Now run the command again, but where <new_password> is the password for the CA_API_USER (the CA Spectrum API user) specified in the<IAHOME>\integrationservices\caspectrum\configuration.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.caapipasswd

For more information about working with the iapassword command, and creating password files, refer to the xMatters Integration Agent Guide.

Configure deduplication

The integration package includes a filter that engages the Integration Agent's filtering and suppression module to suppress duplicate events (also know as deduplication). This can help to avoid disruption of traffic due to event floods (a potential hazard with improperly configured management systems).

The deduplicator is installed into the <IAHOME>\conf folder, and is configured by default to suppress up to 100 duplicate events for two minutes. You can configure the filter to extend the time period in which an event is considered to be a duplicate, the number of events within that period, and the tokens or properties that xMatters uses to determine what makes the event unique.

To enable deduplication:

  1. Navigate to the <IAHOME>/conf directory.
  2. If you have an existing deduplicator-filter.xml file in this folder, create a backup version in a separate location.
  3. Copy the deduplicator-filter.xml file from the integration-agent/conf folder in the extracted integration archive into the <IAHOME>/conf directory.
  4. Restart the Integration Agent.

For more information about the deduplication filter and the available settings, refer to the "Filtering and Suppression" section in the xMatters Integration Agent Guide

Configure CA Spectrum

To configure CA Spectrum to integrate with xMatters, you need to modify the CA Spectrum Alarm Notifier Scripts. 

Note: In the following steps, <CAS_HOME> refers the base installation directory of your CA Spectrum instance.

Modify the Alarm Notifier Scripts

You need to add a reference to the APClient.bin.exe tool that injects the CA Spectrum events into the Integration Agent.

To configure the CA Spectrum Alarm Notifier Scripts:

  1. On your CA Spectrum server, navigate to the <CAS_HOME>\Notifier directory, and open the SetScript file in a text editor.
  2. Add the following code to the end of the file (replace <IAHOME> with the installation folder of your Integration Agent:
#####################################################################
# xMatters
#####################################################################
# Parse Alarm Title info
if [ "$SEV" = "CRITICAL" -o "$SEV" = "MAJOR" -o "$SEV" = "MINOR" ]
then
   ALARMTITLE=`echo $PCAUSE | awk '{ print substr($0,1,index($0,"SYMPTOMS:") - 2) }'`
   echo "Injecting xMatters event for SPECTRUM AlarmID:" $AID
   “/bin/APClient.bin.exe" \
      --map-data "applications|caspectrum-3-0" "" "$AID" "$RAW_ALARM_TIME" "$DTYPE" "$MTYPE" "$MNAME" "$AID" \
      "$SEV" "$CAUSE" "$REPAIRPERSON" "$STATUS" "$SERVER" "$LANDSCAPE" "$MHANDLE" "$MTHANDLE" \
      "$IPADDRESS" "$SECSTR" "$ALARMSTATE" "$ACKD" "$CLEARABLE" "$AGE" "$PCAUSE" "$EVENTMSG" \
      "$ALARMTITLE" "SET" "" "" "$GLOBAL_ALARM_ID"
else
   echo "Not injecting xMatters event for SPECTRUM AlarmID:" $AID
fi
  1. Save and close the SetScript file.
  2. Now open the ClearScript file (in the same folder) in a text editor, and add the following code to the end of the file (replace <IAHOME> with the installation folder of your Integration Agent):
#####################################################################
# xMatters
#####################################################################
if [ "$SEV" = "CRITICAL" -o "$SEV" = "MAJOR" -o "$SEV" = "MINOR" ]
then
   echo "Injecting xMatters event for cleared SPECTRUM AlarmID:" $AID
   "/bin/APClient.bin.exe" \
      --map-data "applications|caspectrum-3-0" "" "$AID" "$RAW_ALARM_TIME" "$DTYPE" "$MTYPE" "$MNAME" "$AID" \
      "$SEV" "$CAUSE" "$REPAIRPERSON" "$STATUS" "$SERVER" "$LANDSCAPE" "$MHANDLE" "$MTHANDLE" \
      "$IPADDRESS" "$SECSTR" "$ALARMSTATE" "$ACKD" "$CLEARABLE" "$AGE" "Cleared Event" \
      "$EVENTMSG" "CLEARED EVENT" "CLEAR" "$CLEARED_BY_USER_NAME" "false" "$GLOBAL_ALARM_ID" 
else
   echo "Not injecting xMatters event for cleared SPECTRUM AlarmID:" $AID
fi
  1. Save and close the ClearScript file.
  2. Still in the <CAS_HOME>\Notifier folder, open the .alarmrc file in a text editor.
  3. Locate the GET_EXISTING_ALARMS parameter and set its value to "false".
    • If you do not change the the GET_EXISTING_ALARMS parameter, CA Spectrum will attempt to notify any existing alarms in the system whenever you run the AlarmNotifier.exe command, regardless of whether the alarms have already been notified.
  4. Locate the ENABLE_CORRELATION parameter, and set its value to "true".
  5. Locate the USE_NEW_INTERFACE parameter, and set its value to "true".
    • These steps ensure that CA Spectrum will include the Global Alarm ID when sending the details of the event to xMatters; the CA Spectrum Web Services API requires this information to update the status of an alarm.
  6. Save and close the .alarmrc file. 

And that's it! Your integration should be ready to go.

How to use the integration

When the integration is configured, CA Spectrum will automatically send information about any alarms it detects to xMatters via the Integration Agent.

Trigger a notification

To test the incident notification portion of the integration, create a new alarm in CA Spectrum that targets a user with a device that you can access (so you can respond to the notification when it arrives).

The Status field on the Alarm Details tab will show when the notification gets delivered:

CASpectrum-NotificationDelivered.png

Respond to a notification

On a device with the xMatters mobile app, you can respond to the message simply by tapping Respond, and then tapping one of the response choices.

CASpectrum-NotifReceived.pngCASpectrum-ResponseChoices.png

Other devices use similar methods: in an email notification, you would click a link in the message body; for an SMS, you would send an SMS reply containing a response option (or even a single digit).

For a voice notification, you would press a button on your phone to indicate your choice. If the message included a conference bridge request, the message is read aloud via the text-to-speech feature, and you would be prompted to join the conference. For example:

This is a manual conference bridge notification from CA Spectrum regarding INC0000054.
Message: The SAP system is throwing database errors.
Press 1 to join the conference, press 2 to ignore and stop notifying.

View response results

After you respond to the notification, you can see how the integration automatically updates the event information with the response details:

CASpectrum-ResponseReceived.png

Extend and optimize your integration

You can use the following tips to customize your integration to better suit your deployment.

Cleared events

By default, the integration terminates events in xMatters when the related event is cleared in CA Spectrum. You can modify the behavior so that xMatters notifies users when the event is cleared instead.

To notify users about cleared events:

  1. In xMatters, navigate to the Developer tab and locate the CA Spectrum communication plan.
  2. Click Edit > Integration Builder.
  3. On the Integration Builder tab, click Edit Constants
  4. Change the value of the Create Event on Alarm Clear constant to true.
  5. Click Save Changes.

Enable extra logging

To enable the logging of user annotations and notification delivery annotations to <IAHOME>\logs\xmatters_spectrum.txt, backup your <IAHOME>\conf\log4j.xml file, and then replace it with the integration-agent/conf/log4j.xml file included in the extracted integration archive.

This feature is turned off by default, as the log file can grow unbounded unless it is watched closely, or logs are rolled over on a regular basis.

Download resources

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk