PrizmDoc
Viewing Package Creators
API Reference > PrizmDoc Application Services PAS RESTful API > Viewing Package Creators

Pre-Conversion Services developer preview

Pre-Conversion Services are included as a "Developer Preview." This feature is in late-stage development and api's marked as such should be used for evaluation purposes only and should not be used in production deployments. Note that these api's may undergo change prior to feature completion. The Pre-Conversion Services will be feature complete in PrizmDoc version 11.2. The Viewing Package Creator API provides a facility to fully convert a document for viewing prior to the creation of a Viewing Session. If a large document is converted for viewing at the time a Viewing Session is created, the user may experience a delay when viewing later pages in the document. By converting a document prior to viewing, the entire document is available for viewing immediately.

Viewing Package Creators

The Viewing Package Creator API provides a facility to fully convert a document for viewing prior to the creation of a Viewing Session. If a large document is converted for viewing at the time a Viewing Session is created, the user may experience a delay when viewing later pages in the document. By converting a document prior to viewing, the entire document is available for viewing immediately.

Note that these routes do not have route keys, as they cannot be re-routed.

POST /v2/viewingPackageCreators

Headers:

Body: a JSON object

The table below shows all the properties available for the POST Request:

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 backend 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, 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-2015-09-30T19:17:24Z.doc"
input.source.markupId {string} Optional The ID to use when querying markup with the XML and JSON layer APIs. If one isn't passed, we create one from the other information we're given.
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's 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.
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 set to 0, 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: alwaysUseRaster, rasterResolution, svgMaxImageSize and vectorTolerance. They are described in the PrizmDoc Server Viewing Session documentation.
minSecondsAvailable {integer} Optional (if a value is not provided, the default value = 3600 seconds will be used) Defines the minimum number of seconds for the conversion process to remain available to GET status. By default this is 3600 seconds because by default, the Viewing Sessions timeout after 20m.

Examples

Create a ViewingPackage using a local document

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

Successful Response:

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.

Errored 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.

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.

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

480 MissingInput
Content-Type: application/json
{
    "errorCode": "MissingInput",
    "errorDetails": {
        "in": "body",
        "at": "input"
    }
}


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

If a POST request is made with either a missing or an invalid header Accusoft-Secret, an error similar to the one below will be returned.

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

Create a ViewingPackage 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 http://localhost:3000/v2/viewingPackageCreators
Content-Type: application/json
{
    "input": {
        "source": {
            "type": "document",
            "fileName": "sample.doc",
            "documentId": "unT67Fxekm8lk1p0kPnyg8",
            . . .
        },
        "render": {
            "html5": {
                "alwaysUseRaster": true
            }
        },
        "viewingPackageLifetime": 2592000
    }
}

Successful Response:

200 OK
Content-Type: application/json
{
    "input": {
        "source": {
            "type": "document",
            "fileName": "sample.doc",
            "documentId": "unT67Fxekm8lk1p0kPnyg8",
            . . .
        },
        "render": {
            "html5": {
                "alwaysUseRaster": true
            }
        },
        "viewingPackageLifetime": 2592000
    },
    "expirationDateTime": "2015-12-09T06:22:18.624Z",
    "processId": "khjyrfKLj2g6gv8fdqg710",
    "state": "processing",
    "percentComplete": 0
}

Errored Responses:

Watermarks Input:

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

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

PUT /v2/viewingPackageCreators/{processId}/SourceFile

Headers:

Body: a source document of Content-Type application/octet-stream

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 http://localhost:3000/v2/viewingPackageCreators/khjyrfKLj2g6gv8fdqg710/SourceFile
   Content-Type: application/octet-stream
   Body: a document

Successful Response:

200 OK

Errored 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.

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.

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

If a PUT request is made with either a missing or an invalid header Accusoft-Secret, an error similar to the one below will be returned.

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

GET /v2/viewingPackageCreators/{processId}

Headers:

Gets the status of an existing viewing package creator.

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".

Examples

GET http://localhost:3000/v2/viewingPackageCreators/khjyrfKLj2g6gv8fdqg710

Successful Response:

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

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:

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"
}


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"
}


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": "CouldNotProvideRasterContent",
                "pageNumber": "4"
            },
            {
                "errorCode": "CouldNotProvideSvgaContent",
                "pageNumber": "5"
            },
            {
                "errorCode": "CouldNotProvideTextContent",
                "pageNumber": "8"
            }
        ]
    },
    "expirationDateTime": "2015-12-09T06:22:18.624Z",
    "processId": "khjyrfKLj2g6gv8fdqg710",
    "state": "complete",
    "percentComplete": 100
}


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",
        "attachments": [
            {
                "name": letter.doc",
                "pageFailures": [
                    {
                        "errorCode" : "CouldNotProvideRasterContent",
                        "pageNumber" : "2"
                    },
                    {
                        "errorCode" : "CouldNotProvideSvgaContent",
                        "pageNumber" : "4"  
                    }
                ]
            },
            {
                "name": "re.eml",
                "attachments": [
                    {
                        "name": "budget1997.xls"
                    }
                ]
            },
            {
                "name": "some-exe",
                "errorCode": "UnrecognizedFileFormat"
            }
        ]
    },
    "expirationDateTime": "2015-12-09T06:22:18.624Z",
    "processId": "khjyrfKLj2g6gv8fdqg710",
    "state": "complete",
    "percentComplete": 100
}

Errored Response:

If a GET request is made with either a missing or an invalid header Accusoft-Secret, an error similar to the one below will be returned.

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

 

 

©2016. Accusoft Corporation. All Rights Reserved.

Send Feedback