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:
Sample use cases for the Object Manager service include:
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 (REST).
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
This page contains the following information:
See this related page:
Review the following information to learn about the methods, classes, and exceptions that used by 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:
The Object Manager service uses classes available in the following namespaces.
The following list contains some of the key classes available in the Relativity.Services.Objects.DataContracts namespace:
Note: You must set the CallingContext property on one of these objects if you have event handlers that depend on a layout. The event handlers won't function properly if 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.
In addition, you can use this class to access the following specialized fields when performing a query on a Document object or RDO:
The following table contains a list of fields and their value types. All of the primitive types are optional, so null is a valid value for them.
FieldType | Expected value type |
---|---|
Fixed-Length Text | string |
Long Text | string |
Date | DateTime |
Whole Number | int? |
Decimal | decimal? |
Currency | decimal? |
Yes/No | bool? |
Single Choice | ChoiceRef |
Multiple Choice | IEnumerable<ChoiceRef> |
User | User (The ArtifactID must be set on this object.) |
File | FileRef |
Single Object | RelativityObjectRef |
Multiple Object | IEnumerable<RelativityObjectRef> |
The following table contains a list of fields and their value types. All of the primitive types are optional, so null is a valid value for them.
FieldType | Expected value type |
---|---|
Fixed-Length Text | string |
Long Text | string |
Date | DateTime |
Whole Number | int? |
Decimal | decimal? |
Currency | decimal? |
Yes/No | bool? |
Single Choice | Choice |
Multiple Choice | List<Choice> |
User | UserRef |
File | FileRef |
Single Object | RelativityObjectValue |
Multiple Object | List<RelativityObjectValue> |
Note: You can reference RelativityObject objects and FieldValuePair objects by GUID instead of Artifact ID during update and read operations.
The Relativity.Services.Objects.Extensions namespace includes classes that contain methods used for working with hydrated objects. For example, you can use the ToRef() method on one of these classes to convert a fully hydrated object to a ref class. This ref class can then be used when instantiating a request object.
Each of the following classes have a ToRef() method:
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 Class library reference.
The Object Manager service also throws the following general exceptions:
Use the following guidelines when working with the Object Manager service:
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:
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.
The following information is provided about the ReadOptions and QueryRequest classes to further explain the properties for long text fields.
The ReadOptions class includes the following properties for long text fields:
The LongTextBehavior enumeration includes the following values:
For information, see the LongTextBehavior enumeration in the Relativity.Services.Objects.DataContracts namespace in the Services API.
When this property isn't set, the he value in the MaximumNumberOfCharactersSupportedByLongText instance setting determines the maximum length. The default value for the instance setting is 100,000 characters. For more information, see
The Object Manager service currently doesn’t support retrieving all the text in a long text field for a read operation when it exceeds the maximum length except through the use of tokens or streaming. For information on the streaming API to retrieve all the data stored in a long text field, see Stream text.
The QueryRequest class includes the following properties for long text fields:
The LongTextBehavior enumeration includes the following values:
For information, see the LongTextBehavior enumeration in the Relativity.Services.Objects.DataContracts namespace in the Services API.
If you set the MaxCharactersForLongTextValues property on the QueryRequest object, it determines the maximum number of characters by overriding limit set by the MaximumNumberOfCharactersSupportedByLongText instance setting up to up to the maximum of 1000. When a long text field exceeds maximum number of characters allowed, the default behavior truncates the field.
The Object Manager service currently doesn’t support retrieving all the text in a long text field for a query operation when it exceeds the maximum length except through the use of tokens or streaming. For information on the streaming API to retrieve all the data stored in a long text field, see Stream text.
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.
//Creates and initializes a ServiceFactory instance. public void InitializeServiceFactory() { String restServerAddress = "http://localhost/relativity.rest/api"; Uri keplerUri = new Uri(restServerAddress); Relativity.Services.ServiceProxy.ServiceFactorySettings settings = new Relativity.Services.ServiceProxy.ServiceFactorySettings( keplerUri, new Relativity.Services.ServiceProxy.UsernamePasswordCredentials("ExampleUsername .com", "ExamplePassword1!")); _serviceFactory = new Relativity.Services.ServiceProxy.ServiceFactory(settings); } //Creates an IObjectManager instance through the ServiceFactory instance. public async Task PerformWorkWithObjectManager() { using (IObjectManager objectManager = _serviceFactory.CreateProxy<IObjectManager>()) { // Do work with the objectManager instance. } } //Creates an IObjectManager instance through the Relativity API Helpers. public async Task PerformWorkWithConnectionHelperObjectManager() { var serviceManager = ConnectionHelper.Helper().GetServicesManager(); using (IObjectManager objectManager = serviceManager.CreateProxy<IObjectManager>(Relativity.API.ExecutionIdentity.System)) { // Do work with the objectManager instance. } }
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.
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.
The Object Manager service invokes the following event handlers:
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.
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; }
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:
Note: If you don't specify a parent object, Relativity defaults to the System object as the parent.
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; }
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; }
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 following list highlights key properties on the ReadOptions class, and suggested setting for them:
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.
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.
public async Task<global::Relativity.Services.Objects.DataContracts.ReadResult> Read_Partial(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, IEnumerable<global::Relativity.Services.Objects.DataContracts.FieldRef> fieldRefs) { 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 = fieldRefs }; return await objectManager.ReadAsync(workspaceId, readRequest); } catch (ValidationException exception) { _logger.LogError(exception, "The Relativity Object or Fields are not valid for reading."); } } return null; }
Use the UpdateAsync() method to modify a field on a Document object or RDO. You call this method by passing the following parameters:
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.
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:
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.
public async Task<UpdateResult> UpdateSingle_SingleObject(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, int fieldArtifactId, int singleObjectArtifactId) { using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User)) { var relativityObject = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = objectArtifactId }; var fieldValuePair = new FieldRefValuePair { Field = new global::Relativity.Services.Objects.DataContracts.FieldRef() { ArtifactID = fieldArtifactId }, Value = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = singleObjectArtifactId } }; var updateRequest = new UpdateRequest { Object = relativityObject, FieldValues = new List<FieldRefValuePair> { fieldValuePair } }; try { return await objectManager.UpdateAsync(workspaceId, updateRequest); } catch (ValidationException exception) { _logger.LogError(exception, "The Relativity Object is not valid for updating."); } } return null; }
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:
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.
The following code sample illustrates how to call the UpdateSync()method without passing an UpdateOptions instance to it. Since this codes doesn't specify the update behavior, the field values are replaced by default.
public async Task<UpdateResult> UpdateSingle_MultipleObject(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, int fieldArtifactId, IEnumerable<global::Relativity.Services.Objects.DataContracts.RelativityObjectRef> objects) { using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User)) { var relativityObject = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = objectArtifactId }; var fieldValuePair = new FieldRefValuePair { Field = new global::Relativity.Services.Objects.DataContracts.FieldRef() { ArtifactID = fieldArtifactId }, Value = objects }; var updateRequest = new UpdateRequest { Object = relativityObject, FieldValues = new List<FieldRefValuePair> { fieldValuePair } }; try { return await objectManager.UpdateAsync(workspaceId, updateRequest); } catch (ValidationException exception) { _logger.LogError(exception, "The Relativity Object is not valid for updating."); } } return null; }
The following code sample illustrates how to specify the update behavior by passing an UpdateOptions instance to the UpdateAsync() method. In this sample, the UpdateBehavior property is set to Merge. You also have the option to set this property to Replace.
public async Task<UpdateResult> UpdateSingle_MultipleObject_WithOptions(Client.SamplesLibrary.Helper.IHelper helper, int workspaceId, int objectArtifactId, int fieldArtifactId, IEnumerable<global::Relativity.Services.Objects.DataContracts.RelativityObjectRef> objects) { using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.User)) { var relativityObject = new global::Relativity.Services.Objects.DataContracts.RelativityObjectRef { ArtifactID = objectArtifactId }; var fieldValuePair = new FieldRefValuePair { Field = new global::Relativity.Services.Objects.DataContracts.FieldRef() { ArtifactID = fieldArtifactId }, Value = objects }; var updateRequest = new UpdateRequest { Object = relativityObject, FieldValues = new List<FieldRefValuePair> { fieldValuePair } }; var updateOptions = new UpdateOptions { UpdateBehavior = global::Relativity.Services.Objects.DataContracts.FieldUpdateBehavior.Merge }; try { return await objectManager.UpdateAsync(workspaceId, updateRequest, updateOptions); } catch (ValidationException exception) { _logger.LogError(exception, "The Relativity Object is not valid for updating."); } } return null; }
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; }
Use the overloaded UpdateAsync() method to mass update RDOs. You can mass update Document objects or RDOs in the following ways:
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:
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; }
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; }
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; }
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:
Use these guidelines for calling the GetDependencyListAsync() method:
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; } }
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:
If you use the overloaded DeleteAsync() method, you can also pass the following arguments:
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; } }
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:
Similar to deleting a single object, the overloaded DeleteAsync() method supports progress reporting, and cancellation requests for mass delete operations.
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; } }
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; } }
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:
Note: Before implementing the query operation on a long text field, review the following best practices in Use tokens with long text fields.
Fields = new List<FieldRef>() { new FieldRef{ Name = "*"} }
If you use one of the overloaded methods, you can also pass the following arguments:
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.
public async Task<global::Relativity.Services.Objects.DataContracts.QueryResult> 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. var sort = new global::Relativity.Services.Objects.DataContracts.Sort() { Direction = global::Relativity.Services.Objects.DataContracts.SortEnum.Ascending, FieldIdentifier = new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = this.SampleField_FixedLengthText_ID } }; var queryRequest = new QueryRequest() { ObjectType = new global::Relativity.Services.Objects.DataContracts.ObjectTypeRef { ArtifactTypeID = documentArtifactTypeId }, 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<global::Relativity.Services.Objects.DataContracts.FieldRef>() //array of fields to return. ArtifactId will always be returned. { new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = SampleField_FixedLengthText_ID }, new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = SampleChoice_ID }, new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = 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.Objects.DataContracts.Sort> { sort }, //an array of Fields with sorting order QueryHint = "waitfor:5" }; using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.System)) { return await objectManager.QueryAsync(workspaceId, queryRequest, indexOfFirstDocumentInResult, lengthOfResults); } } catch (Exception ex) { _logger.LogError(ex, "Error: ObjectManager.QueryAsync was not successful"); } return null; }
public async Task<global::Relativity.Services.Objects.DataContracts.QueryResultSlim> QuerySlimAsync(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. var sort = new global::Relativity.Services.Objects.DataContracts.Sort() { Direction = global::Relativity.Services.Objects.DataContracts.SortEnum.Ascending, FieldIdentifier = new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = this.SampleField_FixedLengthText_ID } }; var queryRequest = new QueryRequest() { ObjectType = new global::Relativity.Services.Objects.DataContracts.ObjectTypeRef { ArtifactTypeID = documentArtifactTypeId }, 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<global::Relativity.Services.Objects.DataContracts.FieldRef>() //array of fields to return. ArtifactId will always be returned. { new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = SampleField_FixedLengthText_ID }, new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = SampleChoice_ID }, new global::Relativity.Services.Objects.DataContracts.FieldRef { ArtifactID = 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.Objects.DataContracts.Sort> { sort }, //an array of Fields with sorting order QueryHint = "waitfor:5" }; using (IObjectManager objectManager = helper.GetServicesManager().CreateProxy<IObjectManager>(ExecutionIdentity.System)) { return await objectManager.QuerySlimAsync(workspaceId, queryRequest, indexOfFirstDocumentInResult, lengthOfResults); } } catch (Exception ex) { _logger.LogError(ex, "Error: ObjectManager.QueryAsync was not successful"); } return null; }
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:
See the following subsections for more information:
The export process is multiple step workflow that uses several methods on the IObjectManager interface:
For an example of this workflow, see Export API code sample.
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:
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
The semantics of MaxCharactersForLongTextValues field is slightly different than other Object Manager API uses:
This method returns an instance of ExportInitializationResults class, which contains the following:
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.
For the complete code, see Export API code sample.
ExportInitializationResults exportInitializationResults = objectManager.InitializeExportAsync(workspaceId, queryRequest, 0).Result;
Call one of the following methods to retrieve document fields from the export job:
Review the following considerations for these methods:
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:
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();
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:
Note: The actual number of results returned may be less than the maximum number requested.
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;
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()
You call the StreamLongTextAsync() method by passing the following parameters:
// 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.
The Export API code sample illustrates how to export the extracted text fields on Document objects.
Note: When running this code sample, make sure to include the required using statements. For example, the call to call Array.Any() requires a using System.Linq statement.
using Relativity.Kepler.Transport; using Relativity.Services.DataContracts.DTOs.Results; using Relativity.Services.Field; using Relativity.Services.Objects; using Relativity.Services.Objects.DataContracts; using Relativity.Services.ServiceProxy; using System; using System.Collections.Generic; using System.IO; using System.Linq; using System.Net; using System.Text; using FieldRef = Relativity.Services.Objects.DataContracts.FieldRef; namespace Relativity.Sample { class Program { // Provide an indicator that the text isn't present and needs to be streamed. private const string _SHIBBOLETH = "#KCURA99DF2F0FEB88420388879F1282A55760#"; // Set the URL for the Relativity instance. private static Uri relativityUrl = new Uri("https://relativity.mycompany.com"); // Set the ID of the Workspace. private static int workspaceId = 1234567; // Provide an Object Manager query. private static QueryRequest queryRequest = new QueryRequest() { Fields = new FieldRef[] { new FieldRef {Name = "Control Number"}, new FieldRef {Name = "Extracted Text"} }, MaxCharactersForLongTextValues = 1024 * 10, ObjectType = new ObjectTypeRef { ArtifactTypeID = 10 } // Document }; // Count of the number of documents to return per call to RetrieveNextResultsBlock() method. private static int blockSize = 1000; // Provide credentials. Production environments should use a secure credential type. private static Credentials credentials = new UsernamePasswordCredentials("me@mycompany.com", "Password goes here"); static void Main(string[] args) { try { // Get an instance of the Object Manager. IObjectManager objectManager; try { objectManager = GetKeplerServiceFactory(relativityUrl, credentials) .CreateProxy<Relativity.Services.Objects.IObjectManager>(); } catch (Exception exception) { Console.WriteLine(exception.Message); return; } // Initialize Export API using the properties set above. Guid runId; long recordCount; List<FieldMetadata> fieldData; int[] longTextIds; try { ExportInitializationResults exportInitializationResults = objectManager.InitializeExportAsync(workspaceId, queryRequest, 0).Result; // Save infomation about this "run". runId = exportInitializationResults.RunID; recordCount = exportInitializationResults.RecordCount; fieldData = exportInitializationResults.FieldData; // Find indexes of all long text fields. List<int> longTextIdList = new List<int>(); for (int i = 0; i < exportInitializationResults.FieldData.Count; i++) { if (exportInitializationResults.FieldData[i].FieldType == Relativity.Services.FieldType.LongText) { longTextIdList.Add(i); } } longTextIds = longTextIdList.ToArray(); } catch (Exception exception) { Console.WriteLine(exception.Message); return; } Console.WriteLine("RunId " + runId + " will return " + recordCount + " documents"); Console.WriteLine(); // 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(); // Print out the fields for each document. foreach (RelativityObjectSlim ros in currentBlock) { for (int i = 0; i < fieldData.Count; i++) { Console.WriteLine(fieldData[i].Name + ": " + ros.Values[i]); // 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(); } } } } } Console.WriteLine(); } Console.WriteLine("Block complete"); Console.WriteLine(); } Console.WriteLine("All blocks complete"); Console.WriteLine(); } catch (Exception exception) { Console.WriteLine(exception.Message); return; } } private static ServiceFactory GetKeplerServiceFactory(Uri relativityUrl, Credentials credentials) { ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12; ServicePointManager.DefaultConnectionLimit = 128; Uri restUri = new Uri(relativityUrl, "Relativity.REST/api"); Uri servicesUri = new Uri(relativityUrl, "Relativity.REST/apiRelativity.Services"); ServiceFactorySettings settings = new ServiceFactorySettings(servicesUri, restUri, credentials); ServiceFactory factory = new ServiceFactory(settings); return factory; } } }
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.
Community Updates |
|||
Aero Developer FAQ | Evolving the Platform | Most recent release notes | |
Learn more | Learn more | Learn more |
Additional Resources |
|||
![]() |
![]() |
||
Access Third-Party Tools with GitHub | Create .NET Apps Faster with NuGet | ||
Visit github | visit nuget |