Document Viewer Services in REST

The Document Viewer Services API provides an HTTP service, which you can use to request document conversions through Representational State Transfer (REST). The Document Viewer Services API provides functionality for requesting the conversion of documents to viewer types supported by Relativity, such as native, image, production, and transcript types. You can also convert files contained in File fields on a Relativity Dynamic Objects (RDOs). These files are converted to their native format on the fly, and then displayed in the standalone viewer.

Relativity performs the conversion and then stores the content in the converted cache table for a specific workspace. After a document is converted to a specified type, you can then display it in the viewer available through the Relativity UI. For more information, see Viewer on the Relativity Server2021 Documentation site.

The Document Viewer Services API also allows you to view information about persistent highlight sets and terms in a specific document and workspace through REST. Persistent highlight sets allow you to configure and apply term highlighting to assist with document review in the Viewer. To learn more, visit Persistent highlight sets.

The Document Viewer Services API also provides functionality for persistent highlight sets and allows you to view information about the persistent highlight sets and terms in a specific document and workspace through REST. The API also allows you to select the default highlight sets or terms as well as make any terms or sets inactive. Persistent highlight sets allow you to configure and apply term highlighting to assist with document review in the Viewer. To learn more, visit Persistent highlight sets.

The following sample use cases illustrate how you can use these cache entries to create custom viewers or workflows for displaying documents:

• Convert documents and save their locations in the cache. Next, create a custom application that retrieves native documents and displays them in a user-friendly format through a browser.
• Create a custom page or workflow that requests a document on the fly for immediate display in the viewer. Send a notification when the document is converted and available for viewing.

You can also use the Document Viewer Services through .NET. For more information, see Document Viewer Services API.

This page contains the following information:

• Client code samples
• Convert documents
• Convert files contained in File fields on RDOs
• Get persistent highlight sets in a specific document and workspace
• Change persistent highlight set state

Client code samples

To use the Document Viewer Services, send an HTTP request that makes a POST method call. See the following RL for this service:

The GetViewerContentKeyAsync endpoint supports different conversion types and priorities. You can use the following .NET code samples as REST clients for requesting conversions. They illustrate how to perform conversions for native formats, productions, and images with various priorities. Additionally, they all perform the following common tasks:

• Instantiate an HttpClient object for sending requests and responses using the URL for the Document Viewer Service.
• Set the required headers for the request.
• Set the BaseAddress variable to the Host Url.
• Set the string represented by parameters variable to the JSON input required to request a conversion.
• Use Newtonsoft to serialize the request object into JSON.
• Use the PostAsync() method to send a post request.
• Return the results of the request and deserialize it.

Convert documents

To convert documents in a workspace, send a request to this URL for the Document Viewer Services:

JSON requests

The following fields on the request object are required unless specifically identified as optional:

• WorkspaceId - the Artifact ID of the workspace that contains the documents for conversion.
• ConversionType - the output type for the documents undergoing conversion. The conversion types include Native, Image, Production, and Transcript. For general information about supported types, see Viewer on the Relativity Server2021 Documentation site.
• DocumentIds - an array of Artifact IDs for the documents that you want to convert.
• Priority - the precedence of a conversion job. The priority levels from highest to lowest precedence include: OnTheFly, ConvertAhead, and MassConvert.
• Options - additional fields required for specific types of conversion jobs. These options include:
  • ProductionID - the Artifact ID of a production set. This field is only required when the conversion type is Production.
  • DocumentSetId - the name of an SQL table on the workspace database that contains the Artifact IDs of the documents that you want to convert. This field is only required when the conversion type is MassConvert.
  • ForceConversion - a Boolean value indicating whether to reconvert a previously converted document. This field is only required when you want to reconvert documents. It must be set to true for this purpose.
  • ClientID - a string value that indicates the client ID of the application caller. It is used to identify the usage of the Document Viewer Service. This field is required, and must have a value. It must not be null or empty.

Sample JSON for native format request

Sample JSON for a production request

Sample JSON request for a mass conversion of images

JSON responses

A conversion response includes a ViewerContentKey object. This object may contain the DocumentArtifactId, CacheEntryId, ConversionVersion, and RequestKey fields. For more information, see Document Viewer Services API.

If the document currently undergoing conversion, the JSON response contains the following fields:

• RequestKey - an unique value associated with a conversion request. You can use this field to track the progress of the conversion. If this property is set, SignalR sends a notification message after conversion has completed.
• DocumentArtifactId - the Artifact ID of a document that is undergoing conversion.

If the conversion of a document has completed, the JSON response contains the following fields:

• DocumentArtifactId - the Artifact ID of a document that has been converted and is available for retrieval.
• CacheEntryId - the identifier for the cached document. This field is only set when the document is available in the cache.
• ConversionVersion - the version number of the converted document.

Convert files contained in File fields on RDOs

You can convert a file contained in a File field on a Relativity Dynamic Object (RDO) for display in the standalone viewer. This file is converted to its native format. Similar to document conversion, this process uses the GetViewerContentKeyAsync endpoint. Send a request to this URL for the Document Viewer Services:

The following fields on the request object are required unless specifically identified as optional:

• WorkspaceId - the Artifact ID of the workspace that contains the file for conversion.
• ConversionType - the output type for the file undergoing conversion should always be set to Native.
• DocumentIds - an array containing one value, which is translated to the FieldArtifactId.
• Priority - the precedence of a conversion job. For File field conversion, this field must be set to OnTheFly.
• Options - additional fields required for specific types of conversion jobs. These options include:
  • ForceConversion - a Boolean value indicating whether to reconvert a previously converted file. This field is only required when you want to reconvert files. It must be set to true for this purpose.
  • FileID - the unique identifier for the RDO that the File field is associated with. For more information about adding File fields to RDOs, see File field.

The JSON responses for converting File fields contain the same fields as those returned for document conversion. For more information, see JSON responses.

Get persistent highlight sets in a specific document and workspace

Persistent Highlight Sets Manager allows you to view all persistent highlight sets and terms within a specified document and workspace.

To see the persistent highlight sets, send a GET request to the following URL:

Change persistent highlight set state

Persistent Highlight Sets Manager allows you to change the default persistent highlight set or terms. Additionally, you can make terms or sets inactive as desired.

To change the state of persistent highlight sets, send a GET request to the following URL: