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