PrizmDoc v12.4 - Updated
Content Converters

Content Converters

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 http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters

Successful Response:

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:

580 InternalError
Content-Type: application/json
{ 
    "errorCode": "InternalError"
}

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

404 Not Found

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

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

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.

Examples

GET http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA

Successful Response:

When the converter process completes with no conversion failures:

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:

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"
                    }
                ]
            }             
        ]
    }
}

Errored Responses:

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

580 InternalError
Content-Type: application/json
{ 
    "errorCode": "InternalError"
}

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

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 value that will be set for the Content-Disposition: filename header property in the response.

Examples

GET http://localhost:3000/v2/viewingSessions/ZGZhc2RmYXNkZmFzZGZkcw/contentConverters/mxivIVSw7UhtL1yWwt3QEA/results/0/file?ContentDispositionFilename=MyFile

Successful Response:

200 OK
Content-Disposition: attachment; filename=MyFile.pdf
Content-Type: {content type of the specific document}

Errored Responses:

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

404 Not Found