User Import Application

Note: Some of the recipes listed below now exist as knowledge base articles on the Relativity Community. When you click those links, you must enter valid Community credentials to access those articles. The remaining recipes will soon be integrated into their corresponding feature documentation so that they'll show up either as new topics or new headings within existing topics. Once this relocation is complete, we will be deprecating this home page, and all of the content below will be accessible via search on our sites.

You must have valid Relativity Community credentials in order to download any Community file linked to the documentation site. You'll need to enter those credentials on the Community login screen if you're not already logged in. If you're already logged in to the Community at the time you click a link, the file is automatically downloaded in the bottom left corner of your screen. If you get an error message stating "URL No Longer Exists" after clicking a Community link, it may be due to a single sign-on error related to the SAML Assertion Validator, and you should contact your IT department.

You can use the Relativity User Import Application to import multiple users into Relativity from a CSV file by defining the users and their Relativity settings. You can also export a list of users from your environment along with their Relativity settings. When planning to import users to your Relativity environment, keep in mind that this application runs only during off hours.

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

RelativityOne
19.1.2.0 Relativity 9.7-Server 2021
19.1.0.41 Relativity 9.5.196.102-9.6
19.1.0.30 9.4-9.5.162.111

Category

The Relativity User Import Application includes the following components:

  • Agents
  • Event handlers
  • Custom pages

Special considerations

  • This application only works during off hours.
  • Passwords cannot be imported or exported with this application. Upon import, users who only have default password providers will be required to click the Forgot your password? link on the login page to generate a new password in order to access Relativity.
  • All users imported with this application will have a Default Password Provider automatically created and associated with their account. System Administrators can restrict newly imported users from using the Forgot your password? workflow and thus restrict access to Relativity with the Default Password Provider by setting the CanChangePassword column in the load file to FALSE.
  • The Forgot your password? workflow will not work if CanChangePassword setting is set to FALSE.
  • Only Default Password Provider and Default Integration Authentication Provider Authentication types are supported. All other authentication types are unsupported and won’t be exported or imported using this tool.
  • Example: A system admin attempts to export a user who has the following login methods:
    • Default Password Provider
    • Default Integration Authentication Provider
    • Default RSA Provider

The user will be exported however only with the Login Methods supported by this solution which are Default Password Provider and Default Integration Authentication Provider. The Default RSA Provider will not be exported and cannot be imported with this solution.

  • Example: A system admin attempts to export a user who has the following login method:
  • Default RSA Provider

The user will be exported however without any Login Methods because Default RSA Provider is not supported. Upon import a Default Password Provider will be automatically created for this user however the user will not be able to login until they complete the Forgot your password? Workflow. Admins can control a user’s ability to change their password with the CanChangePassword column in the load file.

  • During import an error that reports a user may be partially imported indicates that one of the user creation steps failed. We recommend validating the user’s personal information, keywords and notes and login methods. Update the user information as needed or remove the user and retry the import if necessary.
  • Worker queue records are removed sequentially as job errors are recorded therefore the total number of imported/exported records reported in between web page refreshes may not be fully accurate until the job is completely processed.
  • If the import file contains Relativity Admin or Relativity Service Account, and error will most likely occur because all Relativity instances already have these accounts.
  • The Admin Migration application can only be installed in one workspace in your environment.
  • When creating an import load file, a column header row must be included in the load file for import jobs and each column header must be populated with a value.
  • Relativity throws an error if you try to import a user that already exists in your environment.
  • When an import or export job is deleted, all errors that correspond to that job are also deleted.
  • You can't import users that belong to groups that don't exist in the destination environment. You must create the groups in the destination environment before importing.
  • If there are multiple groups in the instance you export from and the instance you import to, users are only imported into the first duplicate name group created.
  • Every user is automatically added to the “Everyone” group, even in scenarios where the group column in the load file is blank.
  • If Trusted IP for the user is empty or blank, the Outside Trusted IPs setting for two factor mode is invalid and won’t work.
  • If the application is uninstalled from your environment, the agents that you manually created remain in the environment, but they will fail and disable as required tables are removed.
  • Uninstalling the application will delete all the database tables, queue records, existing export/import jobs.
  • Custom components may not exhibit the same performance and behavior as native Relativity features.
  • While each solution is carefully built and thoroughly tested to work on your version of Relativity, they are not considered core features and are not eligible for the same level of support as 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: 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.

Creating manager and worker agents

To use the User Import Application , you must add the following manager and worker agents to your environment;

  • RUIA - Export Manager
  • RUIA - Export Worker
  • RUIA - Import Manager
  • RUIA - Import Worker

To create manager and worker agents, perform the following steps:

  1. Click the user drop-down menu in the upper-right corner of Relativity, and then click Home.
  1. Navigate to the Server & Agent Management tab, and then select Agents.
  2. Click New Agent.
  3. Click next to Agent Type, and then filter in the Application Name column for User Import Application.
  4. Select AdminMigrationUtility - Export Manager.
  5. Click Ok.

Note: You can only create one instance of the manager agents. You can create multiple worker agents.

  1. Set the number of manager agents you want in the Number of Agents field.
  2. Click next to Agent Server, and then select the agent server where you want to install the new agent.
  3. Click Ok.
  4. Set the appropriate interval.
  5. Leave all other settings at their default values, and then click Save and New.
  6. Repeat steps 1-11 for the other manager and worker agents.

Note: You must install at least one each agent for all four agent types.

Export utility job

You can create and run an export utility job from the Export Utility Job tab. To create and run an export utility job, complete 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: After selecting the User Object Type, click the Download User Template button 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 Creating a user import file.
    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:

    1. FirstName
      • Required
      • Type: String
      • Description: The user’s first name.

      Note: If the first name is greater than 50 characters. The application will throw an error to truncate user’s first name to 50 characters.

    2. LastName
      • Required
      • Type: String
      • Description: The user’s last name.

      Note: This field can’t contain more than 50 characters. The application will throw an error to truncate user’s Last name to 50 characters

    3. EmailAddress
      • Required
      • Type: String
      • Description: The user’s email address.

      Note: Relativity users can have the same first and last name, but the email address must be unique.

    4. Keywords
      • Optional
      • Type: String
      • Description: Any keywords related to the user.

      Note: This field can’t contain more than 50 characters. The application will throw an error to truncate Keywords to 50 characters.

    5. Notes
      • Optional
      • Type: String
      • Description: Any notes related to the user.
    6. Groups
      • Optional
      • Type: String
      • Description: A semi-colon delimited list of group names to add the user to.
      • Example: Reviewer Group;Attorney Group

      Note: By default, all users are added to the “Everyone” group even if this field is left blank.

    7. Type
      • Required
      • Type: String
      • Description: The user type. The default values are Internal or External, but you can populate this field with any value that exists in the environment where the users will be imported.
    8. Client
      • Required
      • Type: String
      • Description: The client associated with the user.

      Note: If more than one client exists with the same name, the user won’t be created.

    9. RelativityAccess
      • Required
      • Type: Boolean - TRUE or FALSE
      • Description: The settings used to control the user’s access to Relativity. If set to TRUE, Enabled users can to log in to Relativity and are considered for billing under your Relativity license. If set to FALSE, users cannot access Relativity and won't be counted or billed as named users on your Relativity license.
    10. DocumentSkip
      • Required
      • Type: Single choice
      • Description: Controls whether or not the user has the ability to skip documents during review that no longer meet the original conditions of a view due to propagation. Enter one of the following values:
        1. Enabled - enables the Skip function.
        2. Disabled - disables the Skip function.
        3. Force Enabled - always enables the Skip function so that the user can't turn it off. This option is only available for system admins.
    11. BetaUser
      • Required
      • Type: Boolean - TRUE or FALSE
      • Description: Indicates whether the new UI framework is enabled for the user. At the time of writing, users always have the new UI framework enabled no matter the value of this field in the load file.
    12. ChangeSettings
      • Required
      • Type: Boolean - TRUE or FALSE
      • Description: Users without admin rights can change their settings.
    13. KeyboardShortcuts
      • Required
      • Type: Boolean - TRUE or FALSE
      • Description: Enables or disables access to the keyboard icon in the core reviewer interface.
    14. ItemListPageLength
      • Required
      • Type: Whole number - enter a value between 1 and 200.
      • Description: A numeric field indicating the default list length for all views in Relativity.
    15. DefaultSelectedFileType
      • Required
      • Type: Single choice
      • Description: The default viewer mode. Enter one of the following values:
        1. Viewer
        2. Native
        3. Image
        4. Long Text
        5. Production
    16. SkipDefaultPreference
      • Required
      • Type: String
      • Description: The skip default preference. Enter one of the following values:
        1. Skip - advances a user to the next document in the queue that matches the defined view conditions when the user clicks Save and Next.
        2. Normal - document review operates normally, displaying all documents in the queue.
    17. EnforceViewerCompatibility
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: Provides you with the ability to control when users are required to download a new version of the viewer.
    18. AdvancedSearchPublicByDefault
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: Indicates whether saved searches created by the user are public by default.
    19. NativeViewerCacheAhead
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: If enabled, pre-loads the next native document in the review queue once the active document is loaded.

      Note: To utilize Native Viewer Cache Ahead, you must have version 5.04 or greater of the viewer running on your computer. If this application isn't working properly, uninstall and reinstall your viewer to ensure compatibility.

    20. ChangeDocumentViewer
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: Users can select which viewer they want to use.

      Note: If set to FALSE, the user can only use the viewer set in the Document Viewer field.

    21. DocumentViewer
      • Required
      • Type: String
      • Description: Determines which viewer the user can access when reviewing documents. 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.
    22. WindowsAccount
      • Optional
      • Type: String
      • Description: The windows account data for the user. This is the name of the user account in Active Directory.

      Note: This value can be specified as a SAM Account (domain\username) or as a UPN (user@fully-qualified-domain).

    23. UserMustChangePasswordOnNextLogin
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: Indicates whether a user must update the Relativity password on next login.
    24. CanChangePassword
      • Required
      • Type: Boolean - enter TRUE or FALSE
      • Description: Enables the user to change their password.
    25. MaximumPasswordAgeInDays
      • Required
      • Type: Whole number - enter a value between 0 and 1000
      • Description: Sets the maximum number of days a password remains valid. The user will be prompted for a new password on a when logging in after the expiration date. If set to zero, the password does not expire.
    26. TwoFactorMode

      • Optional
      • Type: Single choice - enter None, Always, Outside Trusted IPs
      • Description: Determines when Two Factor authentication is used.
    27. TwoFactorInfo
      • Optional
      • Type: String
      • Description: Enter a valid email address if TwoFactorMode is set to Always or Outside Trusted IPs.

      Note: If TwoFactorMode is None, you don’t need to enter a valid email address for this field.

    28. Trusted IPs
      • Optional
      • Type: String
      • Description: Defines the IP address(es) from where the user can log in.

      Note: This column must not be included in the load file. It must always be set to blank.

    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