Work with choices

In Relativity, choices are predetermined values of single and multi-choice list fields. The Services API includes a set of interfaces for operations on admin and workspace choices. For more information, see Choices on the Relativity Server 2022 Documentation site.

This page provides detailed explanations of the programmatic steps for the following common tasks associated with choices:

• Create workspace choices
• Read workspace choices
• Update workspace choices
• Delete workspace choices
• Query admin choices
• Read admin choices

For complete operations reference and code samples, see Choice in RSAPI reference for .NET.

Create workspace choices

You can create Relativity workspaces and admin choices using both regular multi-artifact and single-artifact patterns. For more information about DTO artifact access patterns, see Single vs. multiple artifact access pattern.

Create a single workspace choice

To create a workspace choice:

1. Instantiate the client proxy object:
   Copy

   1
   2
   3
   4
   using (IRSAPIClient proxy = helper.GetServicesManager().CreateProxy<IRSAPIClient>(ExecutionIdentity.System))
   {
       //All operations on the Services API DTO objects must be enclosed in the using block
   }

   Note: In this example the proxy object instantiates using the IRSAPIClient helper class with System execution identity. For more information, see Create the proxy using the Relativity API Helpers.All subsequent operations with Relativity objects perform within the using block.

2. Set the workspace ID in the APIOptions object. This specifies the Relativity workspace where the choice will be added:
   Copy

   1
   proxy.APIOptions.WorkspaceID = this.SampleWorkspace_ID;

3. Read the underlying Choice Field to obtain the Choice Type ID. ChoiceTypeID is an integer value that associates the field for which the choice is created with the instance of choice type.
   Copy

   1
   Client.DTOs.Field fieldToRead = proxy.Repositories.Field.ReadSingle(this.SampleField_SingleChoice_ID);

4. Instantiate the Choice object:
   Copy

   1
   Client.DTOs.Choice choiceToCreate = new Client.DTOs.Choice();

5. Set the required field values:
1. ChoiceTypeID
   Copy

   1
   choiceToCreate.ChoiceTypeID = fieldToRead.ChoiceTypeID;

2. Name
   Copy

   1
   choiceToCreate.Name = string.Format("API Sample {0}", Guid.NewGuid());

Note: In the example above, the name is set to a GUID.

3. Order
   Copy

   1
   choiceToCreate.Order = 10;

4. Choice color (green) as HighlightStyleID
   Copy

   1
   choiceToCreate.HighlightStyleID = (int)kCura.Relativity.Client.HighlightColor.Green;

Note: In this example HighlightStyleID is set using the kCura.Relativity.Client.HighlightColor enumeration.

6. Call the CreateSingle() method of the ChoiceRepository object passing it the populated Choice object. Use a try/catch block in case the operation fails:
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   try
   {
       int choiceID = proxy.Repositories.Choice.CreateSingle(choiceToCreate);
       Console.WriteLine("New Choice Artifact ID: {0}", choiceID);
   }
   catch (APIException ex)
   {               
       Console.WriteLine("An error occurred: {0}", ex.Message);
       return false;
   }

   If the choice creates successfully, the integer value of its Artifact ID returns.

   If the operations fails, kCura.Relativity.Client.APIException returns. The Message property of the exception indicates the error.

Create multiple workspace choices

To create multiple workspace choices:

1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create a single workspace choice.
2. Read the underlying Choice Field to obtain the Choice Type ID. ChoiceTypeID is an integer value that associates the field for which the choice is created with the instance of choice type.
   Copy

   1
   Client.DTOs.Field fieldToRead = proxy.Repositories.Field.ReadSingle(this.SampleField_SingleChoice_ID);

3. Instantiate a list of Choice objects:
   Copy

   1
   List<Client.DTOs.Choice> choicesToCreate = new List<Client.DTOs.Choice>();

4. Add the Choice objects to the list. In this example an iterative loop is used to add ten (10) choice objects:
   
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   for (int i = 0; i < 10; i++)
   {
       //Create a Choice DTO
       Client.DTOs.Choice choiceToCreate = new Client.DTOs.Choice();
               
       //Set primary fields
       choiceToCreate.ChoiceTypeID = fieldToRead.ChoiceTypeID;
       //The name of the sample data is being set to a random string so that sample data can be debugged
       //and never causes collisions. You can set this to any string that you want
       choiceToCreate.Name = string.Format("API Sample {0}", Guid.NewGuid());
       choiceToCreate.Order = 10;
       choiceToCreate.HighlightStyleID = (int)kCura.Relativity.Client.HighlightColor.Green; 
               
       //Add the create request to the list of requests
       choicesToCreate.Add(choiceToCreate);
   }

   Note: The required ChoiceTypeID, Name, Order, and HighlightStyleID field values in this example are set in the same way as in the example in Create a single workspace choice.

5. Instantiate the WriteResultSet object for the create operation:
   Copy

   1
   Client.DTOs.WriteResultSet<Client.DTOs.Choice> resultSet = new Client.DTOs.WriteResultSet<Client.DTOs.Choice>();

6. Call the Create() method of the ChoiceRepository object, passing it the populated Choice objects list. A WriteResultSet object instantiates to the result of the choices create operation. Use a try/catch block in case the operation fails.
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   try
   {
       resultSet = proxy.Repositories.Choice.Create(choicesToCreate);
   }
   catch (Exception ex)
   {
       Console.WriteLine("The create failed. {0}", resultSet.Message);
       return false;
   }

7. Check the result of the create operation by evaluating the Success property of the WriteResultSet object and iterating through the objects in the Results collection:
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   // Check for success
   if (resultSet.Success) {
    //Check the results
    int succeed = 0;
    foreach(Client.DTOs.Result < Client.DTOs.Choice > choice in resultSet.Results) {
     if (choice.Success) {
      succeed++;
     }
    }
    Console.WriteLine("{0} Choices created", succeed);
   } else {
    Console.WriteLine("The Create operation failed. {0}", resultSet.Message);
    return false;
   }

   If all choices create successfully, the Success property returns as True for every object in the collection.

Read workspace choices

To read a workspace choice:

1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create a single workspace choice.
2. Call the ReadSingle() method of the ChoiceRepository object passing it the choice ID and read the choice. Use a try/catch block in case the operation fails.
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   try
   {
       Client.DTOs.Choice choice = proxy.Repositories.Choice.ReadSingle(this.SampleChoice_ID);
       //The rest of the read operation
   
   catch (APIException ex)
   {
       Console.WriteLine("The create failed. {0}", resultSet.Message);
       return false;
   }

3. Read the basic object fields using the object properties after the Choice object returns, for example, Name:
   Copy

   1
   string name = choice.Name;

Update workspace choices

To update a workspace choice:

1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create a single workspace choice.
2. Call the ReadSingle() method of the ChoiceRepository object and passing it the choice Artifact ID then read the choice that will be updated. Instantiate a Choice object to the results of the read operation. Use a try/catch block in case the operation fails.
   
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   try
   {
       Client.DTOs.Choice choiceDTO = proxy.Repositories.Choice.ReadSingle(this.SampleChoice_ID);
   
   }
   catch (Client.APIException ex)
   {
       Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
       return false;
   }

   Note: You can create the choice manually rather than read it.

3. Change the Name field value. Note that in this example it is set to a GUID, but you can set the name to any other string.
   Copy

   1
   choiceDTO.TextIdentifier = string.Format("API Sample (Updated) {0}", Guid.NewGuid());

4. Change the Order field value to 20.
   Copy

   1
   choiceDTO.Order = 20;

5. Update the choice by calling the UpdateSingle() method of the ChoiceRepository object. Use a try/catch block in case the operation fails.
   
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   try
   {
       proxy.Repositories.Choice.UpdateSingle(choiceDTO);
   }
   catch (Client.APIException ex)
   {
       Console.WriteLine("An error occurred: {0}", ex.Message);
       return false;
   }<br />

Delete workspace choices

To delete a workspace choice:

1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create a single workspace choice.
2. Delete the choice by calling the DeleteSingle() method of the ChoiceRepository object and passing it the choice ID. Use a try/catch block in case the operation fails.
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   try
   {
       Client.DTOs.Choice choice = proxy.Repositories.Choice.DeleteSingle(choiceToDeleteID.Value);
   }
   catch (Client.APIException ex)
   {
      //Exceptions are returned as an APIException
      Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
      return false;
   }

Query admin choices

To query admin choices:

1. Instantiate the client proxy as shown in Create a single workspace choice.
2. Set the workspace ID in the APIOptions object to -1. This indicates the object is stored in the master EDDS database rather than a workspace-specific database.
   Copy

   1
   proxy.APIOptions.WorkspaceID = -1;

3. Define the query condition using the TextQueryCondition object and instantiate the Query object. You retrieve all of the Choices for the User Type field by filtering on ChoiceTypeID of AdminChoice.UserType.
   
   Copy

   1
   2
   3
   WholeNumberCondition criteria = new WholeNumberCondition(Client.DTOs.ChoiceFieldNames.ChoiceTypeID, NumericConditionEnum.EqualTo, (int)AdminChoice.UserType);
   Client.DTOs.Query<Client.DTOs.Choice> query = new Client.DTOs.Query<Client.DTOs.Choice> { Condition = criteria };
   query.Fields = Client.DTOs.FieldValue.AllFields;

4. Instantiate the QueryResultSet object:
   Copy

   1
   Client.DTOs.QueryResultSet<Client.DTOs.Choice> resultSet = new QueryResultSet<Choice>();

5. Call the Query() method of the ChoiceRepository object passing it the populated Query object. Use a try/catch block in case the operation fails.
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   try
   {
       resultSet = proxy.Repositories.Choice.Query(query, 0);
   }
   catch (Exception ex)
   {
       Console.WriteLine("An error occurred: {0}", ex.Message);
       return false;
   }

   You can use the choice objects in the returned result set for further processing. In this example, the number of query results is returned using the TotalCount property of the QueryResultSet object.

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   
   //Check the success
   if (resultSet.Success)
   {
       Console.WriteLine(string.Format("Number of Choices returned: {0}", resultSet.TotalCount));
       return true;
   }
   else
   {
       Console.WriteLine("The query failed. {0}", resultSet.Message);
       return false;
   }

Read admin choices

To read an admin choice:

1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create a single workspace choice.
2. Set the workspace ID in the APIOptions object to -1. That indicates that the object is stored in the master EDDS database rather than a workspace-specific database.
   Copy

   1
   proxy.APIOptions.WorkspaceID = -1;

3. Call the ReadSingle() method of the ChoiceRepository object passing it the choice ID to read the choice. Use a try/catch block in case the operation fails.
   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   try
   {
       Client.DTOs.Choice choice = proxy.Repositories.Choice.ReadSingle(662);
       //The rest of the read operation
   
   catch (APIException ex)
   {
       Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
       return false;
   }

4. Read the basic object fields using the object properties after the choice object returns, for example, Name:
   Copy

   1
   2
   
   string name = choice.Name;