Open topic with navigation



Imaging API (REST)

The Imaging API provides multiple HTTP services used for programmatically interacting with imaging profiles, sets, jobs, and other related components through Representational State Transfer (REST). The REST endpoints on the imaging job service support running and canceling jobs, updating priorities on jobs, and retrying jobs with errors. Endpoints on 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 an endpoint 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.

Additionally, you can also access the Imaging API services through .NET interfaces. These interfaces support the same functionality as available through REST. For more information, see Imaging (.NET).

This page contains the following information:

See this related page:

Client code sample

You can use the .NET code samples provided in this section as a REST client for interacting with the imaging services. The URLs for the imaging services have the following general format:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/[Name of Object] Service\[Function name]

To interact with an endpoint on one of the imaging services, send an HTTP request that makes a POST method call. See the following base URLs for each of the services:

  • Imaging Profile Manager service
    <host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/
  • Imaging Set Manager service
    <host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/
  • Imaging Job Manager service
    <host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/
  • Native Type Manager service
    <host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Native Type Service/
  • Application Field Code Manager service
    <host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/

The following code sample illustrates how to set up the HttpClient object to make REST calls. The baseUri parameter uses the format: https://<Your-Relativity-Instance.com>/Relativity.REST/api/.

public static HttpClient GetHttpClient(string baseUri, string username, string password)
{
    HttpClient httpClient = new HttpClient();
    httpClient.BaseAddress = new Uri(baseUri);
    
    //Encode authorization for the header based on username and password.
    string usernamePassword = string.Format("{0}:{1}", username, password);
    string base64usernamePassword = Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));
    httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
    httpClient.DefaultRequestHeaders.Add("Authorization", "Basic " + base64usernamePassword);
    return httpClient;
}

You can use the method in the next code sample to return a response. It takes the following parameters:

  • httpClient - You can also specify the base address of HttpClient instance as the root URL, such as https://<Your-Relativity-Instance.com>/. For example, you could then pass in the following sample URL to the POST request: 
    Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/ReadAsync
  • jsonToPost - The JSON uses the formats found in the following sections on this page. For example, see the format used for the read endpoint in Retrieving an imaging profile.
  • url - You can pass in an endpoint for a service as follows:
    Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/ReadAsync

See the following code sample:

public static async Task<string> GetJsonResponse(HttpClient httpClient, string jsonToPost, string url)
{
  StringContent content = new StringContent(jsonToPost, Encoding.UTF8, "application/json");
  //All REST API methods use POST.
  HttpResponseMessage response = await httpClient.PostAsync(url, content);
  return await response.Content.ReadAsStringAsync();
}

Guidelines for imaging through REST

While the arguments for passing in JSON are case insensitive, we recommend that you follow capitalization rules used for reading requests and representing objects provided in the following code samples. For example, the SaveAsync methods on the imaging services takes the imagingObject and workspaceId parameters. This JSON sample illustrates the suggested construction of an object:

{
   "imagingObject":{
    "ObjectProperty1":      ...
    "ObjectProperty2":{
         "PropertyOfObjectProperty2":...
      }      ...
   },
   "workspaceId":123456
}

Imaging profiles

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. For more information, see Imaging profiles on the RelativityOne Documentation site.

Create or update an imaging profile

You can create imaging profiles by using options available on basic imaging engine or on the native imaging engine. Review the following guidelines for imaging profiles before creating these objects:

  • When you save an Imaging Profile, Relativity automatically uses "0" for some optional Artifact ID references. Consider reconstructing an object after examination. For example, the TimeZoneFieldOnDocument field is optional, but Relativity sets the ArtifactID = 0.
  • Use the SaveAsync endpoint for both creating and updating an imaging profile. The JSON for the requests contain the same fields, except you must provide the Artifact ID of the profile when you want to execute an update operation.
  • For native imaging, the ImagingProfile object must include the NativeImagingEngineOptions, EmailOptions, HtmlOptions, PresentationOptions, SpreadsheetOptions, and WordProcessingOptions objects. However, some of the fields on these objects are optional, including nullable fields, the TimeZoneFieldOnDocument field, and the NativeImagingEngineOptions field. Verify you must meet any constraints and dependencies on these fields as described in Imaging profiles.
  • During an update operation, if you enter an invalid Artifact ID, Relativity returns an error message when it can't find an imaging profile with that identifier.

To create or update an imaging profile, send a request to the SaveAsync endpoint with this URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/SaveAsync
ClosedView field descriptions for a basic imaging profile request

For convenience, the following list contains brief descriptions of fields used for a basic imaging profile. You can find detailed information about how to set these fields in Imaging profiles on the RelativityOne Documentation site.

In the JSON request, the following fields are required unless specifically identified as optional:

  • imagingProfile - contains the settings specified for an imaging job. The following list contains a subset of fields available on an ImagingProfile object:
    • ImagingMethod - the method used for running the imaging profile. For basic imaging, only a limited number of imaging options are available.
    • BasicOptions - the settings for a basic imaging job include the output quality (DPI), the image format as a JPEG or TIFF, and image size settings.
      • BasicImageFormat - the basic image format, such as JPEG or TIFF.
      • ImageOutputDpi - the image output quality (DPI).
      • ImageSize - the basic image size, such as original setting, letter, A4, or legal.
    • NativeTypes - an array of native types associated with the imaging profile. This field is optional. If you don't set this field, Relativity uses the default restricted native types. For more information, see Imaging native types on the RelativityOne Documentation site.
    • ApplicationFieldCodes - an array of fields used by Microsoft documents to store data. This field is optional. For more information, see Application Field Codes on the RelativityOne Documentation site.
    • ArtifactId - the Artifact ID of the imaging profile that you want to update. This field is required only for updating an imaging set.
    • Name - the user-friendly name for the imaging profile.
    • Notes - a description or other information about the imaging profile.
    • Keywords - words or concise phrase used to describe the imaging profile.
  • workspaceId - the Artifact ID of the workspace where you want to create the imaging profile.
ClosedView sample JSON for a basic imaging profile request

The following sample illustrates the JSON for creating a basic imaging profile. The JSON for updating a basic imaging profile includes the ArtifactId field in addition to the fields listed in this sample.

{
   "imagingProfile":{
      "ImagingMethod":"Basic",
      "BasicOptions":{
         "ImageOutputDpi":300,
         "BasicImageFormat":"Tiff",
         "ImageSize":"OriginalSetting"
      },
      "NativeTypes":[
      ],
      "ApplicationFieldCodes":[
      ],
      "Name":"Test Rest ImagingProfile"
   },
   "workspaceId":1017048
}
ClosedView field descriptions for a native imaging profile request

For convenience, the following list contains brief descriptions of fields used for a native imaging profile. You can find detailed information about how to set these fields in Imaging profiles on the RelativityOne Documentation site.

Note: For native imaging, the ImagingProfile object must include the NativeImagingEngineOptions, EmailOptions, HtmlOptions, PresentationOptions, SpreadsheetOptions, and WordProcessingOptions objects. However, some of the fields on these objects are optional, including nullable fields, the TimeZoneFieldOnDocument field, and the NativeImagingEngineOptions field. Verify you must meet any constraints and dependencies on these fields as described in Imaging profiles.

In the JSON request, the following fields are required unless specifically identified as optional:

  • imagingProfile - contains settings specified for an imaging job. The following list contains fields available on an ImagingProfile object:
    • ImagingMethod - the method used for running the imaging profile. You can set specific options for native imaging, as well as for spreadsheets, emails, and other document types.
    • BasicOptions - the group of basic image settings for this imaging profile as follows:
      • BasicImageFormat - the basic image format, such as a JPEG or TIFF.
      • ImageOutputDpi - the image output quality (DPI).
      • ImageSize - the basic image size, such as original setting, letter, A4, or legal.
      • MaximumImageHeight - the maximum of height of custom images in inches for the imaging profile.
      • MaximumImageWidth - the maximum width of custom images in inches for the imaging profile.
    • NativeOptions - the group of native image settings for this imaging profile as follows:
      • ImageOutputDpi - the resolution and density of an image in dots per inch (DPI). This field is optional.
      • LastModifiedDateOnDocument - the field on a document that stores the last modified date. This field is optional.
      • MaxPagesPerDoc - the maximum number of document pages imaged per file. This field is optional.
      • NativeImageFormat - the image format for files sent to the native imaging engine. The supported formats include JPEG or TIFF.
      • TimeZoneFieldOnDocument - the date and time information in a document image, which corresponds to the field on a document that stores the time zone. This field is optional.
    • SpreadsheetOptions - the settings used for imaging spreadsheets. The following fields are required only for spreadsheets unless specifically identified as optional:
      • PaperSizeOrientation - the paper size and orientation used to render the pages in a spreadsheet.
      • PageOrder - the order used to render the pages in a spreadsheet, such as vertical or horizontal overflow.
      • PrintArea - the print area in a spreadsheet used for an imaging job.
      • HideAndPagebreakAfterConsecutiveBlankRowCol - the option controlling the maximum number of consecutive blank rows or columns.
      • ShowTrackChanges - a Boolean value indicating whether to display modifications made through the Track Changes option in Excel.
      • IncludeRowAndColumnHeadings - indicates whether to render row headings (1, 2, 3, etc.) and column headings (A, B, C, etc.) in a spreadsheet.
      • IncludeHeadersAndFooters - indicates whether to render headers and footers in the spreadsheet.
      • IncludeComments - a Boolean value indicating whether to render comments added to a spreadsheet.
      • IncludeGridlines - indicates whether to render the grid lines between rows and columns in the spreadsheet.
      • IncludeBorders - a Boolean value indicating whether to render the borders in a spreadsheet.
      • UnhideHiddenWorksheets - a Boolean value indicating whether to display hidden worksheets.
      • LimitToPages - controls the number of pages to render. This field is optional.
      • FitToPagesWide - resets the page width for a spreadsheet. This field is optional.
      • FitToPagesTall - resets the page height for a spreadsheet. This field is optional.
      • Formatting - indicates how to format a spreadsheet, such as auto-fit rows and columns, and clearing empty rows and columns. This field is optional.
      • TextVisibility - indicates how to handle text visibility by controlling background and font color.
    • EmailOptions - the settings used for imaging email messages. The following fields are required only for email messages:
      • Orientation - indicates whether the orientation of email messages is portrait or landscape.
      • ResizeImagesToFitPage - a Boolean value indicating whether to modify images to fit the page size.
      • ResizeTablesToFitPage - a Boolean value indicating whether to modify tables to fit the page size.
      • DownloadImagesFromInternet - a Boolean value indicating whether to allow downloading images from the Internet.
      • ClearIndentations - a Boolean value indicating whether tabs are removed from the display of email threads.
      • DisplaySmtpAddresses - a Boolean value indicating whether to display SMTP addresses in the UI.
      • ShowMessageTypeInHeader - a Boolean value indicating whether to identify the image as a message, appointment, distribution list, or other entity.
    • WordProcessingOptions - the settings used for imaging documents formatted with word processing options, such Microsoft Word. The following fields are required only for word processing files:
      • ShowTrackChanges - a Boolean value indicating whether to display any markup added to the document through the Track Changes feature in Microsoft Word.
      • PageOrientation - the word processing option for page orientation, such portrait, landscape, or original orientation.
    • PresentationOptions - the settings used for imaging documents from presentation software, such as Microsoft PowerPoint. The following fields are required only for presentations:
      • ShowSpeakerNotes - a Boolean value indicating whether to display the speaker’s notes at the bottom of presentation slides.
      • SlideOrientation - the orientation of presentation slides, such as landscape, portrait, or original setting.
    • HtmlOptions - the setting used for imaging HTML documents. This field is required only for HTML documents:
      • RemoveNonBreakingSpaceCodes - a Boolean value indicating whether to remove non-breaking spaces (NBSP).
    • ArtifactId - the Artifact ID of the imaging profile that you want to update. This field is required only for updating an imaging profile.
    • NativeTypes - an array of native types associated with the imaging profile. This field is optional. If you don't set this field, Relativity uses the default restricted native types. For more information, see Imaging native types on the RelativityOne Documentation site.
    • ApplicationFieldCodes - an array of fields used by Microsoft documents to store data. This field is optional. For more information, see Application Field Codes on the RelativityOne Documentation site.
    • Notes - a description or other information about the imaging profile.
    • Keywords - words or concise phrase used to describe the imaging profile.
    • Name - the user-friendly name for an imaging profile.
  • workspaceId - the Artifact ID of the workspace where you want to create or update an imaging profile.
ClosedView a JSON sample for a native imaging profile request

The following sample illustrates the JSON for creating a native imaging profile. The JSON for updating a native imaging profile includes the ArtifactId field in addition to the fields listed in this sample.

{
   "imagingProfile":{
      "ImagingMethod":"Native",
      "BasicOptions":{
         "ImageOutputDpi":100,
         "BasicImageFormat":"Tiff",
         "ImageSize":"OriginalSetting"
      },
      "NativeOptions":{
         "ImageOutputDpi":100,
         "NativeImageFormat":"Jpeg",
         "MaxPagesPerDoc":10
      },
      "SpreadsheetOptions":{
         "PaperSizeOrientation":"OriginalSetting",
         "PageOrder":"OriginalSetting",
         "PrintArea":"OriginalSetting",
         "HideAndPagebreakAfterConsecutiveBlankRowCol":50,
         "ShowTrackChanges":false,
         "IncludeRowAndColumnHeadings":"OriginalSetting",
         "IncludeHeadersAndFooters":"OriginalSetting",
         "IncludeComments":false,
         "IncludeGridlines":"OriginalSetting",
         "IncludeBorders":false,
         "UnhideHiddenWorksheets":false,
         "LimitToPages":9,
         "FitToPagesWide":1,
         "FitToPagesTall":1,
         "Formatting":[
            "AutoFitColumns"
         ],
         "TextVisibility":[
            "RemoveBackgroundFillColors"
         ]
      },
      "EmailOptions":{
         "Orientation":"Portrait",
         "ResizeImagesToFitPage":false,
         "ResizeTablesToFitPage":false,
         "DownloadImagesFromInternet":false,
         "ClearIndentations":false,
         "DisplaySmtpAddresses":false,
         "ShowMessageTypeInHeader":false
      },
      "WordProcessingOptions":{
         "ShowTrackChanges":false,
         "PageOrientation":"OriginalSetting"
      },
      "PresentationOptions":{
         "ShowSpeakerNotes":false,
         "SlideOrientation":"Portrait"
      },
      "HtmlOptions":{
         "RemoveNonBreakingSpaceCodes":false
      },
      "Name":"Updated Imaging Profile"
   },
   "workspaceId":1017048
}

When an imaging profile is successfully created or updated, the JSON response contains its Artifact ID, such as 1038842.

Retrieve an imaging profile

Use the ReadAsync endpoint to retrieve an imaging profile. Send a request to the following URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/ReadAsync

The request must contain the following fields:

  • imagingProfileId - the Artifact ID of the imaging profile that you want to retrieve.
  • workspaceID - the Artifact ID of the workspace that contains the imaging profile.
{
   "imagingProfileId":1038583,
   "workspaceID":1017048
}

The response contains the following fields:

  • Miscellaneous fields - the various fields set on an imaging profile. For more information, see the field descriptions in Creating or updating an imaging profile.
  • LastModifiedDateOnDocument - the document-level date field used to display date-related document field codes. This value defaults to the current date if it wasn't set in the imaging profile. For more information, see the Native Image Date option in Imaging profiles on the RelativityOne Documentation site.
  • ArtifactID - the Artifact ID of the imaging profile that you have retrieved.
  • Name - the user-friendly name of the imaging profile.
ClosedView JSON request for retrieving an imaging profile 
{
   "ImagingMethod":"Basic",
   "BasicOptions":{
      "ImageOutputDpi":300,
      "BasicImageFormat":"Tiff",
      "ImageSize":"OriginalSetting"
   },
   "NativeOptions":{
      "ImageOutputDpi":0,
      "NativeImageFormat":"Tiff",
      "TimeZoneFieldOnDocument":{
         "ArtifactID":0,
         "ViewFieldID":0,
         "Guids":[

         ]
      },
      "LastModifiedDateOnDocument":{
         "ArtifactID":0,
         "ViewFieldID":0,
         "Guids":[

         ]
      }
   },
   "SpreadsheetOptions":{
      "PaperSizeOrientation":"OriginalSetting",
      "PageOrder":"OriginalSetting",
      "PrintArea":"OriginalSetting",
      "HideAndPagebreakAfterConsecutiveBlankRowCol":0,
      "ShowTrackChanges":false,
      "IncludeRowAndColumnHeadings":"OriginalSetting",
      "IncludeHeadersAndFooters":"OriginalSetting",
      "IncludeComments":false,
      "IncludeGridlines":"OriginalSetting",
      "IncludeBorders":false,
      "UnhideHiddenWorksheets":false
   },
   "EmailOptions":{
      "Orientation":"Portrait",
      "ResizeImagesToFitPage":false,
      "ResizeTablesToFitPage":false,
      "DownloadImagesFromInternet":false,
      "ClearIndentations":false,
      "DisplaySmtpAddresses":false,
      "ShowMessageTypeInHeader":false
   },
   "WordProcessingOptions":{
      "ShowTrackChanges":false,
      "PageOrientation":"OriginalSetting"
   },
   "PresentationOptions":{
      "ShowSpeakerNotes":false,
      "SlideOrientation":"OriginalSetting"
   },
   "HtmlOptions":{
      "RemoveNonBreakingSpaceCodes":false
   },
   "ArtifactID":1038583,
   "Name":"Test Rest ImagingProfile"
}

Delete an imaging profile

Use the DeleteAsync endpoint to delete an imaging profile. Send a request to the following URL on the Imaging Profile Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Profile Service/DeleteAsync

The request must contain the following fields:

  • imagingProfileId - the Artifact ID of the imaging profile that you want to delete.
  • workspaceID - the Artifact ID of the workspace that contains the imaging profile.
{
   "imagingProfileId":1038583,
   "workspaceID":1017048
}

The response returns true when the imaging profile is successfully deleted.

Imaging sets

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 Sets Manager service supports create, read, update and delete operations on imaging sets. It also supports the hide and release operations used for a QC Review of imaged documents. For more information, see Imaging sets and QC Review on the RelativityOne Documentation site.

Create or update an imaging set

Use the SaveAsync endpoint for both creating and updating an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/SaveAsync

The request must contain the following fields:

  • imagingSet - indicates the imaging profile and saved search to use for an imaging job. It contains the following fields:
    • ImagingProfile - the Artifact ID of the imaging profile associated with the imaging set.
    • DataSource - the Artifact ID of the saved search containing the documents for imaging.
    • EmailNotificationRecipients - a list of email addresses for users who are notified after the associated imaging job completes. This field must be included in the JSON request, but you can set it to an empty string.
    • Status - the state of the imaging job for this imaging set. This field is required only for updating an imaging set. For more information, see the ImagingSetStatus class in Imaging APIon the Relativity API reference page.
    • ArtifactID - the Artifact ID of the imaging set. This field is required only for updating an imaging set.
    • Name - the user-friendly name of the imaging set.
  • workspaceId - the Artifact ID of the workspace that contains the imaging set.
ClosedView JSON request for creating an imaging set 
{
   "imagingSet":{
      "ImagingProfile":{
         "ArtifactID":1038841
      },
      "DataSource":1038838,
      "EmailNotificationRecipients":"",
      "Name":"Imaging Set from rest"
   },
   "workspaceId":1017048
}
ClosedView JSON request for updating an imaging set

The JSON request for updating an imaging set includes its Artifact ID.

{
   "imagingSet":{
      "ImagingProfile":{
         "ArtifactID":1038841
      },
      "DataSource":1038838,
      "EmailNotificationRecipients":"",
      "Status":{

      },
      "ArtifactID":1038842,
      "Name":"Imaging Set updated from REST"
   },
   "workspaceId":1017048
}

When an imaging set is successfully created or updated, the JSON response contains its Artifact ID, such as 1038842.

Retrieve an imaging set

Use the ReadAsync endpoint to retrieve an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/ReadAsync

The request must contain the following fields:

  • imagingSetId - the Artifact ID of the imaging set.
  • workspaceID - the Artifact ID of the workspace that contains the imaging set.
{
   "imagingSetId":1038815,
   "workspaceID":1017048
}

The response returns the following fields:

  • ImagingProfile - the imaging profile associated with the imaging set. This object contains the following field:
    • ArtifactID - the Artifact ID of the imaging profile.
  • DataSource - the Artifact ID of the saved search containing the documents for imaging.
  • EmailNotificationRecipients - a list of email addresses for users who are notified after an associated imaging job completes.
  • Status - the state of the imaging job for this imaging set. For more information, see ImagingSetStatus class in Imaging API on the Relativity API reference page.
  • ArtifactID - the Artifact ID of the imaging set.
  • Name - the user-friendly name of the imaging set.
{
   "ImagingProfile":{
      "ArtifactID":1038814
   },
   "DataSource":1038811,
   "EmailNotificationRecipients":"",
   "Status":{

   },
   "ArtifactID":1038815,
   "Name":"Imaging Set updated from REST"
}

Delete an imaging set

Use the DeleteAsync endpoint to delete an imaging set. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/DeleteAsync

The request must contain the following fields:

  • imagingSetId - the Artifact ID of the imaging set.
  • workspaceID - the Artifact ID of the workspace that contains the imaging set.
{
   "imagingSetId":1038815,
   "workspaceID":1017048
}

The response returns the status code of 200 when the image set is successfully deleted.

Hide an imaging set

You can hide images that need to undergo a quality control review from your reviewers. For more information, see QC Review on the RelativityOne Documentation site.

Use the HideImagingSetAsync endpoint to hide an imaging set from reviewers. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/HideImagingSetAsync

The request must contain the following fields:

  • imagingSet - contains minimal information about an ImagingSet object. It includes the following fields
    • imagingSetId - the Artifact ID of the imaging set.
    • Name - the user-friendly name of the imaging set.
  • workspaceID - the Artifact ID of the workspace that contains the imaging set.
{
   "imagingSet":{
      "imagingSetId":1039603,
      "Name":1017371
   },
   "workspaceId":1017048
}

The response returns the status code of 200 when the image set is successfully hidden.

Release an imaging set

After a quality control review has been completed on images, you can then programmatically make them available to reviewers by making a call to the ReleaseImagingSetAsync endpoint. Send a request to the following URL on the Imaging Set Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Set Service/ReleaseImagingSetAsync

The request must contain the following fields:

  • imagingSet - contains minimal information about an ImagingSet object. It includes the following fields
    • imagingSetId - the Artifact ID of the imaging set.
    • Name - the user-friendly name of the imaging set.
  • workspaceID - the Artifact ID of the workspace that contains the imaging set.
{
   "imagingSet":{
      "imagingSetId":1039603,
      "Name":1017371
   },
   "workspaceId":1017048
}

The response returns the status code of 200 when the image set is successfully released.

Native types

You can retrieve native file types supported by Relativity for imaging. For more information, see Imaging native types on the RelativityOne Documentation site.

Retrieve a native type

Use ReadAsync endpoint to retrieve a native type. Send a request to this URL on the Native Type Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Native Type Service/ReadAsync

The request must contain the following fields:

  • nativeTypeId - the Artifact ID of the native type.
  • workspaceID - the Artifact ID of the workspace that contains the native file type to retrieve.
{
   "nativeTypeId":1036567,
   "workspaceID":1017048
}

The response returns the following fields:

  • BasicCategory - the basic imaging category for this native type, such as spreadsheet, graphic, or others. For more information, see the BasicCategory enumeration in Imaging APIon the Relativity API reference page.
  • NativeCategory - the native imaging category for this native type, such a spreadsheet, email message, or others. For more information, see the NativeCategory enumeration in Imaging API on the Relativity API reference page.
  • UseNativeImaging - a Boolean value indicating whether to use native imaging on this native type.
  • RestrictedFromImagingByDefault - a Boolean value indicating whether this native type is restricted from imaging by default.
  • FileTypeId - the identifier of the file type used by Invariant.
  • PreventNativeDownload - a Boolean value indicating whether the native type is restricted from being downloaded.
  • ArtifactID - the Artifact ID of the native type.
  • Name - the user-friendly name for the native type.
{
   "BasicCategory":"WordProcessor",
   "NativeCategory":"WordProcessor",
   "UseNativeImaging":true,
   "RestrictedFromImagingByDefault":false,
   "FileTypeId":1336,
   "PreventNativeDownload":false,
   "ArtifactID":1036567,
   "Name":"Microsoft Word 2010"
}

Application field codes

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. You can programmatically create, read, update, or delete application field codes through the Application Field Code Manager service. For more information, see Application Field Codes on the RelativityOne Documentation site.

Create or update an application field code

Use the SaveAsync endpoint to create or update an application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/SaveAsync

The request must contain the following fields:

  • applicationFieldCode - indicates how to handle field codes used in Microsoft documents during imaging. This object contains the following fields:
    • FieldCode - a string indicating that the field code is available in a specific application, such as Microsoft Word, Excel, or Visio.
    • Application - an identifier for the application associated with a field code, such as Microsoft Word, Excel, or others. For more information, see the ApplicationType enumeration in Imaging API on the Relativity API reference page.
    • Option - the option controlling whether the field code is displayed, replaced with a Relativity application field code, or some other action is taken for rendering the field code in an image. For more information, see ApplicationFieldCodeOption enumeration in the Imaging API reference and Application Field Codes on the RelativityOne Documentation site.
    • ArtifactID - the Artifact ID of the application field code. This field is only required for updating an existing application field code.
    • RelativityField - links a Relativity field to a field code used in a Microsoft application. This field is optional.
    • ImagingProfiles - a list of ImagingProfileRef objects, which may be linked to the field codes. This field is optional.
    • Name - the user-friendly name for the Relativity application field code.
  • workspaceId - the Artifact ID of the workspace that contains the application field code.
ClosedView JSON request for creating an application field code 
{  
   "applicationFieldCode":{  
      "FieldCode":"Date",
      "Application":"MicrosoftWord",
      "Option":"ShowFieldCode",
      "Name":"Field saved from rest"
   },
   "workspaceId":1017048
}
ClosedView JSON request for updating an application field code 
{  
   "applicationFieldCode":{  
      "FieldCode":"Date",
      "Application":"MicrosoftWord",
      "Option":"ShowFieldCode",
      "ArtifactID":1038582,
      "Name":"Field code updated from rest"
   },
   "workspaceId":1017048
}

When an application field code is successfully created or updated, the JSON response contains its Artifact ID, such as 1038582.

Retrieve an application field code

Use the ReadAsync endpoint to retrieve an application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/ReadAsync

The request must contain the following fields:

  • applicationFieldCodeId - the Artifact ID of the application field code that you want to retrieve.
  • workspaceID - the Artifact ID of the workspace that contains the application field code.
{
   "applicationFieldCodeId":1038582,
   "workspaceID":1017048
}

The response returns the following fields:

  • FieldCode - a string indicating that the field code is available in a specific application, such as Microsoft Word, Excel, or Visio.
  • Application - an identifier for the application associated with a field code, such as Microsoft Word, Excel, or others. For more information, see the ApplicationType enumeration in the Imaging API on the Relativity API reference page.
  • Option - the option controlling whether the field code is displayed, replaced with a Relativity application field code, or some other action is taken for rendering the field code in an image. For more information, see the ApplicationFieldCodeOption enumeration in the Imaging API reference and Application Field Codes on the RelativityOne Documentation site.
  • ArtifactID - the Artifact ID of the application field code.
  • Name - the user-friendly name for the Relativity application field code.
{
   "FieldCode":"Date",
   "Application":"MicrosoftWord",
   "Option":"ShowFieldCode",
   "ArtifactID":1038582,
   "Name":"NewFieldCode"
}

Delete an application field code

Use the DeleteAsync endpoint to remove a specific application field code. Send a request to this URL on the Application Field Code Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Application Field Code Service/DeleteAsync

The request must contain the following fields:

  • applicationFieldCodeId - the Artifact ID of the application field code that you want to delete.
  • workspaceID - the Artifact ID of the workspace that contains the application field code.
{
  "applicationFieldCodeId": 1038582,
  "workspaceID": 1017048
}

The response returns true when the application field code is successfully deleted.

Imaging jobs

You can programmatically run jobs to image documents, cancel the job currently executing on an imaging set, or retry errors that occurred during a job. For general information, see Running an imaging set and Imaging errors on the RelativityOne Documentation site.

Run an imaging set job

Use the RunImagingSetAsync endpoint to start an imaging job. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/RunImagingSetAsync

The request must contain the following fields:

  • imagingJob - a job request sent to the imaging engine to generate a set of images for documents identified by a specific imaging set. It contains the following fields:
    • imagingSetId - the Artifact ID of the imaging set.
    • workspaceId - the Artifact ID of the workspace that contains the imaging set.

Note: 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. For more information, see Imaging (.NET).

{
   "imagingJob":{
      "imagingSetId":1039603,
      "workspaceId":1017371
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"442dd13d-26ed-493d-b48c-3547ef62394c"
}

Image a single document

Use the ImageDocumentAsync endpoint 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.

Note: To an cancel an on-the-fly imaging job, use the StopImagingJobAsync endpoint.

Send a request to the following URL on the Imaging Job service:

<host>/Relativity.Rest/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/ImageDocumentAsync

In the JSON request, the following fields are required unless specifically identified as optional:

  • imageDocumentJob - represents a job submitted for imaging a singe document. The ImageDocumentJob object contains the following fields:
    • WorkspaceId - the Artifact ID of the workspace containing the document that you want to image.
    • DocumentId - the Artifact ID of the document that you want to image.
    • ProfileId - the Artifact ID of the imaging profile used for the imaging job.
    • AlternateNativeLocation - indicates whether to use a Relativity native file or an alternative native file for imaging. To image a Relativity native file, leave this field blank. To image an alternative native file, enter the path that contains file. This file is used only to generate the image, but it isn’t attached to the document. The file type must be supported for imaging in Relativity. For more information, see Imaging native types
    • RemoveAlternateNativeAfterImaging - a Boolean value indicating whether to delete an alternative native file specified in the AlternateNativeLocation field after the imaging job has completed. You may want to set this field to true when you have uploaded a temporary file. If the AlternateNativeLocation field is blank, then this flag is ignored.
{  
   "imageDocumentJob":{  
      "WorkspaceId":1031808,
      "DocumentId":1053648,
      "ProfileId":1036462,
      "AlternateNativeLocation":"//fileshare/path/filename.ext",
      "RemoveAlternateNativeAfterImaging":"true"
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"86367960-076a-47ea-8e24-1cd27135ed33"
}

Cancel imaging jobs

You can use the StopImagingJobAsync endpoint to cancel imaging jobs. The StopImagingJobAsync endpoint cancels any type of imaging job, including imaging set jobs.

Cancel an imaging job

Use the StopImagingJobAsync endpoint to cancel any imaging job, including an imaging set job and a job for imaging on the fly. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/StopImagingJobAsync

The request must contain the following fields:

  • stopImagingJobRequest - a job request sent to the imaging engine to stop an ongoing imaging job. It contains the following fields:
    • imagingJobId - an Artifact ID that identifies the job to be canceled.
    • workspaceArtifactId - the Artifact ID of the workspace where the request originated.
{
   "stopImagingJobRequest":{
      "imagingJobId":1054631,
      "workspaceArtifactId":1017371
   }
}

The response contains the following fields:

  • stopImagingJobResponse - a response from the imaging engine that indicates whether the imaging job was successfully canceled. It contains the following field:
    • success - a Boolean value indicating whether the job is canceled without errors.
{
   "stopImagingJobResponse":{
      "success":true
   }
}

Retry imaging set errors

Use the RetryErrorsAsync endpoint to rerun an imaging job. Send a request to this URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/RetryErrorsAsync

The request must contain the following fields:

  • imagingJob - a job request sent to the imaging engine to generate a set of images for documents identified by a specific imaging set. It contains the following fields:
    • imagingSetId - the Artifact ID of the imaging set.
    • workspaceId - the Artifact ID of the workspace that contains the imaging set.
{
   "imagingJob":{
      "imagingSetId":1039603,
      "workspaceId":1017371
   }
}

The response returns the ImagingJobId field, which contains a GUID that uniquely identifies the job.

{
   "ImagingJobId":"c2f4503a-a14a-4b44-a3c0-cba58d16577a"
}

Update the priority of an imaging job

(Available in RelativityOne 10.2.170.2 and above)

Use the UpdateJobPriorityAsync endpoint to modify the priority for an imaging job in a specific workspace. Send a request to the following URL on the Imaging Job Manager service:

<host>/Relativity.REST/api/Relativity.Imaging.Services.Interfaces.IImagingModule/Imaging Job Service/UpdateJobPriorityAsync

The request must contain the following fields:

  • UpdateJobPriorityRequest - represents a request to modify the priority of an imaging job:
    • jobGuid - the GUID of the job with the priority that you want to update.
    • priority - an integer value representing the new priority for the job.
    • workspaceId - the Artifact ID of the workspace that contains the imaging job.
{
   "UpdateJobPriorityRequest":{
      "jobGuid":"2C0512A4-E56E-4B4F-A0B2-BAC351E13D2F",
      "priority":10,
      "workspaceId":1017371
   }
}

The JSON response contains the following fields:

  • updateJobPriorityResponse - a response object containing the following fields:
    • updateJobPriorityResponse - a Boolean value indicating whether the priority of the job was successfully updated.
    • errorMessage - a string containing information about any errors that occurred when updating the priority.
{
   "updateJobPriorityResponse":{
      "updateJobPriorityResponse":true,
      "errorMessage":""
   }
}

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