Imaging API

The Imaging API supports programmatically interacting with imaging profiles, sets, jobs, and other related components. It includes several interfaces used to access services that provide this functionality. The interfaces for the imaging job service include methods for running and canceling jobs, updating priorities on jobs, and retrying jobs with errors. The services for imaging profiles, imaging sets, and application field codes support all CRUD operations. The imaging set service provides additional functionality used to hide and release images during a quality control review, while the native type service includes functionality for reading native file types supported by Relativity.

Sample use cases for the imaging services include automating workflows and building custom applications with this functionality. For example, you could use the imaging services to automate a workflow for running imaging jobs rather than manually performing these tasks through the Relativity UI. You could implement an application with a custom UI that displays information about imaging profiles, imaging sets, and jobs based on specific requirements from your organization.

In addition, you can also access the services available on the Imaging API through REST. The REST endpoints support the same functionality for the Imaging API services as available through .NET. For more information, see Imaging API services for REST.

This page contains the following information:

• Imaging API fundamentals
• Guidelines for using the Imaging API
• Prerequisites and sample project
• Imaging Profile Manager
• Imaging Set Manager
• Native Type Manager
• Application Field Code Manager
• Imaging Job Manager

See this related page:

• Imaging API services for REST

Imaging API fundamentals

The Relativity.Imaging.Services.Interfaces namespace contains the methods, classes, and enumerations required to run imaging jobs and perform other related tasks. It includes the following interfaces that you can use to access the services for imaging documents:

• IImagingProfileManager interface - contains the CRUD methods used to work with imaging profiles. It includes the SaveAsync(), ReadAsync(), and DeleteAsync() methods. For code samples, see Imaging Profile Manager.
• IImagingSetManager interface - contains the CRUD methods used to work with imaging sets. It includes the SaveAsync(), ReadAsync(), and DeleteAsync() methods. It also provides the HideImagingSetAsync() method used to hide images from reviewers during a quality control review, and the ReleaseImagingSetAsync() method to make them available to reviewers. For code samples, see Imaging Set Manager
• IApplicationFieldCodeManager interface - contains the CRUD methods used to work with application field codes. It includes the SaveAsync(), ReadAsync(), and DeleteAsync() methods. For code samples, see Application Field Code Manager.
• INativeTypeManager interface - contains the ReadAsync() method used to retrieve native file types. For more information, see Native Type Manager.
• IImagingJobManager interface - contains the methods used for executing imaging jobs, including the ImageDocumentAsync(), RetryImagingSetErrorsAsync(), RunImagingSetAsync(), UpdateJobPriorityAsync(), and StopImagingJobAsync() methods. For code samples, see Imaging Job Manager

Class and enumerations

The following list contains some of the key classes available in the Relativity.Imaging.Services.Interfaces namespace:

• ImagingProfile - contains the settings specified for an imaging job. For information about constructing this object type, see Basic imaging profiles and Native imaging profiles.
• BasicImagingEngineOptions - represents the settings for a basic imaging job, including the output quality (DPI), the image format as a JPEG or TIFF, image size settings, and others.
• NativeImagingEngineOptions - represents the settings for a native imaging job, including the output quality (DPI), the image format, number of pages imaged, and others.
• ApplicationFieldCode - contains information about fields used in Microsoft documents to store data. See Application field codes.
• NativeType - represents the native files types associated with an imaging profile. See Native types.
• ImagingSet - represents the imaging profile and saved search used for an imaging job. See Imaging sets.
• ImagingJob - represents a job request submitted to the basic or native imaging engine.
• StopImagingJobRequest - represents a job request sent to the imaging engine to cancel an in-progress imaging job. The StopImagingJobAsync() method takes an object of this type as an argument.
• StopImagingJobResponse - represents a response from the imaging engine that indicates whether an imaging job was successfully canceled. The StopImagingJobAsync() method returns an object of this type.
• UpdateJobPriorityRequest - represents a request to modify the priority of a job. The properties of this class include the GUID of the job being modified, the new priority for the job, the Artifact ID of the workspace containing the job, and an optional identifier for the caller of this method. The UpdateJobPriorityAsync() method takes an object of this type.
• UpdateJobPriorityResponse - represents a response for an update to a job priority. The properties of this class include a Boolean value indicating whether the job succeeded, and an error message. The UpdateJobPriorityAsync() method returns an object of this type.

In addition, this namespace contains multiple enumerations used for setting properties on the ImagingProfile objects and other purposes. For example, it contains the ImageFormat, ImageSize, and PageOrientation enumerations. For a complete list of classes and enumerations, see Imaging APIon the Relativity API reference page.

Prerequisites and sample project

Review the following information about obtaining the required DLLs for developing imaging applications and working with the sample application provided for imaging:

Guidelines for using the Imaging API

Imaging profiles contain the settings used to image a set of documents. They include information about the imaging method, the image output, the file format, and specialized options for email, spreadsheets, and other document types. Consequently, you may find that creating an image profile is a complex process.

To simply this process, review Imaging profiles on the Relativity Server2021 Documentation site.. It contains detailed information about the options available for creating an imaging profile through the Relativity UI. The Imaging API exposes the same options in the ImagingProfile class and includes multiple enumerations used for setting these options. You can use this page as a guide for how to set the properties on an ImagingProfile instance.

Imaging Profiles

You can instantiate an ImagingProfile object by setting the properties used for basic or native imaging on it. Review the following guidelines about how to create ImagingProfile objects.

Basic imaging profiles

When you instantiate an ImagingProfile object for basic imaging, you only need to set a subset of the properties available on the ImagingProfile class. You must set the fields on the BasicOptions property, but you don't need to specify the additional properties used by native imaging, such as EmailOptions, HtmlOptions, and others.

In addition, the following properties on a basic imaging profile are optional:

• ApplicationFieldCodes property - see Application field codes.

  Note: The Imaging API uses the List<SampleObjectRef> construct, as exemplified by the list of ApplicationFieldCodes instances on an ImagingProfile object. When creating a list of these object types, you only need to set the ArtifactID property. The Name property isn't required.

• NativeType property - see Native types.
• Notes property - a description or other information about the imaging profile.
• Keywords property - words or concise phrase used to describe the imaging profile.

The following code sample has settings for properties required for basic imaging:

var imagingProfile = new ImagingProfile {
  BasicOptions = new BasicImagingEngineOptions
  {
    ImageOutputDpi = 100,
    BasicImageFormat = ImageFormat.Jpeg,
    ImageSize = ImageSize.A4
  },
  Name = "New ImagingProfile",
  ImagingMethod = ImagingMethod.Basic
};

Native imaging profiles

To instantiate an ImagingProfile object for native imaging, you must set all of the native imaging properties, including NativeImagingEngineOptions, EmailOptions, HtmlOptions, PresentationOptions, SpreadsheetOptions, and WordProcessingOptions objects. Optional fields on these objects include:

• All nullable fields
• TimeZoneFieldOnDocument field
• NativeImagingEngineOptions field

When determining whether to set these optional fields, you must meet any constraints and dependencies as described in Imaging profiles on the Relativity Server2021 Documentation site.

In addition, the following properties on a basic imaging profile are optional:

• ApplicationFieldCodes property - see Application field codes.

  Note: The Imaging API uses the List<SampleObjectRef> construct, as exemplified by the list of ApplicationFieldCodes instances on an ImagingProfile object. When creating a list of these object types, you only need to set the ArtifactID property. The Name property isn't required.

• NativeType property - see Native types.
• Notes property - a description or other information about the imaging profile.
• Keywords property - words or concise phrase used to describe the imaging profile.

The following code samples demonstrate the complexities of constructing ImagingProfile objects. The first sample illustrates a correctly constructed ImagingProfile object, while the second sample contains conflicting settings.

Application field codes

Microsoft applications use field codes as placeholders for data that may be updated or used for other specialized purposes in documents, such as those created in Word, Excel, or others. In Relativity, application field codes indicate how to handle field codes used in Microsoft documents during imaging. For more information, see Application Field Codes on the Relativity Server2021 Documentation site.

When constructing an ApplicationFieldCode object, the following arguments are optional:

• ImagingProfiles field - a list of ImagingProfileRef objects, List<ImagingProfileRef>. These objects may be linked to the field code.
• RelativityField field - a FieldRef links a Relativity field to a field code used in a Microsoft application.

var appFieldCode = new ApplicationFieldCode() {
    Name = "Test 2",
    FieldCode = "[Date]",
    Option = ApplicationFieldCodeOption.DocumentDefault,
    Application = ApplicationType.MicrosoftWord,
    ImagingProfiles = new List<ImagingProfileRef> { },
    RelativityField = new FieldRef(123456)
}

In addition, you can optionally set the ApplicationFieldCodes property on an ImagingProfile object used for basic or native imaging. When creating a list of ApplicationFieldCodeRef objects, you only need to set the ArtifactID property. The Name property isn't required. See the following code sample:

exampleImagingProfile.ApplicationFieldCodes = new List<ApplicationFieldCodeRef> {
  new ApplicationFieldCodeRef
  {
    ArtifactID = fieldCode.ArtifactID,
    Name = fieldCode.Name
  }
};

Native types

You can optionally set the NativeTypes property on an ImagingProfile object used for basic or native imaging. If you don't set this property, Relativity uses the default restricted native types. For more information about restricted types, see Imaging native types on the Relativity Server2021 Documentation site.

Imaging sets

When you construct an imaging set, the EmailNotificationRecipients property is optional. You can set it to an empty string. For more information, see Imaging Set Manager

The following code sample illustrates how to construct an ImagingSet object:

var imagingSet =  new ImagingSet {
  DataSource = aSavedSearchId,
  Name = "Test imaging set",
  ImagingProfile = new ImagingProfileRef
  {
    ArtifactID = anImagingProfileId
  },
  EmailNotificationRecipients = ""
};

Imaging Profile Manager

An imaging profile defines a set of options that you want to use when imaging a group of documents. It may include options for controlling how spreadsheets, emails, or other document types are imaged, such as page orientation, or other specialized settings. The Imaging Profile Manager service provides CRUD support for ImagingProfile objects. For general information, see Imaging profiles on the RelativityServer2021 Documentation site.

Creating or updating an imaging profile

You can use the SaveAsync() method to create or update an ImagingProfile object. For an update operation, you must provide the Artifact ID of the ImagingProfile object that you want to modify. For information about constructing this object type, see Imaging Profiles.

The following code sample illustrates how to call the SaveAsync() method with an ImageProfile object and the Artifact ID of the Workspace object associate with it.

public static async Task<int> DemonstrateSave(IServicesMgr servicesManager, IAPILog logger, ImagingProfile sampleImagingProfile, int sampleWorkspaceId)
{
    // Get the ImagingProfileManager from the IServicesMgr instance for the current user.
    using (IImagingProfileManager imagingProfileManager = servicesManager.CreateProxy<IImagingProfileManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            // Save the ImagingProfile. Successful saves returns the ArtifactID of the ImagingProfile.
            int result = await imagingProfileManager.SaveAsync(sampleImagingProfile, sampleWorkspaceId);
            logger.LogInformation("Imaging Profile saved with Artifact ID {0}.", result);
            logger.LogInformation("Done Saving.");
            return result;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError($"Could not save imaging profile in workspace {sampleWorkspaceId}: ", ex);
            throw;
        }
    }
}

Retrieving an imaging profile

You can use the ReadAsync() method to retrieve an ImagingProfile object. The following code samples illustrate the properties set on an ImagingProfile object for basic and native imaging jobs. For information about these properties, see Imaging APIon the Relativity API reference page.

Deleting an imaging profile

You can remove an ImagingProfile object from Relativity by calling the DeleteAsync() method. Pass this method the Artifact ID of the ImagingProfile object, and of the Workspace object associated with it. See the following code sample:

public static async Task DemonstrateDelete(IServicesMgr servicesManager, IAPILog logger, int sampleImagingProfileId, int sampleWorkspaceId)
{
    bool success = false;
    logger.LogInformation("Deleting Imaging Profile...");

    // Get the ImagingProfileManager from the IServicesMgr instance for the current user.
    using (IImagingProfileManager imagingProfileManager = servicesManager.CreateProxy<IImagingProfileManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Delete an ImagingProfile by artifactId and workspaceId.
            await imagingProfileManager.DeleteAsync(sampleImagingProfileId, sampleWorkspaceId);
            success = true;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError(ex, $"Could not delete {sampleImagingProfileId} from workspace {sampleWorkspaceId}: {ex.Message}");
            throw;
        }
    }

    if (success)
    {
        logger.LogInformation("Deleted successfully.");
    }
    else
    {
        logger.LogInformation("Delete failed.");
    }
}

Imaging Set Manager

To running an imaging job, you need to create an imaging set, which consists of an imaging profile and a search containing the documents to image. The Imaging Set Manager service provides CRUD support for ImagingSet objects. In addition, it also provides methods for hiding images undergoing a quality control review, and then releasing them to reviewers. For general information, see Imaging sets and QC Review on the RelativityServer2021 Documentation site.

Create or update an imaging set

You can use the SaveAsync() method for creating and updating an ImagingSet object. For an update operation, you must provide the Artifact ID of the ImagingSet object that you want to modify. For information about constructing this object type, see Imaging sets.

The following code sample illustrates how to call the SaveAsync() method with an ImageSet object and the Artifact ID of the Workspace object associate with it.

public static async Task<int> DemonstrateSave(IServicesMgr servicesManager, IAPILog logger, ImagingSet sampleImagingSet, int sampleWorkspaceId)
{
    logger.LogInformation("Saving sample Imaging Set...");

    // Get the ImagingSetManager from the IServicesMgr instance for the current user.
    using (IImagingSetManager imagingSetManager = servicesManager.CreateProxy<IImagingSetManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            // Save the ImagingSet. Successful saves return the ArtifactID of the ImagingSet.
            int result = await imagingSetManager.SaveAsync(sampleImagingSet, sampleWorkspaceId);
            logger.LogInformation("Imaging Set saved with Artifact ID {0}.", result);
            logger.LogInformation("Done Saving.");
            return result;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError($"Could not save imaging set in workspace {sampleWorkspaceId}: ", ex);
            throw;
        }
    }
}

Retrieving an imaging set

You can use the ReadAsync() method to retrieve an ImagingSet object. The following code sample illustrates the properties on this object that you can read. For information about these properties, see Imaging APIon the Relativity API reference page.

public static async Task<ImagingSet> DemonstrateRead(IServicesMgr servicesManager, IAPILog logger, int sampleImagingSetId, int sampleWorkspaceId)
{
    // Get the ImagingSetManager from the IServicesMgr instance for the current user.
    using (IImagingSetManager imagingSetManager = servicesManager.CreateProxy<IImagingSetManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Read an ImagingSet by artifactId and workspaceId.
            logger.LogInformation("Reading updated Imaging Set...");
            ImagingSet imagingSet = await imagingSetManager.ReadAsync(sampleImagingSetId, sampleWorkspaceId);

            logger.LogInformation("Name        : {0}", imagingSet.Name);
            logger.LogInformation("ImagingProfile Name        : {0}", imagingSet.ImagingProfile.Name);
            logger.LogInformation("DataSource ArtifactId        : {0}", imagingSet.DataSource);

            return imagingSet;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError(ex, $"Could not read {sampleImagingSetId} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }

Deleting an imaging set

You can remove an ImagingSet object from Relativity by calling the DeleteAsync() method. Pass this method the Artifact ID of the ImagingSet object, and of the Workspace object associated with it. See the following code sample:

public static async Task DemonstrateDelete(IServicesMgr servicesManager, IAPILog logger, int sampleImagingSetId, int sampleWorkspaceId)
{
    logger.LogInformation($"Deleting Imaging Set {sampleImagingSetId}");

    bool success = false;
    // Get the ImagingSetManager from the IServicesMgr instance for the current user.
    using (IImagingSetManager imagingSetManager = servicesManager.CreateProxy<IImagingSetManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Delete the Imaging Set.
            await imagingSetManager.DeleteAsync(sampleImagingSetId, sampleWorkspaceId);
            success = true;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError(ex, $"Could not delete {sampleImagingSetId} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }

    if (success)
    {
        logger.LogInformation("Deleted successfully.");
    }
    else
    {
        logger.LogInformation("Delete failed.");
    }
}

Hiding an imaging set

During a quality control review, you may want to prevent reviewers from accessing images. The Imaging Set Manager service supports the HideImagingSetAsync() method, which you can use to hide images in a specific imaging set. This method takes an ImagingSet object as one of its arguments. You need to construct this object manually, as illustrated in the following code sample:

ImagingSet setRef = new ImagingSet {
    ArtifactID = updatedimagingSetId,
    Name = imagingSet.Name
};

You can then call the HideImagingSetAsync() method by passing the Artifact ID of the new ImagingSet object and of its associated Workspace object.

public static async Task<bool> DemonstrateHide(IServicesMgr servicesManager, IAPILog logger, ImagingSet imagingSet, int sampleWorkspaceId)
{
    // Make sure the job is finished before calling HideImagingSetAsync() method.
    logger.LogInformation("Waiting for imaging job to complete...");
    ImagingTestHelpers.WaitForSetStatusAsync(servicesManager, imagingSet.ArtifactID, sampleWorkspaceId, ImagingTestHelpers.COMPLETE_STATUS).GetAwaiter().GetResult();
    logger.LogInformation("Imaging Complete");

    bool success = false;
    // Get the ImagingSetManager from the IServicesMgr instance for the current user.
    using (IImagingSetManager imagingSetManager = servicesManager.CreateProxy<IImagingSetManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            logger.LogInformation("Hiding images from users until QC is complete...");
            //Hide images from users until QC Review for them is complete.
            await imagingSetManager.HideImagingSetAsync(imagingSet, sampleWorkspaceId).ConfigureAwait(false);
            success = true;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError(ex, $"Could not hide qc fields for docs in imaging set {imagingSet.Name} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }
    return success;
}

Releasing an imaging set

After completing a quality control review, you can make the imaging set accessible to reviewers by releasing it. The Imaging Set Manager service supports the ReleaseImagingSetAsync() method for this purpose. Similar to the HideImagingSetAsync() method, you must also manually construct a ImagingSet object. You can then call this method by passing the Artifact ID of the new ImagingSet object and of the Workspace object associated with it.

public static async Task<bool> DemonstrateRelease(IServicesMgr servicesManager, IAPILog logger, ImagingSet imagingSet, int sampleWorkspaceId)
{
    bool success = true;
    // Get the ImagingSetManager from the IServicesMgr instance for the current user.
    using (IImagingSetManager imagingSetManager = servicesManager.CreateProxy<IImagingSetManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Release images to users after the QC Review is complete.
            await imagingSetManager.ReleaseImagingSetAsync(imagingSet, sampleWorkspaceId);
            success = true;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging and rethrows the exception.
            logger.LogError(ex, $"Could not release qc fields for docs in imaging set {imagingSet.Name} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }
    return success;
}

Native Type Manager

The Native Type Manager service supports the read method on native file types. The NativeType class represents a native file type in Relativity, which you can retrieve. For general information, see Imaging native types on the Relativity Server2021 Documentation site.

Retrieving a native type

The following code sample illustrates the properties on a NativeType object that you can read. For information about these properties, see Imaging API on the Relativity API reference page.

public static async Task<NativeType> DemonstrateRead(IServicesMgr servicesManager, IAPILog logger, int sampleNativeTypeId, int sampleWorkspaceId)
{
    // Get the ApplicationFieldCodeManager from the IServicesMgr instance for the current user
    using (INativeTypeManager nativeTypeManager = servicesManager.CreateProxy<INativeTypeManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            // read a NativeType by artifactId and workspaceId
            logger.LogInformation("Reading Native Type...");
            NativeType nativeType = await nativeTypeManager.ReadAsync(sampleNativeTypeId, sampleWorkspaceId);
            logger.LogInformation("Name        : {0}", nativeType.ArtifactID);
            logger.LogInformation("Name        : {0}", nativeType.BasicCategory);
            logger.LogInformation("Name        : {0}", nativeType.FileTypeId);
            logger.LogInformation("Name        : {0}", nativeType.Name);
            logger.LogInformation("Name        : {0}", nativeType.NativeCategory);
            logger.LogInformation("Name        : {0}", nativeType.PreventNativeDownload);
            logger.LogInformation("Name        : {0}", nativeType.RestrictedFromImagingByDefault);
            logger.LogInformation("Name        : {0}", nativeType.UseNativeImaging);
            logger.LogInformation("Done reading.");

            return nativeType;
        }
        catch(ServiceException ex)
        {
            //The service throws an exception of type ServiceException, log and rethrow
            logger.LogError(ex, $"Could not read {sampleNativeTypeId} from workspace {sampleWorkspaceId}: {ex.Message}");
            throw;
        }
    }
}

Application Field Code Manager

Microsoft applications use fields codes as placeholders for data that may be updated or used for other specialized purposes in their documents, such as those created in Word, Excel, or others. In Relativity, application field codes indicate how to handle field codes used in Microsoft documents during imaging. The Application Field Code Manager service provides CRUD support for ApplicationFieldCode objects. For general information, see Application Field Codes on the Relativity Server2021 Documentation site.

Creating or updating an application field code

The Application Field Code Manager service includes the SaveAsync() method for creating and updating an ApplicationFieldCode object. For an update operation, you must provide the Artifact ID of the ApplicationFieldCode object that you want to modify. For information about constructing this object type, see Application field codes.

The following code sample illustrates how to call this method.

public static async Task<int> DemonstrateSave(IServicesMgr servicesManager, IAPILog logger, ApplicationFieldCode sampleFieldCode, int sampleWorkspaceId)
{
    logger.LogInformation("Saving sample Application Field Code...");
    // Get the ApplicationFieldCodeManager from the IServicesMgr instance for the current user.
    using (IApplicationFieldCodeManager applicationFieldCodeManager = servicesManager.CreateProxy<IApplicationFieldCodeManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            // Save the ApplicationFieldCode. Successful saves return the ArtifactID of the ApplicationFieldCode.
            int result = await applicationFieldCodeManager.SaveAsync(sampleFieldCode, sampleWorkspaceId);
            logger.LogInformation("Field code saved with Artifact ID {0}.", result);
            logger.LogInformation("Done Saving.");
            return result;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging, and rethrows the exception.
            logger.LogError($"Could not save application field code in workspace {sampleWorkspaceId}: ", ex);
            throw;
        }
    };
}

Retrieving an application field code

You can use the ReadAsync() method to retrieve an ApplicationFieldCode object. The following code sample illustrates the properties on this object that you can read. For information about these properties, see Imaging APIon the Relativity API reference page.

public static async Task<ApplicationFieldCode> DemonstrateRead(IServicesMgr servicesManager, IAPILog logger, int sampleFieldCodeId, int sampleWorkspaceId)
{
    // Get the ApplicationFieldCodeManager from the IServicesMgr instance for the current user.
    using (IApplicationFieldCodeManager applicationFieldCodeManager = servicesManager.CreateProxy<IApplicationFieldCodeManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Read an ApplicationFieldCode by artifactId and workspaceId.

            ApplicationFieldCode fieldCode = await applicationFieldCodeManager.ReadAsync(sampleFieldCodeId, sampleWorkspaceId);

    logger.LogInformation("Reading Application Field Code...");
    logger.LogInformation("Name        : {0}", fieldCode.Name);
            logger.LogInformation("FieldCode   : {0}", fieldCode.FieldCode);
            logger.LogInformation("Option      : {0}", fieldCode.Option);
            logger.LogInformation("Application : {0}", fieldCode.Application);
            logger.LogInformation("Done reading.");

            return fieldCode;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging, and rethrows the exception.
            logger.LogError(ex, $"Could not read {sampleFieldCodeId} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }
}

Deleting an application field code

To remove an ApplicationFieldCode object from Relativity, you call the DeleteAsync() method. Pass this method the Artifact ID of the ApplicationFieldCode object, and of the Workspace object associated with it. See the following code sample:

public static async Task DemonstrateDelete(IServicesMgr servicesManager, IAPILog logger, int sampleFieldCodeId, int sampleWorkspaceId)
{
    logger.LogInformation("Deleting Application Field Code...");
    bool success = false;
    // Get the ApplicationFieldCodeManager from the IServicesMgr instance for the current user
    using (IApplicationFieldCodeManager applicationFieldCodeManager = servicesManager.CreateProxy<IApplicationFieldCodeManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Delete an ApplicationFieldCode passing an artifactId and workspaceId into the method.
            success = await applicationFieldCodeManager.DeleteAsync(sampleFieldCodeId, sampleWorkspaceId);
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, log and rethrow
            logger.LogError(ex, $"Could not delete {sampleFieldCodeId} from workspace {sampleWorkspaceId}: ");
            throw;
        }
    }

    if (success)
    {
        logger.LogInformation("Deleted successfully.");
    }
    else
    {
        logger.LogInformation("Delete failed.");
    }
}

Imaging Job Manager

The Imaging Job Manager service supports running image set jobs, canceling them, and retrying them. For general information, see Running an imaging set and Imaging errors on the Relativity Server2021 Documentation site.

Run an imaging set job

Before running a job, you need to construct an ImagingJob instance by setting its properties with the Artifact ID of the ImagingSet and Workspace objects. The QcEnabled property is an optional argument when constructing a new ImagingJob. If you don't specify it on the initial run of an imaging set, then it defaults to false. On subsequent runs, it defaults to the value used for the previous run. See the following code sample:

var imagingJob = new ImagingJob
{
  ImagingSetId = anImagingSetId,
  WorkspaceId = workspaceId,
  QcEnabled = false
};

To run an imaging set job, you call the RunImagingSetAsync() method by passing an ImagingJob object, as illustrated in the following code sample.

Note: To an cancel imaging set job, use the StopImagingJobAsync() method.

public static async Task<Guid> DemonstrateRun(IServicesMgr servicesManager, IAPILog logger, ImagingJob imagingJob)
{
    // Get the imagingJobManager from the IServicesMgr instance for the current user.
    using (IImagingJobManager imagingJobManager = servicesManager.CreateProxy<IImagingJobManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            //Run an ImagingSet job.
            logger.LogInformation("Running Imaging Job for Imaging Set {0}...", imagingJob.ImagingSetId);
            Guid jobGuid = (await imagingJobManager.RunImagingSetAsync(imagingJob)).ImagingJobId;
            logger.LogInformation("Imaging Job with Guid {0} started", jobGuid.ToString());
            return jobGuid;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging, and rethrows the exception.
            logger.LogError(ex, $"Could not run job for Imaging Set {imagingJob.ImagingSetId} from workspace {imagingJob.WorkspaceId}");
            throw;
        }
    }
}

Image a single document

You can use the ImageDocumentAsync() method to image a single document rather than a group of them belonging to an imaging set. You can also image a native file stored in Relativity or specify an alternative native file by providing a file path for it.

Cancel imaging jobs

You can cancel imaging jobs by calling the StopImagingJobAsync() method. The StopImagingJobAsync() method cancels any type of imaging job, including imaging set jobs, or jobs for imaging on the fly.

Cancel an imaging job

To cancel any type of imaging job, pass a StopImagingJobRequest object to the StopImagingJobAsync() method as illustrated in the following code. This method returns an StopImagingJobResponse object, which has a Success property that is set to true when the job is canceled without errors.

public static async Task<bool> DemonstrateStopImagingJob(IServicesMgr servicesManager, IAPILog logger, StopImagingJobRequest stopImagingJobRequest)
{
    // Get the IImagingJobManager from the IServicesMgr instance for the current user
    using (IImagingJobManager imagingJobManager = servicesManager.CreateProxy<IImagingJobManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            logger.LogInformation($"Stopping imaging job {stopImagingJobRequest.ImagingJobId} in workspace {stopImagingJobRequest.WorkspaceArtifactId}...");

            StopImagingJobResponse stopImagingJobResponse = await imagingJobManager.StopImagingJobAsync(stopImagingJobRequest).ConfigureAwait(false);

            logger.LogInformation($"Stopping imaging job returned value: {stopImagingJobResponse.Success}");
            return stopImagingJobResponse.Success;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, log and return failure.
            logger.LogError(ex, $"Could not stop imaging job {stopImagingJobRequest.ImagingJobId} from workspace {stopImagingJobRequest.WorkspaceArtifactId}");
            
            // Return false since the request to stop could not be submitted successfully.
            return false;
        }
    }
}

Retry an imaging set job with errors

You can retry a imaging job by passing an ImagingJob object to RetryImagingSetErrorsAsync() method as illustrated in the following code sample:

public static async Task<Guid> DemonstrateRetryErrors(IServicesMgr servicesManager, IAPILog logger, ImagingJob imagingJob)
{
    // Wait until the job has stopped.
    ImagingTestHelpers.WaitForSetStatusAsync(servicesManager, imagingJob.ImagingSetId, imagingJob.WorkspaceId, ImagingTestHelpers.STOP_STATUS).GetAwaiter().GetResult();
    logger.LogInformation("Imaging job stopped. Re-starting.");

    // Get the imagingJobManager from the IServicesMgr instance for the current user.
    using (IImagingJobManager imagingJobManager = servicesManager.CreateProxy<IImagingJobManager>(ExecutionIdentity.CurrentUser))
    {
        try
        {
            logger.LogInformation("Retrying Imaging Job for Imaging Set {0}...", imagingJob.ImagingSetId);
            Guid jobGuid = (await imagingJobManager.RetryImagingSetErrorsAsync(imagingJob)).ImagingJobId;
            logger.LogInformation("Imaging Job with Guid {0} will be retried", jobGuid.ToString());
            return jobGuid;
        }
        catch (ServiceException ex)
        {
            //The service throws an exception of type ServiceException, performs logging, and rethrows the exception.
            logger.LogError(ex, $"Could not retry job for Imaging Set {imagingJob.ImagingSetId} from workspace {imagingJob.WorkspaceId}");
            throw;
        }
    }
}

Update the priority of an imaging job

(Available in Relativity 10.2.270.1 and above)

You can modify the priority assigned to an imaging job by passing an UpdateJobPriorityRequest object to the UpdateJobPriorityAsync() method. Before running the update job, you need to construct an UpdateJobPriorityRequest instance by setting the following properties:

• JobGuid - the GUID for the imaging job.
• Priority - an integer value representing the new priority to assign to the job.
• WorkspaceId - an integer representing the Artifact ID of the workspace containing the imaging job.
• OriginationId - an optional identifier for internal use only.

See this code sample showing how to instantiate a request object:

  var updateJobPriorityRequest = new UpdateJobPriorityRequest
  {
   JobGuid = aJobGuid,
   Priority = priority,
   WorkspaceId = workspaceId
  };

The following code sample illustrates how to call the UpdateJobPriorityAsync() method by passing the request object to it:

public static async Task<UpdateJobPriorityResponse> DemonstrateUpdateJobPriority(IServicesMgr servicesManager, IAPILog logger, UpdateJobPriorityRequest updateJobPriorityRequest)
{
       // Get the IImagingJobManager from the IServicesMgr instance for the current user
       using (IImagingJobManager imagingJobManager = servicesManager.CreateProxy<IImagingJobManager>(ExecutionIdentity.CurrentUser))
       {
               try
               {
                      logger.LogInformation($"Update priority for imaging job {updateJobPriorityRequest.JobGuid} in workspace {updateJobPriorityRequest.WorkspaceId}...");

                      UpdateJobPriorityResponse updateJobPriorityResponse = await imagingJobManager.UpdateJobPriorityAsync(updateJobPriorityRequest).ConfigureAwait(false);

                      logger.LogInformation($"Update priority of imaging job returned isJobSuccess: {updateJobPriorityResponse.Success} and Error Message: {updateJobPriorityResponse.ErrorMessage}");
                       return updateJobPriorityResponse;
               }
               catch (ServiceException ex)
               {
                      //The service throws an exception of type ServiceException, log and re-throw.
                      logger.LogError(ex, $"Could not update priority for imaging job {updateJobPriorityRequest.JobGuid} from workspace {updateJobPriorityRequest.WorkspaceId}");
                      throw;
               }
       }
}