Object Manager (.NET)

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 API provides you with the ability to programmatically work with RDOs and Document objects. It exposes methods for performing the following tasks:

  • Create RDOs and set values on their associated fields.
  • Update fields on Document objects or RDOs.
  • Read fields on Document objects or RDOs.
  • Retrieve a list of dependent objects prior to deleting a specific object.
  • Perform mass operations to create, update, and delete Document objects or RDOs.
  • Query for Workspaces, Documents, RDOs and system types.
  • 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 REST. However, the REST endpoints do not support cancellation tokens or progress indicators. For more information, see Object Manager (REST).

The Relativity.ObjectManager.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for the Object Manager service

Review the following information to learn about the methods, classes, and exceptions used by the Object Manager service.

Note: The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 in .NET.

Guidelines for using the Object Manager service

Use the following guidelines when working with the Object Manager service:

Use tokens with long text fields

Use tokens when you are reading or querying on long text fields, and then later performing an update operation on the returned values. This best practice ensures that a long text field is not inadvertently truncated when performing these operations. You can use the default behavior for other operations, such as displaying data in a grid.

To use tokenized behavior, call the read or query methods as follows:

Note: Avoid using the default behavior for LongTextBehavior property for read or query operations when you want to later perform an update operation on the returned values. The tokenized behavior prevents the characters in long text fields from being truncated.

IObjectManager instance

You can create an IObjectManager instance through a ServiceFactory instance or the Relativity API Helpers. If you want to access the service from a custom page or event handler, use the Relativity API Helpers. For more information, see Relativity API Helpers.

Supported field types

The Object Manager API supports create, read, update, delete, and query operations on the following field types.

For file field, the Object Manager API supports read, delete, and query operations. To update file fields, follow the workflow described in the File Field Manager Service.

Propagation

The Object Manager service updates fields on a Document object, which are enabled for propagation. It also updates the enabled fields on all Document objects related to this initially updated object.

Event handlers

The Object Manager API supports interacting with event handlers. Review the following guidelines for using the Object Manager API in event handlers. For more information, see Event Handlers.

Indexers on the RelativityObject class

You can access FieldValuePair objects returned from a read or query operation by using the indexers on the RelativityObject class. The indexers consume either the GUID, Artifact ID, or Name of a Field object. They then use the specified identifier for a Field to return the corresponding FieldValuePair object.

The following sample code illustrates how to use an indexer to access a FieldValuePair object returned in the results from a read operation.

Create an RDO and its specified fields

Use the CreateAsync() method to create an RDO with the values set for the existing fields on it. You call this method by passing the following parameters:

  • The Artifact ID of the workspace where you want to create the RDO.
  • A CreateRequest object with the following properties set:
    • FieldValues - a list of field-value pairs that you want to set on the new RDO.
    • ObjectType - the Artifact Type ID of the ObjectType for the RDO that you want to create. For example, the Artifact Type ID for a Document object is 10.
    • ParentObject - the Artifact ID of the parent object of the for the new RelativityObject.

      Note: If you do not specify a parent object, Relativity defaults to the System object as the parent.

  • An OperationOptions instance that references a CallingContext instance. The CallingContext instance provides 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.

    Note: You must set the CallingContext property on OperationOptions object if you have event handlers that depend on a layout. The event handlers will not function properly when this property is not set. If your event handlers do not require context information, they must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API.

The following code sample illustrates the information that you need to provide to create an RDO, and to set a group of specified fields.

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.

Note: If you specify an identifier that is already in the database, an exception will not be thrown. Instead, the Success property on the MassCreateResult object is set to false. Always check the value of the Success property on the results object as a best practice.

To mass create RDOs, pass a MassCreateRequest object as an argument to the CreateAsync() method. This object contains properties for the parent object type, the object type that you are creating, the fields to set, and the values to use for this purpose.

Note: If you do not specify a parent object, Relativity defaults to the System object as the parent.

The overloaded CreateAsync() method supports progress reporting, and cancellation requests for mass update operations. See the following code sample.

Retrieve field values for a Document object or RDO

Use the ReadAsync() method to retrieve the field values on a Document object or RDO. The method returns fields that you can add to a layout in your custom application.

You call this method by passing the required combination of the following parameters:

  • The Artifact ID of the workspace containing the Document object or RDO that you want to read.
  • ReadRequest object - contains information about the fields to retrieve, and the RelativityObject instance associated with these fields.
  • An optional ReadOptions or OperationOptions object that has a CallingContext and other properties. You can use the ReadOptions class to specify the calling context, the behavior and number of characters for long text fields, and other settings.

    The following list highlights key properties on the ReadOptions class, and suggested setting for them:

    • CallingContext - The CallingContext object provides 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.

      You must set the CallingContext property on ReadOptions or OperationOptions object if you have event handlers that depend on a layout. The event handlers will not function properly when this property is not set. If your event handlers do not require context information, they must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers 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 read operation on a long text field, review the following best practices in Use tokens with long text fields.

The following code sample illustrates how to read a specified subset of fields.

Update field values on a Document object or RDO

Use the UpdateAsync() method to modify a field on a Document object or RDO. You call this method by passing the following parameters:

  • The Artifact ID of the workspace containing the Document object or RDO that you want to update.
  • An UpdateRequest object containing information about the fields to update, and the RelativityObject instance associated with these fields.
  • An optional UpdateOptions object that has CallingContext and UpdateBehavior properties. The CallingContext property provides 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. The UpdateBehavior property indicates whether to merge or replace values when updating multiple choice and multiple object fields.

    Note: You must set the CallingContext property on UpdateOptions object if you have event handlers that depend on a layout. The event handlers will not function properly when this property is not set. If your event handlers do not require context information, they must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API.

Update field values on a single object

The following code samples illustrates how to update field values on a single Document object or RDO. The process for updating other field types is like that used for updating a single object:

  • Create a new RelativityObject instance and set the ArtifactID property.
  • Create a new FieldValuePair instance and set the Field and Value properties on it.
  • On the UpdateRequest object, set the Object property to the RelativityObject instance, and the FieldValues property to a list of FieldRefValuePair objects.
  • Call the UpdateAsync() method by passing the required parameters.

Note: If you need to update a long text field that exceeds the length limits of an HTTP request, use the UpdateLongTextFromStreamAsync() method. For more information, see Update field values on a multiple object.

Update field values on a multiple object

To updates field values on a multiple object or choice, you follow many of the same steps as those for updating a single object. You can also optionally specify the update behavior on the UpdateOptions object, which is passed to the UpdateAync() method. The FieldUpdateBehavior enumeration is used to specify this behavior. It includes the following options:

  • Merge - adds the values that you pass into the service to the current values for the choice or object field.
  • Replace - overwrites the current values for the choice or object field with those that you pass into the service.

This behavior is now set for the entire update operation. If you do not pass a UpdateOptions instance to this method, the service replaces the values by default.

Note: The update operation for field values on a multiple object works the same way on a multiple choice field.

Update a long text field using an input stream in .NET

You can use the UpdateLongTextFromStreamAsync() method to update a single long text field that exceeds the length limits of an HTTP request. This method does not trigger an event handler.

Note: You can use the UpdateAsync() method to update a single long text field with a length less than the HTTP request limits. For more information, see Update field values on a single object.

The following code sample illustrates how to instantiate the UpdateLongTextFromStreamRequest object and required stream objects. It then shows how to pass the workspace ID and these objects to the UpdateLongTextFromStreamAsync() method.

Mass update Document objects or RDOs

Use the overloaded UpdateAsync() method to mass update RDOs. You can mass update Document objects or RDOs 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. You can set this information in a MassUpdateByCriteriaRequest object and then pass it as one of the arguments to the UpdateAsync() method. 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. 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 or GUIDs of these objects as identifiers. You can set this information in a MassUpdateByObjectIdentifiersRequest object and then pass it as one of the arguments to the UpdateAsync() method. 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. See Mass update operation using identifiers.
  • To set different values for specific fields on a group of objects, provide a list of fields for updating. Additionally, provide list of Artifact IDs for 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. You can set this information in a MassUpdatePerObjectsRequest object and then pass it as one of the arguments to the UpdateAsync() method. See Mass update operation using objects.

Similar to updating a single object, the overloaded UpdateAsync() method supports progress reporting, and cancellation requests for mass update operations.

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 Mass update operation using query conditions.
  • Note that the identifier field cannot be updated by any mass update operation.

Mass update operation using query conditions

The following code sample illustrates how to set the ObjectIdentificationCriteria property on the MassUpdateByCriteriaRequest object to mass update objects based on search conditions. For searching information, see Query for resources.

Mass update operation using identifiers

The following code sample illustrates how to set theMassUpdateByObjectIdentifiersRequest object to mass update Document objects or RDOs based on a list of RelativityObjectRef instances. The RelativityObjectRef class has properties for the Artifact ID and GUID that you can use to reference an object.

Mass update operation using objects

The following code sample illustrates how to set the Fields and ObjectValues properties on a MassUpdatePerObjectsRequest object. This object is used to mass update Document objects or RDOs by setting different values for specific fields on a group of objects. The fields variable references the list of fields for updating, and the objectRefValuesPairs variable is a combination of the RelativityObjects to be updated and the values used for this purpose. The values must be provided in the same order as the fields that they are used to update.

Retrieve a list of object dependencies

The GetDependencyListAsync() method retrieves information about Relativity objects dependent on one or more specific objects selected for deletion. It returns a list of Dependency objects, which contain 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 method 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 GetDependencyListAsync() method:

  • Call the method with objects of the same type. If you call the method with objects of different types, it returns an error.
  • Call the method 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.

Delete a Document object or RDO

Use the DeleteAsync() method to remove Document objects and all their associated files, and RDOs from Relativity. You call this method by passing the following parameters:

  • The Artifact ID of the workspace containing the Document object or RDO that you want to delete.
  • A DeleteRequest object containing the Artifact ID or GUID of the RelativityObject instance that you want to delete.

If you use the overloaded DeleteAsync() method, you can also pass the following arguments:

  • CancellationToken - used to request the cancellation of a delete operation. This object has the type System.Threading.CancellationTokenSource provided by the .NET framework.
  • IProgress<DeleteProcessStateProgress>object - used to define a provider for progress updates.

Mass delete Document objects or RDOs

You can use the overloaded DeleteAsync() method to mass delete Document objects or RDOs. All the objects in a mass delete operation must be the same type. Additionally, you can mass delete these objects in the following ways:

  • Use a query to identify objects that you want to delete. Only the items that match the query conditions are deleted. You can set this information in a MassDeleteByCriteriaRequest object and then pass it as one of the arguments to the DeleteAsync() method. See Mass delete operation using query conditions.
  • Provide a list of identifiers for objects that you want to delete. Use the Artifact IDs or GUIDs of these objects as identifiers. You can set this information in an MassDeleteByObjectIdentifiersRequest object and then pass it as one of the arguments to the DeleteAsync() method. See Mass delete operation using identifiers.

The overloaded DeleteAsync() method supports progress reporting, and cancellation requests for mass delete operations.

Mass delete operation using query conditions

The following code sample illustrates how to set the ObjectIdentificationCriteria property on the MassDeleteByCriteriaRequest object to mass delete objects based on search conditions. For more information, see Query for resources.

Mass delete operation using identifiers

The following code sample illustrates how to set the Objects property on the MassDeleteByObjectIdentifiersRequest object to mass delete Document objects or RDOs based on a list of RelativityObjectRef instances. The RelativityObjectRef class has properties for the Artifact ID and GUID that you can use to reference an object.

Query for Relativity objects

With the Object Manager service, you can query for Workspaces, Documents, RDOs, and system types. This service includes the QueryAsync() method, which returns detailed information about the field-value pairs returned by the query. The QuerySlimAsync() method returns a smaller payload, which saves bandwidth. This method is useful for mobile devices and for displaying tabular data. For more information, see System types supported by the Query() method.

The following code samples illustrate how to run a query for Document objects using the Object Manager service. They illustrate how to define the query, call the QueryAsync() method, and return a QueryResult object containing the search results.

Export API

The Object Manager API supports exporting document fields, including complete long text fields such as extracted text, via a set of endpoints collectively called the Export API. This export functionality differs in the following ways from the standard document access performed by the Object Manager API:

  • During the initialization method, the complete document list to be returned is generated from the query provided. This allows the API to guarantee that each document’s data is only returned once.
  • The complete text of long text fields is available.
  • Methods to access the data and long text may be safely called concurrently by different threads or processes, allowing for high throughput.

See the following subsections for more information:

Export API workflow

The export process is multiple step workflow that uses several methods on the IObjectManager interface:

  • Set up an export job - use the InitializeExportAsync() method to set up the export job. It also retrieves a runID used in the RetrieveNextResultsBlockFromExportAsync() and RetrieveResultsBlockFromExportAsync() methods.
  • Retrieve objects - use the RetrieveNextResultsBlockFromExportAsync() method to retrieve successive blocks of document fields or use the RetrieveResultsBlockFromExportAsync() method to retrieve a specific block of document fields from an in-progress export job.
  • Stream text- use the StreamLongTextAsync() method to retrieve the text that exceeds the size limit for the data returned by RetrieveNextResultsBlockFromExportAsync() and RetrieveResultsBlockFromExportAsync() methods. Call this method repeatedly, and optionally, in parallel with the RetrieveNextResultsBlockFromExportAsync(), RetrieveResultsBlockFromExportAsync(), and other StreamLongTextAsync() method calls.

For an example of this workflow, see Export API code sample.

Set up an export job

Use the InitializeExportAsync() method to set up the export of documents from a workspace based on a query. You call this method by passing the following parameters:

  • workspaceID - the Artifact ID of the workspace containing the data to export.
  • queryRequest - the query that defines the data set to export, including ObjectType and Fields, query condition, and an optional maximum text length to export inline. For more information, see Query for Relativity objects.

    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 Instance settings' descriptions on the Relativity Documentation site.

    The semantics of MaxCharactersForLongTextValues field is slightly different than other Object Manager API uses:

    • It sets the size limit to text that is retrieved inline as part of the results of RetrieveNextResultsBlockFromExportAsync() and RetrieveResultsBlockFromExportAsync() methods.
    • It does not truncate the text that exceeds the size limit. If the long text is less than the size limit, it is added to the field. If it exceeds the size limit, a short marker is added to the field. This marker indicates that the full long text should be retrieved through StreamLongTextAsync() method. For more information, see Stream text.
  • start - the zero-based index of a record indicating where to begin the export operation.

This method returns an instance of ExportInitializationResults class, which contains the following:

  • A GUID runId used with the RetrieveNextResultsBlockFromExportAsync() method.

    Note: After an export job is initialized, the export RunID only valid for seven days. The export job then expires and is no longer available for retrieving blocks of documents.

  • A count of type long, which indicates the number of documents to be exported.
  • A List of FieldMetadata information about the requested fields, including the field type. This information simplifies identifying LongText fields that require special processing.

For the complete code, see Export API code sample.

Copy

ExportInitializationResults exportInitializationResults =
    objectManager.InitializeExportAsync(workspaceId, queryRequest, 0).Result;

Retrieve objects

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

  • RetrieveNextResultsBlockFromExportAsync() method - retrieves successive blocks of document fields from an in-progress export job. See Retrieve the next block of records.
  • RetrieveResultsBlockFromExportAsync() method - 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 the RetrieveResultsBlockFromExportAsync() method 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 methods:

  • They retrieve long text fields up to the size limit specified during initialization. Long text fields larger than the size set by MaxCharactersForLongTextValues property on the QueryRequest object contain the text value #KCURA99DF2F0FEB88420388879F1282A55760#. This value indicates that the text in the long text field should be retrieved using the StreamLongTextAsync() method.
  • They return 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 RetrieveNextResultsBlockFromExportAsync() method to get the next block of records from an in-progress export job. You call this method by passing the following parameters:

  • workspaceID - the Artifact ID of the workspace containing the data to export.
  • runID - the in-progress export ID.
  • batchSize - the maximum number of results to return in one call.

The returned RelativityObjectSlim array contains the data for multiple documents, up to and including batchSize. The fields for each document appear in the order defined in the QueryRequest object during initialization.

Retrieve a specific block of records

Use the RetrieveResultsBlockFromExportAsync() method to get a specific block of records from an in-progress export job. You call this method by passing the following parameters:

  • workspaceID - the Artifact ID of the workspace containing the data to export.
  • runID - the in-progress export ID.
  • 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 the batch.

The returned RelativityObjectSlim array contains the data for multiple documents, up to and including the resultsBlockSize, or it may include less the maximum number requested. The fields for each document appear in the order defined in the QueryRequest object during export initialization.

Stream text

Use the StreamLongTextAsync() method to retrieve a stream of text for long text fields marked as exceeding the size limit for the data returned by the RetrieveNextResultsBlockFromExportAsync() or the RetrieveResultsBlockFromExportAsync() method. For more information, see Retrieve objects.

You call the StreamLongTextAsync() method by passing the following parameters:

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

The resulting stream is encoded using UTF-16 and begins with a Unicode Byte Order Mark. We recommend that you look for the UTF-8 Byte Order Mark (0xEF,0xBB,0xBF), when one of the two UTF-16 Byte Order Marks (0xFF 0xFE or 0xFE 0xFF) is not found because that encoding may be used in the future.

Export API code sample

The Export API code sample illustrates how to export the extracted text fields on Document objects.

Export API Helper library

You can use the Export API in multiple threads to achieve high throughput. To simplify this process, a helper library is available. It also functions as an example illustrating how to run your own concurrent implementation. For more information, see relativitydev/export-api-helper on GitHub.