The RelatvityOne - February 3, 2018 release includes multiple enhancements and other modifications to the Object Manager service. On-premise Relativity will include these features in a later release. For more information on available features, see What's new for developers in Relativity 9.5.

The content on this page has been updated for RelatvityOne - February 3, 2018 and above. If you want information about using the Object Manager service with older versions of Relativity, see Deprecated content for Object Manager API with REST.

Object Manager API with REST

The Object Manager service available in the REST API includes functionality for creating Relativity Dynamic Objects (RDOs) and setting values on their associated fields. It supports updating and reading fields on Document objects or RDOs, as well as deleting these objects. You can modify the field types currently available on a Relativity object, including currency, date, user, and others. Additionally, the Object Manager service supports querying for Workspaces, Documents, RDOs and system types.

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

This page contains the following information:

See these related pages:

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", string.Empty);
        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 - contains the Artifact Type ID of an ObjectType. For example, the Artifact Type ID for a Document object is 10. See ArtifactType enumeration on Relativity API reference.
  • 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.

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 object.
  • 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 object, which is represented as an integer.
  • Guids - an array of GUIDs used to identify the RelativityObject object.
  • 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.

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 specific subset of field values on a Document object or RDO must contain the following:

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

The response contains the following fields:

  • Message - a string returned by a Pre Load event handler.
  • Object - an instance of RelatvityObject containing fields and their values that were read. It contains the following:
    • ParentObject - contains the Artifact ID of the parent object associated with RelativityObject specified by the read operation.
      • 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. 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 identifier used to specify object types supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See ArtifactType enumeration on Relativity API reference.

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

      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 Object Manager service doesn't currently support updating file fields.

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 a string with a related message.
    • Success - a Boolean value indicating whether the event handler execution was successful.
{
   "EventHandlerStatuses":[
      {
         "Success":true
      },
      {
         "Success":true
      }
   ]
}

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.
  • OperationOptions - contains information about how the delete operation for this request is being called. It includes the following:
    • CallingContext - provides information about the web context from which an event handler is being called. This field must be included in the JSON request, but you can set it to null if the calling context isn't needed.

      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.

{
   "Request":{
      "Object":{
         "ArtifactID":0
      }
   },
   "OperationOptions":{
      "CallingContext":null
   }
}

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"
         }
      ]
   }
}

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 identifier used to specify object types supported by Relativity. For example, the Artifact Type ID for a Document object is 10. See ArtifactType enumeration on Relativity API reference page.
    • 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.
    • conditions - the search criteria used in the query. For more information, see System types supported by the Query() method. This field is optional.
    • 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 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.