This DTO has been deprecated as part of the Relativity Services API (RSAPI) Deprecation and is no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

BatchSet

In Relativity, a batch set represents a group of batches, which are sets of documents. For more information, see Batches on the Relativity Documentation site.

The Services API supports all create, read, update, and delete (CRUD) and query operations on the BatchSet DTO.

Note: You can also perform a full set of CRUD operations on batch sets using the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.

This page contains the following information:

Create, update, and query BatchSet objects

After you create a BatchSet DTO, you can update its properties by calling the Update() method on the BatchSet repository. This code sample illustrates how to create a BatchSet, read its fields from the database, update the fields, and then query for the BatchSet.

Copy 

public static bool Create_then_Update_A_BatchSet_Using_Repositories(IRSAPIClient proxy)
{
     // STEP 1: Create a BatchSet DTO and set its properties.
     kCura.Relativity.Client.DTOs.BatchSet newBatchSet = new kCura.Relativity.Client.DTOs.BatchSet();
      
     newBatchSet.Name = "My Batch Set";
     newBatchSet.BatchPrefix = "Batch";
     newBatchSet.MaximumBatchSize = 5;
     newBatchSet.AutoBatch = true;
     newBatchSet.MinimumBatchSize = 1;
     newBatchSet.AutoCreateRateMinutes = 30;
     newBatchSet.BatchDataSource = new kCura.Relativity.Client.DTOs.Artifact(1036604);
      
     // STEP 2: Call the Services API to create the BatchSet.
     WriteResultSet<kCura.Relativity.Client.DTOs.BatchSet> createResults = null;
     try
     {
          createResults = proxy.Repositories.BatchSet.Create(newBatchSet);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred creating the batch set: {0}", ex.Message));
          return false;
     }
      
     if (!createResults.Success)
     {
          Console.WriteLine(string.Format("An error occurred creating the batch set: {0}", createResults.Message));
          return false;
     }
      
     Int32 newID = createResults.Results[0].Artifact.ArtifactID;
     Console.WriteLine("ID of the new Batch Set: " + newID.ToString());
      
     // STEP 3: Read the batch to get all the fields from the database.
     ResultSet<kCura.Relativity.Client.DTOs.BatchSet> readResults = null;
     kCura.Relativity.Client.DTOs.BatchSet batchSetRead = new BatchSet(newID);
     batchSetRead.Fields = FieldValue.AllFields;
     try
     {
          readResults = proxy.Repositories.BatchSet.Read(batchSetRead);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred reading the batch set: {0}", ex.Message));
          return false;
     }
     if (!readResults.Success)
     {
          Console.WriteLine(string.Format("An error occurred reading the batch set: {0}", readResults.Message));
          return false;
     }
      
     kCura.Relativity.Client.DTOs.BatchSet readBatchSet = readResults.Results[0].Artifact;
     Console.WriteLine("Initial value of Name: " + readBatchSet.Name);
     Console.WriteLine("Initial value of AutoCreateRate: " + readBatchSet.AutoCreateRateMinutes.ToString());
      
     // STEP 4: Modify properties of the BatchSet. The Name and TextIdentifier both have the
     // same value which is the Batch Set Name. Since they have the same value, 
     // you can update the BatchSet using the TextIdentifier.
     kCura.Relativity.Client.DTOs.BatchSet batchSet = readResults.Results[0].Artifact;
     batchSet.TextIdentifier = "Better Batchset";
     batchSet.AutoCreateRateMinutes = 45;
      
     // MaximumBatchSize must be set for the update.
     batchSet.MaximumBatchSize = readBatchSet.MaximumBatchSize;
     WriteResultSet<kCura.Relativity.Client.DTOs.BatchSet> updateResults = null;
      
     // STEP 5: Call the Services API to update the BatchSet just created.
     try
     {
          updateResults = proxy.Repositories.BatchSet.Update(batchSet);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred updating the batch set: {0}", ex.Message));
          return false;
     }
      
     if (!updateResults.Success)
     {
          Console.WriteLine(string.Format("An error occurred updating the batch set: {0}", updateResults.Message));
          return false;
     }
      
     // STEP 6: Verify that update worked by querying the BatchSet.
     Query<kCura.Relativity.Client.DTOs.BatchSet> batchSetQuery = 
          new Query<kCura.Relativity.Client.DTOs.BatchSet>();
     batchSetQuery.Fields = FieldValue.AllFields;
     batchSetQuery.Condition = 
          new WholeNumberCondition(ArtifactQueryFieldNames.ArtifactID, NumericConditionEnum.EqualTo, newID);
     QueryResultSet<kCura.Relativity.Client.DTOs.BatchSet> queryResultSet = null;
      
     try
     {
          queryResultSet = proxy.Repositories.BatchSet.Query(batchSetQuery);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred reading the batch set after updating: {0}", ex.Message));
          return false;
     }
     kCura.Relativity.Client.DTOs.BatchSet readBatchSet2 = queryResultSet.Results[0].Artifact;
     Console.WriteLine("Updated value of Name: " + readBatchSet2.Name);
     Console.WriteLine("Updated value of AutoCreateRate: " + readBatchSet2.AutoCreateRateMinutes);
      
     return true;
}

Create and delete a BatchSet

This code sample illustrates how to call the Create() and Delete() methods on a BatchSet repository.

Copy 

public static bool Create_then_Delete_A_BatchSet_Using_Repositories(IRSAPIClient proxy)
{
     // STEP 1: Create a BatchSet DTO and set its properties.
     DTOs.BatchSet newBatchSet = new DTOs.BatchSet();
     newBatchSet.Name = "My Batch Set";
     newBatchSet.BatchPrefix = "Batch";
     newBatchSet.MaximumBatchSize = 5;
     newBatchSet.BatchDataSource = new DTOs.Artifact(1036604);
      
     // STEP 2: Declare a variable to hold the returned values.
     WriteResultSet<DTOs.BatchSet> results = 
          new WriteResultSet<DTOs.BatchSet>();
     Int32 newID = new Int32();
      
     // STEP 3: Call the Services API to create the BatchSet.
     try
     {
          results = proxy.Repositories.BatchSet.Create(newBatchSet);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (results.Success)
     {
          newID = results.Results[0].Artifact.ArtifactID;
           
          Console.WriteLine(string.Format("ID of the new Batch Set: {0}", newID));
           
          // STEP 4: Instantiate BatchSet with the ID of the BatchSet that you want to delete.
          DTOs.BatchSet batchSetToDelete = new DTOs.BatchSet(newID);
           
          // STEP 5: Call the Services API to delete the BatchSet just created.
          try
          {
               results = proxy.Repositories.BatchSet.Delete(batchSetToDelete);
          }
          catch (Exception ex)
          {
               Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
               return false;
          }
          Console.WriteLine(string.Format("Overall Status of Deleting a Batch Set: {0}", results.Success));
     }
     return true;
}

Create Batches for a BatchSet

You can use the CreateBatchesAsync() method to add Batch objects to a BatchSet as illustrated in this code sample. For more information about this method, see Asynchronous framework.

Copy 

public static Boolean Create_Batches_For_BatchSet(IRSAPIClient proxy)
{
     // STEP 1: Create a new BatchSet object.
     DTOs.BatchSet batchSet = new DTOs.BatchSet();
     batchSet.Name = "My Batch Set";
     batchSet.MaximumBatchSize = 5;
     batchSet.BatchPrefix = "APISAMPLES-";
     batchSet.BatchDataSource = new DTOs.Artifact(1036604);
      
     // STEP 2: Call the Services API to create the BatchSet.
     WriteResultSet<DTOs.BatchSet> createResults;
      
     try
     {
          createResults = proxy.Repositories.BatchSet.Create(batchSet);
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!createResults.Success)
     {
     Console.WriteLine(String.Format("An error occurred: {0}", createResults.Message));
     return false;
     }
     // STEP 3: Add Handlers for events that may occur while creating Batches.
     proxy.ProcessProgress += HandleProcessProgressEvent;
     proxy.ProcessComplete += HandleProcessCompleteEvent;
     proxy.ProcessFailure += HandleProcessFailureEvent;
     proxy.ProcessCancelled += HandleProcessCancelEvent;
      
     // STEP 4: Create Batches for the Batch Set.  While the server is executing this call,
     // your event handlers are called with progress and completion events.
     Int32 batchSetArtifactID = createResults.Results[0].Artifact.ArtifactID;
     ProcessOperationResult processResult;
      
     try
     {
          processResult = proxy.Repositories.BatchSet.CreateBatchesAsync(new DTOs.BatchSet(batchSetArtifactID));
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!processResult.Success)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", processResult.Message));
          return false;
     }
     return true;
}

Query for a BatchSet

To query for a BatchSet, you can use the fields listed in the following table. For more information, see Search Relativity and Create, update, and query BatchSet objects.

Fields for BatchSet queries
Artifact ID Last Modified By
Artifact ID Last Modified On
Auto Create Rate (minutes) Last Successful Run
Batch Data Source Maximum Batch Size
Batch Prefix Minimum Batch Size
Created By Name
Created On Reviewed
Documents to be Batched Security
Family Field Status
Last Error Reported  

Cancel creation of a BatchSet

When you cancel the creation of a BatchSet, Relativity stops creating new Batches but it doesn't delete those that were already created. This code sample illustrates how to use the FlagProcessForCancellationAsync() to cancel Batch creation. For more information about this method, see Asynchronous framework.

Copy 

public static Boolean Cancel_Batch_Creation(IRSAPIClient proxy)
{
     // STEP 1: Create a new BatchSet object.
     DTOs.BatchSet batchSet = new DTOs.BatchSet();
     batchSet.Name = "My Batch Set";
     batchSet.MaximumBatchSize = 5;
     batchSet.BatchPrefix = "APISAMPLES-";
     batchSet.BatchDataSource = new DTOs.Artifact(1036604);
      
     // STEP 2: Call the Services API to create the BatchSet.
     WriteResultSet<DTOs.BatchSet> createResults;
     try
     {
          createResults = proxy.Repositories.BatchSet.Create(batchSet);
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
      
     if (!createResults.Success)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", createResults.Message));
          return false;
     }
      
     // STEP 3: Add Handlers for events that may occur while creating batches.
     proxy.ProcessProgress += HandleProcessProgressEvent;
     proxy.ProcessComplete += HandleProcessCompleteEvent;
     proxy.ProcessFailure += HandleProcessFailureEvent;
     proxy.ProcessCancelled += HandleProcessCancelEvent;
      
     // STEP 4: Create batches for the Batch Set. While the server is executing this call,
     // your event handlers will be called with progress and completion events.
     Int32 batchSetArtifactID = createResults.Results[0].Artifact.ArtifactID;
     ProcessOperationResult processResult;
      
     try
     {
          processResult = proxy.Repositories.BatchSet.CreateBatchesAsync(new DTOs.BatchSet(batchSetArtifactID));
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!processResult.Success)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", processResult.Message));
          return false;
     }
      
     // STEP 5: Cancel batch creation.  After executing this call, the Relativity server 
     // stops creating Batches, but it doesn't delete the Batches that were already created.
     System.Guid processID = processResult.ProcessID;
     try
     {
          processResult = proxy.FlagProcessForCancellationAsync(proxy.APIOptions, processID);
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred cancelling batch set creation: {0}", ex.Message));
          return false;
     }
      
     if (!processResult.Success)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", processResult.Message));
          return false;
     }
      
     return true;
}

Purge Batches for a BatchSet

You can use the PurgeBatchesAsync() method to delete the Batch objects associated with a BatchSet object as illustrated in this code sample. For more information about this method, see Asynchronous framework.

Copy 

public static Boolean Purge_Batches_For_BatchSet(IRSAPIClient proxy)
{
     // STEP 1: Add Handlers for events that may occur while creating batches.
     proxy.ProcessProgress += HandleProcessProgressEvent;
     proxy.ProcessComplete += HandleProcessCompleteEvent;
     proxy.ProcessFailure += HandleProcessFailureEvent;
     proxy.ProcessCancelled += HandleProcessCancelEvent;
      
     // STEP 2: Call the server method to delete the existing batches for a particular batch set.
     Int32 batchSetArtifactID = 1036606;
     ProcessOperationResult processResult;
     try
     {
          processResult = proxy.Repositories.BatchSet.PurgeBatchesAsync(new DTOs.BatchSet(batchSetArtifactID));
     }
     catch (Exception ex)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!processResult.Success)
     {
          Console.WriteLine(String.Format("An error occurred: {0}", processResult.Message));
          return false;
     }
      
     return true;
}

Event handlers used in code samples

These event handlers are referenced in the previous code samples:

  • Used for progress notification while executing an asynchronous method.
    Copy

    public static void HandleProcessProgressEvent(Object sender, ProcessProgressEventArgs eventArgs)
    {
         ProcessInformation processInformation = eventArgs.ProcessInformation;
         Console.WriteLine("For the Batch Set operation, the number of operations 
              completed is " + processInformation.OperationsCompleted.ToString());
    }
  • Used for notification when an asynchronous method successfully finishes.
    Copy

    public static void HandleProcessCompleteEvent(Object sender, ProcessCompleteEventArgs eventArgs)
    {
         ProcessInformation processInformation = eventArgs.ProcessInformation;
         Console.WriteLine("The Batch Set operation completed");
    }
  • Used for notification when an asynchronous method finishes with an error.
    Copy

    public static void HandleProcessFailureEvent(Object sender, ProcessFailureEventArgs eventArgs)
    {
    ProcessInformation processInformation = eventArgs.ProcessInformation;
    if (processInformation.Success == false)
         Console.WriteLine("There was a problem retrieving the 
              process information, the message is " + processInformation.Message);
    else
         Console.WriteLine("The Batch Set operation failed, the process state is " 
              + processInformation.State.ToString());
    }
  • Used for notification when an asynchronous method stops due to a cancellation request.
    Copy

    public static void HandleProcessCancelEvent(Object sender, ProcessCancelEventArgs eventArgs)
    {
         Console.WriteLine("The Batch Set operation was canceled");
    }