Job Name Discovery

Once a file has been found in one of the FolderMonitor folders (Queues), FolderMonitor first must determine what processing must be done on this particular file.
There are a few ways that FolderMonitor can do that. In priority order

1. Detect a DocOrigin PI containing only Merge-acceptable attributes (as of 3.1.002.03)
2. Detect a DocOrigin PI with a job= "JobName" attribute
3. Skip job name discovery completely and use the Job Processing script identified by a -JPSName option (as of 3.1.002.03) 
4. Use the Job Name Discovery script identified by the -script option
5. Default to using the $E/Default-JobNameDiscovery.wjs script (which may bring to bear an override $O/JobNameDiscovery.wjs)

A common option is to run the JavaScript script defined in the -script command option to "discover" the type of processing that should be done on the file. Like all script files, any job name discovery script (JND) must be saved in UTF-8. This script must return a "job name" - a unique text name that will be used to identify the job processing script to run on the file.

Sample discovery script:

var sData = _file.readfile(_job.datafile);
i = sData.indexOf("SalesTable");
if (i > -1) return "Table Sample - Nested Table";
i = sData.indexOf("CustomerInfo");
if (i > -1) return "Sample Invoice";
return ""; 	// No job name found. Send to Error Folder

The above script reads the contents of the data file, then searches for the keyword "SalesTable" in the file. If this string appears in the file, the job name returned is "Table Sample - Nested Table". Similarly if the keyword "CustomerInfo" is found, the job name becomes "Sample Invoice".

If no job name is found in the file (see The DocOrigin PI below) or by the job name discovery script, an error is triggered and the data file is moved to the Error Folder (see Error Handling).

If a job name is returned, but no such Job Processing script exists, then the default Job Processing script ($E/Default-JobProcessing.wjs) will be run. If you wish to explicitly have the default Job Processing script applied, have your JND return "_default_". As of 3.1.001.22 if the file jobname.wjs is not found in your nominated script folder it will try the file jobname.jps. That is, the .jps extension can be used for Job Processing scripts.

The DocOrigin PI

One good practice, if you have influence in data stream creation, is to include a DocOrigin processing instruction (PI) in the XML data. E.g.

<?DocOrigin job="aName" for="aGuy" printerTarget="aPrinter" outputFormat="aFormat"?> 

If such a PI exists, then the JobNameDiscovery script won't even be invoked. The job attribute in the PI will define the job name, i.e. will define which job processing script to run.

The other attributes, if any, on the PI will be conveniently placed in _job.options.name properties that then become available to the job processing script. The attributes that you choose to put on the PI (aside from job) are totally up to you.

Given the above example PI, the job processing script (aName.wjs) could refer to _job.options.printerTarget, using its value in any way the script desires to affect the processing of the job.

Quite convenient really.

Caveat: While the _job.options properties flow through from the JND (or DocOrigin PI) to the JPS, they do not flow through to Merge (i.e. to script in your form design). Your JPS could transfer such information by creating suitable -cache command line options for Merge to see.

Direct-to-Merge PI

As of 3.1.002.03, if the DocOrigin PI does not have a -job attribute and in fact all the attributes in the PI are valid Merge command line options, then both Job Name Discovery and Job Processing scripts will not be considered. Instead Merge, (and only Merge, not multiple steps), will be run directly using the options specified as attributes in the DocOrigin PI. Surely you would specify the -form option at a minimum. This is very direct with no chance for a script to peek at the job context. Perhaps it will suit your needs.

See Also 

XmlFile Class (Write XML Files) -- the xfile.pi() function.