Create custom invoice and receipt layouts using RDL

 

Invoices and receipts in FBO One can be fully customized. The default fixed layout can be replaced with a custom report.

See the instructions at the bottom of this page on how to replace the default layout with a customized report. To get started, a sample invoice report is available in FBO One under the Menu | Administration | Reports under the sample "Sample RDL layout".

How to customize the layout

For a general introduction, see the FBO One RDL reports tutorial video.

The invoice report is bound to the following data providers or datasets (when viewed from the Report Builder):

For a proper invoice display, data from each dataset is used accordingly in different sections of the RDL template. 

The display modes of the invoice report are:

  • in case of a invoice with multiple orders, there is a front sheet that summarizes the invoice and displays the grand total and amount due. This front page is followed by the receipt of each order.
  • in case of a invoice with a single order, the front sheet is not displayed anymore and the receipt page is displayed as the overall invoice (to change this follow this instructions)

 

The image below gives a better visual perspective on how and where the datasets are put to use:

 

The invoice template has two sections:

  • invoice cover page (grey background)
  • order receipts (yellow background)

The receipt section is made using a Tablix that displays each receipt on a separate page.If you want to display a front page on a single-order invoice, toggle the RowVisibility expression of the rectangle that contains all controls of the cover-page. By default this expression hides the cover-page if the invoice only has a single order.  Note that the RDL report ignores the Administration Single page invoice flag. 


Invoice section (gray background)
 

Upper right corner (orange)

This section only contains invoice related information found within the Invoice line dataset.

Each row of the used Tablix has the RowVisibility property set, so that in case the data needed to be displayed is empty, then the entire row is hidden.

Batched orders (orange)

The lines depicting the batched orders are displayed in a Tablix bound to the Invoice line dataset.

Each order is displayed on a separate row along with related information like description, amount, vat and so on.

Total and VAT (yellow)

The VAT and Grand total information is displayed within a separate Tablix bound to the Invoice VAT subtotal line dataset.

The Total excluding VAT and Total VAT values along with the Grand total value and the charged currency are displayed within the Tablix itself, but outside of the group with the repetitive state, therefor being displayed only once.

The VAT's and their values are displayed within the Tablix group appearing therefor each on different a row.

Alternative currency (brown)

The section responsible for displaying the total values and VAT values broken down to the alternative currency defined in the administration section, uses a Tablix bound to the Invoice alternative currency line dataset.

In case no alternative currency is defined (or the values are entered using the currency defined as being the alternative currency) then this section will be hidden. 

The display mode is very similar to the one in the "Total and VAT" mentioned above.

The code visible in the attached image above is responsible for checking if the used dataset doesn't contain any rows (information) or if the information found within the dataset is empty (this is done by verifying if one of the relevant information to be displayed like the GrandTotalFormatted value is empty or not)

Payments (green)

The payments section Tablix is bound to the Receipt payment line dataset. This section is also shown only if the dataset contains information or the contained information is not empty.

The payment section displays all payments for all the batched orders.

Form of payment (red)

Because the form of payment related information is found within the Invoice line dataset, the Tablix used in this section is bound to this dataset. This section is also shown only if the contained information within the dataset related to form of payment is not empty.


Receipt section (yellow background)

 

Upper right corner (red)

This section only contains order related information found within the Receipt line dataset.

Each row of the used Tablix has the RowVisibility property set, so that in case the data needed to be displayed is empty, then the entire row is hidden.

Receipt lines (red)

The receipt lines are displayed in a Tablix bound to the Receipt line dataset.

Each order line is displayed on a separate row along with related information like quantity, amount, vat and so on.

Total and VAT (blue)

The VAT and Grand total information is displayed within a textbox, that stands at design time as a replacement for the subreport. At runtime the textbox is replaced by a subreport which contains a Tablix bound to the Receipt VAT subtotal line dataset.

The Total excluding VAT and Total VAT values along with the Grand total value and the charged currency are displayed within the Tablix itself, but outside of the group with the repetitive state, therefor being displayed only once.

The VAT's and their values are displayed within the Tablix group appearing therefor each on different a row.

Alternative currency (purple)

The section responsible for displaying the total values and VAT values broken down to the alternative currency defined in the administration section, uses a textbox, that stands at design time as a replacement for the subreport. At runtime the textbox is replaced by a subreport which contains a Tablix bound to the Receipt alternative currency line dataset.

In case no alternative currency is defined (or the values are entered using the currency defined as being the alternative currency) then this section will be hidden. 

The display mode is very similar to the one in the "Total and VAT" mentioned above.

The code visible in the attached image above is responsible for checking if the used dataset doesn't contain any rows (information) or if the information found within the dataset is empty (this is done by verifying if one of the relevant information to be displayed like the GrandTotalFormatted value is empty or not)

Payments (green)

The payments section Tablix is bound to the Receipt payment line dataset. This section is also shown only if the dataset contains information or the contained information is not empty.

Form of payment (red)

Because the form of payment related information is found within the Receipt line dataset, the Tablix used in this section is bound to this dataset. This section is also shown only if the contained information within the dataset related to form of payment is not empty.

Limitations

Because the receipt section is within another Tablix cell (it's nested), all the information is displayed related to a particular order from the invoice and due to this consideration RDL offers some restrictions.

One of the restrictions imposed by RDL is that nested Tablixes must use the same dataset as the parent Tablix, reason for which displaying values for the VAT section, the payment section and alternative currency section is done with subreports.

Subreports are separate RDL templates/files that include only that particular section.

The receipt section contains 3 different subreports:

Each of these files can be downloaded/uploaded by using the template documents section in the FboOne administration area:

Subreports state and load process

Instead of using subreport controls provided by the Report Builder, subreports are depicted in the "Invoice and Receipt RDL report" as usual textboxes. Reason for this is that FboOne makes use of its own template documents section (mentioned above), instead of using other report servers (that would only create a bigger overhead on how to use/alter the receipt/invoice report).

Subreports are therefor loaded into the final report at runtime, by searching through all uploaded template documents for each subreport.

Because subreports are depicted as textboxes and only uploaded at runtime, running the report in the Report Builder will only display the textboxes instead of the actual subreport. 

Subreports naming convention

All components (tablix, textbox, label etc) are given each a proper name so that tracking any element within the RDL template is therefor simplified.

The same approach goes for subreports an their depiction as textboxes that are going to be replaced at runtime with proper subreport components.

In order to be indentified as subreport replacements, the textboxes must use the following naming convention:

Subreport_<SubreportTemplateDocumentFileName>

Example:

Each textbox having the "Subreport_" as a prefix in their name will be considered to be subreports that need to be loaded at runtime. The search for the appropriate subreport template is done automatically by looking for the uploaded template document named as the text specified after the "Subreport_" prefix.

If no subreport template is found in the list of uploaded template documents, a error message will be displayed and the report generation is aborted.

Subreport parameters

In order to functionally link the subreports to the main report parameters are needed.

Because at design time the subreports are depicted as textboxes, the needed parameters must be added using the "Custom Properties" property of the textbox.

The custom property names must match the parameter names within the subreport.

Example:

Main report

Subreport


Previewing and Activating custom Invoice layouts

By default, the RDL sample invoice layout is hidden from users. To activate the RDL layout, it's access permissions need to be updated in MENU | Administration | Reporting | Report access.

This makes the new layout available as a report in the invoice details page :

This way, the report can be previewed and compared easily with the default "Invoice as PDF" layout.

Once the RDL-based report is final, it must be activated for generating the actual invoices. It will then be used by the "Invoice as PDF" command, and it will then also be used when sending invoices by email. 

To activate an RDL-based invoice layout, assign it to the backoffice administration, under Menu | Administration | Administrations. Edit the administration, and select the layout in the Invoice Report dropdown.

Similarly, RDL receipt layouts can be set in the Menu | Fbo Locations editor, in the Receipt Report drop down value.


The above steps can be executed in one go by running the below script. Paste the script into the Script Runner, under MENU | Administration | Api add-ins | Script Runner.

using System;
using System.Linq;
using FboOne.Client;
using FboOne.ServiceModel;

public class Script
{
  public void Main()
  {
    var s = new FboOne.Scripts.ReceiptInvoice.RdlReceiptInvoiceSetup();
    s.SetAsDefaultReports();
  }
}

To revert back to the fixed layout reports, run the below script:

using System;
using System.Linq;
using FboOne.Client;
using FboOne.ServiceModel;

public class Script
{
  public void Main()
  {
    var s = new FboOne.Scripts.ReceiptInvoice.RdlReceiptInvoiceSetup();
    s.RestoreToActiveReports();
  }
}

 

Enable multi page invoice for single order invoice

By default the invoice RDL template displays a single page in case of invoices containing a single order.

In order to always display the front sheet that summarizes the invoice and displays the grand total and amount due, regardless the number of orders the invoice/batch invoice contains the following steps must be taken:

  • download the "Invoice and Receipt RDL-report" template document 
  • open it with Report Builder, click on the blue background that represents the report itself and then on the button that enables the code behind editing
  • once done a popup will appear showing the code used through out the RDL template
  • the IsSinglePageInvoice() function is the one that needs altering as shown below
  • once done run it in Report Builder to make sure it works properly and no error message are shown and uploaded back to FboOne template documents

Code for single page invoices: 

Function IsSinglePageInvoice(numberOfInvoiceLineRows As Integer) As Boolean
   If numberOfInvoiceLineRows = 1 Then
	Return True
   Else
	Return False
   End if
End Function

Code that enables to always display the  front sheet that summarizes the invoice and displays the grand total and amount due 

Function IsSinglePageInvoice(numberOfInvoiceLineRows As Integer) As Boolean
	Return False
End Function


Summary section settings

Both invoice and receipt sections contain each a summary textbox displaying additional notes/information with regards to the invoice or receipt.

Entering line breaks in the summary information setting will force the RDL template to also display line breaks at rendering time:

Result:

 

Subreport error handling

Subreports, as well as the main report, are fully customizable. This can lead to users wanting to customize their receipts and/or invoices and also to situations in which errors might occur due to typos, misspellings or even bad build expressions.

For example the ReceiptVatSubtotalSubreport is being altered and a mistype slips into the expression:

If saved and uploaded back into FboOne template documents, upon generating a new receipt a particular error message is being displayed.

This error message does not describe the error itself, but the final effect it has on the generated report:

In case you encounter this error message instead of the expected subreport section check if:

  • subreport file is uploaded and displayed in the template documents list in Administration | Reporting | Template documents
  • subreport name matches the textbox name in the main report (see image below)
  • any error occur at compile time in Report Builder (note: try to successfully run the report in Report Builder before saving it and uploading it to template documents)


See also:

Invoice report

Invoice queries

Receipt queries

Create custom receipt layout using RDL

 

Download: sample invoice RDL template from here: InvoiceAndReceipt.rdl