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.

CODE

.....
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 a GET 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

XML

<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 a GET 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

JSON

{
  "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.

CODE

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

CODE

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

CODE

GET /api/conversionqa/v1/jobs/12346124

Response (XML)

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)

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)

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)

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
`jobId`	The ID of the Job
`creationTime`	ISO 8601 timestamp when the operation started. Depending on the number of queued jobs, there may be significant time between `creationTime` and `startTime`
`startTime`	ISO 8601 timestamp when the operation started.
`finishedTime`	ISO 8601 timestamp of when the operation finished.
`jobStatus`	An enumeration of the state of the comparison. States include: QUEUED SUBMITTED STARTED INPUTS_LOADING_A INPUTS_LOADING_B INPUT_FILTERS CHECK_RUNNING OUTPUT_FILTERS SAVING FINISHED There are also two states for when a Job has failed or been deleted: FAILED DELETED
`isContentEqual`	true/false of whether the conversion check found all of the content to be equal.
`totalNumberOfStages`	Number of stages in the pipeline, as an integer.
`currentStage`	The current stage of the operation.
`output`	Specifies where the result has been output to.
`error`	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:

CODE

<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:

CODE

<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

CODE

DELETE /api/conversionqa/v1/jobs/12346124

The response will be the Job, note the jobStatus is now CANCELLED:

Response (XML)

XML

<job>
  <creationTime>2022-11-15T11:31:20.863+01:00</creationTime>
  <jobStatus>CANCELLED</jobStatus>
  <totalNumberOfStages>0</totalNumberOfStages>
</job>

Response (JSON)

CODE

{
  "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

CODE

GET /api/conversionqa/v1/downloads/123456

Response

HTML

<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.