Data load from CA Service Desk Manager to xMatters

Contents

Introduction

Configure the Integration Agent

Data load sources and rules

Data load process

Validate the data load

Extend and optimize the data load

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

The data load feature is an extension of the CA Service Desk Manager integration, and enables one-way batch loading (adding and updating only) of groups, users, and devices from CA SDM into xMatters. Make sure you install and configure that integration before following the instructions below to set up the data load for your environment.

Configure the Integration Agent

The data load files are included with the CA Service Desk Manager integration version 3.0 package.

The installation package contains all the components you need to configure the data load from CA SDM to xMatters, including the following configuration files:

  • configuration.js: defines the default values for objects loaded into xMatters, allows the configuration of filters that use CA SDM contact attributes to determine which contacts are transferred to xMatters, and controls the logging of data load results.
  • dataSyncList.js: defines whether the data load updates existing objects or only adds new objects. It also specifies the list of included or excluded objects (referred to as the "sync list").

You can modify the behavior of the data load process by editing the parameters in these two files.

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

Install the data load configuration files

The necessary files should have been installed when you installed the integration files. If not, you can install the files for the data load process separately.

To install the data load files separately:

  1. If you didn't copy the casddataload folder when you installed the CA Service Desk integration, go to the extracted integration archive, navigate to components/integration-agent/integrationservices/applications/, and copy the casddataload-3-0-0 folder to the <IAHOME>/integrationservices/applications directory.
  2. Open the <IAHOME>/conf/IAConfig.xml file and add the following line to the "service-configs" section:
    <path>casddataload-3-0-0/casddataload.xml</path>
  3. Save and close the file.

Edit the data load configuration files

To edit the data load configuration.js file:

  1. Open the <IAHOME>/integrationservices/applications/casddataload-3-0-0/configuration.js file and add or set the values for the following variables:
XMATTERS_INTEGRATION_URL The URL for the CA Service Desk Manager inbound integration you want to send the data load summary to.
SERVICE_DESK_URL The URL of the CA Service Desk Manager web service.
SERVICE_DESK_USER The username of the CA SDM 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.
SEND_SYNC_SUMMARY Determines whether the data load summary is sent to the xMatters Administrator (default is true).
XMATTERS_ADMINISTRATOR  The xMatters user you want to send the data load summary to.
SYNC_SUMMARY_SUBJECT The subject of the sync summary email that is sent to the xMatters Administrator if SEND_SYNC_SUMMARY is set to true.
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.
DATA_LOAD_EXCEPTION_LOG_
MESSAGE
The message that is written to the Integration Agent log file when a data load operation terminates unexpectedly.
WHERE_CLAUSE_USERS

Selects a subset of CA SDM users for transfer to xMatters.

Default: Selects only active CA SDM Contacts whose Contact type is Analyst, Help Desk, Manager, Operator or Technician.

Note: If you change this variable, you must edit WHERE_CLAUSE_GROUP_MEMBERS

The users and groups transferred from CA SDM to xMatters are also impacted by the settings in the dataSyncList.js file.

WHERE_CLAUSE_GROUPS

Selects a subset of CA SDM groups for transfer to xMatters.

Default: Selects only active CA SDM Contacts whose Contact type is Group.

The users and groups transferred from CA SDM to xMatters are also impacted by the settings in the dataSyncList.js file.

WHERE_CLAUSE_GROUP_MEMBERS

Selects the CA SDM users who are members of a specified group.

Default: Selects members of the specified group that are active CA SDM Contacts whose Contact type is one of Analyst, Help Desk, Manager, Operator or Technician.

Note: If you change this variable, you must edit WHERE_CLAUSE_USERS

The users and groups transferred from CA SDM to xMatters are also impacted by the settings in the dataSyncList.js file.

ATTRIBUTES_CNT_OBJECT
ATTRIBUTES_GRPMEM_OBJECT
ATTRIBUTES_CONTACT_ROLES
Determine which attributes are retrieved for contacts, group members and contact roles from CA SDM.
DEFAULT_USER_FIRST_NAME Specifies the first name of any users created in xMatters when the corresponding CA SDM Contact does not have a first name (default is "undefined").
MAP_USER_ROLES

If this variable is false (default), all xMatters users are assigned the role or roles defined by DEFAULT_XMATTERS_ROLES, regardless of what CA SDM Contact Type the individual users have.

If true, the xMatters roles assigned to individual users are based on their types in CA SDM and the role mappings defined by the roleMap variable.

DEFAULT_XMATTERS_ROLES  The default role or roles assigned to users in xMatters, if MAP_USER_ROLES is set to false (default is Standard User).
roleMap If MAP_USER_ROLES is set to true, this setting specifies how to map CA SDM support groups functional roles to xMatters roles.
DEFAULT_USER_SITE The site to which any new xMatters user belongs (default is Default site).
DEFAULT_PROVIDER_EMAIL The default user service provider for email devices (default is (x)matters Email Gateway).
DEFAULT_PROVIDER_TEXT The default user service provider for text devices (default is (x)matters SMS Gateway).
DEFAULT_PROVIDER_VOICE The default user service provider for voice devices (default is (x)matters Voice Gateway).
EXTERNALLY_OWN_USERS Determines whether users created in xMatters should be marked as "Externally Owned" (default is false).
EXTERNALLY_OWN_GROUPS Determines whether groups created in xMatters should be marked as "Externally Owned" (default is false).
WEB_LOGIN_TYPE

Specifies the method of web login to use for users created in xMatters:

  • "NATIVE" (default): uses xMatters web login credentials
  • "LDAP": uses the LDAP domain set in WEB_LOGIN_LDAP_DOMAIN.
WEB_LOGIN_LDAP_DOMAIN The LDAP domain to use if WEB_LOGIN_TYPE is set to "LDAP".
DEFAULT_SUPERVISOR The xMatters user ID of the default supervisor for users and groups in xMatters.
DEFAULT_COUNTRY_CODE The default country code to use when adding phone numbers to xMatters. 
DEFAULT_AREA_CODE The default area code to user when adding phone numbers to xMatters.
countryCodes

Used when loading fax numbers; associates international country dialing prefixes with ISO 3166-1 alpha-2 codes required by xMatters.

Default: Converts a dialing code of "1" to the country code "US".

ALLOW_ADD_USER

When set to false (default), the data load process allows both update and create.

When set to true, the data load process allows only update.

ALLOW_ADD_GROUP

When set to false (default), the data load process allows both update and create.

When set to true, the data load process allows only update.

DEFAULT_SHIFT_NAME Sets the name of the default shift for a group when the group is added to xMatters using the data load.
DEFAULT_SHIFT_DESC Sets the description of the default shift for a group when the group is added to xMatters using the data load.
  1. Save and close the file.
  2. Restart the Integration Agent. 

 To edit the data load dataSyncList.js file:

  1. Open the <IAHOME>\integrationservices\applications\casddataload-3-0-0\dataSyncList.js file in a text editor, and set the values for the following variables:
SYNC_ACTION Defines whether the users and groups specified in the syncList parameter (defined below) should be included or excluded in the data load.
USER_SEED_ONLY

If set to false (default), any modifications to a user in CA SDM will be synchronized with xMatters, overwriting any changes that may have been made to the user in xMatters. 

If set to true, users will be added to xMatters only during the initial data load, and not updated in subsequent data loads. 

GROUP_SEED_ONLY

If set to false (default), any modifications to a group in CA SDM will be synchronized with the group in xMatters, overwriting any changes that may have been made to the group in xMatters. Note that the update process preserves existing xMatters Team information, such as type and rotation settings, and the rotation order and delay settings for existing members. 

If set to true, group objects will be added to xMatters only during the  initial data load, and not updated in subsequent data loads. 

syncList

Defines the user and group names that should be excluded or included, as explained in the following sections. 

Note: If this list exceeds 50 entries, the process may fail due to a limitation in CA SDM. For more information and strategies on handling larger lists, see Specifying longer lists of users or groups to include/exclude.

  1. Save and close the file.
  2. Restart the Integration Agent. 

Data load sources and rules

The data load uses the following rules for creating and updating the individual properties of users and groups in xMatters:

  1. New objects are created from a combination of CA SDM object information and configured defaults provided by the configuration.js file.
  2. When an object in CA SDM is changed and the corresponding user or group in xMatters is updated via the batch data load:
    • Any properties that are populated with information from CA SDM are updated based on CA SDM information even if the property has been changed in xMatters.
    • Any properties that are populated with configured defaults are not updated, and any changes in xMatters will be preserved.

The following tables describe the source for the data used to populate the fields for users, groups and devices in xMatters.

User data

The data for user details in xMatters that is obtained from CA SDM is provided by the XM_CTM_People_WS web service which exposes fields belonging to CTM:People.

xMatters field Data source
Active CA SDM: deleteFlag
User ID CA SDM: userid
First Name CA SDM: first_name (or configuration file if not found)
Last Name CA SDM: last_name
User Devices CA SDM
Roles Configuration file OR CA SDM user roles
User Site Configuration file
Supervisors Configuration file
Externally Owned Configuration file
Web Login Type Configuration file
LDAP Domain Configuration file

Group data

The data loaded to xMatters for group details is provided by the CA Unicenter web service.

xMatters field Data source
Group Name CA SDM: last_name
Active CA SDM: deleteFlag
Externally Owned Configuration file

Device data

The data for device details in xMatters is provided by the CA Unicenter web service.

Note: For these devices to be loaded, you may need to add the device type or name into xMatters. For more information about adding device types and device names, contact xMatters Client Assistance, or talk to your Client Success Manager.

xMatters field xMatters device type CA SDM field
Work Email Email email_address
Pager Email Email pemail_address
Work Phone Voice phone_number
Home Phone Voice alt_phone
SMS Phone Text_Phone beeper_phone
Other Phone Voice fax_phone

The data load integration supports phone numbers with the following formats:

  • Local 7-digit numbers: 555 6473, 555-6473
  • 10-digit numbers: 212 555 6473, (212) 555 6473, 212.515.6473
  • 10-digit numbers preceded by a 1: 1 212 555 6473, 1 (212) 555 6473

The non-digit separators can be any number of non-digit characters, including white space, brackets, dashes, or periods; i.e., "(", ")", "-", "."', etc. Phone extension numbers are not supported.

For text and voice devices, numbers are processed during the data load as follows:

  • if the number in CA SDM is a 7-digit, the number is loaded to xMatters as:
    +<DEFAULT_COUNTRY_CODE><DEFAULT_AREA_CODE><CLEAN_PHONE_NUMBER>
  • if the number in CA SDM is a 10-digit, the number is loaded to xMatters as:
    +<DEFAULT_COUNTRY_CODE><CLEAN_PHONE_NUMBER>
  • if the number in CA SDM is 10-digit+1, the number is loaded to xMatters as:
    +1<CLEAN_10_DIGIT_NUMBER>

where <DEFAULT_COUNTRY_CODE> and <DEFAULT_AREA_CODE> are the values set in the configuration.js file, <CLEAN_PHONE_NUMBER> is the phone number value from CA without all non-digit characters and <CLEAN_10_DIGIT_NUMBER> is the phone number value from CA without the first 1 and all non-digit characters. 

Data load process

You need to run the data load script to initiate the batch data load process to transfer user and group information between CA SDM and xMatters. This instructs the integration to retrieve lists of qualifying users and groups from CA SDM and transfer them to xMatters.

Batch user data load

The USER_SEED_ONLY variable determines how users are treated when loading them into xMatters:

If the USER_SEED_ONLY variable is set to true:

  • If (user ID does not exist in xMatters) AND (user meets Batch Qualification criteria) AND [(user ID is not in excluded list) OR (user ID is in included list)]:
    • New user is created in xMatters
    • User information is populated
    • User devices are added to xMatters
  • IF (user ID already exists in xMatters):
    • No changes are made to any users or devices

If the USER_SEED_ONLY variable is set to false:

  • If (user ID does not exist in xMatters) AND (user meets Batch Qualification criteria) AND [(user ID is not in excluded list) OR (user ID is in included list)]:
    • New user is created in xMatters
    • User information is populated
    • User devices are added to xMatters
  • IF (user ID already exists in xMatters):
    • User information is updated
    • User devices are added to match settings in CA SDM

Note:

  • The integration is not able to change the user ID of xMatters users. If you change the Login ID of a user in CA SDM after the user has been transferred to xMatters, the next data load to xMatters creates a new user matching the new name of the CA SDM user. If you want to rename a user after they've been loaded to xMatters, make sure you rename them in both CA SDM and xMatters (the User ID in the web interface or targetName in the xM API) before performing the next data load. 

Batch group data load

The GROUP_SEED_ONLY variable determines how groups are treated when loading them into xMatters:

If the GROUP_SEED_ONLY variable is set to true:

  • If (group name does not exist in xMatters) AND (group meets Batch Qualification criteria) AND [(group name is not in excluded list) OR (group name is in included list)]:
    • New group is created in xMatters
    • Group attributes are added
    • New Shift is created in xMatters with the configured DEFAULT_SHIFT_NAME. If the DEFAULT_SHIFT_NAME is not "Default Shift", xMatters automatically creates a second shift named "Default Shift".
  • IF (group name already exists in xMatters):
    • No changes are made

If the GROUP_SEED_ONLY variable is set to false:

  • If (group name does not exist in xMatters) AND (group meets Batch Qualification criteria) AND [(group name is not in excluded list) OR (group name is in included list)]: 
    • New group is created in xMatters
    • Group attributes are added
    • New Shift is created in xMatters with the configured DEFAULT_SHIFT_NAME. If the DEFAULT_SHIFT_NAME is not "Default Shift", xMatters automatically creates a second shift named "Default Shift".
  • IF (group name already exists in xMatters):
    • Group attributes are updated
    • If a shift exists in the group with the configured DEFAULT_SHIFT_NAME, any added members are appended to the end of the shift without delays.
    • Otherwise the Group Roster is updated to include all added members.

Notes:

  • Group updates can modify team memberships, but maintain existing xMatters Shift information, such as type and rotation settings, and the rotation order and delay settings for existing members. 
  • If a CA SDM group has no members when it's transferred to xMatters, a group is created with a shift, but the shift has no members.
  • Renaming groups using the data load is not supported. If you change the name of a CA SDM group after the group has been transferred to xMatters, the next data load creates a new Group in xMatters matching the new name of the CA SDM group. If you want to rename a group after it's been loaded to xMatters, make sure you rename it in both CA SDM and xMatters (the group name in the web interface or the targetName in the xM API) before performing the data load.

Shift data load

Shift membership is updated in xMatters only as part of a batch update of CA SDM Support groups.

If the GROUP_SEED_ONLY variable is set to true:

  • If (Group name does not exist in xMatters):
    • New Shift is created in xMatters with the configured DEFAULT_SHIFT_NAME. If the DEFAULT_SHIFT_NAME is not "Default Shift", xMatters automatically creates a second shift named "Default Shift".
    • The Shift provides 24x7 coverage by default.
    • The Shift is comprised of only those Users in xMatters who are members of the group in CA SDM AND for whom "Assignment Availability" equals "Yes".
  • IF (Group name already exists in xMatters):
    • No changes are made

If the GROUP_SEED_ONLY variable is set to false:

  • If (Group name does not exist in xMatters):
    • New Shift is created in xMatters with the configured DEFAULT_SHIFT_NAME. If the DEFAULT_SHIFT_NAME is not "Default Shift", xMatters will automatically create a second shift named "Default Shift".
    • The Shift provides 24x7 coverage by default.
    • New Shift is comprised of only those Users in xMatters who are members of the group in CA SDM AND for whom "Assignment Availability" equals "Yes".
  • IF (Group name already exists in xMatters) AND (DEFAULT_SHIFT_NAME already exists in xMatters):
    • Shift with the name DEFAULT_SHIFT_NAME is updated.
    • Rotation and escalation settings, and ordering of existing team members in xMatters are kept. Any added members are appended to the end of the shift without delays.
  • IF (Group name already exists in xMatters) AND (DEFAULT_SHIFT_NAME does not exist in xMatters):
    • New shifts are not created.
    • All Users in xMatters who are members of the group in CA SDM AND for whom "Assignment Availability" equals "Yes" are added to the Group Roster.

Data load notification and logging

Following each data load operation, a summary of successful, successful with warning, and failed actions is written to the Integration Agent logs. You can also use the XMATTERS_ADMINISTRATOR and SEND_SYNC_SUMMARY variables in the configuration.js file to send a notification containing the summary to a user or group within xMatters.

The summary notification is FYI-only. User responses to the notification are not supported, and the integration does not support any annotations from the recipients of the notification or from xMatters concerning the delivery of the notification.

If the data load operation terminates before completion, a message is written to the Integration Agent logs indicating what happened. The contents of this string can be configured via the DATA_LOAD_EXCEPTION_LOG_MESSAGE in the configuration.js file. In this case, a summary notification is also sent to the configured xMatters user or group.

Validate the user and group data load

It's a good idea to test the data load process before you integrate it into your workflow. Use the following to test the communication between CA SDM and xMatters to make sure the data load is properly configured.

To test the user load:

  1. Review the contents of <IAHOME>\integrationservices\applications\casddataload-3-0-0\dataSyncList.js and the value of WHERE_CLAUSE_USERS in <IAHOME>\integrationservices\applications\casddataload-3-0-0\configuration.js.
    • The default configuration only processes updates to active CA SDM Contacts that have specific contact types.
  2. In CA SDM, create a new active user that meets the criteria of the configuration files, and assign them an email address.
  3. Change the dataSyncList.js settings to only include and add the user ID of the user you created in step 2.
    • For example, set SYNC_ACTION to include and add the user to the syncList.
  4. Navigate to the <IAHOME>\integrationservices\applications\casddataload-3-0-0 folder, and confirm the value of IAHOME in the xmattersDataload or xmattersDataload.bat file (depending on your platform) is correct.<ul
  5. If you installed the Integration Agent in a location other than the default installation folder, you will need to specify is location within the file.
  6. Run one of the following commands: 
    • Windows: xmattersDataload.bat load
    • Linux: xmattersDataload load
  7. Log in to xMatters and confirm that the user has been added, and has an Email Device with the correct address.

For additional information on the data load process, consult the Integration Agent's log file (AlarmPoint.txt), which includes a summary detailing any failures or warnings and their reasons.

Optimize the data load integration

There are some additional ways you can adjust or modify the behavior of the data load integration to best suit your deployment.

Map user roles

By default, the integration assigns the role defined in the data load configuration.js file to all xMatters users it creates:

var DEFAULT_XMATTERS_ROLES = ["Standard User"];

To assign a different role, or to assign multiple roles, to all new or updated users, you can modify the value of that variable to include a comma-delimited list:

var DEFAULT_XMATTERS_ROLES = ["Role 1", "Role 2];

You can also assign xMatters roles to a user based on the roles associated with CA SDM users.

To map xMatters roles based on CA SDM user roles:

  1. In the configuration.js file, set MAP_USER_ROLES to true:
      var MAP_USER_ROLES = true;
  1. In the roleMap section, edit the roleMap lines to reflect the mapping you want to implement, adding new roles using the format ["CA SDM Role"] = ["xMatters Role 1", "xMatters Role 2"]; 
    For example:
      1| var roleMap = [];
2| roleMap["Service Desk Manager"] = ["Group Supervisor"];
  3| roleMap["Help Desk user"] = ["Standard User", "Group Monitor"];
  1. Save and close the file.
  2. Restart the Integration Agent. 

Note how line 3 allows you to map a single CA SDM role to multiple roles in xMatters. Any number of these one-to-many mappings can be specified, but the configuration does not allow you to assign multiple CA SDM roles to a single xMatters Role in a single roleMap entry.

Note: Lines 2 and over can be modified, removed, or added to as needed, but do not remove or modify Line 1.

Change data load default values

The data load integration sets default values for some of the properties of xMatters users, groups, and devices. For example, users are assigned to the "US/Pacific" timezone and to the "Default site" by default.

The default values for any xMatters properties that are assigned in this way are defined in <IAHOME>/integrationservices/applications/casddataload-3-0-0/configuration.js and assigned to the associated xMatters object in the files and functions indicated below. 

Object File Function Details
User processUsers.js makeUserForAddUpdate() Sets User properties after a new User object is created by calling new User()
Device processUsers.js makeUserForAddUpdate() Sets property values for Devices other than Voice and Pager 
phonenumber.js setVoicePhoneOrPager() Sets property values for Voice and Pager Devices
Group processGroups.js makeGroupForAddUpdate() Sets Group properties after a new group is created by calling new Group()
Shift processGroups.js

makeGroupForAddUpdate()

 

Sets the property values for the Team created for Group objects
Team Member processGroups.js

makeGroupForAddUpdate()

Sets the properties for Team members after new GroupMember() is called

Change user device mapping

You can change how CA SDM devices are mapped to xMatters devices. The makeUserForAddUpdate() function within the processUsers.js file examines the "udsObject" object that describes the user details in CA SDM, and maps the user devices to xMatters. The code that does this for a given device is a code block that typically resembles the following:

     casdDeviceInfo = udsObject.email_address;
     syncDevice = new EmailDevice(user.targetName, "Work Email", DEFAULT_PROVIDER_EMAIL);
     syncDevice.isDelete = isEmpty(casdDeviceInfo);
     syncDevice.address = casdDeviceInfo;
     syncDevice.externallyOwned = user.externallyOwned;
     user.devices.add(syncDevice);

In this example, the CA SDM device "email_address" is mapped to the xMatters Work Email device. To change the mappings between devices in CA SDM and devices in xMatters, including a change to the name of the xMatters device, add to or edit the relevant code block for the device as needed.

Change data load process behavior

You can change the default data load process behavior so the process deletes the users and groups it is synchronizing before it re-adds them. 

NOTE: It is recommended that you keep this set to false unless you intend to delete specific loaded data from xMatters, you should always set this to false. When set to true, the data load process deletes all users and groups in xMatters that it is attempting to synchronize.

To change the data load process to delete then add:

  1. In the configuration.js file, set PROCESS_ADD_UPDATE to true:
      var PROCESS_ADD_UPDATE = true;
  2. Save and close the file.
  3. Restart the Integration Agent. 

Specify longer lists of users or groups to include/exclude

Using the dataSyncList.js file, the data load integration allows lists of users and groups to be excluded or included in the data load. However, if the list of users (or list of groups) contains more than approximately 50 entries, the resulting SOAP request to CA SDM will likely fail because of a limitation in CA SDM.

An alternative to limiting the lists is to add a parameter to the "WHERE_CLAUSE_USERS" variable in the configuration.js file; for example:

" ... AND (notify_method = 12345)";

A clause similar to the above would cause users to be included only if their CA SDM user record included the "xmatters" notification method. 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk