7. Invoices and invoice templates

IMPORTANT: Invoice generation is deprecated since mr4.0+. Current invoice generation will damage billing records.

The sip:carrier allows to generate and send customer invoices for each billing period based on Calls Detailed Records (CDR). Generated invoices can be sent to customers emails using invoice generation script Section 7.3, “Invoices generation”.

Invoices present billing information from the reseller point of view. Recipients of the invoices are customers. Invoices include information related to the calls made by subscribers associated with the customer.

By default invoice contains information about billing plan fixed fee, calls zones fees and calls detailed information.

Content and vision of the invoices are customizable by invoice templates Section 7.2, “Invoice templates”.


	The sip:carrier generates invoices in pdf format.

7.1. Invoices management

Invoices can be requested for generation, searched, downloaded and deleted in the invoices interface.

Invoice management interface

To request invoice generation for the particular customer and period press "Create invoice" button. On the invoice creation form following parameters are available for selection:

Template: any of existent invoice template can be selected for the invoice generation.
Customer: owner of the billing account, recipient of the invoice.
Invoice period: billing period. Can be specified only as one calendar month. Calls with start time between first and last second of the period will be considered for the invoice

All form fields are mandatory.

Invoice creation form

Generated invoice can be downloaded as pdf file.

Invoice created view

To do it press button "Download" against invoice in the invoice management interface.

Respectively press on the button "Delete" to delete invoice.

7.2. Invoice templates

Invoice template defines structure and look of the generated invoices. The sip:carrier makes it possible to create some invoice templates. Multiple invoice templates can be used to send invoices to the different customers using different languages.


	At least one invoice template should be created to enable invoice generation. Each customer has to be associated to one of the existent invoice template, otherwise invoices will be not generated for this customer.

Customer can be linked to the invoice template in the customer interface.

7.2.1. Invoice Templates management

Invoice templates can be searched, created, edited and deleted in the invoice templates management interface.

Invoice templates management interface

Invoice template creation is separated on two steps:

Register new invoice template meta information.
Edit content (template itself) of the invoice template.

To register new invoice template press "Create Invoice Template" button.

On the invoice template meta information form following parameters can be specified:

Reseller: reseller who owns this invoice template. Please note, that it doesn’t mean that the template will be used for the reseller customers by default. After creation, invoice template still need to be linked to the reseller customers.
Name: unique invoice template name to differentiate invoice templates if there are some.
Type: currently sip:carrier supports only svg format of the invoice templates.

All form fields are mandatory.

Invoice template creation form

After registering new invoice template you can change invoice template structure in WYSIWYG SVG editor and preview result of the invoice generation based on the template.

7.2.2. Invoice Template content

Invoice template is a XML SVG source, which describes content, look and position of the text lines, images or other invoice template elements. The sip:carrier provides embedded WYSIWYG SVG editor svg-edit 2.6 to customize default template. The sip:carrier svg-edit has some changes in layers management, image edit, user interface, but this basic introduction still may be useful.

Template refers to the owner reseller contact ("rescontact"), customer contract ("customer"), customer contact ("custcontact"), billing profile ("billprof"), invoice ("invoice") data as variables in the "[%%]" mark-up with detailed information accessed as field name after point e.g. [%invoice.serial%]. During invoice generation all variables or other special tokens in the "[% %]" mark-ups will be replaced by their database values.

Press on "Show variables" button on invoice template content page to see full list of variables with the fields:

Invoice template available variables

You can add/change/remove embedded variables references directly in main svg-edit window. To edit text line in svg-edit main window double click on the text and place cursor on desired position in the text.

After implementation of the desired template changes, invoice template should be saved Section 7.2.3, “Save and preview invoice template content.”.

To return to the sip:carrier invoice template default content you can press on the "Discard changes" button.


	"Discard changes" operation can’t be undone.

7.2.2.1. Layers

Default template contains three groups elements (<g/>), which can be thinked of as pages, or in terms of svg-edit - layers. Layers are:

Background: special layer, which will be repeated as background for every other page of the invoice.
Summary: page with a invoice summary.
CallList: page with calls made in a invoice period. Is invisible by default.

To see all invoice template layers, press on "Layers" vertical sign on right side of the svg-edit interface:

Invoice template layers

Side panel with layers list will be shown.

Invoice template layers open

One of the layers is active, and its element can be edited in the main svg-edit window. Currently active layer’s name is bold in the layers list. The layers may be visible or invisible. Visible layers have "eye" icon left of their names in the layers list.

To make a layer active, click on its name in the layers list. If the layer was invisible, its elements became visible on activation. Thus you can see mixed elements of some layers, then you can switch off visibility of other layers by click on their "eye" icons. It is good idea to keep visibility of the "Background" layer on, so look of the generated page will be seen.

7.2.2.2. Edit SVG XML source

Sometimes it may be convenient to edit svg source directly and svg-edit makes it possible to do it. After press on the <svg> icon in the top left corner of the svg-edit interface:

Invoice xml source button

SVG XML source of the invoice template will be shown.

SVG source can be edited in place or just copy-pasted as usual text.


	Template keeps sizes and distances in pixels.

When edit svg xml source, please change very carefully and thinkfully things inside special comment mark-up "<!--{ }-→". Otherwise invoice generation may be broken. Please be sure that document structure repeats default invoice template: has the same groups (<g/>) elements on the top level, text inside special comments mark-up "<!--{ }-→" preserved or changed appropriately, svg xml structure is correct.

To save your changes in the svg xml source, first press "OK" button on the top left corner of the source page:

Save xml source changes

And then save invoice template changes Section 7.2.3, “Save and preview invoice template content.”.


	You can copy and keep the svg source of your template as a file on the disk before start experimenting with the template. Later you will be able to return to this version replacing svg source.

7.2.2.3. Change logo image

Make sure that "Select tool" is active.
Select default logo, clicking on the logo image.
Press "Change image" button, which should appear on the top toolbar.

Steps to change the image

After image uploaded save invoice template changes Section 7.2.3, “Save and preview invoice template content.”.

7.2.3. Save and preview invoice template content.

To save invoice template content changes press button "Save SVG".

Save invoice template

You will see message about successfully saved template. You can preview your invoice look in PDF format. Press on "Preview as PDF" button.

Preview invoice template

Invoice preview will be opened in the new window.


	Example fake data will be used for preview generation.

Preview invoice as PDF

7.3. Invoices generation

Except invoices generation on demand using web interface, invoices can be generated automatically for all customers using cron and invoice generator script.

Also invoice generation script is responsible for the sending generated invoices to the customers.

Script is located at: /usr/share/ngcp-panel/tools/generate_invoices.pl

In short:

To generate and immediately send invoices for the previous month:

perl /usr/share/ngcp-panel/tools/generate_invoice.pl --send --prevmonth

To generate invoices for the previous month without sending:

perl /usr/share/ngcp-panel-tools/generate_invoice.pl --prevmonth

To send already generated invoices for the previous month:

perl /usr/share/ngcp-panel/tools/generate_invoice.pl --sendonly --prevmonth

Regenerate invoices for the specified period:

perl /usr/share/ngcp-panel/tools/generate_invoice.pl --stime="2015-01-01 00:00:00"  --etime="2015-01-31 00:00:00" --regenerate

Some not obvious options:

*--allow_terminated* Generates invoices for the terminated contracts too.
*--force_unrated* Generate invoices despite unrated calls existence in the specified generation period.
*--no_empty* Skip invoices for the contracts without calls in the specified period and with null permanent fee for the billing profile.

To see all possible script options use --help or --man:

/usr/share/ngcp-panel/tools/generate_invoices.pl --man

Script will be run periodically as configured by the cron files. Cron files templates can be found at:

/etc/ngcp-config/templates/etc/cron.d/ngcp-invoice-gen.tt2
/etc/ngcp-config/templates/etc/cron.d/ngcp-invoice-gen.services

After applying your configuration cron file will be located at:

/etc/cron.d/ngcp-invoice-gen

Script uses configuration file located at: /etc/ngcp-invoice-gen/invoice-gen.conf

Except common DB connection configuration following specific options can be defined in the config file:

RESELLER_ID 1,2,3,…N

Comma separated resellers id. Invoice generation will be performed only for the specified resellers.

CLIENT_CONTRACT_ID 1,2,3,…N

Comma separated customers id. Invoice generation will be performed only for the specified customers.

STIME YYYY-mm-DD HH:MM:SS

Usually is not necessary. Script option --prevmonth will define correct start and end time for the previous month billing period. Generated invoices will include all calls with call start time more then STIME value and less the ETIME value.

ETIME YYYY-mm-DD HH:MM:SS

SEND [0|1]

Generated invoices will be immediately sent to the customers.

RESEND [0|1]

Invoices, already sent to the customers, will be sent again.

REGENERATE [0|1]

Already presented invoices files will be generated again. Otherwise they will stay intouched.

ALLOW_TERMINATED [0|1]

Generate invoices for the already terminated customers too.

ADMIN_EMAIL your@email.com

Purposed for notifications about invoices generation fails. Not in use now.

All generated invoices can be seen in the invoice management interface Section 7.1, “Invoices management”.

On request each invoice will be sent to the proper customer as e-mail with the invoice PDF in the attachment. Letter content is defined by the invoice email template.