Introduction
DEPRECATION NOTICE: The "v3" viewing package creators REST APIs have been deprecated and will be removed in a future release.
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
URL | Description |
---|---|
POST /v3/viewingPackageCreators | Creates and starts a new viewing package creation process. |
GET /v3/viewingPackageCreators/{processId} | Gets the state of an existing viewing package creation process. |
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
Name | Description |
---|---|
Content-Type |
Must be application/json or application/json; charset=utf-8 |
Accusoft-Affinity-Token |
The affinityToken of the work file specified by input.source.fileId . Required when server clustering is enabled. |
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 byd
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 theprocessIds.lifetime
central configuration parameter.
Successful Response
Response body
JSON object with the following properties:
input
(Object) A copy of the request bodyinput
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 be0
.affinityToken
(String) Affinity token for this viewing package creation process. Present when clustering is enabled.
Error Responses
Status Code | JSON errorCode |
Description |
---|---|---|
480 |
"MissingBody" |
Request was expected to have a body, but the body was not provided. |
480 |
"MissingInput" |
A required input value was not provided. See errorDetails in the response body. |
480 |
"InvalidInput" |
An invalid input value was used. See errorDetails in the response body. |
480 |
"UnrecognizedInput" |
An unrecognized JSON property was provided. See errorDetails in the response body. |
480 |
"ResourceNotFound" |
The source document could not be acquired. See errorDetails in the response body. |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits. |
480 |
"PackageIdAlreadyInUse" |
There is already a viewing package for the specified packageId. This error code will be returned even if the previous viewing package is still in the creation process. |
480 |
"FeatureDisabled" |
The "v3" viewing packages feature has not been enabled. |
580 |
"InternalError" |
The server encountered an internal error when handling the request. |
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
Name | Description |
---|---|
Accusoft-Affinity-Token |
The affinityToken of the viewing package creation process. Required when server clustering is enabled. |
URL Parameters
Parameter | Description |
---|---|
{processId} |
Id of the viewing package creation process to check. |
Response body
JSON object with the following properties:
input
(Object) A copy of the POST /v3/viewingPackageCreators request bodyinput
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 from0
through100
. Will be0
whenstate
is"queued"
or"processing"
and100
whenstate
is"complete"
or"error"
.errorCode
(String) An error code string if a problem occurred during the viewing package creation process. Only present whenstate
is"error"
.affinityToken
(String) Affinity token for this viewing package creation process. Present when clustering is enabled.
Error Responses and JSON Error Codes
Status Code | JSON errorCode |
Description |
---|---|---|
404 |
"ResourceNotFound" |
No viewing package creator with the provided {processId} could be found. |
200 |
"CouldNotConvert" |
Could not convert the source document. |
200 |
"InvalidPassword" |
The document requires a password (password-protected documents are not yet supported by this API). |
480 |
"LicenseCouldNotBeVerified" |
The server's license could not be verified. If you are evaluating the product without a license, the product is running in evaluation mode and this particular part of the product is unavailable without a license. To obtain a license, contact us at info@accusoft.com. If you have a license, make sure you configured your license correctly, that your license has not expired, and that you have not exceeded any license limits. |
480 |
"FeatureDisabled" |
The "v3" viewing packages feature has not been enabled. |
580 |
"InternalError" |
The server encountered an internal error when handling the request. |
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
}