Standard CSV Fields

The following table summarizes fields that are common to most of the of the included CSV files:

Standard CSV Fields

Field Name

Description

action

Specifies the action to take on the record on the next synchronization (see the "action Field" section below for valid values).
is_externally_owned Controls the ownership of the synchronized object. This flag provides instructions for the xMatters web user interface. Expected value is Y or N (see the "is_externally_owned Field" section below for details); typically, this is set to "Y".

external_key

Unique identifier for all tables, except Membership tables (see the "external_key Field" section below for details).

The following sections discuss each standard field in more detail.

action Field

The action field specifies the action (i.e., processing or removal) that should be performed on the record during synchronization. Prior to processing, the action field should be set to one of the following values (if it is not set to one of these values, the row will be ignored):

User Values for the action Field

Value

Description

Y

Specifies that this record should be processed. If a matching record exists in the system, that record is updated to match this record. If no match exists, a new record is inserted.

R

Specifies that this record should be removed from the file. If a matching record exists in the system, it is removed. If no match exists, no action is taken. When ZipSync is set to mirror data, this row will be ignored (for details on mirroring, see The manifest.xml file).

Note: this action completely removes the User’s Details, Devices, and Team Memberships from the file, even if there are active notifications or scheduled escalations for the User in the system.

During processing, the action field for records matching the latter values are set to one of the following values:

  • is_externally_owned
  • external_key

The following sections discuss these values in detail.

is_externally_owned Field

xMatters objects have an associated ownership. xMatters can own objects (i.e., internal ownership) or they can be owned externally. This flag specifies the ownership type for this synchronized object (value is “Y” or “N”; typically set to "Y"). When objects are in an externally owned state, you can use the External Data page in the xMatters web user interface to control which externally owned data fields Users can change.

For more information about working with externally owned fields, see External ownership and locking.

You cannot use the web user interface to remove objects that have been synchronized as externally owned.

external_key Field

The data synchronization process uses the external_key field to identify the record in the xMatters CSV file that matches this record (the external_key value must be unique within the file). Because this comparison is case sensitive, performing case-insensitive comparisons requires that strict case consistency be used when inserting or changing records.

In general, synchronization matches and updates system elements against existing data by attempting to find a matching entry in the production database with the same external_key. However, the following applies for Sites, Users, and Devices:

  • Site: synchronization first attempts to match a Site with the same name (case-insensitive) in the Company; if not matched, the external_key is used.
  • Users: synchronization first attempts to match a User with its targetname (i.e. the User ID displayed in the web user interface), comparing it against the incoming USER_ID field; if not matched, the external_key is used.
  • Devices: synchronization first attempts to match a Device whose User's targetname matches USER_KEY, and whose Device name (e.g., Home Email, Work Email, Mobile Phone) matches DEVICE_NAME; if not matched, the external_key is used.

The external_key field is also used to establish relationships between records. As a result, to specify a User as a Group Supervisor, that User’s external_key value must appear in the Group Supervisor list. It is also used to determine whether the row in the system was created from an import (i.e., this is used with the mirror setting described in The manifest.xml file).