Document Viewer Services API

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 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. 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. 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.
  • Create a custom Viewer that displays and reads persistent highlight sets and terms.

In addition, you can use the Document Viewer API through the REST API. For more information, see Document Viewer Services in REST.

This page contains the following information:

Fundamentals for the Document Viewer Services API

The Relativity.DocumentViewer.Services namespace contains the interface, classes, and enumerations required to make conversion requests. The IDocumentViewerServiceManager interface includes the GetViewerContentKeyAsync() method, which sends a request to convert documents. It supports requests for native, image, production, and transcript conversion types. This method takes a GetViewerContentKeyRequest object that includes information about how to convert a document, such as its conversion type, priority, and other options. For on-the-fly requests, it returns a request key for documents that are currently undergoing conversion, and a cache entry ID for converted documents.

The Relativity.DocumentViewer.Services namespace contains the interface, classes, and enumerations required to make conversion requests and to retrieve persistent highlight sets. It includes the following methods that you can use to access the services for the document viewer:

  • GetViewerContentKeyAsync() - sends a request to convert documents. It supports requests for native, image, production, and transcript conversion types. This method takes a GetViewerContentKeyRequest object that includes information about how to convert a document, such as its conversion type, priority, and other options. For on-the-fly requests, it returns a request key for documents that are currently undergoing conversion, and a cache entry ID for converted documents.
  • GetPersistentHighlightSets() - retrieves every persistent highlight set and set of terms in a specific document and workspace.
  • SavePersistentHighlightState() - This method allows you to change the default persistent highlight set or terms. Additionally, you can make terms or sets inactive.

Best practices for the conversion requests

Use the following guidelines when calling the GetViewerContentKeyAsync() method:

  • Verify that you are passing valid parameters to it. If you pass an invalid workspace ID or other parameter, the service throws a ValidationException.
  • For production conversions, set the ProductionId property on the Options property of the request object. See GetViewerContentKeyOptions class in Classes and enumerations.
  • For mass conversions, you can create a mass operations resource table to store multiple document IDs. Include the name of the resource table on DocumentSetID property on the Options property of the request object. See GetViewerContentKeyOptions class in Classes and enumerations.

Classes and enumerations

The Relativity.DocumentViewer.Services namespace also contains the following classes and enumerations:

  • GetViewerContentKeyRequest class - represents a conversion request that is passed to the GetViewerContentKeyAsync() method. It includes properties for the conversion type, the priority of the request, the ID of the workspace containing documents for conversion, and the Artifact IDs of these documents. It also contains an Options property, which references a GetViewerContentKeyOptions object.
  • GetViewerContentKeyOptions class - includes specialized conversion properties used for productions and mass conversions. It includes the ForceConversion property used to indicate that a previously converted document should be reconvert, and the ClientId used to indicate indicates the client ID of the application caller, such as DocumentViewer.Conversion.PreConvert. For File field conversion, you can set the FileId property, which provides the identifier for the RDO with an associated File field.
  • ViewerContentKey class - represents a response from a conversion job. It contains a request key for documents that are currently undergoing conversion, and a cache entry ID for converted documents. An object of this type is returned by the GetViewerContentKeyAsync() method.
  • ConversionType enumeration - indicates how the documents should be converted. It contains None, Native, Image, Production, and Transcript members.
  • PriorityLevel enumeration - indicates the precedence of a conversion job. It contains None, OnTheFly, ConvertAhead, and MassConvert members.

For reference information about these classes and enumerations, see Document Viewer Services API

Prerequisites for the Document Viewer Services API

Complete the following prerequisites to begin development with the Document Viewer Services API:

Download the SDKs required for converting documents from the Relativity Community. For more information, see Download the SDKs.

After you download the following SDKs, install or extract their contents to folders on your local machine:

  • Relativity SDK
  • Document Viewer Services SDK - contains the following items:
    • Relativity.DocumentViewer.Services.Interfaces.dll - located in the Vendor folder of this SDK.
    • DVS.Documentation.Samples.sln - contains C# code samples illustrating how to perform various conversion operations.
  • Obtain access to an instance of Relativity Server2021 used for development purposes.
  • Enable Developer mode in your development instance of Relativity to simplify troubleshooting. For more information, see Set up your development environment.
  • In the Relativity UI, set up your workspaces containing documents that you want to convert for display in the viewer.

Convert documents

Use the GetViewerContentKeyAsync() method to convert documents to native, image, production, or transcript type. You can obtain the request key for documents currently undergoing conversion from the ViewerContentKey object returned by this method. It also returns the cache entry ID for converted documents. For jobs with lower priorities, Relativity uses batching to pre-convert documents in a specific workspace.

The following code samples illustrates how to perform these general tasks:

  • Use helper classes to create the proxy and select an appropriate authentication type. See Relativity API Helpers.
  • Create the Services API proxy within a using block in your code.
  • Create a GetViewerContentKeyRequest object.
  • Call the GetViewerContentKeyAsync() method within a try-catch block.
  • Use await/async design pattern. See Basic Services API concepts.
  • Use the logging framework for troubleshooting and debugging purposes. See Log from a Relativity application .

Convert documents to their native format

To convert documents to their native format on the fly, the ConversionType property on the GetViewerContentKeyRequest instance is set to Native, and the Priority property is set to OnTheFly. The request is then passed to the GetViewerContentKeyAsync() method.

public async Task<ViewerContentKey> GetViewerContentKeyAsync(int workspaceId, int[] documentIds)
{
     ViewerContentKey viewerContentKey = null;

     using (IDocumentViewerServiceManager proxy = helper.GetServicesManager().CreateProxy<IDocumentViewerServiceManager>(ExecutionIdentity.User))
     {
          GetViewerContentKeyOptions options = new GetViewerContentKeyOptions();
          options.ForceConversion = false;
          GetViewerContentKeyRequest request = new GetViewerContentKeyRequest();
          request.WorkspaceId = workspaceId;
          request.DocumentIds = documentIds;
          request.ConversionType = ConversionType.Native;
          request.Priority = PriorityLevel.OnTheFly;
          request.Options = options;

          try
          {
               viewerContentKey = await proxy.GetViewerContentKeyAsync(request);
          }
          catch (ServiceException exception)
          {
               ISampleLogger _logger = Client.SamplesLibrary.Logging.Log.Logger.ForContext<IDocumentViewerServiceManager>();
               _logger.LogError(exception, "Document Viewer Service GetViewerContentKeyAsync call failed for Workspace ID {0}", workspaceId);
          }
     }

     return viewerContentKey;
}

Convert documents in a production set

To convert documents in a production set, the ProductionId property on the GetViewerContentKeyOptions instance is set to the Artifact ID of a production set, and the ConversionType property on the GetViewerContentKeyRequest instance is set to Production. The request is then passed to the GetViewerContentKeyAsync() method.

public async Task GetViewerContentKeyAsync(int workspaceId, int[] documentIds, int productionId)
{
     using (IDocumentViewerServiceManager proxy = helper.GetServicesManager().CreateProxy<IDocumentViewerServiceManager>(ExecutionIdentity.User))
     {
          GetViewerContentKeyOptions options = new GetViewerContentKeyOptions();
          options.ForceConversion = false;
          options.ProductionId = productionId;
          GetViewerContentKeyRequest request = new GetViewerContentKeyRequest();
          request.WorkspaceId = workspaceId;
          request.DocumentIds = documentIds;
          request.ConversionType = ConversionType.Production;
          request.Priority = PriorityLevel.ConvertAhead;
          request.Options = options;

          try
          {
               await proxy.GetViewerContentKeyAsync(request);
          }
          catch (ServiceException exception)
          {
               ISampleLogger _logger = Client.SamplesLibrary.Logging.Log.Logger.ForContext<IDocumentViewerServiceManager>();
               _logger.LogError(exception, "Document Viewer Service GetViewerContentKeyAsync call failed for Workspace ID {0}", workspaceId);
          }
     }
}

Pre-convert images

To pre-convert images, the DocumentSetId property on the GetViewerContentKeyOptions instance is set to the name of an SQL table, and the ConversionType property on the GetViewerContentKeyRequest instance is set to Image. Additionally, the Priority property is set to MassConvert. The request is then passed to the GetViewerContentKeyAsync() method.

public async Task GetViewerContentKeyAsync(int workspaceId, string massOpTableDocumentSetId)
{
     using (IDocumentViewerServiceManager proxy = helper.GetServicesManager().CreateProxy<IDocumentViewerServiceManager>(ExecutionIdentity.User))
     {
          GetViewerContentKeyOptions options = new GetViewerContentKeyOptions();
          options.ForceConversion = true;
          options.DocumentSetId = massOpTableDocumentSetId;
          GetViewerContentKeyRequest request = new GetViewerContentKeyRequest();
          request.WorkspaceId = workspaceId;
          request.ConversionType = ConversionType.Image;
          request.Priority = PriorityLevel.MassConvert;
          request.Options = options;

          try
          {
               await proxy.GetViewerContentKeyAsync(request);
          }
          catch (ServiceException exception)
          {
               ISampleLogger _logger = Client.SamplesLibrary.Logging.Log.Logger.ForContext<IDocumentViewerServiceManager>();
               _logger.LogError(exception, "Document Viewer Service GetViewerContentKeyAsync call failed for Workspace ID {0}", workspaceId);
          }
     }
}

Convert files contained in File fields on RDOs

You can convert files contained in File fields on a Relativity Dynamic Objects (RDOs) for display in the standalone viewer. These files are converted to their native format on the fly.

Similar to document conversion, pass a GetViewerContentKeyRequest instance to the GetViewerContentKeyAsync() method. Follow these guidelines for setting properties on the GetViewerContentKeyRequest instance for converting File fields:

  • Set the ConversionType property to Native.
  • Set the Priority property set to OnTheFly.
  • Optionally, set the FileId property on the GetViewerContentKeyOptions instance to the identifier for the RDO with the associated File field.

Note: On the GetViewerContentKeyRequest instance, the DocumentIds property contains only the FieldArtifactID when it is used for converting a file contained in a File field.

You can obtain the request key for File fields currently undergoing conversion from the ViewerContentKey object returned by this method. It also returns the cache entry ID for converted files. For jobs with lower priorities, Relativity uses batching to pre-convert file fields in a specific workspace.

The following code sample illustrates how to convert a file contained in a File field. For information about general tasks performed in this code, see Convert documents.

public async Task<ViewerContentKey> GetViewerContentKeyAsync(int workspaceId, int[] documentIds, int? fileId = null)
{
     ViewerContentKey viewerContentKey = null;
 
     using (IDocumentViewerServiceManager proxy = helper.GetServicesManager().CreateProxy<IDocumentViewerServiceManager>(ExecutionIdentity.User))
     {
          GetViewerContentKeyOptions options = new GetViewerContentKeyOptions();
          options.ForceConversion = false;
          options.FileId = fileId;
          GetViewerContentKeyRequest request = new GetViewerContentKeyRequest();
          request.WorkspaceId = workspaceId;
          request.DocumentIds = documentIds.FirstOrDefault();
          request.ConversionType = ConversionType.Native;
          request.Priority = PriorityLevel.OnTheFly;
          request.Options = options;
 
          try
          {
               viewerContentKey = await proxy.GetViewerContentKeyAsync(request);
          }
          catch (ServiceException exception)
          {
               ISampleLogger _logger = Client.SamplesLibrary.Logging.Log.Logger.ForContext<IDocumentViewerServiceManager>();
               _logger.LogError(exception, "Document Viewer Service GetViewerContentKeyAsync call failed for Workspace ID {0}", workspaceId);
          }
     }
 
     return viewerContentKey;
}

Retrieve persistent highlight sets in a specific document and workspace

This method retrieves each the persistent highlight sets and terms in a specific document and workspace.

public void GetPersistentHighlightSets()
{
	var persistentHighlightSetRepository = _servicesManager.CreateProxy<IPersistentHighlightServiceManager>();
	IEnumerable<PersistentHighlightSet> sets = persistentHighlightSetRepository.GetPersistentHighlightSets(workspaceId, documentId);
}

Change persistent highlight set state

This method allows you to change the default persistent highlight set or terms. Additionally, you can make terms or sets inactive as desired.

public void SavePersistentHighlightState()
{
	int workspaceId = 1;
	int persistentHighlightSetId = 2;
	IEnumerable<int> termIds = new List<int>();
	PersistentHighlightStateAction action = PersistentHighlightStateAction.Collapsed;
	var persistentHighlightSetRepository = _servicesManager.CreateProxy<IPersistentHighlightServiceManager>();
	persistentHighlightSetRepository.SavePersistentHighlightSetState(workspaceId, persistentHighlightSetId, termIds, action);	
}