Group Manager (.NET)

The Group Manager API exposes the following methods on the IGroupManager interface in the Relativity.Identity.<VersionNumber>.Services namespace.

Note: The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.

• AddMembersAsync() method - adds users to the group. Its parameters include the Artifact ID of the group, and a list of user identifiers. See Add users to a group.
• CreateAsync() method - adds a new group to Relativity. This method takes a GroupRequest object and returns a GroupResponse object. See Create a group.
• DeleteAsync() method - removes a group from Relativity. This method takes the Artifact ID of the group. See Delete a group.
• MassAddUsersToGroupsAsync() method - adds multiple users to multiple groups. Its parameters include a list of user identifiers and a list of group identifiers. It returns a list of MassOperationResult objects. See Add multiple users to multiple groups.
• MassRemoveUsersFromGroupsAsync() method - removes multiple users from multiple groups. Its parameters include a list of user identifiers and a list of group identifiers. It returns a list of MassOperationResult objects. See Remove multiple users from multiple groups.
• QueryEligibleClients() method - retrieves a list of clients available for use when creating and updating a group. Its parameters include a QueryRequest object, a start index, and the number of clients to return. It returns a QueryResultSlim object. See Query for clients to associate with a group.

Note: The Object Manager API also uses QueryResultSlim objects. For more information about these objects, see Object Manager (.NET).

• QueryEligibleUsersToAdd() method - retrieves a list of users that can be added to a group. Its parameters include a QueryRequest object, a start index, the number of users to return, and the Artifact ID of a group. It returns a QueryResultSlim object. See Query for users to add to a group.
• QueryMembersAsync() method - retrieves information about the users assigned to a group. Its parameters are a QueryRequest object, a start index, the number of users to return, and the Artifact ID of a group. It returns a QueryResultSlim object. See Query for group members.
• ReadAsync() method - retrieves 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. See Retrieve a group.
• RemoveMembersAsync() method - removes users from a group. Its parameters include the Artifact ID of the group, and a list of user identifiers. See Remove users from a group.
• UpdateAsync() method - modifies properties of a group. Its parameters are the Artifact ID of the group and the GroupRequest object. It returns the GroupResponse object. See Update a group.

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. See the following properties:

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

• GroupResponse class - represents the existing group. See the following properties:

Field	Type	Description
Client	Securable<DisplayableObjectIdentifier>	A client identifier associated with a group.
GroupType	GroupType enum	The type of the group.
Keywords	string	Keywords associated with a group.
Notes	string	Notes about the group.
CreatedOn	DateTime	The date and time of group creation.
CreatedBy	DisplayableObjectIdentifier	The identifier for the user who created the group.
LastModifiedBy	DisplayableObjectIdentifier	The identifier for the user who last modified the group.
LastModifiedOn	DateTime	The date and time of last modification.
Meta	Meta	Metadata for the group, including 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	The Artifact ID of the group.
Guids	List<Guid>	A list of Guids associated with the group.
Name	string	The name of the group.

• GroupType enum - represent the type of a group. See the following enums:

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

int clientArtifactID = 1015644;
 
using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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}");

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

You can pass optional CancellationToken and IProgress<ProgressReport> objects to this overloaded method.

int groupArtifactID = 1029453;
int clientArtifactID = 1015644;
 
using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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}");
}

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

You can pass optional CancellationToken and IProgress<ProgressReport> objects to this overloaded method.

int groupArtifactID = 1029453;
 
using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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}");
}

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

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

You can pass optional CancellationToken and IProgress<ProgressReport> objects to this overloaded method.

using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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}");
    }
}

You can pass optional CancellationToken and IProgress<ProgressReport> objects to this overloaded method.

int groupArtifactID = 1029453;
 
using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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}");
    }
}

using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<IGroupManager>())
{
    QueryRequest request = new QueryRequest
    {
        Fields = new List<FieldRef> { new FieldRef { Name = "Name" } },
        Condition = ""
    };
    QueryResultSlim result = await mgr.QueryMembersAsync(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}");
    }
}

int groupArtifactID = 1029453;
int userArtifactID = 1029457;
 
using (IGroupManager mgr = new ServiceFactory(settings).CreateProxy<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);
}

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 (IGroupManager mgr = ServiceFactory.CreateProxy<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}");
            }
        }
    }
}