Introduction

The COPIAFACTS engine has the ability to write status information to a message queue in real time, thus allowing a customer-written application to monitor progress of a fax or other operation and optionally to display progress information.  The implementation of this feature provides full control over the events that cause a message to be written and the content of the messages. A separate MSMQ message queue can be specified for each COPIAFACTS node or the same queue can be specified for all nodes to write to. The queue is specified using the $monitor_qname command.

You should make use of this feature only if you need real-time information about the progress of a call as it takes place.  To simply collect immediate information about each completed call, use the Notify Queue feature instead.

Selection of Monitoring Events

For each monitoring application, a set of event codes can be defined for which a message will be written to the queue.  Event codes are of two types:

A state number as defined in Appendix B and Appendix C.  When specified, a message will be written as the specified state is entered for a call.

A call progress code (9000+) as defined in the table below.  When specified, a message will be written when the call reaches the specified condition.  These events correspond to the messages shown on the COPIAFACTS line status display.

It is important to note that when monitoring calls, both the states visited and the call progress conditions may be different for different voice and fax hardware and ports.  For this reason the implementation allows an optional event description to be specified.  As an example an event description of CONNECTED might be assigned to a different call progress code on a Diva board from that needed for a Brooktrout board.  The event description allows the application consuming the messages to be written without reference to the specific board in use.

The list of monitored events must be supplied in a text file as follows (blank lines and text following a semi-colon are ignored):

; monitorlist.txt

88=DIAL

9040=CONNECTED

93=STARTFAX

9032=PAGE

9036=DISCONNECT

30=SUCCESS

The event description (to the right of the equals sign) is placed in a variable MONITOR_EVENT which may be selected for output in the message in order to enable the consuming application to determine what event has occurred.  The actual event number is also output as the message ID.  For items in the list which have no equals sign or no text following the equals sign, the numeric message code itself will be placed in MONITOR_EVENT.  List entries with no valid numeric code are silently ignored.

Selection of Monitor Lists

To facilitate the selection of different event lists for different hardware, each monitor list is assigned an internal name, and the same internal name can be used for different board types.  For example your configuration file might contain:

$line_group BROOKTROUT  1-30

$line_group DIVA       31-60

$monitor_list BROOKTROUT WATCHFAX @FFBASE\BTLIST.TXT

$monitor_list DIVA       WATCHFAX @FFBASE\DIVALIST.TXT

When you select the internal listname WATCHFAX for a specific job or transaction, the appropriate list will be selected to work with the line group of the line which happens to be handling the fax call.  The internal list name is selected by specifying it as the value of the MONITOR_LIST variable in a CFG, UJP/USR or FS file:

$var_def MONITOR_LIST WATCHFAX

The MONITOR_LIST value can be set to an empty string to suppress the use of a monitor list specified at a higher level.  A single transaction can only be monitored using one monitor list, but multiple monitor lists can be specified for use with different types of transaction or different jobs.  Line groups specified with the same internal listname should not overlap.

Defining the Message Content

The Message Label will always be the active FS filename for outbound calls, the MCF filename for inbound fax calls, and the call number for inbound voice calls.  Note that this field may be empty if a state which is not part of a call sequence is selected in a monitor list.

The Message ID will always be the event code which triggered the message.

The Message Body will be built from the current contents of the MQM_MESSAGE_TEXT variable.  This variable will normally contain a string of variable expansions and delimiters which are expanded as the message is written.  The MQM_MESSAGE_TEXT value should normally specify the same variables to be expanded at all stages of the transaction: obviously not all will be relevant at all times. For example there will be nothing useful in @OC_SENTPAGES in a message sent for the DIAL event.

Table of Call Progress Events

The following table shows the codes applicable to each board type:

Board Types:

EN     Dialogic Diva and TE-Systems

FM     Fax Modem

PO     Commetrex BladeWare (IP and Sangoma)

BM     Dialogic Brooktrout TR1034

DF     Dialogic VFX40 and R4 (no events shown)

 

Event Code, Description, Board Types:

9001   Initialize fax board              BM

9003   Idle Fax                  FM

9032   Transmitting Pn       EN  FM  PO  BM

9033   Receiving Pn          EN  FM  PO  BM

9034   Disconnecting         EN          BM

9036   Finished Pn                   PO

9038   Receiving EFF Pn                  BM

9039   Transmit EFF Pn                   BM

9040   Connected             EN

9041   Start Receive             FM

9042   Start Send                FM

9043   Received DIS              FM

9044   Sent DIS                  FM

9045   Received DCS              FM

9046   Sent DCS                  FM

9047   Start Training            FM

9048   Disconnected              FM

9049   Ringing                   FM

9050   LI-Disconnect         EN

9051   LI-Connect            EN

9100   (see below)           EN  FM  PO  BM

9200   (see below)           EN  FM  PO  BM

Notes

Event code 9032 is normally signalled at end of page, but CopiaFacts also generates an event as transmission starts, to indicate 'transmitting page 1'.  Instead of requesting event 9032, you should normally select 9100.  Selecting this value will cause events 9101, 9102 etc. to be signalled, indicating 'transmitting page 1', 'transmitting page 2', etc.  Code 9199 indicates a page count of 99 or higher.  An event of this type is not signalled if the indicated transmitted page number exceeds the number of pages scheduled for transmission.

Event code 9033 is normally signalled at end of page, but CopiaFacts also generates an event as reception starts, to indicate 'receiving page 1'.  Instead of requesting event 9033, you should normally select 9200.  Selecting this value will cause events 9201, 9202 etc. to be signalled, indicating 'receiving page 1', 'receiving page 2', etc.  Code 9299 indicates a page count of 99 or higher.  An event of this type will normally be signalled after the last page has been received, indicating one more than the final page count.

Codes 9038 and 9039 are used for Brooktrout Enhanced Fax Formats, of which only color fax is currently supported.  These codes can also be replaced with 9100 and 9200.

The OC_ variables for transmitted faxes, and the PR_ variables for received faxes, may not be available in call progress event states.