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. We recommend you use an exported list of users as the template, especially if you have custom fields in your instance, and that you encode the file using UTF-8 to avoid potential problems with special characters in user names.

You can use the Export Users feature, available on the Users page in the xMatters web user interface to export a list of users in a correctly formatted file (see Export a list of users for more information).

The template file includes the following comma-separated values:

Data Import File Format Version 1.5:

Operation, User, First Name, Last Name, Site, Language, Time Zone, User Supervisor, Role, License Type, Work Email, Work Email Status, Home Email, Home Email Status, SMS Phone, Work Phone, Work Phone Status

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.

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. Supported device types are: EMAIL, VOICE, TEXT_PHONE, FAX, TEXT_PAGER. Mobile app devices must be added by the individual user and cannot be uploaded through the User Upload. For more information on adding mobile app devices, see Get the mobile app.

If you include additional device names, ensure you add a column directly after the device name called <Device Name> Status. You can set a device's status during an upload using the <Device Name> Status column by specifying whether the device should be ACTIVE or INACTIVE. When the file is processed, the status is applied to the device.

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

Operation, User, First Name, Last Name, Site, Language, Time Zone, User Supervisor, Role, License Type, Work Email, Work Email Status, Home Email, Home Email Status, SMS Phone, Work Phone, Work Phone Status, 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, License Type, Work Email, Work Email Status, Home Email, Home Email Status, SMS Phone, Work Phone, Work Phone Status
 
process, bnystrom, Bob, Nystrom, Default Site, English, US/Eastern, amunster, Standard User|Person Supervisor, STAKEHOLDER_USER, bnystrom@company.com, ACTIVE, bnystrom@home.com, ACTIVE, +1 6502530001, +1 6046605550;ext=42, ACTIVE
 
process, dpensky, David, Pensky, Default Site, English, US/Eastern, amunster|bnystrom, Standard User, FULL_USER, dpensky@company.com, ACTIVE, dpensky@home.com, ACTIVE, +55 5552092837, +55 55 52092838, INACTIVE

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.

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. If the file includes duplicate column header names, both columns are processed and the value in the second column used in the database. For example, if the first column in the file is a custom field and a later column in the file is a device, but both are named "Work Email", xMatters populates the database with the contents of the second column, which is the device type.

Duplicate column names are displayed as a warning in the Errors and Warnings table. It is recommended that you give each column header a unique name..

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 fields that are ignored by the upload process. Any changes to the information in the following fields is ignored and will not be applied to the user accounts in your instance: 

  • <Device_Name> Valid
  • Externally Owned Status
  • Last Login
  • Password Status
  • Status
  • UUID

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 User Properties No

Values for custom user properties will depend on the type of custom property. For example, values for Check Box properties will be "true" or false"; list values must match those defined for the list property's items.

Additional custom user property 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).
  • Specifying multiple values: For Multi-Select List properties, values must be delimited by a pipe character ( | ). It is possible to have a pipe delimiter in a property value but it must be escaped to appear in the list of values. For example, green|blue\\|red appears as green, blue|red.
Devices No See the Device-specific formatting section for information about device-specific formatting rules.
Email addresses No

If an email address is supplied for a user, it 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 is 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.
License Type No

The license type describes whether the user is a Full User, or a Stakeholder User.

Operation No

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

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 administrator roles.
  • The user creating the import job in the xMatters web user interface must have permission to assign the included roles.
Site No 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 Yes Initial user ID (also becomes the web login ID).
User Supervisor No 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.
Web Login ID No

An identifier used to log into a web site. You can change the web login ID from the default assigned by xMatters if the user requires a different ID for SAML (Security Assertion Markup Language) and SSO (Single Sign On).

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.