Copia provides a pre-built call-control DLL to simplify the handling of incoming faxes using the DNIS (DID) value. The processing for each dialed number (DNIS) is controlled by a customer-provided Excel file (XLS or XLSX). Each row of the Excel file must have a DNIS value in the first column, and the remaining column values on that row specify the processing for each DNIS value. Calls to numbers which do not appear in the first column are rejected.
As with all call-control DLLs, the objective is to eliminate the need to create and maintain separate USR and MBX files for each DNIS.
Installation
The provided CF9CCXLS.DLL can be installed as a call-control DLL by adding the following $load_dll command to FAXFACTS.CFG:
$load_dll * C CF9CCXLS.DLL
The DLL is loaded and initialized when COPIAFACTS starts up. If it is to apply to certain nodes only, replace the * with a node name and add a command for each node which is to use the DLL.
Basic Operations
As with any call-control DLL, the 'notification' entry-point is called as soon as an incoming call is detected, and is passed the ANI and DNIS from the call. CopiaFacts will have assigned a channel to process the call but the call will not have been answered, and no USR to MBX file will have been loaded to direct the processing of the call.
The DNIS value can optionally be modified by the DLL, and other variables can also be set to affect the processing of the call. The modified DNIS will then be used to pick one of a few special USR/MBX pairs to process the call, and can reference the variables set from the XLSX row to vary the processing for each incoming number.
The DLL returns a 0 return code to cause the call to be processed, or a negative value to cause the call to be rejected. The call is always rejected with a default cause value if the DNIS does not appear in column A of the spreadsheet, but you can also include rows for DNIS values which are to be rejected with different cause values.
Configuration
The DLL is configured by setting variables in FAXFACTS.CFG using $var_def commands.
 | These variables must be defined in FAXFACTS.CFG before the $load_dll command. |
The following variables are used:
CC_XLSX_PATH
This variable specifies the full pathname of the XLSX or XLS file which contains the parameters for each DNIS value. Because its variable name ends with _PATH, variables are expanded in the value.
The file is loaded when COPIAFACTS starts up, and again whenever the modified-time of the file is seen to have changed: it is checked every minute.
The first column in the file must be used for the values to be matched. It will normally contain the DNIS numbers and the format of the other columns is as described below. You may also optionally match on ANI numbers in this column as described below under XLS/XLSX File Format.
CC_DEFAULT_REJECT
If the incoming call's DNIS value is not found in the first column, the negative value in this variable is used to reject the call. If this variable is not present, the value -21 is used (ISDN cause code for "Call rejected"). For a system where incoming calls are SIP, you must override this value with a suitable SIP response code, for example -404.
This value is overridden for any XLS-file row where the second column contains a negative numeric value. All other processing is suppressed for calls which are rejected. No variables are set by the DLL because no script will be run to handle them.
A value of zero in this variable will cause unmatched calls to be accepted. This can be used to set variables for specific calls only.
CC_DEFAULT_DNIS
If present, this value is used to replace the incoming DNIS value. The incoming value is always saved in an ORIGINAL_DNIS variable by the DLL. In a system configured for fax mail, this default value would select a specific USR file to process all the incoming mail.
You can override this value with an XLS file column named NEWDNIS: the default value would then be used for rows where the NEWDNIS value is empty.
When a single USR/MBX pair is used, it is recommended that the USR file should contain a command $no_mbx_update to prevent the mailbox count and date fields from being updated.
CC_DEFAULT_CSID
If present, this value is used to set the CSID to be used for an incoming fax call before returning from the notification call. The special value DNIS in this variable causes the ORIGINAL_DNIS value to be set as the CSID. This value is overridden by the contents of a column named CSID, if present in the XLS file.
Example CFG Commands
$var_def CC_XLSX_PATH @FFBASE\CALLCONTROL.XLSX ; required variable
%var_def CC_DEFAULT_REJECT -404 ; (use 400-range only for incoming SIP)
$var_def CC_DEFAULT_DNIS 11111111 ; use 11111111.USR unless overridden
$var_def CC_DEFAULT_CSID "Copia 630-778-8848" ; unless overridden
$load_dll * C CF9CCXLS.DLL ; must follow variable definitions
XLS/XLSX File Format
We recommend that the Excel file should have a header row. The value DNIS in cell A1 is taken to indicate that there is a header row. Only the first worksheet in the file is used. To match on ANI instead of DNIS, place a value ANI in cell A1 of the header row, which must then be present.
The first column of the worksheet must contain the DNIS or ANI values to be matched. The length and format of each value must exactly match the format used or configured for your fax board or by your IP port and SIP provider, because the value checked is passed to the DLL as presented by the board/port interface. For the same reason, wild-card symbols are not permitted in this column.
The second column of the worksheet may optionally contain a negative numeric value to be used to reject calls to this DNIS. A negative value in this column overrides any column header specifying a variable assignment. You need have no other values on the row, because they will never be set: the call will be rejected.
Other than the above, all other columns (up to column Z only) are used to set CopiaFacts variables to assist with processing the call. If there is a heading row, this row supplies the name of the variable to be set. If there is no heading row, the variable set is named COL_x where x is the Excel column reference.
Typically the later columns might supply an e-mail address to which the incoming fax is to be sent, options to control whether the attachment is to be sent as TIF or PDF, or accounting information to be recorded about the transaction.
Special Column Processing
The special value -999 in column B returns 999 to ignore the call: it is neither answered nor rejected. This value would only be used if there is another device in parallel with the incoming telephone line which is configured to pick up the call if not answered by CopiaFacts.
The variable name (COL_x or the value from row 1) will be overridden if a cell contains an = sign and the content varname=value. You would need this if different variable names are to be set for different DNIS values.
Setting a variable named NEWDNIS overrides the CC_DEFAULT DNIS for the row and changes the DNIS value which will be used to process the call. The original incoming DNIS value is set in an ORIGINAL_DNIS variable for the call.
There is no CopiaFacts variable named CSID, but setting a variable named CSID will actually cause the CSID to be set for a received fax: it is returned from the DLL in the 'channel name' parameter as described in the main Call Control DLL documentation. If the special value DNIS is assigned to CSID, the CSID is set to the value of the ORIGINAL_DNIS.
