Best Practices
Recommended practices for building dashboards, reports, widgets, joins, calculated fields, and global filters. Each section below corresponds to its own detailed walkthrough.
Getting Started
A single role permission gates the entire Builder, and the choice between a dashboard and a report comes down to audience, not features.
- Confirm Configure Reports is enabled before planning any build. It is one toggle, under Reports Configuration on a role, and it gates creating, editing, or deleting any dashboard or report, with no per widget type distinction.
- Choose Dashboard or Report by how the audience consumes it, not by feature. The builder underneath is identical either way. A supervisor who keeps something open all day wants a Dashboard; anyone who wants a file to forward, print, or read offline wants a Report and its Download PDF action.
Built-in Dashboards
The seeded dashboards are reference material, not a sandbox.
- Treat every built-in dashboard as read-only. Duplicate first if experimentation is genuinely needed; the copy starts Hidden regardless of the source's state, so nothing changed in it is visible to anyone until explicitly published.
- Use a built-in dashboard's existing widgets as a working template. Its field combinations, filters, and chart types are already proven in practice, which is a faster starting point than building from an empty canvas.
Creating a Dashboard
A few sequencing details are easy to miss the first time through.
- Fill in both Title and Description before expecting Save to enable. Both are required fields; the Save button stays inert until both are populated.
- Treat Save and Publish as two separate actions every time. Clicking Publish alone only flips the in-memory state; the dashboard reverts to its prior visibility unless Save is also clicked afterward. The sequence is always Save, then Publish, then Save again.
Sharing, Duplicating & Publishing Dashboards
Visibility, sharing, and duplication are three separate levers, not one.
- Add every intended viewer to Share explicitly, up front. There is no public link or org-wide "anyone with the link" option in this build. General access is fixed to restricted and cannot substitute for a real grantee list.
- Use Duplicate for variants, not for scratch drafts. It produces a fully independent copy, with its own id, Share list, and visibility state, always starting Hidden. It is the right tool for "same layout, different filter scope," and the only sanctioned way to experiment on a seeded item.
Built-in Reports
Reports share the Builder with dashboards, but carry a few behaviors of their own.
- Expect some built-in reports to require a Filters card and a Generate Report click. Several seeded reports render nothing until a mandatory filter is filled in and Generate Report is clicked; this is expected behavior for that report, not a loading failure.
- Remember Download PDF has no dashboard equivalent. It is a report-only action, worth factoring in when deciding which item type a given audience actually needs.
Creating a Report
A report's creation flow looks like a dashboard's, with one quiet difference.
- Do not wait for a success toast after saving a new report.
Unlike a dashboard, no confirmation toast fires. Landing on
/reports/{id}/builderis the only, and sufficient, confirmation that it saved. - Use a report Table widget's Time Configuration drop zone when pivoting by date. It is available on a report's Table widget but not on a dashboard's, for pivoting rows by a date dimension.
Exporting & Sharing Reports
What gets exported is configurable independently of what is currently on screen.
- Check Table Row Count before exporting, not just the Page Layout options. Current, 100, 500, 1,000, or Custom controls how many rows each table widget exports, independent of whatever is paginated on screen at the time.
- Read the PDF preview's Filters Applied line before downloading. It records applied filters for the report as a whole and for each individual widget separately, a quick way to confirm the export matches what was intended.
Data Fields & Schema
Not every field that looks like a relationship actually behaves like one.
- Check for an Association badge before building labels around a dimension.
A field can store a foreign key, such as Service Cases' Assigned Agent pointing at Contacts, while carrying only a plain
Dbadge with no join. Dragged into a widget, it returns a raw numeric id instead of a name. - Use the Schema view's All Models scope to find a module by name. In Report or In Dashboard scope only shows what a widget already uses; switching to All Models, with its category dropdown and live counts, is the faster way to locate something not yet in use.
Joins & Calculated Fields
Two mechanisms, each with its own learned habits.
- Open a Blended Data Source instead of fighting the single-module restriction. A plain widget can only pull fields from one module at a time; the link icon's Blended Data Source is the explicit, opt-in way to combine two.
- Find a field's real reference through the Code tab, not the Schema label.
A Schema column name such as
Case_Statusis a display label, not what the platform works with. Typing[followed by a module name in the Code tab surfaces the real, camelCase reference, for examplecrmServiceCases.caseStatus. - Let autocomplete insert the reference rather than typing it from memory. The Formula Code box is Monaco based, and fast simulated keystrokes can garble what lands in it, especially around a suggestion popup. Accepting a suggestion, or pasting, is the reliable path.
- Check the Name field after using Ask Auri, not just the generated expression. Ask Auri can overwrite Name with the raw prompt text, which then fails its own "no spaces" validation while the expression itself stays correct.
Widget Types
Eleven options invite picking the most impressive one; match the type to the question instead.
- Default to the narrowest widget type that answers the question. A Stat box answering "how many cases are open right now" serves a supervisor's screen better than a Sunburst chart burying the same number inside a hierarchy nobody asked for.
- Reach for Pivot when the question is genuinely a cross tabulation. It is the only widget type with built-in Summary Row and Summary Column totals, saving a separate Stat widget just for the grand total.
- Default to Column over Bar unless category labels are long. Reserve Bar specifically for when labels would overlap on a horizontal axis; Column is the better default otherwise.
Filters
"Global" is a deliberate, per-widget opt-in, not an automatic page-wide effect.
- Promote a filter only when the whole page should actually respond to it. Ticking Show in Global Filter on a widget's own filter row is what promotes it; dragging alone does not. Promoting too early turns an intentional, per-widget scope into an accidental, shared one.
- Wire the identical field into every widget that should respond together. A global filter only drives a widget that has that same field in its own Filters zone with the checkbox ticked on that row. It does not reach every widget on the page automatically.
- Set a default value rather than leaving a promoted filter empty. Ticking Set Default in the FILTERS tab, after choosing a value, makes the dashboard or report open already scoped the way its primary audience wants it, with a visible chip and a Reset to Defaults option for anyone who needs to see everything.
Permissions
Building access and viewing access are independent layers, and so is visibility.
- Keep the Configure Reports role toggle and per-item Share separate in your mental model. Configure Reports governs who can build at all, system-wide; Share governs who can see one specific dashboard or report. Neither one substitutes for the other.
- Remember Published and Shared are independent gates too. A dashboard can be Published and still invisible to someone simply because they were never added to its Share list, and the reverse is equally possible.