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