Get started with the Processing API (v0)
The Processing API supports the automation of your processing workflows. You can programmatically use this API to create and update custodians, data sources, processing sets, and profiles required for processing. It provides an alternative to manually creating them through the Relativity UI. You also can use the Processing API to run inventory, discovery, and publishing jobs.
Use the information on this page to learn about Processing API fundamentals. It includes prerequisites for developing with this API, and code samples for common operations. Additional resources to help you get started with the Processing API include:
- Field Mapping Manager and Field Mapping Manager (REST) - provides information about the Field Mapping service available through the Relativity Services API and REST API respectively.
- Processing on the Relativity Documentation site - provides general information about how Relativity supports processing.
See these related pages:
Processing API fundamentals
The Processing application provides system admins with the ability to ingest raw data directly into a workspace for review. When you set up a processing workflow, you create a processing profile. This profile specifies settings that control how the processing engine ingests the data. You create or reference the following items:
- A custodian who is a user associated with the data included in a processing job.
- A data source that contains the path used to specify the location of the files that you want to discover.
You also create a processing set that links a processing profile to one or more data sources. When you run a discovery job, the processing engine discovers files in the data source based on the values specified in the processing set. For more information, see Processing on the Relativity Documentation site
The Processing API provides interfaces and objects that you can use to automate many of the tasks in a processing workflow. It includes the following interfaces that you can use to access services, which interact with custodian, data source, and processing set objects:
- IProcessingCustodianManager - used to access the Processing Custodian Manager service.
- IProcessingDataSourceManager - used to access the Processing Data Source Manager service.
- IProcessingProfileManager - used to access the Processing Profile Manager service.
- IProcessingSetManager - used to access the Processing Set Manager service.
Each of these interfaces provide a ReadAsync() and SaveAsync() method, which you can use to create, update, or retrieve processing objects. The Processing API includes the ProcessingCustodian, ProcessingDatasource, ProcessingProfile, and ProcessingSet classes. You can set or retrieve properties on these classes by calling the ReadAsync() or SaveAsync() method on their respective interfaces. You must call the SaveAsync() method to add any new or modified objects to the database.
Common processing workflows
The Processing API also includes the IProcessingJobManager interface. You can use this interface to access the Processing Job Manager service for running inventory, discovery, and publishing jobs. It includes the following methods:
- SubmitInventoryJobsAsync() method – used for excluding irrelevant files from a data set prior to running a discovery job, such as eliminating NIST file types. The InventoryJob class includes properties for the workspace artifact and processing set IDs required to submit a job.
- SubmitDiscoveryJobsAsync() method – used for submitting data sources to the processing engine for discovery. The DiscoveryJob class includes properties for the workspace artifact and processing set IDs required to submit a job.
- SubmitPublishJobsAsync() method – used to publish the processed data to a workspace after discovery, so that reviewers can access it. The PublishJob class includes properties for the workspace artifact and processing set IDs required to submit a job.
Common workflows for processing include inventorying, discovering, and then publishing data, or just discovering and then publishing data. You can only inventory files that haven’t been discovered. Additionally, you can only publish files after Relativity has completed discovery. For more information, see Processing Job Manager and Processing API services for REST.
In Relativity, you want to enable the auto-publish option on the processing profile, so that the discovered files are automatically added to the workspace. See Relativity environment setup.
Processing API prerequisites
Complete the following prerequisites to begin development with the Processing API:
SDK downloadsDevelopment guidelines for the Processing API
Use these guidelines when automating workflows with the Processing API:
- Add the following DLL references to your Visual Studio project. For additional information, see Prerequisites for Processing API development.
- Relativity.Processing.Services.Interfaces.dll (in the Processing API SDK)
- kCura.Relativity.Client.dll (in the Relativity SDK)
- Relativity.Kepler.dll (in the Relativity SDK)
- Use the Relativity API helpers to establish a connection with the Processing API and set the context used for your code execution. All code samples on this page illustrate how to use the helper classes to connect with the Processing API. For more information, see Using Relativity API Helpers.
- Call the SaveAsync() method on any processing object that you create or modify. Your changes won't be added to the database until you make this call.
- Use a try-catch block around your code for creating, updating, and reading objects. Also, use it when submitting jobs. Catch any ServiceExceptions raised by your code as exemplified in the following code samples.
- Use logging to help troubleshoot your code as exemplified in the following code samples.
Processing Custodian Manager
The Processing Custodian Manager service supports read and save operations on custodian objects. The ProcessingCustodian class represents a custodian associated with the files that you want to process. For more information, see Entity object on the Relativity Documentation site.
Create a ProcessingCustodian
To create a ProcessingCustodian instance, invoke the constructor and then initialize the following properties:
- ArtifactID – set this property to 0, indicating that you are creating a new instance.
- DocumentNumberingPrefix – set this property to a prefix that you want applied to files when the processing engine publishes them to a workspace. The default value is REL.
- FirstName – set this property to the custodian's first name.
- LastName – set this property to the custodian's last name.
Next, call the SaveAsync() method on the proxy created with the IProcessingCustodianManager interface to access the service. You must then pass this method the initialized ProcessingCustodian instance and the workspace Artifact ID.
public async Task<bool> ProcessingCustodianManager_Create_SaveAsync(IHelper helper)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingCustodianManager proxy = helper.GetServicesManager().CreateProxy<IProcessingCustodianManager>(ExecutionIdentity.User))
{
try
{
//Build the ProcessingCustodian object.
ProcessingCustodian processingCustodian = new ProcessingCustodian
{
ArtifactID = 0, // Indicates a new ProcessingCustodian object.
DocumentNumberingPrefix = "REL",
FirstName = "John",
LastName = "Smith"
};
//Create the ProcessingCustodian object. The service returns the Artifact ID of the object.
int artifactId = await proxy.SaveAsync(processingCustodian, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingCustodianManager_Create_SaveAsync), "Create failed", this.GetType().Name);
}
}
catch (Exception exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingCustodianManager_Create_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Read a ProcessingCustodian
Read the values for the properties on a ProcessingCustodian object by calling the ReadAsync() method on the proxy created with IProcessingCustodianManager interface. The ReadAsync() method requires that you pass the Artifact IDs of the ProcessingCustodian object and the workspace as arguments.
public async Task<bool> ProcessingCustodianManager_ReadAsync(IHelper helper, int processingCustodianArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingCustodianManager proxy = helper.GetServicesManager().CreateProxy<IProcessingCustodianManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingCustodian object.
ProcessingCustodian processingCustodian = await proxy.ReadAsync(processingCustodianArtifactId, WorkspaceId);
//Display the last and first name of the custodian.
string fullName = $"{processingCustodian.LastName}, {processingCustodian.FirstName}";
Logger.LogMessage(LogLevel.Debug, nameof(ProcessingCustodianManager_ReadAsync), fullName, this.GetType().Name);
success = true;
}
catch (Exception exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingCustodianManager_ReadAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Update a ProcessingCustodian
When updating a ProcessingCustodian instance, you call the AsyncRead() method on the proxy created with the IProcessingCustodianManager interface. Next, set the properties on the instance to their new values, and then call the SaveAsync() method. You must call the SaveAsync() method in order for your changes to be added to the database.
public async Task<bool> ProcessingCustodianManager_Update_SaveAsync(IHelper helper, int processingCustodianArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingCustodianManager proxy = helper.GetServicesManager().CreateProxy<IProcessingCustodianManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingCustodian object.
ProcessingCustodian processingCustodian = await proxy.ReadAsync(processingCustodianArtifactId, WorkspaceId);
//Modify the document numbering prefix and first name.
processingCustodian.DocumentNumberingPrefix = "ECA";
processingCustodian.FirstName = "Sam";
processingCustodian.Name = $"{processingCustodian.LastName}, {processingCustodian.FirstName}";
//Update the ProcessingCustodian object. The service returns the Artifact ID of the object.
int artifactId = await proxy.SaveAsync(processingCustodian, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingCustodianManager_Update_SaveAsync), "Update failed", this.GetType().Name);
}
}
catch (Exception exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingCustodianManager_Update_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Processing Profile
The Processing Profile represents a collection of settings used to process documents. Processing profiles are associated with processing sets, so you must provide the Artifact ID of a processing profile when creating or updating a processing set, see Processing Set Manager for more details. The Processing Profile can be updated using the Object Manager API, use the Create endpoint for creating a new profile, the Update endpoint for updating a profile, the Query endpoint for retrieving a profile, and the Delete endpoint for removing a profile from Relativity. Sample methods are provided below for performing all of these actions with a Processing Profile.
Getting Started With Processing Profile Guids
The Processing Profile has multiple properties for specifying numbering; deNISTing, extraction, and deduplication settings.
You can find more information about processing profile fields on the following pages:
Before you can create or update fields within a Processing Profile, the ArtifactID’s will need to be queried. Use the ReadMultipleArtifactIdsAsync endpoint from the Artifact Guid Manager to retrieve the field ArtifactID's that are needed. Once the ArtifactID’s are collected using the corresponding Guid from the list below, they can be used to identify which field values are being set.
Processing Profile Guids List
To access Processing Profile fields via the Relativity API, enter the following IDs:
Create a Processing Profile
To create a processing profile in a workspace, set the required fields using their ArtifactID’s queried from the Guid list above and the value. Call the Object Manager Create endpoint by passing it the new Processing Profile values and the Artifact ID of a Workspace object.
Query a Processing Profile
Use the Object Manager Query endpoint to retrieve a list of processing profiles from Relativity if passing in the ArtifactTypeId or pass in the ArtifactId of the specific Processing Profile to retrieve child FieldValues.
Update a Processing Profile
To update a processing profile, modify the profile fields as necessary by passing in the ArtifactID and Value of the field along with the Processing Profile ArtifactID and then pass this object to the Object Manager Update endpoint.
Delete a Processing Profile
Use the Object Manager Delete endpoint to remove a processing profile from Relativity by passing in the Processing Profile ArtifactId and WorkspaceId.
Processing Data Source Manager
The Processing Data Source Manager service supports read and save operations on data source objects. The ProcessingDataSource class represents a data source that contains the location of the files for discovery during processing. For more information, see Processing sets on the Relativity Documentation site.
Create a ProcessingDataSource
To create a ProcessingDataSource instance, invoke the constructor and initialize the following properties:
- ArtifactID – set this property to 0, indicating that you are creating a new instance.
- Custodian – set this property to the Artifact ID associated with this data source.
- TimeZone – set this property to the Artifact ID that you obtained from the workspace database. See Required Artifact IDs.
- DestinationFolder – set this property to the Artifact ID that you obtained from the workspace database. See Required Artifact IDs.
- StartNumber – set this property to the value used to begin numbering a sequence of documents published from a specific data source. This field should not be selected if the Processing Profile has Level Numbering selected for Numbering Type.
Note: You can set this property to null. When it is null, Relativity uses auto-numbering. For more information about numbering type options, see Processing sets on the Relativity Documentation site.
- IsStartNumberVisible – determines whether Relativity UI displays the Start Number field in the Data Source layout. This field should not be selected if the Processing Profile has Level Numbering selected for Numbering Type.
- Other properties – set them to their required values. The following code sample uses the default values.
Call the SaveAsync() method on the proxy created with the IProcessingDataSourceManager interface. You must then pass this method the initialized ProcessingDataSource instance and the workspace Artifact ID as illustrated in the following code.
public async Task<bool> ProcessingDataSourceManager_Create_SaveAsync(IHelper helper, int custodianArtifactId, int destinationFolderArtifactId, int timeZoneArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingDataSourceManager proxy = helper.GetServicesManager().CreateProxy<IProcessingDataSourceManager>(ExecutionIdentity.User))
{
try
{
//Build the processing ProcessingDataSource object.
ProcessingDataSource processingDataSource = new ProcessingDataSource
{
ArtifactID = 0, // Indicates a new ProcessingDataSource object.
ProcessingSet = new ProcessingSetRef { ArtifactID = ProcessingSetId },
Custodian = custodianArtifactId,
DestinationFolder = destinationFolderArtifactId,
DocumentNumberingPrefix = "REL",
InputPath = "@Some/Path",
Name = "Data Source 1",
OcrLanguages = new[] { OcrLanguage.English },
Order = 200,
TimeZone = timeZoneArtifactId,
StartNumber = 8,
IsStartNumberVisible = true,
};
//Create the ProcessingDataSource object. The service returns the Artifact ID for the object.
int artifactId = await proxy.SaveAsync(processingDataSource, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingDataSourceManager_Create_SaveAsync), "Create failed", this.GetType().Name);
}
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingDataSourceManager_Create_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Read a ProcessingDataSource
Read the values for the properties on a ProcessingDataSource object by calling the ReadAsync() method on the proxy created with the IProcessingDataSourceManager interface. The ReadAsync() method requires that you pass the Artifact IDs of the ProcessingDataSource object and the workspace as arguments.
public async Task<bool> ProcessingDataSourceManager_ReadAsync(IHelper helper, int processingDataSourceArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingDataSourceManager proxy = helper.GetServicesManager().CreateProxy<IProcessingDataSourceManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingSet object.
ProcessingDataSource processingDataSource = await proxy.ReadAsync(processingDataSourceArtifactId, WorkspaceId);
//Display the input path.
Logger.LogMessage(LogLevel.Debug, nameof(ProcessingDataSourceManager_ReadAsync), processingDataSource.InputPath, this.GetType().Name);
success = true;
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingDataSourceManager_ReadAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Update a ProcessingDataSource
When updating a ProcessingDataSource instance, you call the AsyncRead() method on the proxy created with the IProcessingDataSourceManager interface. Next, set the properties on the instance to their new values, and then call the SaveAsync() method. You must call the SaveAsync() method in order for your changes to be added to the database.
public async Task<bool> ProcessingDataSourceManager_Update_SaveAsync(IHelper helper, int processingDataSourceArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingDataSourceManager proxy = helper.GetServicesManager().CreateProxy<IProcessingDataSourceManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingDataSource object.
ProcessingDataSource processingDataSource = await proxy.ReadAsync(processingDataSourceArtifactId, WorkspaceId);
//Modify the input path and destination folder.
processingDataSource.InputPath = "@Some/Other/Path";
processingDataSource.DestinationFolder = 99; // Artifact Id of the destination folder
//Update the processing data source object. The service returns the Artifact ID of the object.
int artifactId = await proxy.SaveAsync(processingDataSource, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingDataSourceManager_Update_SaveAsync), "Update failed", this.GetType().Name);
}
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingDataSourceManager_Update_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Processing Set Manager
The Processing Set Manager service supports read and save operations on processing set objects. The ProcessingSet class represents a processing set object that links a processing profile to one or more data sources. For more information, see Processing sets on the Relativity Documentation site.
Create a ProcessingSet
To create a ProcessingSet instance, invoke the constructor and then initialize the following properties:
- ArtifactID – set this property to 0, indicating that you are creating a new instance.
- EmailNotificationRecipients – set this optional property to an array of email addresses.
- Name – set this property to the name of the processing set.
- Profile – set this property to the Artifact ID of the processing profile that you obtained from your workspace database table. See Required Artifact IDs.
Call the SaveAsync() method on the proxy created with the IProcessingSetManager interface. You must then pass the initialized ProcessingSet object and workspace Artifact ID to this method.
public async Task<bool> ProcessingSetManager_Create_SaveAsync(IHelper helper, int processingProfileArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingSetManager proxy = helper.GetServicesManager().CreateProxy<IProcessingSetManager>(ExecutionIdentity.User))
{
try
{
//Build the ProcessingSet object.
ProcessingSet processingSet = new ProcessingSet
{
ArtifactID = 0, // Indicates a new ProcessingSet object.
EmailNotificationRecipients = new[] { "johnSmith@domain.com", "adamJohnson@domain.com" },
Name = "Test Set",
Profile = new ProcessingProfileRef(processingProfileArtifactId) // The Artifact ID of the processing profile.
};
//Create the ProcessingSet object. The service returns the Artifact ID of the object.
int artifactId = await proxy.SaveAsync(processingSet, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_Create_SaveAsync), "Create failed", this.GetType().Name);
}
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_Create_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Read a ProcessingSet
Read the values for the properties on a ProcessingSet object by calling the ReadAsync() method on the IProcessingSetManager. The ReadAsync() method requires that you pass the Artifact IDs of the ProcessingSet object and the workspace as arguments.
public async Task<bool> ProcessingSetManager_ReadAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingSetManager proxy = helper.GetServicesManager().CreateProxy<IProcessingSetManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingSet object.
ProcessingSet processingSet = await proxy.ReadAsync(processingSetArtifactId, WorkspaceId);
//Display the Artifact ID of the processing profile.
string profileId = $"{processingSet.Profile.ArtifactID}";
Logger.LogMessage(LogLevel.Debug, nameof(ProcessingSetManager_ReadAsync), profileId, this.GetType().Name);
success = true;
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_ReadAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Update a ProcessingSet
When updating a ProcessingSet instance, you call the AsyncRead() method on the proxy created with the IProcessingSetManager interface. Next, set the properties on the instance to their new values, and then call the SaveAsync() method. You must call the SaveAsync() method in order for your changes to be added to the database.
public async Task<bool> ProcessingSetManager_Update_SaveAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingSetManager proxy = helper.GetServicesManager().CreateProxy<IProcessingSetManager>(ExecutionIdentity.User))
{
try
{
//Read the ProcessingSet object.
ProcessingSet processingSet = await proxy.ReadAsync(processingSetArtifactId, WorkspaceId);
//Modify the list of email recipients list and the name of the processing set.
processingSet.EmailNotificationRecipients = new[] { "johnSmith@domain.com" };
processingSet.Name = "Test Set";
//Update the ProcessingSet object. The service returns the Artifact ID of the object.
int artifactId = await proxy.SaveAsync(processingSet, WorkspaceId);
if (artifactId != 0)
{
success = true;
}
else
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_Update_SaveAsync), "Update failed", this.GetType().Name);
}
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_Update_SaveAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Retrieve a list of processing sets and related aggregate information
You can use the GetDocumentAggregates() method to retrieve document totals and other information about processing sets in a specific workspace. To retrieve this information, the process sets must have the statuses of Completed or Completed with errors. If you wanted to create a custom dashboard for reporting purposes, use this method to populate it with information about completed processing sets. For example, Relativity uses the GetDocumentAggregates() method to populate the Early Case Assessment dashboard with processing set data.
Use the following classes in conjunction with the GetDocumentAggregates() method. For additional reference information, see Processing API.
public async Task<ProcessingSetDocumentInfoSummary> ProcessingSetManager_GetDocumentAggregatesAsync(IHelper helper, int workspaceArtifactId)
{
// Get a connection to the API using the Relativity API Helper classes, available on event handlers,
// agents, and custom Pages. They are mocked in these samples.
// This sample code executes under the context of the current user.
using (IProcessingSetManager proxy = helper.GetServicesManager().CreateProxy<IProcessingSetManager>(ExecutionIdentity.User))
{
try
{
// Build the GetDocumentAggregatesRequest object.
GetDocumentAggregatesRequest request = new GetDocumentAggregatesRequest
{
Page = 0,
PageSize = 15,
SortColumnName = "ProcessingSetName",
SortDescending = true,
WorkspaceArtifactId = workspaceArtifactId
};
// Submit the request. The service returns information for all 'Completed' and 'Completed with Errors'
// Processing Sets in the given workspace.
ProcessingSetDocumentInfoSummary processingSetDocumentInfoSummary = await proxy.GetDocumentAggregates(request);
return processingSetDocumentInfoSummary;
}
catch (ServiceException serviceException)
{
Logger.LogMessage(LogLevel.Error, nameof(ProcessingSetManager_GetDocumentAggregatesAsync), serviceException.Message, this.GetType().Name);
throw;
}
}
}Processing Job Manager
The Processing Job Manager service includes methods for executing inventory, discovery, and publishing jobs. It also includes a method for canceling any of these jobs for a processing set. This service is available through the IProcessingJobManager interface. For more information, see Common processing workflows.
Inventory jobs
The following code illustrates how to run an inventory job by calling the SubmitInventoryJobsAsync() method on the proxy created with the IProcessingJobManager interface. You must pass an initialized InventoryJob instance to this method. This instance has the Artifact ID of the processing set that you want to use for the job, and the Artifact ID of the workspace where it resides.
If you want to use filtering on your inventory job, apply filters through Relativity after you programmatically run your inventory job. For more information, see Inventory on the Relativity Documentation site.
public async Task<bool> ProcessingJobManager_InventoryAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingJobManager proxy = helper.GetServicesManager().CreateProxy<IProcessingJobManager>(ExecutionIdentity.User))
{
try
{
//Create an inventory job object.
InventoryJob inventoryJob = new InventoryJob
{
ProcessingSetId = processingSetArtifactId,
WorkspaceArtifactId = WorkspaceId
};
//Submit the job for inventory.
await proxy.SubmitInventoryJobsAsync(inventoryJob);
success = true;
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingJobManager_InventoryAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Discovery jobs
The following code illustrates how to run a discovery job by calling the SubmitDiscoveryJobsAsync() method on the proxy created with the IProcessingJobManager interface. You must pass an initialized DiscoveryJob instance to this method. The DiscoveryJob instance represents a processing job that you want to run. This instance has the Artifact ID of the processing set that you want to use for the job, and the Artifact ID of the workspace where it resides. For more information, see Processing on the Relativity Documentation site
public async Task<bool> ProcessingJobManager_DiscoveryAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user. For more information, see the documentation for Relativity API Helpers.
using (IProcessingJobManager proxy = helper.GetServicesManager().CreateProxy<IProcessingJobManager>(ExecutionIdentity.User))
{
try
{
//Create a discovery job object.
DiscoveryJob discoveryJob = new DiscoveryJob
{
ProcessingSetId = processingSetArtifactId,
WorkspaceArtifactId = WorkspaceId
};
//Submit the job for discovery.
await proxy.SubmitDiscoveryJobsAsync(discoveryJob);
success = true;
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingJobManager_DiscoveryAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Publishing jobs
The following code illustrates how to execute a publishing job by calling the SubmitPublishJobsAsync() method on the proxy created with the IProcessingJobManager interface. You must pass an initialized PublishJob instance to this method. This instance has the Artifact ID of the processing set that you want to use for the job, and the Artifact ID of the workspace where it resides.
Similar to the Relativity UI, you can resubmit a publishing job with processing errors by calling the SubmitPublishJobsAsync() method again. For more information, see
public async Task<bool> ProcessingJobManager_PublishAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingJobManager proxy = helper.GetServicesManager().CreateProxy<IProcessingJobManager>(ExecutionIdentity.User))
{
try
{
//Create a publish job object.
PublishJob publishJob = new PublishJob
{
ProcessingSetId = processingSetArtifactId,
WorkspaceArtifactId = WorkspaceId
};
//Submit the job for discovery.
await proxy.SubmitPublishJobsAsync(publishJob);
success = true;
}
catch (ServiceException exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingJobManager_PublishAsync), exception.Message, this.GetType().Name);
}
}
return success;
}Cancel jobs
You can use the SubmitCancelJobAsync() method to cancel inventory, discovery, and publishing jobs for a specific processing set. The following code illustrates how to execute a cancel job by calling this method on the proxy created with the IProcessingJobManager interface. You must pass an initialized CancelJob instance to this method. This instance has the Artifact ID of the processing set associated with the job that you want to cancel, and the Artifact ID of the workspace where it resides.
This sample code returns a Boolean value called success after the cancel job has been successfully submitted. However, this return value doesn't indicate that the job has been canceled. Multiple factors influence when a worker picks up a cancel job and how long the job takes to execute. For example, the amount of data and system state can affect this outcome.
Note: The submission of cancel job returns successfully when the job associated with a processing set has already been canceled.
public async Task<bool> ProcessingJobManager_CancelAsync(IHelper helper, int processingSetArtifactId)
{
bool success = false;
//Get a connection to the API using the Relativity API Helper classes, available on event handlers,
//agents, and custom Pages. They are mocked in these samples.
//This sample code executes under the context of the current user.
using (IProcessingJobManager proxy = helper.GetServicesManager().CreateProxy<IProcessingJobManager>(ExecutionIdentity.User))
{
try
{
//Create a cancel job object.
CancelJob cancelJob = new CancelJob
{
ProcessingSetId = processingSetArtifactId,
WorkspaceArtifactId = WorkspaceId
};
//Submit a job to cancel a processing set.
await proxy.SubmitCancelJobAsync(cancelJob);
success = true;
}
catch (Exception exception)
{
//The service returns exceptions of type ServiceException.
Logger.LogMessage(LogLevel.Error, nameof(ProcessingJobManager_CancelAsync), exception.Message, this.GetType().Name);
}
}
return success;
}