The data model is actually the most important phase in report development, because if you get it wrong or if you have to make fundamental changes to it, it usually means you will have to redo the layout. So, take your time to think about the data model thoroughly.

This means that you have to know what information is required in the layout and where it is from. Are you going to use one or more tables? Is the same information available in different tables, in that case, which one are you going to use?

Make a list of all the tables that contain the information and then decide which ones you are going to use. In real life, this probably means you will have to consult an expert or a business user and explain that the information they require resides in multiple tables, so they can make an informed decision as to which table you should use in the report.

Once you have defined which tables you are going to use, you will need to think about the relations between the tables, how you are going to link the tables, and also in what order? The order will have an influence on the performance of the report, but also on the kind of information that might be missing.

For example, if you are asked to create a report to display inventory by location, the questions you should ask are:

The answers to these questions will define which tables and fields you are going to include in the data model and in which order you are going to iterate over them.

A good suggestion is to have a requirements session with the user, during which you can create a mock-up of the report. Then you can define each field, column, grouping, sorting and printing option. Based on this session, you can then create the data model for the report. This mock-up is also referred to as a format design document.

Although the data model is important for the reasons I just explained, the layout of the report determines how the user will perceive it. So, if the layout is not easy to interpret, or if you can't see the wood from the trees, however cleverly you construct the data model, the report is not going to be used.

There are many out of the box reports in the Dynamics NAV application and most of them are never used. One of the reasons is that they have an inadequate layout.

How do I visualize the information such that the report clearly reveals its intention and the user quickly finds what he or she is looking for? That's the most important question to ask when creating the layout.

Creating a report is not difficult, but making it easy to understand, so that you can spot trends and learn from your data, takes some consideration. The main goal of a report is to communicate information clearly and effectively, for example, graphically. A report needs to create insights by communicating its key points in an intuitive way.

Using the example of the inventory by location report, you might consider how you are going to visualise the inventory. Are you going to display a number, or a data bar? Is it important to include a key performance indicator, for example compare the current inventory with the reorder point (or some other important value)? Or are we using items with an expiry date? If so, do items close to expiry need a different color? Then, in what order are you going to display the locations and items?

Testing is a phase that is often neglected, for different reasons. The most frequent excuse for the lack of tests is not having enough time. That might actually be true when you are developing the report, but, in the end, when users complain about bugs and missing functionality, you will wish you had tested more thoroughly.

Of course, this needs to be specified in your report's design document. Its test criteria should mention which formats the report needs to be tested in.

Another reason tests are usually dismissed or poorly carried out is a lack of understanding of the business case. How is the user going to use the report? Is all the information on there, and is it correct? As a developer in the NAV world, you have to put yourself in the shoes of the user. Only then will you truly understand if what you developed is ready or not.

Tests should include export into different formats (PDF, EXCEL, WORD) and actually printing the report on a printer. Test it on different clients: Windows, web, and tablet.

Using the example of the inventory by location report, a test verifies if the inventory is correct and corresponds to the inventory on the item card. Are there any locations or items missing from the report?

You use Report Dataset Designer in the Microsoft Dynamics NAV Development Environment to define the dataset of a report. This is how you open it:

There are two types of report layouts: client report definition (RDLC) layouts and Word layouts. To create an RDLC layout, you use Visual Studio Report Designer or Report Builder from the Microsoft Dynamics NAV Development Environment.

The RDLC layout is the most flexible. By this, I mean that, from a technical point of view, you have the ability to use expressions to determine how and when data should be visualized. The Word layout is restrictive and imposes limitations on the way you create the dataset.

In this chapter, I will focus on the RDLC layout. The Word layout is explained in Chapter 8, Word Report Layouts.

In this section, I will explain how to use the report dataset designer to create a data model for your report.

Building the dataset is an important process because it determines where and how the data becomes available in the runtime dataset and so will have an impact on how you design the layout.

Data items and columns – fields, variables, and expressions

You design the dataset in the Report Dataset Designer, based on data items and columns. Data items link to tables in the database and columns link to fields or expressions:

A column can be a field in a table, but it can also be an expression, a variable or a text constant.

Let's start with an example and create an item list report. The idea is to display a list of items, so I will use the Item table as my data item and I will add the number, description and inventory as columns.

In the dataset designer, add a Data Type DataItem and Data Source Item line, then use the field menu button to select the fields from the Item table:

The Field Menu allows you to select any of the data item fields and add them to the report without having to type in the Name of the field.

Note

In the Field Menu window, select one or more fields that you want to add to the report dataset. Select multiple fields by holding down the Shift key or the Ctrl key. Choose the OK button to add the selected fields to the dataset.

All names in the Name column must be unique and Common Language Specification (CLS) compliant. You will notice that, when using the Field Menu, the field name consists of the field name, an underscore, and the data item name.

Note

More information about the Common Language Specification is available in the MSDN Library at https://msdn.microsoft.com/en-us/library/12a7a7h3.aspx.

After you have selected the data items and columns you want to add in the dataset, open the properties window. Here you can set the data item and field properties.

Use Shift + F4 or the property button at the top to open the properties. When you select a data item or a field, the property window displays the properties of the selected data item or field. When you go to the last line in the dataset designer, referred to as the first empty line, the property window displays the report properties.

The following image shows the properties of a data item and of a field:

You can also include a variable in the report dataset. Define the variable in C/AL Globals and then add it by typing in its name or using the assist-edit button in the data source column where you can select it from the C/AL Symbol Menu:

Note

An example of this report is available in the object: Packt - CH01-1

A column can also be the result of an expression, here are some examples:

• FORMAT(TODAY,0,4)
• Item.Description + '-' + Item.No_
• STRSUBSTNO(DocumentCaption,CopyText)
• -("Line Amount" - "Inv. Discount Amount" - "Amount Including VAT")

You are not only going to display data in the report layout but also field names and textual information. These names and text will be displayed in the user's own language, since Dynamics NAV is a multilanguage application. You can therefore use captions and labels when you design the dataset. Captions and labels are sent as parameters to the report layout. They are not actually included in the dataset, because their value is the same for every record and we don't want this information to repeat because that would increase the size of the dataset unnecessarily.

To include a caption:

Alternatively, use the IncludeCaption checkbox in the report dataset designer:

If you select a row that contains an expression or a variable, then you will get the following error when you activate the IncludeCaption property for that row:

You can only use the IncludeCaption property on table fields. For other fields, you can define a label.

To include a label:

Alternatively, you can use the assist-edit button to open the label Multilanguage Editor:

IncludeCaption versus FIELDCAPTION

Captions are sent as parameters and in the language of the user. In some cases, for example in document reports, you may want the captions to be in the language of the recipient, not in the language of the user. To do that, you use the FIELDCAPTION function, and add the caption to the dataset as an extra column. Then, you can determine the language via C/AL code.

Note

Keep in mind that adding captions to the dataset with FIELDCAPTION increases the size of the dataset, so only do this when it is really necessary. In previous versions of Dynamics NAV, captions were added by default in the dataset, so using IncludeCaption and labels is a performance improvement.

An example of the use of FIELDCAPTION can be found in most document reports:

• Sales: Quote
• Order: Confirmation
• Sales: Invoice
• Sales: Credit Memo
• Sales: Shipment

Examples of the FIELDCAPTION function are shown in the following screenshot:

How is the dataset flattened?

At runtime, a report dataset consists of rows and columns. If you only have one data item, then the columns in the dataset designer become the columns of the runtime dataset and the rows from the data item (or table) become the rows in the dataset. In this situation, the runtime dataset looks the same as when you simply run the table.

If you combine multiple data items, then the data items at design time can be indented, or not, and this results in a different dataset at runtime. Since the runtime dataset is two dimensional, consisting of rows and columns, information is repeated over multiple rows.

In this section, I will explain and demonstrate how the runtime, flat, dataset is generated, using indented or non-indented data items.

Using multiple data items in a report is a common pattern in most reports and understanding how the multi-data-item dataset at design time is converted into the flat two-dimensional dataset at runtime is very important. Understanding this process is, in my opinion, the most important part of RDLC report development, because it determines how you build the layout and which filters you need to apply in the RDLC layout.

Unrelated tables or multiple data items, without indentation

As an example, let's start with a dataset that consists of two data items, Vendor and Customer:

When we run this report and display the dataset with the About This Report feature, it shows this:

In the dataset there is a column for every column in the report dataset designer: No_Vendor, Name_Vendor, No_Customer, Name_Customer.

When the report processes the data items it starts with the first one (on top), which is Vendor. For all vendors, it fetches their No and Name and adds it to the dataset. The customer columns remain empty. Then, after the Vendor data item has been completely processed, the system starts with the Customer data item and does the same. The result sets of the two data items then follow each other in the dataset, stuck together.

Now imagine that I need to create a request page for this report to include an option to display details. Then, I would create a variable HideDetails, add it to the request page, and also add it to the dataset. If I added this variable to the dataset as an extra column, then we would have a problem. Are we going to add it to the Customer or Vendor data item? If we add it to the customer data item, it will be available at runtime, but not in the vendor rows. Now, as this is a variable that contains a constant value, we only need it once and there's no point in repeating its value on every row, because that would increase the size of the dataset and so decrease performance.

The solution is to include an extra data item that will only add one row to the dataset. To do this, you can use the integer table, as shown in the following screenshot:

Then the dataset becomes this:

The integer data item adds one row at the end of the dataset and this contains the value of the HideDetails variable.

Note

The expression SORTING(Number) WHERE(Number=CONST(1)) in the DataItemTableView property of the Integer data item makes sure that the outer data item produces exactly one row from the Integer table.

Use the following expression to retrieve this value in the layout of the report:

=Last(Fields!HideDetails.Value, "DataSet_Result")

Unless you add the integer data item as the first data item in the report dataset designer, the row is added to the beginning and the expression becomes this:

=First(Fields!HideDetails.Value, "DataSet_Result")

Remember that we have an extra row in the dataset containing our variable HideDetails. This row should be filtered out in the tables in the layout that display the Vendors and Customers.

Note

An example of this report is available in the object: Packt - CH01-2

Using an integer data item, and filtering it to add one or more rows in the dataset, is a common pattern in report design. Instead of filtering on a constant value, you can also set the filter on the integer data item via the C/AL code in the integer data item OnPreDataItem trigger. In that way, you can set it at runtime, depending on an option in the request page. In document reports, this is usually how the NoOfCopies option is implemented. I will come back to this pattern in the Chapter 5, Document Reports.

Related tables or multiple data items with indentation

Let's create a report with a dataset that contains two data items as an example: Customer and Customer Ledger Entry.

Note

In document reports, this pattern is applied a lot, because, in a document report, we have many data items that need to be visualized in different tables (or sections) of the report.

The Customer Ledger Entry needs to be linked to the Customer, so for each customer we can see their individual entries. Linking data items is done by indenting them in the report dataset designer and then, in the indented data item setting, the link fields in the property DataItemLink, as follows:

Then, when you run the report, the dataset becomes:

Customers that don't have ledger entries are shown, but the ledger entry columns are empty. Customers that have ledger entries are shown and, for every ledger entry, there's a row in the resulting dataset.

As you can see, if a customer has multiple ledger entries, then, for every ledger, a row is added to the dataset and the columns for the customers are repeated on each of these rows. This is called the flattening of the dataset, the columns of the parent record are repeated for every child record.

To filter out customers that don't have ledger entries, you can use the PrintOnlyIfDetail property. You need to set this on the top data item, in this example, the Customer:

The property PrintOnlyIfDetails specifies whether to print data in a report for the parent data item when the child data item does not generate any output. If there are more than two data items, then the report iterates through each parent child relationship in the same way.

Note

An example of this report is available in the object: Packt - CH01-3

If you are going to create a layout for this dataset and you want to see the ledger entries per customer, you do this by creating a group in the table and grouping on Customer No.

This is a very common design for the datasets in Dynamics NAV reports. It is used with header and line tables, master and ledger tables, and also in document reports.

Tip

If you omit the DataItemLink and DataItemLinkReference between the Customer and Customer Ledger Entry table, which effectively disconnects the two tables, then the resulting dataset is much larger, since it includes all possible combinations of headers and lines, with absolutely no regard to their possible table relations.

When using multiple data items with indentation, you can also apply the technique of including an integer data item. In that case, investigate the resulting dataset before you create the report layout because, depending on the result, you might want to move the integer data item to the top or bottom to get a better dataset.

A report, like other objects in Dynamics NAV, contains triggers. These triggers are fired when specific events happen and allow you, as a developer, to have code executed at those moments. In this section, I will explain the different triggers and in what order they are fired.

What happens when a report runs?

When you run any report, the OnInitReport trigger is called first. This trigger performs any processing that is necessary before the report is run, and so before any data is read, and before the request page is shown to the user.

Next, the request page for the report is run, if it is defined. Here, you select the options that you want for this report.

If you decide to continue, the OnPreReport trigger is called. At this point, no data has yet been processed. You can use this trigger to initialize variables or fetch information from the database via C/AL code. The Company Information table is usually queried in this trigger to retrieve company information like the name, VAT number, company logo, and so on.

When the OnPreReport trigger has been executed, the first data item is processed. When the first data item has been processed, the next data item, if there is any, is processed in the same way.

When there are no more data items, the OnPostReport trigger is called to do any necessary post-processing.

The following is a visual representation of the report execution flow:

In the Dynamics NAV development environment you can set the Use Report Builder option, via Tools/Options. If set to No, then the system will use Visual Studio to create the report layout, otherwise Report Builder will be used.

Report Builder is (normally) installed together with Dynamics NAV when you install the development environment. Visual Studio has to be installed separately. Report Builder is free and can be downloaded from the Microsoft website. To be able to create report layouts with Visual Studio in Dynamics NAV 2013, you need at least the Professional edition of Visual Studio, which is not free.

As from Dynamics NAV 2015 you can use the Visual Studio Community Edition 2013, which is free and can be downloaded from https://www.visualstudio.com/en-us/news/vs2013-community-vs.aspx.

In this section, we are going to use Report Builder to create a report layout. Make sure you set the option Use Report Builder to Yes.

I will start with the report Packt - CH01-1, which contains a data item for the integer table, and I will create a simple layout to display an item list.

From the report dataset designer, click on View, Layout to open Report Builder:

Wizards for prototyping

Report Builder contains wizards to help you to create a report layout. Let's use them to create our item list.

1. In the Insert tab in the ribbon, click on Insert, then Table, and then Table Wizard.
2. In the Choose a Dataset window select Dataset_Result and click on Next.
3. In the Arrange fields window you can now see the columns on the left. You can drag them to the right and put them into Values, Column Groups and/or Row groups. Let's drag the fields into Values:
   
4. For the inventory, click on the little arrow and select Sum. Click on Next.
5. In the Choose the Layout window, you can select grouping and totaling options, but only if you added a row and/or column group in the previous window. Click on Next.
6. In the Choose a Style window, you can select a style template. Click on Finish.
7. The wizard has ended and it has added a table to the body of the report:
   

Now, we are going to save and test the layout.

In Report Builder, click on the Save button (or Ctrl + S). Then close report builder. If you forget to save it, Report Builder displays the following message:

As you can deduce from this message, Dynamics NAV has generated a report.rdlc file and opened it in Report Builder. Then, we made changes to it, via the wizard. Now, it's asking us to save our modifications. This report.rdlc file will then be imported back into the report dataset designer. This happens when you click on a line in the report dataset designer:

Click on Yes (if you click on No the changes are not imported and will be lost.) After you click on Yes, the system will parse the report.rdlc file for errors. Some errors will be detected at this stage. Now you need to save the layout in the report object in the Dynamics NAV database. Click on File, Save (or Ctrl + S). When you save it, with the compile option checked, the system will parse the complete report and some errors might be detected.

Now run the report via File, Run (or Ctrl + R). The request page opens. Click on Preview:

To further enhance the report layout, you can reopen it via View, Layout.

Note

You don't have to close Report Builder if you know in advance the layout is not ready and you only want to test or preview it. In that case, save the layout in Report Builder and minimize Report Builder, don't close it. Then, click on a data item to import the layout, confirm and save, and run the report. If you need to make more changes to the layout, simply return to Report Builder, make your changes and follow the same steps to import your changes back into the report dataset designer.

It's very easy to create a simple layout using the wizards in Report Builder. I use it a lot for prototyping. You can then further enhance the report layout in Visual Studio.

In this section we are going to use Visual Studio to create a report layout. Make sure you set the option Use Report Builder to No.

I will start with the Item List report I created with Report Builder, but first, I will remove that layout by setting the processingonly property to yes. The following message is displayed:

After confirming and deleting the current layout, don't forget to set the property back to No.

Next, click on View, Layout to open Visual Studio:

In Visual Studio you can see similar sections to those in Report Builder.

To create a table layout, I will use the Toolbox. To open the Toolbox click on View, Toolbox:

Here, I will drag the table onto the report body. Alternatively, right-click in the report body and select Insert, Table:

To populate the table I will use the captions on the first row, which is the header row, and I will use the value fields from the dataset. From the parameters, drag the parameter into the textbox on the header row. Then, in the corresponding textbox on the detail row, click on the drop-down box to select the value:

There are many other ways of doing this, but I find this the easiest. Otherwise sometimes Visual Studio might create extra columns.

Repeat this process for all the columns. Then select the first row via its handle and make it bold. Next, we need to save our layout in Visual Studio, minimize it, and then go back into the report dataset designer and import it into the report object, just like we did with Report Builder. Then you can save and run the report to see the result.

Report formatting, toolbars, and document outline

In Visual Studio, you can change the layout of the report designer. You can move around the report data, properties and other sections. You can enable and disable toolbars, and so on. It's much more flexible than the report builder.

There is also the Format menu:

This menu contains many formatting options. They are especially useful when you need to align textboxes, for example in a document report.

There's also the Solution Explorer:

It contains the complete solution. Be careful, because only the report.rdlc file is imported into the report object. Any changes to the other items in the Solution Explorer are not saved. One advantage is that we can add extra template reports in the Solution Explorer. These templates can contain tables, lists, and matrices which you can pre-format and then copy and paste into your report layout. I will explain later how you can create and include these templates.

I would like to point out that there is a big difference between what you see and experience when you print an enhanced report onscreen and what you see and expect, when you actually print it on paper, or export it to Excel, Word or PDF.

When you run a report in the report viewer then it is fully functional. What I mean by this is that all interactive features the report contains are available to the end user. An enhanced report can, for example, contain hyperlink actions, expand/collapse functionality, drilldowns, and so on. When the user prints the report on paper, that interactivity is lost. If the main usage of a report is to print it, as document reports usually are, then don't spend much time adding interactivity to the report, because it will almost never be used and so will not be a very good return on investment.

Apart from the functional reasons online reports are better than printed reports, there's also the financial aspect. By using online reports, you will spend less on paper, ink, storage, binding, and distribution.

The ability of RDLC to export a report to PDF and/or Excel can help, but you must also remember that not all of the interactive features will still work in PDF and/or Excel. For example, drill down is available in Excel, but not in the PDF format.

Microsoft has published design guidelines you can follow when you create a layout for a report. This is especially important when you develop document and list reports. By following these guidelines, you can make sure that your reports are:

Applying these guidelines has the advantage that you can use a minimum set of rules, by using the default formatting options available in Visual Studio. You can also create report layout templates that you can apply by report type so that all your reports have a standard look and feel and give a consistent user experience.

Microsoft followed these guidelines, in some reports, when they developed the report layouts in Dynamics NAV 2013. In most implementations of Dynamics NAV, document reports are customized and this process can be time-consuming. The idea was to provide layouts that could be used out of the box in real life. I will leave it up to you to decide if this is true.