PrizmDoc Viewer v13.17 - Updated
API Reference / PAS REST API / Application Development / Viewing Package Creators
In This Topic
    Viewing Package Creators
    In This Topic

    Introduction

    The viewing package creators REST API allows your application to create new viewing packages (to manage existing viewing packages, use the viewing packages REST API).

    A viewing package contains fully pre-converted, browser-ready content for a document. If you know ahead of time which documents are going to be viewed and you want to make the viewing experience as fast as possible for your users, you can create viewing packages ahead of time for your documents. Later, when you need to create a viewing session for a document, simply use the same documentId you used when creating the viewing package and PAS will use the pre-converted content from the viewing package.

    NOTE: Creating viewing packages requires you to configure a database. See PAS Configuration for more information.

    Available URLs

    URL Description
    POST /v2/viewingPackageCreators Creates a new viewing package creator process.
    PUT /v2/viewingPackageCreators/{processId}/SourceFile Uploads the source document to use when creating the viewing package.
    GET /v2/viewingPackageCreators/{processId} Gets the status of a viewing package creator process.

    POST /v2/viewingPackageCreators

    Starts a new viewing package creator process.

    Request

    Request Headers

    Name Description
    Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

    Request Body

    JSON object conforming to the following:

    Property Type Required Description
    input.source {object} Yes Properties relevant to PAS will reside in this object. > NOTE: This object will be removed before sending the rest of the body to the PrizmDoc Services.
    input.source.documentId {string} Yes A customer supplied identifier which is used to uniquely identify the resulting viewing package. The documentId is required to have a non-zero length less than 256 characters and must consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    input.source.type {string} Yes Specify where PrizmApplicationServices can find the document. The valid values are "document", "url", or "upload".
    input.source.fileName {string} Yes (If source.type="document") Filename that the Storage Provider API can use.
    input.source.url {string} Yes (If source.type="url") URL to create a viewing session from.
    input.source.headers {object} Optional (Used if source.type="url") Request headers to send from PrizmApplicationServices when retrieving the URL.
    input.source.acceptBadSslCertificate {boolean=false} Optional (Used if source.type="url") If true, requires SSL certificates be valid. > NOTE: to use your own certificate authority (CA), you need to specify an agent that was created with that CA as an option.
    input.source.displayName {string} Yes (if source.type="upload") The display name of the document that's being uploaded. E.g. "sample.doc"
    input.source.markupId {string} Optional The ID to use when querying markup with the XML and JSON layer APIs. If the ID is not provided, we create a new one from the other information we are given. The markupId is required to have a non-zero length, should be less than 256 characters, and should consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet.
    input.source.downloadName {string} Optional The name that will be used when downloading the original document. We will use the "displayName" or "fileName" if this option is not provided.
    input.source.fileExtension {string} Optional A file extension that is used if the File Detection Service cannot determine what type of file was uploaded. We will get the extension from "displayName" or "fileName" if this option is not provided. > NOTE: This parameter may only include alpha-numeric characters.
    input.viewingPackageLifetime {integer} Optional Defines the minimum number of integer seconds for the created content to remain available. By default this is 24 hours (if not configured differently through PAS Configuration). If set to 0, the content will remain available perpetually.
    input.render {object} Optional The object that describes rendering options.
    input.render.html5 {object} Optional The object that describes rendering options for the HTML5 viewer. A whitelist of the following render properties is used: svgMaxImageSize and vectorTolerance. They are described in the PrizmDoc Server Viewing Session documentation.
    minSecondsAvailable {integer} Optional The minimum number of seconds this viewing package creator will remain available so you can GET its status. The actual lifetime may be longer.

    Examples

    Create a Viewing Package using a local document

    POST pas_base_url/v2/viewingPackageCreators
    Content-Type: application/json
    
    {
        "input": {
            "source": {
                "type": "document",
                "fileName": "sample.doc",
                "documentId": "unT67Fxekm8lk1p0kPnyg8",
                ...
            },
            "viewingPackageLifetime": 2592000
        }
    }
    

    Successful Response

    HTTP/1.1 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
    }
    
    

    The response, along with other information, includes a new processId which is used to GET information about the converted content.

    Error Responses

    Duplicate POST Prior to Process Completion:

    If a POST request is made with a body containing the exact same content as a request prior to the completion of the original process, an error similar to the one below will be returned.

    HTTP/1.1 580 ConversionInProgress
    Content-Type: application/json
    
    {
        "errorCode": "ConversionInProgress"
    }
    
    

    Duplicate POST After Process Completion:

    If a POST request is made with a body containing the exact same content as a prior request after that request has completed, the following error similar to the one below will be returned.

    HTTP/1.1 580 DocumentIdAlreadyInUse
    Content-Type: application/json
    
    {
        "errorCode": "DocumentIdAlreadyInUse"
    }
    
    

    NOTE: An existing package must be deleted before re-submitting the same content for conversion.

    Examples of Input Validation error responses:

    HTTP/1.1 480 MissingInput
    Content-Type: application/json
    
    {
        "errorCode": "MissingInput",
        "errorDetails": {
            "in": "body",
            "at": "input"
        }
    }
    
    
    HTTP/1.1 480 InvalidInput
    Content-Type: application/json
    
    {
        "errorCode": "InvalidInput",
        "errorDetails": {
            "in": "body",
            "at": "input",
            "expected": {
                "type": "object"
            }
        }
    }
    
    

    If you are self-hosting PAS and a POST request does not include the correct Accusoft-Secret header value, you will receive an error like the one below. See PAS Configuration for more info about configuring your PAS secretKey.

    HTTP/1.1 403 InvalidSecret
    Content-Type: application/json
    
    {
        "errorCode": "InvalidSecret"
    }
    
    

    Create a Viewing Package with extra options

    PrizmDoc Server allows for render options that modify the output of the conversion process. The valid options are documented at the top of this page, but as an example, this is what a request would look like if you only wanted raster content:

    NOTE: When creating a viewing package, watermarks cannot be used and will return an error.

    POST pas_base_url/v2/viewingPackageCreators
    Content-Type: application/json
    
    {
        "input": {
            "source": {
                "type": "document",
                "fileName": "sample.doc",
                "documentId": "unT67Fxekm8lk1p0kPnyg8",
                ...
            },
            "viewingPackageLifetime": 2592000
        }
    }
    

    Successful Response

    HTTP/1.1 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
    }
    
    

    Error Responses

    Watermarks Input:

    The input.watermarks property cannot be used when creating a viewing package.

    HTTP/1.1 480 ReservedInput
    Content-Type: application/json
    
    {
        "errorCode": "ReservedInput",
        "errorDetails": {
            "in": "body",
            "at": "input.watermarks"
        }
    }
    
    

    PUT /v2/viewingPackageCreators/{processId}/SourceFile

    Uploads the source document to use when creating the viewing package.

    Request

    Request Headers

    Name Description
    Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

    Request Body

    The source document to use.

    A request to this URL allows the user to upload a document to an existing viewing package creator which has not yet been provided a source document. When a viewing package creator is configured with input.source.type: 'upload', viewing package creation waits until a PUT request containing the source document is received. After the source document has been successfully uploaded, viewing package creation will resume.

    Examples

    PUT pas_base_url/v2/viewingPackageCreators/khjyrfKLj2g6gv8fdqg710/SourceFile
    Content-Type: application/octet-stream
    
    <<file bytes>>
    

    Successful Response

    HTTP/1.1 200 OK
    
    

    Error Responses

    When uploading a document for viewing package creation, the following errors may be encountered:

    PUT When Not Allowed

    If a PUT request is made to upload a file for a viewing package creator which does not have input.source.type: 'upload', then the following error will be returned.

    HTTP/1.1 580 NotSupportedForViewingPackageSourceType
    Content-Type: application/json
    
    {
        "errorCode": "NotSupportedForViewingPackageSourceType"
    }
    
    

    PUT When File Already Provided

    If a PUT request is made to upload a file for a viewing package creator after a file has already been uploaded for that viewing package creator, then the following error will be returned.

    HTTP/1.1 580 SourceFileAlreadyProvided
    Content-Type: application/json
    
    {
        "errorCode": "SourceFileAlreadyProvided"
    }
    
    

    If you are self-hosting PAS and a PUT request does not include the correct Accusoft-Secret header value, you will receive an error like the one below. See PAS Configuration for more info about configuring your PAS secretKey.

    HTTP/1.1 403 InvalidSecret
    Content-Type: application/json
    
    {
        "errorCode": "InvalidSecret"
    }
    
    

    GET /v2/viewingPackageCreators/{processId}

    Gets the status of a viewing package creator process.

    Requests to this URL can be sent repeatedly while the state="processing". To limit network congestion, an exponential back-off algorithm is recommended. This means that the time interval between each request is increased, which results in a good trade-off between quickly discovering short conversions that have completed and preventing a large number of requests for long conversions.

    Upon successful package creation, the response will have the state="complete" with percentComplete=100. The errorCode will be null. Additionally it will include an output property which will contain the created package expiration time. If there is an error during processing, the state="error" with percentComplete=100. The exception to this is, some but not all page failures. In this case the state is set to "complete".

    Request

    Request Headers

    Name Description
    Accusoft-Secret Required only if you are self-hosting PAS, must match the value of secretKey in your PAS config file.

    Examples

    GET pas_base_url/v2/viewingPackageCreators/khjyrfKLj2g6gv8fdqg710
    

    Viewing package creation completed successfully

    A response for a package that was successfully generated would look like this:

    HTTP/1.1 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
    }
    
    

    The viewing package creation process may encounter three types of errors, which it will report on as follows:

    Source document not found

    This error describes the conversion result for a nonexistent document. Note that upon completion in this error case, the state is set to "error" because no content could be provided for the document. Additionally, an errorCode property will be provided indicating this is the cause of the error. No output property will be provided when the process completes in an error state.

    HTTP/1.1 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": "error",
        "percentComplete": 100,
        "errorCode": "DocumentNotFound"
    }
    
    

    Incorrect password for source document

    This error describes the conversion result for a password-protected document, which is not supported in this release. A password property may be provided in the request, but it will not be used. Upon completion in this error case, the state is set to "error" because no content could be provided for the document. An errorCode property will be provided indicating an "InternalError". No output property will be provided when the process completes in an error state.

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "source": {
                "type": "document",
                "fileName": "sample.pdf",
                "documentId": "unT67Fxekm8lk1p0kPnyg8",
                . . .
            },
            "password": "opensesame",
            "viewingPackageLifetime": 2592000
        },
        "expirationDateTime": "2015-12-09T06:22:18.624Z",
        "processId": "khjyrfKLj2g6gv8fdqg710",
        "state": "error",
        "percentComplete": 100,
        "errorCode": "InternalError"
    }
    
    

    Individual page conversion failures

    These errors will not mark the entire package as errored, but rather report in the output object in a pageFailures array.

    HTTP/1.1 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",
            "pageFailures": [
                {
                    "errorCode": "CouldNotRetrievePngContent",
                    "pageNumber": "4"
                },
                {
                    "errorCode": "CouldNotRetrieveSvgaContent",
                    "pageNumber": "5"
                },
                {
                    "errorCode": "CouldNotRetrieveTextContent",
                    "pageNumber": "8"
                }
            ]
        },
        "expirationDateTime": "2015-12-09T06:22:18.624Z",
        "processId": "khjyrfKLj2g6gv8fdqg710",
        "state": "complete",
        "percentComplete": 100
    }
    
    

    Attachment failures

    These errors describe the failure of the conversion to provide an artifact for an attachment in the case where a document supports attachments, such as .EML or .MSG.

    If the conversion process finds attachments associated with the document, but the process is unable to provide content for one or more pages, then the state is set to "complete" and an array of attachments is returned as a property in the body.

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {
        "input": {
            "source": {
                "type": "document",
                "fileName": "sample.eml",
                "documentId": "unT67Fxekm8lk1p0kPnyg8",
                . . .
            },
            "viewingPackageLifetime": 2592000
        },
        "output": {
            "packageExpirationDateTime": "2016-1-09T06:22:18.624Z",
            "attachments": [
                {
                    "name": "text-file",
                    "errorCode": "ArtifactCouldNotBeRetrieved"
                },
                {
                    "name": "document-text.pdf"
                },
                {
                    "name": "last-pages-dont-exist.pdf",
                    "errorCode": "CouldNotConvertSourceDocument"
                }
            ]
        },
        "expirationDateTime": "2015-12-09T06:22:18.624Z",
        "processId": "khjyrfKLj2g6gv8fdqg710",
        "state": "complete",
        "percentComplete": 100
    }
    
    

    Error Responses

    If you are self-hosting PAS and a GET request does not include the correct Accusoft-Secret header value, you will receive an error like the one below. See PAS Configuration for more info about configuring your PAS secretKey.

    HTTP/1.1 403 InvalidSecret
    Content-Type: application/json
    
    {
        "errorCode": "InvalidSecret"
    }