Tips and Tricks
…log in to PortaBilling® after installation
…locate the h323-conf-id for a call
…troubleshoot an incorrectly billed call
…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 log in for the first time, you will be requested to change the password – please remember the new password you choose. In case you do not change the root user default password, the user will expire in 14 days.
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 Toolbox and open Trace session.
2. Specify the search parameters on the Session search panel. Find the required call in the Session list and click to view the detailed information about the call.
3. 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. h323-conf-id 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.
· Open the Trace session panel and find the required call in a list of recent calls (you can specify the search parameters on the Session search panel to find all calls made in the past 5, 10, 30, etc. minutes). Click to check the h323-conf-id of the call.
3. Go to the Log viewer panel to check 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 email@example.com. 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.
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 created on the Create custom data panel and then added to a customer class.
To create a new custom field, follow the steps below.
1. On the navigation menu, select My company, and then select Custom data.
2. On the Create custom data panel, fill in the following information:
· Name – 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.
· Object – this defines whether the custom field applies to the Customer or the Account.
· Type – defines the type of field:
o Text – basic single-line input field.
o Number – input field used to store and validate numerical values.
o Date – field type used to store dates.
o Date & Time – custom field that stores dates with a time component.
o List – single select list with a configurable set of options.
· Mandatory – defines the mandatory status of the field.
· Visible to the end – this defines whether end users can see and edit the custom field on their self-care interface.
· Contains personal data – enable this option to anonymize your user’s personal data (e.g., driver’s license or insurance ID) for your staff members who, according to GDPR, are not allowed to access it.
3. Click Save.
To configure custom fields for a customer class, do the following:
1. Open the Customer сlass and go to the Custom fields panel.
2. Select the custom fields you want to associate with the customers of this customer class.
3. Click Save.
Only when configured, the corresponding fields will appear for a customer/account.
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 log in to the SIP server and make outgoing calls, be sure to include the PortaSIP® node with the appropriate tariff in the rating entry (Usage charges panel) 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. You can specify the desired period for keep_month option on the Configuration server. 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.
To do this add a new rule on the Call authorization panel and select IP in the Authorization method field. 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 (e.g., G.711, G711a, G729 etc.). Likewise, enable in-band alerting if your phone supports it, as this will help in situations when the phone is behind a NAT.
First of all, you must record a set of all the voice prompts you need (account_expired, cld_blocked and others). Convert them into “raw,” g723 and g729 formats and name the files <original-name>.sln, <original-name>.g723, and <original-name> .g729. For instance, the “account expired” message in the “raw” format will be contained in the file account_expired.sln. Create a directory on the PortaSIP® server with the name of the language in ISO 639-1 format (e.g /var/lib/porta-sip/sounds/pt-br/). Then upload the previously recorded voice prompts to the created directory (/var/lib/porta-sip/sounds/pt-br/cld_blocked.sln, /var/lib/porta-sip/sounds/pt-br/cld_blocked.g723, /var/lib/porta-sip/sounds/pt-br/cld_blocked.g729).
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 Appendices section 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.