User Import Application

To download Community files linked to the documentation site, make sure you're logged in with your valid Relativity Community credentials.

If you're not logged in:

  1. Click the Community file link.

  2. Enter your credentials on the Community login screen that appears.

  3. The file will download to the bottom left corner of your screen.

If you're already logged in:

The file will download automatically to the bottom left corner of your screen when you click the link.

If you encounter a "URL No Longer Exists" error after clicking a Community link, it might signal a single sign-on error related to the SAML Assertion Validator. Reach out to your IT department for assistance.

The Relativity User Import Application allows you to efficiently manage multiple users: import them from CSV files, including their Relativity settings, and export lists of them with their settings for backup or transfer.

This page contains the following sections:

Before you begin

Supported Versions

This solution is supported in Relativity 9.4 and above. Click a link in the Solution version column in the following table to download this solution from the Relativity Community. Make sure that you select a solution version supported by your Relativity version.

Solution version Relativity version
20.4.5.1 RelativityOne
20.3.24 Server 2022
19.3.1 Server 2021

Category

The Relativity User Import Application includes the following components:

  • Agents
  • Event handlers
  • Custom pages

Special considerations

Passwords and Authentication:

  • Passwords are not imported or exported. Imported users with default password providers must use the "Forgot your password?" link to create a new password.

  • Only Default Password Provider and Default Integration Authentication Provider are supported. Other authentication types won't be imported or exported.

  • System Administrators can restrict password resets for imported users by setting the "CanChangePassword" column to "FALSE" in the import file.

Login Methods:

  • Unsupported login methods (e.g., Default RSA Provider) are not imported or exported. Users with unsupported methods will be imported without login methods and must use the "Forgot your password?" workflow to create a new password.

Partial Imports and Errors:

  • Partial imports indicate a user creation step failed. Validate the user's information and login methods, update as needed, or remove and retry the import.

  • Worker queue records are removed as job errors are recorded. The total imported/exported records may not be accurate until job completion.

Other Considerations:

  • Relativity Admin and Service Account cannot be imported.

  • Install the application in only one workspace.

  • Import files require header rows with populated values.

  • Relativity blocks imports of existing users.

  • Missing destination groups for imported users will cause errors. Create groups before importing.

  • Duplicate group names: Users are imported into the first duplicate group.

  • All users are added to the "Everyone" group, even if the group column is blank in the import file.

  • Empty "Trusted IP" fields for users invalidate the "Outside Trusted IPs" setting for two-factor authentication.

  • Uninstalling the application:

    • Disables manually created agents due to removed tables.

    • Deletes database tables, queue records, and existing jobs.

Custom Components and Support:

  • Custom components may not perform or behave identically to native Relativity features.

  • Solutions are thoroughly tested but are not considered core features and have a different level of support than the Relativity platform.

Deploying and configuring the solution

To deploy and configure the solution, you must first add it to the Application Library as a Relativity application. You can then install and configure the solution in a workspace.

Note: Note: Only install the Admin Migration application to one workspace in your environment.

To add the application to the Application Library:

  1. Log in to Relativity.
  2. Click the user drop-down menu in the upper-right corner of Relativity, then click Home.
  3. Click the Applications & Scripts tab, then click the Application Library tab.
  4. Click Upload Application.
  5. Click Browse, navigate to and select the .rap file, and then click Open.
  6. Click Save.

Preparing the workspace

After you add the application to the Application Library, you’re ready to install and configure it in a workspace by performing these basic tasks:

  • Install the solution application to a single workspace from the Application Library.
  • Create manager and worker agents.

Installing the application

To install the Relativity application in the workspace:

  1. Click the user drop-down menu in the upper-right corner of Relativity, then click Home.
  2. Click the Applications & Scripts tab, then click the Application Library tab.
  3. Click the name of the User Import Application.
  4. Under Workspaces Installed, click Install.
  5. Click next to Workspaces.
  6. Select the destination workspace and click Ok.
  7. Click Save.

Export utility job

You can create and run an export utility job from the Export Utility Job tab in the workspace where you installed the application. Within that workspace, create and run an export utility job by completing the following workflow:

  1. Click New Export Utility Job.
  2. Complete the following fields:
    • Name - enter a name for your export job.
    • Object Type - select User.
    • Priority - (optional) enter a priority for your export job. The lower the number, the higher the priority. Negative numbers are acceptable.
    • Confirmation notification - enter a comma delimited list of email addresses to send a notification to once the export utility job completes.
  3. Click Save.
  4. From the Manage Export Job console, click Submit.
  • Once you click Save, the Status section populates with the following information:
    • Status - the status of the export utility job.
    • Created On - the date and time the export utility job was created.
    • Created By - the name of the user who created the export utility job.
    • System Last Modified On - the date and time the export utility job was last modified.
    • System Last Modified By - the name of the user who last modified the export utility job.

    After you click Submit, Relativity agents begin processing your export utility job. The Progress section populates with the following information:

    • Expected - the expected number of users to be exported.
    • Records That Have Been Processed - the number of users whose data has been prepared for export. This number is updated as the page refreshes.
    • Exported - the number of users exported in the export file.
    • Not exported - the number of users not exported in the export file.

    Click Cancel to stop the job from running. You can monitor the manager and worker agents from the Queue tab. For more information, see Viewing the Queue tab.

    Once the agents finish the export, Relativity populates the Export File field on the export utility job with a CSV file that contains a list of users and their Relativity settings for the object type you specified. Click the file name to download your export file.

    Viewing export errors

    You can view export errors on the Export Utility Job Errors tab. Errors are also linked to your export utility job.

    Import utility job

    You can run an import utility job from the Import Utility Job tab. To run an import utility job, complete the following workflow:

    1. Click New Import Utility Job.
    2. Complete the following fields:
      • Name - enter a name for your import job.
      • Object Type - select User.
      • Note: Once you select an object type from the drop down, click Download User Template to download a template you can populate with the user data you want to import.

      • Priority - (optional) enter a priority for your import job.
      • Note: To import an import file generated by the Relativity User Import Application (RUIA) in a version of Relativity below Relativity 9.4, see Importing users from Relativity 9.3 and below.

      • Import File - select the object file you want to import. You can also select the template you downloaded and populated with your object data. For more information, see User Import Application.
    3. (Optional) Under Confirmation Notification, enter any email addresses that you want to send a confirmation notification to once the import completes. Separate each entry with a comma.
    4. Click Save.
    5. (Optional) Click Validate to validate your import file before you import your users. If there are any errors, you can view them in the Errors section and on the Import Utility Job Errors tab. For more information, see Viewing import errors.

      Note: Validating the import file does not automatically submit it. You must click Submit after validating the file to import users.

    6. Click Submit to validate and import your file. Clicking Submit validates file against user information in Relativity.

    Once you click Save, the Status section populates with the following information:

    • Status - the status of the export utility job.
    • Created On - the date and time the export utility job was created.
    • Created By - the name of the user who created the export utility job.
    • System Last Modified On - the date and time the export utility job was last modified.
    • System Last Modified By - the name of the user who last modified the export utility job.

    After you click Submit, Relativity runs your import job. Click Cancel to stop the job from running.

    Progress

    • Expected - the expected number of users to be imported.
    • Imported - the number of users imported via the import file
    • Not imported - the number of users not imported to Relativity.

    Click Cancel to stop the job from running. You can monitor the worker and manager agents from the Queue tab. For more information, see Viewing the Queue tab.

    Viewing import errors

    You can view export errors on the Import Utility Job Errors tab. Errors are also linked to your import utility job.

    Creating a user import file

    To import users into Relativity using the User Import Application, you must create a load file which contains the users to import. You can download a template load file by clicking New Import Utility Job, selecting an object type from the Object Type drop-down list, and then clicking Download UserTemplate. 

    The User template contains the following fields:

    Field Name Type Required? Description
    FirstName String Yes User's first name (max 50 characters). If the first name is greater than 50 characters. The application will throw an error to truncate user’s first name to 50 characters.
    LastName String Yes User's last name (max 50 characters). This field can’t contain more than 50 characters. The application will throw an error to truncate user’s Last name to 50 characters
    EmailAddress String Yes User's email address (must be unique). Relativity users can have the same first and last name, but the email address must be unique.
    Keywords String No

    Keywords related to the user (max 50 characters. This field can’t contain more than 50 characters. The application will throw an error to truncate Keywords to 50 characters.

    Notes String No Notes related to the user
    Groups String No Semi-colon delimited list of group names. All users added to "Everyone" group by default
    Type String Yes User type (e.g., Internal, External)
    Client String Yes Client associated with the user. If more than one client exists with the same name, the user won’t be created.
    RelativityAccess Boolean Yes Controls user's access to Relativity (TRUE for access, FALSE to disable)
    DocumentSkip String Yes Unsupported in RelativityOne. Only "Disabled" value accepted. This feature is not currently compatible with RelativityOne and as a result, this option does not impact a user's ability to access this feature.
    BetaUser Boolean Yes Indicates whether new UI framework is enabled (currently always enabled)
    ChangeSettings Boolean Yes Allows users without admin rights to change settings
    KeyboardShortcuts Boolean Yes Enables/Disables access to keyboard icon in reviewer interface
    ItemListPageLength Whole number Yes Default list length for all views (1-200)
    DefaultSelectedFileType Single choice Yes Default viewer mode (Viewer, Native Image, Long Text, Production)
    SkipDefaultPreference String Yes Skip default preference (Skip, Normal)
    EnforceViewerCompatability Boolean Yes Controls when users are required to download new viewer version
    AdvancedSearchPublicByDefault Boolean Yes Saved searches created by user are public by default
    NativeViewerCacheAhead Boolean Yes Pre-loads next native document in review queue (requires viewer v5.04+)
    ChangeDocumentViewer Boolean Yes Users can select viewer (TRUE), or use viewer set in DocumentViewer field (FALSE). If set to FALSE, the user can only use the viewer set in the Document Viewer field.
    DocumentViewer String Yes Determines viewer user can access (enter "Default")
    WindowsAccount String No Windows account data (SAM Account or UPN)
    UserMustChangePasswordOnNextLogin Boolean Yes User must update password on next login
    CanChangePassword Boolean Yes Enables user to change password
    MaximumPasswordAgeInDays Whole number Yes Maximum days password remains valid (0-1000)
    TwoFactorMode Single choice No Determines when two-factor authentication is used (None, Always, Outside, Trusted IPs)
    TwoFactorInfo Single choice No Enter a valid email address if TwoFactorMode is set to Always or Outside Trusted IPs. If TwoFactorMode is set to None, you don’t need to enter a valid email address for this field.
    TrustedIPs String (Not supported) No Defines IP addresses for login (importing/exporting not supported)

    Viewing import errors

    You can view import errors on the Import Utility Job Errors tab. Errors are also linked to your import utility job.

    Note: Errors that report a user being partially imported indicate that the user was created, but the application was unable to update one of the user’s properties. We recommend deleting the reported user and attempting the import again.

    Importing users from Relativity 9.3 and below

    Use the following workflows to import an import file generated by the Relativity User Import Application (RUIA) in a version of Relativity below Relativity 9.4. The workflow you use depends on the version of the RUIA you are using, either version 14.8 or 18.1.

    5.4.1 Importing users using an RUIA 14.8 import file

    To import users into Relativity 9.4 using an RUIA 14.8 import file, complete the following in your import file:

    1. Rename the AuthenticationData column to WindowsAccount.
    2. Remove the Password column completely.
    3. Rename the ChangePassword column to CanChangePassword.
    4. Rename the MaximumPasswordAge column to MaximumPasswordAgeInDays.
    5. Remove the Data Focus column completely.
    6. Add the following columns and to the import file, and populate for each user:
      • ChangeDocumentViewer - enter TRUE or FALSE
        1. If TRUE, users can select viewer they want to use. You can still set a default viewer in the Document Viewer field, but users can switch between viewers.
          1. If TRUE users must change the password when the log in.
          2. If FALSE users don’t need to change the password when they login.
        2. If FALSE, users cant’ select which viewer they want to use. Whatever viewer appears in the Document Viewer field is the only viewer the user has access to.
      • DocumentViewer - Enter one of the following values:
        1. Default - only available in Internet Explorer. This option pulls the from the UseLegacyViewer instance setting to determine which viewer the user can access.
        2. HTML - uses the HTML viewer to review documents.
        3. ActiveX - uses the ActiveX viewer to review documents.
      • UserMustChangePasswordOnNextLogin - enter TRUE or FALSE.
        • If TRUE users must change the password when the log in.
        • If FALSE users don’t need to change the password when they login.
      • TwoFactorMode - Enter one of the following values to determine when to use two factor authentication:
        1. None
        2. Always
        3. OutsideRestrictedIPs.
      • TwoFactorInfo - If TwoFactorMode is Always or OutsideRestrictedIPS, enter a valid email address for this field.

    5.4.2 Importing users using an RUIA 18.1 import file

    To import users into Relativity 9.4 using an RUIA 18.1 import file, complete the following in your import file:

    1. Add the following columns and default values to the import file:
      • ChangeDocumentViewer - enter TRUE or FALSE
        1. If TRUE, users can select viewer they want to use. You can still set a default viewer in the Document Viewer field, but users can switch between viewers.
        2. If FALSE, users cant’ select which viewer they want to use. Whatever viewer appears in the Document Viewer field is the only viewer the user has access to.
      • DocumentViewer - enter one of the following values:
        1. Default - only available in Internet Explorer. This option pulls the from the UseLegacyViewer instance setting to determine which viewer the user can access.
        2. HTML - uses the HTML viewer to review documents.
        3. ActiveX - uses the ActiveX viewer to review documents.

    Viewing the Queue tab

    You can view the progress of the worker and manager agent queues from the Queue tab.

    The Queue tab contains the following fields:

    • Job ID - the Artifact ID of the Import or Export Utility Job.
    • Queue Row Id - the ID column in the corresponding table.
    • Object Type - the type of object selected for the job.
    • Queue Status - the status of the current record. The following is a list of possible statuses:

        -1 - ERROR

        0 - NOT_STARTED

        1 - IN_PROGRESS

        2 - COMPLETE

        3 - CANCELLATION_REQUESTED

        4 - WAITING_FOR_WORKERS_TO_FINISH

        5 - FINISHING_JOB

    • Priority - the priority for the job as set by the user.
    • Agent ID - the Artifact ID of the Agent processing the record.

    Performance metrics

    Test

    Test scenario

    Operation time (hh:mm:ss)

    Export

    1 manager agent,

    1 worker agent

    1000 users

    00:08:37

    Export

    1 manager agent

    5 worker agent

    1000 users

    00:03:13

    Validation

    1 manager agent,

    1 worker agent

    1000 users

    00:20:48

    Validation

    1 manager agent

    5 worker agent

    1000 users

    00:07:34

    Validation and Import

    1 manager agent,

    1 worker agent

    1000 users

    01:16:55

    Validation and Import

    1 manager agent

    5 worker agent

    1000 users

    00:50:16