Choice Manager (.NET)

The Choice Manager API includes the following methods available on the IChoiceManager interface in the Relativity.ObjectModel.<VersionNumber>.Choice 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.

• CreateAsync() method - adds a new choice to a Relativity environment. To create a choice, pass a ChoiceRequest object to the method. It returns the Artifact ID of the new choice. 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.

The Choice Manager API includes the following classes and enumerations:

• ChoiceMoveType enum - identifies the position in the list of choices for a field where a subset of choices is relocated.
• ChoiceRequest class - used to specify information for creating or updating a choice.
  • Field - identifies the field associated with the choice.
  • Name - a string representing the user-friendly name of the choice.
  • Color -the color of field.
  • Order - an integer 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.
• Color class - represents a highlight color for a choice.
• MassActionChoiceResponse class - represents the result summary of both a massive delete or a massive update of choices.
• MassCreateChoiceHierarchy class - represents a choice abstraction used to define hierarchy of choices created when a mass create operation is performed.
• MassCreateChoiceModel class - represents data model for choice information of a massive create operation.
• MassCreateChoiceRequest class - represents the request to create multiple choices at once.
  • Choices - a list of choices to be created. For single choice fields, use a flat list of choices without any child choices. For multi-choice fields, the list can be hierarchical. Each choice can have child choices, and each child can its own children. You can only 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.
• 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.
• SortDirection enum - identifies the sort order applied to a list as either ascending or descending.

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);
    }
}

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);
    }
}

using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
{
    int workspaceID = 1022092;
    int choiceID = 1104636;
 
    ChoiceResponse choiceResponse = await choiceManager.ReadAsync(workspaceID, choiceID);
}

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);
    }
}

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);
    }

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);
    }
}

public async Task DeleteChoiceAsync()
{
    using (IChoiceManager choiceManager = _serviceFactory.CreateProxy<IChoiceManager>())
    {
        int workspaceID = 1022092;
        int choiceID = 1104642;
 
        await choiceManager.DeleteAsync(workspaceID, choiceID);
    }
}

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);
    }
}

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);
    }
}

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);
    }
}

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);
    }
}