Troubleshoot synchronization report errors

A single error in a field or row can trigger a cascade of error and warning messages in the synchronization report. When an object fails to be created, other objects that refer to it also fail to be created, generating more errors. This process can cause a large number of errors to be generated from a single failure. This section contains some tips for identifying cascading error messages and finding the original source of the error.

Consider the case where you make a typo in a site name. The site is then created in xMatters with the incorrect name. The users for this site cannot be created because they refer to the correct site name, which does not exist. This causes error messages to be generated for each user at the site. The objects that refer to these users (supervisors, groups, devices, teams, and so on) also fail to be created, because the corresponding users do not exist. This generates even more error messages. In short, the single typo in the site name triggered a cascade of error messages for many different objects, including users, devices, supervisors, groups, teams, and more.

To clarify the source of a cascading error, apply the following tips:

  • Begin by examining the tables that were processed first. Try to fix errors that occur at the beginning of the data synchronization process first, because they are most likely to contain the root cause of an error. Errors that occur later in the synchronization process are more likely to be cascading errors. Start with the sites table, and then inspect users, devices, custom fields, and so on.
  • Start investigating errors at the bottom of the detailed synchronization report, and work your way up. The real errors tend to be located at the bottom of the detailed synchronization report, and the cascading errors are detected later and appear closer to the top of the report.
  • Look at field warnings and errors before row warnings and errors. If a field fails, it will generate an error in the row as well. The field-level error message contains more detailed information about the error than the row-level error message.
  • Ignore errors that do not have error messages. The errors that do not have error messages are likely to be repeated or secondary errors. Focus on the errors that have error messages.
  • Look for a common factor when there are a lot of similar errors. If there are a lot of similar errors, it is likely that they are cascading errors that were triggered by an error somewhere else. When you find a large number of similar-looking errors, see what they have in common and look for errors with their common element. For example, if there are hundreds of users that fail to load because they refer to a missing site, it is more likely that there is an error with the site than with each of the users.

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.

Example

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
Examples
  • 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
Examples:
  • 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.
  • The PERSON_SUPERVISOR_LIST field of the DS_PERSON_SUPERVISORS.csv file.
  • The DS_USER_JOIN_ATTRIBUTES table.
  • The DS_CUSTOM_FIELD_JOIN_VALUES table.
Example

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.