How to Use the Document Pre-Conversion Feature in PrizmDoc
One of the new additions to our recent PrizmDoc v11.0 release was a developer preview of our document pre-conversion feature. This is an exciting new addition, given many of our clients work with thousands—even millions—of large documents and can’t afford to waste even seconds waiting for files to process.
Pre-conversion will allow the conversion of documents and images prior to being requested for viewing. For example, you can determine certain files to be converted and rendered. The rendered viewing packages will be stored in cache. When documents are requested for viewing, PrizmDoc will check to see if the document has been already converted and if so, call the viewing package for that document from cache to the viewer. This will dramatically increase performance, since the documents and images are already converted and ready for viewing before they are requested.
Although the feature is still in late-stage development and is slated to be production-ready in an upcoming release, you can download and use the current developer preview to test and evaluate the functionality. First we’ll give a quick PrizmDoc overview, and then cover how to get started with pre-conversion.
Understanding PrizmDoc
PrizmDoc is a powerful, scalable suite of APIs and Javascript that use HTML5 standard technologies to convert, view, search, annotate, and redact documents in dozens of formats in a zero footprint viewing client. At its core, the basic concept of PrizmDoc is fairly straightforward: your web application passes a document to an http service that converts it into SVG and returns it to the browser. So long as the browser supports SVG (which all modern browsers now do), the document is viewable without needing to install any software on the browsing device. This model works well across PCs, tablets, and even smartphones. Every device can view all standard document types without downloading or installing any extra software.
The above diagram provides an overview of the core components of the PrizmDoc Client and Server
PrizmDoc Application Services
PrizmDoc Application Services (PAS) is installed “ready to run” via any of our four web tier samples (C#, MVC, Java, PHP).
Pre-converting documents in Application Services
When viewing large documents, a user can experience a delay viewing later pages in the document. The pre-conversion API allows the user to avoid any delay in viewing a fully converted document prior to the creation of a viewing session. Users may choose to pre-convert all documents over a certain file size or documents that are frequently viewed, allowing for a more tailored viewing experience.
How to Create a viewing Package by Pre-converting Documents
Pre-conversion is available by using the Pre-conversion API. (For detailed information, refer to PrizmDoc Application Services RESTful Viewing Package Creators API.) Documents are pre-converted using the following steps:
Step 1
Issue a POST request with the body of the request containing JSON formatted ‘source’ object. The source.type property can be a “document”, “url” or “upload”. In this example, “document” is used as a source.type property.
POST http://localhost:3000/v2/viewingPackageCreators
viewingPackageCreator POST Body
Content-Type: application/json
{
"input": {
"source": {
"type": "document",
"fileName": "sample.doc",
"documentId": "unT67Fxekm8lk1p0kPnyg8",
. . .
},
"viewingPackageLifetime": 2592000
}
}
A successful response to the above POST provides 'processId' in the response body.
200 OK
Content-Type: application/json
{
"input": {
"source": {
"type": "document",
"fileName": "sample.doc",
"documentId": "unT67Fxekm8lk1p0kPnyg8",
. . .
},
"viewingPackageLifetime": 2592000
},
"expirationDateTime": "2015-12-09T06:22:18.624Z",
"processId": "khjyrfKLj2g6gv8fdqg710",
"state": "processing",
"percentComplete": 0
}
Step 2
Using the 'processId' obtained in step 1, query the pre-conversion process for the status.
GET http://localhost:3000/v2/viewingPackageCreators/khjyrfKLj2g6gv8fdqg710
A successful response body contains the JSON formatted properties 'state' and 'percentComplete'. The state value indicates whether it is 'complete' or 'processing' and the property 'percentComplete' indicates percentage amount complete.
Start polling the status by issuing a GET command using the above URL. It is recommended to use shorter intervals initially between the requests for the first few times. If it is still not complete, then the document may be large, requiring more processing time. In scenarios like this, an increase in the time interval between requests would be necessary to prevent a large number of status requests that could potentially cause network congestion. On 100% completion, the response body will among other information contain an output object with 'packageExpirationDateTime' property.
200 OK
Content-Type: application/json
{
"input": {
"source": {
"type": "document",
"fileName": "sample.doc",
"documentId": "unT67Fxekm8lk1p0kPnyg8",
. . .
},
"viewingPackageLifetime": 2592000
},
"output": {
"packageExpirationDateTime": "2016-1-09T06:22:18.624Z"
},
"expirationDateTime": "2015-12-09T06:22:18.624Z",
"processId": "khjyrfKLj2g6gv8fdqg710",
"state": "complete",
"percentComplete": 100
}
How to obtain information about the converted viewing Package
(For detailed information about the converted viewing Package, refer to PrizmDoc Application Services RESTful Viewing Package Creators API.)
When the status is 100% complete, details can be obtained about the converted package by issuing the following request:
GET http://localhost:3000/v2/viewingPackages/unT67Fxekm8lk1p0kPnyg8
Response Body
200 OK
Content-Type: application/json
{
"input": {
"source": {
"type": "document",
"fileName": "sample.doc",
"documentId": "unT67Fxekm8lk1p0kPnyg8",
. . .
},
"viewingPackageLifetime": 2592000
},
"state": "complete",
"packageExperationDateTime": "2016-1-09T06:22:18.624Z"
}
How to Delete a Previously Converted Package
(For detailed information about deleting converted viewing Package, refer to PrizmDoc Application Services RESTful Viewing Package Creators API.)
A previously converted package can be deleted by issuing a DELETE request.
DELETE http://localhost:3000/v2/viewingPackages/unT67Fxekm8lk1p0kPnyg8
This request marks the package for asynchronous deletion. A successful response is as follows:
204 (No Content)
Viewing Packages
PrizmDoc Application Services 11.0 introduces the Viewing Packages feature. A Viewing Package is a cached version of a document that the PrizmDoc Viewer will use when displaying a document. Viewing a document from a Viewing Package will significantly reduce the load on PrizmDoc Server and will allow you to serve many more users per minute than you would otherwise be able to.
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 on Multiple Servers topic can provide more information for configuring PAS in Multi-Server 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 Viewing Client 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.packages: "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: "/usr/share/prizm/Samples/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 five Pre-Conversion processes at a time per PrizmDoc Application Services and PrizmDoc Server instance. This will allow packages to be created quickly while maintaining a sustainable load.
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, PrizmDoc Application Services will handle all further viewing sessions until the Viewing Package expires (24 hours by default).
Conclusion
Given the increasing digital nature of document management, the pre-conversion services in PrizmDoc are an exciting addition to our already-robust suite of features. Pre-converting, rendering, and storing documents in cache will provide a more seamless experience, allowing users to immediately call and view documents and images. We believe it’s a game-changer that will allow many of our clients to significantly streamline their processes.
Share This Article