Report Programming Model

Important

This content is archived and is not being updated. For the latest documentation, see Microsoft Dynamics 365 product documentation. For the latest release plans, see Dynamics 365 and Microsoft Power Platform release plans.

Microsoft Dynamics AX reports are built on the concepts of the Model View Controller (MVC) pattern. The report programming model provides APIs to define concepts like the SrsReportRunController class, SrsReportDataContract class, and SrsReportDataContractUIBuilder class.

Overview of concepts

The following table describes the concepts for the report programming model.

Concept

Class

Description

When to override

Report data provider (RDP) contract

Object

A contract used to specify parameters in an RDP class.

Every RDP class that requires input parameters is associated with a contract. Nested contracts are supported by RDP contracts.

Report definition language (RDL) contract

SrsReportRdlDataContract

A framework contract used for query-based, data method–based, and OLAP-based reports, and for reports that contain static parameters created in a report. This contract provides a weakly typed representation of parameters. It contains methods that can be used to get or set values. It also contains a map of parameter names and the SRSReportParameter class.

Override when you must do the following:

  • Add custom validation to parameters. Call super before you validate.

  • Add custom initialization to your parameters.

  • Add your own UI builder for the parameters.

Use the SrsReportNameAttribute attribute on the overridden class to specify which report uses this contract, and to bind the contract to the report. Use this attribute for reports that bind to a query or data method to tie the contract to the report.

Print contract

SRSPrintDestinationSettings

A contract that contains all the relevant contracts after a report RDL is parsed. This contract contains an instance of the RDP contract, RDL contract, print contract, and query contract.

Do not override.

Query contract

No direct class.

A map that contains the parameter name and query object

A contract that provides the query contracts that are used in the report.

Do not override.

Report contract

SrsReportDataContract

A contract that contains all the relevant contracts after a report RDL is parsed. This contract contains an instance of the RDP contract, RDL contract, print contract, and query contract.

Do not override.

Controller

SrsReportRunController

The controller of the Model View Controller (MVC) pattern. Given the report name, the controller does the following:

  • Call SrsReportRunInterface to parse RDL.

  • Get the report contracts.

  • Create the necessary UI builders and invoke them.

  • Call validate on contracts. Validation occurs on the server through a service call.

  • Save to the SysLastValue table.

  • After the form is displayed, and the user clicks OK, run the report.

Override when you must do the following:

  • Change the contract before you run it. For example, to change the query based on parameters in the form, override the modifyReportContract method.

  • React to form control events. In this case, override the method, and provide the override events.

  • Add basic validation that is not part of the contract, or not at the table level. In this case, override the validate method, and call the super method.

  • Change the name of the report that is being run based on a parameter. In this case, override the modifyReportContract method, and set parmReportName.

  • Modify the company or culture. In this case, override the modifyReportContract method, and set the company and culture on SrsReportRdlDataContract.

Group and order

You specify the group and order as follows:

  • If you are using an RDP class, specify them on the contract or in Visual Studio.

  • If you are using a query or data method, specify them by using report designer.

  • If you are using a mix of an RDP class, query, and data method, specify them by using Visual Studio.

In Visual Studio, you can create groups and orders, and preview them in Visual Studio and the Microsoft Dynamics AX client.

UI Builders

SrsReportDataContractUIBuilder

SysOperationAutomaticUIBuilder

UI builders do the following

  • Lay out the fields on the contract.

  • Transfer data from a field to the contract, and bind fields to contract members.

The group and order are specified in the contract in the Visual Studio designer.

The SrsReportDataContractUIBuilder class provides the capability to show the date effective tab and valid values that are specified in the report.

The SysOperationAutomaticUIBuilder class provided by the SysOperation framework renders the UI for a given data contract.

Override when you must do the following:

  • Provide additional grouping or ordering. For example, you can provide radio buttons for groups.

  • Change the layout from one column to multiple columns. For example, you can display three columns of parameters on the form.

Note: To react to control events, you do not need to override the UI builder, because the control override methods need to be specified in the controller.

Evaluate how much you need to override. For example, you can change the layout from one to three columns without an override. In the UI builder, override the build method, update the current form group property columns to 3, and then call super(). The base class lays out the fields.