Group Manager (REST)

The Group Manager service exposes the API to create, read, update, and delete the groups. Sample use cases for Group Manager API include:

  • creating a new group;
  • adding users to a group;
  • removing users from a group.

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

This page contains the following information:

Fundamentals for managing groups

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.

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: 

<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. 
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 to the following URL:

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

The body of the request contains the following fields:

  • groupRequest - represents a group object. It contains the following fields:
    • Name - the name of the group.
    • Client - represents a client securable object associated with the group. It contains the following fields:
      • Secured - true, if object is secured, false otherwise.
      • Value - represents a client object associated with the group. It contains the following fields:
        • ArtifactID - a unique identifier of the client, which is represented as an integer.
        • Guids - a list of GUIDs identifying the client.
    • Keywords - optional words or phrases used to describe the group.
    • Notes - additional information about the group.

When a request is successful, the response contains the object representing the created group. It contains the following fields:

  • ArtifactID - a unique identifier of the create group, which is represented as an integer.
  • Guids - a list of GUIDs identifying the group.
  • Name - the name of the created group.
  • Client - represents a client securable object associated with the group. It contains the following fields:
    • Secured - true, if object is secured, false otherwise.
    • Value - represents a client object associated with the group. It contains the following fields:
      • ArtifactID - a unique identifier of the client, which is represented as an integer.
      • Guids - a list of GUIDs identifying the client.
      • Name - the name of the client.
  • GroupType - indicates the type of the group:

Note: See table below for values and descriptions of GroupType fields

Name Value Description
System group "SystemGroup" Represents a group of users.
System administrators group "SystemAdmin" Represents the group which contains system administrators.
Everyone group "Everyone" Represents the Everyone group which contains all the users in the system.
  • Keywords - optional words or phrases used to describe the group.
  • Notes - additional information about the group.
  • CreatedOn - the date and time when the group was created.
  • CreatedBy - represents the user who created the group. It contains the following fields:
    • ArtifactID - a unique identifier of the user, which is represented as an integer.
    • Name - the name of the user.
    • Guids - a list of GUIDs identifying the user. 
  • LastModifiedBy - represents the user who recently updated the group. It contains the following fields:
    • ArtifactID - a unique identifier of the user, which is represented as an integer.
    • Name - the name of the user.
    • Guids - a list of GUIDs identifying the user.
  • LastModifiedOn - the date and time when the group was most recently modified.
  • Meta - represents metadata for the current group.
  • Actions - lists available actions for the current group.

JSON request 

{
    "groupRequest": {
        "Client": {
            "Value": {
                "ArtifactID": 1015644
            }
        },
        "Name": "MyGroup",
        "Keywords": "Keywords",
        "Notes": "Notes"
    }
}

JSON response 

{
    "Client": {
        "Secured": false,
        "Value": {
            "Name": "Relativity",
            "ArtifactID": 1015644,
            "Guids": []
        }
    },
    "GroupType": "SystemGroup",
    "Keywords": "Keywords",
    "Notes": "Notes",
    "CreatedOn": "2021-05-21T18:38:39.313",
    "CreatedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedOn": "2021-05-21T18:38:39.313",
    "Meta": {
        "Unsupported": [],
        "ReadOnly": [
            "GroupType"
        ]
    },
    "Actions": [
        {
            "Name": "Delete",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "AddMembers",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "RemoveMembers",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "Name": "MyGroup",
    "ArtifactID": 1029462,
    "Guids": []
}

Read a group

To read the group, send a GET request to the following URL:

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

The response of an Read operation contains the same fields as the response for the Create operation.

{
    "Client": {
        "Secured": false,
        "Value": {
            "Name": "Relativity",
            "ArtifactID": 1015644,
            "Guids": []
        }
    },
    "GroupType": "SystemGroup",
    "Keywords": "Keywords",
    "Notes": "Notes",
    "CreatedOn": "2021-05-21T18:38:39.313",
    "CreatedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedOn": "2021-05-21T18:38:39.313",
    "Name": "MyGroup",
    "ArtifactID": 1029462,
    "Guids": []
}

Update a group

To update the group, send a PUT request to the following URL:

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

JSON request 

{
    "groupRequest": {
        "Client": {
            "Value": {
                "ArtifactID": 1015644
            }
        },
        "Name": "MyGroup",
        "Keywords": "Updated Keywords",
        "Notes": "Updated Notes"
    }
}

JSON response 

{
    "Client": {
        "Secured": false,
        "Value": {
            "Name": "Relativity",
            "ArtifactID": 1015644,
            "Guids": []
        }
    },
    "GroupType": "SystemGroup",
    "Keywords": "Updated Keywords",
    "Notes": "Updated Notes",
    "CreatedOn": "2021-05-21T18:38:39.313",
    "CreatedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedBy": {
        "Name": "user, demo",
        "ArtifactID": 1029460,
        "Guids": []
    },
    "LastModifiedOn": "2021-05-21T18:46:33.13",
    "Meta": {
        "Unsupported": [],
        "ReadOnly": [
            "GroupType"
        ]
    },
    "Actions": [
        {
            "Name": "Delete",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "Update",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "AddMembers",
            "IsAvailable": true,
            "Reason": []
        },
        {
            "Name": "RemoveMembers",
            "IsAvailable": true,
            "Reason": []
        }
    ],
    "Name": "MyGroup",
    "ArtifactID": 1029462,
    "Guids": []
}

Delete a group

To delete a group, send a DELETE request to the following URL:

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

The request body is empty. The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes in Relativity REST APIs.

Query users of a group

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

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

JSON request 

{
    "request": {
        "Fields": [
            {"Name": "Full Name"},
            {"Name": "E-mail Address"}
        ],
        "Condition": ""
    },
    "start": 1,
    "length": 1000
}

JSON response 

{
    "TotalCount": 2,
    "Objects": [
        {
            "ArtifactID": 1029457,
            "Values": [
                "user, test",
                "testuser@mydomain.com"
            ]
        },
        {
            "ArtifactID": 1029460,
            "Values": [
                "user, demo",
                "user@mydomain.com"
            ]
        }
    ],
    "IDWindow": [],
    "CurrentStartIndex": 1,
    "ResultCount": 2,
    "ObjectType": {
        "ArtifactID": 1016184,
        "Name": "User",
        "Guids": [],
        "ArtifactTypeID": 2
    },
    "RankWindow": [],
    "Fields": [
        {
            "FieldCategory": "Generic",
            "FieldType": "FixedLengthText",
            "ViewFieldID": 0,
            "ArtifactID": 0,
            "Guids": [],
            "Name": "Full Name"
        },
        {
            "FieldCategory": "Generic",
            "FieldType": "FixedLengthText",
            "ViewFieldID": 37,
            "ArtifactID": 0,
            "Guids": [],
            "Name": "E-mail Address"
        }
    ]
}

Query groups assigned to a user

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

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

Note: Set the {userID} variable to the Artifact ID of the user.

The request and response fields are similar to those of Querying the users belonging to a group.

Add users to a group

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

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

The body of a request contains the following fields:

  • Users - a list of objects describing the users to add. Each object contains the following fields:
    • ArtifactID - a unique identifier of the user.
    • Guids - a list of GUIDs identifying the user.
{
    "users": [
        { "ArtifactID": 1029457 },
        { "ArtifactID": 1029460 }
    ]
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes in Relativity REST APIs.

Remove users from a group

To remove users from a group, send a DELETE request to the following URL:

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

The body of a request contains the following fields:

  • Users - a list of objects describing the users to remove. Each object contains the following fields:
    • ArtifactID - a uniqued identifier of the user.
    • Guids - a list of GUIDs identifying the user.
{
    "users": [
        { "ArtifactID": 1029457 },
        { "ArtifactID": 1029460 }
    ]
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes in Relativity REST APIs.

Mass add users to groups

To add several users to several groups, send a POST request to the following URL:

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

The body of a request contains the following fields:

  • Users - a list of objects describing the users to add. Each object contains the following fields:
    • ArtifactID - a unique identifier of the user.
    • Guids - a list of GUIDs identifying the user.
  • Groups - a list of objects describing the groups. Each object contains the following fields:
    • ArtifactID - a unique identifier of the group.
    • Guids - a list of GUIDs identifying the group.
{
    "users": [
        { "ArtifactID": 1029457 },
        { "ArtifactID": 1029460 }
    ],
    "groups": [
        { "ArtifactID": 1029462 }
    ]
}

The response contains a list of objects, describing the statuses for each sub-operations. Each object contains the following fields:

  • ArtifactID - a unique identifier of the group.
  • Guids - a list of GUIDs identifying the group.
  • Name - the name of the group.
  • Succeeded - true, if all users were successfully added to the group, false otherwise.
  • Exception - an object describing an error which was encountered while adding the users to the group. 
[
    {
        "Succeeded": true,
        "Name": "MyGroup",
        "ArtifactID": 1029462,
        "Guids": []
    }
]

Mass remove users from groups

To remove several users to several groups, send a DELETE request to the following URL:

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

The body of a request contains the following fields:

  • Users - a list of objects describing the users to add. Each object contains the following fields:
    • ArtifactID - a unique identifier of the user.
    • Guids - a list of GUIDs identifying the user.
  • Groups - a list of objects describing the groups. Each object contains the following fields:
    • ArtifactID - a unique identifier of the group.
    • Guids - a list of GUIDs identifying the group.
{
    "users": [
        { "ArtifactID": 1029457 },
        { "ArtifactID": 1029460 }
    ],
    "groups": [
        { "ArtifactID": 1029462 }
    ]
}

The response contains a list of objects, describing the statuses for each sub-operations. Each object contains the following fields:

  • ArtifactID - a unique identifier of the group.
  • Guids - a list of GUIDs identifying the group.
  • Name - the name of the group.
  • Succeeded - true, if all users were successfully removed from the group, false otherwise.
  • Exception - an object describing an error which was encountered while adding the users to the group. 
[
    {
        "Succeeded": true,
        "Name": "MyGroup",
        "ArtifactID": 1029462,
        "Guids": []
    }
]

Query eligible clients

To query the clients that can be assigned to a group being created or updated, send a POST request to the following URL:

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

JSON request

{
    "request": {
        "Fields": [
            {"Name": "Name"}
        ],
        "Condition": ""
    },
    "start": 1,
    "length": 1000
}

JSON response 

{
    "TotalCount": 3,
    "Objects": [
        {
            "ArtifactID": 1006066,
            "Values": [
                "Relativity Template"
            ]
        },
        {
            "ArtifactID": 1015644,
            "Values": [
                "Relativity"
            ]
        },
        {
            "ArtifactID": 1017451,
            "Values": [
                "Sample Client"
            ]
        }
    ],
    "IDWindow": [],
    "CurrentStartIndex": 1,
    "ResultCount": 3,
    "ObjectType": {
        "ArtifactID": 1016169,
        "Name": "Client",
        "Guids": [],
        "ArtifactTypeID": 5
    },
    "RankWindow": [],
    "Fields": [
        {
            "FieldCategory": "Generic",
            "FieldType": "FixedLengthText",
            "ViewFieldID": 21,
            "ArtifactID": 0,
            "Guids": [],
            "Name": "Name"
        }
    ]
}

Query eligible users

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

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

Note: Set the {groupArtifactID} variable to the Artifact ID of the group.

JSON request 

{
    "request": {
        "Fields": [
            {"Name": "Name"}
        ],
        "Condition": ""
    },
    "start": 1,
    "length": 1000
}

JSON response 

{
    "TotalCount": 2,
    "Objects": [
        {
            "ArtifactID": 1029457,
            "Values": [
                "user, test",
                "testuser@mydomain.com"
            ]
        },
        {
            "ArtifactID": 1029460,
            "Values": [
                "user, demo",
                "user@mydomain.com"
            ]
        }
    ],
    "IDWindow": [],
    "CurrentStartIndex": 1,
    "ResultCount": 2,
    "ObjectType": {
        "ArtifactID": 1016184,
        "Name": "User",
        "Guids": [],
        "ArtifactTypeID": 2
    },
    "RankWindow": [],
    "Fields": [
        {
            "FieldCategory": "Generic",
            "FieldType": "FixedLengthText",
            "ViewFieldID": 0,
            "ArtifactID": 0,
            "Guids": [],
            "Name": "Full Name"
        },
        {
            "FieldCategory": "Generic",
            "FieldType": "FixedLengthText",
            "ViewFieldID": 37,
            "ArtifactID": 0,
            "Guids": [],
            "Name": "E-mail Address"
        }
    ]
}