Navigation:  CopiaFacts Features > Fax Broadcasting

Fax broadcasting using CopiaFacts is done in three main ways. Small broadcasts can be initiated from the CopiaFacts Client software. Large-scale job-oriented broadcasts are set-up launched and controlled using the Job Administration features described later. This section discusses the features of FFBC, which is designed for manual set-up and launching of broadcasts.

The FFBC program is principally designed as a command-line application which runs in a console session under Windows, and is therefore equally suitable for 'manual' use or for running automatically from a $run command in a $type query infobox. However FFBC also has a visual mode which allows you to view the broadcast list, to edit the FS template file, browse for document attachments and to preview, test and launch a broadcast.

FFBC supports the following file types:

When the broadcast is generated a complete block of FS file numbers is acquired from the NEXTFS file, so that the FS numbers for a broadcast are always contiguous.

Preparing an ASCII list file

The list file is an ASCII file consisting of one line per record. Lines starting with a ';' or '/*', and blank lines, are ignored. There are two alternate formats for the list file. In the first the fields on each line must be separated by commas or spaces and delimited by double-quotes. The comma is overridden by the character specified as 'list separator' in your Windows regional settings. A pair of double-quote characters together in a quoted field are used to insert one double-quote character. It is recommended that a file of this type should not contain tab characters.

For example, given an input line:

12345678,"Stri,ng 1","Stri""ng 2",String 3,String4

FFBC will create six fields containing the following values:

12345678
Stri,ng 1
Stri"ng 2
String
3
String4

Note that above conventions are designed to be compatible with most CSV files, and do not exactly match the CopiaFacts command-file conventions for quoted fields. This file format must not have file extension .TLS or .TAB or .TXT unless you use the system variable FORCE_CSV to specify that an extension is to be treated as a CSV file. The last two are the default file extension for exports from Microsoft Excel.

In the second format for the list file, fields must be separated by a single TAB character. All characters are then valid in a field, and none have any special purpose, except that a pair of double-quotes surrounding a field are removed. Consecutive TAB characters indicate an empty field. This type of file is designated by a .TLS file extension (tabbed list) or a .TAB or .TXT extension, or by an extension specified in the value of the FORCE_TAB system variable.

FFBC first scans the list file for the maximum and minimum number of fields on any line. It is thus able to provide some limited warning if fields are omitted. It does not currently make any checks for empty fields when more fields are present on the line, so broadcast items may still fail if the list file has errors.

Preparing an Excel File

Currently, the list data must be in the first or only worksheet in the XLS file. All Excel data formats are mapped into string values. If you have the file open in Excel (on any node) while FFBC is attempting to read it, the broadcast may fail.

The default is now set to use a custom interface in F7EXCEL.DLL to read Microsoft Excel files, so that Excel is no longer required to be installed on the machine that is using the list to launch a job. This interface does not support XLS files from Excel 95 or earlier. To force the use of Excel (2000 or later), assign a non-empty value to the variable USE_EXCEL.  Office 2007 XLSX files are not yet supported for lists.

Preparing a dBASE File

Records in the dBASE file using the standard 'deleted record' convention will be ignored. Index files for the DBF are not used and all non-deleted records are used.

Using the list file fields

The first field on every line is reserved by default for the telephone number to be dialed. This number is placed on the $fax_phone, $voice_phone or $poll_phone command line as appropriate. For special applications you can also pick the telephone number from a different field as described below. This first field is also the default field for an e-mail address to be used in e-mail broadcasts.

For voice broadcasts, the second field may be used for the infobox number to transfer to, if the interaction is to start with a different infobox for different called parties, in which case the second parameter on the $voice_phone command must be ?. FFBC will stop if this field is missing on any records when no default infobox has been specified in the template file.

For poll broadcasts, the second field may be used for the mail box number to receive the polled document, if the polling is to use different mail boxes for faxes from different called parties, in which case the second parameter on the $poll_phone command must be ?. FFBC will stop if this field is missing on any records when no default mail box has been specified in the template file.

For normal fax broadcasts, the second field is reserved for the recipient name. In addition, up to three following fields may be specified to be concatenated with the second field into the recipient name. This provides some compatibility with the FAXBC and WBC programs which normally concatenate separate name elements into one recipient name. For details of how to concatenate fields in this way, see the description of the template command $fax_receiver below.

Remaining fields on the list file line are placed in $var_def commands in the generated FS files. The variable names used are of the form BCFn (broadcast field n). These variables work like MEMOn variables, in that they are left blank in the cover sheet if not defined, and they are not partially expanded (e.g. BCF3 is not used to expand @BCF30 if no BCF30 variable is defined). This allows FFBC to suppress the generation of the $var_def command if the variable is empty or not defined on the list file line. The number following 'BCF' corresponds to the field number in the CSV file, so there is never a BCF1 or BCF2 (these are reserved fields) and there may be an additional three numbers missing (BCF3 up to BCF5) if fields have been concatenated with the recipient name as described below.

Using the template file commands

Apart from the special DNS command described below, the template file contains normal .FS file commands. All commands in the template file other than those described specifically below are copied over to the created FS files. When appropriate, the commands described below are also copied to the generated files. Conditional commands such as $if can be included and can use the BCF variable definitions which are inserted at the head of the generated file. Conditional commands are NOT processed by FFBC, but are passed through to the generated FS file for use by applications which read the FS file.

The commands with special significance for broadcast applications are as follows:

$fax_phone ?

This command (with the special '?' parameter) defines the template as a fax broadcast template. Since fax broadcast is the default, this is not a required command, but if used it overrides the voice and poll phone commands. To pick the phone number from a field other the first, follow the ? by the field number (with no spaces). So '?3' picks the phone number from the third column of your list.

$voice_phone ? [infobox]

This command defines the template as a voice broadcast template. If the infobox default is not supplied then a second variable on each list file line must be supplied as the infobox number, or the broadcast item will fail. To pick the phone number from a field other the first, follow the ? by the field number (with no spaces). So '?3' picks the phone number from the third column of your list.

$poll_phone ? [mailbox]

This command defines the template as a poll broadcast template. If the mailbox default is not supplied then a second variable on each list file line must be supplied as the mailbox number, or the broadcast item will fail. To pick the phone number from a field other the first, follow the ? by the field number (with no spaces). So '?3' picks the phone number from the third column of your list.

$email_address ?

This command defines the template as an e-mail broadcast template. To pick the address from a field other than the first, follow the ? by the field number (with no spaces). If the template also contains a $fax_phone or $voice_phone command then the transmission may be attempted as both e-mail and fax or phone, the $email_option command specifying which is tried first. Obviously, the two commands should reference different columns in the list, and if the e-mail address column is blank the e-mail transmission will not be attempted.

$fax_receiver fieldspec

The fieldspec is used to specify how many fields (starting from the second field in each record) comprise the recipient name in a fax broadcast. This feature allows list files prepared for FAXBC or WBC to be used with FFBC, but the default is to use one field only for the complete recipient name. FAXBC and WBC default to concatenating first-name and last-name fields into the recipient name.

The number of fields used (up to 4) is specified by the number of '?' symbols in the fieldspec parameter. The default fieldspec if no command is given is a single "?", which causes just field 2 to be used for the complete recipient name. For example a fieldspec of "? ?, ?" could be used if fields 2, 3 and 4 contained first-name, last-name and company, to produce a recipient name such as "Steve Hersee, Copia International" from three separate fields "Steve","Hersee","Copia International".

$fax_tosend n

This command is used to force FFBC to save the generated FS file in the appropriate TOSEND directory, where n is a number between 1 and 9. FFBC checks that this directory exists.

$fax_cover filename

This command is used to determine the file-extension of the cover sheet template file.

$var_def BCFn selection

Variable definitions for the BCF special fields are used in the template file for record selection. When any such variables are defined, a record is only used in a broadcast if its instance of that field value equals the template selection value.

You can use multiple definitions of the same or different variables and records will be selected which match any of the definitions. Comparisons ignore the case of alphabetic characters. These special selection commands in the FST file are not transferred to the generated FS files, but those for other variables are transferred.

One or both of these keywords may be assigned to the FFBC_OPTIONS variable. The OMITLISTHEADER keyword causes the first data row of the broadcast list to be discarded, on the assumption that it is a header line containing field names.

The DEDUPE keyword causes the broadcast list to be checked for duplicates as the broadcast is launched. Duplicated items will fail with outcome code 127. The first item found of each duplicated set is the one which is retained.  The default is to use the destination (phone or email) plus the $fax_receiver value to check for duplicates. This can be overridden using the DEDUPE_FIELD_NUMBERS variable.

$var_def DEDUPE_FIELD_NUMBERS value

This variable can be used to override the default key used to check for duplicates. Its use is described in Appendix D.

$fax_pages ?

This command (with the special '?' parameter) causes FFBC to calculate the number of pages defined by the $fax_filename and $fax_cover commands in the template file. This feature may be needed if a bureau client uploads a master document for an automatically launched broadcast, and the number of pages to be sent cannot be determined in advance. The calculation takes account of multiple-page TIFF/F or DCX files, but any ASCII file is counted as a single page only unless you use the pre-conversion option. It requires that the machine running FFBC can see the image directories. If you condition the inclusion of documents with $if commands in the template file, the calculation will probably be incorrect.

$fax_origin

This command in the template file is always forced to show origin user_request in the generated FS file.

In addition to the special processing described above, FFBC warns if the filenames on the $fax_user, $fax_filename and $fax_cover commands cannot be found. It also generates $fax_request_date and $fax_request_time commands giving the time that the broadcast is generated.

Do-Not-Send processing

When you need to exclude specific phone numbers, it improves efficiency if FS files are not generated for the COPIAFACTS server to later discard. However, the records excluded at this stage will not appear in any reports of summaries. If you do not mind this disadvantage, you can specify a DNS file for a specific broadcast using the following command:

$DNS_file ndxname

This command is used to specify the full pathname (with NDX extension) of a special NDX file which will be used to exclude items from the broadcast when the phone number matches an entry in the index. The NDX file can be the same format as used for the main CopiaFacts DNS.NDX file, although that file must have a numeric key whereas the file named on the $DNS_file command in the template may alternatively have a character key.

Note that FFBC locks the NDX file while it processes exclusion tests on the broadcast list. However it takes less than a second to process a list of 10,000 items against an index containing 1000 numbers, so this is unlikely to cause a problem. If your NDX file changes between loading FFBC in visual mode and clicking 'Go', the changes will not be reflected unless you make a change on the template screen in order to force re-evaluation of the exclusions.

This special FST file command is not a valid command for FS files and is therefore never carried through to the generated FS files.

Running the FFBC program in console mode

FFBC assumes that you have run the CopiaFacts SETUP on the machine on which it is being run, and uses the normal .INI files to find the CopiaFacts configuration file and request directories. No environment variables are needed. You can run in console mode from a Windows console session, or from a CopiaFacts run-box, typically in a batch file.

There are two required command-line parameters, first the list file name and then the template file name. If FFBC finds that the first file name has .FST extension and the second has .LST extension, it will silently fix your error.

The optional third command-line parameter can either be preview or test. The first causes no FS files to be written and no incrementing of the NEXTFS number to take place. Instead the first non-excluded record in the file is displayed in the console window to allow you to verify what would be placed in the generated FS file, and to allow you to check that the target directory is correct. The test parameter, in addition, generates a single FS file from the same record. You can use this feature to send a test of the broadcast back to the originator, provided that you make sure that the appropriate record is the first non-excluded line in the list file.

Any other value for the third parameter (other than visual, described below) causes only the log messages to be output, and no broadcast is generated.

For example, to preview the first FS file which would be generated:

FFBC c:\faxfacts\bclist20 c:\faxfacts\bc20.fst preview

To run the program 'for real' it will often be convenient to use a batch file, and possibly to record the processing in a log file also, for future reference:

FFBC c:\faxfacts\bclist20 c:\faxfacts\bc20.fst >bclog

The log file contains any warning or error messages generated by FFBC, together with a summary of the FS numbers used. If you do not redirect the output this information appears in the console window.

Running the FFBC program in visual mode

FFBC can be run in visual mode either by using no command-line parameters at all, or by specifying two filenames and a third parameter of visual. Do not run the program in visual mode from a CopiaFacts run-box. To guard against accidentally running in visual mode in this way, FFBC terminates if no mouse-clicks or keystrokes are received within 15 seconds. This timeout is disabled as soon as you have started interacting with the program.

When you start FFBC in visual mode, a console window appears briefly, then closes. This is a consequence of the way that Windows launches programs. To avoid seeing this window when starting FFBC from a Program Manager icon or a shortcut, select the Run Minimized checkbox which will cause an icon to flash briefly instead of a console window.

Because the broadcast list file will usually be derived from a separate master database file, FFBC does not currently allow editing of this file. The list data can be viewed in a scrollable window, and you can adjust the column widths if required. Lines representing excluded records are grayed, and if the exclusion is as a result of do-not-send processing the phone number appears in red. When the Broadcast List page is active, the Open button can be used to load a different list.

The Broadcast page allows you to select cover sheet, documents, delays, variables, and priority more conveniently than just by editing the template file. Changes you make on the Broadcast page are reflected on the Template page, and vice-versa. The Broadcast page uses the specified or default user profile $image_locn commands to locate documents by image number, or you can specify a particular fax file which need not be in your image catalog. Any fax files included on this page are analyzed to create a page count which you can use on the cover sheet in the normal way. If your template file contains conditional commands or more than eight fax filenames, the Broadcast page is disabled.

When the FS Template page is active, the FS Template file can be edited, and saved with the same or a different filename. Selecting New brings up a standard template file, which because it has no fax filename or cover sheet filename will have warnings and errors reported. These error reports are intentional, and will go away when you edit the template to include all the necessary data. It is not necessary to save an edited template file before launching a broadcast. Error and warning messages appear on the Log Messages page, which you should read carefully before and after launching a broadcast. FFBC does not prevent you launching a broadcast when warnings have been noted which could cause the broadcast to fail. Unlike console mode in which only the first record can be previewed or tested, visual mode allows you to preview or test any record. Select the record you wish to use from the Broadcast List page.

The Test and Go! buttons cause FS file(s) to be generated, normally with no further confirmation requested. There is a facility to Stop! a broadcast with the same button that you pressed for Go!, but since FFBC generates FS files at around 100 per second on most Windows systems, you have to be quick. If you press Go! a second time without loading a new broadcast list, you will be asked for confirmation before you generate another broadcast to the original list.

 

---

Topic url: http://www.copia.com/support/refmanual/index.html?faxbroadcasting.htm