Group Manager (REST)

In Relativity, you can organize users by assigning them to one or more groups. Additionally, you can set permissions for a group. For more information, see Groups in the Relativity Documentation site.

The Group Manager service exposes endpoints that provide the following functionality:

  • CRUD and query operations on groups.
  • Helper endpoints for adding and removing users.
  • Helper endpoints for querying on available users and clients to associate with a group.
  • Mass operations for adding and removing multiple users to or from multiple groups.

As a sample use case, you might create an application with a custom interface for adding multiple users with a mass operation.

You can also use the Group Manager service through .NET. For more information, see Group Manager (.NET).

Guidelines for the Group Manager service

Review the following guidelines for working with the Group Manager service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1 or v2
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.

    • Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to retrieve a group:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}?includeMetadata=true&includeActions=true

Set the path parameters as follows:

  • {versionNumber} to the version of the service, such as v1.
  • {groupArtifactID} to the Artifact ID of the group.

Client code sample

To use the Group Manager service, send requests by making calls with the required HTTP methods. See the following base URL for this service:

Copy 
<host>/Relativity.REST/api/Relativity.Groups/workspace/{workspaceID}/groups/

You can use the following C# code as a sample client for creating a group. This code illustrates how to perform the following tasks:

  • Instantiate an HttpClient object for sending requests to the Group Manager service.
  • Set the required headers for the request. For more information, see HTTP headers.
  • Set the URL required for the operation.
  • Set the JSON payload required for the operation.
  • Use the PostAsync() method to send a POST request.
  • Return the artifact ID of the created group.
Copy 
private HttpClient GetHttpClient()
{
    HttpClient httpClient = new HttpClient();
 
    httpClient.BaseAddress = new Uri("https://localhost/");
    httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
    httpClient.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test.user@mydomain.com:Password")));
 
    return httpClient;
}
 
public async Task<List<int>> GetEligibleClientIDs()
{
    string url = "/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/query-eligible-clients";
    var payload = new
    {
        request = new
        {
            Fields = new[]
            {
        new { Name = "*" }
    }
        },
        start = 1,
        length = 100
    };
 
    string payloadString = JsonConvert.SerializeObject(payload);
    var content = new StringContent(payloadString, Encoding.UTF8, "application/json");
 
    HttpClient httpClient = GetHttpClient();
    HttpResponseMessage response = await httpClient.PostAsync(url, content);
    string resultString = await response.Content.ReadAsStringAsync();
 
    var clientIDs = new List<int>();
 
    dynamic result = JObject.Parse(resultString) as JObject;
    foreach (var obj in result.Objects)
    {
        int clientID = obj.ArtifactID;
        clientIDs.Add(clientID);
    }
 
    return clientIDs;
}
 
public async Task<int> Create(int clientID)
{
    string url = "Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/";
    var payload = new
    {
        groupRequest = new
        {
            Name = "Sample group name",
            Client = new
            {
                Value = new { ArtifactID = clientID }
            },
            Keywords = "Sample keywords",
            Notes = "Sample notes"
        }
    };
 
    string payloadString = JsonConvert.SerializeObject(payload);
    var content = new StringContent(payloadString, Encoding.UTF8, "application/json");
 
    HttpClient httpClient = GetHttpClient();
    HttpResponseMessage message = await httpClient.PostAsync(url, content);
    string resultString = await message.Content.ReadAsStringAsync();
 
    dynamic result = JObject.Parse(resultString) as JObject;
    int artifactID = result.ArtifactID;
 
    return artifactID;
}

Create a group

To create a group, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/

Retrieve a group

To retrieve a group, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}?includeMetadata=true&includeActions=true

The request body is empty.

The response for a read operation contains the same fields as a response for a create operation. See the descriptions in View field descriptions for a create response.

Update a group

To update a group, send a PUT request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}

The response for an update operation contains the same fields as a response for a create operation. See the descriptions in View field descriptions for a create response.

Delete a group

To delete a group, send a DELETE request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}

The request body is empty.

When the group is successfully deleted, the response returns the status code of 200.

Add users to a group

To add users to a group, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}/members

When the users are successfully added, the response returns the status code of 200.

Remove users from a group

To remove users from a group, send a DELETE request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}/members

When the users are successfully deleted, the response returns the status code of 200.

Helper methods for users and clients

The Group Manager service exposes multiple helper methods that you can use to query for information about users and clients.

Query for clients to associate with a group

To query the clients that can be assigned to a group, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/eligible-clients/query

Query for users to add to a group

To query the users that can be added to a group, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}/eligible-members/query

The response for this query contains the same fields as a response for a query on clients. See the descriptions in View field descriptions for a query response.

Query for group members

To query for users that belong to a group, send a POST request with a URL in the following format:

Copy 
<host>Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/{groupArtifactID}/query-members

Query groups assigned to a user

To query the groups that are assigned to a user, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/query-by-user/{userID}

This query uses the same request and response fields as Query for group members.

Mass operations on groups

You can use mass operations to add or remove multiple users to or from multiple groups in a single API call.

Add multiple users to multiple groups

To add multiple users to multiple groups, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/members

Remove multiple users from multiple groups

To remove multiple users from multiple groups, send a DELETE request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/groups/members