Choice Manager (REST)

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 RelativityOne Documentation site.

The Choice Manager service 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 mass operations on choices.
  • Provides helper endpoints used to sort choices, move choices in lists, and retrieve highlight colors and parent choices or fields.

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 .NET. For more information, see Choice Manager (.NET).

Guidelines for the Choice Manager service

Review the following guidelines for working with this service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1.
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.
    • To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to retrieve a choice:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}

Set the path parameters as follows:

  • {versionNumber} to the version of the service, such as v1.
  • {workspaceID} to the Artifact ID of the workspace containing the choice.
  • {choiceID} to the Artifact ID of the choice.

Postman sample file

You can use the Postman sample file to become familiar with making calls to endpoints on the Choice Manager service. To download the sample file, click Choice Manager Postman file.

To get started with Postman, complete these steps:

  1. Obtain access to a Relativity environment. You need a username and password to make calls to your environment.
  2. Install Postman.
  3. Import the Postman sample file for the service. For more information, see Working with data files on the Postman web site.
  4. Select an endpoint. Update the URL with the domain for your Relativity environment and any other variables.
  5. In the Authorization tab, set the Type to Basic Auth, enter your Relativity credentials, and click Update Request.
  6. See the following sections on this page for more information on setting required fields for a request.
  7. Click Send to make a request.

Client code sample

You can use the following .NET code as a sample client for creating a choice.

Create a single choice

To create a choice, send a POST request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices

The response contains the Artifact ID of the created choice.

Mass create choices

To create multiple choices in a mass operation, send a POST request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices

Read a choice

To retrieve the metadata for a choice, send a GET request with a URL in the following format (to list the choices for a field, see Object Rule Manager service):

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}

The request body is empty.

Update a choice without a version check

To update a choice without a version check, send a PUT request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}

When the choice is update successfully, the response contains a status code of 200.

Update a choice with a version check

To update a choice with a version check, send a PUT request with a URL in the following format::

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}

When the choice is update successfully, the response contains a status code of 200.

Mass update choices

To update multiple choices in a mass operation, send a PUT request with a URL in the following format

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices

All choices in a mass update request must be associated with the same field.

Delete a choice

To remove a choice from Relativity, send a DELETE request with a URL in the following format::

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}

When the choice is deleted successfully, the response contains a status code of 200.

Mass delete choices

To remove multiple choices in a mass operation, send a DELETE request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices

When the choices are deleted successfully, the response contains a status code of 200.

Sort choices

To sort choices, send a PUT request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/sort

Move choices to the beginning or end of a list

To move choices to the beginning or end of a list, send a PUT request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/move

Move choices after a specific choice in a list

To move choices after a specific choice in a list, send a PUT request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/move

Retrieve a list of available parents

You can retrieve a list of parents for a choice or a field.

Retrieve a list of parents for a choice

To retrieve a list of available parents for a choice, send a GET request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}/parents

The request body is empty.

Retrieve a list of parents for a field

To retrieve a list of available parents for a specific field, send a POST request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/parents

Retrieve a list of available colors

To retrieve a list of available colors for highlighting a choice, send a GET request with a URL in the following format:

Copy 
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/colors

The request body is empty.