Relativity Services API (RSAPI) DTOs have been deprecated and are no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

Choice

In Relativity, choices are predetermined values of single- and multi-choice list fields. You can perform operations on admin and workspace choices. For more information, see Choices on the Relativity Documentation site.

The Services API supports the create, read, update, delete and query operations on a Choice DTO.

Note: You can perform a full set of CRUD operations on choices using the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.

This page contains the following information:

Guidelines for workspace Choice DTOs

Use these guidelines when working with workspace Choice DTOs.

  • Set the following required field values to create choices:
    • Name
    • ChoiceTypeID
    • Order
    • HighlightStyleID
  • ChoiceTypeID is an integer value. For workspace choices, query the single- or multiple-choice type field for which you are creating the choice to obtain the ChoiceTypeID.
  • HighlightStyleID is an integer value corresponding to the color. HighlightStyleID can be set using the kCura.Relativity.Client.HighlightColor enumeration.
  • Optional fields include:
    • KeyboardShortcut
    • RelativityApplications
  • The keyboard shortcut field has Boolean properties to set Ctrl, Alt, or Shift, and a Key property that uses the new enumeration KeyboardShortcutKey. For detailed information about the enumeration values, see Services API.
  • Workspace choice values have the same restrictions and validations as they do in the user interface.

Guidelines for admin Choice DTOs

Use these guidelines when working with admin Choice DTOs.

  • Specify you are accessing Relativity admin objects by setting the WorkspaceID property in APIOptions of the proxy object to -1.
  • For Admin choices, the supported fields include:
    • Name
    • ChoiceTypeID
    • Order

    All of these fields are required when creating an admin choice. Admin choice values have the same restrictions and validations as they do in the user interface.

  • ChoiceTypeID is an integer value that can also be set using the kCura.Relativity.Client.AdminChoice enumeration. The enumeration includes a limited set of standard admin-level single-choice fields:
    • UserType
    • ClientStatus
    • MatterStatus
    • CaseStatus
    • dtSearchIndexShareLocation
    • FileLocation
    • ProcessingSourceLocation
  • Admin choices do not support all fields. Unsupported fields include:
    • Keyboard Shortcut
    • Relativity Applications
    • Object Type Name
  • Do not set unsupported fields and properties for Admin choices.

  • Admin Choice DTOs do not support paging.

Create a Choice

Workspace choices

The following code sample illustrates how to create a choice with the value of "Responsive," a display order of 10, and a highlight color of green for a choice type workspace field identified by GUID. The field is queried to obtain the ChoiceTypeID value.

/// Create a Choice for a Choice Type Field on a Document.

public static bool Create_Workspace_Choice(IRSAPIClient proxy)
{
    // Step 1: Read the underlying Choice Field to obtain the Choice Type ID.
    // NOTE: All Guids are specific to your workspace.
    var fieldDTO = new DTOs.Field(new Guid("8A6747ED-713A-4F2D-B441-C4CD91C3BBA9"));
    fieldDTO.Fields.Add(new FieldValue(FieldFieldNames.ChoiceTypeID));
    ResultSet<DTOs.Field> fieldReadResult = null;
    int? choiceTypeID;
    try
    {
        fieldReadResult = proxy.Repositories.Field.Read(fieldDTO);
        //Check for success and set the choice type id
        if (fieldReadResult.Success)
        {
            choiceTypeID = fieldReadResult.Results[0].Artifact.ChoiceTypeID;
        }
        else
        {
            Console.WriteLine("The Read operation was not successful.{0}{1}", Environment.NewLine, fieldReadResult.Message);
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }


    // STEP 2: Create a Choice DTO for the new Choice and set the required fields.
    DTOs.Choice choiceToCreate = new DTOs.Choice();
    choiceToCreate.ChoiceTypeID = choiceTypeID;
    choiceToCreate.Name = "Responsive";
    choiceToCreate.Order = 10;
    choiceToCreate.HighlightStyleID = (Int32)kCura.Relativity.Client.HighlightColor.Green;

    // STEP 3: Set any optional fields
    choiceToCreate.KeyboardShortcut = new KeyboardShortcut() { Alt = true, Ctrl = true, Key = KeyboardShortcut.KeyboardShortcutKey.R };
    choiceToCreate.RelativityApplications = new DTOs.FieldValueList<DTOs.RelativityApplication>(new DTOs.RelativityApplication(123456));

    // STEP 4: Execute the Create method on the Repository
    WriteResultSet<DTOs.Choice> writeResult = null;
    try
    {
        writeResult = proxy.Repositories.Choice.Create(choiceToCreate);
        // Check for success
        if (writeResult.Success)
        {
            Console.WriteLine("New Choice Artifact ID is {0}", writeResult.Results[0].Artifact.ArtifactID);
        }
        else
        {
            Console.WriteLine("The write operation was not successful.{0}{1}", Environment.NewLine, writeResult.Message);
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }


    return true;
}

Admin choices

The following code sample illustrates how to create an admin choice with the name value of "On Hold" and a display order of 10 for the Case Status field. The choice type ID is set to 7.

/// Create a Choice for an Admin level choice.

public static bool Create_Admin_Choice(IRSAPIClient proxy)
{

   // STEP 1:  hange database to EDDS with the WorkspaceID of -1.
   proxy.APIOptions.WorkspaceID = -1;

   // STEP 2: Create a Choice DTO for the new Choice and set the required fields.
   DTOs.Choice choiceToCreate = new DTOs.Choice();

   // Use the supplied Enum for setting the Choice Type ID.
   choiceToCreate.ChoiceTypeID = 7;

   choiceToCreate.Name = "On Hold";
   choiceToCreate.Order = 10;

   // STEP 3: Execute the Create method on the Repository
   try
   {
      var writeResult = proxy.Repositories.Choice.Create(choiceToCreate);
      // Check for success
      if (writeResult.Success)
      {
         Console.WriteLine("New Choice Artifact ID is {0}", writeResult.Results[0].Artifact.ArtifactID);
      }
      else
      {
         Console.WriteLine("The write operation was not successful.{0}{1}", Environment.NewLine, writeResult.Message);
         return false;
      }
   }
   catch (Exception ex)
   {
      Console.WriteLine("An error occurred: {0}", ex.Message);
      return false;
   }

   return true;
}

Read a Choice

To read Field values on a Choice DTO, use the Read() method on the Choice repository.

Workspace choice

The following code sample illustrates how to read a workspace choice.

/// Read all the properties from a Choice DTO

public static bool Read_Choices(IRSAPIClient proxy)
{
    // STEP 1: Create DTO with criteria for the read.
    // NOTE: All ArtifactIDs are specific to your workspace.
    DTOs.Choice choiceToRead = new DTOs.Choice(1016577);
    choiceToRead.Fields = FieldValue.AllFields;

    // STEP 2: Create ResultSet which contain Results from Read Operation.
    ResultSet<DTOs.Choice> results = new ResultSet<DTOs.Choice>();

    // STEP 3: Perform the Read.
    try
    {
        results = proxy.Repositories.Choice.Read(choiceToRead);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // Check for success
    if (!results.Success)
    {
        Console.WriteLine("The Read operation was not successful.{0}{1}", Environment.NewLine, results.Message);
        return false;
    }

    Result<DTOs.Choice> choiceDtoArtifact = results.Results[0];

    return true;
}

Admin choice

The following code sample illustrates how to read an admin choice.

/// Read all the properties from a admin Choice DTO

public static bool Read_Admin_Choices(IRSAPIClient proxy)
{
    // STEP 1: Change database to EDDS with the WorkspaceID of -1
    proxy.APIOptions.WorkspaceID = -1;

    // STEP 2: Create DTO with criteria for the read.
    // NOTE: All ArtifactIDs are specific to your workspace.
    DTOs.Choice choiceToRead = new DTOs.Choice(662);
    choiceToRead.Fields = FieldValue.AllFields;

    // STEP 3: Create ResultSet which contain Results from Read Operation.
    ResultSet<DTOs.Choice> results = new ResultSet<DTOs.Choice>();

    // STEP 4: Perform the Read.
    try
    {
        results = proxy.Repositories.Choice.Read(choiceToRead);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // Check for success
    if (!results.Success)
    {
        Console.WriteLine("The Read operation was not successful.{0}{1}", Environment.NewLine, results.Message);
        return false;
    }

    Result<DTOs.Choice> choiceDtoArtifact = results.Results[0];

    return true;
}

Update a Choice

Admin and workspace Choice DTOs update in the same manner. The following code sample illustrates how to update a workspace choice:

/// Update a Choice DTO.

public static bool Update_Choices(IRSAPIClient proxy)
{
    // STEP 1: Create a choice DTO and set the updated fields.
    // NOTE: Not all fields are available when updating admin choices. All ArtifactIDs are specific to your workspace.
    DTOs.Choice choiceDTO = new DTOs.Choice(1016503);
    choiceDTO.Name = "Updated Choice 1";
    choiceDTO.Order = 20;

    // STEP 2: Do the update.
    WriteResultSet<DTOs.Choice> writeResultSet = new WriteResultSet<DTOs.Choice>();
    try
    {
        writeResultSet = proxy.Repositories.Choice.Update(choiceDTO);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // Check for success
    if (!writeResultSet.Success)
    {
        Console.WriteLine("The Update operation was not successful.{0}{1}", Environment.NewLine, writeResultSet.Message);
        return false;
    }

    return true;
}

Delete a Choice

Workspace choice

The following code sample illustrates how to create and then delete a workspace choice. The choice is first created for the Designation field specified by GUID with the name "Responsive," a display order of 10, and a highlight color green, and then deleted.

/// Creates first, then deletes, a workspace choice.

public static bool Delete_Workspace_Choice(IRSAPIClient proxy)
{
    try
    {
        // STEP 1: Read the underlying Choice field to obtain the Choice Type ID. 
        // NOTE: All Guids are specific to your workspace.
        DTOs.Field fieldDTO = new DTOs.Field(new Guid("8A6747ED-713A-4F2D-B441-C4CD91C3BBA9"));  // Designation Field
        fieldDTO.Fields.Add(new FieldValue(FieldFieldNames.ChoiceTypeID));

        int? choiceTypeID;
        ResultSet<DTOs.Field> fieldReadResult = proxy.Repositories.Field.Read(fieldDTO);

        if (fieldReadResult.Success)
        {
            choiceTypeID = fieldReadResult.Results[0].Artifact.ChoiceTypeID;
        }
        else
        {
            Console.WriteLine("The Read operation was not successful.{0}{1}", Environment.NewLine, fieldReadResult.Message);
            return false;
        }

        // STEP 2: Create a workspace choice.
        DTOs.Choice workspaceChoice = new DTOs.Choice();
        workspaceChoice.ChoiceTypeID = choiceTypeID;
        workspaceChoice.Name = "Responsive";
        workspaceChoice.Order = 10;
        workspaceChoice.HighlightStyleID = (Int32)kCura.Relativity.Client.HighlightColor.Green;

        WriteResultSet<DTOs.Choice> writeResult = proxy.Repositories.Choice.Create(workspaceChoice);

        if (writeResult.Success)
        {
            Console.WriteLine("New Choice Artifact ID is {0}", writeResult.Results[0].Artifact.ArtifactID);
        }
        else
        {
            Console.WriteLine("The write operation was not successful.{0}{1}", Environment.NewLine, writeResult.Message);
            return false;
        }

        // STEP 3:  Delete the workspace choice
        WriteResultSet<DTOs.Choice> deleteResult = proxy.Repositories.Choice.Delete(workspaceChoice);

        if (deleteResult.Success)
        {
            Console.WriteLine("Choice with Artifact ID of {0} successfully deleted.", deleteResult.Results[0].Artifact.ArtifactID);
        }
        else
        {
            Console.WriteLine("The delete operation was not successful.{0}{1}", Environment.NewLine, writeResult.Message);
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    return true;
}

Admin choice

The following code sample illustrates how to delete an admin choice. The choice creates first for the Case Status field with the name "On Hold" and a display order of 10, and then deleted.

/// Creates first, then deletes, an admin choice (i.e., a choice that appears on the Admin Choices tab).

public static bool Delete_Admin_Choice(IRSAPIClient proxy)
{
    // STEP 1:  Set the Workspace ID to -1, which indicates admin-level access.
    proxy.APIOptions.WorkspaceID = -1;

    // STEP 2: Create an admin choice of type 'Case Status'.
    DTOs.Choice adminChoice = new DTOs.Choice();
    adminChoice.ChoiceTypeID = 7;
    adminChoice.Name = "On Hold";
    adminChoice.Order = 10;

    try
    {
        WriteResultSet<DTOs.Choice> writeResult = proxy.Repositories.Choice.Create(adminChoice);

        if (writeResult.Success)
        {
            Console.WriteLine("New Admin Choice Artifact ID is {0}", writeResult.Results[0].Artifact.ArtifactID);
        }
        else
        {
            Console.WriteLine("The create operation was not successful.{0}{1}", Environment.NewLine, writeResult.Message);
            return false;
        }

        // STEP 3:  Delete the newly-created admin choice.
        WriteResultSet<DTOs.Choice> deleteResult = proxy.Repositories.Choice.Delete(adminChoice);

        if (deleteResult.Success)
        {
            Console.WriteLine("Choice with Artifact ID of {0} successfully deleted.", deleteResult.Results[0].Artifact.ArtifactID);
        }
        else
        {
            Console.WriteLine("The delete operation was not successful.{0}{1}", Environment.NewLine, deleteResult.Message);
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    return true;
}

Query on a Choice

In addition to read, Choice DTOs support the query operation. For detailed information about querying Relativity objects, see Search Relativity.

Workspace choice

The following code sample illustrates how to query for choices associated with the Designation field.

/// Query all the properties from a Choice DTO

public static bool Query_Choices(IRSAPIClient proxy)
{
    // STEP 1: Query for the Field Choice Type ID.
    Query<DTOs.Field> fieldQuery = new Query<DTOs.Field>();
    fieldQuery.Fields.Add(new FieldValue(FieldFieldNames.Name));
    fieldQuery.Fields.Add(new FieldValue(FieldFieldNames.ChoiceTypeID));
    fieldQuery.Condition = new TextCondition("Name", TextConditionEnum.EqualTo, "Designation");

    int choiceTypeID = 0;
    try
    {
        QueryResultSet<DTOs.Field> fieldQueryResultSet = proxy.Repositories.Field.Query(fieldQuery);

        if (fieldQueryResultSet.Success && fieldQueryResultSet.Results.Any())
        {
            DTOs.Field fieldArtifact = fieldQueryResultSet.Results.First().Artifact;
            choiceTypeID = fieldArtifact.ChoiceTypeID.Value;
        }
        else
        {
            Console.WriteLine("The Query operation was not successful.{0}{1}", Environment.NewLine, fieldQueryResultSet.Message);
            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // STEP 2: Setup your query criteria.
    WholeNumberCondition criteria = new WholeNumberCondition(ChoiceFieldNames.ChoiceTypeID, NumericConditionEnum.EqualTo,
    choiceTypeID);
    Query<DTOs.Choice> query = new DTOs.Query<DTOs.Choice> {Condition = criteria};
    query.Fields = FieldValue.AllFields;

    // STEP 3: Create QueryResultSet to collect Query Results.
    QueryResultSet<DTOs.Choice> result = new QueryResultSet<DTOs.Choice>();

    // STEP 4: Perform the Query.
    try
    {
        result = proxy.Repositories.Choice.Query(query, 0);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // Check for success
    if (!result.Success)
    {
        Console.WriteLine("The Query operation was not successful.{0}{1}", Environment.NewLine, result.Message);
        return false;
    }

    Console.WriteLine("Number of Choices returned: {0}", result.Results.Count);

    return true;
}

Admin choice

The following code sample illustrates how to query for choices associated with the user Type field.

/// Query for Admin Choices

public static bool Query_for_Admin_Choices(IRSAPIClient proxy)
{
    // STEP 1: Change database to EDDS with the WorkspaceID of -1
    proxy.APIOptions.WorkspaceID = -1;

    // STEP 2: Setup your query criteria.  We are retrieving all of the Choices for the User Type field, by filtering on ChoiceTypeID equal to AdminChoice.UserType.
    // The admin 
    WholeNumberCondition criteria = new WholeNumberCondition(ChoiceFieldNames.ChoiceTypeID, NumericConditionEnum.EqualTo, (int) AdminChoice.UserType);
    Query<DTOs.Choice> query = new DTOs.Query<DTOs.Choice> {Condition = criteria};
    query.Fields = FieldValue.AllFields;

    // STEP 3: Create QueryResultSet to collect Query Results.
    QueryResultSet<DTOs.Choice> result = new QueryResultSet<DTOs.Choice>();

    // STEP 4: Perform the Query.
    try
    {
        result = proxy.Repositories.Choice.Query(query, 0);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    // Check for success
    if (!result.Success)
    {
        Console.WriteLine("The Query operation was not successful.{0}{1}", Environment.NewLine, result.Message);
        return false;
    }

    Console.WriteLine("Number of Choices returned: {0}", result.Results.Count);

    return true;
}