Object Manager API

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

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

Additionally, you can use the Object Manager service through the REST API. However, the endpoints on this service don't support cancellation tokens or progress indicators through REST. For more information, see Object Manager service.

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 in .NET on the Relativity 9.5 Developers site.

This page contains the following information:

• Fundamentals for managing Relativity objects
• Guidelines for using the Object Manager service
• Create an RDO and its specified fields
• Mass create RDOs
• Retrieve field values for a Document object or RDO
• Update field values on a Document object or RDO
• Update a long text field using an input stream in .NET
• 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 service

Fundamentals for managing Relativity objects

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

Methods on the Object Manager service

In the Services API, the Relativity.Services.Object namespace contains the IObjectManager interface. This interface contains the read, update, query, and export methods required to access the functionality provided by this service. The interface contains the following methods:

• CreateAsync() method - creates one or more RDOs with the values set for the existing fields. To create a single RDO, pass the a CreateRequest object to the method, which then returns a CreateResult object. To mass create RDOs, pass a MassCreateRequest object to the method, which then returns a MassCreateResult object. See Create an RDO and its specified fields or Mass create RDOs.
• DeleteAsync() method - deletes one or more Documents and their associated files, and RDOs. To delete a single Document object or RDO, pass a DeleteRequest object to the method, which then returns an DeleteResult object. To mass delete, pass a MassDeleteByCriteriaRequest or a MassDeleteByObjectIdentifiersRequest object to determine how the operation is performed, such as by querying for objects to delete or by deleting them based on Artifact IDs or GUIDs. A mass delete operation returns a MassDeleteResult object. See Delete a Document object or RDO or Mass delete Document objects or RDOs.
• GetDependencyListAsync() method - retrieves a list of dependent objects based on a request object containing references to objects selected for deletion. This method takes a DependencyListByObjectIdentifiersRequest object, and returns a list of Dependency objects. See Retrieve a list of object dependencies.
• InitializeExportAsync() method - sets up an export job and retrieves a runID used in the RetrieveNextResultsBlockFromExportAsync() and StreamLongTextAsync() methods. This method is called during the first step of the export workflow. It returns an ExportInitializationResults object, which provides information about data that is ready for export. See Set up an export job.
• QueryAsync() method - searches for Workspaces, Documents, RDOs, and system types. This overloaded method also supports functionality for requesting the cancellation of a query, and monitoring progress updates. It returns a QueryResultSet object. See Query for Relativity objects.
• QuerySlimAsync() method - searches for Workspaces, Documents, RDOs, and system types, but returns a smaller payload. It also supports functionality for requesting the cancellation of a query, and monitoring progress updates. It returns a QueryResultSlim object. See Query for Relativity objects.
• ReadAsync() method - retrieves the field values on a Document object or RDO. This overloaded method provides functionality for retrieving a specific subset of fields on these objects. It returns a ReadResult object. See Retrieve field values for a Document object or RDO.
• RetrieveNextResultsBlockFromExportAsync() method - retrieves successive blocks of document fields when it is called repeatedly. This method is called as the second step in the export workflow. See Retrieve objects.
• RetrieveResultsBlockFromExportAsync () method - retrieves a specific block of document fields when provided the block index ID. Call this method as the second step in the export workflow when you want to retrieve a specific block index rather than the next available block. See Retrieve objects.
• StreamLongTextAsync() method - retrieves the text that exceeds the size limit for the data returned by RetrieveNextResultsBlockFromExportAsync() method. This method is called as the third step of the export workflow. See Stream text.
• UpdateAsync() method - updates specified field values on one or more Document objects or RDOs. To update a single Document object or RDO, pass the an UpdateRequestobject to the method, which then returns an UpdateResult object. To mass update, pass a MassUpdateByCriteriaRequest, MassUpdateByObjectIdentifiersRequest, or MassUpdatePerObjectsRequest object to determine how the operation is performed, such as by querying for objects to update or by updating them based on Artifact IDs or GUIDs. A mass update operation returns a MassUpdateResult object. See Update field values on a Document object or RDO or Mass update Document objects or RDOs.
• UpdateLongTextFromStreamAsync() method - updates a single long text field that may exceed the length limits of an HTTP request. This method takes a workspace ID, a UpdateLongTextFromStreamRequest object, and a stream object. See Update a long text field using an input stream in .NET.

Classes used by the Object Manager service

The Object Manager service uses classes available in the following namespaces.

Exceptions thrown by the Object Manager service

The Object Manager service invokes all associated event handlers. If an error occurs and the event handler throws an exception, the service rethrows it as an EventHandlerFailedException. The InnerException property on this exception type contains the Exception instance for the error. The EventHandlerFailedException class is available in the Relativity.Services.Objects.Exceptions namespace. For more information, see Relativity API reference.

The Object Manager service also throws the following general exceptions:

• Service exceptions - thrown when an error occurs during a service call. For example, a ServiceException is thrown when you don't have access to the object type being queried. It contains the following message: "An error occurred while executing query."
• Validation exceptions - thrown when invalid data is passed to the service. For example, you may have passed a fixed-length text field that is longer than its specified length, attempted to save a choice to the wrong field type, or passed a string value to a whole number field. A ValidationException is also thrown if you don't set the Behavior property on a MultipleChoiceFieldUpdateValue or MultipleObjectFieldUpdateValue when attempting an update operation.
• Unauthorized exceptions - thrown when you don't have edit permissions on an object and then attempt to update it. Additionally, an unauthorized exception is thrown when attempting to read an object that you don't have permissions to view.

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 isn't 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:

• Read operations - set the LongTextBehavior property to 1 on the ReadOptions object passed to the ReadAsync() method. See Retrieve field values for a Document object or RDO.
• Query operations - set the LongTextBehavior property to 1 on the QueryRequest object passed to the QueryAsync() or QuerySlimAsync() methods. See Query for Relativity objects.

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.

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 service invokes the following event handlers:

• Pre Save and Post Save event handlers are executed on an update operation.
• Pre Load event handlers are executed on a read operation.

The service rethrows an event handler exception as EventHandlerFailedException. For more information, see Exceptions thrown by the Object Manager service.

Note: If event handlers access or manipulate the ApplicationUrl or Layout, these items must be assigned to properties on a CallingContext object. This object is referenced by a property on OperationOptions, UpdateOptions, and ReadOptions objects, which can be passed to various methods. The event handlers won't function properly if this property isn't set.

For more information about event handlers, see Develop object type 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.

public async Task<global::Relativity.Services.Objects.DataContracts.FieldValuePair> Read_Field(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, string fieldName)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var readRequest = new ReadRequest
            {
                Object =
                    new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = objectArtifactId },
                Fields = new List<global::Relativity.Services.Objects.DataContracts.FieldRef> { new global::Relativity.Services.Objects.DataContracts.FieldRef { Name = fieldName} }
            };

            global::Relativity.Services.Objects.DataContracts.ReadResult result = await objectManager.ReadAsync(workspaceId, readRequest);

            return result.Object[fieldName];
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object or Fields are not valid for reading.");
        }
    }
    return null;
}

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. See ArtifactType enumeration on Relativity API reference.
  • 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.

• 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 won't function properly when this property isn't set. If your event handlers don't 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. For information about running code samples, see Relativity SDK samples.

public async Task<CreateResult> Create(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectTypeID, IEnumerable<FieldRefValuePair> fieldValuePairs)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var createRequest = new CreateRequest();
            createRequest.ObjectType = new global::Relativity.Services.Objects.DataContracts.ObjectTypeRef { ArtifactTypeID = objectTypeID }; //this sets the object type of the RDO you are creating
            createRequest.ParentObject = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = this.SampleWorkspace_RootFolderID }; //the parent of the artifact only needs to be specified if the parent is not system
            createRequest.FieldValues = fieldValuePairs;

            var callingContext = new global::Relativity.Services.Objects.DataContracts.CallingContext //this sets up a calling context to provide any additional information eventhandlers may need
            {
                Layout = new LayoutRef { ArtifactID = SampleLayout_ID },
                PageMode = global::Relativity.Services.Objects.DataContracts.PageMode.Edit
            };

            var createOptions = new OperationOptions
            {
                CallingContext = callingContext
            };
            return await objectManager.CreateAsync(workspaceId, createRequest, createOptions);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object could not be created.");
        }
    }
    return null;
}

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’s already in the database, an exception won't 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 don't specify a parent object, Relativity defaults to the System object as the parent.

Similar to creating a single object, the overloaded CreateAsync() method supports progress reporting, and cancellation requests for mass update operations. See the following code sample.

public async Task<global::Relativity.Services.Objects.DataContracts.MassCreateResult> MassCreate(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectTypeID, IEnumerable<FieldRef> fields, IReadOnlyList<IReadOnlyList<object>> fieldValues)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var massCreateRequest = new MassCreateRequest();
            // Sets the object type of the RDO that you you want to create.
            massCreateRequest.ObjectType = new ObjectTypeRef { ArtifactTypeID = objectTypeID }; 
            // Sets the fields to populate.
            massCreateRequest.Fields = fields; 
            // Sets the values in the order that the fields provided.
            massCreateRequest.ValueLists = fieldValues; 

            return await objectManager.CreateAsync(workspaceId, massCreateRequest);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object could not be created.");
        }
    }
    return null;
}

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. For information, see the ReadOptions class in the Relativity.Services.Objects.DataContracts namespace in the Services API.

  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 won't function properly when this property isn't set. If your event handlers don't 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. For information about running code samples, see Relativity SDK samples.

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 won't function properly when this property isn't set. If your event handlers don't 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 similar to 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.

For information about viewing other field type code samples, see Relativity SDK samples.

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 don’t 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 doesn't 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.

public async Task<UpdateResult> UpdateLongTextFromStream(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, string valueToSet)
{
    Guid kGuidForExtractedTextField = new Guid("58D35076-1B1D-43B4-BFF4-D6C089DE51B2");

    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        var relativityObject = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef
        {
            ArtifactID = objectArtifactId
        };

        var extractedTextFieldRef = new FieldRef
        {
            Guid = kGuidForExtractedTextField
        };

        var updateRequest = new UpdateLongTextFromStreamRequest
        {
            Object = relativityObject,
            Field = extractedTextFieldRef
        };

        try
        {
            using (var memoryStream = new System.IO.MemoryStream())
            {
                using (var streamWriter = new System.IO.StreamWriter(memoryStream, new System.Text.UnicodeEncoding()))
                {
                    streamWriter.Write(valueToSet);
                    streamWriter.Flush();

                    memoryStream.Seek(0, System.IO.SeekOrigin.Begin);

                    using (var keplerStream = new global::Relativity.Kepler.Transport.KeplerStream(memoryStream))
                    {
                        await objectManager.UpdateLongTextFromStreamAsync(workspaceId, updateRequest, keplerStream).ConfigureAwait(false);
                    }
                }
            }
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object is not valid for updating.");
        }
    }
    return null;
}

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. See Mass update operation using query conditions.
  • 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 a large number of objects. See Mass update operation using query conditions.
• Note that the identifier field can’t 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 Search Relativity.

public async Task<MassUpdateResult> MassUpdate(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, ObjectIdentificationCriteria criteria, IEnumerable<FieldRefValuePair> fieldRefValuePairs, FieldUpdateBehavior behavior)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var updateRequest = new MassUpdateByCriteriaRequest();
            // Run a query for all the items that you want to update. 
            updateRequest.ObjectIdentificationCriteria = criteria; 
            // Indicate the fields and the values to be set for all the objects provided.
            updateRequest.FieldValues = fieldRefValuePairs; 
            var updateOptions = new MassUpdateOptions();
            // By default, the behavior is replace.
            updateOptions.UpdateBehavior = behavior; 

            return await objectManager.UpdateAsync(workspaceId, updateRequest, updateOptions);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object is not valid for updating.");
        }
    }
    return null;
}

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.

public async Task<MassUpdateResult> MassUpdate(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, IReadOnlyList<RelativityObjectRef> relativityObjectRefs, IEnumerable<FieldRefValuePair> fieldRefValuePairs, FieldUpdateBehavior behavior)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var updateRequest = new MassUpdateByObjectIdentifiersRequest();
            // Represents RelativityObjects to update.
            updateRequest.Objects = relativityObjectRefs; 
            // Indicates the fields and the values to be set for all the objects provided.
            updateRequest.FieldValues = fieldRefValuePairs;  
            var updateOptions = new MassUpdateOptions();
            // By default, the behavior is replace.
            updateOptions.UpdateBehavior = behavior; 

            return await objectManager.UpdateAsync(workspaceId, updateRequest, updateOptions);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object is not valid for updating.");
        }
    }
    return null;
}

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.

public async Task<MassUpdateResult> MassUpdate(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, IReadOnlyList<FieldRef> fields, IReadOnlyList<ObjectRefValuesPair> objectRefValuesPairs, FieldUpdateBehavior behavior)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var updateRequest = new MassUpdatePerObjectsRequest();
            // The fields updated on each of the objects in the list.
            updateRequest.Fields = fields; 
            // The RelativityObjects and the values to be set for all the fields provided.
            updateRequest.ObjectValues = objectRefValuesPairs; 

            var updateOptions = new MassUpdateOptions(); 
           // The default behavior is replace.
            updateOptions.UpdateBehavior = behavior; 

            return await objectManager.UpdateAsync(workspaceId, updateRequest, updateOptions);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object is not valid for updating.");
        }
    }
    return null;
}

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 doesn't have view permissions or if any of the objects don't exist.

The following code sample illustrates how to instantiate a DependencyListByObjectIdentifiersRequest object, and set its Object property to a list of RelativityObjectRef instances. It then calls the GetDependencyListAsync() method by passing it the Artifact ID of the workspace, and the request object.

{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var dependencyRequest = new DependencyListByObjectIdentifiersRequest();
            dependencyRequest.Objects = new List<RelativityObjectRef>
            {
                new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = objectArtifactId }
            };
            return await objectManager.GetDependencyListAsync(workspaceId, dependencyRequest);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "Dependencies for the Relativity Object could not be retrieved.");
        }
        return null;
    }
}

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.

public async Task<DeleteResult> Delete(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var deleteRequest = new DeleteRequest();
            deleteRequest.Object =
                new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef {ArtifactID = objectArtifactId};
            return await objectManager.DeleteAsync(workspaceId, deleteRequest);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object could not be deleted.");
        }
        return null;
    }
}

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.

Similar to deleting a single object, 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 Search Relativity.

public async Task<global::Relativity.Services.Objects.DataContracts.MassDeleteResult> MassDelete(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, ObjectIdentificationCriteria criteria)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var deleteRequest = new MassDeleteByCriteriaRequest();
            // Run a query for all the items that you want to delete.
            deleteRequest.ObjectIdentificationCriteria = criteria; 

            return await objectManager.DeleteAsync(workspaceId, deleteRequest);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object could not be deleted.");
        }
        return null;
    }
}

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.

public async Task<global::Relativity.Services.Objects.DataContracts.MassDeleteResult> MassDelete(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, IReadOnlyList<RelativityObjectRef> relativityObjectRefs)
{
    using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
    {
        try
        {
            var deleteRequest = new MassDeleteByObjectIdentifiersRequest();
            // Represents a list of RelativityObjects to be deleted.
            deleteRequest.Objects = relativityObjectRefs; 

            return await objectManager.DeleteAsync(workspaceId, deleteRequest);
        }
        catch (ValidationException exception)
        {
            _logger.LogError(exception, "The Relativity Object could not be deleted.");
        }
        return null;
    }
}

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.

You call the QueryAsync() or QuerySlimAsync() method the by passing the following parameters:

• The ArtifactID of the workspace that you want to query.
• A QueryRequest object represents the settings for the search that you want to run. This following list highlights some of key properties on this QueryRequest class:
  • QueryHint - used 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.
  • Condition - determines the search criteria. For more information, see Search Relativity.
  • 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 list of Sort objects. This list determines the sort order of the results. The Sort class has a Direction property, which can be set to ascending or descending. It also has an Order property, which specifies precedence when multiple sort orders are defined. For more information, see Sort class in the Relativity API reference.
  • 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.

    Note: If you set the Fields property of a query to an asterisks (*), the query operation returns all fields except the Extracted Text field. To retrieve extracted text, you must provide a separate query specifically for this field.

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

If you use one of the overloaded methods, you can also pass the following arguments:

• IProgress<ProgressReport> object - used to define a provider for progress updates. This object has the type System.IProgress provided by the .NET framework.
• CancellationToken - used to request the cancellation of a query executed by the Object Manager service. This object has the type System.Threading.CancellationTokenSource provided by the .NET framework.

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. For information about running code samples, see Relativity SDK samples.

Export API

The Object Manager API supports exporting document fields, including complete long text fields such as extracted text, via a new 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 very high throughput.

See the following subsections for more information:

• Export API workflow
• Set up an export job
• Retrieve objects
• Stream text
• Export API code sample
• Export API Helper library

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 doesn't truncated 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.

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 very 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 a number of documents, up to and including batchSize. The fields for each document appear in the order defined in the QueryRequest object during initialization.

// Get blocks of documents until none are left.

RelativityObjectSlim[] currentBlock = null;
bool done = false;

while (!done)
{
    try
    {
        currentBlock = objectManager.RetrieveNextResultsBlockFromExportAsync(workspaceId, runId, blockSize).Result;
    }
    catch (Exception exception)
    {
        Console.WriteLine(exception.Message);
        return;
    }

    if (currentBlock == null || !currentBlock.Any())
    {
        done = true;
        break;
    }

    Console.WriteLine("Got block of " + currentBlock.Count() + " documents");
    Console.WriteLine(); 

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 a number of 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.

ExportInitializationResults exportInitResults = await objectManager.InitializeExportAsync(workspaceArtifactID, queryRequest, 0).ConfigureAwait(false);

Guid exportID = exportInitResults.RunID;
int totalNumberOfRecords = exportInitResults.RecordCount;

int exportIndexID = 0;
int resultsBlockSize = totalNumberOfRecords;

RelativityObjectSlim[] currentBlock = await objectManager.RetrieveResultsBlockFromExportAsync(workspaceArtifactID, exportID, resultsBlockSize, exportIndexID).ConfigureAwait(false);
exportIndexID += currentBlock.Length;
resultsBlockSize -= currentBlock.Length;

return currentBlock;

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.

// Check to determine if the long text field needs to be streamed.

if (longTextIds.Contains(i))
{
    if (ros.Values[i].Equals(_SHIBBOLETH))
    {
        Console.WriteLine("Text is too long, it must be streamed");
        Console.WriteLine();

        RelativityObjectRef documentObjectRef = new RelativityObjectRef { ArtifactID = ros.ArtifactID };

        using (IKeplerStream keplerStream = objectManager.StreamLongTextAsync(workspaceId, documentObjectRef, queryRequest.Fields.ElementAt(i)).Result)
        {
            using (Stream realStream = keplerStream.GetStreamAsync().Result)
            {
                StreamReader reader = new StreamReader(realStream, Encoding.Unicode);
                String line;

                while ((line = reader.ReadLine()) != null)
                {
                    Console.Write(line);
                }
                Console.WriteLine();
            }
        }
    }
}

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) isn't 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.