Invoice Template Configuration
- Mahnoor Khan (Deactivated)
- Micah Gallant
- Greg Walsh
Summary
This article details the configuration options available when adding invoice templates to EngageIP for use.
Template Configuration Fields and Definitions
Below is an example of an invoice template configuration. You can access the Template by loading the Setup page and clicking on Invoice Templates.
For each include option below there is a similarly named token which is associated and holds the data involved. Make sure to review your template to determine which items are actually in the template and therefore in use vs. the options selected in the template configuration but not in use. Enabled options add to the size of the rendered XML which will increase overall system load and take up unnecessary space in the database.
Name - this is the name of the template which will show up under Bill Groups when selecting the template to apply to accounts
Include CDR/UDR Details - if selected this will include all usage records billed for the invoices in the invoice xml for display on the invoice
Include CDR Summaries - if selected this will include summary information for usage records associated to the generated invoice
Include Owner CDR /UDR Summaries - if selected this will include Owner usage record summaries on the invoice (only used when billing at the owner level)
Exclude Reversals - if selected this will not push reversal transactions or credits to the invoice as they cancel each other out. Note: that the credit and reversal need to be on the same invoice otherwise it will still show the reversed credit since the original credit would be on another invoice and potentially delivered to the customer already
Include Resource Info - if you have resources and you are using the appropriate tokens in the template, this will pass the data along to the template
Invoice Template - this is the text area box where you actually paste in the template. Its best to copy and paste into notepad or some similar text editor for editing rather then editing within the text box
Include Zero Dollar CDR /UDR - if selected this will include usage records rated at zero dollars. If you have a large amount of zero rated calls, you may wish simply to not show them
Include Country Category Summary - If selected this shows the summary of Country and Category calls
Include Country Category Summary By Parent - if selected this shows the summary of Country and Category calls broken out by parent
Include Country Category Direction Summary - if selected this shows the summary of Country and Category calls broken out by direction
Include Country Category Direction Summary By Parent - if selected this shows the summary of Country and Category calls broken out by direction and further by parent account
Include Usage Summary
Include Pooled Minute Bucket Summary - if selected, this will show a summary of pooled minute buckets per account
Include Minute Bucket Summary - if selected this will show a summary of minute buckets (pooled or unpooled) per account
Include Minute Bucket Summary By Parent - if selected this will show a summary of minute buckets per account broken out by parent account
Include CDR /UDR Summary - if selected this will sum up all usage and show total counts of CDRs
Include CDR /UDR Summary By Parent - if selected this will sum up all usage and show total counts of CDRs and will be broken out by parent
Include CDR /UDR Summary By Invoice And Category - if selected this will sum up all usage and show total counts of CDRs and will be broken out by Category
Include CDR /UDR Summary By Invoice And Country - if selected this will sum up all usage and show total counts of CDRs and will be broken out by Country
Include CDR /UDR Summary By Invoice And User - if selected this will sum up all usage and show total counts of CDRs and will be broken out by User (not parent)
Include CDR /UDR Summary By Invoice And User And Parent - if selected this will sum up all usage and show total counts of CDRs and will be broken out by Parent and then User
Include Package Summary By Sub Account
Include Aged Invoice Detail - this will include XML detail related to all paste invoices in regard to how they are aged. This includes balances, payments, credits, how much each is overdue etc.
Include User Extended Attributes - this will include data related to the users in the User Extended Attributes on the account for use or display on the invoice
Include User Package Extended Attributes - this will include data if existing from User Package Extended Attributes for use or display on the invoice
Include Aged Invoice Detail
Include Credit Tax Details
Include Ticket Transaction Summary
Include Item By Invoice Group And Package Group
Include Tax Details
Include Invoice Service Group
Include Invoice Service Group Recurring
Include Invoice Service Group Recurring And Prorate
Include Invoice Service Group Non Recurring
Include Package Group Recurring
Include Package Group Recurring By Amount
Include Package Group Recurring And Prorate
Include Package Group Recurring And Prorate Invoice Period
Include Package Group Recurring And Prorate Invoice Period By Amount
Include Package Group Non Recurring
Include Package Group User Recurring And Prorate Invoice Period
Include Package Group User Recurring And Prorate Invoice Period By Amount
Include Package Group User Non Recurring
Include Invoice Service Group Recurring And Prorate With Invoice Period
Include Invoice Service Group Non Recurring With Invoice Date
Include User Package Extended Attribute
Include User Extended Attribute Include Resource Info
Available Invoice Tokens & Custom Invoice Tokens
For information on finding the available tokens in your EngageIP system and creating custom invoice tokens see the Invoice Template Design Overview article.
Custom tokens make use of existing database tables or views in the database or based on custom views that are created to show specific information.
Once a custom token is created and associated to an invoice template, any invoices generated using that template will include the data from the custom token in the XML that is generated. That data in the XML can then be called out in the XSLT template for display or calculations on the invoice itself
To add a custom invoice token:
Go to Setup tab
Click link ‘Custom Invoice Token’
Click ‘Add’
Type Name of custom token, this will reflect on your invoice template configuration page
Enter the table name OR the view name that the data is coming from
Select the invoice identifier - this tells the system to return data specific to InvoiceID or UserID
Click Save
To add a custom token to an invoice template:
Go to Setup tab
Click ‘Invoice Template’ link
Click the link of the template you wish to add the custom token to
Scroll to the bottom section named ‘Custom invoice Token’
Click Add
Locate and add the token you just created
To use the data from the custom token do this:
Go to an invoice that makes use of the template that was updated
Open and Close the invoice to generate the XML and reload the data which will now include the new token data
Update the template itself to make use of the new XML data as needed
Render the invoice on the customer again to reflect the updated template changes
To view the XML data to confirm the data exists that you need, go to the account, check the box beside an invoice that was opened / closed, and click ‘XML’ button. Open the file in Notepad to see all the data that can be extracted or used on the invoice template.
Invoice Optimization
How to optimize your configuration for for database space efficiency and overall system speed
To optimize the speed of billing, rendering and viewing and to save space in the database, consider which items you want to actually send to the invoice and what items should be visible to the customer.
For example, if you are not showing CDR/UDR Details, then you can un-check that item so that the system does not include that as part of the data of the invoice (whether you're displaying it or not). What you can do is open your template and match up the tokens in use in the HTML portion (top of the file) to the names of the check boxes.
As an example of matching the boxes to tokens, the check box labeled 'Include Country Category Summary' will show in your template as a token called 'CountryCategorySummary'. If you do not see that one in your template, then you are safe to uncheck that box.
Once you are done unselecting the options you think you don't need, render an invoice again (by going to the account, clicking invoices, clicking the date of the invoice you want to render, click save without updating the date value, then load the invoice again).
If the invoice is missing data that you need visible, it means that you unchecked one of the tokens that your are using on the invoice. To remedy that, go to the configuration and review the template again, check the box beside the item you require and follow the above to render the invoice again to confirm it's displaying as needed.
Invoice Example Sections
The below shows (in order of appearance):
Include Minute Bucket Summary
Include Country Category Summary
Include CDR /UDR Summary By Invoice And Country
Include CDR /UDR Summary By Invoice And User
The below shows:
Include CDR /UDR Summary By Invoice And User And Parent
Below includes:
Include CDR /UDR Summary By Parent
Below includes:
CDR /UDR Summary By Minute Bucket Pool
Configuration for Receipt Printing
Enter a template under Setup/Branding to enable receipt printing
Install the receipt printer driver on the appropriate computers
Notice: the name of the printer must include the word "Receipt". If no installed printers contain this word then receipt printing will not be available. If multiple printers contain the word the first one found will be used (the order is not predictable)Go to AdminPortal and log in
Configure the browser to allow unsigned ActiveX controls. Under Tools/Internet Options click the Security tab and click the "Custom Level" button. Set the "Download unsigned ActiveX Controls" to "Prompt" and save the changes
Go to the Transactions page
Click the security notification message at the top of the browser window
Click "Install ActiveX Control..."
When the security warning dialog comes up click the Install button
When it finishes installing the Receipt button should be available on the Payments list
You can use "Tools/Manage Add-ons..." to verify that the ReceiptPrinterControl was correctly installed
Troubleshooting
Errors On Invoice Template Save
You do not have a correctly formatted HTML document
Check for missing tags (particularly closing tags). Fully review to confirm the template is up to HTML standards
For EngageIP 8.5.22.0 or earlier: ensure the host's IIS App pool set to .Net 2.0 instead of .Net 4.x. Having the App pool set to 4 may cause reference errors as well