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.

Deprecated content for Object Manager API in .NET

The Object Manager service 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 these object types, including currency, date, user, and others. 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.

Additionally, you can use the Object Manager service through the REST API. However, the QueryAsync endpoint on this service doesn't support cancellation tokens or progress indicators through REST. For more information, see Deprecated content for Object Manager API with REST.

This page contains the following information:

Fundamentals for managing Relativity objects

Review the following information to learn about the methods, classes, and exceptions that support 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, and query methods required to access the functionality provided by this service. The interface contains the following methods:

  • CreateSingleAsync() method - creates an RDO with the values set for the existing fields on it. It returns a ObjectCreateResult object. See Create an RDO and its specified fields.
  • ReadSingleAsync() 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 an ObjectReadResult object. See Retrieve field values for a Document object or RDO.
  • UpdateAsync() method - updates specified field values on a Document object or RDO. It returns an ObjectUpdateResult object. See Update field values on a Document object or RDO.
  • DeleteSingleAsync() method - deletes Documents and their associated files, and RDOs. This overloaded method also supports functionality for requesting the cancellation of a delete request, and monitoring progress updates. It returns an ObjectDeleteResult object. See Delete a Document object or RDO.
  • 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 an ObjectQueryResultSet object. See Query for Relativity objects.

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:

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.

Propagation

The Object Manager service updates on fields on a Document object, which are enabled for propagation. It 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, which is passed as a parameter to the methods for the create, read, and update operations.

For more information about event handlers, see Develop object type event handlers.

Create an RDO and its specified fields

Use the CreateSingleAsync() 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 RelativityObject object with a list of fields that you want set on the new RDO. For more information, see Relativity.Services.Objects.Models namespace.
  • A 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. See Relativity.Services.Objects.Models.WebContent.

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<ObjectCreateResult> Create(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectTypeID, int? parentArtifactID)
  {
     using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
     {
        try
        {
           int attorneyCommentFieldArtifactId = 1013456;
           int mutliChoiceFieldArtifactId = 1017890;
           int responsiveChoiceArtifactId = 1035680;
           int furtherReviewChoiceArtifactId = 1035689;

           List<ChoiceRef> choicesToSelect = new List<ChoiceRef>() {new ChoiceRef(responsiveChoiceArtifactId), new ChoiceRef(furtherReviewChoiceArtifactId)};
           RelativityObject relativityObject = new RelativityObject();
           relativityObject.ObjectTypeRef = new ObjectTypeRef(objectTypeID); //this sets the object type of the RDO you are creating
           relativityObject.ParentArtifactID = parentArtifactID; //the parent of the artifact only needs to be specified if the parent is not system

           FieldValuePair fvp1 = new FieldValuePair();
           fvp1.Field = new FieldRef(attorneyCommentFieldArtifactId);
           fvp1.Value = "This requires further attention.";

           FieldValuePair fvp2 = new FieldValuePair();
           fvp2.Field = new FieldRef(mutliChoiceFieldArtifactId);
           fvp2.Value = new MultipleChoiceFieldUpdateValue()
           {
              Behavior = FieldUpdateBehavior.Replace,
              Choices = choicesToSelect
           };
           List<FieldValuePair> fieldValuePairs = new List<FieldValuePair>() {fvp1, fvp2};
           relativityObject.FieldValuePairs = fieldValuePairs;

           //Set up a calling context to provide any additional information that the event handlers may need.
           CallingContext callingContext = new CallingContext(); 
           callingContext.Layout = new LayoutMetadata() { ArtifactID = SampleLayout_ID };
           callingContext.PageMode = PageMode.Edit;

           return await objectManager.CreateSingleAsync(workspaceId, relativityObject, callingContext);
        }
        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 ReadSingleAsync() 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.

With the overloaded ReadSingleAsync() method, you can specify the Artifact ID or the GUID of the object that you want to read. You can specify a subset of fields on the Document object or RDO, which you want to read.

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.
  • The Artifact ID or the GUID of the object that you want to read.
  • A list of FieldRef objects specifying a subset of fields on the object that you want to read. You can reference fields by their ArtifactID or Name properties.
  • A 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. See Relativity.Services.Objects.Models.WebContent.

    Note: You can set this parameter to null if your event handlers don't require context information. Your event handlers must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API. See Relativity.Services.Objects.Models.WebContent.

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.
  • The Artifact ID of the Document object or RDO that you want to update.
  • A RelativityObject object with a list of fields that you want to update. You can reference fields by their ArtifactID or Name properties. For more information, see Relativity.Services.Objects.Models namespace.
  • A 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 can set this parameter to null if your event handlers don't require context information. Your event handlers must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API. See Relativity.Services.Objects.Models.WebContent.

The following code samples illustrate how to update field values on a single or multiple 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 RelativityObject instance, set the FieldValuePairs property to a list of FieldValuePair objects.
  • Call the UpdateAsync() method by passing the required parameters.

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

Delete a Document object or RDO

Use the DeleteSingleAsync() 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 RelativityObject instance containing the Artifact ID or GUID of the Document object or RDO that you want to delete.
  • A CallingContext instance providing 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 can set this parameter to null if your event handlers don't require context information. Your event handlers must then implement the ICanExecuteWithLimitedContext interface available in the Event Handlers API. See Relativity.Services.Objects.Models.WebContent.

If you use the overloaded DeleteSingleAsync() 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<ProgressReport> object - used to define a provider for progress updates. This object has the type System.IProgress provided by the .NET framework.
public async Task<ObjectDeleteResult> Delete(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId)
{
   using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User))
   {
      try
      {
         RelativityObjectRef relativityObject = new RelativityObjectRef() {ArtifactID = objectArtifactId};
         CallingContext callingContext = null;
         return await objectManager.DeleteSingleAsync(workspaceId, relativityObject, callingContext);
      }
      catch (ValidationException exception)
      {
         _logger.LogError(exception, "The Relativity Object could not be deleted.");
      }
      return null;      
   }
}

Query for Relativity objects

Use the QueryAsnyc() method to search for a Workspace, Document, RDO or system type, such as Application, Batch, Object Type, and others. For more information, see System types supported by the Query() method.

You call the QueryAsnyc() by passing the following parameters:

  • The ArtifactID of the workspace that you want to query.
  • The identifier for the artifact type that you want to query on. You must set either DescriptorArtifactTypeID or the Guids properties on the ObjectTypeRef object that you pass to the method.
  • A Query object identifying the data to return and its format. The Query class includes the following properties and others that you can set. For more information, see Relativity API reference.
    • Condition property - determines the search criteria. For more information, see Search Relativity.
    • Fields property - a collection of FieldRef objects. This collection determines the fields included on the returned RelativityObject object. You can identify FieldRef objects by using their ArtifactID, Guids, or Name properties.
    • Sorts property - 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 Relativity.Services in the Relativity API reference.
  • An integer indicating the index of the first artifact in QueryResultSet object returned from your search. This value is used for paging.
  • An integer indicating the number of items that you want returned in the ObjectQueryResultSet object. The returned items begin at the index provided in the start property.

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 sample illustrates how to run a query for Document objects using the Object Manager service. It illustrates how to define the query, declare a new Query instance, call the QueryAsync() method, and return a ObjectQueryResultSet object containing the search results. For information about running code samples, see Relativity SDK samples.

public async Task<ObjectQueryResultSet> QueryAsync(IHelper helper)
{
    try
    {
        //Prepare parameters for query call
        int workspaceId = this.SampleWorkspace_ID;
        const int documentArtifactTypeId = 10; //target artifact type to query (Document is always 10)
        const int indexOfFirstDocumentInResult = 1; //1-based index of first document in query results to retrieve
        const int lengthOfResults = 100; //max number of results to return in this query call.
        global::Relativity.Services.Sort sort = new global::Relativity.Services.Sort
        {
            Direction = global::Relativity.Services.SortEnum.Ascending,
            FieldIdentifier = new FieldRef(this.SampleField_FixedLengthText_ID)
        };
        global::Relativity.Services.Objects.Models.Query query = new global::Relativity.Services.Objects.Models.Query()
        {
            Condition = "('Email From' IN ['Test0@Test.com','Test1@Test.com'])", //query condition syntax is used to build query condtion.  See Relativity's developer documentation for more details
            Fields = new List<FieldRef>() //array of fields to return.  ArtifactId will always be returned.
            {
                new FieldRef(SampleField_FixedLengthText_ID),
                new FieldRef(SampleChoice_ID),
                new FieldRef(SampleField_MultiObject_ID)
            }, 
            IncludeIdWindow = false,
            RelationalField = null, //name of relational field to expand query results to related objects
            SampleParameters = null,
            SearchProviderCondition = null, //see documentation on building search providers
            Sorts = new List<global::Relativity.Services.Sort>() {sort}, //an array of Fields with sorting order 
            TruncateTextFields = true,
            QueryHint = "waitfor:5"
        };

        using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.System))
        {
            ObjectQueryResultSet queryResults = await objectManager.QueryAsync(workspaceId, new ObjectTypeRef(documentArtifactTypeId), query, indexOfFirstDocumentInResult, lengthOfResults);

            if (queryResults.Success)
            {
                return queryResults;
            }
            _logger.LogDebug("Error: ObjectManager.QueryAsync was not successful - ");
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Error: ObjectManager.QueryAsync was not successful");
    }

    return null;
}