Developing Reports developing-reports

These reports are built on the reporting framework:

• Component Report
• Page Activity Report
• User Report
• Workflow Instance Report

The following reports are based on individual principles and therefore cannot be extended:

• Disk Usage
• Health Check
• Workflow Report

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.

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.

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.

• 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.

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.

propertyConstraints

Limits the result set to nodes that have specific properties with specific values. If multiple constraints are specified, the node must satisfy all of them (AND operation).

For example:

N:propertyConstraints
 [
 N:0
 P:sling:resourceType
 P:foundation/components/textimage
 N:1
 P:jcr:modifiedBy
 P:admin
 ]

Would return all textimage components that were last modified by the admin user.

nodeTypes

Used to limit the result set to the specified node types. Multiple node types can be specified.

mandatoryProperties

Limits the result set to nodes that have all the specified properties. The value of the properties is not account for.

settings

Holds definitions for the active charts.

• active

  As multiple settings can be defined, you can use this to define which are currently active. These are defined by an array of nodes (there is no compulsory naming convention for these nodes, but the standard reports often use 0, 1… x), each having the following property:

  • id

    Identification for the active charts. This must match the id of one of the chart definitions.

definitions

Defines the chart types that are potentially available for the report. The definitions to be used is specified by the active settings.

The definitions are specified using an array of nodes (again often named 0, 1… x), each having the following properties:

• id

  The chart’s identification.

• type

  The type of chart available. Select from:

  • pie
    Pie chart. Generated from current data only.

  • lineseries
    Series of lines (connecting dots representing the actual snapshots). Generated from historic data only.

• Additional properties are available, dependent on the chart type:

  • for the chart type pie:

    • maxRadius ( Double/Long)

      The maximum radius allowed for the pie chart; therefore the maximum size allowed for the chart (without legend). Ignored if fixedRadius is defined.

    • minRadius ( Double/Long)

      The minimum radius allowed for the pie chart. Ignored if fixedRadius is defined.

    • fixedRadius ( Double/Long)
      Defines a fixed radius for the pie chart.

  • for the chart type lineseries:

    • totals ( Boolean)

      True if an additional line showing the Total should be shown.
      default: false

    • series ( Long)

      Number of lines/series to be shown.
      default: 9 (this is also the maximum allowed)

    • hoverLimit ( Long)

      Maximum number of aggregated snapshots (dots shown on each horizontal line, representing distinct values) for which pop-ups are to be displayed. That is, when the user does mouse over on a distinct value or corresponding label in the chart legend.

      default: 35 (that is, no pop-ups at all are shown if more than 35 distinct values are applicable for the current chart settings).

      There is an additional limit of ten pop-ups that can be shown in parallel (multiple pop-ups can be shown when mouse-over is made over the legend texts).

title

/libs/cq/reporting/components/commons/title

Text field to define the report title.

description

/libs/cq/reporting/components/commons/description

Text area to define the report description.

processing

/libs/cq/reporting/components/commons/processing

Selector for the report’s processing mode (manually/automatically load data).

scheduling

/libs/cq/reporting/components/commons/scheduling

Selector for scheduling snapshots for the historic chart.

rootPath

This limits the report to a certain section (tree or subtree) of the repository, which is recommended for performance optimization. The root path is specified by the rootPath property of the report node of each report page (taken from the template upon page creation).

It can be specified by:

• the report template (either as a fixed value or as the default value for the configuration dialog).
• the user (using this parameter)

property

Defines the property to be used for calculating the actual cell value.

If a property is defined as String[], multiple properties are scanned (in sequence) to find the actual value.

For example, if there is:

property = [ "jcr:lastModified", "jcr:created" ]

The corresponding value extractor (which is in control here):

• Checks whether there is a jcr:lastModified property available and if so, use it.
• If no jcr:lastModified property is available, the contents of jcr:created are used instead.

subPath

If the result is not on the node that is returned by the query, subPath defines where the property is located.

secondaryProperty

A second property that must be used for calculating the actual cell value. This definition is only used for certain column types (diff and sortable).

For example, if there is the Workflow Instances Report, the property specified is used to store the actual value of the time difference (in milliseconds) between start and end times.

secondarySubPath

Similar to subPath, when secondaryProperty is used.

resolver

Defines the resolver to be used. The following resolvers are available:

• const

  Maps values to other values; for example, this is used to resolve constants such as en to its equivalent value English.

• default

  The default resolver. This is a dummy resolver that actually resolves nothing.

• page

  Resolves a path value to the path of the appropriate page; more precisely, to the corresponding jcr:content node. For example, /content/.../page/jcr:content/par/xyz is resolved to /content/.../page/jcr:content.

• path

  Resolves a path value by optionally appending a subpath and taking the actual value from a property of the node (as defined by resolverConfig) at the resolved path. For example, a path of /content/.../page/jcr:content can be resolved to the content of the jcr:title property, this would mean that a page path is resolved to the page title.

• pathextension

  Resolves a value by prepending a path and taking the actual value from a property of the node at the resolved path. For example, a value de might be prepended by a path such as /libs/wcm/core/resources/languages, taking the value from the property language, to resolve the country code de to the language description German.

resolverConfig

Provides definitions for the resolver. The options available depend on the resolver selected:

• const

  Use properties to specify the constants for resolving. The name of the property defines the constant to be resolved; the value of the property defines the resolved value.

  For example, a property with Name= 1 and Value =One resolves 1 to One.

• default

  No configuration available.

• page

  • propertyName (optional)

    Defines the name of the property that should be used for resolving the value. If not specified, the default value of jcr:title (the page title) is used; for the page resolver, this means that first the path is resolved to the page path, then further resolved to the page title.

• path

  • propertyName (optional)

    Specifies the name of the property that should be used for resolving the value. If not specified, the default value of jcr:title is used.

  • subPath (optional)

    This property can be used to specify a suffix to be appended to the path before the value is resolved.

• pathextension

  • path (mandatory)

    Defines the path to be prepended.

  • propertyName (mandatory)

    Defines the property on the resolved path where the actual value is located.

  • i18n (optional; type Boolean)

    Determines whether the resolved value should be internationalized (that is, using CQ5’s internationalization services).

preprocessing

Preprocessing is optional and can be bound (separately) to the processing phases apply or applyAfter:

• apply

  The initial preprocessing phase (step 3 in the representation of the processing queue).

• applyAfter

  Apply after preprocessing (step 9 in the representation of the processing queue).

original value:

The preprocessing definition for the original value is specified on apply and/or applyAfter directly.

value in its aggregated state:

If necessary, a separate definition can be provided for each aggregation.

To specify explicit preprocessing for aggregated values, the preprocessing definitions have to reside on a respective aggregated child node ( apply/aggregated, applyAfter/aggregated). If explicit preprocessing for distinct aggregates is required, the preprocessing definition is on a child node with the name of the respective aggregate (for example, apply/aggregated/min/max or other aggregates).

find and replace patterns
When found, the specified pattern (which is defined as a regular expression) is replaced by another pattern; for example, this can be used to extract a substring of the original.

data type formatters

Converts a numeric value into a relative string; for example, the value ``representing a time difference of one hour would be resolved to a string such as 1:24PM (1 hour ago).

pattern

The regular expression that is used to locate a substring.

replace

The string, or representation of the string, that is used as a replacement for the original string. Often this represents a substring of the string located by the regular expression pattern.

For the node definitions/data/preprocessing/apply with the following two properties:

• pattern: (.*)(/jcr:content)(/|$)(.*)
• replace: $1

A string arriving as:

• /content/geometrixx/en/services/jcr:content/par/text

Broken into four sections:

• $1 - (.*) - /content/geometrixx/en/services
• $2 - (/jcr:content) - /jcr:content
• $3 - (/|$) - /
• $4 - (.*) - par/text

And replaced with the string represented by $1:

• /content/geometrixx/en/services

format

Data type formatter:

• duration

  Duration is the time span between two defined dates. For example, the start and end of a workflow action that took one hour, starting at 2/13/11 11:23h and ending one hour later at 2/13/11 12:23h.

  It converts a numeric value (interpreted as milliseconds) into a duration string; for example, 30000 is formatted as * 30s.*

• datedelta

  Datadelta is the time span between a date in the past until “now” (so it has a different result if the report is viewed at a later point in time).

  It converts the numeric value (interpreted as a time difference in days) into a relative date string. For example, 1 is formatted as one day ago.

type

The following are available as standard options:

• string

• number

• int

• date

• diff

• timeslot

  Used for extracting parts of a date needed for aggregation (for example, group by year to get data aggregated for each year).

• sortable

  Used for values that use different values (as taken from different properties) for sorting and displaying.

In addition, any of the above can be defined as multi value; for example, string[] defines an array of strings.

The value extractor is chosen by the column type. If a value extractor is available for a column type, then this extractor is used. Otherwise, the default value extractor is used.

A type may (optionally) take a parameter. For example, timeslot:year extracts the year from a date field. Types with their parameters:

• timeslot - The values are comparable to the corresponding constants of java.utils.Calendar.

  • timeslot:year - Calendar.YEAR
  • timeslot:month-of-year - Calendar.MONTH
  • timeslot:week-of-year - Calendar.WEEK_OF_YEAR
  • timeslot:day-of-month - Calendar.DAY_OF_MONTH
  • timeslot:day-of-week - Calendar.DAY_OF_WEEK
  • timeslot:day-of-year - Calendar.DAY_OF_YEAR
  • timeslot:hour-of-day - Calendar.HOUR_OF_DAY
  • timeslot:minute-of-hour - Calendar.MINUTE

groupable

Defines whether the report can be grouped by this column.

filters

Filter definitions.

• filterType

  Available filters are:

  • string

    A string-based filter.

• id

  Filter identifier.

• phase

  Available phases:

  • raw

    The filter is applied on raw data.

  • preprocessed

    The filter is applied on preprocessed data.

  • resolved

    The filter is applied on resolved data.

aggregates

Aggregate definitions.

• text

  Textual name of the aggregate. If text is not specified, then it takes the default description of the aggregate. For example, minimum is used for the min aggregate.

• type

  Aggregate type. Available aggregates are:

  • count

    Counts the number of rows.

  • count-nonempty

    Counts the number of non-empty rows.

  • min

    It provides the minimum value.

  • max

    It provides the maximum value.

  • average

    It provides the average value.

  • sum

    It provides the sum of all values.

  • median

    It provides the median value.

  • percentile95

    Uses the 95th percentile of all values.

aggregate

Valid aggregate values are the same as for type under aggregates (see Column Specific Definitions (definitions - filters / aggregates) ).

Set the type property of the column’s definition node to generic.

See /libs/cq/reporting/components/userreport/genericcol/definitions

Specify a (standard) dialog definition under the column’s definition node.

See /libs/cq/reporting/components/userreport/genericcol/definitions/dialog

• The fields of the dialog box must refer to the same names as the corresponding component property, including its path.

  For example, if you want to make the type of the generic column configurable through the dialog, use a field with the name of ./definitions/type.

• Properties defined using the UI/dialog take precedence over those defined on the columnbase component.

Define the Edit Configuration.

See /libs/cq/reporting/components/userreport/genericcol/cq:editConfig

Use standard AEM methodologies to define (additional) column properties.

For properties that are defined on both the component and column instances, the value on the column instance takes precedence.

Properties available for a generic column are:

• jcr:title - column name
• definitions/aggregates - aggregates
• definitions/filters - filters
• definitions/type- the type of the column (this must be defined in the dialog, either using a selector/combobox or a hidden field)
• definitions/data/resolver and definitions/data/resolverConfig (but not definitions/data/preprocessing or .../clientFilter) - the resolver and configuration
• definitions/queryBuilder - the query builder configuration
• defaults/aggregate - the default aggregate

If there is a new instance of the generic column on the User Report, the properties defined with the dialog are persisted under:

/etc/reports/userreport/jcr:content/report/columns/genericcol/settings/generic

/etc/designs/reports/<yourReport> is suitable if the report is under /apps/cq/reporting

/etc/designs/<yourProject>/reports/<*yourReport*> for reports using the /apps/<yourProject>/reports pattern

components

Any components and/or component groups that are allowed on the report.

sling:resourceType

Property with value cq/reporting/components/repparsys.

set the sling:resourceType to cq/reporting/components/reportpage

indicate the design to be used

create a report child node that references the container ( reportbase) component with the sling:resourceType property

Timezone defines the timezone historic data is created for. This is to ensure that the historic chart displays the same data for each user around the globe.

Locale defines the locale to be used with Timezone for historic data. The locale is used to determine some locale-specific calendar settings (for example, whether the first day of a week is Sunday or Monday).

Snapshot path defines the root path where snapshots for historic charts are stored.

Path to reports defines the path where reports are located. This is used by the snapshot service to determine the reports to actually take snapshots for.

Daily snapshots defines the hour of each day when daily snapshots are taken. The specified hour is in the local timezone of the server.

Hourly snapshots defines the minute of each hour when hourly snapshots are taken.

Rows (max) defines the maximum number of rows that are stored for each snapshot. This value should be chosen reasonably. If it is too high, this affects the size of the repository, if too low, data may not be accurate because of the way historic data is handled.

Fake data, if enabled, fake historic data can be created by using the fakedata selector; if disabled, then use of the fakedata selector throws an exception.

Because the data is fake, it must only be used for testing and debugging purposes.

Using the fakedata selector finishes the report implicitly, so all existing data is lost. Data can be restored manually, but this can be a time-consuming process.

Snapshot user defines an optional user that can be used for taking snapshots.

Basically, snapshots are taken for the user that has finished the report. There might be situations (for example, on a publish system, where this user is nonexistent as their account has not been replicated) where you want to specify a fallback user that is used instead.

Also, specifying a user might impose a security risk.

Enforce snapshot user, if enabled, all snapshots are taken with the user specified under Snapshot user. This might have a serious security impact if not handled correctly.