Reports¶

A report is a process-level view that exposes a controlled, read-only data set to process users. Reports are useful when users need to explore relational process data without being given access to the underlying database or the query definition.

Reports are built around the Pivot Table widget. The process developer defines the data set and its initial presentation; users can then filter, sort, group, pivot, and aggregate the available data at runtime.

When to use a report¶

Use a report when:

• the data already exists in a process relational schema;
• users need ad-hoc analysis of existing rows;
• the query and exposed fields must remain under developer control; or
• the result should be available from a process folder.

Use a screen instead when the page needs a custom form, a data model, initialization logic, or actions that are not provided by the Pivot Table widget.

Report structure¶

Reports are stored directly under the Reports element of a process definition. A report contains one PivotTable whose Query identifies the controlled data set.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

<Reports>
  <Report Id="5fcaf4ac-67ab-48ec-9d92-b6b7396400c6"
          Name="crm"
          Caption="CRM proposals"
          Order="0"
          IsAnonymouslyAccessible="False"
          IsDashboard="False"
          IsAdministrativeDashboard="False">
    <PivotTable AllowEditingTemplates="False"
                EnableCharts="False"
                DesignMode="False"
                Size="Medium"
                XPath="">
      <Query Id="02a603e5-9168-42c2-be7e-e8fedafd7f11"
             IncludeAllColumns="False"
             XPath=""
             Start="0"
             MaxLength="-1">
        <Parameters>
          <TargetSchema>CRM</TargetSchema>
          <TargetTable>Proposals</TargetTable>
        </Parameters>
        <Columns />
        <Where Condition="And">
          <Criteria />
          <Blocks />
        </Where>
        <Order />
        <SubQueries />
      </Query>
      <Templates />
    </PivotTable>
  </Report>
</Reports>

The complete query model is documented in Relational Database Query.

Report properties¶

Defining the query¶

Target schema and table¶

Set Parameters/TargetSchema and Parameters/TargetTable to a schema and table defined by the process. The report designer uses these values to populate the available fields and relations.

Columns¶

Add a Column for each field that should be explicitly exposed. A column can use a direct field or a relation path:

1
2
3
4
5

<Columns>
  <Column Expression="Name" Caption="Customer" />
  <Column Expression="Orders.Amount" Caption="Order amount" />
  <Column Expression="Orders.Product.Name" Caption="Product" />
</Columns>

If no columns are specified, the repository query can use the table's available columns automatically. Explicit columns are recommended for stable output and for preventing unintended fields from becoming visible when the schema changes.

Column transformations can format or map values before they are displayed. Use them when the database value is not the most useful value for a report user.

Filtering and ordering¶

Use Where for fixed developer-defined criteria and Order for the initial order. Users can apply additional runtime filters and sorting in the report grid, but they cannot change the underlying query definition.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

<Where Condition="And">
  <Criteria>
    <Criteria Expression="Status"
              Comparison="Equals"
              Condition="And">
      <Value>Open</Value>
    </Criteria>
  </Criteria>
</Where>
<Order>
  <Order Expression="CreatedAt" Type="Descending" />
</Order>

For available comparisons, relation paths, functions, grouping, and aggregation, see the relational query guide.

Report templates¶

Templates are named grid layouts stored under PivotTable/Templates. They define the initial presentation of the query result, including column visibility, order, widths, sorting, grouping, and pivot settings. Templates do not change the query or the underlying data.

The Pivot Table designer produces the template state automatically. Developers normally create and adjust templates by using the report designer rather than writing the serialized state by hand.

Only one template should be marked with IsDefault="True". The default template is applied when the report opens. If no default template is defined, the grid's default column state is used.

For a process report, templates are developer-defined. The runtime report intentionally disables saving and deleting templates, so users can select an available template but cannot change the process definition from the report page. If a Pivot Table is used inside a regular form or screen, its AllowEditingTemplates behavior can differ; see the Pivot Table widget.

Runtime behavior¶

At runtime a process report is rendered as a large Pivot Table. The runtime enables charts and prevents users from editing the process-defined templates. Users can still use the configured data set to:

• filter text, number, and date columns;
• sort columns;
• group rows;
• pivot columns;
• aggregate numeric values; and
• switch between developer-defined templates.

Templates are presentation presets. A template can hide technical identifiers, choose a useful column order, set an initial sort, or configure grouping and aggregation for a summary view. Keep at least one detail-oriented template when users need to inspect individual rows.

The query is executed through the authenticated data store and the report request carries the process version context. Do not treat a report as a replacement for row-level authorization: expose only fields and relations that the report's audience is allowed to see, and apply the process schema's authorization model where appropriate.

Access and URLs¶

Reports use the same process and version access checks as other process screens. The user must have access to the containing folder and the folder_report feature scope. Administrative reports additionally require process execution permission. Anonymous reports must be explicitly marked as anonymously accessible.

The report URL is:

1

https://mydomain.emakin.com/app/?/report/<process-id>/<report-id>

Use the report's stable Id rather than its display name when constructing links.

Performance and data exposure¶

• Prefer explicit columns over exposing every table field.
• Keep relations and expressions limited to the fields needed by the report.
• Use fixed criteria to reduce the initial result set where possible.
• Avoid exposing personal, security-sensitive, or operational fields unless the audience requires them.
• Consider the size of the underlying table when allowing unrestricted grouping, pivoting, or aggregation.

Related pages¶

• Screens
• Relational Databases
• Relational Database Query
• Pivot Table widget
• Insert Emakin Links to Forms or Reports