DELIVER CONFIGURATION

The deliver.ini file contains configuration information for the deliver command and deliver() code block function. The file contains a [default] section, an [email] section, one or more fax definition sections, and custom sections for specialized document delivery. The [default] section contains a fax= line that specifies which fax definition section is used. It also contains logging parameters.

Any section can contain a line 'async=1' if deliveries using that section should be queued rather than immediately delivered. This can helpful in cases where delivery might be time consuming and would slow down jobs, or where automatic retries are desired. Email and fax deliveries are good candidates for async delivery.

The [default] section defines standard settings used by the deliver command and deliver() function. The lines are

fax=section	Identifies the deliver.ini section that defines the fax gateway configuration.
logage=days	The number of days deliver logs are maintained before automatic purging.
logtags=0\|1	Determines whether or not to log tags in the log files (0=don't log tags, 1=log tags). This is often helpful information, but does add to the verboseness of the log files.
queue=minutes	When asynchronous delivery is used, this defines how many minutes between queue sweeps are performed. For example, queue=10 would sweep on the 10 minute increments (00, 10, 20, 30, 40, and 50).
retryage=days	The number of days that async deliveries are retried before being purged. If this is 0 or not set, the logage value is used. This feature was added in 9.0.24.

The [email] section defines standard tags used for emailing. These tags supplement the configuration found in prog/mailcall.ini and also in the [mailcall] section of uf90d.ini. Generally there is no need to adjust this section unless you choose to implement the async flag.

A fax definition indicates the type of interaction that is required, command line, email (SMTP), or the internal msfax option, which utilizes the Windows Support Server to send faxes via Microsoft Fax. Each configuration line can contain optional and required tags, which are substituted at runtime with tag values specified in the deliver command or deliver() code block function. Tags are used to specify fax numbers, subject lines, recipient names, and other values, and the values from the commands are mapped to the configuration each time a delivery is performed.

Tag	Usage
%to	Fax number or email address.
%faxfile	File to be sent (the output from UnForm, typically of a subjob). The deliver command manages this value automatically. The deliver() function has a file name argument that this tag references.
%errfile	An error file, which if used and contains content will be returned in the errmsg$ argument of the deliver() function. UnForm generates the file name automatically, and then expects to find error messages, if any, in the file when the fax or email is submitted.
%rspfile	A response file, which if used and contains content will be returned in the response$ argument of the deliver() function. UnForm generates the file name automatically, and then expects to find messages, if any, in the file when the fax or email is submitted. For example, this might be the standard output of a vfx command line, which can contain a fax job number.
%attach	Used for additional documents beyond the %f file. All attach tags are accumulated, with space delimiters for command methods, and comma delimiters for email methods, then the entire list is substituted for the %attach marker. The msfax method does not support attachments.

Additional tags are referenced with a %name syntax, and are substituted from the tag options provided by the deliver command or deliver() function. Optional tags are specified using a { %name } syntax, where a tag and any text can be specified inside the curly braces. After all %name substitutions have occurred, any remaining {…} sequences that contain %name tags are removed before the delivery is actually executed.

When the deliver command generates a document for delivery, it does so with an UnForm subjob. When delivering to an email address, the subjob always produces a pdf file. When delivering to a fax number, the type of file is configured with the format=pcl|pdf|ps line. When executing the subjob, several command line options are automatically managed. The fax configuration section can specify additional options, as can the deliver command itself.

The deliver command can also "deliver" documents to other destinations. If the deliver command's target address matches a section name in deliver.ini, then the configuration in that section is used, rather than a fax or email configuration.

Each of these sections must have a method= line which determines how the balance of the section is interpreted, and a format= line to specify what type of file the deliver command produces.

method=file	Delivers a document to the file system, using the path specification. The path may contain tags, as there should be some dynamic values in the file. One common tag would simply be %file, which represents the base name of the work file generated, which itself is based on the "docid" value provided in the deliver command. This might, for example, be an invoice number or purchase order number, though it can be any value required. Other tags will be substituted from the tags supplied in the deliver command. The extension= value can be used to override the default extension provided by the driver. A sequence=number can be used to prevent overwriting of a file. The value of number specifies the default number of digits used in the sequencer. For example, sequencer=3 would produce unique sequences like -001, -002, and so on. Sequences are always appended to the end of the file, before the file's extension. If sequence is 0, you can specify overwrite=1 to allow overwriting of existing files. Otherwise, if the file already exists, and error is generated.
method=command	This executes the system command specified by the command=value specification. You can optionally use special tags %rspfile and %errfile to capture response and error data from the command for logging purposes.
method=desktop	This method uses Desktop Delivery to send a document to a user running the Desktop Delivery browser interface. A user and optional ipaddr value must be specified in deliver command tags so the system knows where to send the document. Optionally, specify a title and style tag. The style tag can be 0 for standard 'notification' style delivery, or 1 for a popup delivery, which is automatically displayed on the user's desktop if the user is currently connected.
method=code	This method executes runtime code (native pvx) found between 'code on' and 'code off' lines within the section. This code can return a value in response$, or an error message in errmsg$. Lines in the code may contain references to standard and user-supplied tag values, such as %file or %path. This method provides a great deal of flexiblity to allow delivery of documents to cloud services, external document management systems, and other external features.

In addition to tags provided in the deliver command and deliver() functions, the following tags can be used to reference the file to be delivered:

When the deliver command runs, it generates a document file based upon a document ID value and normally will attempt to deliver that file as the job runs. If the delivery section contains an 'async=1' configuration, then the delivery file and information are queued in the server's "deliver" subdiretory, and a separate process is launched to perform the delivery. In addition, if the delivery of any given file gets an error, the file is retained and another process will attempt the delivery later. This retry mechanism is logged as a status of RTY in the deliver log file, indicating there was an error and the delivery will be retried later.

The frequency of retries is determined by the queue=minutes setting in the [default] section.

The retries will continue as long as the delivery file remains in the queue. They are automatically purged based on the same aging process as the log files (by default 30 days). All errors are logged both in the deliver logs and in the main server log.

Queued delivery files are not editable, and it is possible that tags embedded in the files produce permanent errors. For example, if a mail server tag is included with an invalid address, the delivery will always fail. It is possible to create a file named "tagsubs.txt" in the deliver subdirectory. If this file exists, any oldvalue=newvalue lines in the file cause literal text substitution in the tags of each delivery file. As an example, if delivery tags included a bad server server specification of 'server=ssl:smtp.gnail.com', you could add a line "smtp.gnail.com=smtp.gmail.com" to dynamically correct the domain name. Note that if you need to specify an "=" sign in either value, use "\=".

This example [default] section specifies that the vsifax fax definition will be used for faxing. Daily delivery log files will be placed in the deliver subdirectory under the UnForm server, tags will be logged in addition to basic delivery data, and log files will be retained for 30 days.

This [email] section defines a To: header format with an optional quoted name and the to address. The name can be supplied via a name="value" tag in the deliver command or function. If not supplied, then the To: header will just have the email address, automatically supplied as the "to" tag.

Other values can be supplied via additional tags. The email will always include a file attachment, as generated by the deliver command or supplied to the deliver function. In addition, if there are any "attach filename" tags, those files will be attached to the email as well.

The vsifax section defines a fax gateway that uses the vfx command to send a fax. The method is set to "command", indicating that a command line is created and executed. The command is specified over several lines in the deliver.ini file by using \ at the ends of lines to indicate that the line continues on the next physical line.

There are several optional elements, such as name and subject. If they are supplied as tags in the deliver command or deliver() function, then -t options will be added to the vfx command line. If not, then those elements are suppressed from the command line. For example, if one tag was 'name="John Smith"', then there would be a '-t tnm="John Smith"' added to the command line.

Standard output is captured in a response file, and error output is capture in an error file. The use of %r and %e in the command allows the deliver() function to return the command's response or error message.

When the deliver command executes the subjob to produce the file to be faxed, it will produce it in pcl format (using a -p pcl option). In addition, a -nohpgl option will be used.

Note that for Windows, since vfx.exe is a console command, the command should start with "cmd.exe /c vfx.exe ...".

The rapidfax section shows an example of using a third-party Internet faxing service for sending faxes. Such services accept email submissions via email. PDF format is generally supported, and many services offer support for additional document types, meaning you can add additional attachments, such as text files, image files, or Microsoft Office files.

The method is specified as "email" to indicate that UnForm will submit faxes by emailing them to the fax service. The To address for most Internet services is faxnum@service.com. In the case of Rapidfax, the domain is rapidfax.com. Rapidfax expects fax submissions from a specific email address, and with a user-configured subject line. In this example, the From address and subject lines are hardcoded. There can be a message body, specified by a note tag, and both the submitted file and any other files specified by attach=filename tags are submitted for faxing.

The msfax section specifies the "msfax" method, which is an internal UnForm method that works in conjunction with the Windows Support Server. The command value specifies tag names documented in the Windows Support Server chapter and the msfax() function.