Invoice Template Design Overview

Summary

The purpose of this document is to outline the possible uses and configurations of invoices within EngageIP. Depending on the internal business processes and requirements for your organization, these guidelines may or may not apply. It is recommended that you review and consider the requirements for each action and the associated business function. This document is meant to be a guideline and not a complete system configuration. Additional or more advanced configuration may be necessary depending on your business process.

As each organization’s requirement for invoicing is unique, depending on the types of packages your organization is selling the customers you are selling to and the geographic locations of your customers, a range of invoice formats can be designed. Therefore prior to the design of your company’s invoice within EngageIP it is recommended that your organization considers what your customers would like to see on the invoice, how it ought to be designed to maximize branding as well as the potential opportunity to add revenue streams that could be generated from invoices.

Invoice Design Guideline

EngageIP allows for multiple Invoices to be created and attached to various Bill Groups which are then attached to users/accounts. Invoices can be designed to accommodate a range of layouts and functions that includes layouts specific to a type of package, a particular behavior, as well as for various languages.

Due to the fact that all billing data is dumped to an XML file, XSL is used for formatting. It is recommended that you have a working knowledge of HTML and CSS in order to design them accurately. Depending on how sophisticated your organization’s invoicing needs are EngageIP is able to accommodate basic to more detailed requirements.

How Invoices Can be Used

The Bill Group associated with the user/account determines the Invoice template used to generate the invoice the account will receive when billing runs. Since the system supports multiple Bill Groups, a range of invoices can be designed to associate one Bill Group with one invoice or multiple Bill Groups with a single invoice and vice versa.

Invoices can be designed for a range of reasons including:

• specific behavior such as advance bill days or specific bill days

• hardcopy, email or a combination or both

• specific packages, e.g. VoIP, Usage

• different languages

Bill Groups & Invoice Behavior

It is recommended that the name of the Bill Group reflect the type of behavior as well as the associated invoice. For example, Advance Bill Group, Hardcopy Bill Group etc. If your organization wants to bill using different invoices with specific behaviors, make sure that the name of the bill group clearly identifies the associated behavior, e.g. Advanced Billing + Email Invoice. This will allow for easier reference if your organization uses multiple invoice templates or bill groups.

For details on the fields above see the Bill Group Configuration article

Email & Hardcopy Invoices

Since the standard practice for invoicing is the use of email, it is the preferred method that organizations should consider when re-designing their business processes and invoice design. For this reason, email is used extensively throughout the system with the emailing of invoices a central and vital way for organizations to easily gain broad efficiencies.

A hardcopy, otherwise known as paper invoice is still a going concern in the world of billing. For this reason, hardcopy is also an option to deliver invoices. Since organizations are increasingly moving away from hardcopies, package options reflecting a paper charge per month, are becoming popular for companies to cover costs, where regulations permit.

The Default Invoice Delivery Type defines how the invoice should be sent, this is found on the Invoice Configuration page, see: the Invoice Configuration article for details.

Presenting Specific Packages Differently on Invoices

In some cases, companies would like to differentiate between the layouts of invoices as they relate to particular packages. A common reason to do this is in regards to VoIP usage where one customer may want to see more detailed calling information and another may chose not to.

By designing an invoice to show specific data whether for VoIP or another package, and by selecting specific XSL template fields, particular parameters can be reflected on an invoice.

Languages

Besides being able to handle multiple Bill Groups, support for invoices in multiple languages is also possible. The invoice template needs to be designed in the language that your organization wants to send the invoice in and it would then be associated with the appropriate bill group. In some instances organizations are positioning invoices in multiple languages as a value-added service, while others have a requirement to issue multiple language invoices to support a multilingual customer base. Under the category of value-added invoice, an additional per month package charge can be associated with the language invoice.

Invoice Design Requirements

Invoice templates are designed in XSL which converts the XML data into a readable and formatted design to be viewed with your browser. Based on the design layout for a particular invoice, the XML structure and the chosen XSL template fields chosen, the invoice layout and invoice details can vary in design, content and layout.

The next section of this document will walk you through designing your invoice templates.

Although the invoice templates are created using XSL to convert the XML document into HTML this document is not intended to provide a working knowledge of XSL but rather to providing you with a working knowledge of how to create and format your invoice templates to be used within EngageIP. Once you’ve created the template as outlined you can then add it to the invoice template section of the system and assign it to the appropriate Bill Group. Each account associated with the chosen Bill Group will receive then receive the appropriate invoice.

Before we begin, let us first define what are XSL and XML.

XSL

XSL (EXtensible Stylesheet Language) is a standard from the W3C for describing a style sheet for XML documents. It is the XML counterpart to the Cascading Style Sheets (CSS) in HTML and is compatible with CSS2. XSL is made up of three components:

1. XSL Transformations (XSLT) is the processing language for XSL. It is used to convert XML documents into HTML or other document types and may be used independently of XSL

2. XML Path Language (Xpath) is used to identify and select tagged elements within an XML document

3. XSL Formatting Objects (XSL FO) provides the format vocabulary

XML

XML (EXtensible Markup Language) An open standard for describing data from the W3C. It is used for defining data elements on a Web page and business-to-business documents. XML uses a similar tag structure as HTML; however, whereas HTML defines how elements are displayed, XML defines what those elements contain. While HTML uses predefined tags, XML allows tags to be defined by the developer of the page. Thus, virtually any data items, such as "product," "sales rep" and "amount due," can be identified, allowing Web pages to function like database records. By providing a common method for identifying data, XML supports business-to-business transactions and has become "the" format for electronic data interchange and Web services.

Unlike HTML, which uses a rather loose coding style and which is tolerant of coding errors, XML pages have to be "well formed," which means they must comply with rigid rules. The following are examples of XML and HTML tags. Note that the XML statements define data content, whereas the HTML lines deal with fonts and display

Tip: having trouble saving templates because of the validation? Use this xml validation service to quickly find the tags or data causing the issue: http://www.w3schools.com/xml/xml_validator.asp

XML defines "what it is," and HTML defines "how it looks."

Now that you have a basic understanding of what the differences are let us now look at the steps necessary to format and create an invoice template to be used within the system.

Modifying a Sample XSL Invoice

In order to begin modifying the default XSL or creating a new XSL file that will be used it is important to point out a few things:

1. Unlike HTML, each tag must be closed within the XSL file in order for it to render properly

2. The structure of the XSL file must be as outlined below in the XSL Structure section

3. HTML Escape Characters are used instead of traditional special characters

4. An understanding of applying and matching XSL Templates is required

XSL TAGS

XSL Structure

If you have worked with HTML before the structure of an XSL file will look very familiar with just a few minor changes as illustrated below.

The code illustration below outlines the start of an invoice template. In this case all that has been added so far is the company logo, address information and basic invoice properties such as the account, invoice number and date invoice was created.

Let us now look at the code and explain the XSL flow by matching the numbered list below with the code line in the image.

[1] – Represents the type of file and transform method, in this case XSL. This line is usually created by your HTML or XSL editor.
[2] – This XSL template must be present. It instructs the EngageIP Billing application to retrieve values from within the “Invoice” infrastructure.
[3-36] – Basic HTML document code structure.

• Begins your HTML document

• Contains information about your page such as the TITLE, Meta tags, STYLE tags, etc.

• Closes the HTML

[37] – Closed the XSL Template tag in line 2
[38-46] – Matches XSL Templates and displays the output
[47-49] – Additional tags needed to properly close and render the invoice. These do not change and should be inserted as illustrated within the image.

Now that we have a basic understanding of the document structure let us look at how the XSL Templates are inserted into the document, how matches are made, and option on displaying the result.

Sample Invoice

Applying Templates

Whenever you would like to return a value to display on the invoice you will have to insert the following tag to call the appropriate information.

List of available field names can be found in the Available XSL Template Fields in the tables at the bottom of this article. Examples of how these are inserted can be see in the illustration above on lines; [5] [23] [27] and [31].

Matching Templates

The following XSL tags determine how values are displayed.

1. Returning a XSL Template field value within the code illustration a XSL Template was applied to return the InvoiceNumber (lines 5 and 27). The following example will match the template (indicated within the parentheses) on the first line. The second line will display the value as indicated by the period within the parentheses at the location it appears within the code

2. Matching a XSL Template and Calling Additional Templates certain values within the database or XML structure have been grouped to allow for increased flexibility and seamless modifications. In order to return a value from within a group you must instruct the application to first locate the group and then specify which values from within it to return. In the following example, we are instructing the application to first match on InvoceGroup and then return the values for Account and Item

3. Matching a XSL Template and displaying the result using HTML and formatting Alternatively if you would like to reduce the amount of formatting or STYLES that are applied within the tags you have the option to include HTML code within the XSL Template matches as illustrated below

Note: unlike HTML where special characters can be inserted into the document and be displayed properly, XSL requires that proper HTML Escape Characters be used as illustrated below where the traditional space ( ) value was replaced with  

For a list of HTML codes, characters and symbols, check the following link: http://www.ascii.cl/htmlcodes.htm

To see a list of the available tokens see the Developer Documentation article: https://developer.logisense.com/invoice-template-design/

XSL Template Fields

The tables below are separated from the above as they represent predefined groups.

To apply the XSL Template for each group, insert the XSL code at the top of the table, then call the sub-values from within it.

For example, using the table below if you wanted to display the Payment Detail of a payment made on the account the following XSL code would be added in the xsl:template section

<xsl:apply-templates select="Payments/Payment/PaymentDetail"/>

In order to match on Payment Detail which is contained within Payments>Payment the following code would be used.

<xsl:template match="Payments/Payment/PaymentDetail">
<xsl:value-of select="." />
</xsl:template>