Installing and Activating
the BillMax Customer Portal
BillMax Billing Solutions
The iSpark Group, Inc.
PO Box 1947
Colleyville, TX, 76034
USA
877.245.5629
817.446.7776
Fax 817.446.7773
BillMax Documentation
Copyright 1994-2014 The iSpark Group, Inc.©
Documentation for BillMax 2014
All rights reserved. No part of this documentation may be reproduced or transmitted in any
fashion without written permission by The iSpark Group, Inc. This documentation is for use
of evaluating the BillMax billing software created by The iSpark Group, Inc or for the use of
licensees of the BillMax billing software created by The iSpark Group, Inc. Any other use of this
documentation without written permission of The iSpark Group, Inc. is a violation of the use of
this documentation.
While precautions have been taken in the preparation of this documentation, The iSpark Group,
Inc. assumes neither liability nor responsibility for errors or omissions, or for damages resulting
from the use of the information contained herein.
All terms mentioned that are known to be trademarks have been appropriately capitalized. Use
of the a trademark does not affect the validity of any trademark or service mark.
Links to third-party Web sites are provided for convenience. The iSpark Group, Inc. is not
responsible for any content contained in the third-party Web sites.
Comments about this documentation may be sent to <doc@billmax.com>.
Table of Contents
General Overview ............................................................................................................... 3
Compatibility and Location Issues ......................................................................................... 3
Initial Configuration of the Customer Portal on the BillMax Server .............................................. 3
1
Installing and Activating the
BillMax Customer Portal
Create and Install the Edge SSL certificate ..............................................................................
Start the Edge Service .........................................................................................................
Test Basic Functionality .......................................................................................................
Software Requirements for Public Web Server .........................................................................
Customize Pages .................................................................................................................
Installing the Customer Portal On Public Web Server ................................................................
ServerPlus and TowerCoverage Interfaces ...............................................................................
2
4
4
4
4
5
6
6
Installing and Activating the
BillMax Customer Portal
General Overview
The BillMax Customer Portal software functions in two distinct ways. In the first mode, the Portal allows
"self help" where existing end customers can access their account for activities like viewing bills, updating
account information, and making payments. In the second mode, the Portal acts as a shopping cart where
new customers can establish new service.
The Portal is designed to be a "drop in" to a provider's public web site. This is accomplished via the use
of an iframe. In this manner, the Portal can be styled via CSS to have the same look and feel as the rest
of public web site.
Please note that the Portal is licensed separately from the main BillMax software. If your license key
description does not show 'Customer Portal Yes' under the Modules section, you will need a license. Please
contact sales@billmax.com for details.
Compatibility and Location Issues
Warning
Customer Portal clients (applications) prior to BillMax 2013.Q4.4.0.4119 (released 12/17/2013)
are not compatible with newer versions of the Customer Portal server. Running an older version of
the client software with current portal server software may result in protocol mismatch errors. In
these cases, the remedy is to update the client software from the same release as that of the server.
The location of the portal files has changed from earlier releases. To clearly separate BillMax staff interface
files from the portal files and to facilitate the transfer of files to remote web servers, the files have been
moved to a new directory in the web server's document root called portal.
Initial Configuration of the Customer Portal on
the BillMax Server
In the BillMax web interface, select the System Administration menu. Then click on Remote Applications
(under the Interface section). Then click the NEW button on the menu on the left side of the page. The
following instructions will configure a basic Customer Portal for self help use.
• Specify a name and description.
• Make sure Type is set to 'Customer Portal'.
• Specify the Virtual Company and Profile to be used for this instance. These will be used when creating
new accounts if the Portal is in shopping cart mode.
• Specify a username and a password. This username and password are used to authenticate the remote
client Portal software.
• Optionally, specify other Customer Portal Login settings as desired.
• Save the record. This will also create a set of default edgedata records which control access to
the database schema.
• Edit the file /usr/local/billmax/html/portal/billmaxedge/lib/php/local/
billmaxedge.ini and enter the username and password entered above.
3
Installing and Activating the
BillMax Customer Portal
Create and Install the Edge SSL certificate
• As the BillMax system user (typically 'billmax') run the following from the command line:
/usr/local/billmax/bin/certs.pl
When prompted, enter the same value for every password/passphrase request.
• Run:
cp /usr/local/billmax/local/root.pem
/usr/local/billmax/html/portal/billmaxedge/lib/php
• Edit the file /usr/local/billmax/local/edge.conf and supply the password entered above.
Leave the port alone. If you change it, you must change the value in the edge.wsdl file (see below).
• If you plan to utilize the one page sign up form instead of the standard portal's storefront.php entry
point, please edit the /usr/local/billmax/html/portal/signup.php file as desired. See
the file content for instructions.
Start the Edge Service
The Edge service is a BillMax daemon that services incoming requests from remote applications like the
Customer Portal. It must be running in order for the Customer Portal to function. As the root system user,
run:
cp /usr/local/billmax/bin/bx_edge /etc/init.d
chkconfig --add bx_edge
chkconfig bx_edge on
service bx_edge start
Test Basic Functionality
Once the Edge service is configured and started, via the steps listed in the prior section, you should test
whether or not the configuration is correct locally before installing and using the Customer Portal on a
remote web server. To test, using your browser, enter the URL https://billmax-server-ip/portal/login.htm
where billmax-server-ip is the IP address of the billmax server. If the result is a login page, the Customer
Portal is operational.
Software Requirements for Public Web Server
• For security reasons, the BillMax server should reside in a local area network behind a firewall and the
Portal client software should be run on a provider's public web server. Assuming a working public web
server is in place, the following additional prerequisites are required:
• php
• php-pear
4
Installing and Activating the
BillMax Customer Portal
• php-soap
• php-mcrypt
• php-xml
• php-gd
• PHPTAL
• To install these packages (assuming your public server is running CentOS), run:
yum -y install php php-pear php-soap php-mcrypt php-xml php-gd
pear install http://phptal.org/latest.tar.gz
/sbin/service httpd restart
• If your remote public server is not running CentOS, please consult your operating system's
documentation on how to install PHP and these components.
• Please note that, depending on your OS and how PHP is configured, some additional requirements
may exists. The easiest way to discover missing dependencies is to use the portal. Please contact
<support@billmax.com> and provide details and error messages should the portal fail to function
properly.
Customize Pages
The Customer Portal may be easily modified to hide functionality or change the layout or styling. As
an example, some service providers may wish to hide the sign up link on the login page to prevent
new accounts from being created. To achieve this, all that is needed is a quick edit of the ./portal/
billmaxedge/lib/php/templates/userLogin.html file.
The following listing shows the directory layout for the Portal. Relative paths (to the web server's document
root) are shown.
• ./portal - Base directory for all BillMax remote applications. This directory holds certain entry point
scripts and portal directories. Many of these are examples (stubs) for the html that you would include
as an iframe on your public web server. For example, the ./portal/login.htm file contains
JavaScript and an iframe that normally would be included within an existing page at your public web site.
• ./portal/billmaxedge - Holds the vast majority of files needed for the Customer Portal as well
as the TowerCoverage interface.
• ./portal/billmaxedge/css - Holds the style sheets for the Customer Portal.
• ./portal/billmaxedge/lib - Holds php files and templates.
• ./portal/billmaxedge/lib/js - Holds the JavaScript for the Customer Portal. Should not be
edited.
• ./portal/billmaxedge/lib/php - Holds php files. Can be edited by more advanced users.
• ./portal/billmaxedge/lib/php/templates - Holds PHPTAL html templates. These files
can be edited for look and feel or to hide certain capabilities.
5
Installing and Activating the
BillMax Customer Portal
Warning
All edits should only be done on the local BillMax server instead of the remote web server so
that the BillMax upgrade procedure can integrate any updates with local changes. Never edit the
remote files separately. Instead make the changes on the BillMax server, then copy the changes
to the remote web server.
Installing the Customer Portal On Public Web
Server
• Create a tar file of the files. These files include interfaces for the standard Customer Portal, a one page
sign up form, ServerPlus and TowerCoverage integration. Use the following command:
cd /usr/local/billmax/html
tar czf edge.tgz portal
• Copy the tar file to the public web server and extract into your web site's document root. For example:
scp edge.tgz root@your-public-ip:/var/www/html
On the public web server:
cd /var/www/html
tar xzf edge.tgz
• Make sure the extracted files have the correct ownership and permissions for your web server.
• The login.htm, storefront.htm, etc. are simple wrappers for illustration purposes. You will
probably wish to place the iframe within existing pages at your site and remove these files after testing.
• Edit the line <SOAP:address location="https://localhost:1800"/> in the file ./portal/
billmaxedge/lib/php/edge.wsdl and specify the host name or IP address and port of the
BillMax server. This line can be found near the bottom of the file.
• Make sure that any firewall software allows communication between the public web server and the
BillMax server over the specified port.
• Make sure that SE-Linux is disabled on the public web server.
• Note that php-soap caches various information about web services. If you access the Portal, then change
the WSDL file anytime thereafter, you will need to remove the cache file (typically the file name begins
with /tmp/wsdl-) and restart the web server.
ServerPlus and TowerCoverage Interfaces
• The ServerPlus interface provide integration between BillMax and their call center/customer
support application. See ServerPlus web site [http://www.serverplus.com] for details. To utilize this
functionality, you must be licensed to use the Customer Portal and you must install the portal files
(as described in the section above). Furthermore, some additional configuration is required. See the
ServerPlus Configuration document for details.
6
Installing and Activating the
BillMax Customer Portal
• The TowerCoverage interface provide integration between BillMax and their customer self
qualification coverage maps and data gathering services. See TowerCoverage web site [http://
www.towercoverage.com] for details. To utilize this functionality, you must be licensed to use the
Customer Portal and you must install the portal files (as described in the section above). Furthermore,
some additional configuration is required. See the TowerCoverage Configuration document for details.
7