How to Start a ConversionQA Job
By default, requests are handled synchronously i.e. the response waits for the conversion check to run and returns the change report.
For distributed systems, larger requests, etc you can start an asynchronous Job to handle the request and return to the result when it is finished.
Specifying An Async Job
Form Request
When using multipart/form-data
, set the parameter async
to true.
You can also use the parameters callback
and output
to specify a URL that will be called when the conversion check operation is complete, and where the result will be written to.
.....
Content-Disposition: form-data; name= "async"
true
--boundary
Content-Disposition: form-data; name= "callback"
http: //www.example.com/comparison-callback
--boundary
Content-Disposition: form-data; name= "output"
/Users/exampleUser/Documents/out.xml
--boundary
.....
XML Structured Request
When using XML requests, an asynchronous comparison will use the <async>
element to specify the optional values <callback>
and <output>
.
<callback>
provides a callback URL that the REST service will make aGET
request to after the comparison is complete. This is detailed in Callback below.<output>
allows you to specify a location for the result to be written to. For more information see I/O Types
<checkConversion>
<inputA type="http">
<uri>http://www.example.com/file1.dita</uri>
<dxFormat>xml</dxFormat>
</inputA>
<inputB type="http">
<uri>http://www.example.com/file2.dita</uri>
<dxFormat>xml</dxFormat>
</inputB>
<async>
<callback>http://www.example.com/comparison-callback</callback>
<output type="file">
<path>/Users/exampleUser/Documents/result.xml</path>
</output>
</async>
</checkConversion>
JSON Structured Request
When using JSON requests, an asynchronous comparison will use the async
object to specify the optional values callback
and output
.
callback
provides a callback URL that the REST service will make aGET
request to after the comparison is complete. This is detailed in Callback below.output
allows you to specify a location for the result to be written to. For more information see I/O Types
{
"inputA": {
"type": "http",
"uri": "http://www.example.com/file1.xml",
"dxFormat": "xml"
},
"inputB": {
"type": "http",
"uri": "http://www.example.com/file2.xml",
"dxFormat": "xml"
},
"async": {
"callback": "http://www.example.com/comparison-callback",
"output": {
"type": "file",
"path": "/Users/exampleUser/Documents/result.xml"
}
}
}
Response
The response will consist of the created Job, and a Location
header pointing to where you can poll the Job status.
Headers:
Location: http://localhost:8080/api/conversionqa/v1/jobs/d5192e56-60cc-44d7-b46b-192221b2210e
Body:
<job>
<jobId>d5192e56-60cc-44d7-b46b-192221b2210e</jobId>
<numberOfStages>0</numberOfStages>
<progressInPercentage>0.0</progressInPercentage>
<jobStatus>QUEUED</jobStatus>
</job>
Callback
If the user registered a callback URL with the comparison request, the REST service will attempt an HTTP GET
to that URL on completion of the comparison.
In this example the callback
URL http://www.example.com/conversion-check-callback
was registered in the comparison request - we will add a request parameter of jobId
which allows the Job resource to be located:
Request
GET http://www.example.com/conversion-check-callback?jobId=12346124
Reading the Job Object
For each async comparison a Job is created. The jobs can be read from the /jobs/{jobId}
endpoint. For example, you can poll for the Job's status:
Request
GET /api/conversionqa/v1/jobs/12346124
Response (XML)
<job>
<jobId>3180d315-fc13-42a4-a872-fca1126274b6</jobId>
<startTime>2021-11-15T13:50:58.528+0000</startTime>
<jobStatus>PROCESSING</jobStatus>
<totalNumberOfStages>23</totalNumberOfStages>
<currentStage>15</currentStage>
</job>
Response (JSON)
{
"jobId": 123456124,
"startTime": "2022-11-15T13:55:32.484+0000",
"jobStatus": "PROCESSING",
"totalNumberOfStages": 23,
"currentStage": 15
}
You can see that the comparison is currently in progress on stage 15 of 23, but some time later...
Response (XML)
<job>
<jobId>5e3e85ec-b1eb-45d8-9295-238767881e97</jobId>
<startTime>2022-11-15T13:55:32.484+0000</startTime>
<finishedTime>2022-11-15T13:55:44.249+0000</finishedTime>
<jobStatus>SUCCESS</jobStatus>
<output type="http">
<size>20409</size>
<uri>http://0.0.0.0:8080/api/conversionqa/v1/downloads/5e3e85ec-b1eb-45d8-9295-238767881e97</uri>
</output>
<totalNumberOfStages>23</totalNumberOfStages>
<currentStage>23</currentStage>
<isContentEqual>false</isContentEqual>
</job>
Response (JSON)
{
"jobId": 123456124,
"startTime": "2022-11-15T13:55:32.484+0000",
"finishedTime": "2022-11-15T13:55:44.249+0000",
"jobStatus": "SUCCESS",
"output: [
{
"size": 20409,
"uri":
}
]
"totalNumberOfStages": 23,
"currentStage": 23,
"isContentEqual": "false"
}
...the comparison is now finished.
Job Model
The Job contains the following objects:
Object | Description |
---|---|
| The ID of the Job |
| ISO 8601 timestamp when the operation started. Depending on the number of queued jobs, there may be significant time between |
| ISO 8601 timestamp when the operation started. |
| ISO 8601 timestamp of when the operation finished. |
| An enumeration of the state of the comparison. States include:
There are also two states for when a Job has failed or been deleted:
|
| true/false of whether the conversion check found all of the content to be equal. |
| Number of stages in the pipeline, as an integer. |
| The current stage of the operation. |
| Specifies where the result has been output to. |
| Contains error information if an error happened. See Error Handling for more information. |
When using Cloud I/O output
will contain the Cloud I/O information provided minus the client ID / secret information for security reasons, for example:
<output type="s3">
<region>EU-WEST-1</region>
<bucket>DeltaXML-Example-Bucket</bucket>
<fileName>output.xml</fileName>
</output>
If not using Cloud I/O for the output
, then it will contain a uri
and size
(which provides the result size in bytes - as an integer). For example:
<output type="http">
<uri>http://localhost:8080/api/conversionqa/v1/downloads/12346124</uri>
<size>390</size>
</output>
If the comparison failed, an error
element will contain details of the failure, including a stack trace which can help diagnose the issue. The size of the result is reported in terms of bytes.
Cancelling a Job
Jobs can be cancelled while they are queued or running, it is invoked by using a DELETE
request to the specified Job:
Request
DELETE /api/conversionqa/v1/jobs/12346124
The response will be the Job, note the jobStatus
is now CANCELLED
:
Response (XML)
<job>
<creationTime>2022-11-15T11:31:20.863+01:00</creationTime>
<jobStatus>CANCELLED</jobStatus>
<totalNumberOfStages>0</totalNumberOfStages>
</job>
Response (JSON)
{
"creationTime": "2022-11-15T11:31:20.863+01:00",
"jobStatus": "CANCELLED",
"totalNumberOfStages": 0
}
Downloading the Output
A GET
request to the output
uri
will then complete the asynchronous lifecycle:
Request
GET /api/conversionqa/v1/downloads/123456
Response
<html xmlns:deltaxml="http://www.deltaxml.com/ns/well-formed-delta-v1" xmlns:dxa="http://www.deltaxml.com/ns/non-namespaced-attribute" xmlns:dxx="http://www.deltaxml.com/ns/xml-namespaced-attribute" xmlns:format="http://www.deltaxml.com/ns/formatting" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" deltaxml:deltaV2="A!=B" deltaxml:version="2.0" deltaxml:content-type="full-context" schemaVersion="3.2" whiteSpaceMode="preserve" xsi:schemaLocation="http://www.typefi.com/ContentXML http://www.typefi.com/TPS/content/3_2/ContentXML.xsd" lang="en" data-deltaV2="A!=B">
<head>
<meta name="viewport" content="width=device-width, initial-scale=1"></meta>
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-KyZXEAg3QhqLMpG8r+8fhAXLRk2vvoC2f3B09zVXn8CA5QIVfZOJ3BCsw2P0p/We" crossorigin="anonymous"></link>
<script type="text/javascript" src="https://www.gstatic.com/charts/loader.js"></script>
<style>
.no-content-text {
color: gray;
font-size: .75em;
font-style: italic;
}
....
Note
If the POST request specified an output file location, the output file will be available at that location after a successful asynchronous comparison. A GET request from the downloads resource will return an error response specifying that the result has been written to the output location specified in the request.