Choice Manager API

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 Choices in the Relativity Documentation site.

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 methods, classes, and other entities used by the Choice Manager service.

Methods

In the Relativity Services API, the Relativity.Services.Interfaces namespace contains the IChoiceManager interface that exposes the following methods:

  • Create a choice - 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.
  • GetAvailableParentsListAsync() 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 and enumerations

Relativity.Services.Interfaces.Choice.Models namespace contains the following classes and enumerations used by the Choice Manager API:

  • ChoiceMoveTypeEnum class - identifies the position in the whole list of choices of a field where a subset of choices could be relocated.
  • ChoiceReorderTypeEnum class - identifies the type of sort applied to a list of choices.
  • ChoiceRequest class - represents a DTO used as a request for creating or updating a choice.
  • 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.
  • MassChoiceProgressResport class - represents a snapshot report of progress in a choice mass operation.
  • MassCreateChoiceModel class - represents data model for choice information of a massive create operation.
  • MassCreateChoiceRequest class - represents the request to create multiple choices at once.
  • MassCreateChoiceResponse class - represents the result summary of both massive create choices.
  • MassCreateChoiceStructure class - represents choice abstraction used to define hierarchy of choices to be created when a mass creation operation is performed.
  • MassCreatedChoice class - represents data model for choice information returned by massive create operation.
  • MassDeleteChoiceRequest class - represents a request to delete multiple choices.
  • MassUpdateChoiceRequest class - represents data model for choice massive update request.

Create a choice

The following code sample illustrates how to create a single choice asynchronously with the IChoiceManager interface using the await pattern.

public async Task<int> CreateChoiceAsync(IHelper helper, int workspaceID){
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
		ChoiceRequest choiceRequest = new ChoiceRequest();
		// This field will contain the new choice
		choiceRequest.Field = new Relativity.Services.Interfaces.Shared.Models.ObjectIdentifier() { ArtifactID = 1234567 };
		choiceRequest.Name = "Choice Tester 2";
		choiceRequest.Color = 3;
		choiceRequest.Keywords = "";
		choiceRequest.Notes = "";
		return await choiceManagerProxy.CreateAsync(workspaceID, choiceRequest);
        }
        catch (Exception exception)
        {
		logger.LogError(exception, "The Choice could not be created.");
        }
    }
    return null;
}

The following code sample illustrates how to mass create choices asynchronously with the IChoiceManager interface using the await pattern. 

public async Task<MassCreateChoiceResponse> MassCreateAsync(IHelper helper, int workspaceID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            MassCreateChoiceStructure<string> choiceOne = new MassCreateChoiceStructure<string>
            {
                Name = "Choice 1",
                //The childrens will be created if the field type is MultipleChoice
                Children = new List<MassCreateChoiceStructure<string>>() {
                new MassCreateChoiceStructure<string>() { Name = "Choice 1.1" },
                new MassCreateChoiceStructure<string>() { Name = "Choice 1.2" }
                }
            };
            MassCreateChoiceStructure<string> choiceTwo = new MassCreateChoiceStructure<string>
            {
                 Name = "Choice 2"
            };
            MassCreateChoiceRequest massCreateRequest = new MassCreateChoiceRequest
            {
                Choices = new List<MassCreateChoiceStructure<string>> { choiceOne, choiceTwo },
                ChoiceTemplateData = new MassCreateChoiceModel()
                {
                    Field = new Interfaces.Shared.Models.ObjectIdentifier()
                    {
                        ArtifactID = fieldDTO.ArtifactID
                    },
                    Keywords = "",
                    Notes = "",
                    RelativityApplications = new List<Interfaces.Shared.Models.ObjectIdentifier>()
                }
            };
            return await choiceManagerProxy.CreateAsync(workspaceID, massCreateRequest);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choices could not be created.");
        }
    }
    return null;
}

Read a choice

The following code sample illustrates how to read a single choice asynchronously with the IChoiceManager interface using the await pattern.

public async Task<ChoiceResponse> ReadChoiceAsync(IHelper helper, int workspaceID, int choiceID, bool includeMetadata, bool includeActions)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.ReadAsync(workspaceID, choiceID, includeMetadata, includeActions);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choice could not be read.");
        }
    }
    return null;
}

Update a choice

The following code sample illustrates how to mass update choices asynchronously using the IChoiceManager interface with await pattern.

public async Task UpdateChoiceAsync(IHelper helper, int workspaceID, int choiceID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            	ChoiceRequest choiceRequest = new ChoiceRequest();
            	// This field will contain the new choice
		choiceRequest.Field = new Relativity.Services.Interfaces.Shared.Models.ObjectIdentifier() { ArtifactID = 1234567 };
		choiceRequest.Name = "Choice Update";
            	choiceRequest.Color = 3;
            	choiceRequest.Keywords = "";
            	choiceRequest.Notes = "";
            	choiceRequest.KeyboardShortcut = new Interfaces.Shared.Models.KeyboardShortcutCombination()
            {
               Alt = false,
               Ctrl = true,
               Shift = false,
               Key = 14
            };
         	await choiceManagerProxy.UpdateAsync(workspaceID, choiceID, choiceRequest);
        }
        catch (Exception exception)
        {
            	_logger.LogError(exception, "The Choice could not be updated.");
        }
    }
}

The following code sample illustrates how to update a single choice asynchronously using the IChoiceManager interface with await pattern.

Delete a choice

The following code sample illustrates how to delete a single choice asynchronously using the IChoiceManager interface with await pattern.

public async Task DeleteChoiceAsync(IHelper helper, int workspaceID, int choiceID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            await choiceManagerProxy.DeleteAsync(workspaceID, choiceID);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choice could not be deleted.");
        }
    }
}

The following code sample illustrates how to mass delete choices asynchronously with the IChoiceManager interface using the await pattern. 

public async Task<MassActionChoiceResponse> MassDeleteAsync(IHelper helper, int workspaceID, List<ObjectIdentifier> choicesID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            MassDeleteChoiceRequest massDeleteChoiceRequest = new MassDeleteChoiceRequest();
            massDeleteChoiceRequest.ChoiceIDs = choicesID;
            return await choiceManagerProxy.DeleteAsync(workspaceID, massDeleteChoiceRequest);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choice could not be deleted.");
        }
    }
    return null;
}

Sorting choices

The following code sample illustrates how to sort choices alphabetically with the IChoiceManager interface using the await pattern. 

public async Task<MassActionChoiceResponse> SortAsync(IHelper helper, int workspaceID, int fieldID, ChoiceReorderTypeEnum choiceReorderType)
{
    using (Interfaces.Choice.IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.SortAsync(workspaceID, fieldID, choiceReorderType);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choices could not be sorted.");
        }
    }
    return null;
}

Moving choices

The following code sample illustrates how to move choices to the beginning or end of a list of choices with the IChoiceManager interface using the await pattern. 

public async Task<MassActionChoiceResponse> MoveAsync(IHelper helper, int workspaceID, int fieldID, ObjectIdentifier[] choiceObjectIdentifiers, ChoiceMoveTypeEnum choiceMoveType)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.MoveAsync(workspaceID, fieldID, choiceObjectIdentifiers, choiceMoveType);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choices could not be moved.");
        }
    }
    return null;
}

The following code sample illustrates how to move a choice after a specific choice in a list of choices with the IChoiceManager interface using the await pattern. 

public async Task<MassActionChoiceResponse> MoveAsync(IHelper helper, int workspaceID, int fieldID, ObjectIdentifier[] choiceObjectIdentifiers, ObjectIdentifier choiceIdentifier)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.MoveAsync(workspaceID, fieldID, choiceObjectIdentifiers, choiceIdentifier);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The Choices could not be moved.");
        }
    }
    return null;
}

Retrieve a list of available parents

The following code sample illustrates how to retrieve a list of available parents for a specific choice or field with the IChoiceManager interface using the await pattern. 

public async Task<List<ObjectIdentifier>> GetAvailableParentsListAsync(IHelper helper, int workspaceID, int choiceID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.GetAvailableParentsListAsync(workspaceID, choiceID);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The parent choices could not be retrieved.");
        }
    }
    return null;
}

Retrieve a list of available colors

The following code sample illustrates how to retrieve a list of available colors that can be assigned to choices with the IChoiceManager interface using the await pattern. 

public async Task<List<NameIDPair>> GetAvailableParentsListAsync(IHelper helper, int workspaceID)
{
    using (IChoiceManager choiceManagerProxy = helper.GetServicesManager().CreateProxy<IChoiceManager>(ExecutionIdentity.User))
    {
        try
        {
            return await choiceManagerProxy.GetColorsListAsync(workspaceID);
        }
        catch (Exception exception)
        {
            _logger.LogError(exception, "The colors could not be retrieved.");
        }
    }
    return null;
}