Sales

Support

Cyberfax Mini/Mainframe Interface

While our fax server was developed as a "direct" interface to Tech-7 Systems (Tigard, Oregon) travel reservations software for sending fax/email invoices, payment reminders, broadcast advertising, etc,  and processing credit cards , it is very easy to have your own custom interface created for practically any other large system application.  

This, of course, depends on your vendor and their willingness to allow or provide customization.  The information provided here should allow any of these vendors to quickly add the ability to send email and faxes from your existing application(s).

We are supplying this information in order to allow you to use the vendor of your choice to do whatever is needed to incorporate this very flexible server into your business.

Fax/Email

Our software processes "command files" which contain all of the information needed to send a fax and/or email.  These files are created in a specific location on your main server hard drive with a specific name.  If you have the Samba "lan manager" installed, Cybers makes it easy to "mount" a main server shared directory onto the Cyberfax server. You simply create/copy these "command files" to that shared directory or you may use ftp to quickly send the command files to Cyberfax.

These "command files" may contain multiple outgoing faxes/email so it works well for single faxes/email as well as bulk.

A 'command file' may contain any html code you wish to use for formatting including html references to images.  We use a GPL/GNU based html converter called htmldoc .  This converter program handles a large percentage of the latest html code but you should test the html code you intend to use by sending the fax/email to yourself.

Note: If you include image references for faxes you should be aware that fax machines are not capable of very good resolution and generally handle color images badly.  Faxed images should be black & white with minimal detail. 

Each fax/email 'command file' consists of header lines that tell Cyberfax what to do with it as in the example below as well as the text and html code for the fax/email. You should create a single temporary file and append as needed. When done you simply close the temp file and rename or move it to "filename.###" where filename is a predefined name (use "cyberfax" as in cyberfax.001) and ### will be a Cyberfax  job number you setup for Cyberfax using the Cybers browser program.  Cyberfax can currently do up to 50 different jobs simultaneously as described by clicking here.

You may insert several "hidden" commands into the 'command file' to tell Cyberfax what to do.

The most important hidden commands are ^#^ and ^!^ which must be placed at the top of the fax/email and the bottom respectively. If either is missing the fax will either not be sent (incomplete) or may cause one fax/email to be merged into another..

As an example, consider the following for an "Invoice" job.

The first line of a new invoice is:

^#^5031235555

Where the first 20 characters following the ^#^ are used for the fax phone number or E if it will be an email (example: "^#^E" )

If it will be an email you need to include the following lines.

^email^From: faxmaster@whoever.com
^email^Subject: Booking 123456 Invoice
^email^To: receiveemail@abc.com

These 3 lines give the sender email address, who will receive it and what it is for. The "From:" should be a valid email address in case of reply. The "To:" must be the correct address to send it to.  The "Subject:" can be anything but should not be blank.

If it is a fax or email you should include the following Information line so that it can be reported on the logs:

^I^ B=reference1   R=reference2

(that is an uppercase i in ^I^)

There cannot be blanks in reference1 or reference2. Cyberfax will stop at the first blank space in each. You should buffer at least 5 characters following the last reference. Anything other than these two fields are ignored.

The end of the last page of the invoice needs a line:

^!^

(that is an exclamation)

Thats all that is needed. Please be aware that Cyberfax will not adjust your faxes to fit on a page.  It is up to your output program to generate the correct page length while taking into account any differences caused by using html code (font size & images).

^#^5036635354 
^I^ B=123456  R=Cyberfax     
                          Example Faxed INVOICE            Page 1
Attn: Jane                                            Tour Code: ABC 
ABC Travel                                          Travel Date: 01/01/05
123 Main St                                             Returns: 01/15/05
------------------------------------------------------------------------- 
1 night @ ABC Hotel

<form feed (control L)> 
------------------------------------------------------------------------- 
Invoice payment stub info 

^!^ 
^#^E 
^I^ B=123456  R=EmailInvoice     
^email^From: autofax@here.com
^email^Subject: Your invoice for booking 123456
^email^To: receiver@customer.com
                          Sample Email   INVOICE            Page 1
Attn: Jane                                            Tour Code: ABC 
ABC Travel                                          Travel Date: 01/01/05
123 Main St                                             Returns: 01/15/05
------------------------------------------------------------------------- 
1 night @ ABC Hotel
 
--------------------------------------------------------------------- 
Invoice payment stub info 
^!^ 

Page breaks can be done using the normal control f (^L, ASCII 12, \214\) as commonly used when sending to a printer. You should do page breaks based on a standard 8.5x11 page since most non-paper roll fax machines need this. Everything you insert into this file will be used/shown on the outgoing fax except for cyberfax commands such as the ^#^, ^x^, ^!^,  ^email^, ^P#, etc.. These lines should be ignored if you are counting the lines you are inserting.

All 'command' lines except ^#^, ^!^ and ^x^ can be anywhere inside the 'command file'. There are a number of other special commands that we have not documented but you may only need the Priority command which allows certain types of faxes to go before others. For example: You would want to use this command so that you could make invoices go before broadcast advertising.

^P^#

Where # is a number from 0 to 9 or a letter from A to Z inclusive. This line can be anywhere between the ^#^ and ^!^. The lower the number the higher the priority (0 will be sent before 9).  Letter A is a much higher priority than letter Z.

Setting a Priority level on outgoing email is irrelevant.  Outgoing email is sent immediately as opposed to faxes which must wait for an available modem.

The command ^x^ tells Cyberfax not to insert html code before converting an outgoing fax.  This command is used when you pre-format your fax as a full html web page with the appropriate header tags (<html>, <title></title>, <body>, </body>, </html>). This command must be placed on the next line immediately below the ^#^ command.

Another command allows you to insert 'graphic' pages to your outgoing fax/email:

&&filename

This command tells Cyberfax to look for a graphic image in its predefined attachment directory for all files beginning with the same filename as above.  You must not include page numbers or filename extensions like .tif or .pdf.  Cyberfax will determine the appropriate extension for you.  These "attachments" may contain up to 999 pages.  Each page is a separate file and is inserted wherever the && command is placed. Note that the "&&filename" command must be placed starting at the first position of a new line in the file.  This command cannot be used to insert images into a page.  It is used only to attach additional predefined attachments to an outgoing fax/email.

The purpose of the && command is to allow you to easily attach policy, warranty, insurance, or any other standard  information pages to your faxes and/or use it for broadcast advertising as shown below:  Each page in the attachment is a full page in the fax.

Currently each fax/email must be entered as above even though they contain the same basic information.  We are working on a change that will allow you to list a virtually unlimited list of receivers using just one set of commands (between ^#^ and ^!^).

If you will be using the ftp transfer from your main server to cyberfax you will need to create a small ftp script that first checks to see if the job file exists on the Cyberfax server (Cyberfax hasn't processed the previous one yet).  If the file exists you should have the script "sleep" and try again or exit.  If the file does not exist you would send the new file over to the Cyberfax server using a different name then use the ftp command to rename the file.  This will usually prevent Cyberfax from trying to process a file that hasn't been fully transmitted yet.  The "download" directory where you send these 'command files" to is defined using the Cybers admin tab, Cyberfax Configuration button. The 'variable' named udirdownup is set to the directory where Cyberfax will look for 'command files' from your main server.

If you use the Samba software to share a directory on your main server, you will simply copy the 'command files' to that directory on your main server then rename it as above. Just to be clear: When you are using Samba, you will define a directory that will be shared that exists on your main server.  You use the "Remote Servers" tab on the Cybers Fax Server screen to tell Cyberfax how to "mount" that shared directory onto the Cyberfax server.  Samba is available for a wide variety of platforms and can be configured for reasonable security so that only authorized users can access your main server using Samba.  There is also quite a lot of online documentation to help you install and configure Samba on your main server. 

You may use the Cybers Fax Server Status tab - Log History option to view the log of sent fax/email or you can setup a Cyberfax job to automatically create a log report which you can process on your main server.

The log report file 'cyberfax.up' is used for a log for all faxes/email you send and is formatted as below with fixed length records terminated with a carriage return line feed pair.  In other words, each line in the text file contains a fixed length record reporting the status of an outgoing fax.

The format is weird because it comes from the days when Cyberfax used serial communications to the main server and the marker fields were used as delimiters.

Based on the job # and status you could generate reports or other actions needed such as adding memos to history transactions saying the fax/email was sent or failed.

Cyberfax Jobs

Cyberfax can perform up to 50 different Jobs that are identified by a job number (001 to 999).  We have typically tried to separate similar jobs by using number ranges.  For example: Invoice/notices/reminders/statements related jobs are numbered from 001 to 050. Credit Card jobs are numbered from 400 to 499. Miscellaneous maintenance batch jobs are numbered from 600 to 999.  You can number them any way you choose.

Cyberfax jobs are assigned a 'type' consisting of one character of one of the following:

Jobs are configured through Cybers Fax Server Jobs tab.

Also, if you are using the credit card processing feature and want to settle with your bank at multiple times during the day you could have Job 500 type C queue 501 set to run at 10am, Job 510 type C queue 501 set to run at 8pm.

Credit Cards

Credit Card Approval Requests

Credit card approval requests and answers (responses from your processor) are handled very similar to the way fax/email 'command files' are handled.  The only real difference is that each credit card request 'command file' contains only delimited record(s) of credit card information formatted as below.  Each delimited line in the file is a separate transaction.

Each record (line) in the request file consists of fields separated with a ; (semicolon) delimiter.  You should enclose each field with the double " as well if it may contain the semi-colon character.  Example: field1;field2;field3;field4;field6;"ref1;my ref";etc..  Only fields which may contain a ; should be surrounded by quotes.

Request files are named "u*.snd" where * can be any string of number and letters you wish.  Do not use blank spaces or special characters in request filenames.  There are 3 exceptions:  (1) Do not use filenames starting with "uw",  (2)Do not use a filename that starts with the same prefix as the answer filename as described below.  (3) Do not use the filename prefix "ureque".  

The directory that Cyberfax looks to for these request files is set in the Cybers Fax Server Admin tab - Cyberfax Configuration button using the 'udircc=' variable.  Set this to the directory you have mounted on your main server or the directory where you ftp requests to, from your main server, just as you would do for fax/email 'command files'.

Answers to Approval Requests

All answers to your credit card requests are placed in a single file.  Cyberfax will create this file then your main server will process and remove/rename it.  Cyberfax will not overwrite this file once it exists and will not add additional answers to it.  Cyberfax will cache answers it receives until you have removed the previous answer file.

The Answer file is named according to the setting in Cybers Fax Server Admin tab - Cyberfax Configuration button using the 'ccansfilename=' variable.  The default is to use the filename of uii.ans.  This file is written to the same directory where requests are placed.

The Answer file is formatted as below.  This file may not necessarily contain responses to requests in the same order as requested and may not contain all responses.  You should assume that the answer file contains the "latest" approvals received.  Cyberfax automatically resends requests that are rejected in error by the processing program so occasionally you may not receive responses in the same order they are sent.

Transaction History Reports

Requests for a transaction history report are placed in a file named 'getccrpt.req' in the same directory as request and answer files.  This report request file has a single fixed length record formatted as below.  This record is not delimited.

Field Size Description of Transaction History Report Request Fields BeginningDate 8 mmddyyyy EndingDate 8 mmddyyyy Reference1 20 Prefixed with "UX" followed by the same reference1 used for requests (or blank) Reference2 20 Same as the reference2 used for requests (or blank) CreditCard# 20 Same as on request (or blank) Expires 8 Field is 8 but first 4 characters must be yymm followed by 4 blank spaces Reserved 20 Must leave blank Amount 10 Same as on request (or blank)

When Cyberfax gets the response to the Report request it will copy the report to the same directory used for request and answer files. The name of the report file will be xpreport.txt.  Cyberfax also archives these reports into the same directory used for archiving settlement reports as below with the name format of: "ca" plus the year as yy plus month and day as mmdd plus the extension of a unique number from 001 to 999.  Example:  "ca021105.001"  There currently is no way to view or manage these archived files with Cybers.  These reports are archived for backup purposes and a future release of Cybers will allow you to manage them.

Settlement Reports

Unlike Transaction History Reports, Settlement reports are automatically created by the "force settlement" job.  After Cyberfax has instructed IcVerify to perform a bank settlement it then requests a copy of the settlement report.  It places the settlement report into the same directory used for request and answer files with the name "xcyymmdd.###' where yy is the 2 digit year (zero filled), mmdd is the month and day (zero filled) plus a spool queue number from 001 to 999.  Each settlement will have its own spool queue file for a single date.  This report is also archived by Cyberfax with the same name except that it begins with cc instead of xc. You may use the Cybers Fax Server Credit Card Reports tab to view and delete these reports from the archive log.

Note: Transaction history and settlement reports & requests can only be done if you are using the DOS version of IcVerify.  The Microsoft Windows version does not allow third party applications to capture these reports to a fixed filename so you are forced to use the IcVerify program to manually generate these reports.  We are trying to resolve this critical automation issue with IcVerify or by using another means of forcing the IcVerify program to use a fixed filename for its report output.

Email Support: support@mercware.com