Object Manager (REST)

Relativity applications contain system objects and Relativity Dynamic Objects (RDOs). System objects are predefined and included in applications default by default. RDOs are custom objects that you can define for your specific business needs through the UI or programmatically. For information about using objects through the UI, see Relativity Objects .

The Object Manager service provides you with the ability to programmatically work with RDOs and Document objects. It exposes endpoints for performing the following tasks:

  • Create RDOs and set values on their associated fields.
  • Update fields on Document objects or RDOs. Modify the field types currently available on a Relativity object, including currency, date, user, and others.
  • Read fields on Document objects or RDOs.
  • Retrieve a list of dependent objects prior to deleting a specific object.
  • Perform mass operations to create RDOs, and to update and delete Document objects or RDOs.
  • Query for Workspaces, Documents, RDOs, system types, and all Relativity Objects.
  • Export objects.

Sample use cases for the Object Manager service include:

  • Modifying and saving coding decisions or changes to attorney's notes.
  • Searching for object data, which you display in the Relativity UI or use for other purposes in your applications. For example, use this service to populate data that appears in the list views.

You can also use the Object Manager service through .NET, which supports the use of progress indicators and cancellation tokens for queries. For more information, see Object Manager (.NET).

This page contains the following information:

Guidelines for the Object 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 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 or v2
  • 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.
  • 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 service. To download the sample file, click Object Manager Postman file.

Client code sample

You interact with the Object Manager service by sending an HTTP request that uses the POST method. See the following base URL for this service:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/

You can use the following .NET code samples as the REST client for making calls with the Object Manager service.

Create an RDO

To create an RDO with a specific set of fields, send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/create

Mass create RDOs

You can mass create multiple RDOs of the same type and specify the values set on the fields that they contain. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/create

Note: If you specify an identifier that’s already in the database, an exception will not be thrown. Instead, the Success field in the JSON response is set to false. Always check the value of the Success field in the JSON response as a best practice.

Retrieve field values for a Document object or RDO

To read a specified subset of field values on a Document object or an RDO, send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/read

Update fields on a Document object or RDO

To update field values on a Document object or RDO, send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/update

Click a field type in the following list to view sample JSON and information about the field values.

Update a long text field using an input stream

You can use the updatelongtextfromstream endpoint to update a single long text field that exceeds the length limits of an HTTP request. This endpoint uses multi-part message for the request, which includes a JSON payload, and a Stream form input. For C# code used to make this request, see Update a long text field using an input stream in .NET.

To call the updatelongtextfromstream endpoint, send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/updatelongtextfromstream

When the long text field is successfully updated, the response returns the status code of 200.

Mass update Document objects or RDOs

You can specify the Document objects or RDOs that you want to mass update in the following ways:

  • To set the same value on specific fields for a group of objects, perform one of these tasks:
    • Use a query to identify the objects that you want to update. Only the objects that match the query conditions are updated. In the Relativity UI, this update operation is equivalent to the user selecting the All option in the mass operations bar on a list page.
    • Note: To search for data, you can use a variety of query options, including conditions, fields, sorts, and relational fields. These query options have a specific syntax for defining the for defining query conditions. For information about query conditions and options, see Query for resources.

    • Provide a list of identifiers for objects that you want to update. Use the Artifact IDs of these objects as identifiers. In the Relativity UI, this update operation is equivalent to the user selecting the Checked or These option in the mass operations bar on a list page.
  • To set different values for specific fields on a group of objects, provide a list of fields for updating in the JSON request. This request should also contain a list of Artifact IDs for the objects to be updated, and the respective field values. The values must be in the same order as the fields that you want to update.

Review the following best practices for mass update operations:

  • Make sure all the objects in a mass update operation are the same type.
  • Use Artifact IDs instead of GUIDs for better performance. In addition, mass update by criteria is the fastest option for updating many objects. See View a JSON request using query conditions.
  • Note that the identifier field can’t be updated by any mass update operation.

To execute a mass operation, send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/update

Click one of the following options to view sample JSON and field descriptions for a mass update operation. For JSON samples showing how to update a specific field type, see Update fields on a Document object or RDO.

Retrieve a list of object dependencies

The dependency list endpoint retrieves information about Relativity objects dependent on one or more specific objects selected for deletion. It returns information such as the relationship between the objects and whether a dependent object would be deleted or unlinked. For information about the dependency report in the Relativity UI, see Deleting object dependencies.

Sample use cases for this endpoint include:

  • Determining whether the delete operation may be blocked by the dependencies on an object selected for deletion.
  • Determining how other objects in Relativity may be affected by deleting a one or more objects.

Use these guidelines for calling the dependencylist endpoint:

  • Call the endpoint with objects of the same type. If you call the endpoint with objects of different types, it returns an error.
  • Call the endpoint only with objects that the user has permission to view. It returns an error if the user does not have view permissions or if any of the objects do not exist.

To call the dependencylist endpoint send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/dependencylist

Delete a Document object or RDO

You can delete a Document object and all its associated files, or an RDO. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/delete

Mass delete Document objects or RDOs

You can specify the Document objects or RDOs that you want to mass delete in the following ways:

  • Use a query to identify the objects that you want to delete. Only the objects that match the query conditions are deleted. For more information, see Query for resources.
  • Provide a list of identifiers for objects that you want to delete. Use the Artifact IDs of these objects as identifiers.

Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/delete

Click one of the following options to view field descriptions and sample JSON:

Query for Relativity objects

With the Object Manager service, you can query for Workspaces, Documents, RDOs, and system types. This service includes

the Query endpoint, which returns detailed information about the field-value pairs returned by the query. The QuerySlim endpoint returns a smaller payload, which saves bandwidth. This endpoint is useful for mobile devices and for displaying tabular data.

To execute a query, send a POST request with a URL in the following format:

  • Query endpoint
    <host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/query
  • QuerySlim endpoint
    <host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/queryslim

Note: To search for data, you can use a variety of query options, including conditions, fields, sorts, and relational fields. These query options have a specific syntax for defining the for defining query conditions. For information about query conditions and options, see Query for resources.

Export API

The Object Manager service supports exporting document fields, including complete long text fields such as extracted text, via the Export API. The Export API uses a multistep workflow with several endpoints:

  • Set up an export job- use the InitializeExport endpoint to set up the export job. The response retrieves a runID used by the RetrieveNextResultsBlockFromExport, the RetrieveResultsBlockFromExport, and the StreamLongText endpoints.
  • Retrieve objects - use the RetrieveNextResultsBlockFromExport endpoint to retrieve successive blocks of document fields or use the RetrieveResultsBlockFromExport endpoint to retrieve a specific block of document fields from an in-progress export job.
  • Stream text - use the StreamLongText endpoint to retrieve the text that exceeds the size limit for the data returned by RetrieveNextResultsBlockFromExport and RetrieveResultsBlockFromExport endpoints. Make requests to this endpoint repeatedly, and optionally, in parallel with requests to the RetrieveNextResultsBlockFromExport or the RetrieveResultsBlockFromExport endpoint, as well as other requests to the StreamLongText endpoint.

Set up an export job

Use the initializeexport endpoint to set up the export of documents from a workspace based on a query. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/<workspace artifact id>/object/initializeexport

Retrieve objects

Call one of the following endpoints to retrieve document fields from the export job:

  • RetrieveNextResultsBlockFromExport endpoint - retrieves successive blocks of document fields from an in-progress export job. See Retrieve the next block of records.
  • RetrieveResultsBlockFromExport endpoint - retrieves a specific block index of document fields from an in-progress export job. It provides the option to specify a block size and starting point. For example, you may want to use this endpoint to break up the export job into smaller blocks, which simplifies retrying a job for that specific block of records. See Retrieve a specific block of records.

Review the following considerations for these endpoints:

  • When the long text field size is greater than the maximum value, the response contains the #KCURA99DF2F0FEB88420388879F1282A55760# token instead of the text. Use a stream for retrieving the text content of a field. See Stream text.
  • The request returns null when all the records are retrieved, and the export job is complete.
  • They can be called in multiple threads simultaneously, or from multiple processes. It returns sequential, non-overlapping, non-repeating blocks of documents. Use this type of parallelism to achieve high throughput.

Retrieve the next block of records

Use the retrievenextresultsblockfromexport endpoint to get the next block of records from an in-progress export job. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/retrievenextresultsblockfromexport

Retrieve a specific block of records

Use the RetrieveResultsBlockFromExport endpoint to get a specific block of records from an in-progress export job. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/RetrieveResultsBlockFromExport

Stream text

Use streamlongtext endpoint to retrieve a stream of text for long text fields marked as exceeding exceeds the size limit for the data returned by the RetrieveNextResultsBlockFromExport or RetrieveResultsBlockFromExport endpoint. Send a POST request with a URL in the following format:

<host>/Relativity.Rest/api/Relativity.ObjectManager/{versionNumber}/workspace/{workspaceID}/object/streamlongtext

The response is a text stream of the content from a specific field. For unicode-enabled fields, the stream is encoded as UTF-16.