Example-6: XQuery Execution
This example uses PowerShell on Windows to execute an XQuery document on an XML document. Both documents are located in the examples folder of your application folder (RaptorXMLXBRLServer2024).
| Note: | The use of quotes may be different on other shells ('bash' works with the example when one uses 'curl' instead of 'curl.exe'). |
Submit the Inline-XBRL-validation POST request using CURL
Given below is an example CURL command for submitting an Inline XBRL validation request.
curl.exe -F 'msg={"command": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}};type=application/json' -F "additional-files=@CopyInput.xq;type=text/plain" -F "additional-files=@simple.xml;type=application/xml" http://localhost:8087/v1/queue
For easier readability:
(1) -F 'msg={
(2) "command": "xquery",
(3) "args": ["additional-files:///CopyInput.xq"],
(4) "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}
(5) };type=application/json'
(6) -F "additional-files=@CopyInput.xq;type=text/plain"
(7) -F "additional-files=@simple.xml;type=application/xml"
(7) http://localhost:8087/v1/queue
Input
The different parts of the CURL command are explained below, keyed to the callouts in the listing above.
(1) -F 'msg={...}' specifies a form field with name 'msg'
The -F option: (i) causes CURL to generate a multipart form post with Content-Type: multipart/form-data and (ii) causes this form field to be automatically added to the request header. We use a JSON object to describe the command that RaptorXML+XBRL Server should execute.
Content-Type: multipart/form-data; boundary=--------------------...
CURL translates this option in the HTTP request to:
Content-Disposition: form-data; name="msg"
Content-Type: application/json
{"command": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"input": "additional-files:///simple.xml", "output": "MyQueryResult"}}
(2) The RaptorXML+XBRL Server command to execute on the server. See the Command Line Interface (CLI) section for information about the commands that can be accepted here. In our example, the command for XQuery execution is XQuery.
(3) The command's arguments (as accepted by the RaptorXML+XBRL Server command line) are encoded as a JSON array. RaptorXML+XBRL Server uses an explicit scheme additional-files:// to reference additional resources inside a separate additional-files form field. In our example, we reference the XQuery document CopyInput.xq.
| Note: | All resources in the args array must be available on the server or submitted with the request, similar to (6 and 7). |
(4) The command's options (as accepted by the RaptorXML+XBRL Server command line) are encoded as a JSON object. If the default values of options are as you want them (see the CLI section), then this part can be left out. In our example, we specify (i) the XML file on which the XQuery is to be executed and (ii) the file where the output of the XQuery execution will be stored.
(5) The Content-Type of the msg form field is specified after the definition of the form field and is separated from it by a semicolon. In our example, the Content-Type of msg is given by: type=application/json.
(6, 7) Files that contain additional resources for the command can be specified using the additional-files form field. In our example, we specify two additional resources: (i) @CopyInput.xq, followed by a semicolon separator and then its Content-Type, which we give as type=text/plain; (i) simple.xml, followed by a semicolon separator and then its Content-Type, which we give as type=application/xml.
| Note: | Prefix the filename with @ to instruct CURL to (i) use the file name as the value of the filename property and (ii) the content of the file as the form's value. The additional-files form field can be supplied multiple times, once for each additional resource required by the command. CURL translates this option into the following in the HTTP request: |
Content-Disposition: form-data; name="additional-files"; filename="CopyInput.xq"
Content-Type: text/plain
<<content of CopyInput.xq>>
Content-Disposition: form-data; name="additional-files"; filename="simple.xml"
Content-Type: application/xml
<<content of simple.xml>>
| Note: | Files in other folders can be supplied by putting the relative path in front of the filename, like this: -F "additional-files=@Examples/CopyInput.xq;type=text/plain". However, when an additional file from another folder is specified in this way, it must be referenced using the file name only. For example: |
curl.exe -F 'msg={"command": "xquery", "args": ["additional-files:///CopyInput.xq"], "options": {"output": "MyQueryResult"}};type=application/json' -F "additional-files=@Examples/CopyInput.xq;type=text/plain" http://localhost:8087/v1/queue
If you want to preserve a folder structure, put the files in a ZIP folder and reference the files in the usual way for ZIP folders.
Output
The RaptorXML+XBRL Server output is a JSON object:
{"jobid": "42B8A75E-0180-4E05-B28F-7B46C6A0C686", "result": "/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686"}
The JSON object contains a jobid key and a result key. The value of the result key is the path to the result. This path must be appended to the <scheme>://<host>:<port> part used to submit the request. In our example, the full result URL would be: http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686. The result URL is also used to ask for the result of the command execution. See Getting the Result Document.
Get error/message/output of the POST request
The input command that is sent to get the error/message/output of the POST request (see Getting Error/Message/Output Documents) would be something like this:
curl.exe http://localhost:8087/v1/results/42B8A75E-0180-4E05-B28F-7B46C6A0C686
In our example, this command returns the following JSON object:
{"jobid":"42B8A75E-0180-4E05-B28F-7B46C6A0C686","state":"OK","error":{},"jobs":[{"file":"additional-files:///simple.xml","jobid":"768656F9-F4A1-4492-9676-C6226E30D998","output":{"result.trace_file":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/trace.log"],"xquery.main_output_files":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1"],"xquery.additional_output_files":[]},"state":"OK","output-mapping":{"/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1":"file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult"},"error":{}}]}
This is transcribed on separate lines below for easier readability and with callouts for easier referencing:
(1) {
(2) "jobid":"42B8A75E-0180-4E05-B28F-7B46C6A0C686",
(3) "state":"OK",
(4) "error":{},
(5) "jobs":[{
(6) "file":["additional-files:///simple.xml"],
(7) "jobid":"768656F9-F4A1-4492-9676-C6226E30D998",
(8) "output":{
(9) "result.trace_file":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/trace.log"],
(10) "xquery.main_output_files":["/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1"],
(11) "xquery.additional_output_files":[]},
(12) "state":"OK",
(13) "output-mapping":{
(14) "/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1":
(15) "file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult"
(16) },
(17) "error":{}
(18) }]
(19) }
Given below is an explanation of this listing:
(1) The result is returned as a JSON object.
(2) The jobid on the first level is the main job identifier.
(3) The state for this job is OK. Possible states are: none; Dispatched; Running; Canceled; Crashed; OK; Failed.
(4) The JSON error object in our example is empty. It may contain the JSON serialization of the error as reported by RaptorXML+XBRL Server.
(5) The main job (on the first level) generates sub-jobs (for example, one per argument).
(6) The argument for the this job is the XML instance file: additional-files:///simple.xml.
(7) Sub-jobs also have a job identifier that can be used to query the state or fetch the results. Job execution is asynchronous. As a result short jobs submitted after longer jobs may finish earlier.
(8) to (16) The JSON output object contains keys for the server-generated output files that can be requested via HTTP. Some keys (such as xquery.main_output_files) specify URLs to the generated files stored on the server. These server-local paths can be mapped to names, which can be used as JSON output-mapping objects in HTTP URLs. Such URLs are used to fetch output files via HTTP and are constituted as follows:
<scheme>://<host>:<port>/<output-mapping-value>
Our example to fetch the main XQuery output file would therefore look like this:
curl.exe http://localhost:8087/v1/results/768656F9-F4A1-4492-9676-C6226E30D998/output/1
Note that in the output-mapping object (13), the first value (14), is the mapping value that we have keyed to the XQuery output (15), file:///C:/ProgramData/Altova/RaptorXMLXBRLServer2016/Output/768656F9-F4A1-4492-9676-C6226E30D998/MyQueryResult. This enables us to use the mapping vaue to reference the file.