This DTO has been deprecated as part of the Relativity Services API (RSAPI) Deprecation and is no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

User

Individuals are added to Relativity as users, who are then added to groups associated with workspaces. For more information, see Users on the Relativity Documentation site.

The Services API supports all CRUD and query operations on a User DTO.

Note: You can also perform a full set of CRUD operations on users with the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.

Note: Under the authentication model introduced in Relativity 9.4.224.2 (June 2016 monthly update) we moved several user object fields to different objects. This API will still update most of these fields but developers are encouraged to switch to the new protocol. The following fields that are backwards compatible are: Invalid Login Attempts, Changes Password, Maximum Password Age, Password Last Reset on, and Change password next login. The Authentication Data field is supported only if the field is set to empty string or null.

Create a User

You can add a User to Relativity by calling the Create() method on the User repository. For more information about Password fields, see Fields used by Group and User objects.

This code sample illustrates how to create the User DTO and references several utility methods for retrieving ArtifactIDs. See Utility methods for User DTO creation.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

public static bool CreateUserUsingRepository(IRSAPIClient proxy)
{
     proxy.APIOptions.WorkspaceID = -1;
      
     int defaultSelectedFileType = 1;
     int userType = 3;
     int documentSkip = 1000003;
     int skipDefaultPreference = 1000004;
     int password = 1000005;
     int sendNewPasswordTo = 1000006;
      
     // STEP 1: Get the ArtifactIDs for the required Choice, Group, and Client objects.
     int returnPasswordCodeID = FindChoiceArtifactID(proxy, sendNewPasswordTo, "Return");
     int passwordCodeID = FindChoiceArtifactID(proxy, password, "Auto-generate password");
     int documentSkipCodeID = FindChoiceArtifactID(proxy, documentSkip, "Enabled");
      
     int documentSkipPreferenceCodeID = FindChoiceArtifactID(proxy, skipDefaultPreference, "Normal");
     int defaultFileTypeCodeID = FindChoiceArtifactID(proxy, defaultSelectedFileType, "Native");
     int userTypeCodeID = FindChoiceArtifactID(proxy, userType, "Internal");
      
     int everyoneGroupArtifactID = FindGroupArtifactID(proxy, "Everyone");
     int clientArtifactID = FindClientArtifactID(proxy, "Relativity Template");
      
     // STEP 2: Create a User DTO for the User that you want to create.
     kCura.Relativity.Client.DTOs.User userDTO = new kCura.Relativity.Client.DTOs.User();
      
     userDTO.AdvancedSearchPublicByDefault = true;
     userDTO.AuthenticationData = "";
     userDTO.BetaUser = false;
     userDTO.ChangePassword = true;
      
     userDTO.ChangePasswordNextLogin = false;
     userDTO.ChangeSettings = true;
     userDTO.Client = new kCura.Relativity.Client.DTOs.Client(clientArtifactID);
     userDTO.DataFocus = 1;
      
     userDTO.DefaultSelectedFileType = new kCura.Relativity.Client.DTOs.Choice(defaultFileTypeCodeID);
     userDTO.DocumentSkip = new kCura.Relativity.Client.DTOs.Choice(documentSkipCodeID);
     userDTO.EmailAddress = "zzz12344@test.com";
     userDTO.EnforceViewerCompatibility = true;
      
     userDTO.FirstName = "Bruce";
     userDTO.Groups = 
          new List<kCura.Relativity.Client.DTOs.Group> 
               { new kCura.Relativity.Client.DTOs.Group(everyoneGroupArtifactID) };
     userDTO.ItemListPageLength = 25;
     userDTO.KeyboardShortcuts = true;
      
     userDTO.LastName = "User for User Create Testing";
     userDTO.MaximumPasswordAge = 0;
     userDTO.NativeViewerCacheAhead = true;
     userDTO.PasswordAction = new kCura.Relativity.Client.DTOs.Choice(passwordCodeID);
      
     userDTO.RelativityAccess = true;
     userDTO.SendPasswordTo = new kCura.Relativity.Client.DTOs.Choice(returnPasswordCodeID);
     userDTO.SkipDefaultPreference = new kCura.Relativity.Client.DTOs.Choice(documentSkipPreferenceCodeID);
     userDTO.TrustedIPs = "";
     userDTO.Type = new kCura.Relativity.Client.DTOs.Choice(userTypeCodeID);

     //Beginning in August 2017, you can auto-disable a User on a specific date. Note that you must use a UTC date format, and the date must be in the future:
     userDTO.DisableDate = "2017-11-01T12:00:00-08:00"; 
      
     WriteResultSet<kCura.Relativity.Client.DTOs.User> createResults = 
          new WriteResultSet<kCura.Relativity.Client.DTOs.User>();
      
     // STEP 3: Attempt to create the User.
     try
     {
          createResults = proxy.Repositories.User.Create(userDTO);
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     // Check for success.
     if (!createResults.Success)
     {
          Console.WriteLine(String.Format("An error occurred creating user: {0}", createResults.Message));
           
          foreach (Result<kCura.Relativity.Client.DTOs.User> createResult in createResults.Results)
          {
               if (!createResult.Success)
               {
                    Console.WriteLine(String.Format("   An error occurred in create request: {0}", createResult.Message));
               }
          }
          return false;
     }
      
     //STEP 4: Output the password.
     Console.WriteLine(String.Format("Password for created user is {0}", 
          createResults.Results[0].Artifact["Password"]));
      
     return true;
}

Notes:

AuthenticationData must be set to empty or null. It may be left off completely.
ChangePassword, ChangePasswordNextLogin, and MaximumPasswordAge are currently required and will make a password method for the user without a password being set.
Configuring AdminsCanSetPasswords in Relativity.Authentication section of instance settings, it is possible to set the password on the password method for the user with userDTO.Password = “securePasswordHere”. This should not be done in a production environment. See Manually setting passwords for configuring AdminsCanSetPasswords.

Utility methods for User DTO creation

The code sample illustrating how to create the User DTO uses the following utility methods to facilitate the retrieval of ArtifactIDs for Choices, Groups, and Clients.

FindChoiceArtifactID() method

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

private static int FindChoiceArtifactID(IRSAPIClient proxy, int choiceType, string value)
{
     int artifactID = 0;
      
     WholeNumberCondition choiceTypeCondition = 
          new WholeNumberCondition(ChoiceFieldNames.ChoiceTypeID, NumericConditionEnum.EqualTo, (int)choiceType);
      
     TextCondition choiceNameCondition = 
          new TextCondition(ChoiceFieldNames.Name, TextConditionEnum.EqualTo, value);
      
     CompositeCondition choiceCompositeCondition = 
          new CompositeCondition(choiceTypeCondition, CompositeConditionEnum.And, choiceNameCondition);
      
     Query<kCura.Relativity.Client.DTOs.Choice> choiceQuery = 
          new Query<kCura.Relativity.Client.DTOs.Choice>(new List<FieldValue> { new 
               FieldValue(ArtifactQueryFieldNames.ArtifactID) }, choiceCompositeCondition, new List<Sort>());
      
     try
     {
          QueryResultSet<kCura.Relativity.Client.DTOs.Choice> choiceQueryResult =
                proxy.Repositories.Choice.Query(choiceQuery);
           
          if (choiceQueryResult.Success && choiceQueryResult.Results.Count == 1)
          {
               artifactID = choiceQueryResult.Results.FirstOrDefault().Artifact.ArtifactID;
          }
          else
          {
               Console.WriteLine("The choice could not be found.");
          }
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
     }
     return artifactID;
}

FindGroupArtifactID() method

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

private static int FindGroupArtifactID(IRSAPIClient proxy, string group)
{
     int artifactID = 0;
      
     TextCondition groupCondition = 
          new TextCondition(GroupFieldNames.Name, TextConditionEnum.EqualTo, group);
      
     Query<kCura.Relativity.Client.DTOs.Group> queryGroup = 
          new kCura.Relativity.Client.DTOs.Query<kCura.Relativity.Client.DTOs.Group> { Condition = groupCondition };
      
     queryGroup.Fields.Add(new FieldValue(ArtifactQueryFieldNames.ArtifactID));
      
     try
     {
          QueryResultSet<kCura.Relativity.Client.DTOs.Group> resultSetGroup = 
               proxy.Repositories.Group.Query(queryGroup, 0);
           
          if (resultSetGroup.Success && resultSetGroup.Results.Count == 1)
          {
               artifactID = resultSetGroup.Results.FirstOrDefault().Artifact.ArtifactID;
          }
          else
          {
               Console.WriteLine("The Query operation failed.{0}{1}", Environment.NewLine, resultSetGroup.Message);
          }
     }
     catch (Exception ex)
     {
               Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
     }
     return artifactID;
}

FindClientArtifactID() method

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

private static int FindClientArtifactID(IRSAPIClient proxy, string group)
{
     int artifactID = 0;
      
     TextCondition clientCondition = 
          new TextCondition(ClientFieldNames.Name, TextConditionEnum.EqualTo, group);
      
     Query<kCura.Relativity.Client.DTOs.Client> queryClient = 
          new Query<kCura.Relativity.Client.DTOs.Client> { Condition = clientCondition };
      
     queryClient.Fields = FieldValue.AllFields;
      
     try
     {
          QueryResultSet<kCura.Relativity.Client.DTOs.Client> resultSetClient = 
               proxy.Repositories.Client.Query(queryClient, 0);
           
          if (resultSetClient.Success && resultSetClient.Results.Count == 1)
          {
               artifactID = resultSetClient.Results.FirstOrDefault().Artifact.ArtifactID;
          }
          else
          {
               Console.WriteLine("The Query operation failed.{0}{1}", Environment.NewLine, resultSetClient.Message);
          }
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
     }
     return artifactID;
}

Read a User

To read Field values, you can use the Read() method on the User repository as illustrated in this code sample.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

public static bool ReadUserUsingRepository(IRSAPIClient proxy)
{
     proxy.APIOptions.WorkspaceID = -1;
      
     // STEP 1: Create the User DTO.
     kCura.Relativity.Client.DTOs.User user = new kCura.Relativity.Client.DTOs.User(1015464);
     user.Fields = FieldValue.AllFields;
     ResultSet<kCura.Relativity.Client.DTOs.User> userResults = null;
      
     //STEP 2: Read the User DTO.
     try
     {
          userResults = proxy.Repositories.User.Read(user);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred reading the user: {0}", ex.Message);
          return false;
     }
      
     //STEP 3: Check for success.
     if (!userResults.Results.Any())
     {
          Console.WriteLine("Could not find the user: {0}", userResults.Message);
          return false;
     }
     return true;
}

Note: Workspace ID must to be set to -1; otherwise, the user DTO will return only the FullName field.

Update a User

You can use the Update() method on the User repository to modify its properties as illustrated in this code sample. Updating a password requires the following properties:

Password
PasswordAction
ChangePassword

See Fields used by Group and User objects.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

public static bool UpdateUserUsingRepository(IRSAPIClient proxy)
{
     proxy.APIOptions.WorkspaceID = -1;
      
     //STEP 1: Define the query.
     Condition userQueryCondition = 
          new TextCondition(UserFieldNames.FirstName, TextConditionEnum.EqualTo, "Bruce");
      
     Query<kCura.Relativity.Client.DTOs.User> userQuery = 
          new Query<kCura.Relativity.Client.DTOs.User>(FieldValue.AllFields, userQueryCondition, new List<Sort>());
      
     QueryResultSet<kCura.Relativity.Client.DTOs.User> userQueryResults = null;
      
     //STEP 2: Query for the User.
     try
     {
          userQueryResults = proxy.Repositories.User.Query(userQuery);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred querying for the user: {0}", ex.Message);
          return false;
     }
      
     if (!userQueryResults.Results.Any())
     {
          Console.WriteLine("Could not find the user: {0}", userQueryResults.Message);
          return false;
     }
      
     //STEP 3: Retreive the User artifact and update it.
     kCura.Relativity.Client.DTOs.User userToUpdate = userQueryResults.Results.First().Artifact;
     userToUpdate.FirstName = "Steve";
     WriteResultSet<kCura.Relativity.Client.DTOs.User> userUpdateResults = null;
      
     //STEP 4: Complete the update.
     try
     {
          userUpdateResults = proxy.Repositories.User.Update(userToUpdate);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred updating the user: {0}", ex.Message);
          return false;
     }
      
     //STEP 5: Check for success.
     if (userUpdateResults.Success)
     {
          Console.WriteLine("The user has been updated!");
     }
     else
     {
          Console.WriteLine("An error occurred updating the user: {0}", userUpdateResults.Message);
          return false;
     }
     return true;
}

Delete a User

You can remove a User from Relativity by calling the Delete() method on the User repository as illustrated in this code sample.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

public static bool DeleteUserUsingRepository(IRSAPIClient proxy)
{
     proxy.APIOptions.WorkspaceID = -1;
      
     // STEP 1: Create the User DTO.
     kCura.Relativity.Client.DTOs.User user = new kCura.Relativity.Client.DTOs.User(1015464);
     ResultSet<kCura.Relativity.Client.DTOs.User> userResults = null;
      
     // STEP 2: Delete the User.
     try
     {
          userResults = proxy.Repositories.User.Delete(user);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred deleting for the user: {0}", ex.Message);
          return false;
     }
      
     // STEP 3: Check for success.
     if (!userResults.Results.Any())
     {
          Console.WriteLine("Could not delete the user: {0}", userResults.Message);
          return false;
     }
     return true;
}

Query for a User

This code sample illustrates how to set query conditions, call the Query() method on the User repository, and iterate through the result set.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

public static bool QueryUserUsingRepository(IRSAPIClient proxy)
{
     proxy.APIOptions.WorkspaceID = -1;
      
     // STEP 1: Create the query for a given user.
     Condition userQueryCondition = 
          new TextCondition(UserFieldNames.FirstName, TextConditionEnum.EqualTo, "Bruce");
      
     Query<kCura.Relativity.Client.DTOs.User> userQuery = 
          new Query<kCura.Relativity.Client.DTOs.User>(FieldValue.AllFields, userQueryCondition, new List<Sort>());
      
     QueryResultSet<kCura.Relativity.Client.DTOs.User> userQueryResults = null;
      
     // STEP 2: Query for the user.
     try
     {
          userQueryResults = proxy.Repositories.User.Query(userQuery);
     }
     catch (Exception ex)
     {
          Console.WriteLine("An error occurred querying for the user: {0}", ex.Message);
          return false;
     }
      
     // STEP 3: Check for success.
     if (!userQueryResults.Results.Any())
     {
          Console.WriteLine("Could not find the user: {0}", userQueryResults.Message);
          return false;
     }
     return true;
}

Multi-tenancy

With the introduction of support for multi-tenancy, Client becomes the parent of the User object. Subsequently the ParentArtifact property is set to the Client associated with the User.

Auto-disable a User

Beginning in September 2017, you can auto-disable a user on a specific date. You can set the optional DisableDate property when creating or editing an individual user. The date value is stored in the UTC format. You can use UTC or ISO 8601 format to specify the date. The date must be in the future:

Copy

1
userDTO.DisableDate = "2017-11-01T12:00:00-08:00";

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet

User

Create a User

Utility methods for User DTO creation

Read a User

Update a User

Delete a User

Query for a User

Multi-tenancy

Auto-disable a User

Additional Resources