FFEXTERN has several functions other than document conversion.  This topic covers only document conversion functions.

Scanning FS Files

Document Converter scans for FS files in PREPROC and in the preprocess MSMQ if specified.

If any file on a $fax_filename command has a file type which is included in the $convert_types configuration command, a preprocess statement is temporarily added to the FS with queue 0. It is important to note that the $email_attach command does not participate in the decision to select an FS file for conversion, either in FFEXTERN or in the CopiaFacts engine.

If a preprocess queue has been specified in FFEXTERN which enables processing of the document type of any of the files, it is selected for document conversion of all files named on $fax_filename commands.

In practice, only queue 0 is used for document conversion.

In a Job Admin environment, selected files are ignored for suspended jobs, and caused to fail with outcome code 134 if the job has been canceled.  Files with a FORCE_FAIL are also moved direct to a TOSEND queue to be processed for failure.  If a Job Admin PreConvert operation is being performed, the initial FS may have only a $fax_phone or only an $email_address destination, but $fax_phone is assumed to be present if the broadcast type is FB, FEB1, or FEB2, and an $email_address command is assumed to be present if the broadcast type string contains 'EB'.

Document Conversion Preparation

Conversion options are obtained from the USR/UJP file $convert_options command, all of which are replaced by those on an FS file $convert_options command if present.

Each $fax_filename command is then processed separately.  Wildcards are expanded in the pathname, from FS and other available variables.

The source file type is determined, and the conversion method is then decided from this and the convert options.  This uses the same internal functions that are also used in CVSINGLE.

If the file is not one of those specified for automatic conversion on $convert_types, it is ignored.

If the source file time is in the future by more than five minutes, the conversion fails with outcome 129.  If the future time is within five minutes, the conversion output file time will be set to one minute later than the source file time.

All $email_attach commands are then scanned and the variable-expanded attachment pathname is compared to the name on the current fax-filename command; the file extension does not participate in this comparison. There may be more than one such matched attachment command if the document is to be attached in more than one format.

FFEXTERN can request CVSINGLE to create four types of output: a final converted TIF file; a final converted PDF file; an intermediate PDF file which will be converted to TIF in a second phase; or to save a DOC file from a Wordmerge customization.

A TIF file will be requested in the following circumstances:

The document is not a faxable TIF, AND one of the following conditions applies:

The FS file has an $email_address command, and a matched attachment is present, which has an 'image' content-type other than one matching the document extension, OR

The FS file has an $email_address command, and the document is not a PDF, and a matched attachment other is present, which has a 'PDF' content type, and the PDFattach convert option is not present, OR

The FS file has a $fax_phone command, either is a preconvert or did not have a 'nofax' keyword, and the InterPDF convert option is not present with a supported conversion method (Office 2007 SP2 or later Office), OR

The FS file has a $worker_box command with the option set to create a job preview (JOBBOT20)

A PDF file (final) will be requested in the following circumstances:

The document is not a faxable TIF or a PDF file, AND

The FS file has an $email_address command, and a matched attachment is present, which has a 'PDF' content type, and the PDFattach convert option is present with a supported conversion method

A PDF file (intermediate) will be requested in the following circumstances:

The document is not a faxable TIF or a PDF file, AND

The FS file has a $fax_phone command, or a a $worker_box command with the option set to create a job preview, and the InterPDF convert option is present with a supported conversion method (Office 2007 SP2 or later Office)

A DOC file will be requested in the following circumstances:

The document is a Wordmerge document, and the FS file has an $email_address command, and a matched attachment is present which has a 'Word' content type.

If no conversions are needed for a specific document, it is ignored.  However if it had the 'nofax' keyword the $fax_filename command will be deleted.  This might be the case for fax items in a WordMerge job or when converting bcf expanded variables where the $fax_filename command was only required to trigger conversions for e-mail items.

The preparation phase concludes with the setting up of parameters to control CVSINGLE

Variable Expansion

The following variable-expansion operations are performed:

CF8JOBADM may have marked the $fax_filename command with an ExpandBCFVars option if there are BCF or BCX variables in the HTML file.  Such files are skipped for preconvert operations, but the variables are expanded into a temporary file for per-item conversions.

If CF8JOBADM has marked the $fax_filename command with an ExpandBCFVars option, or if the checkbox is set in FFEXTERN preprocess options for non-job conversions, FFEXTERN the variables are expanded into a temporary file for all conversions.

If the 'expand RTF variables' checkbox is set in FFEXTERN preprocess options for non-job conversions, the variables are expanded into a temporary file for RTF conversions.

FFEXTERN performs passes the temporary output file to CVSINGLE instead of the original file, and deletes the temporary file after conversion.

Selecting a Destination Folder and Filename

The destination folder and filename are selected as follows.  In each case the number x starts at 1 and incremented for each $fax_filename command.

In a Job Administration environment:

Wordmerge output files (TIF, PDF, DOC) are written to a TEMP folder in the job instance folder, with a filename of the FS name with suffix of _WMx.  The output file is always deleted if already present.

Per-recipient converted items are written to a TEMP folder in the job instance folder, with a filename of the FS name with suffix of _TMPx.

Preconvert output files (TIF) are written to a pathname specified by CF8JOBADM which is the same as the UJP with a suffix of _Cx.TIF.

Not in a Job Administration environment:

If the file is an HTML file, it is written to a TEMP folder in the folder specified by $convert_dir or $webfax_dir, with a filename of the FS name with suffix of _Fx.

Otherwise, it is written to the same folder as the source file, with a suffix of the original file extension (e.g. sample.doc becomes sampledoc.tif).

Calling CVSINGLE

CVSINGLE is then called.  It returns a negative value on error.  For a successful conversion, it now returns an integer value which is the sum of:

the number of TIF pages converted

the number of PDF pages converted, times 1000

1000000 if a word merge customized DOC file has been saved.

Counts are maintained of successive failures and timeouts which may trigger OMA.  If the AllowFail convert option is not present, an unsuccessful conversion causes the remaining conversions, if any, not to be attempted.  Unsuccessful conversions normally result in outcome 83, unless the failure occurs after a successful word-merge operation has taken place: these fail with outcome 138, which is not an outcome for which retry can be configured.

FS File updating

After a successful conversion, the following changes are made to the FS file:

For WordMerge documents where the launcher has indicated (with a WordMergeNF $fax_filename keyword) that no fax is to be sent, the $fax_filename command is deleted.

The active $fax_filename command is replaced by one just containing the output TIF filename.

Variables are added CVRT_TIFx, CVRT_PDFx , CVRT_DOCx  with the input and output filenames.

Matching $email_attach commands for WordMerge documents are then processed as follows:

If the the content-type is a 'Word' content type, the output DOC filename replaces the attachment filename.

If the PDFattach convert option is in effect and the content type is a 'PDF' content type, the output PDF filename replaces the attachment filename.

If the PDFattach convert option is not in effect and the content type is a 'PDF' content type, the output TIF filename replaces the attachment filename.

If the content type is an 'image' content type, the output TIF filename replaces the attachment filename.

If the attachment filename has not been replaced (which should not happen) the output TIF filename replaces the attachment filename.

Matching $email_attach commands for non-WordMerge documents are then processed as follows:

if the document file extension matches the content type it is left unchanged.

if the PDFattach convert option is in effect and the content type is a 'PDF' content type, the output PDF filename replaces the attachment filename.

If the PDFattach convert option is not in effect and the content type is a 'PDF' content type, the output TIF filename replaces the attachment filename.

If the content type is an 'image' content type, the output TIF filename replaces the attachment filename.

If the attachment filename has not been replaced (which should not happen) the output TIF filename replaces the attachment filename.

If there is no $email_address command in the FS and the FS is not a preview, all $email_attach commands are deleted

If there is no $fax_phone command in the FS and the FS is not a preview, all $fax_filename commands are deleted

Completion Tasks

After documents have been converted, the FS file is moved to TOSEND, with or without a FORCE_FAIL command.

A successful preconvert operation will trigger calling CF8JOBADM to launch the job.

Bulk WordMerge

The Bulk WordMerge operation is a 'special process' not a 'pre-process' operation.  FFEXTERN instances can be configured either for pre-processing or for Bulk WordMerge, for which a license option is required.  In the latter mode the program reads the MSMQ specified by the $preproc_wmdcqname command.

FFEXTERN does little more than pass the UJP filename and parameters to CVSINGLE.