

Last date modified: June 17 2025
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:
As a sample use case, you could use the Choice Manager API to create choices used to perform specific operations in a custom application.
You can also use the Choice Manager API through REST. For more information, see Choice Manager (REST).
Review the following information to learn about the methods, classes, and enumerations used by the Choice Manager API.
The Choice Manager API includes the following methods available on the IChoiceManager interface in the Relativity.ObjectModel.<VersionNumber>.Choice namespace.
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.
The Choice Manager API includes the following classes and enumerations:
Use these guidelines when working with choice fields:
The following code sample illustrates how to create a single choice asynchronously using the CreateAsync() method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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);
}
}
The following code sample illustrates how to mass create choices asynchronously using the CreateAsync() method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
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);
}
}
The following code sample illustrates how to read a single choice asynchronously using the ReadAsync() method. (To list the choices for a field, see Object Rule Manager service.)
1
2
3
4
5
6
7
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104636;
ChoiceResponse choiceResponse = await choiceManager.ReadAsync(workspaceID, choiceID);
}
The following code sample illustrates how to use the UpdateAsync() method modify information on a choice without performing a version check.
After the choice is created, you cannot change the field associated with it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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);
}
}
The following code sample uses the UpdateAsync() method modify information on a choice. It performs a version check before applying the update. The update succeeds if the version token in the request matches that of the choice object in the environment. If the version tokens do not match, a status code 409 Conflict is returned.
After the choice is created, you cannot change the field associated with it.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
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);
}
The following code sample illustrates how to use the UpdateAsync() method to modify multiple choices as a mass operation.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
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);
}
}
The following code sample illustrates how to delete a single choice asynchronously.
1
2
3
4
5
6
7
8
9
10
public async Task DeleteChoiceAsync()
{
using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
int workspaceID = 1022092;
int choiceID = 1104642;
await choiceManager.DeleteAsync(workspaceID, choiceID);
}
}
The following code sample illustrates how to mass delete choices asynchronously using the DeleteAsync() method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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);
}
}
The following code sample illustrates how to sort choices under the specified field in the specified direction using the SortAsync () method.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
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);
}
}
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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);
}
}
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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);
}
}
You can retrieve a list of available parents as follows:
Use the GetColorsListAsync() method to retrieve a list of colors that can be assigned to choices. See the code sample for Create a single choice.
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |