Group Manager (.NET)

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 REST API. For more information, see Group Manager service.

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 Groups

Methods

The Group Manager API exposes the following methods on the IGroupManager interface in the Relativity.Identity.{versionNumber}.Services namespace:

  • CreateAsync() method - adds a new user group. Its parameter is the GroupRequest object which describes the group to create. It returns the GroupResponse object which contains information about the created group.
  • ReadAsync() method - Retrieves advanced metadata for a user group, including its name, associated client, and other properties. Its parameter is the Artifact ID of the group. It returns the GroupResponse object which contains information about the group.
  • UpdateAsync() method - modifies properties of the user group. Its parameters are the Artifact ID of the group and the GroupRequest object. It returns the GroupResponse object which contains information about the group.
  • DeleteAsync() method - deletes the group. Its parameter is the Artifact ID of the group.
  • QueryMembersAsync() method - retrieves information about the users that belong to the group. Its parameters are QueryRequest object, start index and count of users to return and the Artifact ID of the group. It returns the QueryResultSlim object.
  • AddMembersAsync() method - adds users to the group. Its parameters include the Artifact ID of the group, and a list of user identifiers.
  • RemoveMembersAsync() method - removes users from the group. Its parameters include the Artifact ID of the group, and a list of user identifiers.
  • MassAddUsersToGroupsAsync() method - adds given users to each of the given groups. Its parameters include a list of user identifiers and a list of group identifiers. It returns a list of MassOperationResult objects.
  • MassRemoveUsersFromGroupsAsync() method - removes given users from each of the given groups. Its parameters include a list of user identifiers and a list of group identifiers. It returns a list of MassOperationResult objects.
  • QueryEligibleClients() method - retrieves a list of clients that can be used when creating and updating the group. Its parameters include the QueryRequest object, start index and count of clients to return. It returns the QueryResultSlim object.
  • QueryEligibleUsersToAdd() method - retrieves a list of users that can be added to a given group. Its parameters include the QueryRequest object, start index and count of users to return, and the Artifact ID of the group. It returns the QueryResultSlim object.

Objects

The Group Manager API includes the following classes available in the Relativity.Identity.{versionNumber}.GroupModels namespace.

GroupRequest class - represents the data used to create or update the group, as outlined in the table below:

Field Type Description
Client Securable<ObjectIdentifier> Client identifier associated with a group.
Name string A name of a group.
Keywords string Keywords associated with a group.
Notes string Notes for a group.

GroupResponse class - represents the existing group, as outlined in the table below:

Field Type Description
Client Securable<DisplayableObjectIdentifier> Client identifier associated with a group.
GroupType GroupType enum Group type.
Keywords string Keywords associated with a group.
Notes string Notes for a group.
CreatedOn DateTime A date and time of group creation.
CreatedBy DisplayableObjectIdentifier Identifier of a user that created a group.
LastModifiedBy DisplayableObjectIdentifier Identifier of a user that last modified a group.
LastModifiedOn DateTime A date and time of last modification.
Meta Meta Meta information (a list of read-only and unsupported fields).
Actions List<Action> A list of available actions that can be performed on a group.
ArtifactID int Artifact ID of a group.
Guids List<Guid> A list of Guids associated with a group.
Name string A name of a group.

GroupType enum - represent a type of a group, as outlined in the table below:

Name Value Description
SystemAdmin 1 A group containing system administrators.
SystemGroup 2 A group containing users.
Everyone 3 A special group containing all the users in the system.

Code samples

Querying eligible clients

using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    QueryRequest request = new QueryRequest
    {
        Fields = new List<FieldRef> { new FieldRef { Name = "Name" } },
        Condition = ""
    };
    QueryResultSlim result = await mgr.QueryEligibleClients(request, 1, 1000);
 
    for (int i = 0; i < result.ResultCount; i++)
    {
        Console.WriteLine($"Client {result.Objects[i].Values[0]} with Artifact ID {result.Objects[i].ArtifactID}");
    }
}

Creating a group

int clientArtifactID = 1015644;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    GroupRequest request = new GroupRequest()
    {
        Client = new Securable<ObjectIdentifier>()
        {
            Value = new ObjectIdentifier()
            {
                ArtifactID = clientArtifactID
            }
        },
        Name = "My Group",
        Keywords = "Group keywords",
        Notes = "Group notes"
    };
 
    GroupResponse response = await mgr.CreateAsync(request);
 
    Console.WriteLine($"Created group with ArtifactID {response.ArtifactID}");

Reading a group

int groupArtifactID = 1029453;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    GroupResponse response = await mgr.ReadAsync(groupArtifactID);
 
    Console.WriteLine($"Read group with ArtifactID {response.ArtifactID}");
}

Updating a group

int groupArtifactID = 1029453;
int clientArtifactID = 1015644;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    GroupRequest request = new GroupRequest()
    {
        Client = new Securable<ObjectIdentifier>()
        {
            Value = new ObjectIdentifier()
            {
                ArtifactID = clientArtifactID
            }
        },
        Name = "My Group",
        Keywords = "Updated group keywords",
        Notes = "Updated group notes"
    };
 
    GroupResponse response = await mgr.UpdateAsync(groupArtifactID, request);
 
    Console.WriteLine($"Updated group with ArtifactID {response.ArtifactID}");
}

Deleting a group

int groupArtifactID = 1029455;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    await mgr.DeleteAsync(groupArtifactID);
 
    Console.WriteLine($"Delete group with ArtifactID {groupArtifactID}");
}

Querying group members

int groupArtifactID = 1029453;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    QueryRequest request = new QueryRequest()
    {
        Fields = new List<FieldRef>
        {
            new FieldRef { Name = "Full Name" },
            new FieldRef { Name = "E-mail Address" }
        },
        Condition = "'E-mail Address' == 'testuser@mydomain.com'"
    };
 
    QueryResultSlim result = await mgr.QueryMembersAsync(request, 1, 1000, groupArtifactID);
 
    string emailAddress = result.Objects[0].Values[1].ToString();
 
    Console.WriteLine($"Queried user with email address {emailAddress}");
}

Querying eligible users to add to a group

int groupArtifactID = 1029453;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    QueryRequest request = new QueryRequest
    {
        Fields = new List<FieldRef> { new FieldRef { Name = "Full Name" } },
        Condition = ""
    };
    QueryResultSlim result = await mgr.QueryEligibleUsersToAdd(request, 1, 1000, groupArtifactID);
    for (int i = 0; i < result.ResultCount; i++)
    {
        Console.WriteLine($"User {result.Objects[i].Values[0]} with Artifact ID {result.Objects[i].ArtifactID} is can be added to a group with Artifact ID {groupArtifactID}");
    }
}

Adding users to a group

int groupArtifactID = 1029453;
int userArtifactID = 1029457;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    ObjectIdentifier objIdentifier = new ObjectIdentifier()
    {
        ArtifactID = userArtifactID
    };
 
    await mgr.AddMembersAsync(groupArtifactID, objIdentifier);
 
    Console.WriteLine($"Added user with ArtifactID {userArtifactID}");
}

Removing users from a group

int groupArtifactID = 1029453;
int userArtifactID = 1029457;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    ObjectIdentifier objIdentifier = new ObjectIdentifier()
    {
        ArtifactID = userArtifactID
    };
 
    await mgr.RemoveMembersAsync(groupArtifactID, objIdentifier);
 
    Console.WriteLine($"Removed user with ArtifactID {userArtifactID}");
}

Querying groups that user belongs to

using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    QueryRequest request = new QueryRequest
    {
        Fields = new List<FieldRef> { new FieldRef { Name = "Name" } },
        Condition = ""
    };
    QueryResultSlim result = await mgr.QueryEligibleClients(request, 1, 1000);
 
    for (int i = 0; i < result.ResultCount; i++)
    {
        Console.WriteLine($"Client {result.Objects[i].Values[0]} with Artifact ID {result.Objects[i].ArtifactID}");
    }
}

Mass adding users to groups

int groupArtifactID = 1029453;
int userArtifactID = 1029457;
 
using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = new ServiceFactory(settings).CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
{
    List<ObjectIdentifier> groups = new List<ObjectIdentifier>()
    {
        new ObjectIdentifier() { ArtifactID = groupArtifactID }
    };
 
    List<ObjectIdentifier> users = new List<ObjectIdentifier>()
    {
        new ObjectIdentifier() { ArtifactID = userArtifactID }
    };
 
    List<MassOperationResult> result = await mgr.MassAddUsersToGroupsAsync(users, groups);
}

Mass removing users from groups

public static async Task MassRemoveUsersFromGroups()
{
    int groups = new List<ObjectIdentifier>
    {
        new ObjectIdentifier { ArtifactID = 1015005 },
        new ObjectIdentifier { ArtifactID = 1015028 }
    };
    int users = new List<ObjectIdentifier>
    {
        new ObjectIdentifier { ArtifactID = 1026730 },
        new ObjectIdentifier { ArtifactID = 1026732 }
    };
 
    using (Relativity.Identity.{versionNumber}.Services.IGroupManager mgr = ServiceFactory.CreateProxy<Relativity.Identity.{versionNumber}.Services.IGroupManager>())
    {
        List<MassOperationResult> results = await groupManager.MassRemoveUsersFromGroupsAsync(users, groups);
        for each (MassOperationResult result in results)
        {
            if (result.Succeeded)
            {
                Console.WriteLine($"Users removed from a group with Artifact ID {result.ArtifactID}");
            }
            else
            {
                Console.WriteLine($"Failed to remove users from a group with Artifact ID {result.ArtifactID}: {result.Exception.Message}");
            }
        }
    }
}