Deprecated content alert

The Object Manager service has undergone extensive enhancements as of the RelatvityOne - February 3, 2018. The content on this page contains code samples and other information that is now deprecated. It applies only to the following versions of Relativity:

  • RelativityOne - January 6, 2018 and below
  • On-prem Relativity 9.5.411.4 - January 31, 2018 and below

If you want about information about using the Object Manager service in RelatvityOne - February 3, 2018 and above, see Object Manager API with REST.

Deprecated content for 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 Deprecated content for Object Manager API in .NET.

This page contains the following information:

Client code sample

Depending on the operation performed by the Object Manager service, you use an HTTP request that makes a GET or POST method call. See the following base URL for this service:

<host>/Relativity.REST/api/Relativity.Objects/workspaces/{workspaceID}/objects/

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<ObjectUpdateResult> UpdateExample()
    {
        ObjectUpdateResult 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 = $"{{\"relativityObject\":{{\"artifactID\":{objectArtifactID},\"FieldValuePairs\":[{{\"Field\":{{\"ArtifactID\":{fieldArtifactID}}},\"Value\":\"{valueToUpdate}\"}}]}}}}";
            var url = $"workspaces/{workspaceId}/objects/{objectArtifactID}";
            var response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
            response.EnsureSuccessStatusCode();
            var content = await response.Content.ReadAsStringAsync();
            result = JsonConvert.DeserializeObject<ObjectUpdateResult>(content);
            return result;
        }
        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/workspaces/{workspaceID}/objects/create

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

  • relativityObject - The RelativityObject contains the following fields:
    • ObjectTypeRef - 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.
    • FieldValuePairs - the field value pairs must contain the Artifact ID or name of any required field, and the value for the field. The type of field determines the requirements for the value that you can assign to it. See Relativity.Services.Field namespace.
  • 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.Models.WebContent.

The response contains the following fields:

  • RelativityObject - an instance of RelatvityObject containing fields and their values that were created. See Relativity.Services.Objects.Models namespace.
    • ParentArtifactID - the Artifact ID of the parent of the newly created RelativityObject object.
    • FieldValuePairs - an array containing FieldValuePair objects. See Relativity.Services.Field namespace.
    • ArtifactID - a unique identifier for the RelativityObject object, which is represented as an integer.
    • ObjectTypeRef - contains minimal information about an RelativityObject object, including the ArtifactID, Guids, and DisplayText properties.
  • 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/workspaces/{workspaceID}/objects/{objectID}/read

The body of the request for reading a specific subset of field values on a Document object or RDO must contain the following:

  • FieldRefs - an array of Artifact IDs, which identify the fields containing values that you want to read.
  • ArtifactID - a unique identifier for a field. You can use either the ArtifactID or the Name to identify the field.
  • Name - the user-friendly name of the field. If you use the ArtifactID to identify the field, then you don't need to include the Name field.
  • 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.Models.WebContent.

    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.

The response contains the following fields:

  • Message - a string returned by a Pre Load event handler.
  • RelativityObject - an instance of RelatvityObject containing fields and their values that were read. See Relativity.Services.Objects.Models namespace.
  • FieldValuePairs - an array containing FieldValuePair objects. See Relativity.Services.Field namespace.
  • 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.
    • 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.
  • ArtifactID - a unique identifier for the RelativityObject object, which is represented as an integer.

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/workspaces/{workspaceID}/objects/{objectID}

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

  • relativityObject - the Artifact ID of the object that you want to update.
  • FieldValuePairs on the relativityObject - the field value pairs must contain the Artifact ID or name of the field that you want to update, and the new value for the field. The type of field determines the requirements for the value that you can assign to it.
  • 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.Models.WebContent.

    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.

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 returns the status of each event handler that executed during the update. For more information, see the ObjectUpdateResult class in Relativity.Services.Objects.Models namespace.

{
   "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/workspaces/{workspaceID}/objects/{objectID}/delete

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

  • RelativityObjectRef - contains the Artifact ID or GUID of the object that you want to delete.
  • 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.

{
   "RelativityObjectRef":{
      "ArtifactID":1040075
   },
   "CallingContext":null
}

The response contains the following fields on a :

  • DeleteReport - contains a list of one or more DeleteItems objects.
  • DeleteItems - information about the items that were removed. The DeleteItems object includes:
    • ObjectType - 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.
{
   "DeleteReport":{
      "DeleteItems":[
         {
            "ObjectType":"Custom Object",
            "Action":"Delete",
            "Count":1,
            "Connection":"Parent"
         }
      ]
   }
}

Query for Relativity objects

To query for Workspaces, Documents, RDOs, and system types, use a POST method and send a request with the following URL format:

<host>/Relativity.REST/api/Relativity.Objects/workspaces/{workspaceID}/objects/query

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

  • artifactTypeId - the identifier for the artifact type that you want to query on. You can set either the DescriptorArtifactTypeID or the Guids field, but you must set one of these fields in the JSON request.
  • query - a collection of settings used to search for Relativity objects. The Query object contains the following fields:
    • 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.
    • 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, the object type that was queried, and additional information.