CA Spectrum (integration version 3.0.1)



Before you begin

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.


This article provides technical details for the implementation of the integration between xMatters and CA Spectrum.

This integration uses a workflow within xMatters 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.1) is compatible with CA Spectrum 10.2.0 and above, and is designed specifically for xMatters. 

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 included the following updates and enhancements:

  • The integration now targets the inbound integrations included in the workflow 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.

Before you begin

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 workflow, which contains pre-configured integrations, forms, properties, and messages specifically designed for CA Spectrum. Do NOT extract the contents of the workflow .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

The first step in configuring this integration is to set up the components on the xMatters side.

Set up an integration user

This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters. See Create an integration user for more information.

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.

Import the workflow

The next step is to import the workflow.

To import the workflow:

  1. In xMatters, click the Workflows tab, and then click Import.
  2. Browse to the .zip file you downloaded, or drag it onto the Import Workflow dialog box.
  3. Click Import Workflow.
    • Once the import is finished, the workflow should be automatically enabled. If it isn't, click the Disabled toggle to enable it.
  4. Click the gear icon beside the workflow, and select Editor Permissions.
  5. Add the integration user, and then click Save.
  6. Click the workflow name to open the Forms tab.
  7. For the first form in the list (Spectrum Incidents), click the Web Service dropdown, and then select Sender Permissions.
  8. Add the integration user, and then click Save Changes.
  9. Repeat steps 7-8 for each of the other forms.

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 Save.
  5. Scroll down to the bottom of the page, and click Copy beside the field:


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 workflow - 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 workflow.
  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, 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

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

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


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


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


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.


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-1/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" ]
   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-1" "" "$AID" "$RAW_ALARM_TIME" "$DTYPE" "$MTYPE" "$MNAME" "$AID" \
   echo "Not injecting xMatters event for SPECTRUM AlarmID:" $AID
  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" ]
   echo "Injecting xMatters event for cleared SPECTRUM AlarmID:" $AID
   "/bin/APClient.bin.exe" \
      --map-data "applications|caspectrum-3-0-1" "" "$AID" "$RAW_ALARM_TIME" "$DTYPE" "$MTYPE" "$MNAME" "$AID" \
      "$IPADDRESS" "$SECSTR" "$ALARMSTATE" "$ACKD" "$CLEARABLE" "$AGE" "Cleared Event" \
   echo "Not injecting xMatters event for cleared SPECTRUM AlarmID:" $AID
  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:


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.


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:


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 Workflows tab and locate the CA Spectrum workflow.
  2. Click the workflow name then select the Integration Builder tab.
  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
    Christine Astle

    Updated to version 3.0.1, improving how the integration handles a specific response scenario from xMatters that was resulting in errors.

Please sign in to leave a comment.
Powered by Zendesk