Running pdfToolbox via Webservices (SOAP)

It is possible to submit jobs to a pdfToolbox instance and retrieve the results via SOAP requests.

In order to do so you first have to start the pdfToolbox in a "listening mode":

./pdfToolbox --satellite --port=<any free port number, e.g. 1201>
Click to copy

Or on Windows:

.\pdfToolbox.exe --satellite --port=<any free port number, e.g. 1201>
Click to copy

It is currently not possible to submit PDF files or kfpx Profiles via such SOAP requests, so both have to be available to pdfToolbox on mounted volumes.

The SOAP requests wrap any command line parameters in <ns:args> tags. The simple requests  below asks pdfToolbox to send usage information back by submitting the --help parameter.

Beginning from pdfToolbox 9:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:ns="http://callassoftware.com/cws.xsd">
 <SOAP-ENV:Body>
  <ns:extExecute>
   <ns:args>
    <ns:userID></ns:userID>
    <ns:args>--noprogress</ns:args>
    <ns:args>--nosummary</ns:args>
       <ns:args>--nohits</ns:args>
    <ns:args>-o=/AppData/pdfToolbox/WebService/sample_result.pdf</ns:args>
    <ns:args>-r=XML,ALWAYS,ALL,PATH=/AppData/pdfToolbox/WebService/sample_result.xml</ns:args>
    <ns:args>/Applications/callas pdfToolbox Server 10/cli/var/Profiles/PDFX compliance/Convert to PDFX-1a (ISO Coated v2 (ECI)).kfpx</ns:args>
    <ns:args>/AppData/pdfToolbox/WebService/sample.pdf</ns:args>
   </ns:args>
  </ns:extExecute>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Click to copy

Beginning from pdfToolbox 10:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:ns="http://callassoftware.com/cws.xsd">
 <SOAP-ENV:Body>
  <ns:extExecute>
   <args>
    <userID></userID>
    <args>--noprogress</args>
    <args>--nosummary</args>
       <args>--nohits</args>
    <args>-o=/AppData/pdfToolbox/WebService/sample_result.pdf</args>
    <args>-r=XML,ALWAYS,ALL,PATH=/AppData/pdfToolbox/WebService/sample_result.xml</args>
    <args>/Applications/callas pdfToolbox Server 10/cli/var/Profiles/PDFX compliance/Convert to PDFX-1a (ISO Coated v2 (ECI)).kfpx</args>
    <args>/AppData/pdfToolbox/WebService/sample.pdf</args>
   </args>
  </ns:extExecute>
 </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Click to copy

You may include as many parameters as required, there is no limitation.

Any results will be sent back in XML back to the program that you have used to send the request.

You may use the curl tool on command line to send requests and retrieve results:

curl -H "Content-Type: text/xml; charset=utf8" -d@.\ns.extExecute_help.req.xml http://<pdfToolbox' IP>:<Port>
Click to copy

A Web Service Defintion Language file can be found in the pdfToolbox program folder:

The example below is a simple SOAP request that asks pdfToolbox to create single pages from the original PDF file. Path and name of the PDF need of course to be adapted.

ns.extExecute_makesinglepages.req.xml

Getting progress

If you want to get progress for a longer running action, this can be done as well. When making the original request, make sure the userID element is filled with a unique identifier for the call you're making.

...
  <ns:extExecute>
   <args>
    <userID>Job777</userID>
    <args>--noprogress</args>
    <args>--nosummary</args>
       <args>--nohits</args>
    <args>-o=/AppData/pdfToolbox/WebService/sample_result.pdf</args>
    <args>-r=XML,ALWAYS,ALL,PATH=/AppData/pdfToolbox/WebService/sample_result.xml</args>
    <args>/Applications/callas pdfToolbox Server 10/cli/var/Profiles/PDFX compliance/Convert to PDFX-1a (ISO Coated v2 (ECI)).kfpx</args>
    <args>/AppData/pdfToolbox/WebService/sample.pdf</args>
   </args>
  </ns:extExecute>
...
Click to copy

The unique identifier ("Job777" in the above example), can then be used to get progress information through a REST call:

http://<HOST:PORT>/exExecute/<USERID>/progress
Click to copy