One of the most popular applications for InterFAX is in time-sensitive order processing applications, such as restaurant and take-away ordering. Time-sensitive applications are usually business-critical processes, as each fax represents an actual order by a web visitor.
The visitor is unaware that his order, which has been placed and charged through a web site, travels to the order-fulfillment destination by fax, and that a number of variables may delay or prevent its arrival. Therefore, special precautions must be taken to ensure the faxes' arrival.
In order to overcome various faults that may keep an order from reaching its destination, programmers developing with InterFAX must implement a closed-loop logic to track faxes' progress through the system up to their ultimate delivery. This requires using InterFAX through its API (and not via email-to-fax) for two reasons:
- When submitting a transaction through the API, the submitted fax's ID is returned in the response.
- The API offers operations that enable the retrieval of a submitted faxes status.
A backup procedure must be in place to alert an administrator of a failure. The administrator must be able to retrieve the failed fax (for example, by entering the InterFAX online screens and finding the failed transaction) and either to resubmit it manually or to forward the message by alternative means.
High availability web service
InterFAX offers a high availability web service to ensure “always on” service to clients sending time sensitive faxes. Programmers developing with InterFAX are recommended to integrate with the HA web service (please refer to our API documentation for more details)
The following steps are suggested to implement a closed-loop logic to track a faxes progress through the Interfax system:
- Create a local database which will act as a local copy of the InterFAX outbound queue for the subset of your transactions. The fields you will need are the same as the output fields of the FaxQuery method. Make the data in this database accessible to your users, formatted however you like.
Sending a fax
- When you submit a fax (using one of the Send* methods), you receive a (positive) transaction ID number on InterFAX back as a token. Create a new (mostly empty) record in your local database with this transaction ID and record your local Status field for that record as -1 (Preprocessing).
If you receive a negative number back from InterFAX when submitting your message (see Web Service Return Codes), especially an error -150 (System Error), you need to act on the error code. You may wish to retry submitting your message several times. If no positive number is returned after retries - alert an administrator. A negative number - or no response at all - means that your message has NOT been accepted and that NO fax is about to be sent.
Wait two minutes. (If submitting hundreds of faxes at once, wait 10-20 minutes).
Check your local database to see if there are any transactions whose Status is a negative number (that is, pending faxes).
Use the FaxQuery method to query InterFAX for all transactions retrieved in #4 , by setting property Verb to IN and property VerbData to a comma-delimited list of your pending transactions. InterFAX will return status information for all queried transactions. For transactions whose retrieved Status is a negative number (which means that they are still in transmission) do nothing. For transactions whose retrieved Status is zero or greater - update all of the retrieved fields, and especially the Status field, in your local database.
Action on fax status
Three situations you need to consider at this point:
a.) Faxes that take longer than a predefined duration to send (say, 20 minutes). This might indicate an outage at InterFAX and you may wish to alert an administrator. (If you have a fallback provision, such as a secondary provider or an in-house fax modem, this is the time to use it.)
b.) Faxes that have failed (Status > 0). This can be the result of a busy, non-answering, or wrong destination number. You may wish to alert the user that a fax transmission has failed, so that s/he can act upon this information, e.g. verify the fax number, re-attempt transmission, etc. You may need to update the local database with the current status and prevent further status queries to be made on this fax.
c.) Calling the Web Service query returns a negative number or times out. This means that there is a problem with the Web Service. You may wish to retry several times. If no positive number is returned after retries - alert an administrator. Please note the InterFAX system limitations on number of queries allowed per minute.
Continue the loop
- Go to step 3.