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 channel 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:
$channel_group BROOKTROUT 1-30
$channel_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 channel group of the channel 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. Channel 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.
The following table shows the codes applicable to each board type:
Board/Port Types:
EN Dialogic Diva and TE-Systems
FM Fax Modem
PO Commetrex BladeWare
BM Dialogic Brooktrout
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 signaled 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 signaled, 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 signaled if the indicated transmitted page number exceeds the number of pages scheduled for transmission.
Event code 9033 is normally signaled 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 signaled, 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 signaled after the last page has been received, indicating one more than the final page count.
Codes 9038 and 9039 were used for Brooktrout Enhanced Fax Formats, no longer 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.
