Administrator > Upload users > Modify the upload template file

Modify the upload template file

You can download a template file by clicking the link provided in the Upload step of the User Upload Wizard, or by using the Export Users feature to export a list of users in a correctly formatted file.

Depending on your version of xMatters, the template file will be one of the following versions, indicated by the header information in the first line of the file:

  • Version 1.1
  • Version 1.2
  • Version 1.3
  • Version 1.4
  • Version 1.5

To determine the version of user upload file you are using, open the exported users list or template file in a text editor; the version number is identified in the first line. Where applicable, the following instructions indicate the differences between the versions, and provide a description of how to convert an existing template to the latest version.

The template file includes comma-separated values in one of the following formats:

Data Import File Format Version 1.1:

Operation, User, First Name, Last Name, Site, User Supervisor, Work Email, Home Email, SMS Phone
 

Data Import File Format Version 1.2:

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

Data Import File Format Version 1.3:

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
 

Data Import File Format Version 1.4:

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

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. Note that some of the columns in version 1.2, 1.3, 1.4, and 1.5 are optional, depending on the specified operation. 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.

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 in version 1.3 format:

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
 
process, amunster, Arnold, Munster, Default Site, FALSE, Current, English, US/Eastern, ,Person Supervisor|Group Supervisor, amunster@company.com, amunster@home.com,5552092837, 555 2092838, 555 2092259
 
process, bnystrom, Bob, Nystrom, Default Site, TRUE, Expired, English, US/Eastern, amunster, Standard User|Person Supervisor, bnystrom@company.com,,5552092837, 555 2092838, 555 2094697
 

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.

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.

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.

User ID and names Yes Initial user ID (also becomes the web login ID), and first and last names for this user.
Site Yes Name must already exist for the associated company.
Externally Owned Status No

Not Available in version 1.1 or 1.2

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.

Password Status No

Not Available in version 1.1 or 1.2

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).

Language No

Not available in version 1.1

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.

Time Zone No

Not available in version 1.1

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 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
Role No

Not available in version 1.1 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.

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 the associated 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.

When assigning roles to users, note the guidelines and best practices defined in Consider user roles.

Last Login No

Not available in version 1.1, 1.2, or 1.3

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.

UUID No

Not available in version 1.1, 1.2, 1.3, or 1.4

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.

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).

To help ensure that users receive the xMatters account notification sent after data file processing, all email devices for each user will be set as default devices.

Devices No See the following section for information about device-specific formatting rules.
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).

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 will be 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

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

Note that from version 1.2 onward, you can enter a phone number in any format supported by the web user interface.

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 will be used.

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

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.

Numeric Pagers

There are two types of format accepted:

  • An ordinary phone number, following the same validation rules as voice devices.
  • A PIN, formatted as "PIN", followed by a space, followed by all digits. For example, "PIN 123456".

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.

Converting an existing user upload file

To convert a version 1.1, 1.2, 1.3, or 1.4 file to a version 1.5 file, open the file in a text editor (or as a CSV in spreadsheet program), and do the following:

  1. Change the version number in the file header to 1.5.
  2. If you are updating a version 1.1 file, after the User Supervisor column, add a Role column. Populate the column with at least one role for each user (separate multiple roles with a pipe ("|") character.

The values specified in the Roles column will overwrite all role assignments for existing users. If you are converting from 1.1 to a newer version and you add a Role column with "Standard User" specified for every user, uploading the file will remove all other roles assigned to existing users. For existing users, it is safer to use the Export feature on the Users page to create a new version 1.5 file and modify it as necessary.