Dashboard Reference

Complete configuration reference for the Enezaframework dashboard system. Part of the Dashboards series.

Table of Contents

1. A. Report Class Attributes
2. B. Identifiers and Permissions
3. C. Eligibility Rules
4. D. Report Metadata Contract
5. E. Definition Schema
6. F. Widget Configuration
7. G. Layout and Widget Limits
8. H. Parameters, Filters, and Periods
9. I. Settings
10. J. Routes
11. K. Error Codes
12. Related Guides

A. Report Class Attributes

These attributes are declared on a report class. The base defaults come from the metadata layer in enezareporting/report_types.py and the unified bases in enezareporting/report_base.py.

Core report attributes

Dashboard opt-in attributes

Class methods

Computation fields

from django.db.models import Sum
from enezareporting.fields import ComputationField

TotalValue = ComputationField.create(
    Sum,
    "value",
    verbose_name="Total Value",
)

• The generated column name is <method>__<field> when no name is supplied, for example sum__value (enezareporting/fields.py:76-99).
• A computation field becomes a measure with one supported aggregation: the method name (enezareporting/dashboard.py:238-278).
• The class attribute (TotalValue) is exposed as an alias, but canonical column names are safer in definitions.

B. Identifiers and Permissions

Code derivation

From enezareporting/dashboard.py and enezareporting/report_types.py:

# get_dashboard_code()
code_app_label = report_app_label
                 or report_model._meta.app_label
                 or report_class.__module__.split(".")[0]

# discovery metadata
meta_app_label = report_model._meta.app_label
                 or report_app_label
                 or report_class.__module__.split(".")[0]

report_slug = get_report_slug()
              or report_slug
              or report_class.__name__.lower()

report_ref = dashboard_code or f"{code_app_label}.{report_slug}"

output_code = f"output.{meta_app_label}.{report_slug}.view"

Consequences:

• Do not set report_app_label when report_model exists. The two app labels above can disagree, producing a report_ref that does not match the permission code.
• dashboard_code changes report_ref only. The RBAC permission still follows report_slug.
• Duplicate report_ref values raise ImproperlyConfigured during discovery (enezareporting/dashboard.py:345-353).
• report_url is reverse(report_url_name). An unreversible name leaves the URL blank but does not make the report ineligible (enezareporting/dashboard.py:197-202).

Permission

Every widget execution calls:

has_output_permission(user, source.meta.output_code, request=request)

If the permission is missing, the widget returns a report_forbidden error and the report is removed from the page's filter groups (enezareporting/dashboard.py:501-527, enezadashboard/services/renderer.py:156-180).

Run python manage.py rbac_sync after adding or renaming reports.

C. Eligibility Rules

A source is returned by discovery only if all conditions pass (enezareporting/dashboard.py:204-217, enezareporting/dashboard.py:332-355).

Ineligible reports are excluded silently. The internal reason string is stored on the source metadata but never shown in discovery results.

D. Report Metadata Contract

DashboardReportMeta.to_dict() returns these keys (enezareporting/dashboard.py:50-90):

Column descriptor

Measure descriptor

Numeric database fields support sum, avg, min, max, count. Computation fields support their own method name only.

Abridged example

The exact values depend on the report class; the shape is:

{
  "code": "frameworkapp.frameworktestdocumentsales",
  "title": "Framework Test Document Sales",
  "app_label": "frameworkapp",
  "report_type": "tabular",
  "model_label": "frameworkapp.frameworktestdocumentline",
  "output_code": "output.frameworkapp.frameworktestdocumentsales.view",
  "report_url_name": "frameworkapp:frameworktestreport",
  "report_url": "/frameworkapp/frameworktestreport/",
  "columns": [
    {
      "name": "sum__item_quantity",
      "label": "Total Quantity",
      "type": "number",
      "format": "number",
      "align": "right",
      "is_computation": true,
      "computation_field": "item_quantity",
      "aggregations": ["sum"],
      "aliases": ["sum__item_quantity", "SumItemQuantity"],
      "source": "magic_field"
    }
  ],
  "dimensions": ["item_code", "item_description"],
  "measures": [
    {
      "name": "sum__item_quantity",
      "label": "Total Quantity",
      "aggregations": ["sum"],
      "aliases": ["sum__item_quantity", "SumItemQuantity"]
    }
  ],
  "parameters": [
    {
      "name": "date_range",
      "label": "Date Range",
      "type": "date_range",
      "required": false,
      "start_field": "created_at",
      "end_field": "created_at",
      "form_fields": ["start_date", "end_date"]
    }
  ],
  "filter_fields": ["item_code", "item_description"],
  "filter_schema": {},
  "eligible": true,
  "ineligible_reason": ""
}

Use the metadata endpoint to inspect the real values:

/dashboards/manage/report-meta/?report=frameworkapp.frameworktestdocumentsales

E. Definition Schema

Dashboard definition

Tab definition

Widget definition

Unknown keys are ignored by the seeder. They do not raise an error, so a typo in an optional key can silently do nothing. Validate with --dry-run and inspect the resulting draft.

F. Widget Configuration

All widget keys live under display_config. Validation code:

• KPI
• Chart
• Table
• Report preview

KPI

Behavior:

• Formatting is done by format_metric() (enezadashboard/widgets/base.py:61-81).
• integer and text use the same numeric formatting path as number; they do not coerce values to strings.
• currency does not imply two decimals. Set decimals: 2 explicitly; the form default is 0.
• The KPI compares against the previous period or previous year automatically when the page has comparison enabled and the report supports dates.
• A sparkline runs a query over the report rows and renders an SVG; it is not a client-side chart.

Chart

Chart types:

line, area, bar, horizontal_bar, donut, pie, funnel, gauge, heatmap, radar, scatter, bubble, bullet, combo, stacked_bar, stacked_area (enezadashboard/widgets/chart.py:27-44).

Requirement matrix:

Runtime rules:

• Pie, donut, funnel, stacked bar, stacked area, and heatmap reject negative values with invalid_data (enezadashboard/widgets/chart.py:245-253).
• Charts render server-side; no JavaScript chart library is loaded.
• gauge uses a true aggregate, not report rows.

Table

Runtime query parameters: page, page_size, sort, dir. page_size is clamped to MAX_PAGE_SIZE (enezadashboard/widgets/table.py:45-111).

Report preview

A preview is a non-paginated table with page_size = row_limit. It reuses the table renderer, so sortable defaults to true internally, but the preview form does not expose a sortable toggle (enezadashboard/widgets/report_preview.py:30-43).

G. Layout and Widget Limits

Default widget layout by type when a definition omits layout (enezadashboard/services/seeding.py:84-91):

H. Parameters, Filters, and Periods

Allowed widget parameters

parameter_config may contain only:

• start_date, end_date for a DateRangeParam;
• the parameter name and any form_fields for every other parameter.

Unknown keys fail validation with “Unknown report parameter(s)”.

Widget filter shape

{
  "condition": "AND",
  "primary_model": "frameworkapp.frameworktestdocumentline",
  "related_models": [],
  "groups": [
    {
      "condition": "AND",
      "rules": [
        {
          "id": "item_code",
          "field": "item_code",
          "type": "string",
          "input": "text",
          "operator": "equal",
          "value": "A-100"
        }
      ]
    }
  ]
}

Rules:

• Each rule id must be in meta.filter_fields.
• operator must be supported by the workflow engine.
• Page-level user filters may use AND, OR, or NOT group conditions; NOT requires exactly one rule (enezadashboard/services/renderer.py:635-668).
• Widget-level admin filters and page-level user filters merge with AND when the admin filter is also AND. An admin filter using OR is not merged, and the page shows a warning (enezadashboard/services/renderer.py:322-332, enezadashboard/services/renderer.py:733-758).

Dashboard and tab date settings

Period resolution order:

1. tab date_range.default_period (default means no range; a preset or custom resolves dates)
2. tab date_range.default_start_date / default_end_date (when the period is custom)
3. dashboard data_settings.default_period
4. site DEFAULT_PERIOD

Reference-date resolution order:

1. tab filter_config.data.reference_date_field
2. dashboard data_settings.reference_date_field
3. report's date_range.start_field
4. report's date_field
5. common created-date fields (created_at, created, …)
6. the first date field on the model

Reference-date resolution is in enezadashboard/services/renderer.py:495-533. Period resolution is in enezadashboard/services/renderer.py:218-254.

Period presets

today, yesterday, last_7_days, last_30_days, this_week, last_week, this_month, last_month, this_quarter, last_quarter, this_year, last_year, ytd, custom (enezadashboard/services/periods.py:10-25).

Comparison choices: none, previous, previous_year (enezadashboard/services/periods.py:34-41).

Page query parameters

Invalid periods fall back to the configured default and add a warning rather than raising (enezadashboard/services/periods.py:218-260).

I. Settings

Settings are read by dashboard_settings() and merged over the defaults in enezadashboard/conf.py:3-21:

ENEZA_DASHBOARD_SETTINGS = {
    "DEFAULT_PAGE_SIZE": 20,
    "MAX_PAGE_SIZE": 100,
    "MAX_CHART_CATEGORIES": 100,
    "MAX_PREVIEW_ROWS": 20,
    "QUERY_CACHE_TTL": 0,
    "QUERY_TIMEOUT_MS": 0,
    "DESIGNER_ACTION_CODE": "action.enezadashboard.manage",
    "AUTO_REFRESH_MIN_SECONDS": 30,
    "DEFAULT_PERIOD": "last_30_days",
    "DEFAULT_COMPARE": "none",
    "MAX_USER_FILTER_RULES": 20,
    "MAX_USER_FILTER_GROUPS": 5,
}

The project already ships the main overrides in framework/settings.py:326-335. The remaining keys in the block above come from conf.py defaults. Override individual keys in the project's settings rather than redefining the whole dictionary.

J. Routes

All dashboard routes use the enezadashboard namespace.

Source: enezadashboard/urls.py:7-129.

K. Error Codes

DashboardValidationError carries message, code, and optional structured errors (enezareporting/dashboard.py:30-47).

Non-DashboardValidationError failures:

• Duplicate report code — ImproperlyConfigured during discovery.
• Duplicate definition identity — ValueError during load_definitions.
• Model/slug validation — Django ValidationError from model or form validation.

Related Guides

• Dashboards Overview
• Creating a Dashboard Data Source
• Defining and Seeding Dashboards
• Dashboard Designer and Publication
• Worked Example: frameworkapp
• Operations and Troubleshooting
• Dashboards — Developer Index