Getting the Result Document
This section:
•Result Document containing URIs of error documents
•Result Document containing URIs of output documents
•Result Document containing no URI
•Accessing error and output documents listed in the Result Document
The Result Document URI
A result document will be created every time a job is created, no matter whether the result of a job (for example, a validation) is positive (document valid) or negative (document invalid). In both cases a 201 Created message is returned. This message will be in JSON format and will contain a relative URI of the result document. The JSON fragment will look something like this:
{
"result": "/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB",
"jobid": "E6C4262D-8ADB-49CB-8693-990DF79EABEB"
}
The result object contains the relative URI of the result document. The URI is relative to the server address. For example, if the server address is http://localhost:8087/ (the initial configuration address), then the expanded URI of the result document specified in the listing above will be:
http://localhost:8087/v1/results/E6C4262D-8ADB-49CB-8693-990DF79EABEB
| Note: | The correct version number /vN is the one that the server returns (and is not necessarily the one in this documentation). The number that the server returns is the version number of the current HTTP interface. Previous version numbers indicate older versions of the HTTP interface, which, however, are still supported for backward compatibility. |
Fetching the Result Document
To get the result document submit the document's expanded URI (see above), in an HTTP GET request. The result document is returned and could be one of the generic types described below.
| Note: | When a job is successfully placed in the server queue, the server returns the URI of the result document. If the client requests the result before the job has been started (it is still in the queue), a "status": "Dispatched" message will be returned. If the job has been started but not completed (say, because it is a large job), a "status": "Running" message will be returned. In these two situations, the client should wait for some time before making a fresh request for the result document. |
| Note: | The example documents below all assume restricted client access. So error documents, message documents, and output documents are all assumed to be saved in the relevant job directory on the server. The URIs for them in the result document are therefore all relative URIs. None is a file URI (which would be the kind of URI generated in cases of unrestricted client access). For the details of these URIs, see the section Getting Error/Message/Output Documents. |
Result document containing URIs of error documents
If the requested job finished with a state of Failed, then the job returned a negative result. For example, a validation job returned a document-invalid result. The errors encountered while executing the job are stored in error logs, created in three file formats: (i) text, (ii) long-XML (detailed error log), and (iii) short-XML (less-detailed error log). See the JSON listing below.
{
"jobid": "6B4EE31B-FAC9-4834-B50A-582FABF47B58",
"state": "Failed",
"error":
{
"text": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/error.txt",
"longxml": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/long.xml",
"shortxml": "/v1/results/6B4EE31B-FAC9-4834-B50A-582FABF47B58/error/short.xml"
},
"jobs":
[
{
"file": "file:///c:/Test/ExpReport.xml",
"jobid": "20008201-219F-4790-BB59-C091C276FED2",
"output":
{
},
"state": "Failed",
"error":
{
"text": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/error.txt",
"longxml": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/long.xml",
"shortxml": "/v1/results/20008201-219F-4790-BB59-C091C276FED2/error/short.xml"
}
}
]
}
Note the following:
•Jobs have sub-jobs.
•Errors at sub-job level propagate up to the top-level job. The state of the top-level job will be OK only if all of its sub-jobs have a state of OK.
•Each job or sub-job has its own error log.
•Error logs include warning logs. So, even though a job finishes with a state of OK, it might have URIs of error files.
•The URIs of the error files are relative to the server address (see above).
Result document containing URIs of output documents
If the requested job finished with a state of OK, then the job returned a positive result. For example, a validation job returned a document-valid result. If the job produced an output document—for example, the result of an XSLT transformation—then the URI of the output document is returned. See the JSON listing below.
{
"jobid": "5E47A3E9-D229-42F9-83B4-CC11F8366466",
"state": "OK",
"error":
{
},
"jobs":
[
{
"file": "file:///c:/Test/SimpleExample.xml",
"jobid": "D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8",
"output":
{
"xslt-output-file":
[
"/v1/results/D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8/output/1"
]
},
"state": "OK",
"output-mapping":
{
"/v1/results/D34B5684-C6FF-4A7A-BF35-EBB9A8A8C2C8/output/1": "file:///c:/temp/test.html"
},
"error":
{
}
}
]
}
Note the following:
•The output file is created in the output folder of the job. You can use its relative URI to access the file.
•The URIs of the output files are relative to the server address (see above).
•The output-mapping item maps the output document in the job directory on the server to the file location specified by the client in the job request. Notice that only output documents specified by the client in the job request have a mapping; job-related files generated by the server (such as error files) have no mapping.
•Alternatively, it is possible to retrieve all the generated result documents for a specific job as a zip archive using the URL "/v1/results/JOBID/output/zip". This feature is not available in unrestricted filesystem mode. Please note that the zip archive will contain mangled file names, which need to be mapped back to the actual names using the output-mapping object.
Result document containing no URI
If the requested job finished with a state of OK, then the job returned a positive result. For example, a validation job returned a document-valid result. Some jobs—such as a validation or well-formed-test—produce no output document. If a job of this type finishes with a state of OK, then the result document will have neither the URI of an output document nor the URI of an error log. See the JSON listing below.
{
"jobid": "3FC8B90E-A2E5-427B-B9E9-27CB7BB6B405",
"state": "OK",
"error":
{
},
"jobs":
[
{
"file": "file:///c:/Test/SimpleExample.xml",
"jobid": "532F14A9-F9F8-4FED-BCDA-16A17A848FEA",
"output":
{
},
"state": "OK",
"error":
{
}
}
]
}
Note the following:
•Both the output and error components of the sub-job in the listing above are empty.
•A job could finish with a state of OK but still contain warnings or other messages, which are logged in error files. In such cases, the result document will contain URIs of error files even though the job finished with a state of OK.
Accessing error and output documents listed in the Result Document
Error and output documents can be accessed with HTTP GET requests. These are described in the next section, Getting Error/Output Documents.