Template data fields

Table 1-1 – Examples of number formats.

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).
• AM/PM – a.m. or p.m. indicator.
• MI – minutes.
  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.

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:

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.

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

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.

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.

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.

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

Table 1-4 – Output value type for other format 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 that 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:

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

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.

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