The simplest CopiaFacts API for sending faxes, e-mails and voice messages is a 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 sub-directories, to one of which the FS file will be moved on completion.
It is important to follow the guidance below when writing applications which generate FS files for processing by CopiaFacts.
Finding the Folders to Save FS Files Into
On every machine where your application may run to generate FS files, you should first run the COPIACONNECT program.
 | This program is located in the COPIA share on the machine where the CopiaFacts Application Data area resides. It uses the location of its executable program to determine the location of the COPIA share, so it must be run from that location. On the machine where your application is running, open a run box or a CMD window, and enter: \\server\COPIA\COPIACONNECT.EXE. |
After running COPIACONNECT, using the same account in which your application will be running, your application can obtain the location of the main folders used by CopiaFacts by reading the registry:
HKCU\Software\Copia\Installers\Appdata
HKCU\Software\Copia\Installers\Netbin
HCKU\Software\Copia\Installers\SharePath
The UNCname value in the first of these registry keys is the path of the FAXFACTS folder, the second that of the NETBIN folder, and the third that of the COPIA share itself. If you have had reason to use Advanced Configuration Features, it is possible that the first two folders may not reside in the COPIA share.
COPIACONNECT will also have created system environment variables FaxFactsDir and FaxFactsLocal containing the path name of the FAXFACTS folder, which you can use to find the location of this folder. The latter variable will not be available if the folder is not on a local drive.
Finally, COPIACONNECT also creates a COPIACONNECT.INI file, which will be found in your local ProgamData\Copia folder on modern operating systems and elsewhere on others. You can also find the UNC pathname of the COPIA share in this INI file as described in the Advanced Configuration Features topic, but you should only do this as a last resort. You should never modify COPIACONNECT.INI. If your server changes or moves, re-run COPIACONNECT from the new server.
Naming the FS Files that you create
It is your responsibility to ensure that the file name part of the FS files you generate are unique. Never re-use an FS number, other than to resubmit the same transaction, with an $attempt_record history, for retry.
You should preferably maintain your own range of FS file numbers different from the all-numeric values that are used by CopiaFacts. CopiaFacts uses a NEXTFS file to control unique numeric file names.
| You should never read or write NEXTFS directly from your own applications. |
If you wish to make use of the CopiaFacts FS file sequence, you can use the NEXTFS program in a batch file or call the CF9JOBADM DLL to obtain a number from the NEXTFS file in the TOSEND sub-directory. If you have no alternative but to access NEXTFS directly, please first contact Copia Support to review in detail the locking and retry procedures you are using. CopiaFacts operations can be seriously disrupted by incorrect access to this file.
Reading and Writing FS Files
The file name of the ASCII FS file should have extension .FS and the file must contain 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. If you need to have Unicode contact, you should ensure that the $unicode command specifies UTF8 or UNICODE for FS files.
Write and close TOSEND\12345678.TFS
Rename 12345678.TFS to 12345678.FS
| This ensures that CopiaFacts does not attempt to pick up the file until it is completely written. |
| If you plan to read or move 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. Do not rely on the presence of a file in the ACTIVE folder to indicate that CopiaFacts is still processing the file. |
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.
