Introduction

The "v3" viewing package creators REST APIs allow you to pre-convert a document from any of the formats supported by PrizmDoc Server for viewing.

NOTE: These APIs are not for use with the PrizmDoc Viewer Client. If you need to pre-convert a document for the PrizmDoc Viewer client, use the PAS "v2" viewing package creators and viewing packages REST APIs instead (see Work with Viewing Packages in the PAS Developer Guide for more information).

NOTE: The "v3" viewing package creators and viewing packages REST APIs are currently only available for on-premise deployments.

NOTE: This feature is disabled by default. See Enable Pre-Conversion to PDF on how to enable and configure this feature.

Available URLs

POST /v3/viewingPackageCreators

Creates and starts a viewing package creation process which converts a document to a PDF.

The server process to create the viewing package is started by this request, but a response is sent before the process is complete. Use the GET /v3/viewingPackageCreators/{processId} URL below to get the state and results of an in-progress or completed viewing package creation process.

Request

Request Headers

Request Body

JSON object conforming to the following:

• input

  • source (Object) Required. Identifies which source document to use for the viewing package.
    • type (String) Required. How the source document will be provided. The only valid value is:
      • "workFile" - An existing work file will be used as the source document.
    • fileId (String) Required.. Id of the work file to use as the source document.
  • packageId (String) Required. Your own unique identifier for the new viewing package. Must be a string containing at least 1 and at most 255 characters and only consist of characters defined by RFC4648 - Base 64 Encoding with URL and Filename Safe Alphabet, not including the "=" padding character.

  • lifetimeAfterLastUse (String) Required Amount of time a viewing package will be kept after its most recent use, after which it will be automatically deleted. Value must be one of the following:

    • A string indicating a number of days, such as "30d" for 30 days. The string must be a positive integer followed by d for days.

      Each time the viewing package content is downloaded via GET /v3/viewingPackages/{packageId}/content/pdf, its lifetime will be increased to the current time plus lifetimeAfterLastUse. In other words, a viewing package will remain available as long as it is being frequently used.

    • "forever" to retain the package indefinitely.

• minSecondsAvailable (Integer) The minimum number of seconds the status of this viewing package creator will remain available via a GET request. The actual lifetime may be longer. The default lifetime is defined by the processIds.lifetime central configuration parameter.

Successful Response

Response body

JSON object with the following properties:

• input (Object) A copy of the request body input object.
• processId (String) Unique Id of the new viewing package creation process.
• expirationDateTime (String) Date and time (in ISO 8601 Extended Format) when the viewing package creator will be deleted. Note that the viewing package itself will continue to exist and be usable after this time.
• state (String) State of the viewing package creation process:
  • "queued" - The viewing package creation has been queued.
  • "processing" - The viewing package is being created.
• percentComplete (Integer) The percentage (0 – 100) complete of the viewing package creation process. The response will always be 0.
• affinityToken (String) Affinity token for this viewing package creation process. Present when clustering is enabled.

Error Responses

Example

In this first example, a source document is first uploaded as a work file, and assigned the Id "V2V5bGFuZC1ZdXRhbmkgU3BlY2lhbCBPcmRlciAjOTM3". When the viewing package creator is started, that work file id is provided as input.

Request

POST /v3/viewingPackageCreators
Content-Type: application/json

{
  "input": {
    "packageId": "RmluYWwgcmVwb3J0IG9mIHRoZSBjb21tZXJjaWFsIHN0YXJzaGlwIE5vc3Ryb21v",
    "source": {
      "type": "workFile",
      "fileId": "V2V5bGFuZC1ZdXRhbmkgU3BlY2lhbCBPcmRlciAjOTM3"
    },
    "lifetimeAfterLastUse": "30d"
  }
}

Response

HTTP 200 OK
Content-Type: application/json

{
  "processId": "SHVkc29uOiBHYW1lIG92ZXIgbWFuISBHYW1lIG92ZXIh",
  "expirationDateTime": "2092-01-07T12:00:00Z",
  "input": {
    "packageId": "RmluYWwgcmVwb3J0IG9mIHRoZSBjb21tZXJjaWFsIHN0YXJzaGlwIE5vc3Ryb21v",
    "source": {
      "type": "workFile",
      "fileId": "V2V5bGFuZC1ZdXRhbmkgU3BlY2lhbCBPcmRlciAjOTM3"
    },
    "lifetimeAfterLastUse": "30d"
  },
  "state": "processing",
  "percentComplete": 0
}

GET /v3/viewingPackageCreators/{processId}

Gets the state of a viewing package creation process started by POST /v3/viewingPackageCreators.

When state is "complete", you can use GET /v3/viewingPackages/{packageId}/content/pdf to get the output PDF.

If the viewing package creation process encountered an error, the state property will be "error" and the errorCode property will contain an error code string.

Request

Request Headers

URL Parameters

Response body

JSON object with the following properties:

• input (Object) A copy of the POST /v3/viewingPackageCreators request body input object we accepted to start the viewing package creation process.
• processId (String) Id of the viewing package creation process.
• expirationDateTime (String) Date and time (in ISO 8601 Extended Format) when the viewing package creator will be deleted. Note that this is not the expiration date of the viewing package, just the creation process.
• state (String) State of the viewing package creation process:
  • "queued" - The viewing package creation has been queued.
  • "processing" - The viewing package is still being created.
  • "complete" - The viewing package has been created and is ready for use.
  • "error" - An error occurred and the viewing package was not created.
• percentComplete (Integer) Progress of the viewing package creation process as an integer from 0 through 100. Will be 0 when state is "queued" or "processing" and 100 when state is "complete" or "error".
• errorCode (String) An error code string if a problem occurred during the viewing package creation process. Only present when state is "error".
• affinityToken (String) Affinity token for this viewing package creation process. Present when clustering is enabled.

Error Responses and JSON Error Codes

Example

Request

GET /v3/viewingPackageCreators/iFhSZRvrz2vtFjcTSi9Qlg

Response

When the viewing package creation process completes with no errors:

HTTP 200 OK
Content-Type: application/json

{
  "processId": "SHVkc29uOiBHYW1lIG92ZXIgbWFuISBHYW1lIG92ZXIh",
  "expirationDateTime": "2092-01-07T12:00:00Z",
  "input": {
    "packageId": "RmluYWwgcmVwb3J0IG9mIHRoZSBjb21tZXJjaWFsIHN0YXJzaGlwIE5vc3Ryb21v",
    "source": {
      "type": "workFile",
      "fileId": "V2V5bGFuZC1ZdXRhbmkgU3BlY2lhbCBPcmRlciAjOTM3"
    },
    "lifetimeAfterLastUse": "30d"
  },
  "state": "complete",
  "percentComplete": 100
}