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 you with the installation and configuration details you need to integrate the xMatters On-Demand service with CA Service Desk Manager.
This integration uses the communication plan technology within xMatters On-Demand to become the voice and interface of an automation engine. When CA Service Desk Manager detects something that requires attention, xMatters places phone calls, send emails, or notifies your mobile app.
This version of the integration (3.0) is compatible with CA Service Desk Manager 14.1 (and later), and is designed specifically for xMatters On-Demand.
The integration adds functionality to the CA Service Desk Manager notification process, allowing users to own, acknowledge, escalate, and clear events remotely from their device.
Whenever CA SDM detects an event, a custom Notification Method runs a wrapper shell script that sends a notification file to the xMatters Integration Agent. The Integration Agent extracts the NX_NTX fields from the notification file and sends them to xMatters as event properties.
A REST-based call to the CA Service Desk Manager web services API updates the original event with response information.
You may need to customize some aspects of this integration to suit your specific requirements. For example, by default the integration filters out notifications that are not addressed to the ticket's assignee or group, and terminates previous xMatters events related to the same ticket. You can also customize the response options according to your business needs.
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.
Before you get started configuring the integration, there are a couple of things you can do ahead of time to make it easier.
The .zip file attached to this article contains all of the components required to integrate xMatters and CA Service Desk Manager. 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 named CAServiceDeskManager within the extracted integration package. This is the communication plan, which contains pre-configured integrations, forms, properties, and messages specifically designed for CA Service Desk Manager. Do NOT extract the contents of the communication plan .zip file! You'll import it directly into xMatters.
(This version of the integration uses a new version of the Integration Agent Utilities package that is included in the integration archive.)
You'll need the username and password for a user who can access and make REST calls to the CA Service Desk Manager Web Services API.
For information about adding users and the Web Services API, refer to the CA Service Desk Manager documentation.
The first step in configuring this integration is to get your On-Demand environment ready, and set up the components on the xMatters side.
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.
The next step is to import the communication plan.
To import the communication plan:
- In xMatters, click the Developer tab, and then click Import Plan.
- Click Choose File, and then locate the plan you downloaded from this article (the .zip file).
- 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.
You need to configure the authentication and retrieve the URLs for each of the inbound integrations to configure CA Service Desk Manager.
To configure an inbound integration:
- In the Integration Builder, expand the list of inbound integrations.
- Click the name of an integration to view its details.
- Under the Select authentication method step, select Basic from the drop-down list.
- Click Update Integration.
- Scroll down to the bottom of the page, and click Copy URL beside the field (you'll need this later to configure the Integration Agent):
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:
- In xMatters, click the Users tab, and then, in the menu on the left side of the page, click Add Web Service User.
- On the Add Web Service User page, enter a User ID.
- 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
- Enter a Password for the new web service user.
- Click Save.
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 displays the identifier for the component in a dialog box, which you can copy and paste into 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:
- In xMatters, open the CA Service Desk Manager communication plan.
- On the Service Desk Manager Incidents form, click Edit > Responses.
- Beside the Acknowledged response, click the API icon.
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.
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:
- Within the extracted integration archive, navigate to components/integration-agent/integrationservices, and copy the entire contents of the folder to the <IAHOME>/integrationservices directory.
- Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
- Save and close the file.
- Open the <IAHOME>/integrationservices/applications/caservicedesk-3-0-0/configuration.js file and add or set the values for the following variables:
|INTEGRATION_URLS||The URLs for each of the CA Service Desk Manager inbound integrations.|
|ERROR_URL||The URL of the inbound integration to use when response updates fail in CA Service Desk Manager.|
|RESPONSES||The identifiers for the response options for each xMatters form or CA Service Desk Manager ticket type.|
|INITIATOR||The User ID of the integration (REST) user you created in xMatters.|
|INITIATOR_PASSWORD_FILE||Path and filename of the password file containing the encrypted password of the xMatters initiator user.|
|INITIATOR_USER_ID||The User ID of the user that authenticates REST API calls to xMatters.|
|SERVICE_DESK_URL||The URL of the CA Service Desk Manager web service.|
|SERVICE_DESK_USER||The user name of the CA Service Desk Manager web service user used to access the web services.|
|SERVICE_DESK_PASSWORD_FILE||Path and filename of the password file containing the encrypted password of the web service user.|
|DEDUPLICATOR_FILTER_NAME||Name of the filter used to suppress duplicate notifications for this integration. For more information, see Configure deduplication.|
|DELETE_EXISTING_EVENTS||When set to true, sends a 'delete' prior to creating the new event to clear any existing events for this Incident ID.|
|Used to create an xMatters event when there is an exception while processing a user response.|
|ERROR_MESSAGE_PRIORITY||Priority of the xMatters event created if there's an exception while processing a user response.|
|INTEGRATED_PROPERTIES||Specifies the mapping of CA Service Desk Manager web service properties to the integrated properties in xMatters.|
|TICKET_CONTACTS||CA Service Desk Manager incident properties to be treated as Contact UUIDs and resolved via look-up call to CA SDM.|
|ADD_IGNORE_RESPONSE||If set to true (default), adds "Ignore" to the list of response choices. Set this to false to remove the option for a user to ignore a notification.|
- Save and close the file.
- Restart the Integration Agent.
This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the integration user and the CA SDM web services user. You need to update (or create) the files with the correct passwords for these users.
- "initiatorpasswd" stores the password for the integration user
- "caservicedesk" stores the password for the CA Service Desk Web Services user
Note: If you store the passwords with a different file name or in a different location, you must update the <IAHOME>/integrationservices/applications/caservicedesk-3-0-0/configuration.js file with the correct name and path.
To configure the REST API user password:
- Open a command prompt and navigate to <IAHOME>\bin.
- Run the following command, where <new_password> is the password for the INITIATOR (the integration user) specified in the <IAHOME>/integrationservices/applications/caservicedesk-3-0-0/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
- Next, run the following command, where <new_password> is the password for the SERVICE_DESK_USER (the CA Service Desk Web service user) specified in the <IAHOME>/integrationservices/appllcations/caservicedesk-3-0-0/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/caservicedesk.pwd
For more information about working with the iapassword command, and creating password files, refer to the Integration Agent section in the help.
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 avoid disruption of traffic due to event floods (a potential issue 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:
- Navigate to the <IAHOME>/conf directory.
- If you have an existing deduplicator-filter.xml file in this folder, create a backup version in a separate location.
- Copy the deduplicator-filter.xml file from the integration-agent/conf folder in the extracted integration archive into the <IAHOME>/conf directory.
- If you backed up an existing deduplicator file, merge the contents of your backup with the newly installed <IAHOME>/conf/deduplicator-filter.xml file: open both files in a text editor, and then copy the <filter> node from the backup file into the new deduplicator file after the last </filter> node. Save and close the file.
- Restart the Integration Agent.
For more information about the deduplication filter and the available settings, refer to the "Filtering and Suppression" section in the Integration Agent section of the help.
To configure CA Service Desk Manager to integrate with xMatters, you need to:
- Install the xMatters integration script on the CA SDM server.
- Configure a new notification method to notify Users via xMatters.
- Configure CA SDM to use managed login and allow impersonations (optional but recommended).
Note: You may also want to perform periodic maintenance on the CA SDM temporary files, as described in Purging temporary files.
The integration has a pair of operating-system-specific integration scripts (xmattersIntegration for Linux and xmattersIntegration.bat for Windows) that are used as a bridge between CA SDM and the event integration service. You need to configure the file for your OS then copy it to your CA SDM server.
Configure the integration script
These scripts assume that the Integration Agent is installed in the default <IAHOME> folder. If you installed the Integration Agent in a different location, update the script files to reflect the installation path of your Integration Agent.
Note: CA SDM also requires that any paths in these script do not contain spaces. For example, the default installation path in Windows systems includes the "Program Files (x86)" folder. In this case, you need to replace all paths in the xmattersintegration.bat file with their "8dot3" formatted equivalents.
To determine the 8dot3 version of a folder name, run the dir /x command in its parent folder. This command produces a directory listing of the folder's contents in 8dot3 format (for example, "Program Files (x86)" often becomes PROGRA~2). Use these folder names when configuring your integration script.
To configure the integration script:
- For Windows systems, determine the "8dot3" representation of the path to your <IAHOME> folder.
- For example, the 8dot3 representation of the default Integration Agent installation folder should resemble the following: c:\progra~2\xmatters\integr~1
- Open the <IAHOME>/integrationservices/applications/caservicedesk-3-0-0/xmattersintegration.bat (xmattersintegration for Linux) file in a text editor.
- Edit the following lines to replace the paths with the location of your Integration Agent's bin folder.
IF EXIST "C:\Program Files (x86)\xmatters\integrationagent\bin\" (
SET IAHOME=C:\Program Files (x86)\xmatters\integrationagent
For example, to use the path shown earlier, you would edit the lines as follows:
IF EXIST "c:\progra~2\xmatters\integr~1\bin\" (
- Save and close the file.
Some versions of the integration script contains two sets of similar lines. We recommended you replace both sets of the lines with a single set as identified in the steps above.
Copy the integration script to the CA SDM Server
To simplify the command path for the xMatters Notification Method that you'll create in CA SDM, we recommend you copy the integration script files to the CA SDM server.
Copy the scripts to one of the following locations:
- Windows: Copy the <IAHOME>\integrationservices\applications\caservicedesk-3-0-0\xmattersIntegration.bat file from the extracted integration archive to the <CA SDM Install Folder>\Service Desk Manager\bin folder. (On Windows systems, the default CA SDM installation location is C:\Program Files\CA\Service Desk Manager.)
- Linux: Copy the <IAHOME>/integrationservices/applications/caservicedesk-3-0-0/xmattersIntegration file from the extracted integration archive to the <CA SDM Install Folder>/Service Desk Manager/bin folder.
To configure a notification method for this integration, create a new notification for xMatters, and then set CA Service Desk Manager to use the new notification method.
To configure a notification method:
- Click the Administration tab in the CA Service Desk Manager Web Client interface, expand Notifications, and then click Notification Methods.
- Click Create New.
- In the Create New Notification Method dialog box, enter the following information:
- Symbol: xM
- Write to File: Yes
- Supports SMTP: No
- Record Status: Active
- Description: Notify via xMatters
- In the Notification method field, type the command appropriate for your operating system:
- Windows: launchit.exe -b xmattersIntegration.bat
- Linux: launchit -b xmattersIntegration
- Set the xM notification method for contacts. CA SDM will now use xMatters On-Demand to notify users.
- Configure the notification rules in CA SDM.
It is recommended that you configure CA Service Desk Manager to support managed login and impersonation. This allows interactions from xMatters to CA SDM to be executed by impersonating the user responding to the notification.
Note: this requires each CA SDM user who you want to receive notifications from xMatters to have the Impersonate check box selected.
The Managed Login functionality in CA SDM performs the user authentication by: locating the defined security policy through the plain text policy code; finding the policyholder's public key associated with the policy; decrypting the encrypted policy code; matching decrypted content with the policy code; and, finally, opening a session with a back-end server.
To configure Managed Login on CA SDM, please refer to the CA Service Desk Manager documentation on how to create the Manager Certificate for use in this process.
Note: Upgrading CA Service Desk Manager overwrites the Manager Certificate. Ensure that you create a copy of the Manager Certificate file and store it in a location outside the CA SDM subdirectory.
To configure Managed Login with xMatters:
After the Manager Certificate has been created:
- Open the <IAHOME>/integrationservices/appllcations/caservicedesk-3-0-0/configuration.js file.
- Ensure that:
- MANAGED_LOGIN and ENABLE_IMPERSONATE are set to true,
- ACCESS_POLICY_FILE_PATH matches the location of the Manager Certificate (ending in a forward slash), and
- ACCESS_POLICY matches the name of the Manager Certificate (with no file extension).
The values in the configuration.js file are the default values that are applicable if you are following the CA Service Desk Manager documentation.
If you don't want the integration to use managed login, set the MANAGED_LOGIN and ENABLE_IMPERSONATE variables to false. In this case, the SERVICE_DESK_USER is used to update the tickets with xMatters responses. The managed login functionality applies only to the notification integration; the data load service does not use managed login.
Configure a contact for system notifications
If you configure the integration to use managed login, it's a good idea to configure a separate CA SDM contact to use for xMatters system notifications (such as delivery notifications). You can use any Access Type that has Functional Access for issue_mgr set to "Modify" in the CA SDM Security and Role Management details. For more information, refer to your CA SDM documentation.
To configure the contact:
- In the CA SDM interface, click the Administration tab, expand Security and Role Management, then click Contacts.
- Click Create New.
- In the Create New Contact dialog box, enter the following information:
- Last Name: xMatters
- User ID: xMatters
- Access Type: Administration
- Status: Active
- Click Save.
Note: If you enter a different User ID, you must also update the value of the ANNOTATION_USER variable in the configuration.js file.
And that's it! Your integration should be ready to go.
When the integration is configured, CA Service Desk Manager automatically sends information about any incidents it detects to xMatters via the Integration Agent.
To test the incident notification portion of the integration, create a new ticket or incident in CA Service Desk Manager that targets a user with a device that you can access (so you can respond to the notification when it arrives) and who exists in both CA SDM and xMatters.
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.
After you respond to the notification, you can see how the integration automatically updates the event information with the response details in CA SDM.
In the following example, the "Assignee" field has been updated to the name of the responding User, the "Status" has been updated to "Acknowledged", and the "Incident Activity Log List" has been updated with additional entries to show the changes resulting from the User's response:
You can use the following tips to customize your integration to better suit your deployment.
This integration relies on temporary files created by CA SDM to store notification data that will be sent to the integration agent. Files generated for the xMatters integration are not needed after the incident has been injected into the integration agent, but the temporary files are not automatically deleted.
If these files are not purged occasionally, injections into xMatters may be delayed while CA SDM searches for the next available file name (for example, after restarting CA SDM).
By default, these files are stored in the temp folder on the CA SDM server, and are named sequentially, for example, c:\temp\1, c:\temp\2, etc.
The integration creates a folder into which it moves the notification files after they have been processed. This folder is named "xmatters", and is located within the original file location. For example, if CA SDM creates a notification file called C:\temp\1, the integration renames the file and moves it to c:\temp\xmatters\1.<date>, where <date> is the current date and time in a "yyMMddHHmmss" format. (The directory and filename scheme can be customized by editing the caservicedesk.js integration script. This process is intended to reduce the delay that may be encountered after CA SDM is restarted, before notifications are sent to the integration agent.
It's recommended that you occasionally purge the files from the temp\xmatters folder to reduce congestion of the CA SDM server's file system.
Customize the handling of temporary files
The temporary file handling feature can be disabled or configured by modifying the following sections within the caservicedesk-event.js integration script.
// markProcessed() will attempt to move the parsed notification file to a subdirectory called xmatters.
// This is bound by file system access so if you don't want this feature just comment out fileParser.markProcessed().
// If you want a different directory, use full qualified path.
//fileParser.markProcessed('<custom directory>', '<custom filename>');
// If you want to control directory and file name.
To copy (instead of move) the CA SDM temporary file to the xmatters folder after processing, set setCopyAfterProcessing to true.
To move the file to a folder other than %temp%\xmatters, edit the script to include the desired location using the format "fileParser.markProcessed('<custom directory>');". For example:
To move the file to a custom folder AND rename it, edit the script to include the desired location and name in the format "fileParser.markProcessed('<custom directory>', '<custom filename>');". For example:
This causes the previous notification files to be overwritten, effectively preventing the folder from filling up with temporary files (since each file replaces the previous one when it is moved and renamed.)
By default, this integration annotates the originating CA SDM ticket for each device to which a notification is delivered. If this is not desirable in your environment, you can prevent delivery annotation of an incident by changing the ANNOTATE_DELIVERY variable to false in the configuration.js file.
This integration supports one-way batch loading of groups, users, and devices from CA SDM into xMatters. To configure the data load according to your business needs, see Configuring data load for CA Service Desk Manager.