Developing Reports

Last update: April 17, 2024

CREATED FOR:

  • Developer

Adobe Experience Manager (AEM) provides a selection of standard reports most of which are based on a reporting framework.

Using the framework you can either extend these standard reports, or develop your own, new reports. The reporting framework integrates tightly with existing CQ5 concepts and principles so that developers can use their existing knowledge of CQ5 as a springboard for developing reports.

For the standard reports delivered with AEM:

NOTE
The tutorial Creating Your Own Report - An Example also shows how many of the principles below can be used.
You can also refer to the standard reports to see other examples of implementation.
NOTE
In the examples and definitions below the following notation is used :

  • Each line defines a node or a property where:
    N:<name> [<nodeType>] : Describes a node with the name of <*name*> and node type of <*nodeType*>.
    P:<name> [<propertyType] : Describes a property with the name of <*name*> and a property type of <*propertyType*>.
    P:<name> = <value> : Describes a property <name> that must be set to the value of <value>.

  • Indentation shows the hierarchical dependencies between the nodes.

  • Items separated by | denotes a list of possible items; for example, types or names; for example, String|String[] means that the property can be either String or String[].

  • [] depicts an array; such as String[] or an array of nodes as in the Query Definition.

Unless otherwise stated the default types are:
  • Nodes - nt:unstructured
  • Properties - String

Reporting Framework

The reporting framework works on the following principles:

  • It is entirely based on result sets that are returned by a query executed by the CQ5 QueryBuilder.

  • The result set defines the data displayed in the report. Each row in the result set corresponds to a row in the tabular view of the report.

  • The operations available for execution on the result set resemble RDBMS concepts; primarily grouping and aggregation.

  • Most data retrieval and processing is done server-side.

  • The client is solely responsible for displaying the pre-processed data. Only minor processing tasks (for example, creating links in cell content) are executed client-side.

The reporting framework (illustrated by the structure of a standard report) uses the following building blocks, fed by the processing queue:

chlimage_1-248

Report Page

The report page is:

Report Base

The reportbase component forms the basis of any report because it:

  • Preserves the definition of the query that delivers the underlying result set of data.

  • It is an adapted paragraph system that contains all columns ( columnbase) added to the report.

  • Defines which chart types are available and which are currently active.

  • Defines the Edit dialog box, which allows the user to configure certain aspects of the report.

Column Base

Each column is an instance of the columnbase component that:

  • Is a paragraph, used by the parsys ( reportbase) of the respective report.
  • Defines the link to the underlying result set. That is, it defines the specific data referenced within this result set, and how it is processed.
  • Retains additional definitions; such as the aggregates and filters available, together with any default values.

The Query and Data Retrieval

The query:

  • Is defined as part of the reportbase component.

  • Is based on the CQ QueryBuilder.

  • Retrieves the data used as the basis of the report. Each row of the result set (table) is tied to a node as returned by the query. Specific information for individual columns is then extracted from this data set.

  • Usually consists of:

    • A root path.

      This specifies the subtree of the repository to be searched.

      To help minimize the performance impact, it is advisable to (try to) restrict the query to a specific subtree of the repository. The root path can be either predefined in the report template or set by the user in the Configuration (Edit) dialog box.

    • One or more criteria.

      These are imposed to produce the (initial) result set; they include, for example, restrictions on the node type, or property constraints.

The key point here is that each single node returned in the result set of the query is used to generate a single row on the report (so a 1:1 relationship).

The developer has to ensure that the query defined for a report returns a node set appropriate for that report. However, the node itself does not need to hold all the required information, this can also be derived from parent and/or child nodes. For example, the query used for the User Report selects nodes based on the node type (in this case rep:user). However, most columns on this report do not take their data directly from these nodes, but from the child nodes profile.

Processing Queue

The query returns a result set of data to be displayed as rows on the report. Each row in the result set is processed (server-side), in several phases, before being transferred to the client for display on the report.

This allows:

  • Extracting and deriving values from the underlying result set.

    For example, it lets you process two property values as a single value by calculating the difference between the two.

  • Resolving extracted values; this can be done in various ways.

    For example, paths can be mapped to a title (as in the more human-readable content of the respective jcr:title property).

  • Applying filters at various points.

  • Creating compound values, if necessary.

    For example, consisting of a text that is displayed to the user, a value to be used for sorting and an additional URL that is used (on the client side) for creating a link.

Workflow of the Processing Queue

The following workflow represents the processing queue:

chlimage_1-249

Phases of the Processing Queue

Where the detailed steps and elements are:

  1. Transforms the results returned by the initial query (reportbase) into the basic result set using value extractors.

    Value extractors are automatically chosen depending on the column type. They are used for reading values from the underlying JCR Query and creating a result set from them; after which further processing may then be applied. For example, for the diff type, the value extractor reads two properties, calculates the single value that is then added to the result set. The value extractors cannot be configured.

  2. To that initial result set, containing raw data, initial filtering (raw phase) is applied.

  3. Values are preprocessed; as defined for the apply phase.

  4. Filtering (assigned to the preprocessed phase) is executed on the preprocessed values.

  5. Values are resolved; according to the defined resolver.

  6. Filtering (assigned to the resolved phase) is executed on the resolved values.

  7. Data is grouped and aggregated.

  8. Array data is resolved by converting it into a (string-based) list.

    This is an implicit step that converts a multi-value result into a list that can be displayed; it is required for (unaggregated) cell values that are based on multi-value JCR properties.

  9. Values are again preprocessed; as defined for the afterApply phase.

  10. Data is sorted.

  11. The processed data is transferred to the client.

NOTE
The initial query returning the basis data result set is defined on the reportbase component.
Other elements of the processing queue are defined on the columnbase components.