User Manager (.NET)

Users are individuals who have access to the Relativity environment. For general information, see Users on the Relativity Documentation site. The User Manager API exposes multiple operations that you can use to programmatically manage users in your Relativity environment. It includes the following features:

  • Supports create, read, update, and delete operations on users.
  • Supports read and update operations on the settings of the current users.
  • Provides helper methods used to retrieve the available user types.
  • Retrieval of all users from a workspace or admin-level context.

Sample use cases

  • Developing a custom tool to import users in Relativity.
  • Updating properties like the name or the email of the logged user or any other user in Relativity.
  • Retrieve user information for display in a view for a custom application.

You can also use the User service through the REST API. For more information, see User Manager (REST).

This page contains the following information:

The Relativity.Identity.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for managing users

Guidelines and considerations

You can use the following sample workflow to add users to your Relativity environment:

  1. Retrieve a list of user types available in a Relativity environment.
  2. Retrieve a list of available clients. You can use the Object Manager to query for clients.
  3. Add the user.

Methods

The IUserManager interface in the Relativity.Identity.{versionNumber}.Services namespace exposes the following methods:

  • CreateAsync() - adds a new user to a Relativity environment. It returns a UserResponse object containing the Artifact ID and other properties of the new user.
  • ReadAsync() - retrieves advanced metadata for a user, including their Relativity access, name, email, and other properties. You can also use this overloaded method to return extended metadata, including information about the operations that you have permissions to perform on the user, such as update or delete.
  • UpdateAsync() - modifies the properties of a user (e.g., email, first and last name, etc.). You can use also this overloaded method to restrict the update of a user based on the date that it was last modified using the following optional parameters:
    • lastModifiedOn - the date and time used for comparison with the last modified date assigned to the user.
    • cancel - a request to cancel the execution of the operation.
  • DeleteAsync() - removes a user from Relativity. This overloaded method supports functionality for requesting the cancellation of the delete.
  • ReadSettingsAsync() - retrieves the settings of the current user, including its email, first name, last name, and others.
  • UpdateSettingsAsync() - modifies the user setting properties of the current user. You can also use an overloaded method containing the following optional parameters:
    • lastModifiedOn - the date and time used for comparison with the last modified date assigned to the user.
    • cancel - a request to cancel the execution of the operation.
  • ReadActiveUsersAsync() - asynchronously retrieves a list of all active users in a workspace. If the number of returned users exceeds the ChoiceLimitForUI setting, no users will be returned.
  • ReadAllUsersAsync() - asynchronously retrieves a list of all users in a workspace, including administrators and (optional) deleted users.
  • RetrieveAllWithRelativityAccessAsync() - asynchronously retrieves a list of users from the specified workspace that have Relativity access (use -1 for Admin workspace).
  • RetrieveCurrentAsync() - asynchronously retrieves the current user in the specified workspace. NOTE: User Artifact ID may differ for the same user in different workspaces.
  • RetrieveUsersBy() - gets a list of users and their information, and supports filtering, ordering, and paging these results.
  • QueryEligibleGroupsToAddUsersToAsync() - query for Groups that are eligible for adding at least one of specified users. You can also use an overloaded method containing the following optional parameters:
    • progress - a callback that reports query execution progress..
    • cancel - a request to cancel the execution of the operation.
  • QueryGroupsByUserAsync() - query for groups the user is a member of.
  • GetAvailableTypesAsync() - retrieves a list containing all the available choices for the user type.

Classes and enumeration

  • DocumentViewerProperties class - represents user properties that are related to the document viewer. The UserRequest and UserResponse classes have a property of this type.
  • DocumentViewerFileType enumeration - indicates the default viewer mode.
  • DocumentViewer enumeration - indicates which viewer the user can access when reviewing documents.
  • EmailPreference enumeration - indicates the preference for email notifications when adding or deleting users or groups.
  • UserRequest class - represents the data used to create or update a user. The CreateAsync() and UpdateAsync() methods take an object of this type. Its properties include the email, first and last name, user type, and others.
  • UserResponse class - represents the results of a read operation. The ReadAsync(), CreateAsync() and UpdateAsync() methods return an object of this type. Its properties include the email, first and last name, user type, and others.
  • UserSettingRequest class - represents the data used to update the settings of the current user. The UpdateSettingsAsync() methods take an object of this type. Its properties include the email, first and last name, email preference, and others.
  • UserSettingResponse class - represents the results of a read settings operation. The ReadSettingsAsync() and UpdateSettingsAsync() methods return an object of this type. Its properties include the email, first and last name, email preference, and others.

Code samples

Create a user

Before creating a user, you need to identify the client and the user type. The following code sample illustrates how to use the CreateAsync() method to add a single user. It passes the Artifact ID of the client and the user type.

public async Task CreateUserAsync()
{
    int clientID = 1;
    int userTypeID = 1;
 
    UserRequest request = new UserRequest
    {
        AllowSettingsChange = true,
        Client = new Securable<ObjectIdentifier>(new ObjectIdentifier { ArtifactID = clientID }),
        DefaultFilterVisibility = true,
        DisableOnDate = new DateTime(2030, 12, 31),
        DocumentViewerProperties = new DocumentViewerProperties
        {
            AllowDocumentSkipPreferenceChange = true,
            AllowDocumentViewerChange = true,
            AllowKeyboardShortcuts = true,
            DefaultSelectedFileType = DocumentViewerFileType.Default,
            DocumentViewer = DocumentViewer.Default,
            SkipDefaultPreference = false
        },
        EmailAddress = "email address",
        EmailPreference = EmailPreference.Default,
        FirstName = "First",
        ItemListPageLength = 25,
        Keywords = string.Empty,
        LastName = "Last",
        Notes = string.Empty,
        RelativityAccess = true,
        SavedSearchDefaultsToPublic = true,
        TrustedIPs = string.Empty,
        Type = new ObjectIdentifier { ArtifactID = userTypeID }
    };
 
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            UserResponse response = await userManager.CreateAsync(request);
            string info = string.Format("Created user with Artifact ID {0}", response.ArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve metadata for a user

Use the overloaded ReadAsync() method to retrieve basic metadata for a user or extended metadata, which includes information about the operations that you have permissions to perform on this user. The following code sample illustrates how to call the ReadAsync() method by passing the Artifact ID of the user. If you want to return additional information, use the overloaded method by passing Boolean values set to true for additional metadata and permissions.

public async Task ReadUserAsync()
{
    int userArtifactID = 1;
 
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            UserResponse response = await userManager.ReadAsync(userArtifactID);
            string info = string.Format("Read user {0} {1} with Artifact ID {2}", response.FirstName, response.LastName, response.ArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve settings of the current user

Use the overloaded ReadSettingsAsync() method to retrieve the settings of the current user or extended metadata, which includes information about the operations that you have permissions to perform on the user settings. The following code sample illustrates how to call the ReadSettingsAsync() method. If you want to return additional information, use the overloaded method by passing Boolean values set to true for additional metadata and permissions.

public async Task ReadSettingsAsync()
{
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            UserSettingResponse response = await userManager.ReadSettingsAsync();
            string info = string.Format("Read settings of user {0} {1}.", response.FirstName, response.LastName);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Update the properties of a user

Use the UpdateAsync() method to modify the properties of a user. The following code sample illustrates how to call this method by passing the Artifact ID of the user, and a UserRequest object. This overloaded method also supports functionality for requesting the cancellation of the update, and monitoring progress.

Additionally, you can also restrict the update of a user to the date that it was last modified by passing the value of LastModifiedOn property as an argument to the overloaded UpdateAsync() method.

public async Task UpdateUserAsync()
{
    int userArtifactID = 1;
 
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            UserResponse userResponse = await userManager.ReadAsync(userArtifactID);
            UserRequest request = new UserRequest(userResponse);
            request.LastName = "Updated Last Name";
            request.FirstName = "Updated First Name";
            UserResponse updateResponse = await userManager.UpdateAsync(userArtifactID, request);
            string info = string.Format("Updated user with Artifact ID {0}", updateResponse.ArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Update the settings of the current user

Use the UpdateSettingsAsync() method to modify the setting properties of the current user. The following code sample illustrates how to call this method by passing a UserSettingRequest object. This overloaded method also supports functionality for requesting the cancellation of the update, and monitoring progress. Additionally, you can also restrict the settings update to the date that it was last modified by passing the value of LastModifiedOn property as an argument to the overloaded UpdateSettingsAsync() method.

public async Task UpdateUserSettingAsync()
{
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            UserSettingResponse userResponse = await userManager.ReadSettingsAsync();
            UserSettingRequest request = new UserSettingRequest(userResponse);
            request.LastName = "Updated Last Name";
            request.FirstName = "Updated First Name";
            UserSettingResponse response = await userManager.UpdateSettingsAsync(request);
            string info = string.Format("Updated settings of user {0} {1}.", response.FirstName, response.LastName);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Delete a user

Use the DeleteAsync() method to remove users from Relativity. The following code sample illustrates how to call this method by passing the Artifact ID of the user. This overloaded method also supports functionality for requesting the cancellation of the delete, and monitoring progress.

public async Task DeleteUserAsync()
{
    int userArtifactID = 1;
 
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            await userManager.DeleteAsync(userArtifactID);
            string info = string.Format("Deleted user with Artifact ID {0}", userArtifactID);
            Console.Write(info);
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve all the available types for the user

Use the GetAvailableTypesAsync() method to retrieve a list containing all the available choices for the user type. You can call this helper method before creating a user to get the Artifact ID of the user type.

public async Task GetAvailableTypesAsync()
{
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            List<DisplayableObjectIdentifier> response = await userManager.GetAvailableTypesAsync();
            foreach (DisplayableObjectIdentifier identifier in response)
            {
                string info = string.Format("Available user type with Artifact ID {0}.", identifier.ArtifactID);
                Console.WriteLine(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Retrieve all users for a given workspace

Use the RetrieveAll() method to retrieve a list containing all the users in a given workspace.

public async Task RetrieveAll()
{
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            int workspaceID = 1018249;
            List<UserInfo> response = await userManager.RetrieveAll(workspaceID);
            foreach (UserInfo userInfo in response)
            {
                string info = string.Format("Available user {0} with Artifact ID {1}.", userInfo.FullName, userInfo.ArtifactID);
                Console.WriteLine(info);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}

Query for users in a given workspace

Use the RetrieveUsersBy() method to query users in a given workspace.

public async Task RetrieveUsersBy()
{
    using (Relativity.Identity.{versionNumber}.Services.IUserManager userManager = serviceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IUserManager>())
    {
        try
        {
            int workspaceID = 1018249;
            int start = 0;
            int length = 25;
 
            QueryRequest query = new QueryRequest
            {
                Condition = "'User Type' IN ['Internal']"
            };
 
            UserInfoQueryResultSet response = await userManager.RetrieveUsersBy(workspaceID, query, start, length);
 
            if (response.ResultCount > 0)
            {
                foreach (Services.Interfaces.UserInfo.Models.UserInfo userInfo in response.DataResults)
                {
                    string info = string.Format("Available user {0} with Artifact ID {1}.", userInfo.FullName, userInfo.ArtifactID);
                    Console.WriteLine(info);
                }
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        }
    }
}