PrizmDoc® v14.2 Release - Updated
PrizmDoc / Developer Guide / PrizmDoc Application Services (PAS) / Work with Viewing Packages
In This Topic
    Work with Viewing Packages
    In This Topic

    Introduction

    A Viewing Package is a cached version of a document that the Viewer will use when viewing a document. Viewing a document from a Viewing Package significantly reduces the load on PrizmDoc Server and allows you to serve many more users per minute than you could otherwise. A Viewing Package can be created through Pre-Conversion or by using On-Demand Caching.

    This topic provides information about the following:

    Storage

    Viewing Packages are stored in both the filesystem and configured database. If using multiple instances of PAS, you must use a shared database and NAS (Network Attached Storage). The Running PrizmDoc Application Services (PAS) on Multiple Servers topic can provide more information for configuring PAS in Cluster Mode.

    By default, storage is configured in the following way:

    Config Key Storage Provider Description
    viewingPackagesData database Data about a Viewing Package. This is the data that can be retrieved from GET /v2/viewingPackages.
    viewingPackagesProcesses database Data about a Viewing Package creator process. This is the data that can be retrieved from GET /v2/viewingPackageCreators.
    viewingSessionsData database Data about a Viewing Session. When creating a Viewing Session, an entry is added to this table.
    viewingSessionsProcessesMetadata database Data about processes for a Viewing Session. This is currently used for content conversion and markup burner processes.
    viewingPackagesArtifactsMetadata database Metadata for a viewing package artifact. This is used to find specific artifacts for a package and contains the artifact type, the file name in the filesystem among other important information.
    viewingPackagesArtifacts filesystem Artifacts for a Viewing Package. These include SVG and raster content for every page, the source document, and other artifacts the Viewer will likely request.

    Configuration

    Viewing Packages are opt-in and require special configuration to work properly. At a minimum, your configuration should include the following:

    \# Feature toggles
    
    feature.viewingPackages: "enabled"
    
    
    \# Database configuration
    
    database.adapter: "sqlserver"
    
    database.host: "localhost"
    
    database.port: 1433
    
    database.user: "pasuser"
    
    database.password: "password"
    
    database.database: "PAS"
    
    
    \# Default timeout for the duration of a viewing session
    
    defaults.viewingSessionTimeout: "20m"
    
    
    viewingPackagesData.storage: "database"
    
    viewingPackagesProcesses.storage: "database"
    
    viewingSessionsData.storage: "database"
    
    viewingSessionsProcessesMetadata.storage: "database"
    
    
    viewingPackagesArtifactsMetadata.storage: "database"
    
    viewingPackagesArtifacts.storage: "filesystem"
    
    viewingPackagesArtifacts.path: "/your/path/to/viewingPackages"
    
    

    Pre-Conversion

    Creating a Viewing Package through Pre-Conversion provides a way to generate packages whenever it makes the most sense for your application to do so. It allows you to make use of down-time for Pre-Conversion to reduce load in high traffic periods. Pre-Conversion does all the work of creating a Viewing Package whenever it is requested. It starts a process that will begin downloading content and allow you to poll for progress.

    It is recommended that you maintain a queue of Pre-Conversions so you don’t overload the server and have faster turnaround time. We recommend a maximum of 5 Pre-Conversion processes at a time per PAS and PrizmDoc Server instance. This will allow packages to be created quickly while maintaining a sustainable load.

    For a step-by-step process, go to the Pre-Converting Documents topic.

    On-Demand Caching

    Creating a Viewing Package through On-Demand Caching is a seamless process through the Viewing Session API. On-Demand Caching allows you to trigger a Viewing Package creation process in the background and use the resulting Viewing Package when it is ready. This feature is designed to allow immediate viewing using PrizmDoc Server while caching a package for subsequent views of the same document.

    As an example, consider this request for a Viewing Session:

    POST /ViewingSession
    
    {
    
       "source": {
    
           "documentId": "PdfDemoSample-a1b0x19n2",
    
           "type": "document",
    
           "fileName": "PdfDemoSample.pdf"
    
       }
    
    }
    
    

    This request will always return a viewingSessionId regardless of the status of the matching Viewing Package. If a Viewing Package does not currently exist with the given documentId, PrizmDoc Server will handle document viewing while a background process creates a Viewing Package. Once the background process is complete, PAS will handle all further viewing sessions until the Viewing Package expires (24 hours by default).

    Performance Considerations

    When enabling the Viewing Packages feature, there are additional considerations for hardware requirements. See Sizing Servers for more information.

    Known Issues

    Document Comparison

    Viewing packages are not supported for comparison viewing sessions.

    Markup & Redaction

    When creating a Viewing Package and pages of the source document have successfully converted to the intermediate PDF, but PAS fails to get one or more pages of viewable content, the Viewer will not have that failed page content available to markup (i.e., redact). Because of this, when the user attempts to burn the markup into the output document, (which is generated from the intermediate PDF), it will have the page content and no markup.

    If this occurs and the failed page contains content that must be redacted, a new viewing package should be created to retry the conversion.

    Raster Content

    • Viewing Packages limit available raster content. During Viewing Package creation, raster content is requested only for 0.125 , 0.25, 0.5, and 1.0 scale. API requests for raster content with a scale that is not one of these values will return 404 Not Found. PrizmDoc will always request full scale raster content from a viewing package which may result in degraded fidelity since the full scale image will be returned and any additional scaling will occur within the browser. Additionally, requests for tiling and thumbnails are not supported and will return 501 NotImplemented.
    • The render.html5.alwaysUseRaster property cannot be used when creating a viewing session with caching.

    Watermarks

    • The watermarks property cannot be used when creating a viewing session with caching.