diff --git a/README.md b/README.md index 55d10e6..b8524c8 100644 --- a/README.md +++ b/README.md @@ -209,6 +209,38 @@ produces a report that runs cleanly and reports the wrong number. **Fleet fuel comes from the energy use record.** `VehicleAssetEmssnSrc` has no fuel field — fuel, consumption and distance all live on `VehicleAssetEnrgyUse`. +## Scope: the reports read the whole object, deliberately + +Fifteen of the 21 reports carry no filter, and all 21 leave the standard date filter +unbounded. That is a decision, not an oversight, and it is worth understanding before you +deploy into an org with years of history. + +**Why unbounded.** The date column available on these objects is `CreatedDate` — when +somebody typed the record in. The business axis is `ReportingYear`, and the two do not +agree: a footprint *for* 2024 is routinely entered in 2026, during the disclosure cycle. +Bounding on `CreatedDate` would therefore drop records that belong in the answer. It would +make the reports faster and wrong, which is the worse of the two failures for anything +feeding a disclosure. + +**What it costs.** Each of these reports reads every record in scope on every run. On a +dev org or a first year of data that is invisible. On an org with several years of +footprint and energy-use records it is the first thing that will get slow, and the +dashboard-fed reports pay it on every refresh. + +**What to do about it, when you get there.** Add a `ReportingYear` filter — it is on every +report type here, and it is the axis the reports already group by. Which years to keep is +a question about your disclosure obligations rather than about Salesforce, which is why +this repository does not choose for you. + +Two related shapes, also deliberate: + +- **The six tabular reports have no row limit.** They are worklists and lookup lists — + *Footprint Data Entry*, *Asset Names and Locations* — meant to be worked all the way + through. A row limit on a worklist hides the rows somebody still has to fill in. +- **The summary reports show details.** The same reports are read two ways: as a chart on a + dashboard, and as a list of the specific assets to go and fix. Turning details off would + make the chart marginally cheaper and the worklist useless. + ## Also in this repo - [`sample-data/`](sample-data/) — six UTF-8 CSVs with deliberate gaps and orphans, so the diff --git a/docs/building-your-own.md b/docs/building-your-own.md index 5fba29f..1cbc449 100644 --- a/docs/building-your-own.md +++ b/docs/building-your-own.md @@ -174,3 +174,55 @@ that pattern. The lesson is the same one as the report type joins: the platform' objects use plain API names in places where its older objects use legacy keys, and only a deploy tells you which you've got. + +## Retrieving overwrites what the source deliberately leaves out + +`sf project retrieve start` does not give you back what you deployed. It gives you the +org's rendering of it, and for dashboards that includes two elements this package +deliberately does not carry: + +```xml +someone@example.com +someone@example.com +``` + +Salesforce stamps both on every dashboard, whatever the source said, and it does so even +for a `LoggedInUser` dashboard where the running user is not used to decide what anyone +sees. Commit them and you have broken the package for everybody else: that username does +not exist in their org, so the deploy fails on a user it cannot resolve. You have also put +your own email address into a public repository, twice per dashboard. + +The committed dashboards here carry `LoggedInUser` and no +owner or running user. That omission is the portable form, and it is load-bearing. + +**So: never commit a dashboard retrieve without checking.** + +```bash +sf project retrieve start --manifest manifest/package.xml --target-org +grep -rn "owner\|runningUser" force-app/main/default/dashboards/ +``` + +Anything printed has to come out before you commit. If the rest of the retrieve is +cosmetic — and it usually is — the honest move is to throw the whole thing away and keep +the hand-authored source: + +```bash +git checkout -- force-app +``` + +### What else comes back, and why none of it is worth keeping + +The same round trip adds a few dozen lines of defaults across the reports: +`co1`, ``, ``. +They change nothing — a deploy from the source without them succeeds — and they make a +report definition longer without making its intent clearer. + +The dashboards also come back with two properties *rewritten* rather than added: +`` flips to `false` and `` is dropped altogether. Neither applies +to a Bar component; Salesforce is normalising settings that were never doing anything. +That is worth knowing when you write a new component — those two do nothing on a bar chart +— but it is not worth taking a two-hundred-line reformat to find out. + +The general rule, and it is the same one as everywhere else in this document: a deploy +tells you whether the source is *sufficient*. A retrieve tells you what the org chose to +store, which is a different question, and a noisier answer. diff --git a/force-app/main/default/dashboards/NZC_Dashboards/NZC_Data_Quality.dashboard-meta.xml b/force-app/main/default/dashboards/NZC_Dashboards/NZC_Data_Quality.dashboard-meta.xml index 0e7c202..11812ac 100644 --- a/force-app/main/default/dashboards/NZC_Dashboards/NZC_Data_Quality.dashboard-meta.xml +++ b/force-app/main/default/dashboards/NZC_Dashboards/NZC_Data_Quality.dashboard-meta.xml @@ -128,6 +128,44 @@ Orphaned Energy Uses by Fuel false + + true + Auto + Bar + Auto + false + false + true + true +
Orphans
+ Bottom + NZC_Reports/Orphaned_Fleet_Footprints + false + false + true + RowValueDescending + Orphaned Fleet Footprints + false + + + true + Auto + Bar + Auto + false + false + true + true +
Orphans
+ Bottom + NZC_Reports/Orphaned_Vehicle_Energy_Uses + false + false + true + RowValueDescending + Orphaned Vehicle Energy Uses + false + #000000 NZC Data Quality