Modify the upload template file

You can download the User Upload Template v1.5 file by clicking here, or by using the Export Users feature to export a list of users in a correctly formatted file.

The template file includes the following comma-separated values :

Data Import File Format Version 1.5:

Operation, User, First Name, Last Name, Site, Externally Owned Status, Password Status, Language, Time Zone, User Supervisor, Role, Last Login, UUID, Work Email, Home Email, SMS Phone, Work Phone

When there is no data for a given value, include commas for the missing information to ensure that the remaining data is imported in the proper order. For details, see Additional formatting information below.

The downloadable template file is static; it does not automatically adapt to the device names configured for your xMatters deployment. If you want to add different device names, you must modify the file manually.

You can also add custom fields that have been defined in your xMatters deployment to the template. For example, if you have a custom field named "Location" you could modify the sample template file as follows (for details, see the table below):

Operation, User, First Name, Last Name, Site, Externally Owned Status, Password Status, Language, Time Zone, User Supervisor, Role, Work Email, Home Email, SMS Phone, Work Phone, Location
 

Example

The following lines represent the "column" headers and two rows of sample import data:

Operation, User, First Name, Last Name, Site, Language, Time Zone, User Supervisor, Role, Work Email, Home Email, SMS Phone, Work Phone
 
process, amunster, Arnold, Munster, Default Site,English,US/Eastern, ,Person Supervisor|Group Supervisor, amunster@company.com, amunster@home.com, +1 6502530001, +1 650 2530002
 
process, bnystrom, Bob, Nystrom, Default Site,English,US/Eastern, amunster,Standard User|Person Supervisor, bnystrom@company.com,bnystrom@home.com, +1 6502530001, +1 650 2530002 ext: 24
 

In some cases, validation fails when the file contains special characters or accents such as those used in French. To avoid these issues on Windows, always use Notepad (and not Excel) to save the file in Unicode format. If you are editing the file on a Mac, always use TextEdit to save the file in UTF-8 format.

If you export a list of users from the xMatters user interface, the file is automatically formatted to work with the legacy User Upload Wizard. To use the file with the User Upload feature:

  1. Open the exported file in Excel.
  2. Make modifications to the file as required.
  3. Delete all columns titled {Device} Status and {Device} Valid. For example: Android Status, iPhone Valid.
  4. Save and close the file in Excel.
  5. Windows users only:
    1. Open Windows Explorer and go to the location of the saved file.
    2. Rename the file to have a ".txt" file extension.
  6. Upload the text file as described above.

Resolve naming conflicts

During an upload, xMatters uses the column headers of the data file to parse the data and propagate it to the proper database location. As a result, the file cannot include duplicate column header names (i.e., because xMatters cannot determine the intended database destination for the data). For example, if a custom field and a device are both named "Work Email", xMatters will be unable to determine whether the related column values should be associated with the custom field or the device.

If your xMatters deployment has duplicate names across devices and custom fields, you will not be able to access the features of the Upload Jobs page. Instead, the page will display an error message and a table identifying each naming conflict. To resolve these conflicts, it is recommended that you rename the custom field names that conflict with the device names.

Consider user roles

Consider the following best practices when associating roles with the users that will be uploaded:

  • Associate only the roles that a given set of users will need to interact with xMatters. For example, most users will not need the permissions associated with the Group Supervisor role; the more basic permissions of the Standard User role are often adequate for most users in a typical xMatters deployment.
  • It is recommended that you limit the number of different roles to only those required in your deployment. For example, if you plan ahead to determine who your group supervisors will be, you may find that the vast majority of users should be given only the Standard User role.
  • Before uploading users, divide them into categories based on which roles they will have. Then, create a separate job for each distinct category or set of roles. For example, a unique user upload job might consist of users who will have the following three roles: Standard User, Group Supervisor, and Scenario Initiator. Another job might include users who will have only the Standard User role.

Additional formatting information

If the file you are using is generated by exporting the list of existing users, it will contain additional fields that are ignored by the upload process (such as externally owned status and password status).

The following table provides additional general and specific formatting information for the data file:

Data File Element Mandatory Formatting Guidelines

All fields

N/A

Note that all fields have a maximum length of 100 characters.

Custom Fields No

Values for custom field elements will depend on the type of custom field. For example, values for Boolean custom fields will be "true" or false"; list values must match those defined for the custom field list.

Additional custom field value formatting rules:

  • Leading and trailing whitespace: ignored (unless the value is delimited with double-quotes, in which case the whitespace is preserved.
  • Embedded commas: acceptable, but value must be delimited with double-quotes (e.g., "Value 1, With a comma").
  • Embedded double-quotes: acceptable, but double-quote characters must be doubled, and the field must be delimited with double-quotes (e.g., "Value 2, With ""A Double Quote""").
  • Delimiters parsed and discarded: value may always be delimited with double quotes; delimiters will be parsed and discarded (e.g., "London" will be read the same as London).
Devices No See the following section for information about device-specific formatting rules.
Email addresses Yes

At least one email address must be defined for each new user.

Addresses must follow the Internet Standards RFC specification; typically, <alphanumeric_characters>@<domain_name> (e.g., bsmith@company.com).

Externally Owned Status No

Values include: TRUE or FALSE.

This field is used only by the export users function; any content in this field will be ignored during the import process.

In an exported users list, this field indicates if users are externally owned and synchronized into xMatters.

First Name No

The first name of the user. If no first name is provided in the upload file, a default value of "First" is assigned.

Language No

Must be a valid, enabled language for the associated company. If this entry exists for any User, it must exist for all Users.

If you are adding a user or modifying a user's site and this entry does not exist, the site defaults will be assigned for this user.

Last Login No

The last date and time the user logged into the xMatters user interface. For example: 2015-07-30 14:40:20 PDT. This field is used only by the export users function; any content in this field will be ignored during the import process.

Last Name No

The last name of the user. If no last name is provided in the upload file, a default value of "Last" is assigned.

Operation Yes

Valid values are:

  • process: specifies that the user should be added or updated based on the values in the associated fields; information in the upload file will overwrite existing User information only if the upload information is different.
  • remove: specifies that the user should be deleted from the system

Note: if an existing user is being updated via the process operation, empty fields for custom fields will be cleared except where not permitted (e.g., when the custom field is Boolean); and, empty device fields will delete the associated device.

Password Status No

Values include: Current, Unset, or Expired.

This field is used only by the export users function; any content in this field will be ignored during the import process.

The Password Status field is not relevant for users using external authentication (such as SAML or LDAP).

Role No

Note that if you are adding any Users, this column must be present.

A list of roles to assign to the user, delimited by the pipe ("|") character (e.g., "Person Supervisor|Standard User"). If this entry exists for any user, it must exist for all users. If the Role for a user is left blank, the user is assigned the No Access User role.

Note the following conditions that must be met for each added or removed role if you are adding a user or modifying an existing user's roles:

  • The role must exist within your company.
  • You cannot use this feature to add or alter "Company Admin" or "Super Admin" Roles.
  • The user creating the import job in the xMatters web user interface must have permission to assign the included roles.
Site Yes Name must already exist for the associated company.
Time Zone No

Must be a valid, enabled time zone for the associated company. If this entry exists for any user, it must exist for all users.

If you are adding a user or modifying a user's site and this entry does not exist, the site defaults will be assigned for this user.

User ID and names Yes Initial user ID (also becomes the web login ID), and first and last names for this user.
User Supervisor Yes A list of user IDs of user supervisors for this user, delimited by the pipe ("|") character (the specified user IDs must already exist in the system). For example: bsmith | mmcbride
UUID No

The Universally Unique ID (UUID) of the user. This field is used only by the export users function; any content in this field will be ignored during the import process.

If you use the User Export file to upload users with special characters in their names into xMatters, you may need to save the file in Excel with UTF-8 encoding for the special characters to be displayed correctly.

Device-specific formatting

The following sections identify how to format and include properties for different device types.

Voice Devices

Numbers must be in one of the following formats: <area code> <phone number> OR +<country code> <area code> <phone number> (e.g., 789 5551234, +1 789 5551234). Note that if no country code is specified, the associated xMatters Site's country code is used.

The following numbers represent example numbers for the indicated jurisdiction:

  • North America (phone number): 555 5551212, +1 555 5551212
  • UK land line: 1234 567890 OR +44 1234 567890 (however, London's area code has only three digits (020) and prefixes the main number with 7 or 8 (e.g, 20 7112345)).
  • UK mobile: 11234 567890 OR 11234 567890 OR +44 11234567890
  • Australia (phone number): 4 55556666, +61 4 55556666

These examples are not meant to be exhaustive; check with your service provider for full format details.

Text Phones

Numbers must not start with zero, and must be in one of the following formats: <area code> <phone number> OR +<country code> <area code><phone number> (e.g., 5555551212 OR +1 5555551212). Note that if no country code is specified, the associated xMatters Site's country code is used.

  • North America SMS: 5555551212 OR +1 5555551212
  • UK SMS: 7777123456 OR +44 7777123456
  • Australia SMS: 455556666 OR +61 455556666

These examples are not meant to be exhaustive; check with your service provider for full format details

Fax Devices

The number validation for fax devices follows the same rules as the web user interface. The import will accept a string of digits or a country code, preceded by a plus ("+") sign, followed by a space, followed by the remaining digits. No spaces, parentheses, or other characters are allowed.

Text Pagers

This is the only device type that accepts a specified provider. The format must be as follows:

<provider> - <digits>
 

For example, "Bell South - 1234567".

If you do not specify a provider, the only acceptable format is a string of digits (no special characters or symbols). If you do not specify a provider and it is a new device, the first acceptable provider (alphabetically by name) is assigned.