Object Manager (REST)

The Object Manager service exposes multiple operations designed to facilitate working with Document objects and all types of Relativity Dynamic Objects (RDOs). You can perform the following operations with this service:

• 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.

The Relativity Services API supports the same functionality for this service as available through the REST API. Additionally, it supports the use of progress indicators and cancellation tokens for queries. For more information, see Object Manager (.NET).

Note: The Object Manager service has undergone extensive enhancements as of the RelatvityOne - February 3, 2018, and the Relativity February 28, 2018 releases. The content on this page addresses these changes. For information about working with older Relativity versions, see Deprecated content for Object Manager with REST on the Relativity 9.5 Developers site.

This page contains the following information:

• Client code sample
• Create an RDO and its specified fields
• Mass create RDOs
• Retrieve field values for a Document object or RDO
• Update fields on a Document object or RDO
• Update a long text field using an input stream
• Mass update Document objects or RDOs
• Retrieve a list of object dependencies
• Delete a Document object or RDO
• Mass delete Document objects or RDOs
• Query for Relativity objects
• Export API

See this related page:

• Object Manager (.NET)

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.Objects/workspace/{workspaceID}/object/

You can use the following .NET code as the REST client for making calls with the Object Manager service. This sample code illustrates how to perform the following tasks for an update operation:

• Instantiate an HttpClient object for sending requests using the URL for the Object Manager service.
• Set the required headers for the request. For information on setting headers, see HTTP headers.
• Initialize variables with values required for updating a field.
• Set the url variable to the URL for the update operation.
• Set the JSON input required for the update operation.
• Use the PostAsync() method to send a post request.
• Return the results of the request and deserialize it.

public async Task<UpdateResult> UpdateExample()
{
    UpdateResult result = null;
    using(HttpClient client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        client.DefaultRequestHeaders.Add("Authorization",
            "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
        client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
        client.BaseAddress = new Uri("https://localhost/Relativity.REST/api/Relativity.Objects/");
            
        var workspaceId = 1016847;
        var objectArtifactID = 1039331;
        var fieldArtifactID = 1039320;
        var valueToUpdate = "New Value";

        string inputJSON = $"{{\"request\":{{\"Object\":{\"{artifactId\":{objectArtifactID}}},\"FieldValues\":[{{\"Field\":{{\"ArtifactID\":{fieldArtifactID}}},\"Value\":\"{valueToUpdate}\"}}]}}}}}}";
        var url = $"workspace/{workspaceId}/object/update";
        var response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        result = JsonConvert.DeserializeObject<UpdateResult>(content);
    }
    return result;
}

Create an RDO and its specified fields

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

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/create

The body of the request for creating an RDO must contain the following fields:

• request - a request object for the create operation with the required fields set.
• ObjectType - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See the ArtifactType enumeration in the Services API.
• FieldValues - an array of field value pairs, which contain an identifier for the required field, and a value for it. This field contains the following:
  • Field - the Artifact ID, GUID, or name of the required field.
  • Value - a value for the field. The type of field determines the requirements for the value that you can assign to it.
• ParentObject - the Artifact ID of the parent object of the for the new RelativityObject.

  Note: If you don't specify a parent object, Relativity defaults to the System object as the parent.

The response contains the following fields:

• Object - an instance of a RelatvityObject containing the fields and their values that were created.
• ParentObject - the Artifact ID of the parent object of the newly created RelativityObject. If you didn't specify a parent object, Relativity defaults to the System object as the parent.
• FieldValues - an array containing FieldValuePair objects.
  • Field - a field associated with a specific value. The Field object contains the following:
    • ArtifactID - a unique identifier for the field, which is represented as an integer.
    • FieldCategory - indicates the specific functionality assigned to a field, such as stores descriptive text, acts as a relational field, represents grouping for batching, and others. For more information, see the FieldCategory enumeration in Relativity.Services.Objects.DataContracts namespace in the Services API.
    • FieldType - the type of a Relativity field, such as fixed-length text, date, single object, or others. For more information, see the FieldType enumeration in Relativity.Services.Objects.DataContracts namespace in the Services API.
    • Guids - an array of GUIDs used to identify the field.
    • Name - a user-friendly name for the field.
    • ViewFieldID - a unique identifier used to reference a view field.
  • Value - the data assigned to a field, represented as an Object type. It contains the following:
    • ArtifactID - a unique identifier for the object, which is represented as an integer.
    • Guids - an array of GUIDs used to identify the object.
    • Name - a user-friendly name for the object.
• ArtifactID - a unique identifier for the RelativityObject instance, which is represented as an integer.
• Guids - an array of GUIDs used to identify the RelativityObject.
• EventHandlerStatuses - an array of EventHandlerStatus objects if any were executed. Each object contains a Boolean value indicating whether the execution was successful, and a string with a related message.

Mass create RDOs

You can mass create multiple RDOs of the same type, and you can specify the values set on the fields that they contain. Use the POST method and send a request with the following URL:

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/create

Note: If you specify an identifier that’s already in the database, an exception won't 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.

In the JSON request for a mass create operation, the following fields are required:

• massRequest - a request to create multiple RDOs.
• ParentObject - the parent of the RelativityObject instances that you want to create. It contains an ArtifactID field, which uniquely identifies the parent object.

  Note: If you don't specify a parent object, Relativity defaults to the System object as the parent.

• ObjectType - indicates the type of objects that you want to create. It contains an ArtifactTypeID field, which contains the Artifact ID used to uniquely identify the object type.
• Fields - an array of Artifact IDs for the Field objects that you want set when the new RelativityObject instances are created. It contains an ArtifactID field for each Field object.
• ValueLists - an array of objects that contain the values used to update the fields on the RelativityObject instances. The order of the values corresponds to the order of the Field objects. In addition to the specified values, each object contains an Artifact ID used to identify it.

The response contains the following fields:

• Success - a Boolean value indicating whether the operation completed without any errors.
• Message - explanatory information provided when an error occurs.

• Objects - an array of RelativityObjectRef instances constructed by a mass create operation.
• ArtifactID - the unique identifier for a RelativityObject instance.

Retrieve field values for a Document object or RDO

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

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/read

The body of the request for reading a subset of field values on a Document object or RDO must contain the following unless specifically identified as optional:

• Request - a request object for the read operation with the required fields set.
• Object - represents minimal information needed to identify a RelativityObject. It contains the following:
  • ArtifactID - the unique identifier for the RelativityObject instance, which contains the fields that you want to retrieve.
• Fields - an array of identifiers for the group of fields that you want to read. It contains the following:
  • ArtifactID - a unique identifier for a field, which is represented as an integer. This field is optional if you identify the field by name or GUID.
  • Name - the user-friendly name of the field. This field is optional if you identify the field by Artifact ID or GUID.
  • Guids - an unique identifier for a field. This field is optional if you identify the field by Artifact ID or name.
• ReadOptions - an optional field that may specify the calling context, the behavior and number of characters for long text fields, and other settings. For information, see the ReadOptions class in the Relativity.Services.Objects.DataContracts namespace in the Services API.
  • FieldTypesToReturnAsString - a list of object type values which should be returned as strings.
  • LongTextBehavior - indicates whether the default or tokenized behavior is used for long text fields that exceed the maximum number of characters set in the MaxCharactersForLongTextValues property. To avoid inadvertently truncating of long text fields, we recommend setting this property to 1 for tokenized behavior when you are reading or querying on long text fields, and then later performing an update operation on the returned values. You can use the default behavior for other operations, such as displaying data in a grid.

    Note: Before implementing the query operation on a long text field, review the following best practices in Use tokens with long text fields.

The sample responses contains the following fields:

• Message - a string returned by a Pre Load event handler.
• Object - an instance of a RelatvityObject containing fields and their values that were read. It contains the following:
  • ParentObject - contains the Artifact ID of the parent object associated with the RelativityObject specified by the read operation.
    • ArtifactID - a unique identifier for the object, which is represented as an integer.
    • Guid - a unique identifier for the object, which is represented as a GUID.
• Name - the user-friendly name of the RelativityObject.
• FieldValues - an array containing FieldValuePair objects. See Relativity.Services.Objects.DataContracts namespace - classes used for general functionality. It contains the following:
  • Field - a field associated with a specific value. The Field object includes:
    • ArtifactID - a unique identifier for the field, which is represented as an integer.
    • FieldCategory - indicates the specific functionality assigned to a field, such as stores descriptive text, acts as a relational field, represents grouping for batching, and others. For more information, see the FieldCategory enumeration in Services API on the Relativity API reference page.
    • FieldType - the type of a Relativity field, such as fixed-length text, date, single object, or others. For more information, see the FieldType enumeration in Relativity.Services.Objects.DataContracts namespace in the Services API.
    • Guids - an array of GUIDs used to identify the field.
    • Name - a user-friendly name for the field.
    • ViewFieldID - a unique identifier used to reference a view field.
  • Value - the data assigned to a field, represented as an Object type. It may contain one or more of the following:
    • ArtifactID - a unique identifier for the object, which is represented as an integer.
    • Guids - an array of GUIDs used to identify the object.
    • Name - a user-friendly name for the object.
• ArtifactID - a unique identifier for the RelativityObject instance, which is represented as an integer.
• Guids - an array of GUIDs used to identify the RelativityObject instance.
• ObjectType - contains information about the type of object returned from the read operation. It contains the following fields:
  • ArtifactID - a unique identifier for the ObjectType instance, which is represented as an integer.
  • Name - a user-friendly name for the object type, such as Document, Field, and others.
  • Guids - an array of GUIDs used to identify the object type.
  • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See the ArtifactType enumeration in the Services API.
• ObjectVersionToken - the version token of the RelativityObject. You can pass this value to an update request to enable record overwrite protection.

Update fields on a Document object or RDO

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

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/update

The body of the request for updating field values on a Document object or RDO must contain the following fields:

• request - a request object for the update operation with the required fields set.
• Object - contains an identifier for the object with fields that you want to update. It contains the following:
  • artifactId - a unique identifier for the object, which is represented as an integer.
• FieldValues - an array containing FieldValuePair objects. See Relativity.Services.Objects.DataContracts namespace - classes used for general functionality. It contains the following:
  • Field - contains an identifier for the field that you want to update.
    • ArtifactID - a unique identifier for the Field object, which is represented as an integer.
  • Value - a value for the field. The type of field determines the requirements for the value that you can assign to it.
• OperationOptions - contains information about how the update operation for this request is being called. It includes the following:
  • UpdateBehavior - indicates whether you want to replace or merge a choice or object. These options are available for only multiple choice and multiple object fields. See the following sample JSON for these fields.
  • CallingContext - information about the web context from which the event handler is being called, such as the originator of the call, the page mode, and the related layout. See Relativity.Services.Objects.DataContracts namespace - classes used for general functionality.

    Note: You can set the callingContext field to null if your event handlers don't need any context information, but you must include it in the JSON request. Your event handlers must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API.

    • Layout - contains an identifier for the layout where the update call originates.
      • ArtifactID - a unique identifier for the layout, which is represented as an integer.

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

The response contains the following fields:

• EventHandlerStatuses - contains information about the execution of event handlers during the update operation. It includes a status and an optional string with a related message.
  • Success - a Boolean value indicating whether the event handler execution was successful.

{
   "EventHandlerStatuses":[
      {
         "Success":true
      },
      {
         "Success":true
      }
   ]
}

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 to a URL with the following format:

<host>/relativity.rest/api/Relativity.Objects/workspace/{workspaceID}/object/updatelongtextfromstream

<host>/relativity.rest/api/Relativity.Objects/workspace/{workspaceID}/object/updatelongtextfromstream

The JSON request must include the following fields:

• updateLongTextFromStreamRequest - a request object for the updating a long text field with a stream. It contains the following fields:
  • Object - a RelativityObjectRef to be updated. It contains the following:
    • ArtifactID - the Artifact ID of an RelativityObjectRef.
  • Field - a field to be updated. The Field object contains the following:
    • ArtifactID - a unique identifier for the Field object, which is represented as an integer.
    • Guid - a GUID used to identify the object.
    • Name - the user-friendly name of the field.
    • ViewFieldID - a unique identifier used to reference a view field.

{
   "updateLongTextFromStreamRequest":{
      "Object":{
         "ArtifactID":1039314
      },
      "Field":{
         "ArtifactID":0,
         "Guid":"",
         "Name":"Extracted Text",
         "ViewFieldID":0
      }
   }
}

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.
  • 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 a large number of objects. See View a JSON request using query conditions for a mass update operation.
• Note that the identifier field can’t be updated by any mass update operation.

To execute a mass operation, use the POST method and send a request with the following URL:

<host>/Relativity.REST/api/Relativity.Objects/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.

The response contains the following fields:

• TotalObjectsUpdated - the total number of objects successfully updated.

• Success - a Boolean value indicating whether the operation completed without any errors.
• Message - explanatory information provided when an error occurs.

Retrieve a list of object dependencies

The dependencylist 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 more information on the dependency report available through 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 effected 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 doesn't have view permissions or if any of the objects don't exist.

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

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/dependencylist

The request must include the following fields:

• request - a request for a list of objects dependent on the specified Document objects or RDOs.
• Objects - an array of objects identified by their Artifact IDs.
• ArtifactID -the Artifact ID of an object.

{
    request: {
        Objects: [
            { ArtifactID: 1234567 },
            { ArtifactID: 1234568 }
        ]
    }
}

The response contains the following fields:

• ObjectType - the type of the Relativity object dependent on the object selected for deletion.
  • Secured - indicates whether the current user has permissions to view the setting in the Value field.
  • Value - represents a securable value, which is the object type.
• Action - indicates whether a dependent object is deleted or unlinked when a specific object is deleted.
• Count - indicates the number of objects with a dependency on a specific object selected for deletion.
  • Secured - indicates whether the current user has permission to view the setting in the Value field.
  • Value - represents a securable value, which is the number of dependent objects.
• Connection - indicates whether the object for deletion is a parent, or a field on a single or multiple object field.
  • Secured - indicates whether the current user has permission to view the setting in the Value field.
  • Value - represents a securable value, which is the type of relationship between the objects. For example, the value is Parent when the dependent object is a child, and Field: {field name} when the dependent object is a field on a single or multiple object field.
• HierarchicLevel - indicates the degree of dependency between object types. For example, you might select an object type for deletion that has a child object type. The fields and views associated with the child object type have a dependency with a hierarchical level of 1.

[
   {
      "ObjectType":{
         "Secured":false,
         "Value":"Parent Object Type"
      },
      "Action":"Delete",
      "Count":{
         "Secured":false,
         "Value":2
      },
      "Connection":{
         "Secured":false,
         "Value":"Parent"
      },
      "HierarchicLevel":0
   },
   {
      "ObjectType":{
         "Secured":false,
         "Value":"Child Object Type"
      },
      "Action":"Delete",
      "Count":{
         "Secured":false,
         "Value":3
      },
      "Connection":{
         "Secured":false,
         "Value":"Child of: Parent Object Type"
      },
      "HierarchicLevel":0
   }
]

Delete a Document object or RDO

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

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/delete

The body of the request for deleting Documents and RDOs must include the following fields:

• Request - a request object for the delete operation with the required fields set.
• Object - represents minimal information needed to identify a RelativityObject that you want to delete. It contains the following:
  • ArtifactID - the unique identifier for a RelativityObject instance.

{
   "Request":{
      "Object":{
         "ArtifactID":1051263
      }
   }
}

The response contains the following fields:

• Report - contains a list of one or more DeleteItems objects.
• DeleteItems - information about the items that were removed. The DeleteItems object includes:
  • ObjectTypeName - identifies the child or associative object that has a dependency on the object selected for deletion.
  • Action - the operation performed to remove the object. Delete is the action for child objects, and Unlink is the action for associative objects.
  • Count - the number of items removed.
  • Connection - indicates a relationship to the object selected for deletion, such as parent, child, and associative object.

{
   "Report":{
      "DeletedItems":[
         {
            "ObjectTypeName":"Custom Object",
            "Action":"Delete",
            "Count":1,
            "Connection":"Parent"
         }
      ]
   }
}

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.
• Provide a list of identifiers for objects that you want to delete. Use the Artifact IDs of these objects as identifiers.

Use the POST method and send a request with the following URL for a mass delete operation:

<host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/delete

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

The response contains the following fields:

• Success - a Boolean value indicating whether the operation completed without any errors.
• Message - explanatory information provided when an error occurs.

• Report - contains a list of the DeleteItems objects.
• DeletedItems - see the field descriptions provided in Delete a Document object or RDO.

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, use a POST method and send a request with one of the following URL formats:

• Query endpoint

  <host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/query

• QuerySlim endpoint

  <host>/Relativity.REST/api/Relativity.Objects/workspace/{workspaceID}/object/queryslim

In the body of the request, the following fields are required unless specifically identified as optional:

• Request - a request object for the query operation with the required fields set.
  • ObjectType - contains information about the type of object that you want to query on. You can identify an object type by its name, Artifact ID, or GUID. It may contain any one of the following fields:
    • Guid - a unique identifier for the object type. This field is listed in the sample JSON.
    • Name - the user-friendly name of the object type.
    • ArtifactTypeID - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See the ArtifactType enumeration in the Services API.
  • fields - a collection of fields used like a SELECT statement in an SQL query. For a query request, you can identify fields by name, Artifact ID, or GUID. This field is optional.
    • Guid - a unique identifier for a field.
    • ArtifactID - a unique identifier for the field, which is represented as an integer.

    • Name - a user-friendly name for the field.

    Example:

    "fields":
    
    {"Name":"*"}

  • conditions - the search criteria used in the query. This field is optional.
  • LongTextBehavior - indicates whether the default or tokenized behavior is used for long text fields that exceed the maximum number of characters set in the MaxCharactersForLongTextValues property. To avoid inadvertently truncating of long text fields, we recommend setting this property to 1 for tokenized behavior when you are reading or querying on long text fields, and then later performing an update operation on the returned values. You can use the default behavior for other operations, such as displaying data in a grid.

    Note: Before implementing the query operation on a long text field, review the following best practices in Use tokens with long text fields.

  • sorts - a collection of Sort objects. This field indicates whether the results are sorted in ascending or descending order, and identifies the field used to sort the results by name. This field is optional. See the Sort class in the kCura.Relativity.Client namespace.
  • QueryHint - set a QueryHint field to optimize the view. For example, you can use the hashjoin setting with the value of true or false, or you can use the waitfor setting with a value, such as waitfor:5. This field is optional. For more information about general query options, see Query for resources.
• start - the one-based index of the first artifact in the result set.
• length - the number of items to return in the query result, starting with index in the start field.

The response for a query includes information about the number of results returned, the start index in the result set, and the object type that was queried. The information in the response depends on whether you executed the search using the Query or QuerySlim endpoint. See the following JSON examples.

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 to the following URL:

<host>/Relativity.REST/api/Relativity.Objects/workspace/<workspace artifact id>/object/initializeexport

<host>/Relativity.REST/api/Relativity.Objects/workspace/<workspace artifact id>/object/initializeexport

The body of the request must include the following fields:

• workspaceID - the Artifact ID of the workspace containing the data to export.
• queryRequest - a query that specifies the data set to export. It includes the following fields:
  • ObjectType - an integer value used as an identifier for an object type supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See the ArtifactType enumeration in the Services API.
  • fields - an array containing the Artifact IDs of the fields for export.
  • condition - the query used to determine the set of objects for export. The maximum length of text to export can be optionally specified inline. For information about constructing queries, see Query for Relativity objects.

    Note: You can use the MaxCharactersForLongTextValues field of the queryRequest object to override the number limit set by the MaximumLongTextSizeForExportInCell instance setting. For more information, see Set up the export job in .NET, and Instance setting descriptions on the Relativity 9.6 Documentation site.

• start - the zero-based index of a record indicating where to begin the export operation.

{
  "queryRequest": {
      "ObjectType": {"ArtifactTypeID":10},
      "fields":[
         {
            "ArtifactID":1003668
         }
      ],
      "condition":"'Extracted Text' ISSET "
   },
  "start":0
}

The response contains the following fields:

• RunID - a unique identifier for the export job.
• RecordCount - the number of records that were exported.

{
    "RunID": "60b6d8c2-9475-4fda-80bb-339f4dcad504",
    "RecordCount": 100000
}

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 very 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 to the following URL:

<host>/Relativity.REST/api/Relativity.Objects/workspace/<workspace artifact id>
/object/retrievenextresultsblockfromexport

The body of the request must include the following fields:

• workspaceID - the Artifact ID of the workspace containing the data to export.
• runID - the unique identifier for the in-progress export job.
• batchSize - the maximum number of results to return in a single call.

{
  "runID": "1f485684-e28c-4204-a795-f11dc91c0f3a",
  "batchSize":5
}

The response contains a collection of objects with the following fields:

• ArtifactID - the Artifact ID of an object.
• Values - the text from the fields included in the export job.

[
  {
    "ArtifactID": 1048512,
    "Values": [
      "Test CHINA CLEANS UP FISCAL & TAXATION PREFERENTIAL POLICIES from AsiaInfo Services\r\n\r\nBEIJING, Jun 26, 2002 (AsiaPort via COMTEX) -- Chinese government continues theefforts to clean up completely all kinds of fiscal and taxationpreferential policies and fiscal subsidy policies, abolish fiscaland taxation preferential policies for a few enterprises and areas,and abolish fiscal subsidy styles that do not accord with Chinesegovernment' s commitment and the WTO regulations.\r\n\r\nOn the basis of seriously cleaning up fiscal and taxation laws, rules and systems, Chinese government will continue to revise the contents that do not in accordance with Chinese\r\n"
    ]
  },
  {
    "ArtifactID": 1048513,
    "Values": [
      "Sally International affairs\r\nOvertaxed.\r\n\r\nWorkout Chinese rural taxation in the context of government regulation.\r\nSharing and Collaboration Policies within Government Agencies.\r\nCorporate Sector: Surtax\r\n\r\n"
    ]
  },
  {
    "ArtifactID": 1048519,
    "Values": [
      "Are Government Policies More Important Than Taxation in Attracting FDI?\r\n\r\nThis paper attempts to broaden the existing empirical literature on foreign direct investment by incorporating government expenditure policies, such as investment in infrastructure, and institutional factors that may impact business investment, such as corruption, along with other conventional determinants such as taxes, location factors, and agglomeration effects. We do so in an unbalanced panel data setting, where we use fixed effects to control for country specific idiosyncrasies and also year dummies in some specifications. Our data include both developing and developed countries in different regions of the world. The regression results indicate that better infrastructure and lower taxes attract FDI, with weaker evidence suggesting lower corruption also increases FDI. These results are robust and hold after controlling for fixed country effects, common year effects of FDI, and agglomeration effects. The magnitude of the response of FDI to infrastructure changes is similar to that of taxes in elasticity terms. The results add evidence to previous cross-sectional results and emphasize the importance of a range of government policies in addition to taxation in attracting foreign direct investment."
    ]
  },
  {
    "ArtifactID": 1048520,
    "Values": [
      "Foreign Affairs:\r\n\r\nInternational relations (IR) represents the study of foreign affairs and global issues among states within the international system, including the roles of states, inter-governmental organizations (IGOs), non-governmental organizations (NGOs), and multinational corporations (MNCs). It is both an academic and public policy field, and can be either positive or normative as it both seeks to analyze as well as formulate the foreign policy of particular states. It is often considered a branch of political science.\r\n\r\nApart from political science, IR draws upon such diverse fields as economics, history, law, philosophy, geography, sociology, anthropology, psychology, and cultural studies. It involves a diverse range of issues including but not limited to: globalization, state sovereignty, ecological sustainability, nuclear proliferation, nationalism, economic development, terrorism, organized crime, human security, foreign interventionism and human rights.\r\n"
    ]
  }
]

The following JSON response contains the #KCURA99DF2F0FEB88420388879F1282A55760# token instead of the text.

[
  {
    "ArtifactID": 1048512,
    "Values": [
      "#KCURA99DF2F0FEB88420388879F1282A55760#"
    ]
  },
  {
    "ArtifactID": 1048513,
    "Values": [
      "#KCURA99DF2F0FEB88420388879F1282A55760#"
    ]
  },
  {
    "ArtifactID": 1048515,
    "Values": [
      "#KCURA99DF2F0FEB88420388879F1282A55760#"
    ]
  },
  {
    "ArtifactID": 1048517,
    "Values": [
      "#KCURA99DF2F0FEB88420388879F1282A55760#"
    ]
  },
  {
    "ArtifactID": 1048518,
    "Values": [
      "#KCURA99DF2F0FEB88420388879F1282A55760#"
    ]
  }
]

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 to the following URL:

<host>/Relativity.REST/api/Relativity.Objects/workspace/<workspace artifact id>
/object/RetrieveResultsBlockFromExport

The body of the request must include the following fields:

• runID - the unique identifier for the in-progress export job.
• resultsBlockSize - the maximum number of results to return in one call.

  Note: The actual number of results returned may be less than the maximum number requested.

• exportIndexID - the export block index ID of a batch.

{
   "runID":"310a6c13-3619-45fd-8723-bfaad86dfa45",
   "resultsBlockSize":4,
   "exportIndexID":0
}

The response contains a collection of objects with the following fields:

• ArtifactID - the Artifact ID of an object.
• Values - the text from the fields included in the export job.

[
  {
    "ArtifactID": 1048512,
    "Values": [
      "Test CHINA CLEANS UP FISCAL & TAXATION PREFERENTIAL POLICIES from AsiaInfo Services\r\n\r\nBEIJING, Jun 26, 2002 (AsiaPort via COMTEX) -- Chinese government continues theefforts to clean up completely all kinds of fiscal and taxationpreferential policies and fiscal subsidy policies, abolish fiscaland taxation preferential policies for a few enterprises and areas,and abolish fiscal subsidy styles that do not accord with Chinesegovernment' s commitment and the WTO regulations.\r\n\r\nOn the basis of seriously cleaning up fiscal and taxation laws, rules and systems, Chinese government will continue to revise the contents that do not in accordance with Chinese\r\n"
    ]
  },
  {
    "ArtifactID": 1048513,
    "Values": [
      "Sally International affairs\r\nOvertaxed.\r\n\r\nWorkout Chinese rural taxation in the context of government regulation.\r\nSharing and Collaboration Policies within Government Agencies.\r\nCorporate Sector: Surtax\r\n\r\n"
    ]
  },
  {
    "ArtifactID": 1048519,
    "Values": [
      "Are Government Policies More Important Than Taxation in Attracting FDI?\r\n\r\nThis paper attempts to broaden the existing empirical literature on foreign direct investment by incorporating government expenditure policies, such as investment in infrastructure, and institutional factors that may impact business investment, such as corruption, along with other conventional determinants such as taxes, location factors, and agglomeration effects. We do so in an unbalanced panel data setting, where we use fixed effects to control for country specific idiosyncrasies and also year dummies in some specifications. Our data include both developing and developed countries in different regions of the world. The regression results indicate that better infrastructure and lower taxes attract FDI, with weaker evidence suggesting lower corruption also increases FDI. These results are robust and hold after controlling for fixed country effects, common year effects of FDI, and agglomeration effects. The magnitude of the response of FDI to infrastructure changes is similar to that of taxes in elasticity terms. The results add evidence to previous cross-sectional results and emphasize the importance of a range of government policies in addition to taxation in attracting foreign direct investment."
    ]
  },
  {
    "ArtifactID": 1048520,
    "Values": [
      "Foreign Affairs:\r\n\r\nInternational relations (IR) represents the study of foreign affairs and global issues among states within the international system, including the roles of states, inter-governmental organizations (IGOs), non-governmental organizations (NGOs), and multinational corporations (MNCs). It is both an academic and public policy field, and can be either positive or normative as it both seeks to analyze as well as formulate the foreign policy of particular states. It is often considered a branch of political science.\r\n\r\nApart from political science, IR draws upon such diverse fields as economics, history, law, philosophy, geography, sociology, anthropology, psychology, and cultural studies. It involves a diverse range of issues including but not limited to: globalization, state sovereignty, ecological sustainability, nuclear proliferation, nationalism, economic development, terrorism, organized crime, human security, foreign interventionism and human rights.\r\n"
    ]
  }
]

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 to the following URL:

<host>/Relativity.REST/api/Relativity.Objects/workspace/<workspace artifact id>
/object/streamlongtext

The body of the request must include the following fields:

• workspaceID - the Artifact ID of the workspace containing the object to be retrieved.
• exportObject - a RelativityObjectRef of the document that contains the text to be streamed.
• longTextField - a FieldRef of the long text field that contains the text to be streamed.

{
  "exportObject": {
    "ArtifactID": 1048519
  },
  "longTextField": {
    "ArtifactID": 1003668
  }
}

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