portabilling: templates guide mr85...invoice templates contain such data as the period from date,...

©2000-2020 PortaOne, Inc. All rights reserved.

www.portaone.com

PORTAONE

PortaBilling

Templates GuideM A I N T E N A N C E R E L E A S E 8 6

PortaBilling® Templates Guide

© 2000–2020 PortaOne, Inc. All rights Reserved. www.portaone.com

2

Copyright Notice & Disclaimers Copyright © 2000–2020 PortaOne, Inc. All rights reserved PortaBilling® Templates Guide, August 2020 Maintenance Release 86 V1.86.02 Please address your comments and suggestions to: Sales Department, PortaOne, Inc. Suite #408, 2963 Glen Drive, Coquitlam BC V3B 2P7 Canada. Changes may be made periodically to the information in this publication. Such changes will be incorporated in new editions of the guide. The software described in this document is furnished under a license agreement, and may be used or copied only in accordance with the terms thereof. It is against the law to copy the software on any other medium, except as specifically provided in the license agreement. The licensee may make one copy of the software for backup purposes. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopied, recorded or otherwise, without the prior written permission of PortaOne Inc. The software license and limited warranty for the accompanying products are set forth in the information packet supplied with the product, and are incorporated herein by this reference. If you cannot locate the software license, contact your PortaOne representative for a copy. All product names mentioned in this manual are for identification purposes only, and are either trademarks or registered trademarks of their respective owners.



3

Table of Contents

Copyright Notice & Disclaimers ................................................................................. 2 Preface ................................................................................................................................ 4 What is new in maintenance release 86? ............................................................. 5

1. Template concepts....................................................................... 6

Real life situation ............................................................................................................ 7 Template engine ............................................................................................................. 8 Template components ................................................................................................ 10 Template parameters .................................................................................................. 13 Template data fields .................................................................................................... 15 Template groups ........................................................................................................... 22 Things to remember .................................................................................................... 25

2. Rate upload/download............................................................. 29

Upload via the rate upload wizard ......................................................................... 30 Usage of the effective from field ............................................................................ 50 When is importing tariff data not possible? ....................................................... 50 How to ... ......................................................................................................................... 56 Rate download ............................................................................................................... 60

3. Invoicing ....................................................................................... 62

How does invoicing work in PortaBilling®? ....................................................... 63 Invoice template ........................................................................................................... 65 Billing, invoicing and taxes ....................................................................................... 66

4. Layout designer .......................................................................... 70

General document properties .................................................................................. 72 Working with images ................................................................................................... 73 Placing data elements ................................................................................................. 73 Changing text attributes ............................................................................................ 74

5. External invoice templates ...................................................... 76

Creating an external invoice template ................................................................. 77 Uploading an invoice template to PortaBilling® .............................................. 82 Updating an earlier uploaded template ............................................................... 86

6. Templates for outgoing notification messages ................. 88

Notification templates ................................................................................................. 89

7. Appendices ................................................................................... 93

APPENDIX A. Variables that can be used in an external invoice template ............................................................................................................................ 94 APPENDIX B. External invoice template example ......................................... 101 APPENDIX C. Advanced template customizations ......................................... 107 APPENDIX D. Available notification messages ............................................... 115



4

Preface The PortaBilling® Templates Guide gives a detailed explanation of the template module. This manual also describes in detail how to optimally import and export data from PortaBilling®.

Where to get the latest version of this guide

The hard copy of this guide is updated upon major releases only, and does not always contain the latest material on enhancements that occur in-between minor releases. The online copy of this guide is always up to date, and integrates the latest changes to the product. You can access the latest copy of this guide at www.portaone.com/resources/documentation/.

Conventions

This publication uses the following conventions: • Commands and keywords are given in boldface. • Terminal sessions, console screens, or system file names are

displayed in fixed width font. Exclamation mark draws your attention to important actions that must be taken for proper configuration.

NOTE: Notes contain additional information to supplement or accentuate important points in the text.

Timesaver means that you can save time by taking the action described here. Tips provide information that might help you solve a problem. Gear points out that this feature must be enabled on the Configuration server.

http://www.portaone.com/resources/documentation/



5

What is new in maintenance release 86?

Added:

• The Rate download chapter.

Template concepts


6

1. Template concepts

Template concepts


7

Real life situation Before discussing some technical details about PortaBilling® and templates, let’s take a look at a “real life” example which will help us learn more.

Situation

You are the owner of a VoIP billing system. You receive list of rates from your vendors, which you need to import into the system.

Solution 1: Manual entry

In order to do this, you decide to hire a temporary worker to type in all the data. This person does not know much about your business, so you will have to give him or her detailed instructions on how to proceed. These might be similar to the following:

1. This is an Excel file from our vendor. 2. After you open it, in the first row of the second worksheet,

entitled “Rates”, you will see a title and a list of rates underneath it.

3. The value in column C (entitled “Prefix”) goes in the “Destination” field on the web interface, but do not enter 011 at the beginning of the number, if for example, your vendor provides the phone prefix for the Czech Republic as 011420. The value in column F (entitled “Price per minute”) goes in the “Price 1” and “Price N” fields on the web. There is no “Effective From” data in the file, so just enter the current date in that field on the web.

Does this sound complicated? Let’s now take a look at what you have just done:

• You have specified the file format which the data is in (“an Excel file”).

• You have specified where the required data is to be found within that file (“in the first row of the second worksheet, entitled ‘Rates’”).

• And, finally, for each data element which needs to be imported into the system (Destination, Price) you have specified:

o Which column the data is in (“column C (entitled ‘Prefix’)”).

o The format of the data (whether it needs to be changed somehow prior to being entered into the system) (“do not enter 011 at the beginning”).

Now, let’s take a look at an alternative way of handling the same process more easily, faster, and with fewer errors.

Template concepts


8

Solution 2: Template engine

Instead of having your employees type in all the data, you can entrust this job to PortaBilling®! The PortaBilling® rate upload wizard and templates allow you to do the following:

• Upload your XLS or CSV rate file to the server and immediately see the result of file processing (in order to verify that the file was recognized correctly, and to adjust parameters such as the field delimiter).

• Using a drag-and-drop interface, you can place markers on columns in the file to identify where particular groups of data are located in it (e.g. the destination prefix in the third column, and the price in the fifth column). In fact, the rate upload wizard will try to automatically recognize data elements, so most of the time you will only need to confirm the proposed column assignment.

• You can adjust the format which each data element is in (for example, whether the phone prefix is given as 011420 or as 420). You can also apply post-processing rules (analogous to formulas in spreadsheet editors).

• The upload wizard will process all the rate information and allow you to compare new rates with the existing rates and make adjustments if necessary.

• If there are new destination prefixes in the file (not in the database yet), they can be created automatically during rate upload. Also, you can assign new prefixes into specific destination groups during the upload process.

• Once the new rates are uploaded into the system, PortaBilling® saves all of your changes as a template associated with this tariff. Thus, the next time you receive a new file from the vendor and need to upload it, everything is ready and no special actions are required.

Template engine The template engine allows you to define and use data conversion rules (templates) during the rate upload process. There are two methods of template-based data processing and, accordingly, two types of templates.

Template concepts


9

Import data into PortaBilling (upload)

Such a template (called an upload template) is defined via a user-friendly rate upload wizard during the first upload of rates from a tariff with a specific format. The Rate upload wizard provides:

• Rate upload with visual results review at each successive step • Rate change analysis • Automatic creation of new destinations • Prefix assignment to destination groups • Rate update notifications • Definition of changes to apply to the data before entering it into

the database • Saving all of the steps performed as a template associated with this

tariff that can be used later on during subsequent rate uploads When rate data is being uploaded into a tariff, the template engine parses the input file according to its type, locates the data inside the file, converts it into an internal representation according to the specification predefined during the first upload, applies post-processing rules and then writes the data to the database.

Export data from PortaBilling® (download)

Such a template (called a download template) defines:

Template concepts


10

• The output data format. • How the data is to be processed before being downloaded into the

file. • How the data should be arranged in the output file.

When data processing takes place, the template engine extracts data from the database, converts it into the specified format, applies post-processing rules, and then creates a file of the specified type, entering the data in the appropriate places in the file.

Template components Data for an invoice or a tariff may have a very complex structure. In order to facilitate such cases, data within the template is split into different groups, called “template components,” so that it can be managed separately. Look at the sample invoice in the picture below:

We can clearly identify a few independent groups of data here:

1. Invoice header – This is only present one time in the file, and contains global information.

2. Invoice line(s) – Groups of data which repeat multiple times in the file, each time with different values.

3. Invoice footer – This is only present one time in the file, and contains global information.

Here is another example, this time for a rate download template:

Template concepts


11

Here we see a single group, Rate data. This is a data group that repeats within the file multiple times though with different values. Thus there are five possible template components:

Header

A header contains data fields with global data for the object. On an invoice, this would be the invoice number or the name of the company issuing the invoice.

Page Header This template component is available only for printable forms in which data is split across several pages. Data fields defined in this component are placed at the top of each printed page.

Template concepts


12

NOTE: This component may not be available in invoice templates of the Totals only type.

Similar to the Header, this component contains global data for an invoice. Data fields are split between the Header and Fields simply for convenience, with the Header containing the main parameters, while auxiliary parameters are included in Fields. For instance, Fields invoice templates contain such data as the period from date, the period to date and the due date.

NOTE: Header and Fields components for rate download templates are obsolete.

Columns (repeating groups)

This is the most important component, since it describes the variable portion of the data. For example, rate entries all have the same structure and format (phone prefix in the first column, country name in the second, price in the third, etc.). However, there are many such rows in the file, and each row is an independent object. Thus, you define how one single row of data is to be formatted and this is then applied to all rows in the file.

Footer

Contains additional data about the object; for example, invoice totals.

Page Footer Available only for printable forms; data fields to be placed at the end of each printed page.

Groups

See the Template groups section.

Template concepts


13

Template parameters

Template type

The template type defines the intended use of the template: • Whether it is used to generate invoices (based on a standard or a

custom invoice template) or to export data from PortaBilling®. • What kind of data is involved (invoice data or tariff data, etc.).

Template media

This defines the file format to be processed, for example .csv (Comma-Separated Values), .xls (Microsoft Excel), or a printable form (a specific HTML, which might be converted into a .pdf file).

Template time zone

Normally, when people specify a point in time, they name the day of the week, the month, the year, the hour and the minute, and, optionally, even the seconds as well. However, in order to be absolutely precise, this definition must also include the time zone. Let’s assume that your vendor sends you a data file that contains his new rates and for each rate, the date on which it becomes effective. This is fine; but is 01-May-2019 00:00 in the Pacific Standard time zone, or in the Central European one? Obviously, time zone misinterpretation can render the rest of the data invalid. In most cases, specific time zones are not included in the date itself, but are instead defined externally. For example, your vendor might tell you that all of the given times are in Eastern Standard Time. Or, there might be a note in the file that says this. In any case, the template engine needs to know which time zone is to be used. This is specified in the Template time zone parameter. If the parameter is set to “Auto,” it means that the time zone of the user who performs the upload is used. This is convenient when you work with your own tariffs, but is not usually acceptable when you upload tariffs from vendors.

NOTE: If the date includes a time zone (for example, 2019-04-10 12:00:00 Australia/Sydney,) the time zone takes precedence over the template’s time zone. However, make sure that the time zone specified is both supported and unambiguous. For example, EST could mean Eastern Standard Time in both the US (GMT -5) and Australia (GMT +10) – quite a big difference!

Template concepts


14

Media parameters

Media parameters define the data layout within the file, (e.g. which separator is used in .csv files) where the data for individual components must be located in the file, and whether they are present at all.

You can manage media attributes for rate download templates in the .csv file format. The following options are available:

• CSV delimiter is a character used to separate independent data in a file. The default delimiter is a comma; you can select another delimiter from the list or define your own delimiter as the Other field value.

• CSV text qualifier is a wrapper used to identify the field within the file. The default text qualifier is double quotes. You can select another available text qualifier from the list or define your own in the Other field.

Here is an example of the output file that matches this template.

The file structure for .xls files is fixed and not editable.

Template concepts


15

Template data fields Data fields describe a single element of data, such as “invoice number”, “price” or “company name”. For each data field in the template you specify the following:

Target columns (for download templates)

Target columns define where to position the result value. If you want to skip the downloading of specific data, choose None for this data field. To change the target column, click the Edit icon and select the new column value in the Column list. Multiple data fields can be populated from the same target column.

NOTE: This option is available for rate download templates. To specify where you would like the value to appear in download templates with printable form media such as invoices, use Layout Designer.

Format

A format describes data fields so that they may be converted from the database (default) format to a specific format during download. For example, if you choose format “011E.164” for the “Destination” data field, then the template engine will know that you require the downloaded numbers to be in a US dialing format, so the international number must be prefixed by “011.” Therefore, “011” will be prefixed to the number “4201234567” during the download, so the number in the output file will be “0114201234567.” In order to provide better quality control of data, PortaBilling® supports several data types. These define what kind of data appears in the data

Template concepts


16

field, as well as possible ways to process it. Currently supported data types include:

• Destination (phone number). • Date/time • Number • Time interval (number of minutes/seconds) • Text • Boolean (yes/no)

A data type is predefined for each data field, so you do not need to specify one. For each data type in PortaBilling® there is a set of default formats, so that you will usually not have to invent anything from scratch. If you encounter a data format for which there is no suitable data type in PortaBilling®, you may choose “Other”. You will then be able to specify a custom format rule.

“Other” format rule

If none of the PortaBilling® default formats suit your needs, you can choose “Other” and enter your own formatting rule. See below for a description of how a format rule works for data fields of a particular type.

Number

For numeric data fields (for example, “First price” or “Connect fee”), the value you enter in the Other Format field is considered to be the format specification ###,###.##, where:

• A # sign or the digits 0-9 represent one digit of the input or output number.

• The first character from the right which is not a digit or # (e.g. . in #,###.00) specifies a decimal separator.

• The first character from the left which is not a digit or # (e.g. , in #,###.00) specifies a group separator.

• The number of characters after the decimal separator specifies the precision of the number. However, # indicates no zero padding, and 0 indicates zero padding.

• If the number has too many digits for the format specification, it will be rounded to the number of decimal digits specified in the format.

• A group separator (if present) specifies which character should be used to split groups of 3 digits in the number. If none is specified, then no group separation will be done.

• It is sufficient to specify a group separator only once, even if your real numbers will be large and contain more than one digit group. All digits to the left of the decimal point are always shown, regardless of how many of them are actually shown in the format.

Template concepts


17

This is important mainly for download templates, where the format or precision you use to present numbers in documents differs from the format in which data is stored in the database. For upload templates, number format specification is mainly used to handle non-standard group or decimal separators. See the table below for examples of formats for converting numbers. Format Number Result Comment #,###.## 1.6 1.6 No zero padding #,###.00 1.6 1.60 Zero padding #,###.00 34567.6 34,567.60 Digit groups ####.00 34567.6 34567.60 No digit groups #.# 2.382 2.4 Rounding #.# 2569.31 2569.3 Significant part is

never truncated #.###,## 2569.31 2.569,31 German format # ###,## 7892569.31 7 892 569,31 Yet another

custom format Table 1-1 – Examples of number formats.

Date and Time

This type is used for data fields that contain either both the date and time (e.g. Effective from) or just the date (e.g. Invoice date). Each data field has a default format. For instance, for Period From Date on the Field tab of the invoice template it is YYYY-MM-DD. This means that end users see dates in this format: 2015-08-23. All of the date and time format specifiers are listed below:

• YYYY – Year (four digits, e.g. 2009). • YY – Year (short format, e.g. 05). Note that this format can lead

to potential data interpretation problems, since “10” could be either 2010 or 1910. The PortaBilling® template engine considers the year values 00-30 to be in the 21st century, and 31-99 to be in the 20th century.

• MM – Number of the month (01…12). • MON – Abbreviated name of the month (e.g. Jan). Only English

names of the months are currently supported. • MONTH – Full name of the month (e.g. January). Only English

names of the months are currently supported. • DD – Day of the month with a leading zero for 1 through 9; for

example, 01, 06, 14, 25. • D – Day of the month without a leading zero for 1 through 9; for

example, 1, 6, 14, 25. • HH or HH24 – Hour (24-hour format). • HH12 – Hour (12-hour format).

Template concepts


18

• AM/PM – a.m. or p.m. indicator. • MI – Minutes.

NOTE: Very often people make the mistake of using MM as a format for minutes. This is incorrect, as MM is a format for month. Thus, HH:MM:SS will clearly not work correctly.

• SS – Seconds. • TZ – Time zone name (e.g. CET). • XXX – Any combination of non-space characters; used in formats

for parsing dates to skip a variable part of the date, for example, the name of a weekday (see examples below in Table 1-2).

• All other symbols in the format (spaces, delimiters like /, -, : or ; and other characters) represent themselves. So they are placed as-is in the output date string, and must be found in the input string exactly as they were entered.

PortaBilling® administrators can customize date and time formats according to their needs and we show you how to do it for different template types.

Rate upload and download templates Specify your customized date and time format for the required data field within the Other Format Rule field. Click Save to apply the changes:

Let’s take a look at some examples for importing dates into:

Date / time string Description Correct format specification

07/04/2009 July 4th 2009, US date format

MM/DD/YYYY

04-07-2009 July 4th 2009, European date format

DD-MM-YYYY

Template concepts


19

07-04-09 July 4th 2009, US date format, short year format

MM-DD-YY

11:05 a.m. Time, 12-hour format HH12:MI AM/PM 11:05 Time, 24-hour format HH:MI 18:58:00 Time with seconds HH:MI:SS 2009-07-04 14:00:00 Date and time, ISO

format YYYY-MM-DD HH:MI:SS

07/04/09 2:00:00 p.m.

Date and time, US format

MM/DD/YY HH12:MI:SS AM/PM

1-May-2009 18:52 Date and time, abbreviated month name

D-MON-YYYY HH:MI

Sun, 16 Mar 09 Date and time, skip weekday name

XXX D MON YY

12th of March, 2009 Date with “as is” elements

Dth of MONTH, YYYY

Table 1-2 – Examples of date and time formats for upload.

The following table gives examples for using templates to convert values in the PortaBilling® database to the desired format.

Date / time in Format specification

Resulting value

01-May-2014 12:34:56 MM/DD/YYYY 05/01/2014 01-May-2014 12:34:56 DD-MM-YYYY 01-05-2014 01-May-2014 12:34:56 MM-DD-YY 05-01-14 01-May-2014 12:34:56 HH12:MI AM/PM 12:34 p.m. 01-May-2014 12:34:56 HH:MI 12:34 01-May-2014 12:34:56 HH:MI:SS 12:34:56 01-May-2014 12:34:56 YYYY-MM-DD

HH:MI:SS 2014-05-01 12:34:56

01-May-2014 12:34:56 MM/DD/YY HH12:MI:SS AM/PM

05/01/14 12:34:56 p.m.

01-May-2014 12:34:56 D-MON-YY 1-May-14 01-May-2014 12:34:56 D of MONTH,

YYYY 1 of May, 2014

01-May-2014 12:34:56 YYYYMMDD HHMISS

20140501 123456

Table 1-3 – Examples of date and time formats for download.

Template concepts


20

Invoice template To apply your customized date and time format for the invoice template, insert this code into the Other Format Rule field of the required data field:

Porta::Date->new_iso($value)->asCustomFormat('DD-MM-YYYY')

where 'DD-MM-YYYY' is an example of date format.

Parsing module Please note that when importing data that has dates in a customized format (e.g. rate upload), you can use the Time::ParseDate module to recognize the date format. This module examines a data string and finds bits of data, regardless of how they are placed or separated there. In order to use the Time::ParseDate module for parsing dates, choose “Auto” as the format. Unfortunately, in some situations even Time::ParseDate is unable to properly identify the date. For example, the string “02-01-2009” could either mean February 1st or January 2nd. In such situations, an exact format specification is required.

Other data types

For other data types (e.g. Destination, Text or Interval) there are no specific format elements. The “Other” format rule is regarded as a Perl macro; thus it is evaluated, and the result of the evaluation is considered a new value. For a detailed description of Perl macros, see the Post-processing rules section below. The original string value is received as a parameter, and the converted value should be returned in the required format.

Template concepts


21

The following table provides a description of which type of output value is required for other format rules, depending on the data field type.

Data field type Other format rule in Output value Destination Perl code string Number Number format N/A Boolean Perl code string (‘Y’ or ‘N’) Interval Perl code number DateTime Date/time format N/A Text Perl code string

Table 1-4 – Output value type for other format rules.

Post-processing rules

Sometimes you will need to perform a very specific conversion which is not possible using the standard PortaBilling® formats. In this case, you can use post-processing rules. A post-processing rule is a piece of Perl code which is executed at run-time, and the value it returns becomes the final value for a field. This is similar to formulas or macros in Excel, giving you a virtually unlimited ability to change your data as you need to. There are a few requirements for writing post-processing rules:

• A processing rule is Perl code, i.e. one or more Perl operations separated by semicolons.

• The input value (to be processed) is in the $value variable. • The final result is the value returned by the last expression in the

list. TIP: One of the most useful things post-processing rules can do is to create new data which is not based on the input data. This is required, for example, when certain data fields (e.g. Interval 1 and Interval N) are absent from the input file. If you know that Interval 1 is 30 seconds, and Interval N is 6 seconds, you can simply assign these values as constants in the post-processing rule. Let’s look at a few examples:

Post-processing rule Input data Result

Remove all leading white space from the string $value =~ s/^\s+//;$value Aruba Aruba

Remove all leading and trailing white space from the string $value =~ s/^\s+//; $value =~ s/\s+$//;$value

Aruba Aruba

Add 1 before the phone number, but only if it does not start with 0

Template concepts


22

$value =~ m/^0/ ? $value : '1'.$value;

6041234567 16041234567

Take only the part of the input string following the hyphen my @a = split('-', $value, 2); $a[-1];

Norway-Oslo Oslo

Assign a constant value to the field $value = 30 None 30

30 None 30

Replace all hyphens with spaces and remove all quotes $value =~ s/-/ /g; $value =~ s/\”//; $value

Germany-'Berlin' Germany Berlin

Use an external (custom) module to translate English country names into Czech use Czech::Translate; transl_data($value);

Austria Rakousko

Table 1–5 – Examples of using post-processing rules.

NOTE: This manual does not cover details of programming in Perl. There are excellent books on this subject, for example:

• Programming Perl by Larry Wall, Tom Christiansen, Jon Orwant(ISBN 0-596-00027-8)

• Learning Perl by Randal L. Schwartz, Tom Phoenix (ISBN 0-596-00132-0)• Perl Cookbook by Tom Christiansen, Nathan Torkington (ISBN 1-56592-243-3)

Values returned by a post-processing rule should have the same type as the input value it receives. The following table provides information about types of input values for post-processing rules, depending on the data field type.

Data field type Input value ($_) Destination String Number number Boolean string (‘Y’ or ‘N’) Interval number DateTime unixtime Text string

Table 1–6 – Input value type for post-processing rules.

Template groups

Concepts

Template groups are necessary for performing / sorting subtotals on large sets of data. For example, you might need to make a list of all phone calls and include a subtotal for each country.

http://www.oreillynet.com/cs/catalog/view/au/148




Template concepts


23

Group

Each group is a portion of data that has an identical value for some parameter or parameters. All of the input data is sorted according to groups, and rows within the same group are presented together. In the example above, three groups are visible and each of them contains all calls made to some country.

Groups can also be nested. For example, the group “Country” contains several sub-groups named “Destination.” These are sorted according to their order in the list of groups so that the outermost group is on top, and the innermost at the bottom.

Template concepts


24

Custom expression

This is a parameter that defines which group the data belongs to. All of the available data are sorted according to this field. In the example above, the list of all calls is sorted by the name of the destination country (so calls made to Slovenia appear before calls made to Ukraine). Next, rows that have the same custom expression value are grouped together in the same group, as seen in the example above for all calls made to Slovenia, Ukraine or the US.

Normally, the custom expression value is predefined for the selected group (in the example above, this is the “Country” column). If you create your own groups, you can define a custom expression, specifying any valid SQL expression.

Group header

This is a template component that is inserted into the document immediately before the group data. Besides static text, variable fields (e.g. “Destination”) can also be used. In the example above, this is the row containing the name of the country.

Group footer

Similar to the group header, this element is placed immediately after the last row of the group. It can consist of static text and variable fields. In the example above, this is the row containing “TOTAL by” and the name of the country, as well as the total number of seconds and the amount for the country.

Group fields

These variable elements are very similar to data fields in the Columns section of a template (and are actually based on them). You can alter their parameters (such as format or post-processing rules) in exactly the same way as you would for standard elements of the Columns section.

Group totals

Since one group may consist of many rows of data, what would be the value in the group fields for the header / footer? The fields in the group header have the value of the first row in the group. You can specify how you would like to populate the value of fields in the group footer. Click

You can create your own custom groups (e.g. to group calls made from home country and from other countries). To configure custom group sorting, define the custom expression for the group break value. See details below.

Template concepts


25

the Edit icon next to the column and select one of the possible pre-defined options:

• Summary (sum of values for the corresponding column across allrows)

• Count (number of rows in the group)• Last value (value of this column in the last row)

You can always write your own custom total rules. These are very similar to post-processing rules, in that you can specify any Perl expression. The current value of the column is given in the $value variable, the current value of the total is given in the $total variable, and the result returned by the expression becomes the new total.

In the example below you see what a list of calls looks like if you use two groups:

1. Break group by country (so that each group contains all calls madeto the same country).

2. Break group by destination. This group exists within the firstgroup, so it contains all calls made to a specific destination withina certain country.

Things to remember

XDR number limitation in the invoice

In order to avoid high resource consumption while generating vast invoices, the number of rows in the invoice is limited to 1000 by default, but it can be changed via the Configuration server.

Template concepts


26

Custom data

Sometimes service providers must supply customers with additional information (for example, tax code, contract number, etc.) on the invoices. In PortaBilling®, additional information can be filled in on the Custom data panel when you add a new customer or edit an existing one. Later this information can be added in the Layout Designer of the invoice template.

If you need to add extra fields to the invoice perform the following steps: • Add necessary custom fields on the Web Interface page. • Ensure that all required information is specified on the Custom

fields panel for the customers who require additional information on their invoices.

• Open the invoice template where you would like to add custom fields.

• Launch Layout Designer. • Right-click on the layout designer sheet and select the desired

custom field from the available list in the Header section.

NOTE: There are up to 10 custom fields available for adding to the invoice template and all custom fields are sorted by the order of their addition to the Custom data panel.

The Hide column info option

You can configure the invoice template to show only the totals per each service such as total payments, total credits and total call duration and cost to specific countries. In the figure below you can see an invoice example with the Hide column info option disabled.

Template concepts


27

In the figure below you can see an invoice example with the Hide column info option enabled.

Destination upload

Why can’t I use custom templates for destination upload/download?

There is only one format available for uploading destinations at the moment, since:

• The format is fairly simple. • You almost never need to upload new destinations alone;

normally, you will need to input new rates in the system which requires the new destinations, and in this case the PortaBilling® template processor will add new destinations automatically.

Template concepts


28

However, functionality for creating custom templates for destination upload or download is available, and may be included in future releases.

How to fill in country information for a destination

For each destination entered into PortaBilling®, it is necessary to provide information on which country (and, optionally, administrative subdivision in that country) the destination belongs to. This will help you keep better track of rates for a specific country, and will also be used to ensure a correct description in call details and statistics for you and your customers. PortaBilling® comes with a complete list of countries registered with the International Standards Organization, providing each country’s ISO code (e.g. US for United States of America, CA for the Canada, and so on). When a new destination is manually entered using the PortaBilling® web interface, you can choose the country from a list. When importing many new destinations at once, country information must be provided for each in the form of the two-letter ISO code. Why not the country name? Unfortunately, country names can be very ambiguous. For example, UK, United Kingdom, Great Britain, Britain and England are all synonyms for the same country (which could also could be called The United Kingdom of Great Britain and Northern Ireland), and you never know which version of the name your vendor will decide to use. Moreover, country names in local languages (e.g. Velka Britanie in Czech), spelling errors (e.g. Untied Kigndom), punctuation marks, and the like further complicate the matter. This is why PortaBilling® uses country codes instead, since they define exactly which country is meant. Does this mean that you now have to fill in country codes for several hundred missing destinations manually? No, there is a better way! TIP: When uploading destinations with empty country codes, PortaBilling® will try to find country information based on data which is already in the database. For example, if the prefix 61 already exists in the database, and is assigned to Australia, then when you upload a new destination with prefix 61881 PortaBilling® will automatically fill in the country information for you.

NOTE: Of course, in order for this method to work effectively you need to have an initial set of destinations in the database already. PortaBilling® comes with a default set of almost 3,000 destinations, which covers most of the countries of the world and popular destinations in those countries. You can download it using the Get default set button in the Destinations screen, customize it according to your needs, and then upload it.

Rate upload/download


29

2. Rate upload/download



30

Upload via the rate upload wizard PortaBilling® offers the ability to program data processing rules (called templates) for each type of rate file you receive, so that you can eliminate the need for any manual data conversion and save yourself a lot of time. Also, the rate upload process is interactive and provides a comparison between new rates and existing ones, so that you can review the rates being uploaded for validity and accuracy.

Let’s have a look at how a rate import is performed. We will perform the rate upload for the “X-Telecom” termination tariff, proceeding step by step. You can then use this as a model for uploading any other tariffs.

NOTE: In PortaBilling®, the proper name for the initial portion of the phone number (used to determine which location or type of phone network this number belongs to) is destination (e.g. 44 for the United Kingdom and 442 for London, United Kingdom). In the VoIP business the same entity is frequently called prefix – so we will use these terms interchangeably.

If you experience network connection issues, we recommend that you change the load balancing among the web servers to ensure seamless rate upload. To do this, open the Configuration server > web cluster > HAProxy group > hash_type option > set the consistent method.

Start the import

1. On the Tariff list panel, click on the tariff name. 2. On the Edit tariff panel, click Rate upload, and then select a file to

upload.



31

Let’s now discuss the available options and their effect.

Add or replace rates

This radio button controls behavior in respect to rates which were already defined in the tariff at the time of import. The default is to add new rates into the tariff. So when the new rates appear, and there is an existing rate for a certain prefix, the new rate will simply override the old one. If a rate for a certain prefix is in the tariff but is not given in the file you received from the carrier, it will stay unchanged. This mode is frequently used, since most of the time your partners will send you rate updates only, i.e. the file will contain only a small subset of prefixes for which the price has changed. In some cases, however, you need to ensure following import that the tariff structure matches the provided file exactly, so that there are no “old” rates remaining. This is normally done when your carrier changes the structure of the prefixes and sends you a “replacement” rate update. In this case, you will want to use replace mode, which uploads all the new rates and then marks rates for all prefixes not present in the uploaded file as discontinued. The replace mode operates as follows:



32

• It adds all the rates having new destinations from the uploaded file.

• If a rate for a certain destination is present in the tariff and the uploaded file and its Effective From date is past, the rate is discontinued.

• If a rate for a certain destination is present in the tariff and the uploaded file and its Effective From date is in the future, the tariff rate is replaced with the rate from the file. The Effective From date is then updated in accordance with the new rate.

• If a rate for a certain destination is present in the tariff but not in the uploaded file, the rate is discontinued.

NOTE: To prevent a situation where some rates would be discontinued erroneously because a new rate was not uploaded due to a data error (e.g. a typo in the price column), discontinuation of rates will take place only if there were no errors in uploading the new rates.

In our example, we assume that a normal, “incremental” rate import is being used; thus, we will be adding rates.

Effective from

PortaBilling® allows each rate to be assigned an “effective from” date, so that an automated rate change can be easily scheduled for the future. Thus if your carrier sends you a file which indicates the date when a specific rate becomes effective, this can be extracted from the file and added to the rate information in PortaBilling®. Sometimes it may happen, though, that you receive the file later than expected, when the moment at which the rate was supposed to become effective has already passed. In order to protect data integrity, it is impossible to upload the rate and assign an “effective from” date in the past, since xDRs for calls previously made will have already been rated according to the old rate and stored in the database (see the xDR rerating topic for more information about how this situation can be resolved). Consequently, you have the choice to either skip these rates or upload them as effective immediately. This can be adjusted by using the Rates with ‘effective from’ date from the past should be uploaded as effective immediately check box.

Skip duplicate rates

Sometimes carriers will include all prefixes in a rate update file, even if for some of them no change in pricing has occurred. If you upload the whole rate file, it will create duplicate rate rows. This has no effect on the way calls are billed, but it will increase the amount of entries in the rate table and, in the long run (if it occurs continually), have a negative effect on performance.



33

In order to prevent this, simply activate the option to skip duplicate rates. This will slightly increase the time it takes to upload the whole rate file (since PortaBilling® will have to check the already existing rates and compare them with the new ones). If rate parameters such as price, preference, and so on turn out to be identical, no extra (excess) rate will be inserted. We use this mode in our example (and certainly recommend using it whenever possible). Finally, choose the rate file and click Next. The file is uploaded to the server, and we move on to the next step.

Review file parsing

The purpose of this screen is to verify that the general structure of the file has been determined correctly, so that the data can be properly extracted. There are different ways to organize data files: for instance, CSV files, despite their name (comma-separated values) can use semi-colons or other characters as a separator. PortaBilling® attempts to make a best guess, but it is important to review the results and, if necessary, change the settings according to your preference.

Multiple prefixes in the same cell

Typically one row in the table contains the rate information for a single phone prefix (destination) such as 447 or 447527. Sometimes you may receive a file from the vendor where multiple prefixes are placed in the same table cell as shown in the screenshot below.



34

You can easily process such files – you just need to specify which character (e.g., comma (,), semicolon (;) or something else) will be used to separate the individual prefixes in the Delimiter For Multiple Destinations field. This way, during the upload, the system will treat each occurrence as if there is a separate row in the table for each prefix.

In our case, it looks as if the file was parsed properly, so we can click Next and move on to the next step

Review data fields definition

This is a very important step, since we need to identify where individual data elements (e.g. destination prefix or price) are located in the file, and map them to the attributes (data fields) for the rate. You can imagine what would happen if the system were to confuse them. PortaBilling® applies some artificial intelligence, and usually guesses quite well, where the specific columns are; but, obviously, you need to check whether the data fields have been assigned to the proper columns, and adjust them if necessary.



35

On the right-hand pane you see the Available Fields select menu, which represents all the attributes of the rate record. You can drag and drop fields from here to the table headers in order to associate a particular data field with a column. A blue label will then remain at the top of the column, signaling that the values in this column (e.g. column A) will be used for the specified rate data field (e.g. Destination). Also, the data field in the list will be highlighted – this allows you to quickly see which data fields are already assigned. You can also drag a label to a different column (thus associating the data field with a different column) or back to the Available Fields menu (the data field will then not receive any input values from the file). The Format select menu allows you to adjust the way PortaBilling® interprets the values in the table cells, e.g. whether a leading 00 should be stripped off or considered part of the phone prefix, or whether a comma (,) or a dot (.) should be considered as a decimal separator for numbers. Finally, you have the post-processing rule. Here you can write a mini-program in Perl which will alter the original value, e.g. append or remove characters, increase or decrease numeric values. It can also perform advanced operations, e.g. look up the current exchange rate for the vendor’s currency and convert the value into the currency you use.

What if the file does not contain a value for a certain data field? This is another common situation: the carrier may not have included some important information (e.g. rounding intervals) in the file, or it could be that you simply need to assign the value based on your own decision (e.g. when uploading rates from carrier ABC, you will mark them as the Cheap route category). In this case, you may leave the data field



36

unassigned to any column in the file, and simply type a value in the Default Value field.

What if you need to associate a single column with more than one data field? For instance, the carrier only supports a single “rounding interval” rating parameter, and so they provide a single column only (column D, in our example). In PortaBilling®, however, you have First Interval and Next Interval. In this case, you will associate one data field with the column, and then click on the other data field and link it to the first one (select the first field name in the Link With menu).



37

What if you want to “preserve” some of the already assigned rate attributes? Quite often you will initially upload all the rates from a given carrier with a default preference (e.g. 5) or route category (e.g. Default). After that, you start to fine-tune your routing based on quality reports, testing, customer feedback, and so on. Let’s assume that, in this particular vendor’s tariff, the preference for prefix 44 was changed to 8 (to reflect the fact that this is our preferred vendor for this destination) and the preference for prefix 447 was changed to 3 (here we actually decided to move the vendor to the bottom of the routing list for this particular destination). Now, if we were to simply upload the rate file, it would assign the default value (5) for preference to all the new rates, and our subsequent routing adjustments will be lost. To prevent this, you may specify that the default value should only be applied if there are no existing rates for this prefix in the tariff.



38

Thus, the parameter value from the existing rate will be copied into the new one, so that the new rate for 44 will retain preference 8, and the rate for 447 – preference 3. Tip: In PortaBilling® you configure the rate information using two parameters: the price for the first interval (First Price) and the price for subsequent intervals (Next Price). Most of the wholesale carriers do the rating using only one parameter: price per minute. So when importing such a file into PortaBilling® you would need to assign the First Price data field to the column that contains the price and then link the Next Price to it. Since it is a very common operation, for your convenience the rate import wizard contains a special data field: Price. If this “virtual” data field is assigned to a column, then the value found there will be used for both First Price and Next Price rate parameters.

Ready to move forward?

In order to proceed, you must assign the Destination and Price data fields to columns in the file. The Destination Description field is not required for the actual rate import, but it will be very useful later on if there are any new destinations created. Tip: In order for the destination description to be automatically filled in it is needed to create a “Destination Description” column and fill in some descriptive information in the file before the upload procedure.

Click Next to proceed.



39

Review rate information

The rate import wizard will process the rate data according to the rules previously specified and present the results on the screen for review before storing them in the database.

The Status column shows the comparison between the current rate and the new rate in the PortaBilling® file so you can quickly understand exactly how the rate will change. A red arrow indicates a price increase (this destination is more expensive) and a green arrow indicates a price decrease (making it cheaper to call that destination). The Off-Peak Period column shows the off-peak period defined for the rate via the tariff configuration. You can change the off-peak period for a particular rate by selecting a previously defined off-peak period from the list. In the Price field you can see the actual price differences for updated rates. Also, you can double-click on a specific cell in the table and enter a new price value. The duplicate rates (i.e. the rates that have exactly the same parameters as already existing ones in the database) are highlighted as inactive and therefore appear grey. If you do wish to add an inactive rate, it is necessary to manually activate it. Click on the icon at the end of the row to activate the rate. When activated, the rate color will change to black.



40

NOTE: You can edit active rates only.

You can also change the values for the Payback Rate, Forbidden, Hidden, or Discontinued fields:

• Payback Rate – This means that the customer is credited for using certain services, rather than paying for them (e.g. the service provider receives the termination fee for his own subscribers and wants to encourage his users to receive more calls by passing on a certain portion of these savings).

• Hidden – This means that the rate is excessive (e.g. there are usually more than 500 rates for Argentina mobile because of different prefixes). This flag does not affect usage of the rate by the billing engine. It simply indicates that this rate may be omitted when making a list of rates for the end user.

• Discontinued – This means that the rate will stop being active immediately or from the specified time-stamped date. To deactivate the rate in the future, specify a certain date and time in the Effective From field.

• Forbidden – This means that no calls are authorized for this particular destination.

and / or select another route category for a particular rate from the list. As you can see in the screenshot, for the 355 destination, the value of the Preference parameter of this rate is 3 (while most other rates have a preference of 5) – this is because there is an existing rate for this destination, and it is already assigned preference 3. Click Next in order to proceed.



41

Managing new prefixes

This screen only appears if the rate file contains any prefixes you haven’t yet defined in your system and it allows you to add new prefixes quickly and efficiently. This process takes a very little time and reduces the chances for error.

Carriers frequently send rate files containing prefixes that have not yet been defined in your system. These prefixes must be added into the system in order for rates to be created for them – so the big questions are: ‘how will this affect the routing and billing on your system in general?’ and ‘how will other carriers and customers be affected?’ When adding a new destination, extra parameters may be provided in addition to the actual prefix - see below.

Assigning the country

Each destination is associated with a country. For a new destination the association has to be made before it can be inserted into the database. It is a good idea to upload the default set of destinations provided with PortaBilling®, or some other set that contains, at the least, destinations for each country, e.g. United Kingdom – 44, Germany – 49, etc. Then PortaBilling® can correctly assign the country name to the majority of new prefixes. Thus you do not need to choose the country for each destination manually (e.g. if you try to upload a destination 33040, but there is already a more generic one 33 in the system and the country has been defined as France – the upload wizard will propose assigning the number 33040 to France as well). If required, a country for the new



42

destination may be chosen from the list on the Create New Destinations page.

NOTE: This is a required step – the rate import cannot proceed until each of the new prefixes has been assigned to a country.

Sadly, both the US & Canada pose the biggest challenges, since they (plus a handful of other countries, like Bermuda) share the prefix 1. This makes it impossible to guess the country code just by looking at the phone number. For instance, 1204 is Manitoba, Canada and 1205 is Alabama, US! In these cases you will need to manually assign country codes for these destinations. The good news is that new area codes for the US & Canada do not appear that often.

In our example we will assign the 670 destination to the country East Timor.



43

Including a destination into a destination group

Destination groups are invaluable for saving hours of time and for avoiding mistakes, since one can change the rate for a whole group with just a single click instead of modifying rates for many destinations (and many could literally mean thousands), manually. So for instance, when the new destination 4473 is being added – it may be a good idea to immediately include it into a destination group (within the destination group set that’s associated with this tariff) – UK-Mobile in this case. Then the next time someone updates the UK-Mobile rate, the change will be applied to this prefix as well. See the screenshots below for the sequence of actions.



44

In some cases it may also be beneficial to include this destination into groups that are in other destination group sets. In our example, the new destination 4473 (UK-Mobile-Vodafone) is detected while uploading rates into the tariff of carrier X-Telecom (which has the X-Telecom destination group set associated with it). You may want to immediately add it into the UK-Mobile destination group in the Retail-Customers destination group set. This way the next time your colleague is generating rates to be applied to your customers – this prefix will appear and he can apply the special pricing for it.



45



46

Multiple similar destinations

In our example you may notice that there are several destinations (55123, 55124, 55125, etc.) which look very similar. That’s because they belong to the same country (Brazil) and they are in the same destination group (Brazil-Mobile). In order to save time and avoid assigning parameters to each one of them manually, you can do the following: assign the required parameters to just one of them, select the others using the checkbox on the left side of each row and then move the mouse over to the rows that don’t have parameters assigned. A popup menu will appear – choose Apply to Selected and this will automatically change all the rows. Please see how the change is applied to several prefixes for Brazil below.



47

Tip: You can filter the list of new destinations by country or hide the destinations that have already been assigned a country or destination group. For this action, use the Select All button in conjunction with Apply To Selected to quickly apply settings to hundreds of destinations. If I add a new destination while uploading rates for carrier ABC will it affect my other carriers? Customers who are used to old-style routing systems are very concerned about adding new prefixes, since on many of those, a carrier with a longer prefixes in their tariff would all of a sudden get priority routing (although it is not the cheapest or the one with better quality). Attempts to



48

“harmonize” the prefixes (to ensure that all carriers use the same prefix set) require lots of manual labor and are Sisyphean in scope: the moment you finish changing the prefixes and things are finally looking good, one of the carriers sends you an updated prefix list and you have to start the task all over again. This is not the case with PortaBilling®, which uses a true real-time routing engine giving each carrier their own set of prefixes for the tariff. When the routing is calculated, available routes are compared based on cost, preference and route category – never on the prefix length. So if you upload the rate for 4471 for carrier A (and other carriers only have prefixes 44 and 447) – when a routing for a call to 4471234567 is computed, the 4471 rate will be compared by price and preference with the rates for 44 or 447 from other carriers (who don’t have the 4471 prefix). Consequently, the system always produces a correct routing and you don’t have to worry about adding new prefixes that are only used by a few carriers. I do not want to add a destination right now, what do I do? You can delete the destination from the list of destinations that will be automatically created during the import by using the delete button. Note that in this case, the rate for this destination will not be imported (since there is no destination to associate it with). To undo the delete destination action, click the button, respectively.

Summary

On the Summary page, you will see an overview of information about the number of rate records to be processed. You can also specify a name under which the current import settings will be saved as a template. Note that a name for a tariff upload template is automatically filled in with the tariff name. Later you can re-use them when uploading rates into this or other tariffs.

You may specify who should receive a report about the rates being uploaded, and then click Start Import to launch the rate import process. The report will contain following information:



49

• Total rates processed – The total number of rates in the imported file.

• Total rates created – The total number of rates created including the newly created rates (the rates which were not present in the tariff prior to the import) and the overwritten ones.

• Old rates overridden – Reflects the total number of rates, which were updated (i.e. the previous rates were replaced by the new ones for some destination).

• Skipped (due to errors) – The number of rates that contained errors (e.g. a typo in the price column) and therefore were not added to the tariff. The information about the occurred errors you can see in the email with the tariff upload report.

• Skipped (duplicates) – The number of skipped duplicate rates. It means that if some rates (rate parameters) in the uploaded file were identical with the ones already present in the tariff, the system skipped the duplicates i.e. no extra (excess) rate were inserted into the tariff.

• Rates for destinations, previously absent in this tariff, created – the number of rates created for destinations which were not in the tariff prior to the import.

• Destinations, previously absent in the system, created – the number of new destinations created in the system (billing environment).

In the attached file you can see the detailed information about the result of the rate upload procedure in order to quickly understand exactly how the existent rates were changed. You can also see information about new rates added if there are any. See the example of the file on the screenshot below:



50

Usage of the effective from field

You can only upload rates that are effective immediately or for the future

Since billing is done in real time, calls are billed immediately and an xDR is written to the database. In order to modify xDRs that are already in the database, a re-feed should be used. Therefore, when you are copying a rate entry between tariffs that includes the Effective from column with a date from the past, PortaBilling® adds / updates this rate entry as effective immediately (if the appropriate check box is selected, otherwise these rates are skipped). This protects the integrity of the data and ensures that updated rates will be used to charge end users for new calls only.

You can schedule the discontinuation of a rate

It is possible to schedule a rate for a certain prefix to be discontinued on a given date in the future. This simplifies the management of the vendor’s tariffs, since an announcement that a rate for a prefix is no longer available is typically received in advance. If you perform the upload immediately after receiving the updated rate sheet, the system will continue using the current rate for that prefix until the moment it actually becomes inactive (the date and time specified in the Effective from field).

When is importing tariff data not possible? Despite all the flexibility and power of the PortaBilling® template engine, sometimes it may still not be possible to directly import certain files. Let’s take a look at the most typical cases.

File format not supported by PortaBilling®

It could be that your vendor sends you data in PDF, Microsoft Word, or another format which is not currently supported by the PortaBilling® template engine. PortaBilling® currently supports:

• Comma-separated values files (CSV) • Microsoft Excel files (XLS)

So either ask your vendor to use a different format, or try to perform conversion yourself before importing the data.

No phone prefix information in the file

Unfortunately, this is a very common situation: your partner sends you a list of rates, but only includes the country or location name, as in the example below.



51

1. Go to Destination Group Sets and create a new destination group set to be assigned to this tariff.

2. Within the set, create destination groups. On the Create destination group panel, fill in the name of the destination group



52

that will coincide with the name of the destination (the country or location name) in the tariff and specify the prefixes for this destination group. Create a destination group for every name provided in the tariff.

3. When creating a new tariff, select the already created destination group set in the Destination Group Set field and click Save.



53

4. Click Upload and select the document that contains rates. You can see an example of rates below.

5. Click Next to proceed with a review of file parsing.



54

6. Click Next to review the data field definition. When you locate the “Destination” column A, select it and drag it back to the Available Fields list and assign the “Destination Group” instead.



55

7. Click Next to view the rate information. Make sure the rates coincide with the predefined destination groups and click Next.



56

How to ...

…upload tariff rates with country code and area codes in separate columns?

Sometimes vendors may send you tariffs in a format with country codes and area codes in separate columns. To upload rates in this format, there is no need to edit manually .xls files in order to merge these two columns into one beforehand. You can upload rates with country code and area codes that are in separate columns. During the upload, the value of the Country Prefix column will join each destination value of the Destination column. For area codes you can use comma-separated values or the values separated by dashes (see an example below). The .xls file in this case should look like the following:

During upload on the Review Data Fields Definition page, assign the Country Prefix data field to the column with country codes and the Destination data field to the column containing area codes.



57

The result of performing the above-mentioned actions should look like the following:

…upload US inter- / intrastate rates?

You may also specify whether the destination pertains to this category before the rate upload. Simply specify “_USInterIntraState_” in the Off-peak Period field. For interstate rates specify the price in the First Price and Next Price fields; for intrastate – in the Second Off-peak First Price and Second Off-peak Next Price fields. During the upload, the system will automatically recognize the destinations marked as inter / intra state and appropriate rates will be applied.

After successfully configuring the inter / intra state rates for calls between different states the interstate price will be used. For calls within the state, the intrastate price will be used.

… upload within / outside EEA rates?

To upload rates for calls within / outside the European Economic Area (EEA) the ZoneRating module is used. Specify “_ZoneRating_” value in the Off-peak Period field in your .csv file. For Outside EEA rates specify the price in the First Price and Next Price fields; for Within EEA – in the Second Off-peak First Price and Second Off-peak Next Price fields. Note that you can use separate rates for calls within / outside EEA only for peak periods. Peak / off-peak pricing is not supported.



58

After the rates for calls within / outside the EEA are uploaded and configured, PortaBilling® checks whether the CLI belongs to any of the EEA countries for each call to a European destination. If the CLI belongs to the EEA countries – the price for calls within EEA is used. If the CLI does not belong to any of the EEA countries, the price for calls outside EEA is used.

… upload tariff rates in E.212 format?

Typically your SMS providers send you rates for destinations defined in the E.212 format. This is a format used in mobile networks and it defines destinations as combinations of mobile country codes (MCC) and mobile network codes (MNC). PortaBilling® can upload rates in the E.212 format as easily and effectively as it does with the E.164 rates. The upload procedure is very similar. The only difference is that the rate upload in E.212 is based on MCC, MNC and Unit Price data parameters. Therefore, verify that PortaBilling® assigns MCC, MNC and Unit Price column headers to the appropriate columns and adjust them if necessary.



59

Make changes to MCC, MNC or Unit Price:

The result of the rate upload will look like the following:



60

Rate download You can download tariff rates using the rate download template. Upon download, you can change the rate details in the file (e.g. change the prices for all US destinations) and upload those modified rates to the tariff by using the Rate upload function. When creating a rate download template, you can define the output file format and select which data fields to receive in the output file.

You can set the created template as the default for a specific tariff in the Web download template field.

To download the rates, click Rate download on the edit tariff panel. The output file configuration will be taken from the assigned template. You can change it by selecting another template or a different file format.



61

Rate download using a specific template allows you to save time and improve tariff management.

Invoicing


62

3. Invoicing

Invoicing


63

How does invoicing work in PortaBilling®? PortaBilling® provides a ready-to-use invoice function. You can design how your invoices will look. Internal invoices are created automatically based on calls the customer has made. To generate and store invoices as .pdf files, the administrator must enable this functionality. The invoices can be automatically emailed to the customer (if this option is enabled and the customer has an email address set up in his properties). The invoices can be viewed online or printed via the administrator and customer self-care web interfaces.

Who is invoiced?

Only customers (both resellers and retail customers) are invoiced, since only they have all the information required for invoicing, such as address, taxpayer ID, and so forth. Individual accounts are not invoiced.

How often?

Each customer has his own billing period, which could be: • Daily • Weekly • Semimonthly • Monthly (anniversary or on the first day of every month) • 30 calendar days.

When the current billing period is over (for example, on the first day of the month) a summary of all the calls made by the customer is calculated. Customer call statistics are generated and stored on the server (optionally, they can also be mailed to the customer automatically) and an invoice is created. Note that the billing period is based on the customer’s time zone. For example, if the customer has a weekly billing period and his time zone is Australia/Melbourne, his statistics would cover the period from 24-Mar-2009 00:00 Melbourne time (23-Mar-2009 14:00 GMT) until 31-Mar-2009 00:00 Melbourne time (30-Mar-2009 14:00 GMT). For another customer, who also has a weekly billing period but is in the New York time zone, this billing period will cover calls made from 24-Mar-2009 00:00 New York time (24-Mar-2009 05:00 GMT) to 31-Mar-2009 00:00 New York time (30-Mar-2009 14:00 GMT).

Invoicing


64

When are PortaBilling® invoices generated?

Statistics are generated with a sufficient delay to make sure that the billing period for a particular customer (according to that customer’s time zone) has ended. Also, statistics calculation takes place only at a certain time of day (usually during night hours, when there is the least amount of activity in the system). Weekly invoices cover Monday through Sunday. Assuming that your system does statistical calculation from 2am until 8am Central European Time every day, then statistics for those customers whose time zone is in Asia or Europe should be available each Monday morning. For customers with a time zone in the US, the billing period will not have ended yet when statistics are calculated on Monday morning; thus they are created on Monday night and made available Tuesday morning. It might occur that in the middle of a billing period, a customer wants to pay for services consumed and does not want to wait until the end to receive an invoice. For such customers, administrators may generate a midterm invoice. For example, a customer with a monthly billing period wishes to pay for services consumed up to the 13th of May. On the 14th of May the administrator generates a midterm invoice for this customer, which covers the period from the 1st of May until the 13th of May. The midterm invoice is generated within the hour. Sometimes invoices for extra services such as a technician visit or an equipment purchase need to be provided at the time when such service is rendered so the customer can immediately proceed with payment. The administrator can generate an out-of-turn invoice (to cover only a few specific items) on demand. The out-of-turn invoice is generated immediately. More detailed information about midterm and out-of-term invoices can be found in the PortaBilling Administrator Guide.

Invoice total

There are two methods available for calculating the invoice total:

All charges during the period

This is the simpler method – the invoice contains all of the call charges for the specified period, with the invoice total equaling the sum of these charges. Balance adjustments, refunds and payments made by a customer via the online payment system are not included, since these refer to transactions which have already been made and will not occur again. So, for example, if during August a customer makes calls for $120 and pays $100 for his services in July on August 10, his invoice will show $120. Of

http://portaone.com/support/documentation/

Invoicing


65

course, the customer’s payment will be recorded in the system, and will affect his balance.

Including the previous balance

The invoice total will be calculated as: • Previous invoice total • + Sum of all charges during the period (call-related or manual

charges) • - Sum of all payments or refunds made during the period.

So, taking our previous example: if the customer’s invoice for July was $110, and he paid $100 and made calls for $120 during August, his total on the August invoice will be $110 + $120 - $100 = $130 Invoicing modes are controlled by the New_Style_Invoice_Calculation configuration option.

Basis of invoices

For a reseller, the call charges on the invoice are based on the sum total of all his xDRs in a given period. For a retail customer, the call charges on the invoice are the sum total of all CDRs (call charges and maintenance fees) for this customer’s credit accounts. Debit accounts are prepaid, and so since they have been already paid in full there is no need to invoice these calls.

Invoice template The invoice template is a specially formatted HTML document, which is created using either the PortaBilling® layout designer or an external tool (e.g. any third-party HTML editor). We suggest generating large invoices (hundreds of pages and more) using the external template uploaded into PortaBilling® as it requires less computing power for .pdf file generation in comparison with the layout designer. See the following chapters for a detailed description for each approach. It defines how the invoice should look, with information on fonts, colors, pictures, and placement of the components. When you view the invoice on the web interface, or when the invoice is automatically emailed to the customer, the template engine takes the invoice template and simply fills in the data fields (such as Header.Invoice Number) with their real values (for example, 1001 as the invoice number). The result of this processing is a .pdf file.

Invoicing


66

PortaBilling® generates PDF invoices using PrinceXML - industry-leading PDF generation software. The license for PrinceXML is provided as a part of an OEM agreement for all PortaOne customers. Requirements for invoices vary greatly from country to country (and even within the same country). The default invoice templates supplied with the system are suitable for British Columbia, Canada, and are provided as examples only. Be sure to create your own invoice template and assign it to your customers. Three predefined invoice templates for Layout Designer are supplied with PortaBilling®: “Totals only”, “Service usage details included” and “Service usage details + subtotal per service.” What is the difference among them?

A Totals only invoice

This is a traditional-style invoice. It consists of a single page with an invoice header (your company name, customer name, etc.), invoice fields (invoice number, invoice date), and invoice footer (subtotal, total).

Service usage details included invoice

This template’s first page is identical to the Totals only invoice template. In addition to this, it contains multiple pages with details of calls related to the invoice. You can use the Details Page button in Layout Designer to switch between the main page and the call details page. All of the calls made by a customer can be included, or only the summaries.

Service usage details + subtotal per service invoice

In addition to details of services used, this invoice contains subtotals calculated per every service.

Billing, invoicing and taxes Does PortaBilling® perform billing with or without taxes? Actually, PortaBilling® is a rating engine, so it all depends on how you use it. PortaBilling® does all the calculations based on rates you enter into the system, as well as tariff parameters and call duration. So, in this sense, it makes no difference whether the price includes tax or not. Thus, there are two scenarios available for dealing with taxes, and each has its own advantages.

Invoicing


67

Calculating taxation xDRs at the end of the billing period

If you enter rates without tax into PortaBilling®, the CDRs for calls (and other services) will not include the taxes. The calculation of taxation CDRs is performed prior to invoice calculation at the end of the billing period. The customer’s actual balance will be identical to the invoice total and will reflect all proper tax charges. The advantage of this method is that it gives unlimited flexibility: you can implement support for any taxation scheme you need. Note that since all the CDRs exclude taxes, customer balances do not include taxes until the end of the billing period when a taxation CDR is created. For prepaid services such as prepaid cards, taxes are applied at the time a calling card or top-up voucher is purchased. The amount of the card excludes taxes. If later on a customer makes a payment using a credit card to top-up their account, the taxes are calculated based on the amount of the top-up and are added to the payment sum. Upon successful payment processing, the customer’s balance is topped up by the actual amount excluding the tax.

Calculating xDRs with taxes

If you enter rates into PortaBilling® including taxes, you will get a “final” price, and the CDRs are calculated accordingly (with tax included). In this case, the balances are correct, and prepaid products work fine. To provide tax information on the invoice (if this is required), deduct the taxes from the amounts. This is the recommended method as it provides accurate billing for both prepaid and postpaid customers. To calculate taxes using either taxation method, PortaBilling® uses a unified invoice template. The taxation method itself is determined on a customer class or for a customer individually.

NOTE: If you defined the invoicing and taxation configuration via a customer class and then override a taxation plugin for an individual customer, PortaBilling® clears the Regular invoice and Out of turn invoice template settings to avoid configuration mismatches. For example, when you change a taxation plugin from SureTax to Fixed VAT Rate for a customer, the Regular invoice template value changes from As defined by the Customer Class to Do Not Create Invoice. To resume invoice generation, assign the invoice template that is compatible with new taxation plugin to the customer.

Invoicing


68

Applying fixed VAT rate using customer classes

Let’s consider the example of including a fixed tax into a customer class, which will then be applied to the customer:

1. Go to the Templates page. • Create a new invoice template. • Click Save.

2. Go to the Customer Classes page. • Create a new customer class or modify an existing one. • Select Finances and then click Invoicing. • On the Invoicing panel, click Regular invoices and:

o Enable the Use regular invoices option; o Select the created above template in the Invoice

template drop down menu.

• Click Taxation from the Finances section on the customer class panel.

• Select the Fixed VAT rate from the Taxation plugin list. • Specify whether rates are included into the rates or excluded

from them. • Select when to assess taxes for customers, at the moment of

payment (applicable to prepaid customers) or at the end of the billing period (applicable to postpaid customers).

• Select No from the Exempt from list.

Invoicing


69

• Specify the desired percentage in the VAT percentage field and click Save.

Applying fixed VAT rate without using customer classes

To apply a fixed tax directly to the customer, do the following: • On the Customer panel select Finances and then go to the

Invoices and Taxation panel. • Click Invoicing configuration and select the above-created

template in the Regular invoice template field. • Click Taxation and select Fixed VAT Rate from the

Taxation plugin list. • Choose No in the Exempt From Tax field. • Specify the required tax percentage.

Layout designer


70

4. Layout designer

Layout designer


71

Layout Designer is a visual (WYSIWYG) tool for creating document templates. It is implemented using only Javascript and DOM HTML extensions, so it will work in the MS IE or Mozilla web browser, and no installation of extra components on the user’s computer is required. When you design a template in Layout Designer, you define how the document should look: the location of components, pictures, fonts, and colors. You also place the data fields on the document. These are containers for real data, defining where the data element should appear. For example, on the invoice template you put an Invoice.number data field in the place where you would like the invoice number to be printed (top-right corner, in the example below). When the actual invoice is generated based on this template, Invoice.number will be replaced by the actual invoice number (e.g. 557). Make sure you insert the data field using the pop-up menu, because if you simply type Invoice.number it will be regarded as a text string, and so will appear on the invoice exactly as you have typed it. NOTE: During design, data fields are represented on the screen by sample data, e.g. 25 for the invoice number. This data is provided only for your convenience, and is used only in design mode. All sample data are shown in over lined font, which makes it easy to recognize.

Layout Designer consists of two main parts:

• Toolbar (on the left). It contains buttons and controls for manipulating content in the editor window.

• Worksheet (on the right). It contains the document itself.

Layout designer


72

General document properties

Page setup

In order to access page setup properties, right click on the empty background of a template window (i.e. not on an object such as a table or image).

Choose the “Page Setup” item.

You can choose the paper format, margins, and the position of envelope windows. Consult the online help for a detailed description of different envelope styles.

Grid properties

The grid helps you easily adjust objects in the template. There are a few buttons on the toolbar which control the grid’s behavior:

• - Turn the grid on or off (by default it is on).

• - Turn snap to grid on or off. When snap to grid is on, object edges will always be on one of the grid lines, so you cannot place an object between the grid lines when dragging or resizing it.

Layout designer


73

• The select menu allows you to choose the size of grid cells.

• - Shows or hides the envelope window on the template.

Working with images You can add your own images to the template. These images will then be stored on the server for use by anyone browsing documents created from the template. To add a new image:

• Click on the empty background of the template (i.e. no other object, such as a picture or table, should be selected). The Add picture button will become enabled.

• Click on the Add Picture button. • The Open File dialog will appear. Choose a picture on your local

disk in the .jpg, .png or .gif format. • Click Open and the picture will be transferred to your template.

You can now move or resize it.

Placing data elements The main object of the Layout Designer is the table, a placeholder for all inserted information. A table contains text or data fields which otherwise could not be put into the template. To add a new table to a template:

• Click on the empty background of the template (i.e. no other object, such as a picture or table, should be selected). The Add Table button should become enabled.

• Click on the Add Table button. A new table will then be added to the template. This is a very basic table, consisting only of a single cell. However, you can change it. To move the table to the desired place, simply drag it there (click on the table and move the mouse without releasing the mouse button). To perform advanced operations on the table (e.g. adding a row), right click on the table so that a menu appears.

Layout designer


74

A table or a cell within a table can be moved and scaled by dragging the cell handles. Double click a table or a cell to enter cell editing mode, where you can type in or edit the cell’s text. To change the attributes of the cell’s text, make sure the cell is selected (8 black square handles are visible) and set the text attributes in the toolbar on the left. Changing a cell’s text attributes in the toolbar will affect all text in the current cell. To change the attributes of part of the text, enter cell editing mode (double-click), select part of the text, and use the keyboard shortcuts listed below:

• Ctrl + B - Bold • Ctrl + I - Italic • Ctrl + U - Underlined

To insert data fields into the cell, do the following:

• Right-click on the cell where the data field should be inserted. • In the top part of the menu, click on the component name to

which the data field belongs (e.g. Header). A submenu with a list of all data fields in this component will appear.

• Click on the name of the data field you would like to insert. You can always go into cell editing mode and add text before or after the data field. Also, by removing all of the over lined data field name, you can completely delete the data field from the cell.

Changing text attributes You can apply multiple formatting styles to text elements in a table (this includes both static text and data fields), namely:

• Text alignment within the cell.

Layout designer


75

• Text font and font attributes, text color. • Table cell borders and border style.

Let’s consider the example of changing the “Bill To:” table text attributes: • Align the text to the middle left position. • Change font style to Bold, font Family to Fantasy and set Font

Size to 9. • Apply green Foreground Color and wheat Background color. • Set square Table Border.

Then click Save. Now you can generate a preview by pressing the Preview button.

Consult the online help for a complete list of all possible text operations.

External invoice templates


76

5. External invoice templates



77

As an alternative to the WYSIWYG invoice layout designer (built into the system), you can use another approach in which an invoice template can be designed as an HTML+CSS file and then uploaded into the system (CSS stands for Cascading Style Sheets). This simplifies the process if the invoice template is created by an external design agency (that does not have access to PortaBilling®) and allows advanced template customizations (e.g. arrangement of data to exactly match “legacy” invoices or insertion of dynamic content such as banners) by third-party developers. Also we suggest using this approach for large invoices (hundreds of pages and more) as it requires less computing power for PDF file generation in comparison with the WYSIWYG invoice layout designer.

Creating an external invoice template The external invoice template is a HTML + CSS file. This file consists of ordinary HTML/CSS code and special placeholders (variables) that define which relevant invoice data should be shown in your invoice (i.e. company name, invoice number or invoice due date). When a template file is parsed for output, the variables are replaced with their actual values by a template processing engine (also known as a template processor). The CSS part of the code defines how your invoice will look and may include special style sheets for proper PDF styling which will be used by PrinceXML to convert HTML documents into PDF files.

Add variables to your invoice template

Your invoice template includes changeable and unchangeable content. The unchangeable (boilerplate) part of the template is defined by plain HTML code with style classes, while the changeable part is defined by means of variables – variable values that show up in your invoice. Variables are included in special tags to clearly indicate where in the document they must be placed and they are then auto-replaced with the actual values by a template processing engine. PortaBilling® uses the Template Toolkit to process external invoice templates (the manual can be found at https://metacpan.org/pod/Template::Manual ). By default, the [% ... %] tags are used to indicate variables in the Template Toolkit. The following code demonstrates how to include the variables invoice.issue_date (indicates the date when the invoice was created) and invoice.invoice_number (indicates the invoice’s order number) in an invoice template: <table class="abs date-num"> <tr>

<td>Date</td> <td>Invoice #</td>

</tr>

https://metacpan.org/pod/Template::Manual



78

<tr> <td>[% invoice.issue_date | html %]</td> <td>[% invoice.invoice_number | html %]</td>

</tr> </table>

In APPENDIX A. Variables that Can Be Used in an External Invoice Template, you will find a list of variables (and their descriptions) that can be used to show different information in the invoice.

Template toolkit directives

Besides the use of variables, the Template Toolkit provides a set of directives that allows more complex processing operations to be performed. These include accessing and updating template variables, processing templates files and blocks (for example, including another template onto the current one), and ways of selecting and grouping the data based on a particular condition, etc.

The Template::Manual::Directives page lists all the Template Toolkit directives, complete with examples of their use.

PDF specific CSS

PrinceXML – the PDF conversion tool used in PortaBilling® – converts HTML documents into PDF files by applying Cascading Style Sheets (CSS). In order to adjust generated PDF files to your own look and feel, customize the style sheets written in CSS according to PrinceXML’s guidelines for CSS customization (available on their web site: http://www.princexml.com/doc/8.1/ ). For example, the following CSS code sets the page size and borders for your PDF files: @page {

size: A4 portrait; margin-left: 0.25in; margin-right: 0.25in; margin-top: 0.25in; margin-bottom: 0.25in;

}

The following CSS code can be used to add a custom footer to the bottom of every PDF page in your invoice: @page { @bottom-left {

content: "2000-2015 PortaOne, Ink. Thank you for choosing our company!"; font-family: serif; font-size: 10pt;

} }

https://metacpan.org/pod/Template::Manual::Directives

http://www.princexml.com/doc/8.1/

79

Advanced template customization

This section provides some code examples to help in designing a unique template that best meets your needs. For example, the following code adds a separate page in your invoice with details about voice calls made during a billing period:   [% SET iter = services.3 -%] [% SET row = iter.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 7;"><b>Voice Calls</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% SET total_time = 0 -%] [% SET prev_row = undef -%] [% WHILE row -%] <tr> <td>[% row.xdr_cli | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.country_name | html -%]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% row.xdr_charged_quantity %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td> </tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% SET total_time = total_time + row.xdr_charged_quantity -%] [% SET prev_row = row -%] [% SET row = iter.next_row -%] [% END -%] [% IF prev_row -%] <tr> <td style="table-column-span: 5;"><b>Total:</b></td> <td>[% total_time %]</td> <td>[% total_amount %] [% customer.iso_4217 %]</td> </tr> [% END -%] </tbody> </table> [% END -%] The resulting invoice page with details on voice calls will look like this:

80

The following code demonstrates how to group voice calls made during a billing period by country name:   [% SET iter = services.3 -%]  [% SET row = iter.next_row('country_name') -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 7;"><b>Voice Calls</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% SET total_time = 0 -%] [% SET prev_row = undef -%] [% WHILE row -%] [% IF prev_row AND prev_row.country_name != row.country_name -%] <tr> <td style="table-column-span: 5;"><b>Total by [% prev_row.country_name | html -%]</b></td> <td>[% total_time %]</td> <td>[% total_amount %] [% customer.iso_4217 %]</td> </tr> <tr> <td style="table-column-span: 7;">[% row.country_name | html -%]</td> </tr> [% SET total_amount = 0 -%] [% SET total_time = 0 -%] [% ELSIF NOT prev_row %] <tr> <td style="table-column-span: 7;">[% row.country_name | html -%]</td> </tr> [% END %]



81

<tr> <td>[% row.xdr_cli | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.country_name | html -%]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% row.xdr_charged_quantity %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td> </tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% SET total_time = total_time + row.xdr_charged_quantity -%] [% SET prev_row = row -%] [% SET row = iter.next_row -%] [% END -%] [% IF prev_row -%] <tr> <td style="table-column-span: 5;"><b>Total by [% prev_row.country_name | html -%]</b></td> <td>[% total_time %]</td> <td>[% total_amount %] [% customer.iso_4217 %]</td> </tr> [% END -%] </tbody> </table> [% END -%]

The resulting invoice page summarizing voice calls grouped by country name will look as follows:



82

In APPENDIX C. Advanced Template Customizations, you can find other examples of advanced template customizations (e.g. arrangements of data that exactly match “legacy” invoices).

General recommendations

Below are a few general points to remember when creating your own invoice template:

1. If you are planning to develop a multiple page template (for example, with summary information on the first page and detailed information on the second page), we recommend that you write the code for each page individually and then combine it later on. If the code is contained in one single file, pages may overlap when viewed in a web browser.

2. If the Template Toolkit construction is included in a custom invoice template, some template blocks might be displayed incorrectly in a web browser until the final HTML output is produced. This is normal and is corrected when the template passes through the template processor.

3. It is a good idea to work out the overall design of your invoice template first, and then proceed with adding the Template Toolkit constructions.

4. You may link the template HTML file to an external CSS file as PrinceXML does not apply any restrictions on this.

Uploading an invoice template to PortaBilling®

To upload an external invoice template to PortaBilling®, follow these steps:

1. Locate the HTML+CSS file for your custom template. An improved external invoice template is now available and can be downloaded from www.portaone.com: http://portaone.com/resources/invoice_template.zip

2. Prepare image files to be inserted into the template. The images must be defined in the HTML+CSS file with the following tag: <img class="advert" src="[% image_path %]ad.jpg" />

3. Upload the new invoice template to the PortaBilling® administrative web interface.

http://portaone.com/resources/invoice_template.zip

http://portaone.com/resources/invoice_template.zip



83



84

4. Check the look of the invoice template. When you click Preview on the toolbar, a PDF-file showing the final layout is generated.

5. Assign the uploaded invoice template to a new or existing customer.



85

6. Below is an example of the invoice generated using a custom invoice template.



86

In APPENDIX B. External Invoice Template Example, you can find another example of the custom invoice template. This example is analogous to the invoice layout designer’s default template.

Updating an earlier uploaded template To introduce changes and adjustments to an invoice template that was already uploaded follow these steps:

1. Update the HTML+CSS file for your custom template according to your requirements.

2. Prepare new image files to be inserted into the template. 3. Upload the updated invoice template on the PortaBilling®

administrative web interface.



87

4. Delete images that are no longer used and upload new images defined in the invoice template.

Templates for outgoing notification messages


88

6. Templates for outgoing notification messages



89

Notification templates There are many types of email and SMS messages that PortaBilling® sends to your administrative and end users: notifications that a balance approaches its credit limit, statistics summaries, different alerts sent to administrators, etc. The notification messages are managed via notification templates. There are two types of notification templates:

• customer class notifications • user notifications.

Both template types contain a set of notification messages. You can customize the language and content of these messages, e.g. add the “Company name” variable to the “Credit limit exceeded” notification.

To enable the notifications on a customer class or user, first create a notification template. Then open the Notifications panel and assign the notification template. When the template is assigned, select which notifications to send individually for each customer class or user. You can select a specific notification group or particular notifications from each notification group.



90

To edit the email or SMS notification messages, open the required notification template and modify the subject, BCC and body of the notification. The changes will apply to all the entities this template is assigned to.

Notification messages syntax

NOTE: Notification messages use basic HTML::Mason syntax; you can find more information on the HTML::Mason homepage.

http://www.masonhq.com/



91

Here is an example of the default Credit limit exceeded notification message: Subject: Credit limit exceeded - services are now blocked

BCC: [email protected] Body: Dear <% $greetings %>, We would like to inform you that the current balance on your account <% $companyname ? $companyname : $name %> has reached its credit limit and your service is now blocked. Your balance: <% $balance %><% $currency %> Your credit limit: <% $credit_limit %><% $currency %>

Variables: greetings companyname name balance credit_limit currency

Each template contains subject, BCC, body and variables sections. The variables section defines the parameters (e.g. Current customer balance) that can be used in the body section. The subject section contains the text to be entered in the subject line of the outgoing email (e.g. Credit limit exceeded). The BCC section contains email addresses of persons who want to receive a copy of this notification. You can specify more than one valid email address; make sure you separate them with commas. The body section contains the text which will be used as the email body text. Any normal text entered here will appear unchanged in the email. If you want to include the current value of a certain parameter in the text, enclose the parameter variable in <% %> as shown below: Your credit limit: <% $credit_limit %><% $currency %>.

In fact, you may include mini-pieces of Perl code in <% %>. For instance, the line below includes a conditional statement, and will produce either a company name (if one is defined) or a customer name: <% $companyname ? $companyname : $name %>

You may also use the following service functions for editing email notification templates:



92

• column (text, width => N, align => ‘left’|’right’) – This outputs a space padding string of a given width. The text alignment can be either flush left or flush right. By default, text alignment is set to the left. The function’s parameters are:

o text – defines the text to output o N – defines the width of the output string o align – defines the string alignment (can be ether left-

or right-aligned) • line (char, width) – This outputs a string of repeated

characters (e.g. it can be used to display underlined text). The function’s parameters are:

o char – defines the character to output o width – defines how many times to output the char

parameter

For example, the following code: <% column('Previous Balance:', width => 45) %> <% column($previous_balance, width => 10, align => 'right') %> <% line('-', 25) %> `

will output the following string: Previous Balance: 10.00 ------------------------- In APPENDIX D. Available Notification Messages, you can find email notification messages and their descriptions.

Appendices


93

7. Appendices

Appendices


94

APPENDIX A. Variables that can be used in an external invoice template

Template Name Description Environment for direct customers, Reseller for sub-customers

env.i_env ID env.name Environment name env.companyname The conventional form for your

company’s name env.addr1 Company’s street address env.addr2 ... env.addr3 ... env.addr4 ... env.contact_city City where company is located env.contact_email

Company contact person’s email address

env.contact_subdivision Province / state where the company is located

env.contact_zip Postal code for company’s location env.country Country name env.description Short description env.email Primary email contact env.faxnum Primary fax number env.laddr1 Address where company name

is legally registered env.laddr2 ... env.lcountry Country where company is legally

registered env.lcity City where company is legally

registered env.lname Legally recognized form of company’s

name env.lzip Postal code for company’s registered

location env.iso_3166_2 Country subdivision code env.iso_3166_1_a2 Country code env.iso_4217 The internal currency env.phone Company’s primary telephone number env.subdivision Country subdivision name env.tax_id Locally designated tax number env.tz Time zone company operates in env.web Company’s web address

Appendices


95

Customer information customer.i_customer Customer’s unique numeric number customer.i_customer_class Numeric ID for customer Class

assigned to customer customer.i_customer_type 1 (Retail), 2 (Reseller), 3 (Distributor) customer.i_lang Localization language, 2 characters

ISO639-1 code (examples: en, es) customer.iso_4217 Customer’s currency customer.address Full address line customer.address_line_2 The 2nd line of the customer's address

that contains the values from baddr2, baddr3, baddr4 and baddr5 fields. The values are separated by the '\n' delimiter.

customer.balance Customer’s balance at time of PDF generation

customer.billing_period Defines customer’s invoicing frequency

customer.bp_charge_cc Y or N defines if customer’s credit card is charged when invoice is generated

customer.companyname The conventional form of company’s name

customer.cont1 Primary contact customer.cont2 Alternative contact customer.city City name customer.country Country name customer.creation_date Date when customer was added to

PortaBilling® system customer.credit_limit Customer’s current credit limit customer.custom_field1 Value for first Custom Field customer.custom_field2 Value for second Custom Field ... ... customer.custom_fieldN Value for Nth Custom Field customer.discount_rate Amount of discount applied to all of

customer’s subscriptions by default customer.email Primary email contact customer.faxnum Primary fax number customer.firstname First name customer.midinit Middle name customer.lastname Last name customer.lname Either company name or first name +

last name customer.login Customer self-care login customer.name Customer ID, defines customer name

as it appears in PortaBilling® system

Appendices


96

customer.notepad Text entered in Notepad field on web customer.opening_balance Customer’s starting balance customer.out_date_format Preferable date format customer.out_date_time_format

Preferable date-time format

customer.out_time_format Preferable time format customer.phone1 Primary telephone number customer.phone2 Alternative telephone number customer.salutation Something like ‘Mr.,’ ‘Ms.’ customer.state Province / state name customer.zip Postal code customer.tax_id Locally-designated tax number customer.TZ Time zone

Invoice information invoice.i_env Environment ID invoice.i_customer Reference to customer’s ID number invoice.i_invoice ID number invoice.invoice_number Visible invoice number invoice.i_invoice_status Invoice status, refer to value from

Invoice_Status_Attribs table invoice.i_invoice_type Indicates the type of invoice: 1 –

regular, 2 – out of turn, 3 – midterm invoice.additional_invoices Sum of out-of-turn invoices for period invoice.adjustments Adjusted amount customer must pay

for this period invoice.amount_due Current invoice’s due amount invoice.amount_net Invoice period’s total amount invoice.amount_paid Amount customer already paid invoice.calls Sum of charges for all other services invoice.cust_name Name of customer for whom invoice

was issued invoice.do_not_pay This indicates that invoice amount is

too low to charge customer, therefore invoice amount is added to next invoice.

invoice.due_date Due date of the invoice in format defined by the customer

invoice_due_date_orig The invoice due date defined in the ISO format (YYYY-MM-DD)

invoice.due_days Days left until due date invoice.closed Indicates whether the invoice is closed

(sent to the customer) or not. invoice.issue_date Date when invoice was created,

displayed in format defined by the customer

invoice.issue_date_orig Date when invoice was created,

Appendices


97

displayed in ISO format (YYYY-MM-DD)

invoice.invoice_status_desc Invoice status description invoice.is_void N for normal invoices; Y for voided

ones invoice.iso_4217 Currency invoice.last_invoice The amount due from previous

regular invoice invoice.last_closing_date Indicates the date the customer was

closed after the invocie became overdue

invoice.last_notific_date Indicates the date the invoice was first sent to the customer

invoice.last_recollect_date Indicates the date the collection attempt was made (attempt to charge the customer's credit card on file for the amount due).

invoice.last_resend_date Indicates the date the invoice was resent to the customer

invoice.last_suspension_date

Indicates the date the customer was suspended after an invoice became overdue

invoice.last_warning_date Indicates the date the notification email was sent to the customer informing about service suspension

invoice.manual_charges Sum of manual charges from invoice period

invoice.measured_services Sum of charges for measured services invoice.new_style Defines whether the invoice includes

the previous balance or not invoice.override_control 1 indicates that this is an invoice to

charge for recurring fees separately invoice.period_from Invoice period’s start date invoice.period_from_orig Invoice period’s start date, displayed

in ISO format (YYYY-MM-DD invoice.period_to_orig Invoice period’s end date, displayed in

ISO format (YYYY-MM-DD invoice.period_to Invoice period’s end date invoice.payments Sum of payments made during invoice

period invoice.previous_balance Previous invoice’s due amount invoice.prior_balance Amount charged to customer before

first invoice issued. It might be that invoicing for this customer was initially disabled.

invoice.prior_balance_paid Amount customer paid before first

Appendices


98

invoice was issued. invoice.subscriptions Sum of subscription charges generated

during invoice period invoice.subtotal Equal to amount_net. Available only

if taxation plug-in used invoice.subtotal_without_taxes

Equal to (amount_net – taxes). Available only if taxation plug-in used

invoice.taxes Sum of taxes, non-zero only if taxation plugin used

invoice.tax_method 1 if taxation plug-in used, 0 if taxes are included in rates

Service totals for given invoice services Array indexed by i_service number,

value is ‘Service totals’ Service totals (allow to get xDRs for the chosen Services)

i_service Unique ID number for service name Service name i_service_type Unique ID number for service type rating_base Either ‘quantity’ or ‘session time’ period_totals.records Accumulated number of records period_totals.quantity Sum of quantity-based service period_totals.amount Accumulated sum of charged amount period_totals.tax_amount Accumulated sum of taxes period_totals.total_amount Accumulated sum of charges + taxes next_row Iterator, which returns next xDRs’

row for this service, or undefined if there are no more records

rating_base_unit Name of the smallest unit for measuring service usage. This is also the smallest unit you can use in rating configuration (e.g. one second)

rate_unit Name of the unit for calculating service usage charges (e.g. one minute)

taxation_codes Taxation codes defined for this service xDR row

account_id Master account ID account_batch Account batch name account_i_account Account’s unique ID account_name Account owner’s name country_iso_3166_1_a2 Country code country_name Country corresponding to destination country_subdivision_name Country subdivision corresponding

to destination destination_destination Destination used destination_description Destination description

Appendices


99

destination_group_name Destination group name destination_i_dest Destination’s unique ID rate_i_rate Rate ID used rate_effective_from Date when rate becomes effective rate_is_off_peak ‘Y’ for off-peak period rate, ‘N’

otherwise rate_interval_1 Rates.interval_1 (Rates.op_interval_1

for off-peak) rate_interval_n Rates.interval_n (Rates.op_interval_n

for off-peak) rate_price_1 Rates.price_1 (Rates.op_price_1

for off-peak) rate_price_n Rates.price_n (Rates.op_price_n

for off-peak) rate_off_peak_period 0, 1, 2 for ‘normal,’ off-peak

and second off-peak periods tariff_i_tariff Tariff ID used tariff_name Tariff name used xdr_account_id Account ID in xDR, may be account

alias xdr_accumulated_correction

Difference between initial and re-rated xDRs’ amounts

xdr_bill_time Date-time of session billing, displayed in customer’s format

xdr_bill_time_orig Date-time of session billing, displayed in ISO format

xdr_call_id Call-id xdr_charged_amount Charged amount xdr_charged_quantity Service quantity charged xdr_cli CLI xdr_cld CLD xdr_connect_time Connection date-time defined in

customer format xdr_connect_time_orig Connection date-time defined in ISO

format (YYYY-MM-DD HH:MM:SS) xdr_disconnect_time Date-time when session is

disconnected, displayed in customer’s format

xdr_disconnect_time_orig Date-time when session is disconnected, displayed in ISO format (YYYY-MM-DD HH:MM:SS)

xdr_h323_conf_id H323-conf-id xdr_h323_incoming_conf_id Incoming H323-conf-id xdr_history Additional information about xDR xdr_id ID of xDR xdr_peak_level Peak level applied

Appendices


100

xdr_setup_time Time (in mins.) between initial provisional response and connect_time.

xdr_split_order Sequential number if xDR is part of a group of xDRs resulting from same session

xdr_subscriber_ip Subscriber IP xdr_table Table name: cdr_accounts

or cdr_customers xdr_used_quantity Service quantity used xdr_acli Information about actual caller

identity within IP Centrex environment where call originated from. This identity may differ from the one delivered by the IP PBX (e.g. the IP PBX main account or caller’s phone if forwarded calls occurred) and displayed on the called party’s device

xdr_xcld Information about the extension ID dialed

xdr_xcli Information about the extension ID initiating the call

xdr_via_hg Information about the huntgroup dispatching the call

xdr_via_ext Information about the last extension ID the call was either forwarded or transferred from

xdr_media_duration Information about actual time during which owner of the billed account spoke

xdr_prerated_charge Information about original charges imported to PortaBilling® associated with xDR

xdr_e212_roaming_network Information about caller / callee roaming ID in E.212 format

Other variables image_path Path to the template images, used

to make a full link to the included image

xrate_list Enables the retrieval of exchange rate for the currency and calculates the price there. This variable requires the key that equals the iso_4217 code of the required currency (e.g. xrate_list.EUR)

Appendices


101

APPENDIX B. External invoice template example

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html> [% USE format -%] [% money = format('%.2f') -%] <html> <head> <style type="text/css"> @page { size: A4 portrait; margin-left: 0.25in; margin-right: 0.25in; margin-top: 0.25in; margin-bottom: 0.25in; } @page { @top-left { content: "Page " counter(page) " of " counter(pages); font-family: serif; font-size: 9pt; }; } table { border-collapse: collapse; } body { font-family: serif; } .abs { position: absolute; } .logo { top: 10mm; left: 10mm; } .company { top: 10mm; left: 40mm; width: 50mm; } .invoice { top: 10mm; left: 150mm; font-size: 24pt; font-weight: bold; } .date-num { top: 20mm; left: 120mm; width: 70mm; } .date-num td { border: black solid 1px; font-size: 10pt; text-align: center; vertical-align: center; height: 8mm; } .bill-to { top: 50mm; left: 10mm; width: 80mm; } .bill-to td { border: black solid 1px; padding-left: 3px; } .bill-to-header { height: 10mm; } .bill-to-body { height: 30mm; } .statement { top: 95mm; left: 10mm; width: 130mm; } .statement-header1 { table-column-span: 2; border: black solid 1px; text-align: center; height: 10mm; font-size: 10pt; } .statement-header2 { border: black solid 1px; text-align: center; height: 7mm; font-size: 10pt; } .statement-row { border: black solid 1px; text-align: center; height: 7mm; font-size: 10pt; } .due { top: 120mm; left: 10mm; width: 100mm; } .due .label { width: 70mm; border-bottom: 1px solid black; height: 10mm; font-size: 10pt; } .due .amount { border-bottom: 1px solid black; height: 10mm; font-size: 10pt; text-align: right; } .due .total { font-weight: bold; border-top: 3px solid black; border-bottom: none }

Appendices


102

.rule { top: 160mm; left: 15mm; width: 160mm; height: 1px; } .rule td { border-top: 1px solid black; } .totals { top: 160mm; left: 80mm; width: 100mm; } .totals .label { width: 75mm; border-bottom: 1px solid black; height: 10mm; font-size: 10pt; } .totals .amount { border-bottom: 1px solid black; height: 10mm; font-size: 10pt; text-align: right; } .totals .total { font-weight: bold; border-top: 3px solid black; border-bottom: none } .totals .subtotal { border-top: 3px solid black; } .details { top: 225mm; left: 10mm; width: 170mm; height: 30mm; border: 1px solid black; font-size: 10pt; text-align: center; vertical-align: top; padding-top: 2mm; } .disclaimer { top: 260mm; left: 10mm; width: 170mm; height: 20mm; border: 1px solid black; font-size: 10pt; text-align: center; vertical-align: top; padding-top: 2mm; } .xdrs { width: 200mm; font-size: 9pt; } .xdrs td { height: 7mm; text-align: left; } </style> </head> <body> <img class="abs logo" src="[% image_path %]parcel.gif"/> <div class="abs company"> [% env.companyname | html %]<br> [% env.addr1 | html %]<br> [% env.addr2 | html %]<br> [% env.addr3 | html %]<br> [% env.addr4 | html %] </div> <div class="abs invoice">Invoice</div> <table class="abs date-num"> <tr> <td>Date</td> <td>Invoice #</td> </tr> <tr> <td>[% invoice.issue_date | html %]</td> <td>[% invoice.invoice_number | html %]</td> </tr> </table> <table class="abs bill-to"> <tr> <td class="bill-to-header">Bill To:</td> </tr> <tr> <td class="bill-to-body"> [% customer.companyname | html %]<br> [% customer.salutation | html %] [% customer.firstname | html %] [% customer.midinit | html %] [% customer.lastname | html %] <br> [% customer.baddr1 %]<br> [% customer.baddr2 %]<br> [% customer.baddr3 %] </td> </tr> </table> <table class="abs statement"> <tr>

Appendices


103

<td class="statement-header1">Statement Period</td> <td></td> <td></td> </tr> <tr> <td class="statement-header2">From</td> <td class="statement-header2">To</td> <td class="statement-header2">Terms</td> <td class="statement-header2">Due Date</td> </tr> <tr> <td class="statement-row">[% invoice.period_from | html %]</td> <td class="statement-row">[% invoice.period_to | html %]</td> <td class="statement-row">Pay in full</td> <td class="statement-row">[% invoice.due_date | html %]</td> </tr> </table> <table class="abs due"> <tr> <td class="label">Previous Balance</td> <td class="amount">[% money(invoice.previous_balance) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label">Payments</td> <td class="amount">[% money(0 - invoice.payments) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label">Charges this period</td> <td class="amount">[% money(invoice.amount_net - invoice.taxes) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label total">Total due</td> <td class="amount total">[% money(invoice.amount_due) %] [% customer.iso_4217 %]</td> </tr> </table> <table class="abs rule"><tr><td></td></tr></table> <table class="abs totals"> <tr> <td class="label">Session charges</td> <td class="amount">[% money(invoice.calls) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label">Subscription charges</td> <td class="amount">[% money(invoice.subscriptions) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label">Credits</td> <td class="amount">[% money(invoice.manual_charges) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label subtotal">Subtotal</td> <td class="amount subtotal">[% money(invoice.amount_net - invoice.taxes) %] [% customer.iso_4217 %]</td> </tr> <tr> <td class="label">Taxes</td> <td class="amount">[% money(invoice.taxes) %] [% customer.iso_4217 %]</td> </tr> <tr>

Appendices


104

<td class="label total">Total</td> <td class="amount total">[% money(invoice.amount_net) %] [% customer.iso_4217 %]</td> </tr> </table> <div class="abs details">Payment Details:<br>Explain how to pay here</div> <div class="abs disclaimer">Fine Print / Disclaimer</div> <div style="page-break-before: always;"></div>   [% SET iter = services.2 -%] [% SET row = iter.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 5;"><b>Payments</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% WHILE row -%] <tr> <td>[% row.account_id | html %]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td> </tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% row = iter.next_row %] [% END %] </tbody> <tfoot> <tr> <td style="table-column-span: 4;"><b>Total Payments</b></td> <td>[% money(total_amount) %] [% customer.iso_4217 | html %]</td> </tr> </tfoot> </table> [% END -%]  [% SET iter = services.1 -%] [% SET row = iter.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 5;"><b>Credits</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% WHILE row -%] <tr> <td>[% row.account_id | html %]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td>

Appendices


105

</tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% row = iter.next_row %] [% END %] </tbody> <tfoot> <tr> <td style="table-column-span: 4;"><b>Total Credits</b></td> <td>[% money(total_amount) %] [% customer.iso_4217 | html %]</td> </tr> </tfoot> </table> [% END -%]  [% SET iter = services.4 -%] [% SET row = iter.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 6;"><b>Subscriptions</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% WHILE row -%] <tr> <td style="width: 30mm;">[% row.account_id | html %]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% row.xdr_disconnect_time | html %]</td> <td>[% money(row.xdr_charged_amount) %]</td> </tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% row = iter.next_row -%] [% END -%] </tbody> <tfoot> <tr> <td style="table-column-span: 5;"><b>Total Subscriptions</b></td> <td><b>[% money(total_amount) %]</b></td> </tr> </tfoot> </table> [% END -%]  [% SET iter = services.12 -%] [% SET row = iter.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 6;"><b>Taxes</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% WHILE row -%] <tr> <td>[% row.account_id | html %]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% row.xdr_disconnect_time | html %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td> </tr>

Appendices


106

[% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% row = iter.next_row %] [% END %] </tbody> <tfoot> <tr> <td style="table-column-span: 5;"><b>Total Taxes</b></td> <td>[% money(total_amount) %] [% customer.iso_4217 | html %]</td> </tr> </tfoot> </table> [% END -%]  [% FOREACH srv = services -%] [% NEXT UNLESS srv -%] [% SET i_service = srv.i_service -%] [% NEXT IF i_service == 1 -%] [% NEXT IF i_service == 2 -%] [% NEXT IF i_service == 11 -%] [% NEXT IF i_service == 12 -%] [% NEXT IF i_service == 100 -%] [% SET row = srv.next_row -%] [% IF row -%] <table class="xdrs"> <thead> <tr> <td style="table-column-span: 7;"><b>[% srv.name | html %]</b></td> </tr> </thead> <tbody> [% SET total_amount = 0 -%] [% SET total_time = 0 -%] [% SET prev_row = {} -%] [% WHILE row -%] [% IF prev_row AND prev_row.country_name != row.country_name -%] <tr> <td style="table-column-span: 5;"><b>Total by [% prev_row.country_name | html -%]</b></td> <td>[% total_time %]</td> <td>[% total_amount %] [% customer.iso_4217 %]</td> </tr> <tr> <td style="table-column-span: 7;">[% row.country_name | html -%]</td> </tr> [% SET total_amount = 0 -%] [% SET total_time = 0 -%] [% END -%] <tr> <td>[% row.xdr_cli | html %]</td> <td>[% row.xdr_cld | html %]</td> <td>[% row.country_name | html -%]</td> <td>[% row.destination_description | html %]</td> <td>[% row.xdr_connect_time | html %]</td> <td>[% row.xdr_charged_quantity %]</td> <td>[% money(row.xdr_charged_amount) %] [% customer.iso_4217 | html %]</td> </tr> [% SET total_amount = total_amount + money(row.xdr_charged_amount) -%] [% SET total_time = total_time + row.xdr_charged_quantity -%] [% SET prev_row = row -%] [% SET row = srv.next_row -%] [% END -%] [% IF prev_row -%] [% END -%]

Appendices


107

[% IF prev_row -%] <tr> <td style="table-column-span: 5;"><b>Total by [% prev_row.country_name | html -%]</b></td> <td>[% total_time %]</td> <td>[% total_amount %] [% customer.iso_4217 %]</td> </tr> [% END -%] </tbody> </table> [% END -%] [% END -%] </body> </html>

APPENDIX C. Advanced template customizations

You can use extra tools to customize templates so that information in invoices is provided in the most convenient and suitable form for your customers. Advanced template customization makes it possible to sort, group and sum up xDR information in the ways you need. To do this, use the template toolkit engine. Discover its syntax on this website: http://template-toolkit.org.

NOTE: Advanced template customizations require basic knowledge of template markup language and programming algorithms. Please contact the PortaOne support team to order a template that meets your individual needs.

PortaBilling® clients are encouraged to create customized templates themselves. To make this task easy for you we provide typical algorithms that are useful for the most common queries.

Grouping by a single parameter

Basic algorithm

You may need to display your xDRs grouped by account ID, destination country or some other key parameter. To do this, follow this basic algorithm:

1. Define a key parameter for sorting and grouping. The SET directive updates the variable’s value:

[% SET row = iter.next_row('key') -%]

In this statement the template engine forms a DB query and assigns the first entry from the xDR tables to the row variable. The variable called key in our example defines the key parameter for the xDR

Appendices


108

grouping. To insert you own key parameter use its DB name from the xDR row section of Appendix A. The following table rows can be obtained by consecutive calls to iter.next_row(’key’).

NOTE: The default value for the key variable is billing time – xdr_bill_time. It will be applied if you do not mention any key: [% SET row = iter.next_row() -%]

2. Use WHILE loop and the following block of code to define and

group xDRs with the same key parameter: [% WHILE row -%] [% IF prev_row AND prev_row.key != row.key -%]

The prev_row variable stores the previous value of the row variable. The template engine compares these values to find if the key values differ in these adjacent rows. If they do differ, it means that the previous group of xDRs has ended and a new group starts.

3. Output data by the key parameter: <tr> <td> Result is [% prev_row.key %]</td> </tr>

Detailed code example

To see how to apply this algorithm for the template, please consider the code with detailed comments. In this template the system sorts and groups xDRs by account ID (account_id), and then calculates and outputs the total amount for the calls from each account:  [% SET iter = services.3 -%]

 [% SET prev_row = undef -%] <-- Reset the counter --> [% SET total_amount = 0 -%]

 [% SET row = iter.next_row('account_id') -%]

<-- Repeat for all xDRs for a current account. The WHILE

loop repeats until all account xDRs are processed -->

Appendices


109

[% WHILE row -%] <-- If the values of key parameter differ in any two

adjacent rows, it means that the previous group of xDRs has ended and a new group starts. In this example, the xDRs for the previous account has ended, so the billing engine outputs the subtotals for it, resets the counters and then processes the next account’s xDRs -->

[% IF prev_row AND prev_row.account_id != row.account_id -%]

 <tr> <td>Total for the account #[% prev_row.account_id

%]</td> <td>[% total_amount %]</td> </tr>  [% SET total_amount = 0 -%] [% END -%] 

[% SET total_amount = total_amount + row.xdr_charged_amount -%]

[% SET prev_row = row -%] [% SET row = srv.next_row -%]

[% END -%] <-- The WHILE section’s code ends and the loop repeats anew

-->

Grouping by multiple parameters

You may need to group the xDRs by two or more parameters. For instance, if your end users often make calls abroad, then you can provide information regarding how much each call to each foreign country costs. For this template two key parameters are needed – account ID (account_ID) and destination country (country_name).

Basic algorithm

Let’s consider the algorithm of grouping by two parameters: 1. Define the variables for counting and set them to zero:

[% SET total_amount = 0 -%] [% SET country_amount = 0 -%]

2. Define the key parameters for sorting and grouping using a comma:

[% SET row = iter.next_row('account_id,country_name') -%]

Appendices


110

When you apply this statement, data is sorted in the following way (account ID, destination country, total amount spent): 11125557100, Austria, $5

11125557100, Austria, $3 11125557100, Brazil, $10 11125557100, Brazil, $3 18887123555, Austria, $1 18887123555, Austria, $3 18887123555, France, $5

3. Use the WHILE loop and compare the adjacent rows in order to group the xDRs with the same key parameters:

[% WHILE row -%] [% IF prev_row %] [% IF prev_row.account_id != row.account_id -%]

4. Count subtotals for the groups of xDRs that belong to the current account and current destination country:

[% SET total_amount = total_amount + row.xdr_charged_amount

-%] [% SET country_amount = country_amount +

row.xdr_charged_amount -%]

When the WHILE loop is executed for the first time, the prev_row variable is empty, so the variables for counting are simply updated:

total_amount = 5 (0+5) country_amount = 5 (0+5)

After this, the row with 100, Austria, $5 data is saved to the prev_row variable. When the WHILE loop is executed for the second time, the system finds out that the account_id and country_name in the adjacent rows are the same. That is why the variables for counting are easily updated:

total_amount = 8 (5+3) country_amount = 8 (5+3)

5. Output the total amount for the service when a key parameter (either destination country or account ID) in the adjacent rows differs. In the third WHILE loop execution, the account remains the same for the adjacent rows, but the countries differ. It means that it is time to output the variable for counting total amount per country:

<tr> <td> Total amount for calls to [%

prev_row.country_name %] for the account #[% prev_row.account_id ] is [% country_amount %]

</td> </tr>

Appendices


111

In this case the invoice will represent the following information: Total amount for calls to Austria for account #100 is $8. Zeroize the variable for counting the total amount per country:

 [% SET country_amount = 0 -%]

After this, the WHILE loop processes the next country for the same account.


We provide the full code of the current example with detailed comments about each fragment:

 [% SET iter = services.3 -%]

 [% SET prev_row = undef -%] <-- Reset the counters --> [% SET total_amount = 0 -%] [% SET country_amount = 0 -%]

 [% SET row = iter.next_row('account_id,country_name') -%]

[% WHILE row -%] [% IF prev_row %] [% IF prev_row.account_id != row.account_id -%]  <tr> <td>Total amount for the account #[%

prev_row.account_id %]</td> <td>[% total_amount %]</td> </tr>  [% SET total_amount = 0 -%]

[% SET country_amount = 0 -%] [% ELSIF prev_row.country_name != row.country_name -%] <!-- Processing the next country name for the same account -

->

Appendices


112



<tr> <td>Total for the account #[% prev_row.country_name

%]</td> <td>[% country_amount %]</td> </tr>  [% SET country_amount = 0 -%] [% END %-] [% END -%] <-- Update all counters --> [% SET total_amount = total_amount + row.xdr_charged_amount

-%] [% SET country_amount = country_amount +

row.xdr_charged_amount -%] [% SET row = srv.next_row -%] [% END -%]

Choosing the service

Service ID

Before processing the xDRs, you must specify which service the xDRs were created for. To do this, you need the service’s unique database ID that can be found in the Services table of the PortaBilling® database. To specify a service, use this code at the very beginning of a template:

[% SET iter = services.X -%]

where X indicates the service’s ID.

NOTE: Each table in your template may contain data that represents only one service. Specify a service ID every time you process xDRs with a different type of service.

Predefined services with their unique IDs can be found in the following table:

i_service Name 1 Credits / Adjustments 2 Payments 3 Voice Calls 4 Subscriptions 5 Data Service [KB] 6 Data Service [MB] 7 Quantity Based 8 Wi-Fi 9 Dial-up 10 Messaging Service

Appendices


113

11 Cleanup 12 Taxes 14 Conferencing 15 DID Usage 16 IPTV

If required for business, an ITSP can create customized services via the administrator web-interface. To process the xDRs of such customized services, the administrator must retrieve the service’s unique ID from the Services table. There are two ways to do this:

1. API methods – Use get_service_list to see the full list of services.

2. SQL query – Input this query to see customized services: 'SELECT i_env, i_service, name FROM Services WHERE i_env != 0'

One day you might want to expand your business and provide additional services. For this reason it would be good to have an adjusted template to represent charges for new services. In order to check whether other services need to be output to the template, use this code:

[% FOREACH srv = services -%] [% NEXT UNLESS srv -%] [% SET i_service = srv.i_service %] [% SER service_name = srv.name %]

This code seeks each service from the Services table, one by one. If a service is found in the xDRs, start the process of sorting and grouping as described previously.


In addition, we provide the full code for the system to check whether other services are present. If they are, they are sorted and grouped by their key parameters. We refer to the previous case with multiple key parameters – account ID and destination country.

NOTE: Add this code at the very end of your template.

<-- Searching for other services --> [% FOREACH srv = services -%] [% NEXT UNLESS srv -%] [% SET i_service = srv.i_service -%]  [% NEXT IF i_service == 3 -%]  [% NEXT IF i_service == 11 -%]

Appendices


114



[% NEXT IF i_service == 12 -%]  [% NEXT IF i_service == 100 -%]  [% SET service_name = srv.name %]   [% SET prev_row = undef -%] <-- Reset the counters --> [% SET total_amount = 0 -%] [% SET country_amount = 0 -%]  [% SET row = iter.next_row('account_id,country_name') -

%] [% IF row %]  <tr> <td colspan=2>Service: [% service_name %]</td> </tr> [% END %] [% WHILE row -%] [% IF prev_row %] [% IF prev_row.account_id != row.account_id -%]  <tr> <td>Total amount for the account #[%

prev_row.account_id %]</td> <td>[% total_amount %]</td> </tr>  [% SET total_amount = 0 -%] [% SET country_amount = 0 -%] [% ELSIF prev_row.country_name != row.country_name -

%]   <tr> <td>Total for the account #[%

prev_row.country_name %]</td> <td>[% country_amount %]</td> </tr>  [% SET country_amount = 0 -%]

Appendices


115

[% END %-] [% END -%] <-- Update all counters --> [% SET total_amount = total_amount +

row.xdr_charged_amount -%] [% SET country_amount = country_amount +

row.xdr_charged_amount -%] [% SET row = srv.next_row -%] [% END -%]  [% END %]

APPENDIX D. Available notification messages

The following table provides a brief summary of notification messages included in PortaBilling®.

User notifications

These notification messages are sent to an administrator. You can configure them for an admin user.

Notification name

Description Email SMS

Inventories management DID numbers were uploaded

This notification confirms that DID numbers have been uploaded. The message provides a list of successfully uploaded DID numbers and a list of DID numbers that were not uploaded due to error.

+

SIM cards upload

This notification informs that SIM cards upload procedure has been completed. The message contains a summary about total SIM cards processed.

+

DID upload error

This notification asserts that some update operations failed during DID upload. The file, including data that was not properly imported, is attached to this message.

+

Billing notifications Failed to re-generate the

This notification asserts that invoice re-generation failed +

Appendices


116

invoice, no invoice number or customer ID

because invoice number or customer ID was not identified.

Failed to re-generate invoice

This notification asserts that the attempt to re-generate the invoice failed.

+

Invoice re-generated successfully

This notification confirms that the invoice was re-generated successfully.

+

List of the auto-approved invoices

This notification provides a list of invoices auto-approved by the system.

+

Auto-payment error

This notification asserts that an error occurred during invoice auto-payment. Because of this, auto-payment functionality is frozen and must be manually unlocked.

+ +

Invoice cannot be created because there are no corresponding xDRs

This notification asserts that invoice cannot be created because the corresponding xDRs were not found. +

Recalculation of invoices was finished

This notification informs whether the recalculation of invoices was finished successfully, with warnings or with errors. This message includes a list of invoice IDs which were not recalculated.

+

List of the invoices under review

This notification provides a list of invoices that are under administrator’s review.

+

Rerating complete

The notification informs that the xDR re-rating procedure has been completed. The message includes a list of xDRs processed.

+

Customer management Customer accounts closed

This notification reports that some customer accounts have been closed.

+

Accounts generation error, cannot fetch

This notification is produced because this customer was deleted by another administrator

+

Appendices


117

customer name during account batch generation.

Accounts generation error, cannot open file

The notification asserts that a report file used during account generation cannot be open.

+

Accounts generation error, cannot access directory

This notification reports that the directory used during account generation cannot be accessed due to permissions issues.

+

Accounts generation error, unknown customer

This notification asserts that the account batch cannot be generated because this customer is not found in PortaBilling. It is possible that the customer was terminated after the account generation procedure was scheduled.

+

Accounts generation error, cannot create directory

This notification asserts that the directory required for account generation does not exist and an attempt to create it failed.

+

Accounts generation error, cannot create a new batch

This notification asserts that batch generation failed. +

Accounts generation error, batch exists

This notification reports that the batch name the administrator is trying to use already exists.

+

Accounts generation error, exceeded generation attempts

This notification asserts that batch generation failed due to excessive number of generation attempts.

+

Accounts generation error, number of available account exceeded

This notification reports that the batch cannot be generated because the amount of available DID numbers in the selected DID batch has been exceeded.

+

Accounts generation finished

This notification confirms that the accounts have been successfully created.

+

Accounts generation error, cannot fetch

This notification asserts that the wrong product was selected to generate the account batch. For

+

Appendices


118

product name example, when the batch was being generated, the product was deleted by another administrator.

Spending plan limit exceeded

This notification alerts an administrator that a customer has outreached their spending limit.

+ +

Accounts generation error, batch control number overflow

This notification is sent to an administrator when the account generation procedure fails due to a batch control number overflow.

+

Spending plan limit ratio exceeded

This notification alerts an administrator that a customer has reached the warning threshold configured for their spending plan.

+ +

Platform management Task rejected This notification asserts that a

task from the TaskStack queue was rejected.

+ +

Alarm replication error

This notification asserts that a problem with replication of the main database was detected.

+ +

Adaptive routing penalty threshold reached

This notification reports that call quality for a particular route is below the specified acceptable level. The route is penalized and removed from its usual position in the routing list.

+ +

Adaptive routing warning threshold reached

This notification asserts that call quality for a particular route is below the specified warning threshold.

+ +

Payment processing error

This notification reports that an error occurred during payment processing via the payment processor.

+ +

User error report This notification is sent to an administrator when a user submits a report about an unsuccessful call via the web interface.

+

No currency This notification asserts that no + +

Appendices


119

exchange rate found

exchange rates were found for converting a different currency to the base currency.

Not defined base currency for environment

This notification reports that no base currency was defined for the environment.

+ +

Exchange rate actualizing error

This notification asserts that an error occurred while processing an exchange rate.

+ +

No wrapper configured for the LinkPoint online processor

This notification reports that the LinkPoint wrapper (LPERL) used for processing payments via the First data global gateway virtual terminal (formerly known as LinkPoint) was not configured.

+

No keyfile configured for the LinkPoint online processor

This notification reports that no keyfile for processing payments via the First data global gateway virtual terminal (formerly known as LinkPoint) was configured or that the pass to the keyfile is incorrect.

+ +

No temporary directory for the LinkPoint online processor

This notification reports that no temporary directory for processing payments via the First data global gateway virtual terminal (formerly known as LinkPoint) was configured or that the pass to this directory is incorrect.

+

No store name configured for LinkPoint online processor

This notification reports that the Store name option required for processing payments via the First data global gateway virtual terminal (formerly known as LinkPoint) was not configured in the porta-admin.conf file

+ +

No vendor configured for the PayflowPro online processor

This notification reports that the Merchant account vendor name option required for processing payments via PayflowPro online processor was not configured.

+ +

No partner configured for the PayflowPro

This notification reports that the Merchant account partner name option required for processing

+ +

Appendices


120

online processor payments via PayflowPro online processor was not configured.

Online payment processor configured improperly

This notification asserts that an online payment processor was not properly configured. + +

Balance mismatch detected

This notification is sent when a discrepancy between customer balance (an amount owed to the ITSP) and invoice amount due is detected.

+ +

Tax calculation errors

This notification asserts that tax calculation scheduled for a customer has failed.

+ +

Fraud prevention Account screened

This notification is sent when an account’s status is changed to screened. The notification includes information about the reason for account screening.

+ +

Suspicious destinations

This notification is sent to an administrator when the duration of calls to suspicious destinations reaches a threshold defined in the fraud traffic profile.

+

Customer's account: fraudulent activity detected

This notification alerts you that customer’s account attempted to use the service from an unusual location.

+

Account quarantined

This notification informs you that the account was quarantined because of suspicious activity.

+ +

Session unauthorized location

This notification alerts you that customer’s account attempted to use the service from an unauthorized IP address.

+ +

Service catalog management Product cloned successfully

This notification confirms that the product was successfully cloned.

+ +

Failed to clone product

This notification asserts that an attempt to clone the product failed.

+ +

Tariff cloned This notification confirms that + +

Appendices


121

successfully the tariff was successfully cloned.

Failed to clone tariff

This notification asserts that an attempt to clone the tariff failed. + +

Destinations were uploaded

This notification confirms that a destination upload has been completed and includes information on how many destinations were added, removed or ignored.

+

Destinations upload failed

This notification asserts that some update operations failed during destination upload. The file, including data that was not properly imported, is attached to this message.

+

Destination group set was uploaded

This notification confirms that a destination group set upload has been completed and includes information on how many prefixes were added, removed or ignored.

+

Destination group set upload failed

This notification asserts that some update operations failed during a destination group set upload. The file, including data that was not properly imported, is attached to this message.

+

Tariff upload failed

The notification informs that some update operations failed during tariff upload. The file including the data which has not been imported is attached to the message.

+

Tariff uploaded The notification informs that a tariff has been successfully uploaded. The message includes a summary about total rates processed.

+

Reapplying subscriptions for product

The notification informs that a product’s subscription has been reapplied. The message includes the number of affected accounts.

+

Accounts generation error,

This notification asserts that the account batch generation failed +

Appendices


122

invalid add-on products combination

because the provided add-on products combination cannot be used with the main product.

Reports Custom report This notification includes the

results of custom report execution.

+

Password recovery Web self-care password change

The notification is sent if a user changes their password on the web self-care interface. This message contains the new password.

+ +

Web password change link

The notification is sent when the “Password recovery” feature on the web self-care interface has been used. The message contains the reset password link.

+

Customer notifications

These notification messages are sent to a customer. You can configure them for a customer class.

Notification name Description Email SMS

Inventories management SIM cards upload

This notification informs that SIM cards upload procedure has been completed. The message contains a summary about total SIM cards processed.

+

Billing notifications Due date for invoice is approaching

This notification informs the customer that the due date for the invoice is approaching. This message contains a summary of account charges for the invoice.

+ +

Invoice is overdue

This notification alerts that the invoice is overdue. This message contains a summary of account charges for the invoice.

+ +

Customer is about to be suspended

This notification reports that a customer is about to be suspended because of an outstanding invoice.

+ +

Appendices


123

Customer was suspended

This notification asserts that a customer is suspended because of an unpaid invoice or insufficient funds.

+ +

Customer is going to be suspended again (no payment)

This notification asserts that a customer is suspended again because of an outstanding invoice. + +

Payment applied to the account

This notification reports that customer’s credit card is successfully charged. This message contains information about a current balance.

+ +

Invoice is generated

This notification reports that the invoice is generated. This message contains a summary of charges for the invoice and information about the current balance.

+ +

Balance adjustment

This notification reports that the balance is adjusted. This message contains information about the current balance.

+ +

Credit card is about to expire

This notification alerts that the credit card is about to expire. + +

Credit card expired

This notification reports that the credit card is expired. + +

Recalculation of invoices was finished

This notification reports that the recalculation of invoices is successfully completed.

+

Failed to re-generate the invoice, no invoice number or customer ID

This notification asserts that invoice re-generation failed because invoice number or customer ID was not identified. +

Failed to re-generate invoice

This notification asserts that the attempt to re-generate the invoice failed.

+

Invoice re-generated successfully

This notification reports that the invoice is regenerated successfully. +

Payment receipt

This notification contains the payment receipt. + +

Account periodic payment error

This notification reports a periodic error that occurs during payment. + +

Appendices


124

Invoice is voided

This notification reports that the invoice sent previously is voided. + +

Customer management Customer accounts closed

This notification reports that some customer accounts have been closed. +

Customer is about to be closed

This notification asserts that a customer is about to be closed. + +

Customer is closed

This notification reports that a customer has been closed. + +

Number porting complete

This notification reports that a customer’s number has been successfully ported in.

+ +

Accounts generation error, cannot fetch customer name

This notification is produced because this customer was deleted by administrator during account batch generation. +

Accounts generation error, cannot open file

The notification asserts that a report file used during account generation cannot be open. +

Accounts generation error, cannot access directory

This notification asserts that the directory used during account generation cannot be accessed due to permissions issues.

+

Accounts generation error, unknown customer

This notification asserts that the account batch cannot be generated because this customer is not found in PortaBilling. It is possible that the customer was terminated after the account generation procedure was scheduled.

+

Accounts generation error, cannot create directory

This notification asserts that the directory required for account generation does not exist and an attempt to create it failed.

+

Accounts generation error, cannot create a new batch

This notification asserts that batch generation failed.

+

Appendices


125

Accounts generation error, batch exists

This notification reports that the batch name the administrator is trying to use already exists. +

Accounts generation error, exceeded generation attempts

This notification asserts that batch generation failed due to excessive number of generation attempts. +

Accounts generation error, number of available account exceeded

This notification asserts that the batch cannot be generated because the amount of available DID numbers in the selected DID batch has been exceeded.

+

Accounts generation finished

This notification confirms that the accounts have been successfully created.

+

Accounts generation error, cannot fetch product name

This notification asserts that the wrong product was selected to generate the account batch. For example, when the batch was being generated, the product was deleted by another administrator.

+

Spending plan limit exceeded

This notification alerts a customer that a spending limit is reached. + +

Accounts generation error, batch control number overflow

This notification is sent when the account generation procedure fails due to a batch control number overflow. +

Spending plan limit ratio exceeded

This notification warns a customer that the threshold configured for their spending plan has been reached.

+ +

Platform management Payment processing error

This notification asserts that an error occurred during payment processing via the payment processor.

+ +

Fraud prevention

Appendices


126

Account screened

This notification is sent when an account’s status is changed to screened. The notification contains information about the reason for account screening.

+ +

Account: fraudulent activity detected

This notification alerts you that suspicious activity has been detected on behalf of your account. +

Customer's account: fraudulent activity detected

This notification alerts the customer that some account attempted to use the service from an unusual location. +

Account quarantined

This notification informs you that the account was quarantined because of suspicious activity.

+ +

Session unauthorized location

This notification alerts you that customer’s account attempted to use the service from an unauthorized IP address.

+ +

Service catalog management Product cloned successfully

This notification confirms that the product was successfully cloned. + +

Failed to clone product

This notification asserts that an attempt to clone the product failed. + +

Tariff cloned successfully

This notification confirms that the tariff was successfully cloned. + +

Failed to clone tariff

This notification asserts that an attempt to clone the tariff failed. + +

Failed to clone rates

This notification asserts that an attempt to clone the rates failed. + +

Tariff upload failed

The notification informs that some update operations failed during tariff upload. The file including the data which has not been imported is attached to the message.

+

Tariff uploaded

The notification informs that a tariff has been successfully uploaded. This message includes a summary about total rates processed.

+

Reapplying subscriptions for product

The notification informs that a product’s subscription has been reapplied. This message includes the number of affected accounts.

+

Appendices


127

Accounts generation error, invalid add-on products combination

This notification asserts that the account batch generation failed because the provided add-on products combination cannot be used with the main product.

+

Reports Custom report This notification includes the results

of custom report execution. +

Call statistics This notification includes the call statistics for a specific period. +

Password recovery Web self-care password change

The notification is sent if a customer changes their password on the web self-care interface. This message contains the new password.

+ +

Web password change link

The notification is sent when the “Password recovery” feature on the web self-care interface has been used. This message contains the reset password link.

+

Balance change Balance warning threshold crossed

This notification reports that the current credit limit is almost reached. + +

Credit limit exceeded

This notification asserts that the current balance reached its credit limit and service for the customer’s credit accounts is now blocked.

+ +

Volume discount threshold crossed

This notification is sent to customers to inform them that the discount threshold has been crossed and the discount no longer applies.

+ +

Volume discount threshold will be crossed soon

This notification is sent to customers to inform them that the volume of services consumed is approaching the discount threshold.

+ +

The service wallet expired

This notification reports that the unused balance of a service wallet is expired.

+ +

The service wallet is about to expire

This notification reports that the unused balance of a service wallet is about to expire.

+ +

Appendices


128

Units successfully transferred from sender's service wallet

This notification asserts that units have successfully transferred from sender’s service wallet. This message contains information about a current balance.

+ +

Units successfully transferred to recipient's service wallet

This notification asserts that units successfully transferred to recipient’s service wallet. This message contains information about a current balance.

+ +

Service wallet top up report

This notification includes a report about service wallet top ups and also information about a current balance.

+

The funds were transferred to the account balance

This notification reports that funds successfully transferred to the account balance. This message contains information about a current balance.

+ +

The funds were transferred from the account balance

This notification reports that funds successfully transferred from the account balance. This message contains information about a current balance.

+ +

The verification code for the transfer of funds

This notification contains the verification code for the transfer of funds. + +

The verification code for the transfer of service wallet content

This notification contains the verification code for the transfer of service wallet content. + +

portabilling: templates guide mr85...invoice templates contain such data as the period from date,...

Documents