The CopiaFacts Fax Send (FS) API

The CopiaFacts API for sending faxes, e-mails and voice messages is a simple file-based API. Any program which can write an ASCII file into one of the TOSEND directories can initiate a fax transmission. CopiaFacts will monitor the transmission, control retries, and report the results. If your program needs to determine the outcome of the transmission it can either read the DBF daily log file, scanning for the FS file number, or monitor the SENT and FAIL subdirectories, to one of which the FS file will be moved on completion.

The file name of the ASCII file should have extension .FS and the file contains commands listed under FS File Commands. As a minimum for fax operations, you must specify $fax_phone and $fax_user. Also, you must either specify a cover sheet with $fax_cover or one or more documents to be transmitted, using $fax_filename, or both.

The filename part of the FS file must be numeric and unique.  Never re-use an FS number, other than to resubmit the same transaction, with $attempt_record history, for retry.  You can either maintain your own range of FS file numbers different from that used by CopiaFacts, or you can use the NEXTFS program or the CF8JOBADM DLL to obtain a number from the NEXTFS file in the TOSEND subdirectory. We recommend that you do not access the NEXTFS file directly.  If you do so, please contact Copia support first to review in detail the locking and retry procedures you are using.  CopiaFacts operations can be seriously disrupted by incorrect access to this file.

To ensure the maximum reliability of your application, we strongly suggest first writing the FS file temporarily with a different name, or in a different directory, and renaming it when you have completely written it. There may be a brief time window in which the file is readable by CopiaFacts after it has been created but before it has been completely written.  For example:

      Write and close TOSEND\12345678.TFS

      Rename 12345678.TFS to 12345678.FS

This ensures that CopiaFacts does not pick up the file until it is completely written.
If you plan to process (for example to archive) an FS file from SENT and FAIL it is essential that you wait before processing it.  The fact that a file appears in SENT or FAIL is not a signal that CopiaFacts processing of the transaction is complete.  We recommend that you do not process a file in SENT or FAIL unless its last modification time is more than a minute ago. If you are not processing it from the file server, you should allow for the fact that the file time may not exactly match the time on the machine your application is running on.

You can use the TOSEND1 through TOSEND15 directories, when defined on the $request_dir configuration command, to control the priority of the transmission or the blackout times. You should not normally place FS files directly in the special preprocessing directories for document conversion; CopiaFacts will move such files from the TOSEND directories when needed.

Examples of FS files