PrizmDoc Viewer v13.11 Release - Updated
Content Converters
API Reference > PAS REST API > Content Converters

Introduction

Available URLs

URL Description
POST /v2/viewingSessions/{viewingSessionId}/contentConverters Starts a conversion process for the source document of a particular viewing session.
GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId} Gets the status of the specific converter process.
GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}/results/{index}/file?ContentDispositionFilename={fileName} Gets the contents of a file produced by the converter process.

POST /v2/viewingSessions/{viewingSessionId}/contentConverters

Routes key: CreateContentConverterV2

Starts a conversion process for the source document of a particular viewing session. This URL has the following parameters:

Parameter Description
{viewingSessionId} The ID provided in the response from POST /ViewingSession.

Request

Body: Empty. An error will be returned if any data is present.

NOTE: PDF is currently the only supported destination format. A successful response will include several input properties as shown below. A future release will allow these properties to be set in the request body to create various kinds of output.

Response

Body: a JSON object with the following properties:

Property Type Description
input {object} An object that specifies the input used for the conversion.
input.dest {object} An object that specifies the destination file format and any additional details which control how the content is converted.
input.dest.format {string} Specifies the output file format.
input.dest.pdfOptions {object} An object that specifies additional options when input.dest.format is "pdf".
input.dest.pdfOptions.forceOneFilePerPage {boolean} If true, the conversion process will produce single-page PDF files, one file for each page of content (instead of a single PDF with multiple pages). Default is false.
input.sources {object} An array of objects, one for each input file.
input.sources[n].pages {string} The page numbers and/or page ranges, separated by commas, of the source document to convert.
processId {string} The id of the contentConverter resource which represents the file conversion operation.
state {string} The current state of the conversion process, which will be one of the following: "processing", "complete", or "error". If "processing", the conversion is still in progress. If "complete", the conversion has completed successfully. If "error", the conversion failed due to a problem. For the initial POST, this value will almost always be "processing". Results are typically only available with a subsequent GET.
percentComplete {integer} An integer from 0 to 100 that indicates what percentage of the conversion is complete.
errorCode {string} An error code string if a problem occurred during the conversion process.

Examples

POST pas_base_url/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters

Successful Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "expirationDateTime": "2015-11-04T19:20:09.280Z",
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "processing",
    "percentComplete": 0
}

Errored Responses

When a response with a status code of 580 is received check the response body for details:

HTTP/1.1 580 InternalError
Content-Type: application/json

{
    "errorCode": "InternalError"
}

When a viewing session does not exist for the given viewingSessionId:

HTTP/1.1 404 Not Found

When any data is present in the body of the request:

HTTP/1.1 480 ReservedInput
Content-Type: application/json

{
    "errorCode": "ReservedInput",
    "errorDetails": {
        "in": "body"
    }
}

When the server's license could not be verified:

HTTP/1.1 480 LicenseCouldNotBeVerified
Content-Type: application/json

{
    "errorCode": "LicenseCouldNotBeVerified"
}

GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}

Routes key: PollContentConverterV2

Gets the status of the specific converter process. This URL has the following parameters:

Parameter Description
{viewingSessionId} The ID provided in the response from POST /ViewingSession.
{processId} The ID provided in the response from POST /v2/viewingSessions/{viewingSessionId}/contentConverters.

Response

Body: a JSON object with the following properties:

Property Type Description
input {object} An object that specifies the input used for the conversion.
input.dest {object} An object that specifies the destination file format and any additional details which control how the content is converted.
input.dest.format {string} Specifies the output file format.
input.dest.pdfOptions {object} An object that specifies additional options when input.dest.format is "pdf".
input.dest.pdfOptions.forceOneFilePerPage {boolean} If true, the conversion process will produce single-page PDF files, one file for each page of content (instead of a single PDF with multiple pages). Default is false.
input.sources {object} An array of objects, one for each input file.
input.sources[n].pages {string} The page numbers and/or page ranges, separated by commas, of the source document to convert.
processId {string} The id of the contentConverter resource which represents the file conversion operation.
state {string} The current state of the conversion process, which will be one of the following: "processing", "complete", or "error". If "processing", the conversion is still in progress. If "complete", the conversion has completed successfully. If "error", the conversion failed due to a problem.
percentComplete {integer} An integer from 0 to 100 that indicates what percentage of the conversion is complete.
errorCode {string} An error code string if a problem occurred during the conversion process.
output.results {object} An array of objects, one for each output file created. The 0-based index of each output file will be used in the URL GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}/results/{index}/file to retrieve the contents of each file.
output.results[n].sources {object} An array of objects, one for each source file which contributed to this output file.
output.results[n].sources[n].pages {string} The page or pages used from the source file. This will be a string value using one-based indexing. For example, if the output file represents page 2 of the source document, pages would have a value of "2". If the output file represents all 20 pages of a source document, pages would have a value of "1-20".
output.results[n].pageCount {integer} The total number of pages in the output file.

Example

GET pas_base_url/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA

Successful Response

When the converter process completes with no conversion failures:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "complete",
    "percentComplete": 100,
    "output": {
        "results": [
            {
                "fileId": "eOsJIqI8aHkxVV0yJug",
                "sources": [
                    {
                        "pages": "1-4"
                    }
                ],
                "pageCount": 4
            }
        ]
    }
}

When the converter process completes with a failure:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "input": {
        "dest": {
            "format": "pdf",
            "pdfOptions": {
                "forceOneFilePerPage": false
            }
        },
        "sources": [
            {
                "pages": ""
            }
        ]
    },
    "processId": "mxivIVSw7UhtL1yWwt3QEA",
    "state": "error",
    "percentComplete": 100,
    "errorCode": "CouldNotConvert",
    "output": {
        "results": [
            {
                "errorCode": "CouldNotConvertPage",
                "sources": [
                    {
                        "pages": "3"
                    }
                ]
            }
        ]
    }
}

Error Responses

When a response with a status code of 580 is received check the response body for details:

HTTP/1.1 580 InternalError
Content-Type: application/json

{
    "errorCode": "InternalError"
}

When a converter process does not exist for the given processId:

HTTP/1.1 404 Not Found

GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}/results/{index}/file?ContentDispositionFilename={fileName}

Routes key: GetContentConverterOutputFileV2

Gets the contents of a file produced by the converter process. This URL has the following parameters:

Parameter Description
{viewingSessionId} The ID provided in the response from POST /ViewingSession.
{processId} The ID provided in the response from POST /v2/viewingSessions/{viewingSessionId}/contentConverters.
{index} The 0-based index of the result file, originating from its position in the response.output.results array in the response from GET /v2/viewingSessions/{viewingSessionId}/contentConverters/{processId}.
{fileName} The filename as a URL-encoded string, without extension, to be used in the Content-Disposition response header (the appropriate file extension such as pdf will be appended automatically).

Response Headers

Name Description
Content-Disposition Specifies 'attachment' disposition, RFC-2183 compatible filename parameter and an RFC-8187 compatible filename* parameter, allowing the use of non-ASCII filenames.
Content-Type The most-specific MIME type for the returned document.

Response Body

The raw bytes of the result document.

Example

GET pas_base_url/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA/results/0/file?ContentDispositionFilename=MyFile

Successful Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="Greek____.pdf"; filename*=UTF-8''Greek%CE%91%CE%92%CE%93%CE%94.pdf


<<PDF data>>

Error Responses

When an output file does not exist for the given index:

HTTP/1.1 404 Not Found