Report Definition form - Completing the Data Access tab

Use the Data Access tab to:

establish class joins, to simplify reporting on data from multiple classes or tables. This involves defining a logical condition, like a filtering condition, that equates properties in the two classes. For example:

MyOrg-CustomerService-Work.ProductID Is Equal MyOrg-Sales-Data-Products.SKU
establish declarative indexes built from the class on which you are reporting. A declarative index is often used to access embedded properties of an object. It uses an Index- class defined by a Declare Index rule to store embedded properties in a separate database table, in such a way that this table can be easily joined to the data you are reporting on.
see information about existing Association rules that support the report.
identify and configure the connections to sub-reports that provide data for this report.
Allow non-optimized properties (properties in the BLOB) to be available for selection in the Report Editor.
set general data source settings, such as the maximum number of rows to retrieve, for this report. You can adjust default settings for all reports on the Reporting > Settings landing page.
define security information for the report.

Field

Description

Prefix

Enter a short text string to be used as an alias for the joined class and all its properties. The Prefix is assigned to all the properties in the class and used to reference the properties from these fields on other tabs in the rule form.

Class Name

Select a class to be the primary class for the join. The Prefix plus this class name specify the joined class. You can specify multiple primary classes to be joined.

If this work type is derived from Work-, choose carefully whether you want to join to an implementation class, or to a framework class.

You can't join to an external class.

Edit Conditions (button)

Click to open the Enter Filter Conditions form and specify filters for the data from the class being joined.

Check the Remove Duplicate Rows checkbox to discard multiple entries that have the same data in the exposed columns.

Add rows for multiple filter conditions by clicking the add-a-row button .

Complete the fields for each condition:

Field	Description
Label	Enter a text label to identify the condition in this row. The label is used in the Conditions field to establish the relationship among multiple filter conditions.
Column	Select a property associated with the class you have specified for this join. This property must be an exposed column.
Relationship	Select `Is Equal`.
Value	Select the property in the report's Applies To class that corresponds to the Column value you entered.
Conditions	This field is in the form header. Using the values entered in the Label field for each row, enter a logical expression that defines how the system combines the criteria into an overall logical condition at runtime. The expression can include parentheses and the operators AND or OR. For example, if the table contains four rows labeled, A, B, C, and D, you can enter: (`A` OR `B` OR `C`) AND `D` in this field. This notation is the same as for the logic statement in when condition rules. Every filter condition in the list must be included in the Conditions statement.

Click OK to establish the filter conditions and dismiss the form. Click Cancel to leave the form without saving any changes you made.

Type

Accept the default choice, Only include matching instances, to cause the report to only include instances in each class that have a matching instance in the other class (referred to in database terms as an inner join).

By choosing one of the other options, you can instead use an outer join for the report in which all instances of one of the classes are included in the report even if they have no matching instances in the other class:

Select Include all rows in <class> to cause the report output to include all qualifying instances of the Applies To class of the rule, even if there is no match found in the prefix class.
Select Include all rows in <prefix> to cause the report output to include all qualifying instances of the joined class (identified by the value of the Prefix field), even if there is no match found in the Applies To class.

Note that when you define a join from one class to another, the report results may include multiple entries for each work item, if there are multiple corresponding entries in the other class or table.

You can specify indexes created by Rule-Declare-Index rules here to reference embedded properties from the Applies To class. This facilitates using Rule-Declare-Index rules for performance by avoiding retrieving properties from the BLOB (Storage Stream) column. You can attach an alias to any declarative index that you have previously defined.

Field	Description
Prefix	Enter a text string to be used as an alias for the joined declarative index class and all its properties. The prefix is assigned to all the properties in the class and used to reference these properties on other tabs of the rule form.
Index Name	Select the Index- class created by the Declare Index rule.
Type	Optional. The default choice, `Only include matching instances`, indicates that the report will only include instances in the Applies To class that have a matching instance in the declarative index (referred to in database terms as an inner join). By choosing the other option here, you can instead use an outer join for the report, in which all instances of the Applies To class are included in the report, even if they have no matching instances in the declarative index.

This read-only area lists any association rules that support the report, based on the properties you entered on the Design tab. Association rules are linked to report definitions automatically, as needed. See About Association rules and PDN article 26153 When and how to create an association rule to support reporting.

You can use existing Report Definition reports as sub-reports in the new report you are assembling. Any Report Definition report to which you have access, and which does not have its own sub-report, can serve as a sub-report. Using a report as a sub-report does not change its nature, and users can still access it directly without regard to its being used as a sub-report.

For a configuration example, see PDN article 26376 When and how to use sub-reports in Report Definition reports.

To add a sub-report, click the add-a-row button in the Sub-Reports section. Fill in the three fields:

Field	Description
Prefix	Create a unique prefix for the sub-report, consisting of letters, numbers, and the underscore character, with no spaces. This prefix must not be the same as the prefix for any other sub-report, or for a Class join or Declarative Index join, in this tab.
Class name	Select the class that contains the report you wish to use as a sub-report.
Name	Select the report to use as a sub-report. If you select a report that has its own sub-report, an error message appears when you click the Configure button to remind you that "a sub-report cannot itself contain a sub-report." If you see this error message, select a different report to serve as the sub-report.

When you have identified the report to use as a sub-report, click the Configure button to display the Configure Sub-Report Use form. Complete the form as follows:

Field

Description

Number of rows returned by this Sub-Report? Select either More than 1 Row (the default) or 1 Row.

Where will you use this Sub-Report?

This establishes which option lists on the Design tab will include columns from the sub-report. Select one or more of the options presented:

Columns To Include
Left Hand Side of Filter conditions
Right Hand Side of Filter conditions

How will you join results from the Sub-Report to those in this Report?

Click the add-a-row button ( ) to add filter conditions for adding sub-report data to the main report. For each row provide information in the fields as follows:

Field	Description
Label	Provide a unique alphanumeric label, with no spaces, for each filter condition.
Sub-Report Column	Select a column from the sub-report.
Relationship	Select a relationship statement (Is Equal, Is Greater Than, and so on).
Value	Select a property in the main report.

Use the labels to construct a statement in the Conditions field at the top of this section. The statement might look like A and B, or A and (B or C), depending on the nature of the conditions. Each filter condition must be represented in the Conditions statement.

Select one of the options in the drop-down menu to direct whether the report includes:

only matching rows from both reports
all rows from the main report
all rows from the sub-report

The default option is Do not match rows.

A sub-report that returns more than one column must be configured with a join to the main report. For such a sub-report, you cannot leave this section blank.

Ignore filter conditions from the Sub-Report in this report The sub-report may have filter conditions. Select this option to ignore those conditions. This makes available a larger, less-focused set of data in the sub-report.

How will you refer to columns in the Sub-Report within this Report? For each column in the sub-report, provide an alias (composed of letters, numbers, and the underscore character, with no spaces). The report uses these aliases in its selection menus when offering sub-report columns as options.

When you have completed configuring the sub-report, click OK. Click Cancel to leave the form without saving your changes.

Field	Description
General Data Source Settings	You can adjust default settings for all reports on the> Reporting > Settings landing page.
Maximum Number of Rows to Retrieve	Optional. Enter a maximum number of instances to retrieve for the report contents. As a best practice during testing, accept the default value `500`. If you leave this blank, the system enforces a limit of 10,000. If you exceed the established limit, the rows that have been retrieved are displayed, and the report header displays how many rows there are. No error dialog or error message is shown, and no error is written to a log. When the Use Paging checkbox on the User Interactions tab is selected, this value is ignored (and not available). You can advance though pages with no limit.
Maximum Elapsed Time in Seconds	Optional. Enter the maximum elapsed time in seconds that the report execution is allowed to run before being interrupted. If you leave this blank, the system enforces a default limit of 30 seconds. If the report exceeds the maximum elapsed time, a dialog appears explaining that the report took too long to run and that the filter conditions must be more specific. A report typically runs faster by adding additional filter conditions, or making the existing ones more constraining.
Maximum Number of Rows for Export	Optional. Override the default of 10,000 to enforce export of a smaller report, or to permit export of a larger one.
Maximum Elapsed Time in Seconds for Export	Optional. Override the default of 30 seconds if your system generally requires more time to export a report.
Restore Default	Click to clear any custom values and to restore the system defaults for the four settings in this section.
Display Unoptimized Properties in Data Explorer	Check this checkbox to have unoptimized properties (properties stored in the BLOB column) appear as selection options in the Report Editor's Data Explorer, in the Calculation Builder, and when establishing report filters. When you select an unoptimized property, a reminder appears that using such properties in calculations or for report columns may significantly increase the time it takes for the report to resolve. See PDN article 26454 When to use — and when not to use — unoptimized properties in reports.
Report on Descendant Class Instances	If the Applies To key part of this rule is a framework class, at runtime report execution can use the corresponding implementation class, not the framework class, for comparisons and report content. This feature eliminates the need to copy each framework class-based Report Definition report into the implementation class. Check this checkbox to enable this capability.

Field

Description

Get Row Key

If this checkbox is selected, the key of the table (usually the pzInsKey property, for internal classes) is included among the columns listed in the select clause.

By default, this checkbox is selected. However, when you select the Remove Duplicate Rows option on the Design tab, this checkbox is cleared, because if a unique row key is included, there are no duplicate rows.

Field	Description
Privilege	Optional. Use SmartPrompt to select security privileges required to run this report. Click the add-a-row button ( ) to add additional privileges.

Report Definition form Completing the Data Access tab
About New Design Chart Data Access User Interactions Pages & Classes
Parameters History More...

	external class, sub-report
	Working with the Report Viewer Working with the Chart Editor About Association rules
	Atlas — Standard Report Definitions

Report Definition form Completing the Data Access tab

Field

Description

Field

Description

Field

Description

Field

Description

Field

Description

Field

Description

Field

Description

Field

Description

Report Definition form
Completing the Data Access tab