Open topic with navigation



Choice Manager (REST)

The Relativity REST API supports operations with the Choice objects though the Choice Manager service. The operations available through the service are equivalent to the asynchronous methods for interacting with the Choice objects.

For more information and method and class definitions, see Choice Manager (.NET) documentation.

This page contains the following information:

Guidelines for the Choice Manager service

Review the following guidelines for working with this service.

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

  • Set {versionNumber} to the version of the API, using the format lowercase v and the version number, such as v1.
  • Set other path parameters in the URLs to the Artifact ID of a given entity, such as {workspaceID} to the Artifact ID of a workspace.

    • Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.

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.

ClosedClick to view more information.

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

ClosedClick to view code sample. 
public async Task<int> CreateChoiceRestAsync()
{
 
    int choiceID = 0;
    using (Relativity.ObjectModel.V1.Choice.IChoiceManager choiceManager = _serviceFactory.CreateProxy<Relativity.ObjectModel.V1.Choice.IChoiceManager>())
    using (HttpClient client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("<user login>:<user password>")));
        client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
        client.BaseAddress = new Uri("http://localhost/");
 
        string inputJSON = @"{""choiceRequest"":{""Field"":{""ArtifactID"":1104632,""Guids"":[]},""Name"":""Relevant"",""Color"":3,""Order"":100}}";
        string url = "/Relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/1022092/choices";
        HttpResponseMessage response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
        response.EnsureSuccessStatusCode();
        string content = await response.Content.ReadAsStringAsync();
        choiceID = Int32.Parse(content);
    }
 
    return choiceID;
}

Create a single choice

Send a POST request to the Choice Manager service URL to create a choice:

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

Mandatory fields in the request are Field, Name, and Color.

Closed Sample JSON request for creating a choice 
{
    "choiceRequest": {
        "Field": {
            "ArtifactID": 1104632,
            "Guids": []
        },
        "Name": "Relevant",
        "Color": 3,
        "Order": 100
    }
}

The response is an Artifact ID of the created choice.

Mass create choices

Send a POST request to the Choice Manager service URL to mass create choices:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices
Closed Sample JSON request for mass creating choices 
{
    "massCreateChoiceRequest": {
        "Choices": [
            {
                "Name": "Important",
                "Children": [
                    {
                        "Name": "Critical"
                    },
                    {
                        "Name": "Very"
                    },
                    {
                        "Name": "Somewhat"
                    }
                ]
            }
        ],
        "ChoiceTemplateData": {
            "Field": {
                "ArtifactID": 1104635,
                "Guids": []
            }
        }
    }
}
Closed Sample JSON response for mass creating choices 
{
    "ChoicesCreated": [
        {
            "ObjectIdentifier": {
                "Name": "Important",
                "ArtifactID": 1104660,
                "Guids": []
            },
            "ParentChoice": {
                "ArtifactID": 0,
                "Guids": []
            }
        },
        {
            "ObjectIdentifier": {
                "Name": "Critical",
                "ArtifactID": 1104661,
                "Guids": []
            },
            "ParentChoice": {
                "ArtifactID": 1104660,
                "Guids": []
            }
        },
        {
            "ObjectIdentifier": {
                "Name": "Very",
                "ArtifactID": 1104662,
                "Guids": []
            },
            "ParentChoice": {
                "ArtifactID": 1104660,
                "Guids": []
            }
        },
        {
            "ObjectIdentifier": {
                "Name": "Somewhat",
                "ArtifactID": 1104663,
                "Guids": []
            },
            "ParentChoice": {
                "ArtifactID": 1104660,
                "Guids": []
            }
        }
    ],
    "Success": true,
    "Message": ""
}

Read a choice

You can retrieve basic or extended metadata for a choice. Extended metadata includes operations that you have permissions to perform on the choice, such as delete or update.

Send a GET request to the Choice Manager service URL to retrieve metadata: 

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

The request body is empty.

ClosedSample JSON response for retrieving metadata 
{
    "ObjectIdentifier": {
        "Name": "Critical",
        "ArtifactID": 1104661,
        "Guids": []
    },
    "Field": {
        "Name": "Multi choice test field",
        "ArtifactID": 1104635,
        "Guids": []
    },
    "Order": 1000,
    "Color": {
        "ID": 3
    },
    "Parent": {
        "ArtifactID": 1104660,
        "Guids": []
    }
}

Update a choice (no version check)

Send a PUT request to the Choice Manager service URL to update a choice:

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

The following is a sample URL for sending a PUT request to the Choice Manager service.

Closed Sample JSON request for updating a choice 
{
    "choiceRequest": {
        "Name": "Critical - 2",
        "Color": 3,
        "Parent": {
            "Name": "Important",
            "ArtifactID": 1104636,
            "Guids": []
        },
        "Order": 1000
    }
}

The response is a status code of 200 when the request is successful.

Update a choice (with version check)

Send a PUT request to the Choice Manager service URL to update a choice:

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

The following is a sample URL for sending a PUT request to the Choice Manager service.

Closed Sample JSON request for updating a choice 
{
    "choiceRequest": {
        "Name": "Critical - 3",
        "Color": 3,
        "Parent": {
            "Name": "Important",
            "ArtifactID": 1104636,
            "Guids": []
        },
        "Order": 400
    },
    "objectVersionToken": "637499580733130000"
}

The response is a status code of 200 when the request is successful.

Mass update choices

Send a PUT request to the Choice Manager service URL to mass update choices.

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

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices
Closed Sample JSON request for mass updating choices 
{
    "massUpdateChoices": [
        {
            "ObjectIdentifier": {
                "ArtifactID": 1104662,
            },
            "Name": "Relevant",
            "Color": 3
        },
        {
            "ObjectIdentifier": {
                "ArtifactID": 1104663,
            },
            "Name": "Confidential",
            "Color": 3
        }
    ]
}
Closed Sample JSON response for mass updating choices 
{
    "TotalChoices":2,
    "Success":true,
    "Message":""
}

Delete a choice

Send a DELETE request to the Choice Manager service URL to delete a choice:

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

The response is a status code of 200 when the request is successful.

Mass delete choices

Send a DELETE request to the Choice Manager service URL to mass delete choices:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices
Closed Sample JSON request for mass deleting choices 
{
    "massDeleteRequest": {
        "ChoiceIDs": [
            {
                "ArtifactID": 1104661,
            },
            {
                "ArtifactID": 1104662,
            },
            {
                "ArtifactID": 1104663,
            }
        ]
    }
}
Closed Sample JSON response for mass deleting choices 
{
    "TotalChoices":3,
    "Success":true,
    "Message":""
}

The response is a status code of 200 when the request is successful.

Sort choices

Send a PUT request to the Choice Manager service URL to sort choices:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices/sort
Closed Sample JSON request for alphabetically sorting choices 
{
    "fieldID": 1104635,
    "sortType": "Ascending"
}
Closed Sample JSON response for sorting choices 
{
    "TotalChoices": 16,
    "Success": true
}

Move choices to start or end of list

Send a PUT request to the Choice Manager service URL to move choices:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices/move
Closed Sample JSON request for moving choices to the start or end of a list 
{
    "fieldID": 1104635,
    "choiceObjectIdentifiers": [
        {
            "ArtifactID": 1104638,
            "Guids": []
        },
        {
            "ArtifactID": 1104637,
            "Guids": []
        }
    ],
    "moveListTo": "End"
}
Closed Sample JSON response for moving choices to the start or end of a list

A successful request will return a 200 status code. Response body contains a information about number of choices moved, whether the request was successful, and if not, why.

{
    "TotalChoices":0,
    "Success":true,
    "Message":""
}

Move choices after a specific choice in a list

Send a PUT request to the Choice Manager service URL to move choices:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices/move
Closed Sample JSON request for moving choices after a specific choice in a list 
{
    "fieldID": 1104635,
    "choiceObjectIdentifiers": [
        {
            "ArtifactID": 1104638,
            "Guids": []
        },
        {
            "ArtifactID": 1104637,
            "Guids": []
        }
    ],
    "choiceID": {
        "ArtifactID": 1104651,
        "Guids": []
    }
}
Closed Sample JSON response for moving choices after a specific choice in a list

A successful request will return a 200 status code. Response body contains a information about number of choices moved, whether the request was successful, and if not, why.

{
    "TotalChoices":0,
    "Success":true,
    "Message":""
}

Retrieve a list of available parents

Send a GET  request to the Choice Manager service URL to retrieve a list of available parents for a specific choice:

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

Send a POST request to the Choice Manager service URL to retrieve a list of available parents for a specific field:

<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/<workspaceID>/choices/parents
Closed Sample JSON request for retrieving a list of available parents for a specific field 
{
    "fieldIdentifier": {
        "ArtifactID":1104635,
        "Guids":[]
    }
}
Closed Sample JSON response for retrieving a list of available parents for a specific field 
[
    {
        "Name": "Important",
        "ArtifactID": 1104636,
        "Guids": []
    },
    {
        "Name": "Very",
        "ArtifactID": 1104637,
        "Guids": []
    },
    {
        "Name": "Somewhat",
        "ArtifactID": 1104638,
        "Guids": []
    },
    ...
    {
        "Name": "Privileged",
        "ArtifactID": 1104640,
        "Guids": []
    },
]
Closed Sample JSON request for retrieving a list of available parents for a specific choice 
No request body.
Closed Sample JSON response for retrieving a list of available parents for a specific choice 
[
    {
        "Name": "Important",
        "ArtifactID": 1104636,
        "Guids": []
    },
    {
        "Name": "Very",
        "ArtifactID": 1104637,
        "Guids": []
    },
    {
        "Name": "Somewhat",
        "ArtifactID": 1104638,
        "Guids": []
    },
    ...
    {
        "Name": "Privileged",
        "ArtifactID": 1104640,
        "Guids": []
    },
]

Retrieve a list of available colors

Send a GET request to the Choice Manager service URL to retrieve a list of available colors for a specific choice:

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

No request body.

Closed Sample JSON response for retrieving a list of available colors 
[
    {
        "Name": "Green",
        "ID": 3
    },
    {
        "Name": "Gray",
        "ID": 12
    },
    {
        "Name": "Blue",
        "ID": 13
    },
    {
        "Name": "Orange",
        "ID": 14
    },
    {
        "Name": "Tan",
        "ID": 15
    }
]

Additional Resources
DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.