The User Information Manager service supports the retrieval of all users from a workspace or admin-level context. It provides the option to filter on a list of users with conditions set in a query. When you filter on the results, paging is also available. The service returns the Artifact ID, full name, and email address for each user. As a sample use case, you could use this service to retrieve user information for display in a view for a custom application.
The Relativity Services API also provides functionality for retrieving user information. For more information, see User Information Manager (.NET).
This page contains the following information:
See this related page:
Client code sample
You can use the following .NET code as a REST client for making calls with the User Information Manager service. This code illustrates how to perform the following tasks:
- Instantiate an HttpClient object for sending requests and responses using the URL for the User Information Manager service.
- Set the required headers for the request.
- Set the url variable to the URL for the operation that you want to perform.
- Return the results of the request.
- Use the logging framework for troubleshooting and debugging purposes. See Log from a Relativity application.
For more information about running this code sample, see Relativity SDK samples.
View client code sample
public async Task<bool> RetrieveAllUsers(IHelper helper)
{
//Set the ForContext for the method.
kCura.Relativity.Client.SamplesLibrary.Logging.ISampleLogger logger = _logger.ForContext("MethodName", nameof(RetrieveAllUsers), false);
bool success = false;
int artifactID = 0;
string fullName = string.Empty;
string email = string.Empty;
string username = ConfigurationManager.AppSettings["Username"].ToString();
string password = ConfigurationManager.AppSettings["Password"].ToString();
string base64header = helper.GetServicesManager().GetBase64Header(username, password);
string baseAddress = ConfigurationManager.AppSettings["BaseAddress"].ToString();
// Set up the client.
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri(string.Format("{0}/", baseAddress));
// Set the required headers.
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", base64header);
// Call the GET method
string url = "/Relativity.Rest/API/Relativity.Users/workspace/" + SampleWorkspace_ID + "/users/retrieveall";
HttpResponseMessage response = await httpClient.GetAsync(url);
string result = response.Content.ReadAsStringAsync().Result;
success = HttpStatusCode.OK == response.StatusCode;
if (success)
{
// Parse the result with Json.NET
JArray resultJArray = JArray.Parse(result);
JToken resultToken = resultJArray.Children().FirstOrDefault();
if (resultToken == null || resultToken.Count() == 0)
{
logger.LogInformation("Relativity.Users\retrieveall API succeeded but returned empty result.");
return success;
}
JToken artifactIDToken;
JToken fullNameToken;
JToken emailToken;
JObject resultChildObject = resultToken as JObject;
resultChildObject.TryGetValue("ArtifactID", StringComparison.InvariantCultureIgnoreCase, out artifactIDToken);
resultChildObject.TryGetValue("FullName", StringComparison.InvariantCultureIgnoreCase, out fullNameToken);
resultChildObject.TryGetValue("Email", StringComparison.InvariantCultureIgnoreCase, out emailToken);
artifactID = int.Parse(artifactIDToken.ToString());
fullName = fullNameToken.ToString();
email = emailToken.ToString();
logger.LogInformation("Relativity.Users\retrieveall API succeeded. User(first in the list) ArtifactID is {artifactID}, FullName is {fullName}, Email is {email}.", artifactID, fullName, email);
}
else
{
logger.LogError("Error: Relativity.Users\retrieveall was not successful - {result}", result);
}
return success;
}
Retrieve all users
You can retrieve a list of all users in a workspace or at the admin-level context. To make a request, use the GET method and specify the Artifact ID for the workspace containing users that you want to retrieve.
Use a URL with the following general format:
<host>/Relativity.Rest/API/Relativity.Users/workspace/{workspaceId}/users/retrieveall
To retrieve users at the admin-level context, specify -1 as the workspaceId:
<host>/Relativity.Rest/API/Relativity.Users/workspace/-1/users/retrieveall
The response contains the following fields:
- ArtifactID - a unique identifier for the field, which is represented as an integer.
- FullName - the last name followed by the first name of a user.
- Email - the email address of a user.
[
{
"ArtifactID":9,
"FullName":"Smith, Jane",
"Email":"jsmith@example.com"
},
{
"ArtifactID":1117813,
"FullName":"Jones, Bob",
"Email":"bjones@example.com"
},
{
"ArtifactID":777,
"FullName":"Green, Tom",
"Email":"tgreen@example.com"
}
]
Retrieve and filter on users
Like the retrieveall endpoint, the retrieveusersby endpoint gets a list of all users and their information. It also filters on the list of users with query conditions, and supports paging.
Use a URL with the following general format:
<host>/Relativity.Rest/API/Relativity.Users/workspace/{workspaceId}/users/retrieveusersby
To retrieve users at the admin-level context, specify -1 as the workspaceId:
<host>/Relativity.Rest/API/Relativity.Users/workspace/-1/users/retrieveusersby
To make a request, use the POST method. Specify the Artifact ID for the workspace containing users that you want to retrieve. Additionally, add a query to the body of the request for filtering on the results, and provide paging information.
The request must include the following fields:
- query - a request object for a query operation with its fields set. It contains the following fields:
- Condition - determines the search criteria. For more information, see Search Relativity.
- Sorts - a list of Sort objects. This list determines the sort order of the results. The Sort class has a Direction property, which can be set to ascending or descending. It also has an Order property, which specifies precedence when multiple sort orders are defined. For more information, see Sort class in the Relativity API reference.
- start - the index of the first artifact in the result set.
- length - the number of items to return in the query result, starting with index in the start field.
{
"query": {
"condition": "('FullName' LIKE ['admin'])",
"sorts": [
{
"Direction": "Ascending",
"FieldIdentifier": {
"Name": "FullName"
}
}
]
},
"start": 1,
"length": 10
}
The response contains the following fields:
- DataResults - represents the results of the query. It contains an array of UserInfo objects with the following fields:
- ArtifactID - a unique identifier for the field, which is represented as an integer.
- FullName - the last name followed by the first name of a user.
- Email - the email address of a user.
- ResultCount - the number of objects returned by the current query. Also, see the description of TotalCount in this list.
- TotalResultCount - the total number of objects in Relativity that meet the criteria of the query. For example, you may request 100 objects, but 115 objects satisfy the query. The ResultCount is 100, while the TotalCount is 115.
- CurrentStartIndex - the index of the first artifact in the result set.
{
"DataResults":[
{
"ArtifactID":1017295,
"FullName":"Admin, Relativity",
"Email":"admin@sample.com"
},
{
"ArtifactID":1017306,
"FullName":"Admin Assistant, Relativity",
"Email":"assistant@sample.com"
}
],
"ResultCount":2,
"TotalResultCount":12,
"CurrentStartIndex":11
}
