Within Relativity, you can use groups to organize users. You can then assign a specific set of permissions to each group. For more information, see Groups on the Relativity Documentation site.
The Services API supports create, read, delete, and query operations on a Group DTO.
Note: You can also perform a full set of CRUD operations on groups using the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.
This page contains the following information:
Create a Group
You can add a Group to Relativity by calling the Create() method on the Group repository as illustrated in this code sample. See Fields used by Group and User objects.
public static bool Create_Group(IRSAPIClient proxy)
{
// STEP 1: Create a DTO and set its properties.
DTOs.Group newGroup = new DTOs.Group();
newGroup.Name = "Sample Group";
// STEP 2: Create a WriteResultSet. It provide details after the create operation completes.
WriteResultSet<DTOs.Group> resultSet = new WriteResultSet<DTOs.Group>();
// STEP 3: Create the new Group.
try
{
resultSet = proxy.Repositories.Group.Create(newGroup);
}
catch (Exception ex)
{
Console.WriteLine("An error occurred: {0}", ex.Message);
return false;
}
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine("The Create operation failed.{0}{1}",Environment.NewLine, resultSet.Message);
return false;
}
// Output the results.
Console.WriteLine("The Create succeeded.");
DTOs.Group createdGroup = resultSet.Results[0].Artifact;
Console.WriteLine("{0}The Artifact of the New Group is: {1}", Environment.NewLine, createdGroup.ArtifactID);
// Console.WriteLine("The name of the Group is: {0}", createdGroup.GroupName);
return true;
}
Read a Group
To read Field values, you can use the Read() method on the Group repository as illustrated in this code sample.
public static bool Read_Group(IRSAPIClient proxy)
{
// STEP 1: Create a DTO with criteria you want to read.
DTOs.Group groupToRead = new DTOs.Group(1016219);
groupToRead.Fields = FieldValue.AllFields;
// STEP 2: Create ResultSet to store Results.
ResultSet<DTOs.Group> resultSet = new ResultSet<DTOs.Group>();
// STEP 3: Perform the read operation.
try
{
resultSet = proxy.Repositories.Group.Read(groupToRead);
}
catch (Exception ex)
{
Console.WriteLine("An error occurred: {0}", ex.Message);
return false;
}
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine("The Read operation failed.{0}{1}", Environment.NewLine, resultSet.Message);
return false;
}
// Output the results.
Console.WriteLine("Read completed successfully.");
DTOs.Group readGroup = resultSet.Results[0].Artifact;
SampleHelpers.APIHelpers.Print_All_Properties(readGroup);
return true;
}
Update a Group
You can use the Update() on the Group repository to modify its properties as illustrated in this code sample. See Fields used by Group and User objects.
public static bool Update_Group(IRSAPIClient proxy)
{
// STEP 1: Create DTO, and set its properties.
DTOs.Group newGroup = new DTOs.Group(1016219);
newGroup.Name = "Sample Group";
// STEP 2: Create a WriteResultSet. It provides details after the update operation.
WriteResultSet<DTOs.Group> resultSet = new WriteResultSet<DTOs.Group>();
// STEP 3: Perform the update operation.
try
{
resultSet = proxy.Repositories.Group.Update(newGroup);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine("The Update operation failed.{0}{1}",Environment.NewLine, resultSet.Message);
return false;
}
Console.WriteLine("Updated completed successfully.");
DTOs.Group updatedGroup = resultSet.Results[0].Artifact;
// Console.WriteLine("The updated name of the Group is: {0}", updatedGroup.GroupName);
return true;
}
Delete a Group
You can remove a Group from Relativity by calling the Delete() method on the Group repository as illustrated in this code sample.
public static bool Delete_Group(IRSAPIClient proxy)
{
// STEP 1: Create a DTO populated with criteria for a DTO you want to delete.
DTOs.Group groupToDelete = new DTOs.Group(1016219);
// STEP 2: Create a WriteResultSet. It provides details after the delete operation completes.
WriteResultSet<DTOs.Group> resultSet = new WriteResultSet<DTOs.Group>();
// STEP 3: Perform the delete operation.
try
{
resultSet = proxy.Repositories.Group.Delete(groupToDelete);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine("The Delete operation failed.{0}{1}",Environment.NewLine, resultSet.Message);
return false;
}
// Output the results.
Console.WriteLine("Delete completed successfully.");
DTOs.Group deletedGroup = resultSet.Results.ElementAt(0).Artifact;
Console.WriteLine("The Artifact ID of the deleted Group is: {0}", deletedGroup.ArtifactID);
return true;
}
Query for a Group
This code sample illustrates how to set query conditions, call the Query() method on the Group repository, and iterate through the result set.
public static bool Query_Group(IRSAPIClient proxy)
{
// STEP 1: Create a Query and ObjectsCondition. It provides details after the query operation.
ObjectsCondition workspaceCondition =
new ObjectsCondition(GroupFieldNames.Workspaces, ObjectsConditionEnum.AnyOfThese, new Int32[] { 1016204 });
Query<DTOs.Group> query = new DTOs.Query<DTOs.Group> { Condition = workspaceCondition };
query.Fields = FieldValue.AllFields;
// STEP 2: Create QueryResultSet to collect information about the DTO after the query completes.
QueryResultSet<DTOs.Group> resultSet = new QueryResultSet<DTOs.Group>();
// STEP 3: Perform the query.
try
{
resultSet = proxy.Repositories.Group.Query(query, 0);
}
catch (Exception ex)
{
Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
return false;
}
// Check for success.
if (!resultSet.Success)
{
Console.WriteLine("The Query operation failed.{0}{1}", Environment.NewLine, resultSet.Message);
return false;
}
// Output the results.
Console.WriteLine(string.Format("Number of Groups returned: {0}", resultSet.Results.Count));
foreach (DTOs.Result<DTOs.Group> groupResult in resultSet.Results)
{
Console.WriteLine(string.Format("{0}Name:{1}", Environment.NewLine, groupResult.Artifact.Name));
Console.WriteLine(string.Format("ArtifactID:{0}", groupResult.Artifact.ArtifactID));
}
return true;
}
Multi-tenancy
With the introduction of support for multi-tenancy, Client becomes the parent of the Group object. Use the following guidelines when interacting with Groups using the Services API:
- The Client property is not required when creating or updating Group. If the Client is not explicitly specified for a Group, the Client value is set to the default Relativity Client.
Note: Client is a required field when creating new Groups through the Relativity UI.
- On upgrade existing groups are assigned the default Relativity Client.
- If an existing client becomes a tenant and there are groups where all users are associated with the tenant (except SysAdmin), then the groups are assigned the tenant's Client ID.
