docs(embed): document va_parmap and the Filter button per embed mode #26

2026-10-28T10:47:24Z

hermes commented

2026-10-28 10:47:24 +00:00

Docs for the va_parmap work in dc/dc#383. Draft until that PR ships, so the page does not describe something the released app does not do.

What this adds

Mapping parameters to columns - the new va_parmap URL parameter, which overrides the name-based match between a VA parameter and a DC column. This is what lets two report objects filter the same column from differently-named parameters, which the name match cannot express.
the warning banner, next to it: what a report author sees when an entry cannot be used, and why the parameter is then ignored rather than filtered on the wrong column.
the ?embed= table now has a Filter button column, so it is explicit that embed=true keeps Data Controller's own filter builder and embed=va hands filtering to the report (the button is hidden there).

Grammar documented

https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=REGION_TAB1-REGION

One entry per mapping, <VA parameter>-<DC column>, repeated for more than one entry. Split at the last hyphen so a label may contain hyphens; key matched case-insensitively against the parameter label then its internal name; one parameter maps one column; a mapping that cannot be used is reported in a banner and ignored rather than falling back to the name match.

Notes

a label containing & has to be percent-encoded; a space may be written as + or %20
the same behaviour is described from the code side in dc/dc#383, where the e2e cases pin the mapping, the warnings and the two-parameter case

Why the Filter button is hidden in VA mode

Worth calling out, because it is the one thing that would otherwise look like an omission: in va mode the report owns the filter, and the two mechanisms are alternatives rather than layers. A filter built in Data Controller is replaced the next time the report's selection changes, and vice versa. Showing the button there would offer a filter that silently stops applying as soon as the report is touched, so it is hidden rather than disabled.

The page says this explicitly now, after the embed-mode table.

Making them interoperable (for example AND-ing a Data Controller filter with the report's parameters) is a real change, not a UI tweak, and is out of scope for this release: every apply path converges on "save one filter, reload at /editor/<table>/<FILTER_RK>", so combining them means defining the combination rule, reading the stored filter's clauses back client-side, and reworking the signature/dedup that currently stops the VA replay fighting itself. That is its own PR.

The embed modes are now described in full

The table has a fourth column (which value lets the report drive filtering and columns), and va mode is described by what it actually changes, not just the Filter button:

filtering from the report, live or confirm, with the first load already filtered
column visibility taken from the columns the report sends (primary keys always kept)
the Filter button is not offered, and the two filter mechanisms are alternatives rather than layers
Add Record is not offered
a "Back to Edit table" bar appears on the stage / approve / review pages

true is described as chrome-hiding only.

Also covers date anchors

The same page now documents the ADD(...) / RANGE(...) anchors on a mapping (dc/dc#386, stacked on #383). Both land together, so the page stays one description of va_parmap rather than two.

Docs for the `va_parmap` work in dc/dc#383. Draft until that PR ships, so the page does not describe something the released app does not do. ## What this adds - **Mapping parameters to columns** - the new `va_parmap` URL parameter, which overrides the name-based match between a VA parameter and a DC column. This is what lets two report objects filter the same column from differently-named parameters, which the name match cannot express. - the warning banner, next to it: what a report author sees when an entry cannot be used, and why the parameter is then ignored rather than filtered on the wrong column. - the `?embed=` table now has a **Filter button** column, so it is explicit that `embed=true` keeps Data Controller's own filter builder and `embed=va` hands filtering to the report (the button is hidden there). ## Grammar documented ``` https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=REGION_TAB1-REGION ``` One entry per mapping, `<VA parameter>-<DC column>`, repeated for more than one entry. Split at the last hyphen so a label may contain hyphens; key matched case-insensitively against the parameter label then its internal name; one parameter maps one column; a mapping that cannot be used is reported in a banner and ignored rather than falling back to the name match. ## Notes - a label containing `&` has to be percent-encoded; a space may be written as `+` or `%20` - the same behaviour is described from the code side in dc/dc#383, where the e2e cases pin the mapping, the warnings and the two-parameter case ## Why the Filter button is hidden in VA mode Worth calling out, because it is the one thing that would otherwise look like an omission: in `va` mode the report owns the filter, and the two mechanisms are alternatives rather than layers. A filter built in Data Controller is replaced the next time the report's selection changes, and vice versa. Showing the button there would offer a filter that silently stops applying as soon as the report is touched, so it is hidden rather than disabled. The page says this explicitly now, after the embed-mode table. Making them *interoperable* (for example AND-ing a Data Controller filter with the report's parameters) is a real change, not a UI tweak, and is out of scope for this release: every apply path converges on "save one filter, reload at `/editor/<table>/<FILTER_RK>`", so combining them means defining the combination rule, reading the stored filter's clauses back client-side, and reworking the signature/dedup that currently stops the VA replay fighting itself. That is its own PR. ## The embed modes are now described in full The table has a fourth column (which value lets the report drive filtering and columns), and `va` mode is described by what it actually changes, not just the Filter button: - filtering from the report, live or confirm, with the first load already filtered - column visibility taken from the columns the report sends (primary keys always kept) - the Filter button is not offered, and the two filter mechanisms are alternatives rather than layers - Add Record is not offered - a "Back to Edit table" bar appears on the stage / approve / review pages `true` is described as chrome-hiding only. ## Also covers date anchors The same page now documents the `ADD(...)` / `RANGE(...)` anchors on a mapping (dc/dc#386, stacked on #383). Both land together, so the page stays one description of `va_parmap` rather than two.

hermes added 1 commit 2026-10-28 10:47:24 +00:00

docs(embed): document va_parmap, the mapping warnings and the Filter button per mode b88002a752

The SAS Visual Analytics Embed page now covers mapping report parameters to
DC columns from the URL, which the name-based match cannot do for two report
objects filtering the same column from differently-named parameters.

- new "Mapping parameters to columns" section: the `va_parmap` grammar, the
  lower-case example, what overrides what, and the rules that matter to a
  report author (last-hyphen split, label-then-name key matching, one parameter
  to one column, no fallback to the name match)
- the warning banner is documented next to it, including that a parameter is
  ignored rather than filtered on the wrong column
- the `?embed=` table now shows the Filter button per mode, so it is explicit
  that `embed=true` keeps Data Controller's own filter builder while `embed=va`
  hands filtering to the report

hermes marked the pull request as work in progress 2026-10-28 10:47:29 +00:00

hermes added 1 commit 2026-10-28 10:47:52 +00:00

docs(embed): say why the Filter button is hidden in va mode 75a97e6300

hermes added 1 commit 2026-10-28 10:51:38 +00:00

docs(embed): describe everything va mode changes, not just the Filter button 17bdecff89

hermes added 1 commit 2026-10-28 10:52:18 +00:00

docs(embed): drop the jargon, name the header and navigation instead 73222aa9bd

hermes added 1 commit 2026-10-28 11:53:24 +00:00

docs(embed): document va_parmap date anchors 4623bfa5e2

hermes added 1 commit 2026-10-28 12:32:43 +00:00

docs(embed): the mapping key matches the parameter label only d4e7c26f13

hermes added 1 commit 2026-10-28 12:59:23 +00:00

docs(embed): show the mapping, the warning banner and a date anchor 24e088d663

Screenshots taken against the demo estate with a licence key installed, so
no evaluation banner appears. The banner section now tabulates every cause
the editor reports, because the reader is the report author looking at the
Data Controller object and the URL is the only thing they can edit.

hermes added 1 commit 2026-10-28 13:07:23 +00:00

docs(embed): a configuration walkthrough for the VA Report Designer 91c49a27c5

Replaces the two-sentence section with the steps a report author needs:
where the URL goes, that the parameter has to be bound into the object's
query or VA never sends it, and how to tell a working mapping from a broken
one when the report runs. Also drops the note about intnx argument names,
which was explaining a decision rather than the behaviour.

hermes added 1 commit 2026-10-28 15:44:30 +00:00

docs(embed): the object runs as the viewer, who must be a DC user 6367ed2f43

Found by testing a report against a freshly configured instance: the DC
object showed its login card inside the report because the viewer's SAS
identity was not registered yet, which reads as a broken embed rather than
a permissions problem.

hermes marked the pull request as ready for review 2026-10-28 17:14:45 +00:00

hermes added 1 commit 2026-10-28 17:14:54 +00:00

docs(embed): review pass before the release 6af7692f97

- the link to va-messaging.service.ts opened with a backtick and closed with a
  quote, so it rendered as broken text
- the URL example was a plain URL wrapped in backticks inside a fenced block,
  which shows the backticks; it is a text fence with the bare URL now
- restored the space the "updated- all from inside the same report" sentence lost
- closed the sentence about brush columns, and spelled out "primary key columns"
- two causes the banner reports were missing from the table: an entry with no
  parameter before the "-", and a parameter mapped to two columns (the first
  entry wins). Both come from parseVaParmap, so the table now covers every
  message the banner can carry.

Checked against the merged code on release/7.20 (00df87f): the embed values and
their effects, the split at the last hyphen, the case-insensitive label match,
the plain-SAS-name rule, the anchor and period names, and the banner wording.
Tables are consistent, fences balanced, page is ASCII only, and both cross-links
(/filter/ and /developer-guide/browser-variables/) resolve.

hermes referenced this pull request from dc/dc

2026-10-28 17:54:59 +00:00

Release/7.20 #387

allan merged commit 1587530d9c into main

2026-10-28 17:56:05 +00:00

allan deleted branch docs/va-param-map

2026-10-28 17:56:05 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dc/docs.datacontroller.io#26