In Relativity, choices are predetermined values of single and multi-choice list fields. You can perform operations on admin and workspace choices. For more general information, see
The Choice Manager API exposes multiple operations you can use to programmatically manage choices in your Relativity environment. It includes the following features:
- Supports create, read, update, and delete operations and massive operations on choices.
- Provides helper methods used to retrieve choice types and choice servers. Use these methods to determine if a server supports the choice type that you want to add to it.
A sample use case for the Choice Manager API service is a custom application that includes choices you want to perform operations with.
You can also use the Choice Manager service through the REST API. For more information, see Choice Manager service.
This page contains the following information:
Fundamentals for managing choices
Review the following information to learn about the Choice Manager service.
Guidelines and considerations
- Multi-choice fields allow choices to be arranged in a hierarchical fashion. For instance a choice of Important might have child a choices of Critical. Selecting the child choice on a field (in the RDO layout) will also cause the parent choice to be selected.
- Single-choice fields do not allow for this arrangement of choices. As such, some of the endpoints only apply to multi-choice fields, or choices that are associated with multi-choice fields. Examples of this are the GetAvailableParentListAsync() methods. Requests to these made to these endpoints that reference single-choice fields will result in a status code 422 (unprocessable entity) response. See the method description details below for which methods are multi-choice only.
Methods
The IChoiceManager interface in the Relativity.ObjectModel.<VersionNumber>.Choice namespace exposes the following methods:
Note: The <VersionNumber> variable indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 in .NET.
- CreateAsync() method - adds a new choice to a Relativity environment. It returns the Artifact ID of the new choice. To create a choice, pass a ChoiceRequest object to the method. To mass create choices, pass a MassCreateChoiceRequest object to the method. It returns a MassCreateChoiceResponse object.
- ReadAsync() method - retrieves information about a choice. To retrieve a choice, pass a valid choice Artifact ID or GUID. It returns a ChoiceResponse object.
- UpdateAsync() method - modifies one or more choices. To update a choice, pass a ChoiceRequest object and valid choice Artifact ID or GUID to the method. To mass update choices, pass a MassUpdateChoiceRequest object to the method. It returns a MassActionChoiceResponse object.
- DeleteAsync() method - removes one or more choices from Relativity. To delete a choice, pass a valid choice Artifact ID or GUID to the method. To mass delete choices, pass a MassDeleteChoiceRequest object to the method. It returns a MassActionChoiceResponse object.
- AvailableParentsListAsync() method - retrieves a list of available parents for a specific choice or field.
- GetColorsListAsync() method - retrieves a list of colors that can be assigned to a choice.
- SortAsync() method - sorts a list of choices. To alphabetically sort all choices in a field, pass a valid field Artifact ID and a ChoiceReorderTypeEnum object. It returns a MassActionChoiceResponse object.
- MoveAsync() method - moves one or more choices in a list. To move a choice(s) to the beginning or end, pass a valid field Artifact ID, a list of ObjectIdentifier, and a ChoiceMoveTypeEnum object. To move a choice(s) after a specific choice, pass a valid field Artifact ID, a list of ObjectIfentifier, and an ObjectIdentifier object that represents the specific choice. It returns a MassActionChoiceResponse object.
Classes
The following classes are used by the Choice Manager API:
- ChoiceRequest class - used to specify information for creating or updating a choice.
- Field - identifies which field the choice is associated with.
- Name - name of field.
- Color - color of field.
- Order - field order. Used to determine order in which multiple choices are listed in UI. Lower values are listed first.
- ChoiceResponse class - represents the results of a read operation on a choice.
- MassActionChoiceResponse class - represents the result summary of both a massive delete or a massive update of choices.
- MassCreateChoiceRequest class - represents the request to create multiple choices at once.
- Choices - list of choices to be created. For single choice fields this must be a flat list of choices (choices cannot have child choices). In the case of multi-choice fields the list can be hierarchical. Each choice can have child choices, each of which in turn can have their own child choices, etc. Note that it's only possible to specify the choice name property with mass create.
- ChoiceTemplateData - information to be applied to all the created choices.
- MassCreateChoiceResponse class - represents the result summary of both massive create choices.
- MassDeleteChoiceRequest class - represents a request to delete multiple choices.
- MassUpdateChoiceRequest class - represents data model for choice massive update request.
Enumerations
- WorkspaceID - ArtifactID of the workspace containing the choice. Use -1 to refer to the admin workspace.
- ChoiceID - the ArtifactID of the choice to update.
- ChoiceGuid - the ArtifactGuid of the choice to update.
- ObjectVersionToken - the version token of the choice being updated. The token is generated from the choice object's last-modified-on time stamp.
- ChoiceObjectIdentifiers - Choices to be moved.
- MoveListTo - an enumeration specifying whether to move the designated choices to the beginning or end of the list of choices under the field. Options are "Beginning" or "End".
- SortType - an enumeration specifying the sort order (i.e., ascending or descending).
- FieldIdentifier - the object identifier (ArtifactID or GUID) of the field for retrieving the parent choices.
Create a single choice
Click to view code sample.
The following code sample illustrates how to create a single choice asynchronously using the CreateAsync() method.
public async Task CreateSingleChoiceAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104632;
// use helper method to get list of available colors
List<Color> colors = await choiceManager.GetColorsListAsync(workspaceID);
ChoiceRequest choiceRequest = new ChoiceRequest()
{
Name = "Relevant",
Field = new ObjectIdentifier() { ArtifactID = fieldID},
Order = 10,
Color = colors.FirstOrDefault(color => color.Name == "Green").ID
};
int choiceID = await choiceManager.CreateAsync(workspaceID, choiceRequest);
}
}
Mass create choices
Click to view code sample.
The following code sample illustrates how to mass create choices asynchronously using the CreateAsync() method.
public async Task CreateMultipleChoicesAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104635;
// This request creates four fields with the following hierarchy:
// + Important
// + Critical
// + Very
// + Somewhat
MassCreateChoiceRequest massCreateRequest = new MassCreateChoiceRequest()
{
Choices = new List<MassCreateChoiceHierarchy>()
{
new MassCreateChoiceHierarchy
{
Name = "Important",
Children = new List<MassCreateChoiceHierarchy>()
{
new MassCreateChoiceHierarchy() {Name = "Critical"}
new MassCreateChoiceHierarchy() {Name = "Very"},
new MassCreateChoiceHierarchy() {Name = "Somewhat"},
}
}
},
ChoiceTemplateData = new MassCreateChoiceModel()
{ // Template data applies to all fields created.
Field = new ObjectIdentifier() { ArtifactID = fieldID },
}
};
MassCreateChoiceResponse choices = await choiceManager.CreateAsync(workspaceID, massCreateRequest);
}
}
Read a choice
Click to view code sample.
The following code sample illustrates how to read a single choice asynchronously using the ReadAsync() method.
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104636;
ChoiceResponse choiceResponse = await choiceManager.ReadAsync(workspaceID, choiceID);
}
Update a choice (no version check)
Click to view code sample.
The following code sample illustrates how to update a choice asynchronously using the UpdateAsync() method.
Note: The field a choice is associated with cannot be changed after the choice has been created.
public async Task UpdateSingleChoiceAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104635;
int choiceID = 1104640;
// retrieve available parents
ObjectIdentifier fieldIdentifier = new ObjectIdentifier() {ArtifactID = fieldID};
List<DisplayableObjectIdentifier> availableParents = await choiceManager.AvailableParentsListAsync(workspaceID, fieldIdentifier);
// Get existing choice information
ChoiceResponse choiceResponse = await choiceManager.ReadAsync(workspaceID, choiceID);
// Move choice under different parent choice
ChoiceRequest choiceRequest = new ChoiceRequest()
{
Name = choiceResponse.ObjectIdentifier.Name,
Color = choiceResponse.Color.ID,
Order = choiceResponse.Order,
Parent = availableParents.FirstOrDefault(parent => parent.Name == "Important")
};
await choiceManager.UpdateAsync(workspaceID, choiceID, choiceRequest);
}
}
Update a choice (with version check)
Click to view code sample.
The following code sample using the using the UpdateAsync() method updates information on the specified choice, but performs a version check before applying the update. If the version token in the request matches that of the choice object in the environment the update will go through. If the version tokens do not match, a status code 409 (conflict) will be returned. Note that the field a choice is associated with cannot be changed after the choice has been created.
public async Task UpdateSingleChoiceWithVersionCheckAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104642;
// retrieve available parents
List<DisplayableObjectIdentifier> availableParents = await choiceManager.AvailableParentsListAsync(workspaceID, choiceID);
// Get existing choice information
ChoiceResponse choiceResponse = await choiceManager.ReadAsync(workspaceID, choiceID);
// Move choice under different parent choice
ChoiceRequest choiceRequest = new ChoiceRequest()
{
Name = choiceResponse.ObjectIdentifier.Name,
Color = choiceResponse.Color.ID,
Order = choiceResponse.Order,
Parent = availableParents.Find(parent => parent.Name == "Important")
};
// Version token is generated from the last-modified-on time stamp.
// If the choice object has been modified since we performed
// the read this updated will fail.
string versionToken = choiceResponse.LastModifiedOn.Ticks.ToString(CultureInfo.InvariantCulture);
await choiceManager.UpdateAsync(workspaceID, choiceID, choiceRequest, versionToken);
}
Mass update choices
Click to view code sample.
The following code sample mass updates information on the specified choices using the UpdateAsync() method.
public async Task UpdateMultipleChoicesAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104632;
int choiceID1 = 1104640;
int choiceID2 = 1104641;
// Get existing choice information
ChoiceResponse choice1 = await choiceManager.ReadAsync(workspaceID, choiceID1);
ChoiceResponse choice2 = await choiceManager.ReadAsync(workspaceID, choiceID2);
MassUpdateChoiceRequest[] massUpdateRequest = new MassUpdateChoiceRequest[]
{
new MassUpdateChoiceRequest()
{
ObjectIdentifier = choice1.ObjectIdentifier,
Name = "Privileged",
Color = choice1.Color.ID
},
new MassUpdateChoiceRequest()
{
ObjectIdentifier = choice2.ObjectIdentifier,
Name = "Confidential",
Color = choice2.Color.ID
}
};
MassActionChoiceResponse response = await choiceManager.UpdateAsync(workspaceID, massUpdateRequest);
}
}
Delete a choice
Click to view code sample.
The following code sample illustrates how to delete a single choice asynchronously.
public async Task DeleteChoiceAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104642;
await choiceManager.DeleteAsync(workspaceID, choiceID);
}
}
Mass delete choices
Click to view code sample.
The following code sample illustrates how to mass delete choices asynchronously using the DeleteAsync() method.
public async Task DeleteMultipleChoicesAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
MassDeleteChoiceRequest massDelete = new MassDeleteChoiceRequest()
{
ChoiceIDs = new List<ObjectIdentifier>()
{
new ObjectIdentifier() {ArtifactID = 1104641},
new ObjectIdentifier() {ArtifactID = 1104642},
new ObjectIdentifier() {ArtifactID = 1104643},
}
};
await choiceManager.DeleteAsync(workspaceID, massDelete);
}
}
Sort choices
Click to view code sample.
The following code sample illustrates how to sort choices under the specified field in the specified direction using the SortAsync () method.
public async Task SortChoicesAsync()
{
// Assuming the choices under this field are organized as follows:
// + Privileged
// + Important
// + Critical
// + Very
// + Somewhat
//
// After this ascending sort request they will be organized as follows:
// + Important
// + Critical
// + Somewhat
// + Very
// + Privileged
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104635;
MassActionChoiceResponse sortResponse = await choiceManager.SortAsync(workspaceID, choiceID, sortType: SortDirection.Ascending);
}
}
Move choices to start or end of list
Click to view code sample.
The following code sample illustrates how to move a set of choices to either the start or end of the list of choices under a specific field using the MoveAsync() method by passing it the WorkspaceID, ChoiceObjectIdentifiers, and MoveListTo parameters.
public async Task MoveChoiceListAsync()
{
// Assuming the choices under this field were organized as follows:
// + Privileged
// + Important
// + A
// + B
// + C
//
// After this sort request they will be organized as follows:
// + C
// + B
// + A
// + Privileged
// + Important
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104635;
ObjectIdentifier[] choicesToMove = new ObjectIdentifier[]
{
new ObjectIdentifier() {ArtifactID = 1104650}, // Choice "A"
new ObjectIdentifier() {ArtifactID = 1104651}, // Choice "B"
new ObjectIdentifier() {ArtifactID = 1104652}, // Choice "C"
};
MassActionChoiceResponse sortResponse = await choiceManager.MoveAsync(workspaceID, fieldID, choicesToMove, ChoiceMoveType.Beginning);
}
}
Move choices after a specific choice in a list
Click to view code sample.
The following code sample illustrates how to move a choice after a specific choice in a list of choices using the MoveAsync() method by passing it the WorkspaceID, ChoiceObjectIdentifiers, and ChoiceID parameters.
public async Task MoveChoiceListAsync()
{
// Assuming the choices under this field were organized as follows:
// + C
// + B
// + A
//
// After this sort request they will be organized as follows:
// + A
// + B
// + C
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int fieldID = 1104635;
ObjectIdentifier choiceIdentifier = new ObjectIdentifier() {ArtifactID = 1104650 }; // Choice "A"
ObjectIdentifier[] choicesToMove = new ObjectIdentifier[]
{
new ObjectIdentifier() {ArtifactID = 1104651}, // Choice "B"
new ObjectIdentifier() {ArtifactID = 1104652}, // Choice "C"
};
MassActionChoiceResponse sortResponse = await choiceManager.MoveAsync(workspaceID, fieldID, choicesToMove, choiceIdentifier);
}
}
Retrieve a list of available parents
Click to view code sample.
You can retrieve a list of available parents for a specific choice by passing the AvailableParentsListAsync() method a WorkspaceID, ChoiceGuid, and ChoiceID.
See the code sample for Update a choice (single choice update) for an example of how to use this endpoint.
You can retrieve a list of available parents for a specific field by passing the AvailableParentsListAsync() method a WorkspaceID and FieldIdentifier.
See the code sample for Update a choice (with version check) for an example of how to use this endpoint.
Retrieve a list of available colors
Click to view code sample.
You can retrieve a list of available colors that can be assigned to choices using the GetColorsListAsync() method.
See the code sample for the Create a single choice endpoint for an example of how to use this endpoint.
