Legacy Upload Users Information

A new xMatters REST API-based User Upload feature is available for bulk upload and updating of user data. The Upload Users process is renamed to "Legacy Upload Users" and remains available until the feature is deprecated. This page contains information on using our legacy user upload, including:

The User Upload Wizard provides you with a fast and simple way to add information for many users into the system. The following diagram shows the high-level workflow for this feature: 

Each aspect of this workflow is described in User Upload Wizard. Before you begin creating upload jobs, consider the following requirements

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.

Define upload jobs

The Upload Jobs page allows you to add, manage, and monitor user upload tasks. This page provides at-a-glance information about all user upload data jobs, including their status, number of entries, when they were created, and who created them. You can add and remove jobs, as well as click job name links for more detailed information about a job's status.

The following table explains each possible value in the Status column of the Upload Jobs table:

User Upload Job Status Definitions
Status Meaning
NEW Job has been created (i.e., it has a unique name and roles have been associated with the users to be uploaded), but there is no data file associated with the job.
VALIDATED Job has been created and a data file is associated with it, but the data file cannot be processed.
SCHEDULED FOR PROCESSING Job has been validated, and is scheduled to be processed when the next scheduled processing occurs. By default, processing occurs hourly.
PROCESSING Job is currently being processed. The job cannot be deleted while in this state.
PROCESSED Processing has been completed, but users have not been sent a notification message.
NOTIFIED File processing is complete and all uploaded users have been sent a message with information about how to complete their xMatters account setup.
ClosedManage upload jobs
  • Delete a job by selecting its check box and clicking Remove Selected.
  • View more details for an existing job by clicking its link in the Name column.
  • Add a job by clicking the Add New link.

Remove a data file from an upload job

If you decide that you want to associate a different data file with a job, you can delete the data file without having to delete the job. Deleting the existing file allows you to add a new file to the job whenever you are ready to do so.

You can only delete jobs that are in the VALIDATED or SCHEDULED FOR PROCESSING state. If the file has already been processed, you will have to create a new job if you want to use a different data file.

ClosedRemove a data file
  • From the Data File Validation or Data File Processing page, click Delete File.
  • From the Upload Jobs page, click the name link of job, and then click Delete File.

User upload wizard

The User Upload Wizard allows you to create a new upload job and import users into xMatters by uploading a data file in comma-separated values format. Once you have added a new upload job, the wizard guides you through a four-step process to load your users into xMatters:

  1. Upload your data file
  2. Validate your data file
  3. Process your data file
  4. Notify users about their account

A template file is available in the first step of the of the User Upload Wizard (for more information, see Modify the upload template file).

If you do not have access to the User Upload Wizard, contact Customer Support to help you upload users into xMatters using this tool.

ClosedCreate the user upload job

When you create a User Upload Job for the first time, you must give it a unique name.

To create a new job:
  1. Click the Admin tab, and then click the User Upload menu item.
  2. On the Upload Jobs page, click the Add New link.
    1. The Add an Import Job page is displayed.

  1. Type a name for the job in the Name field.
  2. Click Save, which takes you to the Data File Upload Page.
    • If you are not ready to associate a file with the job, you can return to the page later to upload the data file.

ClosedUpload and validate the data file

Once you have added the upload job, you can associate a data file to it. If you are not already familiar with the required data file format, see Modify the upload template file.

To upload the data file:
  1. On the Upload Jobs page, click the name link of the job to which you want to add a data file.
  2. Click Browse and navigate to the file you want to upload (if necessary, download a data file template by clicking the provided link).
  3. Click Upload to validate the file.

  1. After the file has validated, do one of the following:
    1. If the file validated without errors, click Continue to process the file.
    2. If there were validation errors, address the errors and try uploading the file again (for assistance, see Troubleshooting user upload errors and warning messages).
    3. If there were validation errors and you still want to process the Users, click Continue to process the file.

ClosedSchedule for processing

You must wait until the file is processed before you can send a notification message to the new users. By default, processing occurs hourly. If you need to change the processing interval, contact your xMatters representative.

To monitor data file processing:
  1. Check the related job's status in the Upload Jobs page.

  1. Periodically refresh or return to the Upload Jobs page to see whether the job's status has changed to PROCESSED.

  1. Click the job's name link to check for processing errors.

  1. Click Continue to advance to the User Notification page.
ClosedSend a notification message to users

After the data file has been validated and processed, the next step is to send new users a notification that includes explanatory text and a URL to access their account. This allows users to start self-managing their information (devices, web login password, etc.) immediately.

The Message Body field includes a default message that you can edit as required. The message is pre-populated with the login page specified by the WEBSERVERURL Global Constant (only super administrators or xMatters hosts have access to this setting).

To help ensure that users receive the notification, all email devices for each user are set as default devices during the import. Once you have made the necessary modifications, including replacing placeholder text with actual values, click Send Message. Users have 36 hours to change their web login password.

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

ClosedAccess the data upload template file in the User Upload Wizard
  1. On the Admin tab, click User Upload in the Configuration menu.
    1. xMatters displays the Upload Jobs page.
  2. Click Add New.
  3. Type a name for the import job and click Save.
  4. On the Data File Upload page, click Click here to save or open the Data Import template file.

ClosedExport a list of users to use as a template

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

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 User Upload.
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
  • 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.

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

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.

Troubleshoot user upload validation errors

This section describes how to deal with common validation errors in the user upload wizard. After making the suggested changes in a text editor, try to import the new users again through the wizard.

The following table summarizes validation errors that may occur while uploading user data, and provides troubleshooting guidance (angle brackets "<>" are placeholders for the actual values):

User Upload Wizard Validation Error Messages
Validation Error Messages Suggested Action
Data import file version information missing or incorrect. Indicates that the first line (i.e., that is not commented out or blank) of the data file is missing or incorrect. The first line of the file should be similar to the following, where "X.x" represents the correct version number: "Data Upload File Format Version: X.x". Ensure that this is the first uncommented or non-blank line, and that it contains the correct version number.
Column <column_name> does not have a header. Add an appropriate header for the specified column (see the sample template file for guidance).
Header is duplicated in columns <column_name> and <column_name>. Remove one of the specified column headers.

Column header in position <position_number> does not match any company device or any custom field.

 Replace the specified column header with an appropriate header (see the sample template file for guidance).
Mandatory column header <column_header> expected in column <column_name>. Add the specified mandatory column header, or replace an existing header with the mandatory header. The following columns are mandatory: Operation, User. If any users are being added or updated, it is also necessary to add First Name, Last Name, and Site. Finally, added users require at least one valid email device.
No column header matches a configured email device. Ensure that at least one column header matches the name of a configured email device.
User <User> is duplicated in an earlier line. Remove one of the rows in which the user value is duplicated.
Line does not contain any email values (at least one email device must be configured for each User). Remove the line, or add an email device for the user in the specified line. (At least one email device must be specified for each new user so that xMatters can send them a message with instructions and a link for setting up their new account.)

Device type is not supported in the User Upload Wizard (only the Email, Voice, Text Phone, and Text Pager Device types are supported).

 Remove the unsupported device type or replace it with a supported type.
Line has more values (<number_of_values>) than the number of column headers (<number_of_
headers>).		 Indicates there is a mismatch between the number values in a line and the number of column headers for the line. Remove any extra values for the specified line.
Mandatory value is not present in line. Modify the specified username, or remove its line from the user Upload file.
Value exceeds the maximum length of <number> characters. Modify the specified value so that it is within the maximum character limit.
Line has Site value <Site_value> that does not exist in the database. Correct the spelling of the Site name, or replace the specified Site value with a Site that exists in the database.
The email address is invalid. Ensure that the specified email address is properly formatted and does not contain special characters that are not allowed (e.g., #, $, &).
Phone has an invalid number (phone numbers must be in the following format: <area code> <phone number>. Ensure that the specified phone number is properly formatted and does not include extra spaces or dashes. For example, the following are valid: 5555555, 555 5555555.
Number is not valid (only digits and spaces are allowed). Ensure that the specified number includes only digits and spaces.
Submitted ZIP file contains more than one data file. For storage purposes, xMatters creates an archive (ZIP) file for each data import file. However, each archive must include only one data file. If you receive this error, contact your xMatters Administrator.
Could not create the parent folder <folder_name>. xMatters was unable to create a parent folder for the data import file (e.g., due to a server problem, network issue, etc.). If you receive this error, contact your xMatters Administrator.
Could not access import data file <import_data_file_name>.

xMatters was unable to access the data import file (e.g., due to a server problem, network issue, etc.). If you receive this error, contact your xMatters Administrator.
Value is mandatory for this field. Add the mandatory Custom Field value for each user.
Value must be "true", "false", "yes", or "no". Modify the Custom Field value to one of the specified values.
Value does not exist in the list choices. Specify an existing list value for the Custom Field.
Value length must be between <lower_number> and <higher_number>. Modify the length of the Custom Field value to be within the specified range.
Value must be between <lowend> and <highend>. Modify the Custom Field value to be within the specified range.
Value cannot be parsed to an integer. Modify the Custom Field value to an Integer.
Value cannot be parsed to a decimal. Modify the Custom Field value such that there is at least one digit on either side of the decimal point (e.g., 1.2).
Row must have at least an operation (remove or process) followed by a user. Ensure that their is an operation of remove or process specified for this user, as well as the associated user ID.
Operation must be either 'remove' or 'process'. Ensure that their is an operation of remove or process specified for this user.
Row with 'process' operation needs values for the following fields (in order): <field_list> Ensure that the specified rows have valid values.
Cannot find user to remove. You cannot delete the user because they do not exist in the system. This may be due to an incorrect user ID (i.e., a typo), or the user may have been previously removed. Correct the typo or remove the user from the file.
Cannot remove the last Company Admin. You cannot delete the last Company Administrator for a Company. Remove this user from the file.
Cannot remove the last Super Admin. You cannot delete the last Super Administrator from the system. Remove this user from the file.
User Supervisor has not been specified; <currently_logged_in_User> will be used. If a user supervisor is not specified, the currently-logged-in user will be assigned as the user supervisor.
User Supervisor is invalid as it is going to be removed. This is a warning that although the user will be deleted, you should be aware that they are a user supervisor of another user.
User Supervisors are invalid as they are going to be removed: <position_list>. This is a warning that although the users will be deleted, you should be aware that they are user supervisors of another user.
Specified User Supervisor is not a valid User: <position_list>. Specify a valid user as user supervisor.
Specified User Supervisors are not valid: <position_list>. Specify valid users as user supervisors.
User cannot be their own User Supervisor: <position_list>. Specify a valid user supervisor other than the user.
<UserID> is specified as the supervisor for one or more users, but does not have the required permission (ability.act.PersonSupervisor).

Specify a valid user as user supervisor, or assign the specified user the required permission to supervise users.
Import job has more than <number> lines; use 10,000 or fewer lines per job. Break the import job into parts that include 10,000 or fewer lines.