PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PrizmDoc Server REST API / Pre-Conversion to PDF Support / "v3" Viewing Package Creators
In This Topic
    "v3" Viewing Package Creators
    In This Topic

    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 Client. If you need to pre-convert a document for the PrizmDoc 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 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

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

    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
    }