Types of data synchronization errors

This section describes some errors that can occur during the data synchronization process. This does not list every possible error, but provides examples that can help you recognize the types of errors that can occur. Some of the errors listed in this section are detected by the EPIC command-line tool, and must be corrected before the data synchronization job can be started. Others may appear as errors in the synchronization report.

A required field is missing

Fields are required unless they are marked as optional.


The SITENAME field of the DS_SITES table is mandatory. If this value is missing, the data synchronization job is not submitted to xMatters until the error is corrected.

Data is in an invalid format

Some fields must use a predefined value or be formatted according to a specific xMatters format. If a field is not formatted correctly, it is not processed and generates an error.

The following field types use a specific format:
  • dates
  • country names
  • country codes
  • timezones
  • languages
  • phone numbers
The following fields use predefined values:
  • is_externally_owned
  • action
  • use_default
  • member type
  • status
  • The SITE_TIMEZONE field of the SITES table must be formatted according to xMatters timezone formatting. Using US/Pacific in this field is accepted, but using UTC−8:00 causes an error.
  • The IS_EXERNALLY_OWNED field must use the value Y or N. Typing T or F in this field causes an error.

Data refers to an invalid or nonexistent xMatters value

Some fields refer to an object that exists within xMatters.  These values may be configured uniquely for your xMatters company. If the object name is incorrect, or if the object is missing from xMatters, then importing the data generates an error. See your xMatters deployment to ensure that the system is configured with the expected values.

The following objects must be defined in xMatters:
  • sites
  • roles
  • device names
  • group names
  • user names
  • time zones
  • countries
  • Importing a user who has a custom role fails if the role has not already been created in xMatters.
  • Importing a new site fails if the country or time zone of the new site has not already been created in xMatters.
  • Importing a device fails if its device type does not exist in xMatters.

An object cannot be deleted

Some objects cannot be deleted, either because they are required or because they are being used by another object.

Objects that cannot be deleted include the following:
  • The last supervisor of a group.
  • The last active device of a user.
  • A site that has users.

Sometimes you must perform the data synchronization process more than once to delete an object. For example, you must run the data synchronization process twice to delete a site that contains users. The first time you run the process, the site is not deleted because it is processed before the users are deleted. The second time you run the data synchronization process, you can delete the site because the users have already been deleted.

Removing a nonexistent object is considered a success; this includes removing person supervisors for a nonexistent user.

An object cannot be created

You cannot create duplicate objects in xMatters. For example, if you attempt to create two users with the same user ID, the EPIC tool detects the error and does not submit the data synchronization job to xMatters.

A comma-delimited list or joined table contains an invalid value (partial failure)

A partial failure occurs when a list or joined table contains several valid values and one or more invalid values. For example, if a team contains a list of users, and all of the users except one can be found in xMatters, then the record generates a partial failure.

Lists and joined tables that can generate partial failures include the following:
  • The SUPERVISOR_LIST or OBSERVER_LIST fields in the DS_GROUPS.csv file.
  • The ROLE_LIST field in the DS_USERS.csv file.

If the SUPERVISOR_LIST field of the DS_GROUPS.csv file includes the values Person Supervisor, Group Supervisor, and Custom Supervisor, but your xMatters system only contains the roles Person Supervisor and Group Supervisor, then processing this value generates a partial error. The Person Supervisor and Group Supervisor roles are processed, but the Custom Supervisor role is not found and generates a partial error.