877.245.5629
sales@billmax.com
|
BillMax Billing Solutions 877.245.5629 sales@billmax.com |
| Chapter 1. Overview | ||
|---|---|---|
 |
Provisioning with BillMax | 
|
Provisioning by BillMax is done through a programs called BillMax Hooks. The basic concepts is that whenever data for a record of a designated table is modified or created through BillMax routines, a BillMax Hook is executed. The designated BillMax tables and the corresponding BillMax Hooks are:
| BillMax Table | BillMax Hook |
|---|---|
| account table | /usr/local/billmax/local/account_hook |
| user table | /usr/local/billmax/local/user_hook |
| service table | /usr/local/billmax/local/service_hook |
| payhist table | /usr/local/billmax/local/payhist_hook |
Data for the BillMax Hooks is provided through UNIX environment variables. The variables provided to each hook depends on the BillMax Hook that is being executed.
If a new record is being added, the environment variable NEW is set to "1". In addition, most of the fields from the table are available in the environment. The variable names are NEW_columnname. For example, if a new Account is added with account.cfname set to "John", then the environment variable NEW_cfname will be available and the value will be "John".
If an existing record is being modified, the environment variable NEW is set to "0". In addition, most of the fields from the table are available in the environment. The variable names are OLD_columnname for the values in the record before modification, and NEW_columnname for values in the record after modification. For example, if the data for a account.cfname is modified with the old value being "John" and the new value "Mark", then the environment variable OLD_cfname will be available and the value will be "John" and the environment variable NEW_cfname will be available and the value will be "Mark". Note that fields that are not modified, the OLD_* and NEW_* variables will be available and will have the same value.
In addition to data from the designated table, data from other tables may be present. The following environment variables containing the associated table data is available for listed BillMax Hook:
CONFIG_* - data from the config table to which the Account is associated.
ACCOUNT_* - data from the account table to which the User is associated.
CONFIG_* - data from the config table to which the User's Account is associated.
USER_* - data from the user table to which the Service is associated.
ACCOUNT_* - data from the account table to which the Service's User is associated.
CONFIG_* - data from the config table to which the Account is associated.
SERVDEF_* - data from the servdef table to which the Service is associated. If the data being changed is service.servdef, the environment variables are those of the new Service Definition.
ACCOUNT_* - data from the account table to which the Financial Transaction is associated.
CONFIG_* - data from the config table to which the Financial Transaction's Account is associated.
Before any environment variables are set and the BillMax Hook is executed, all existing environment variables are deleted from the environment with the exception of the following:
TERM
PATH
SHELL
HOME
USER
BILLMAXDIR
CURRENTDATE - in "yyyy-mm-dd" format.
CURRENTTIME - in "HH:MM:SS" format.
BXSESSIONID
REMOTE_ADDR
TMPDIR
LOGNAME
PRINTER
PASSWORD
REMOTE_USER
REMOTE_ID
SERVER_NAME
SCRIPT_NAME
LD_LIBRARY_PATH
These variables may or may not exist in the environment at the time of the BillMax Hook execution. If they do exist, they will not be deleted and therefore will be available to the BillMax Hook.
In addition, there may be the need to pass variables to the BillMax Hook that have nothing to do with a database table. For these instances, environment variables of which the name begins with KEEP_ may be set. These environment variables are not deleted from the environment and are available to the BillMax Hook.
Having a BillMax Hook for a designated table is optional. If there is no need for a BillMax Hook for a designated table, simply make sure that the BillMax Hook does not exist in /usr/local/billmax/local or is not executable.
Although it is discouraged, a BillMax Hook may change the data in the designated table. After a BillMax Hook is executed, the record is re-read into internal BillMax structures before processing continues.
Technical Aspects for a BillMax BillMax Hook
Successful execution of a BillMax BillMax Hook should have a return code of "0"
Unsuccessful execution of a BillMax BillMax Hook should have a non-zero return code. In addition, a descriptive error message should be printed to stderr or stdout.
If a BillMax Hook returns a non-zero return code, then either the new record will not be created or the existing record will not be modified.
A BillMax Hook is run as UNIX user RUNHOOK_USER as defined in /usr/local/billmax/local/billmax.conf.
A BillMax Hook is run as UNIX group RUNHOOK_GROUP as defined in /usr/local/billmax/local/billmax.conf.
A BillMax Hook must be executable by the RUNHOOK_USER or RUNHOOK_GROUP.
Only one instance of a BillMax Hook is active at anytime. Multiple calls to a BillMax Hook triggered by the actions of a Customer Service Representative will be executed serially.
A BillMax Hook is called anytime data is modified in a designated table. The data changes may or may not have any Provisioning implications. The uses of a BillMax Hook are not limited to Provisioning.
A BillMax Hook may be called multiple times when executing a single action.
|
|
 |
|
| Provisioning with BillMax |  |
Chapter 2. Provisioning for a Service |