ZipSync file creation best practices

This section describes best practices transforming your system's data into the format required for the CSV files that comprise the ZipSync archive. This includes tips for data cleansing, mapping system data to xMatters fields, and creating fields in the appropriate order. Refer to ZipSync mode Included Files for specific details about the structure of the files in the ZipSync archive.

Create lookup tables

When you create CSV files for the ZipSync archive, you convert some of your system's values to predefined xMatters values, and provide supplementary information that does not exist in the source system. For example, you must convert time zones to xMatters time zones, and you may need to provide a list of xMatters roles for each user.

Create lookup tables to map the values from your system to xMatters values, and use these lookup tables to populate the fields of the CSV files. Microsoft Excel is a popular tool for creating lookup tables, because it is easy for non-technical personnel to use, and it can save files in formats that are readable by many ETL tools.

The following list describes some types of data transformations that may require lookup tables:

  • Maps of your system's location information to xMatters values for sites, countries, country codes and time zones.
  • Information about phone number dialing codes for each country. This can help you extract the one, two, or three-digit dialing codes from international phone numbers.
  • Information that is not present in the source system. For example, you may need to map user IDs to xMatters Roles and provide information about supervisor structures.

Example 1: The location data in your system contains state information, but does not store time zones. You can map each state to the corresponding xMatters time zone. Refer to this mapping to look up time zones for each state.

 
STATE_CODE STATE_NAME TIME_ZONE
AK Alaska US/Alaska
AL Alabama US/Central
AR Arkansas US/Central
AZ Arizona US/Arizona

 

Example 2: Your system contains international phone numbers that have one, two, or three-digit dialing codes. Map each country to its dialing code and the number of digits in each code. Refer to this table when you parse international phone numbers.

 
COUNTRY_CODE COUNTRY_NAME DIALING_CODE DIGITS TIME_ZONE
AD Andorra 376 3 Europe/Andorra
AE United Arab Emirates 971 3 Asia/Dubai
AF Afghanistan 93 2 Asia/Kabul
AG

Antigua and Barbuda

1 1 America/Antigua

 

Example 3: You want to assign roles to specific users, and there is no way to determine this automatically from your source system data. Map the user ID to a list of xMatters role, and refer to this mapping when you create the list of roles to assign to each user.

 
USER_ID ROLE_LIST
233881 Group Supervisor | Person Supervisor
238304 Developer
239503 Scenario Administrator | Scenario Supervisor

Create prerequisite fields first

It is helpful to create the CSV files in the ZipSync archive so that prerequisite fields are created before the fields that refer to them:

  • Create site definitions before you create user definitions, because each user refers to the site that they belong to.
  • Create user definitions before creating devices, custom values, user join attribute joins, Person Supervisors, groups and team memberships, because these fields refer to user IDs.
  • Create teams before team memberships.

To help avoid conflicts with prerequisites, create fields in the following order:

  1. Sites (optional)
  2. Users
  3. User join attributes
  4. User custom values
  5. Person Supervisors
  6. Email devices
  7. Text pager devices
  8. Voice devices
  9. Voice IVR devices
  10. Text phone devices
  11. Groups
  12. Teams
  13. Team memberships

Create the ZipSync archive

Specific instructions for creating the files in the ZipSync archive are located in ZipSync mode Included Files. Here are a few points to remember when you create the ZipSync archive:

  • Include the manifest file.
  • Include all of the files in the ZipSync archive, even if they do not contain any values.
  • Each field has a maximum length. You can find this information in ZipSync mode Included Files.
  • Enclose special characters in an escape sequence.
  • Include values for all of the fields that you want to preserve. When you leave blank spaces in the CSV files, those properties are deleted from xMatters.
  • When using international characters, the files must be saved in UTF-8 format without a byte order mark (BOM).

Data transformation best practices

Transform your system's data by removing invalid values, reformatting it, and converting certain values to xMatters predefined values.

Sites

Sites are xMatters physical locations, such as a city or an office. You can define sites during the data synchronization process, or you can use the site definitions that already exist in xMatters. Create sites to match company locations or user's home cities.

Follow these best practices when creating sites:

  • Create sites before creating users, because users refer to site values.
  • Convert time zones, language codes, country codes, and country names to predefined xMatters values.
  • Record sites that do not have country information and report them as errors.

Users

When you convert users in your system to xMatters users, you must specify which site each user belongs to. The site values must match the site names in xMatters.

You can assign each user a set of xMatters roles. If you do not specify a role, the user is assigned to the No Access User role, which enables them to receive notifications but does not allow them to log into xMatters. You may be able to assign roles to users based on the data in your source system. For example, you could assign the Group Supervisor role to all managers. However, if it is difficult to determine which roles to assign to each user based on the data in your system, you will need to create a lookup table that maps each user to their xMatters roles.

Follow these best practices when creating users:

  • Create sites before creating users, because users refer to site names.
  • Create user definitions before creating device definitions, custom values, user Attributes joins, Person Supervisors, groups and team memberships, because these fields refer to user IDs.
  • Ensure that every user has a unique ID.
  • Remove duplicate users.
  • Record users that do not have site information, and log them as errors.
  • Use a lookup table to map user IDs to a list of the xMatters Roles to assign to them.

User attribute joins

User attribute joins map users to their custom attributes. For example, a user could have the custom attribute "skills|First Aid".

Follow these best practices when creating user attribute joins:

  • Create users before creating user attribute joins, because user attribute joins refer to user IDs.
  • Ensure that Attributes are one of the custom attributes defined in xMatters.
  • Use a lookup table to map user IDs to a list of the xMatters custom attributes to assign to them.

User custom values

User custom values are custom field values associated with each user.

Follow these best practices when creating user custom values:

  • Create custom values after users, because custom values refer to user IDs.
  • Filter out empty custom values.
  • Truncate custom values to 98 characters.

Person supervisors

A person supervisor is a user that can add and edit other users.

Follow these best practices when creating person supervisors:

  • Create person supervisors after users, because person supervisors refer to user IDs.
  • Person supervisors may be left blank.
  • If a person supervisor is defined, the user ID must be for a user that has a role of Person Supervisor, Group Supervisor, or Company Supervisor. Typically, the person supervisor is set to the main administrator of the system who has the role of Company Supervisor.

Email devices

An email device is an email address that can receive notifications from xMatters.

Follow these best practices when creating email devices:

  • Create email devices after creating users, because email devices refer to user IDs.
  • Convert email addresses to lower case.
  • Remove whitespace from email addresses.
  • Ensure that the device name field refers to one of the device names defined in xMatters; for example, "Home Email", "Work Email".
  • Use an email validation program to check for invalid email addresses. If you do not have access to an email validation program, ensure that email addresses conform to the standards set out by Internet Standard RFC 3693. These standards includes some of the following rules:
    • Ensure email addresses match the format local-part@domain
    • Ensure email addresses do not exceed the maximum length.
    • Ensure there are no invalid characters in the email address.
      There are complex rules that define valid characters in email addresses. Quotation marks, UNICODE characters, and certain special characters may be included in some situations. Refer to RFC 3696 for details.
  • Record invalid email addresses and log them as errors.
Example email address conversion
Type of conversion Original Converted
To lower case Bob.Smith@myCompany.com bob.smith@mycompany.com
Remove whitespace      bob.smith@    mycompany.com bob.smith@mycompany.com

Invalid format

bob smith at mycompany dot com error

Voice and voice IVR devices

Voice devices are devices that can receive a phone call; for example land lines and mobile phones. Voice IVR devices are typically used for public address systems, and contain the same settings as voice devices. Convert phone numbers to xMatters format by stripping off the country dialing information and extracting the area code from the rest of the phone number.

Follow these best practices when creating voice and voice IVR devices:

  • Create voice and voice IVR devices after creating users, because voice and voice IVR devices refer to user IDs.
  • Country code values may be set to an xMatters country code or left blank. If the country code is left blank, xMatters automatically sets it to the country value of the corresponding site.
  • Ensure device names are selected from the device names defined in xMatters; for example, "Home Phone".
  • Remove white space from phone numbers.
  • Remove leading zeros from phone numbers.
  • Remove non-numeric characters, including letters, dashes, and parentheses from phone numbers.
  • Extract area codes from phone numbers. Note that area codes may be one, two, or three digits long, depending on the dialing codes of the country. You may want to create a lookup table that maps area code information to each country and refer to this table when you parse phone numbers.
  • Use a phone number validation program to verify that phone numbers actually exist.
  • Filter out invalid phone numbers and report them as errors.
  • Filter out phone numbers that do not have a user associated with them, and report them as errors.
  • When importing voice IVR devices, make sure that your system is already configured to use the voice IVR device type. If your system is not already configured, an administrator may need to add new user service provider and voice IVR device type.
Example voice phone number transformation
Country Original Area code Phone number Extension
US (424) 555-1414   424 5551414  
US +1 250 555 8393 250 5558393  
GB 148355555 1483 55555  
US 2505551414 x304 250 5551414 304

Text phone devices

Text phone devices are phones that can receive text messages.

Follow these best practices when creating text phone devices:

  • Create text phone devices after creating users, because text phone devices refer to user IDs.
  • Ensure the device name field matches a device name defined in xMatters; for example, "SMS Phone".
  • Country code values may be set to an xMatters country code or left blank. If the country code is left blank,xMatters automatically sets it to the country value of the corresponding site.
  • Ensure the phone number field includes an area code and phone number.
  • Remove white space from phone numbers.
  • Remove non-numeric characters from phone numbers.
  • Use a phone number validation program to verify that the phone numbers actually exist.
  • Filter out invalid phone numbers and report them as errors.
  • Filter out phone numbers that do not have an associated user, and report them as errors.
Example text phone number transformation
Country Original Transformed
US (424) 555-1414   4245551414
US +1 250 555 8393 2505558393

Text pager devices

Text pager devices are pagers that can receive text messages.

Follow these best practices when creating text pager devices:

  • Create text pager devices after creating users, because text pager devices refer to user IDs.
  • Ensure the device name field matches a device name that exists in xMatters; for example, "Pager".
  • Ensure the service provider name matches a service provider name that exists in xMatters.

Groups

Groups are a collection of teams and Schedules relating to a specific task or responsibility. All groups created and updated via EPIC are on-call groups; you can only create or modify broadcast groups using the web user interface or the xMatters REST API.

Follow these best practices when creating groups:

  • Create sites before creating groups, because each group can optionally specify a site to use for holiday information.
  • Create users before creating groups, because groups refer to supervisor user IDs.
  • Ensure the time zone field matches an xMatters time zone.
  • Ensure the observer list field is a list of xMatters Roles that can observe the group; for example, "Scenario Supervisor".

Teams

Teams are a set of users, devices, groups or other teams that are available during specific schedule times. After you define a team, create team memberships to specify which of these items are assigned to a particular team.

Follow this best practice when creating teams:

  • Create groups before creating teams, because each team belongs to a group and refers to group names.

Team memberships

Team memberships define an association between a team and the users, devices, groups and other teams that make up the team.

Follow these best practices when creating team memberships:

  • Create users, devices, groups and teams before creating team memberships, because team memberships refer to their IDs.
  • Ensure the member type field defines type of member; for example a person, device, team or group. The member type field must be one of the xMatters predefined fields; for example, "DEVICE".
  • Ensure the optional member subtype field is one of the predefined xMatters fields; for example, "VOICE".