Processing Details

Jobs

The unit of work for a DocOrigin web service (WS) is termed a "job". What that job does is defined by a previously deployed script. Either the delivered default script or a user-customized script may be invoked by the DocOrigin WS call. The WS is almost certainly requested to deliver a data payload, and may also provide additional user-defined options if so desired.

Of course, the WS always returns a result. Certainly, it will return operational 'headers' but most frequently it also returns the primary result of the job, quite typically a PDF file. (But it could be anything.) One call and you get your result delivered to you. WS requests may choose either sync or async mode. The vast majority are done in synchronous fashion. You make the call and the result is returned to you ASAP. However, you can initiate an async job, and make later requests for the status and collateral of the defined job. When the WS is requested to do a job, it creates a new, uniquely named, folder for that job. All resources pertaining to that job are kept in that job's folder.

REST and SOAP web services both provide similar request choices:

1. Run a job, sync or async
2. Get a status/result of a job
3. Delete job data (the entire folder created specifically for the identified job)
4. Get a list of files available for a job (i.e. the files left by the script in the job's folder)
5. Get a specific file for a job (e.g. log.txt)
6. Get a WS version

REST API

The REST API is best seen via the built-in "Swagger" docs. Use the Tomcat manager application and click on your web service to navigate there. 

The API includes:

1. Execute a job (sync or async)
2. Delete the job folder
3. Get the job result
4. Get a list of a job's available files
5. Get a selected job file
6. Execute Merge job (as of v. 1.3.5)

SOAP API

The SOAP API is best seen via its WSDL. Use the Tomcat manager application and click on your web service. You may use that wsdl for your SOAP client implementation.

The API includes:

1. runJob (sync)
2. submitJob (async)
3. deleteJob
4. getJobResult
5. listJobFiles
6. getJobFile
7. runMerge (sync) (as of v. 1.3.5)
8. submitMerge (async) (as of v. 1.3.5)

Job Internals

All configuration values mentioned below are taken from the provided [Default-]DocOriginWs.ini file. See Configuration.

For reference, what follows is a sample WS configuration override file: $O/DocOriginWs.ini

* DocOrigin Web Services configuration
TempPath=C:\DocOrigin\User\Temp
KeepJobHours=1
* RunTimeoutSec=60
* JobInfo=jobInfo.properties
Input=DOWebService.input

When the web service (WS) receives a request to run a job, it creates a new folder under the path specified by the TempPath configuration value. The name of the created folder is guid-like (e.g. 1fb4e383-fe9f-475e-ad90-45ffc981f5e2) and in fact is the "jobid" assigned to the job.

The WS then places the supplied input (data) file into that folder with the file name specified by the Input configuration value. Note that the configuration names (e.g. Input) are case-sensitive.

(Before v. 1.3.5) The WS then executes DocOrigin's RunScript program providing it a set of command line options:

(As of 1.3.5) The WS then executes DocOrigin's command template (specified by the cmdDefault configuration value). By default it runs RunScript program providing it a set of command line options:

Note that options is not DocOrigin specific but rather an arbitrary string which your script understands. e.g. key1=value1;key2=value2. The WS itself has no idea what you might put in that options string. It's yours to use as you wish.

What your script does is completely up to you. Typically, it quickly examines the supplied data file contents and determines what processing should be done, for example, which form design file to apply. The script might also look at the supplied options for guidance on what specific user actions apply to this request. Those options are user-defined, the WS is oblivious to them.

The delivered $E/Default-WsRun.wjs is a great example to start from, if you want to create a customized script. If you do supply a custom script it must be pre-deployed on the server that is hosting the WS. You cannot send the actual script content along with the WS request. That would be super dangerous. Control your WS-accessible scripts.

Returned Results

The WS is designed in a way such that it can immediately return one result file and several properties. The file to return is defined by the output property described below. Typically the result file is a DocOrigin Merge generated PDF file, but it could be anything. Notice that, with further calls to the WS, you can get other results from your job as well. See the API. Typically a single call with a single result suffices.

While your script does whatever you want, it has to keep in mind these rules:

1. The script has to create a 'communications' file named jobInfo.properties (by default) in its job folder. That file name has whatever name you defined in the JobInfo configuration value. That file is to contain a set of name=value lines. The content of the file will be read by the WS and returned to the caller. For example, in REST, those 'job info properties' are returned as do.xxx response headers and the nominated output file is returned as the response body. See the info block below.

2. Some names in the jobInfo.properties file have a special meaning:

   	jobInfo.properties critical contents
   output	if set, is used by the WS as the file name of the primary 'result' file which is to be returned to the caller as the response body.
   mime	if set, is used as the content-type of the "output". (often application/pdf, or plain/text as applicable.

3. jobInfo.properties must be created as the very last operation of your script since the WS decides whether the job is complete by checking for this file's existence.

The WS returns three special info fields back to indicate job execution state:

(These are returned as response headers in REST)

For reference, what follows is a fairly typical set of response headers from a REST WS call. Please draw your attention to the custom headers that begin with "do.".

HTTP/1.1 100 Continue

HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
do.completed: true
do.jobId: f4469907-d668-4cb0-9a93-75e994fdeb73
Access-Control-Allow-Credentials: true
Access-Control-Expose-Headers: do.completed, do.jobId, do.exitCode, do.property.rc, do.property.message, do.property.output, do.property.mime
do.exitCode: 0
do.property.rc: 0
do.property.message: OK
do.property.output: C:\DocOrigin\User\Output\PurchaseOrder_2016-001.pdf
do.property.mime: application/pdf
Date: Thu, 13 Jun 2019 23:23:14 GMT
Content-Type: application/pdf
Transfer-Encoding: chunked

Note, that the jobId is available to you, and you will need that if you choose to make more WS API calls regarding this same job. Also note that the WS special do.jobId, do.exitCode, and do.completed headers are differentiated from the user-defined headers by being named only do.xxx and not do.property.xxx.

For more correlation, the following is the jobInfo.properties file contents for the above job:

rc=0
message=OK
output=C:\DocOrigin\User\Output\PurchaseOrder_2016-001.pdf
mime=application/pdf

Note, that async calls return only limited set of data (like jobId) because job is not yet completed by the time of WS response. You may ask for job data later using jobId.

As of v. 1.3.4, added do.service.url, do.service.base, do.service.path to Web Service response header.

Limitations

WS is designed with some build-in automation regarding job outcome. Like, in synchronous scenario WS automatically returns the generated output back to the client. So WS has to know where and how the output is called, you do not want to break this automation. Also, you do not want one job to spoil the file-system results of the other jobs.

By default your script starts out with its current directory being the 'job folder'. It is not recommended to change the current directory in your script or form for the reasons mentioned above. All work should be done in the job's folder, and jobInfo.properties must be created there.

Also, while you are welcome to specify "business-level" options like -cache, -config, etc., it is not recommended to set "system-level" options like output location, logfile location, etc. for the same reasons.

The only useful exception of these rules we can think of is the case when you want a fire-and-forget (async) job sending output directly to some printer. Then it is OK to specify custom output location.

The Default Script

By default, DocOrigin provides the $E/Default-WsRun.wjs script which

1. consumes an XML file
   
2. tries to determine the applicable form name
   
3. tries to find that form under %DO_ROOT%\DO\Samples\
   
4. runs DocOrigin Merge to generate a PDF
   
5. returns that PDF as the request response.

The WS returns additional information. For example, in REST, we return do.jobId, do.completed, do.exitCode plus all other name=value pairs from the jobInfo.properties file as do.property.xxx response headers.

Out-of-the-box, you can try the WS by executing a job and passing %DO_ROOT%\DO\Samples\Sample_Invoice.xml as the input parameter. You should receive a generated PDF back.

Direct Merge call

As of v. 1.3.5, new functionality was added - direct Merge call. It is /jobs/merge for REST and run/submitMerge for SOAP.

This allows you to avoid any script calls which speeds up output generation and simplifies set up process.

Let's say at client side, having your data file ready you already know that you want a form called Sample_invoice.xatw and PCL output. So you may call /jobs/merge REST WS just passing:

• input data in input parameter
• say -form $R/DO/Samples/Sample_invoice.xatw -config Default-LJ4.prt in options parameter

As a result, a single Merge call will be executed using supplied data file and options, and resulting output returned back to the client.

Note, you should be careful which options you are sending with this call. It is natural that you will want to send something "business-level" like -form, -config, -cache, etc. But do not pass "system-level" options like -cd, -logfile, etc. See "Limitation" topic.

Calling The WS

How do you 'execute a job', i.e. call/invoke the WS? Well..

There are lots of ways, as many ways as there are computer languages and frameworks. The WS distribution package includes a 'reference implementation' for a Java-based invocation of the WS. You can certainly peruse that (both REST and SOAP) for inspiration (if you need any). See DEMO Application.

One way to see an invocation of the WS 'out in the open' is via a cURL call. Following is a Windows .bat file that uses cURL to invoke the WS, i.e. to execute a job. The point here is not .bat files or cURL but just showing one, nothing up our sleeves, way to execute a job.

The meat of the .bat file is as follows

set input=%~1
set server=myws.example.com
set port=8443
curl -X POST -u %myDOWSCreds% -k        ^
 https://%server%:%port%/DORest/1.3/jobs ^
 -F input=@"%input%"                     ^
 -F options="a relevant option string"   ^
 -D wsHeaders.txt                        ^
 -o wsOutput.pdf

The presumption in this .bat file snippet is that you have put your DO WS credentials into an environment variable named myDOWSCreds. That would be in the format userId:password. There are other ways to specify your credentials. Use whichever method you like but you do have to give the WS useful credentials.

Of course, you need to know the name of the server where the WS has been installed.

The port is something you need to get from the installer. They could easily have configured the ports that Tomcat is using. By default, port 80 is used for http: access and port 443 is used for https: access. By some long ago programmer's whim, the non-standard port numbers 8080, and 8443 often appear in use. ...Ask the installer.

The -k option is a synonym for ‐‐insecure. That option has been shown since during initial "playing" it is not uncommon for the server to be protected by a mere self‐signed certificate. Not recommended, but out-of-our-scope, and we don't want you to endure hassles when you are just getting started. Security is something you need to be aware of and have professionally addressed.

The -D wsHeaders.txt is not mandatory, but in the interests of illustration, it's nice to see what headers come back.

The -o wsOutput.pdf (note the small o) is needed to receive the primary response result. The explicit .pdf extension is a bit optimistic since some failure could have occurred along the way and it may not be a .pdf that comes back. You should be checking the headers that come back before ass-u-ming.

If it applied, you could also supply a -F scriptName="someCustomPredeployed.wjs"