PrizmDoc® v14.1 Release - Updated
PrizmDoc / API Reference / PAS REST API / Viewer Support / Content Converters
In This Topic
    Content Converters
    In This Topic

    Introduction

    The content converters REST API is used by our viewer to allow the user to download the document they are viewing as a PDF.

    This REST API is designed for our viewer. If your application needs to convert a document to a different format, we recommend you use PrizmDoc Server’s content converters REST API instead. It offers more options and does not require the use of a viewing session.

    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
    
    

    NOTE: See the Base URL for PAS topic for more information.

    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
    
    

    NOTE: See the Base URL for PAS topic for more information.

    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
    
    

    NOTE: See the Base URL for PAS topic for more information.

    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