Updating Custom Report Layouts by Using Upgrade Codeunits

You can update custom report layouts by creating upgrade codeunits to handle changes in report datasets that affect the report layouts. Upgrade codeunits enable you to programmatically update multiple custom report layouts in the database to changes in report datasets. Although report layout updates can be done from the Microsoft Dynamics NAV client, there are certain changes to the dataset that require the user to manually modify report layouts before they can be used. These types of changes include, for example, deleted fields or field name conflicts as a result of renaming. Upgrade codeunits enable you handle these breaking changes to report datasets and layouts without requiring end-user interaction.

To design the report upgrade logic in an upgrade codeunit, you add C/AL code that implements the report upgrade API (through .NET Framework interoperability) and a set of functions that are available in codeunit 9651Document Report Mgt.. In the Microsoft Dynamics NAV application, codeunit 9651Document Report Mgt. is the main component for running and maintaining customized report layouts.

For general information about upgrade codeunits, see Upgrade Codeunits.

Report Upgrade API Overview

The upgrade and maintenance of report layouts in the databases is controlled by the following .NET Framework assemblies on the Microsoft Dynamics NAV Server:

• Microsoft.Dynamics.Nav.DocumentReport.dll

• Microsoft.Dynamics.Nav.Types.Report.dll

Microsoft.Dynamics.Nav.Types.Report Assembly

The Microsoft.Dynamics.Nav.Types.Report assembly contains the following types that you can use to for programmed report layout upgrades in upgrade codeunits.

DeleteAction Enumeration

The DeleteAction enumeration determines how content controls for fields (data items and columns of the report's dataset) in a report layout are deleted. The following table describes the members of the DeleteAction enumeration:

IReportUpgradeSet Interface

The IReportUpgradeSet interface provides an interface to the object that stores all changes that must be applied to a specific report layout in the current database.

Properties

The following table describes the properties of the IReportUpgradeSet interface.

Methods

The following table describes the methods of the IReportUpgradeSet interface. You use the methods to specify whether to delete or modify the content controls for data items and columns (fields) in a report layout. The behavior is controlled by the DeleteAction enumeration parameter.

All methods with matching names and paths will overwrite existing change definitions in the collection for the same item.

Parameters

The following table describes the parameters of the IReportUpgradeSet interface methods.

Microsoft.Dynamics.Nav.DocumentReport Assembly

The Microsoft.Dynamics.Nav.DocumentReport assembly contains several types for creating and managing report layouts. With regards to upgrading report layouts, only the ReportUpgradeCollection class is relevant.

ReportUpgradeCollection Class

The ReportUpgradeCollection class stores sets of changes that have been calculated or specified for reports in the current database.

The ReportUpgradeCollection class has only the AddReport method. This method adds a new report to the upgrade collection.

public IReportUpgradeSet AddReport(int reportId)

This method instantiates a new object for the report ID that is specified by the reportId parameter. If the report already exists in the collection, the existing object will be returned.

Custom Report Layout Upgrade Example

This example illustrates how you can update custom report layouts to dataset changes by using C/AL code, the report update API, and upgrade codeunits. This example will update a custom report layouts for report ID 1306 Mini Sales - Invoice. The following table describes the changes to the report dataset and how to the handle the updates in the custom report layouts:

To create the upgrade codeunit

1. Create a codeunit and set the SubType Property (Codeunit) to Upgrade.

2. Create a new local function called UpgradeReportLayout, and then do the following:

   • Define a parameter that has the name TestMode and datatype Boolean.

   • Define the following variables:

     Name	DataType	SubType
     ReportUpgradeSet	DotNet	Microsoft.Dynamics.Nav.Types.Report.IReportUpgradeSet.'Microsoft.Dynamics.Nav.Types.Report, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'
     ReportUpgradeCollection	DotNet	Microsoft.Dynamics.Nav.DocumentReport.ReportUpgradeCollection.'Microsoft.Dynamics.Nav.DocumentReport, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'
     DeleteAction	DotNet	Microsoft.Dynamics.Nav.Types.Report.ReportChangeOptions+DeleteAction.'Microsoft.Dynamics.Nav.Types.Report, Version=8.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'
     DocumentReportMgt	Codeunit	Document Report Mgt.

3. Add the following code to the UpgradeReportLayout function.

   // Instantiate the ReportUpgradeCollection variable
   ReportUpgradeCollection := ReportUpgradeCollection.ReportUpgradeCollection;
   // Calculate the set of changes for all layouts in the current database
   DocumentReportMgt.CalculateUpgradeChangeSet(ReportUpgradeCollection);
   // Example code snippet for applying a "breaking" change to a report design.
   // The example uses report 1306 Mini Sales - Invoice.
   ReportUpgradeSet := ReportUpgradeCollection.AddReport(1306);
   IF NOT ISNULL(ReportUpgradeSet) THEN BEGIN
     // Delete the text content control for the CompanyIBAN column and replace with empty text string)
     ReportUpgradeSet.DeleteField('CompanyIBAN',
                                  '/Header',
                                  DeleteAction.DeleteContent,
                                  '');
     // Delete the text content control for the UnitPrice and replace the control with the text Deleted.
     ReportUpgradeSet.DeleteField('UnitPrice',
                                  '/Header/Line',
                                  DeleteAction.ReplaceWithText,
                                  'Deleted');
     // Delete the control containing the field.
     ReportUpgradeSet.DeleteField('Quantity_ShipmentLine',
                                  '/Header/Line/ShipmentLine',
                                  DeleteAction.DeleteNode,
                                  '');
     // Rename the VariantCode_AssemblyLine field
     ReportUpgradeSet.ChangeField('VariantCode_AssemblyLine',
                                  'VariantCode_NewAssemblyLine',
                                  '/Header/Line/AssemblyLine',
                                  '/Header/Line/AssemblyLine');
   END;
   // Apply the upgrade steps to the report layouts
   DocumentReportMgt.ApplyUpgradeToReports(ReportUpgradeCollection,TestMode);
   

   The UpgradeReportLayout function instantiates a report upgrade collection object and calculates the change set based on the current report dataset designs and the XML documents that are stored with the custom report layouts in the application database. Then, it adds additional changes to the custom report layouts for report 1306, including deleting fields and renaming a field.

   Finally, the DocumentReportMgt.ApplyUpgradeToReports method applies all the updates to report layouts in the current database. If the TestMode parameter is True, the layout changes are only tested and will not be committed to the database.

4. Add a function called TestLaypoutUpgrade and set the FunctionType Property (Upgrade Codeunits) to CheckPrecondition. Add the following code:

   UpgradeReportLayout(FALSE);
   

   The defines a CheckPrecondition function type, which is the first function that is executed when the codeunit is run. This function will test the report layout changes before they are applied to the layouts in the database. If an error occurs when this function is run, then the changes are not applied.

5. Add a function called RunLayoutUpgrade and set the FunctionType Property (Upgrade Codeunits) to UpgradePerDatabase. Add the following code:

   UpgradeReportLayout(TRUE);
   

   This function is run after the CheckPrecondition function to perform the upgrade the report layouts.

6. Save and compile the codeunit.

7. Perform a data upgrade to run the upgrade codunit.

   Open development environment as an administrator. On the Tools menu, choose Data Upgrade, and then choose Start and follow the instructions.

   Note

   You can also perform the data upgrade by running the Start-NavDataUpgrade cmdlet from the Microsoft Dynamics NAV 2016 Administration Shell.

See Also

Concepts

Updating Report Layouts to Dataset Changes
Designing Word Report Layouts
Designing RDLC Report Layouts