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:
- Sites (optional)
- Users
- User join attributes
- User custom values
- Person Supervisors
- Email devices
- Text pager devices
- Voice devices
- Voice IVR devices
- Text phone devices
- Groups
- Teams
- 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.
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.
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.
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".