Tips and Tricks
…log in to PortaBilling® after installation
…locate the h323-conf-id for a call
…troubleshoot an incorrectly billed call
…make the periodic payments tab appear in the customer / account info
…make the custom fields tab appear in the customer / account info
…create a custom report from portabilling®
Use ODBC to connect to PortaBilling®
…force PortaBilling® to disconnect after a customer calls over his credit limit
…create accounts to be used for sip services
…automatically purge old xDRs to reduce the size of the database
… provide services to and bill a customer who has a SIP-enabled gateway but no authorization capability (e.g. Cisco AS5350)
… allow a customer to have two phone numbers from different countries which will both ring on the same SIP phone
… configure SIP phone X made by vendor Y
… bill incoming calls from PSTN to SIP using a special rate
... provide error messages from the media server in my users’ local language
... calculate how much bandwidth I need for my PortaSIP
... enable my SIP phone or ATA to be automatically provisioned by PortaSwitch®
There is one default environment pre-created, which contains a single user “pb-root” with the password “pb-root” as well. After you login for the first time, you will be requested to change the password – please remember the new password you choose.
Unique call IDs are extremely important for troubleshooting. They allow you locate a call in the database and find call information in the billing engine logs or RADIUS detail files. Finally (and this is the most important thing), when reporting call problems to the PortaOne Support team or your business partner, a call ID helps to prevent confusion and allows the problem to be solved quickly.
In order to find the h323-conf-id for a call, do the following:
1. From the main menu, go to Trace Session.
2. Using the CLD and from/to date filters, make sure the required call is shown in the list of calls on the page.
3. In the row containing call information, click the View icon (far left column). You will be shown detailed information about the call.
4. The first field on the page should be the h323-conf-id, which is a combination of four hexadecimal numbers separated by spaces, e.g. 5FF7F6D1 715E02C6 A40990F3 C823E27E.
1. Make sure that someone in your organization is subscribed to the PortaBilling® mail alerts (especially “Missing critical information”). This will help you to detect problems early.
2. Find the h323-conf-id for this call. This is a unique ID (a string of four hex numbers) generated by the gateway when the call was started, which will help you to exactly identify this particular call among all the others. You can find this ID by doing one of the following:
· Looking at the statistics on your gateway.
· In the BE Log Viewer section of the web interface you can find a list of recent calls (a select menu allows you to see all calls made in the past 5, 10, 30, etc. minutes).
3. Use BE Log Viewer on the web interface to find all of the information about call processing there.
NOTE: Normally we receive information about each of the call legs separately, so it is necessary that you check the log entry regarding the processing of all call legs and the final call clean-up.
4. The following are typical error situations:
· Call was not billed at all. It was considered an “unresolved” call, because we did not detect that it went to any of the vendors. Check that you have correctly defined connections to your vendors.
· Call was billed only to vendor, not to an account or customer (and you received an email alert). The billing engine needs an Account ID in the User-Name attribute to correctly identify the account and customer. Check the logs to see what was in the User-Name attribute. Typical situations are:
o Incorrect value in User-Name (for example, phone number instead of IP address of the remote gateway). Cause: the required application was not used to handle the call. Remedy: check that the application is configured and associated with the corresponding incoming dial-peer.
o On some of the call legs there is a correct value in the User-Name, while on others there is an IP address. When a call is originated on gateway A and terminated on gateway B, then a “real” username appears only in the accounting from gateway A. In gateway’s B accounting the username will be the IP address of gateway A, because gateway A had to authenticate itself before being able to make the call. This is a perfectly normal situation. PortaBilling® recognizes this and will replace a username identical to the node’s ID (IP address) with a “real” username from the other call legs.
o Value in User-Name is correct, but reports “Did not find account/customer”. Check the rating table for the account’s product. It may be that, even if you have such an account, the rating table in the account’s product is incorrect (it does not include the service consumption point where you are trying to use the service).
· Call was billed, but the phone number in the billing is incorrect (not in E.164 format) and there is a “Mismatch in rates or destinations” error. Cause: missing or incorrect translation rule on connection to the vendor. Remedy: assign a translation rule; read the Handle technical prefixes and numbering formats section in the Unified PortaSwitch Handbook Collection.
· Call was billed and the phone number in the billing is correct, but there is a “Mismatch in rates or destinations” error. Cause: missing rate for this phone prefix in the tariff. Remedy: create a rate for this destination in the tariff.
5. If you are unable to solve the problem by yourself, submit a problem report to firstname.lastname@example.org. Please make sure that you include the following in your email:
· A detailed description of the call flow and what seems to be incorrect.
· H323-conf-id of the call.
· Relevant items from the billing engine log.
The Periodical payments tab will only be shown if the rest of the system is configured to accept payments. This requires:
· At least one payment system defined in the Payments section; this payment system must have the Recurring option enabled.
· A payment system associated with the currency of this account or customer.
· For accounts, the E-commerce enabled flag must also be switched on.
· On the Payment Method tab, the preferred payment method must be set and information about the credit card entered.
For subcustomers or accounts belonging to subcustomers, the requirements are the same, except that the payment systems are defined in the reseller information, not in Payments section.
Using custom fields, you can store a set of extra attributes (e.g. driver’s license ID or tax code) that supplements the standard PortaBilling information. Custom fields should be initially set up using the Custom Fields tab on the Web Interface page and then added to a customer class.
To add a new custom field, follow the steps below.
1. On the Web Interface page, click Add.
2. For each new custom field, set the following attributes:
This defines whether the custom field applies to the Customer or the Account.
This is the descriptive name of the field; the name that will be displayed next to the custom field on the Customer / Account Info page.
Defines the type of field:
· Text – Basic single-line input field.
· Number – Input field used to store and validate numerical values.
· Date – Field type used to store dates.
· Date & Time – Custom field that stores dates with a time component.
· List – Single select list with a configurable set of options.
This enables you to customize field properties that define its form, appearance or value. These properties are specific to the field type.
Click Properties or the Wizard icon to invoke the wizard. This will enable you to define a new field format or change an existing one and to specify the default value that a custom field should have.
This is a read-only attribute which must be specified in the Properties attribute.
Defines the mandatory status of the field.
Visible to End User
This defines whether end users can see and edit the custom field on their self-care interface.
3. Click Save to save the custom field.
To configure custom fields for a customer class, do the following:
1. On the Customer Class page, select the Custom Fields tab.
2. Select the custom fields you want to associate with the customers of this customer class.
3. Click Save.
Only when configured, the corresponding tab will appear in the customer / account info.
You can delete a custom field at any time. All records of its values will then also be deleted.
PortaBilling® provides you with an open data model. An ER-diagram of the database structure is not included in this document but may be received from the PortaOne support team upon request. If you want to prepare custom reports on your workstation or a non-PortaBilling® server, you will need to do the following:
· Make sure the remote computer has database drivers installed to access the PortaBilling® database. Normally you would use native MySQL connectivity on Unix-based hosts and ODBC on Windows-based hosts.
· For any data-mining solutions (extracting data from the database), use only the replica database.
· Use a tool like Crystal Reports, Microsoft Access or some custom application to retrieve data from the database, process it and submit it to the user.
ODBC (Open Database Connectivity) provides a way for client programs to access a wide range of databases or data sources. If you need extended customized reporting not available in PortaBilling®, you can do this using external tools such as MS Access or Crystal Reports.
Create a MySQL user to be used for reports
1. Log in into your PortaBilling® replica DB server using ssh.
2. Start the MySQL command tool.
andrew@demo:/home/porta-admin$mysql -u root mysql
Reading table information for completion of table and column names
You can turn off this feature to get a quicker startup with -A
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 42122 to server version: 4.0.17-log
Type ‘help;’ or ‘\h’ for help. Type ‘\c’ to clear the buffer.
3. Create a new user using the GRANT command.
mysql> grant ALL PRIVILEGES on `porta-billing`.* to ‘reports’@’192.168.0.5’ identified by ‘pod23uk’;
Query OK, 0 rows affected (0.02 sec)
NOTE: The command above will permit access to all of the tables in the database. It is provided only as an example. You can modify it according to your actual needs, e.g. give read-only access to some tables only.
4. Flush the privileges.
mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.07 sec)
Installing the MySQL ODBC driver
1. Download and run the installation package from: http://www.mysql.com
2. Click Next on the information pages.
3. Click Finish.
Before configuring the data source, create a MySQL user on replica DB server with read-only permissions. Please examine the following document on how to add new user accounts to MySQL: http://www.mysql.com/doc/en/Adding_users.html
1. Control panel -> Administrative tools -. Data sources (ODBC).
2. Select myodbc3-test and click Configure. Fill in the configuration form. Important parameters include:
· Host/Server Name (or IP) – Hostname (or IP address) of your replica DB server.
· Database Name – porta-billing.
· User – Username of the MySQL user you have created for reporting purposes.
· Password – Password of the MySQL user you have created for reporting purposes.
· Port – The port on which the database service is accessible; enter 3307 here.
NOTE: This port number differs from the one used by default.
In MS Access
1. Create a blank database.
2. Right-click in the table design view and select Link tables.
3. Choose ODBC databases from the Files of type list.
4. Select Machine data source.
5. Select PortaBilling and click OK.
6. Select the desired tables.
In Crystal Reports
1. Create a new report.
2. In Data Explorer, open ODBC branch.
3. Select PortaBilling.
4. Select the desired tables.
There is no need for PortaBilling® to do this, as the gateway is able to by itself. When the gateway authorizes an account to make a call in PortaBilling®, PortaBilling® returns a maximum credit time in the case of a successful authorization. When the gateway connects the call, it starts a timer; when the timer hits zero, it automatically disconnects the call.
PortaBilling® sends two RADIUS attributes related to the maximum call duration. The h323-credit-time attribute is the standard one (announced credit time); there is also a custom h323-ivr-in = DURATION attribute (actual credit time). The value for the second attribute is computed with billing tricks taken into account. Thus, in the case of $10 available funds, a $0.10/min rate and a 10% post-call surcharge, this attribute will be 5400 seconds (90 minutes), while the h323-credit-time will be 6000 seconds (100 minutes).
If the application supports only the h323-credit-time attribute (e.g. Cisco default debit card application), then this time will be announced to the end user and used to disconnect the call, and h323-ivr-in = DURATION will be ignored.
There are no special requirements as to how such accounts should be created. You use the same interface to create and manage accounts for all services supported by PortaBilling® (H323, SIP). Thereafter accounts can use H323, SIP or SIP & H323 services, depending on their product’s rating table. So, if you plan for accounts with a certain product to be able to login to the SIP server and make outgoing calls, be sure to include the PortaSIP® node with the appropriate tariff in the rating table (Usage Charges tab) for this product.
Database size continually increases, thus affecting system performance: longer PDD (Post Dial Delay), longer response time on web interface pages related to xDRs (rate upload, xDR browser, invoicing) etc. Large xDRs tables also increase database query execution time. xDR Cleanup procedure is periodically executed on your system to ensure the smooth operation. By default the execution is scheduled for every day during your off-peak hours.
The maximum period for keeping xDRs depends on your requirements. We recommend keeping xDRs for the period that corresponds to the maximum period you need to generate reports plus an additional month. Thus, if you only need monthly reports, keeping the xDRs for 2 months will be sufficient.
PortaSIP is able to authenticate incoming calls using the IP address of the remote side. This method ensures that PortaSIP will accept calls from your own gateways, but it can also be used to bill traffic from your customers. In the call scenarios management screen you need to create a new entry, which would activate the “Authorize by IP” application for all calls, coming from this IP address and then create an account for your customer with an account ID identical to the IP address of his gateway.
You can have an unlimited number of such “extra” phone numbers. Your customer will have one main account (e.g. 12025550003) which will be provisioned on his phone, and extra phone numbers (e.g. 4981234567) will be added as aliases to it. Alternatively you can create extra accounts (e.g. 4981234567), with the follow-me service on these accounts configured to always go to 12025550003.
Obviously, we cannot provide a sample configuration for every possible SIP phone model. Please check the documentation shipped with your device. Essentially, however, you need to configure the following settings:
· IP address of the SIP proxy - IP address or hostname of the PortaSIP server.
· CID (Caller Identification).
· Login and password – account ID and password of the corresponding account in PortaBilling®.
· Preferred audio codec – depends on your network characteristics; should be compatible with the codec used by other components (e.g. VoIP gateways used for PSTN termination).
In the case of PortaSIP, both the login name and CID should be set to the same value. Set the preferred audio codec to G.723 if your phone supports this. Likewise, enable in-band alerting if your phone supports it, as this will help in situations when the phone is behind a NAT.
The following applies to PSTN->SIP calls, which you receive via a PSTN gateway on your network. For PSTN->SIP calls received directly to your SIP server via VoIP, see the Special Access Codes section of this guide.
In order to properly bill a SIP account for such calls, do the following:
· Install a PSTN2SIP application on your Cisco gateway which handles incoming PSTN calls.
· Create an appropriate tariff with the desired rates. For example, if your SIP customer has account 12021234567 and you want to charge him for incoming calls from PSTN to that number, there should be a rate with a prefix matching this number, for example, 1202.
· In the product associated with this account, create a rating entry with this PSTN-SIP gateway as the node and the tariff created in the previous step.
Now calls originating from a SIP phone to 1202 numbers will be charged using the tariff associated in the product’s Services and Rating list with the PortaSIP node. Calls terminated from the PSTN to the SIP phone will be charged using a different tariff, one associated with the PSTN gateway.
First of all, you must record a set of all the required voice prompts (account_expired, cld_blocked and others). Convert them into “raw” format and name the files <original-name>-<language>.sln; for instance, the Chinese version of the “account expired” message will be contained in the file account_expired-ch.sln. Then upload the files to the PortaSIP server in the /var/lib/porta-sip/sounds/ directory. This will be sufficient to enable the PortaSIP media server to play this voice prompt to SIP phones using G.711, GSM and many other popular codecs.
Unfortunately, you cannot perform such online transcoding into the G.723 or G.729 codec, since in this case you must pay a license fee. A solution is to pre-convert this voice prompt into a G.723 or G.729 byte stream, store it in a file with the same name (but with the .g723 or .g729 extension), and upload it to PortaSIP. The Media server will then use the appropriate file.
The amount of bandwidth required for SIP signaling is insignificant compared to that used by the RTP stream, so the most important task is to correctly estimate your RTP bandwidth needs (of course, this is only applicable if an RTP proxy is used, otherwise the voice stream goes directly between the SIP phone and the remote gateway).
The bandwidth will naturally depend on the codec being used. However, the “codec bitrate” parameter of the codec cannot be used for calculations since it only reflects the actual “useful” data stream. When this data is sent over an IP network it is encapsulated inside of a large number of IP packets (each packet is fairly small since they are sent frequently and do not cause interruptions). In addition to the actual data, each IP packet also contains a header with the information required to route and process the packet.
In the particular case of voice stream, the amount of actual data in the packet may be equal to or even less than the size of an IP packet header. Since bandwidth is used to transport both the header and the data – the actual amount of consumed bandwidth is higher than the codec’s bitrate.
For instance, a G.729 codec has 8 Kbps bitrate and requires about 31 Kbps of actual Internet bandwidth. You should remember that the total amount of required PortaSIP® bandwidth is twice the bandwidth required for all calls, since calls originate from both inside and outside the PortaSIP® system.
For example, if you anticipate a maximum of 60 simultaneous calls with the G.729 codec, you will need 31.2 Kbps * 2 * 60 = 3.7 Mbps.
You can use a VoIP Toolbox Bandwidth Calculator to properly calculate the bandwidth consumption required by voice calls, depending on the codec being used.
First of all, you must make sure that your device supports auto-provisioning. Find the list of the auto-provisioned devices in the APPENDIX C. SIP Devices with Auto-provisioning in the PortaSIP® Administrator guide. Then create the required IP phone profile and enter information about the IP phone into the inventory. Provision the SIP service as described in this manual, and then assign it to an available port on your IP phone in the account info screen for a SIP account.
Enter information about the provisioning server into your IP phone’s configuration. In some cases, you may need to restart the IP phone in order to force a configuration update from the provisioning server.