This document contains text automatically extracted from a PDF or image file.

Formatting may have

been lost and not all text may have been recognized.
To remove this note, right-click and select "Delete table".
Chapter 5: Reports
CHAPTER 5: REPORTS
Development III in Microsoft Dynamics® AX 2009
Scenario
Arnie, the Accounts Receivable clerk, has requested a report that shows the
maximum, minimum and average invoice amounts per customer. Isaac, the
systems developer, has been asked to create this report and to ensure that the
report is printed with a title, date and page numbers on every page.
Architecture
Use reports to print information from the database. The report focuses on the
following:
• Fetching the data
• Filtering the data
• Sorting the data
• Aggregating the data
• Presenting the data in the correct layout
The figure illustrates the structure of the report as displayed in the Application
Object tree (AOT).
5-2
FIGURE 5.1 THE THREE SECTIONS OF A REPORT
The report consists of three main components in the AOT:
• General methods
• Data sources
• Designs
Microsoft Official Training Materials for Microsoft Dynamics ®
Your use of this content is subject to your current services agreement

Methods È Data Sources E Designs

Chapter 5: Reports
Methods
The general or system methods control the execution of the report. These
methods are frequently overridden to supplement or modify the standard
execution of a report. Variables defined in the class declaration of the report can
be accessed from all methods in the report and can be used to hold status and
general information about the report.
Data Sources
Reports are designed to use a query to fetch the data. This section of the report
contains the definition of the query. The structure is similar to the independent
queries in the AOT.
Default filtering ranges and sorting can be specified that the user can override, or
they can be locked to force specific criteria. There is no need to use a
QueryBuildRange object in the code to specify simple filtering, as there is with
forms.
Sorting can be specified as Order By or Group By in the Order mode property on
the data source. Specifying the Group By parameter on the data source enables
aggregating or summing of the fields in the tables. This is a common requirement
in reports. Specifying Sort by will mean that the report is sorted by the fields
specified in the Sorting node.
Design
The design of the report controls the layout and presentation of the data. There
can be many sections to a report design. Some sections are specific to a table, and
will be printed whenever a record in that table is sent. Other sections, for
example, headers and footers, only print in specific sections on the page. There
are also Programmable sections that will only be printed when specifically called
from code.
There can also be multiple designs in a report. This might be used, for example,
when there are different layouts required for an invoice in different companies.
The design to be used can be specified at run time with the reportRun.design()
method. For example in the fetch method you could add the following code:
if (VendParameters::find().UseInvoiceDesign1)
{
this.design(identifierStr(CompanyDesign1));
}
else
{
this.design(identifierStr(CompanyDesign2));
}
Microsoft Official Training Materials for Microsoft Dynamics ®
5-3
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2009
5-4
Handles to the Objects in a Report
When programming a report you can access the individual objects, for example
the data sources or controls of the report, using the kernel classes used to build
them, or by overriding the methods on the object itself.
All methods in the report are related to an object. This object can be accessed
from the methods associated with it, by using the handle “this”. Note this
reference is relative to where you are programming: for example, if you are
coding in a method attached to a control in the report design, then “this” refers to
the control. If you are coding in a report method, “this” refers to the report.
When referencing an object from a method that is not associated with that object,
you need to use the objects handle. The following table lists the objects and how
you can access them:
Object Access from X++
ReportRun Element
QueryRun queryRun
Query Query
Active record in data source <name of data source in the query>
ReportDesign Name assigned to design, when property
autodeclaration is set to Yes
or
ReportRun.design([<name of design>])
ReportAutoDesignSpecs ReportDesign.autoDesignSpecs()
ReportSectionGroup ReportDesign.SectionGroup
( < tableId >, [ <fieldId> ] )
ReportSection Name assigned to section, when property
autodeclaration is set to Yes
or
Auto design:
ReportAutoDesignSpecs.(<tableId>)
Generated design:
ReportSectionGroup.Section.
(<sectionType>)
Report……Control Name assigned to control, when property
autodeclaration is set to Yes
or
reportSection.control(<fieldId>)
PrinterJobSettings ReportRun.PrintJobSettings()
Microsoft Official Training Materials for Microsoft Dynamics ®
Your use of this content is subject to your current services agreement
Chapter 5: Reports
Data Sources
Report data sources are rarely modified from the code once a report is running.
The user normally requires a lot of flexibility and control over what data is
printed in the report. Reports are therefore created with default values for the data
sources ranges, sorting and grouping.
One data source can be joined to another by dragging the table to be used for the
joined data source to the data source node on the main data source. The join type
can then be specified using the JoinMode property on the joined data source.
Aggregated values can be added by grouping the data source appropriately and
specifying the fields to be aggregated in the Fields node.
Procedure: Using Aggregate Fields
This procedure shows the steps to create a report that lists the average invoice
amount per customer. through the use of aggregated functions.
1. Create a new report in the AOT. Rename the report.
2. Expand the new report node.
3. Expand the Data Sources node.
4. Expand the Query node.
5. Open another AOT window, find the CustInvoiceJour table.
6. Drag the CustInvoiceJour table to the Data Sources node.
7. Expand the new CustInvoiceJour_1 node.
8. Right-click on the Fields node and select properties.
9. Change the Dynamic property to No.
10. Expand the Fields node.
11. Highlight all fields listed under the node and press Delete.
12. Right-click the Fields node and select New > AVG.
13. Right-click on the new field created and select Properties.
14. Change the Field property to Invoice Amount.
15. Under the CustInvoiceJour_1 node, right-click on the Group By node
and select New Field.
16. Right-click on the new field and select Properties.
17. Change the Field property to OrderAccount.
18. Right-click on the Designs node and select New Report Design.
19. Expand the ReportDesign1 node.
20. Right-click on the AutoDesignSpecs node and select Generate Specs
From Query.
Microsoft Official Training Materials for Microsoft Dynamics ®
5-5
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2009
5-6
21. Right-click on the CustInvoiceJour_Body node and select New
Control > Field From CustInvoiceJour.
22. Drag the InvoiceAmount field from the window that is opened, to the
CustInvoiceJour_Body node.
23. Save and run the report.
Design
A report design can have one of two types of designs: an Auto Design or a
Generated Design. Both report design types can then have multiple sections used
to control how the report is displayed.
Auto and Generated Designs
The Auto Design specifies which fields to include in the report. The actual layout
is decided at runtime after the user has specified the sorting and subtotals. This
approach provides a flexible report where the user can control the break and sum
structure of the report. The disadvantage is that the system developer cannot
control the layout as it is generated at runtime.
Reports with an auto design can use templates that are evaluated at runtime. A
change in the template affects all reports using the template if they are using the
auto design approach.
The generated design specifies which fields to include and the specific layout of
the report. As the break and sum structure is specified by the system developer,
the end-user has less flexibility. The advantage is that the report is presented
exactly as specified and implemented by the system developer.
If both types of design exist, the Generated Design will be used.
Microsoft Official Training Materials for Microsoft Dynamics ®
Your use of this content is subject to your current services agreement
Chapter 5: Reports
List of Design Sections
The following table describes the different sections available in a report design.
Section Description
Prolog Appears at the beginning of a report. Use it to
display items such as a logo, a report title, or the
current date. The prolog is printed before the page
header on the first page of the report.
PageHeader Appears at the top of every page in a report.
Header Only available for generated designs. Appears at
the beginning of a new group of records. Use it to
display items such as a group name.
SectionGroup Only available for generated designs. Appears in
the middle of a report. A section group can contain
a Header, Body, or a Footer section. The structure
of data sources is reflected in the structure of the
section groups.
Footer Only available for generated designs. Appears at
the end of a group of records. Use it to display
items such as sub totals.
PageFooter Appears at the bottom of every page in a report.
Use it to display items such as page numbers.
Epilog Appears at the end of the report. Use it to display
items such as a logo. The epilog is printed just after
the page footer on the last page in a report.
ProgrammableSection Use programmable sections to add any kind of
customized information. To activate a
programmable section, activate it explicitly with an
element.execute(Number) statement. The Number
must be specified in the ControlNumber property
for the design section.
Properties of Report Elements
The Developer Help includes a full list of properties for the Design, Design
Sections and Controls of a report. You can view these lists by opening the
Developer Help, then in the Contents tab expand Microsoft Dynamics AX
SDK > Reference > Object Properties, and then select the appropriate page to
view.
Microsoft Official Training Materials for Microsoft Dynamics ®
5-7
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2009
Lab 5.1 - Add Header and Footer Sections
Scenario
The report created in Procedure: Using Aggregate Fields needs to have a header
that contains the company name, the date the report was run, the page number,
and a caption. It also requires the company logo to be printed in the bottom right
corner of every page.
Challenge Yourself!
The required header is the standard header used in the report templates. Select a
template for the design that will add this header. Add a footer section and a
bitmap control to display an image file. Set the properties to ensure it displays in
the correct place at a reasonable size.
Step by Step
1. Expand the node in the AOT of the report created in the previous
procedure.
2. Expand the Design node.
3. Right-click on the ReportDesign1 node and select Properties.
4. Change the ReportTemplate property to InternalList.
5. Change the Caption Property to “Average Customer Invoice
Amount”.
6. Expand the ReportDesign1 node.
7. Right-click on the AutoDesignSpecs node and select New > Page
Footer.
8. Right-click on the PageFooter node and select New Control >
Bitmap.
9. Right-click on the Bitmap control and select Properties
10. Set the ImageName property to a file name of an image file to be
displayed as the logo.
11. Set the ResizeBitmap property to Yes
12. Set the Height and Width properties to 3 char and 5 char
respectively. Adjust these values to ensure the image still looks
correct.
13. Set the Left property to Auto (right).
5-8
Microsoft Official Training Materials for Microsoft Dynamics ®
Your use of this content is subject to your current services agreement
Chapter 5: Reports
Methods
One of the key requirements when running reports is for the report to be as
flexible as possible when it comes to allowing the user to select data and display
it as required. When running a simple report that uses the report query, the user
can filter by any field, add related tables to filter based on data in those tables,
sort and group by any field and show or hide sub-totals based on the groupings
created.
Many reports require the developer to control the fetch and display of data a little
more, depending on the complexity of the report. There may also be a
requirement to prompt the user for information that cannot be entered using the
query tool. An example is the customer aging report, where the user is prompted
for information such as the As Of Date, the Aging Buckets to be used, whether to
use the transaction date or the due date on which to base the aging, and many
other criteria. The user can limit the report by customer account, or any other
field on the customer table, but the calculations that are shown are based on the
customer transaction table.
This is done by overriding system methods in the report. For example, to prompt
the user for more information, the dialog() method is overridden, and a dialog
object is created with the necessary fields. To calculate the data, the Fetch
method is overridden and the results from the query retrieved to find which
customers to calculate the amounts for are used.
In this report there are many other methods created that are used for controlling
the layout of the report and displaying the data. You can add display methods
here as with forms, that can be used on fields in the report.
Common Methods to Override
ReportRun.Init
This method initializes the report and its objects. This method is the first event
you can override with the startup of the report.
Never remove the super() call from this method, as this removes the initialization
of all the objects.
To make some manual initialization, it is typically put in this method. This could
include the following tasks:
• Verification of the contents of the args-object received
• Initialization of supporting classes
• Dynamically changes to the design
If manipulation needs access to the objects of the report, wait until the super()
call has been executed.
Microsoft Official Training Materials for Microsoft Dynamics ®
5-9
Your use of this content is subject to your current services agreement
Development III in Microsoft Dynamics® AX 2009
5-10
ReportRun.Dialog
The dialog method is used as with the dialog method in the RunBase class
framework. The method should instantiate an object of type Dialog, add dialog
fields and field groups as required, and return the Dialog object. The values from
the dialog can be retrieved by creating a new method in the report called
GetFromDialog. This is not a system method so is not overridden, but the
ReportRun class checks to see if a method with this name exists and then calls it
if it does.
Note that the dialog method is not called when the report is run directly from the
report node in the AOT. For the dialog method to be called, the report must be
called from a menu point.
ReportRun.Fetch
The fetch method is responsible for the following tasks:
• Initialize the QueryRun
• Prompt for the query
• Prompt for the printer settings
• Fetch the data
• Send the data
The following example in X++ illustrates the standard contents of fetch:
boolean fetch()
{
queryRun = new QueryRun(this);
;
while (queryRun.next())
{
salesTable = queryRun.get(tableNum(salesTable));
this.send(salesTable);
}
return true;
}
If you chose to override fetch, remove the call to super(). Then you are
responsible to re-implement the parts of the example as needed.
Fetch is typically overridden in the following situations:
• The report is not based on a query
• The report contains some processing of the fetched data
• The report is based on a temporary table
Microsoft Official Training Materials for Microsoft Dynamics ®
Your use of this content is subject to your current services agreement