Merge pull request 'docs(va): show Data Controller inside a real VA report' (#28) from docs/va-report-screenshots into main

Reviewed-on: #28

docs/visual-analytics.md

@@ -50,6 +50,10 @@ VA pushes a JSON payload to the iframe via `window.postMessage` whenever the sel
 
 If VA sends an empty / unmatched message the editor falls back to the unfiltered view but stays in VA mode.
 
+The applied filter is shown above the grid, so what the report did to the editor is visible without touching it.  In the report below, three report parameters - `SOME_CHAR`, `SOME_DROPDOWN` and `SOME_NUM` - reach one Data Controller object, and the editor shows both the combined filter and the single row it matches:
+
+![Three report parameters driving the embedded editor](img/va-report-filters.png)
+
 More logic available in [`va-messaging.service.ts`](https://git.datacontroller.io/dc/dc/src/branch/main/client/src/app/services/va-messaging.service.ts).
 
 ## Mapping parameters to columns
@@ -168,6 +172,10 @@ The mapping lives entirely in the URL of the report object, so the job is to get
 
     Everything before the `#` is the normal deployment URL; the `#/editor/...` part is the DC route, and `?embed=va` plus the `va_parmap` entries are what this page describes.  One object per report tab, each with its own entry, is what lets two tabs filter the same column differently.
 
+    The URL is a property of the object, not a data source: it lives in **Options > Web Content > URL**, and the object needs no data assigned for Data Controller to open its own table.  In the designer that section looks like this (the field is scrolled to the end of a long URL):
+
+    ![The Web Content URL property on a Data-driven content object](img/va-report-object-options.png)
+
 3. **Make the parameter reach the object.**  VA sends an object only the parameters its query uses.  A report parameter that the object's data does not reference never arrives, and the mapping then has nothing to map - DC reports it as `VA is not sending ...` in the banner.  So bind the parameter into the object (assign it as a source on the object's query, as you would for any other visual), rather than only defining it at report level.
 
 4. **Save the report**, then open it.  DC shows the applied filter above the grid, so a correct mapping is visible without opening the editor:
@@ -187,6 +195,8 @@ The object runs as the person **viewing** the report, using their SAS identity -
 
 Register everyone who will open the report before you ship it (Users in DC), and test the report as one of them rather than as the person who built it - the author often has elevated permissions, so a report that works for them can fail for everyone else.
 
+The deployment itself has to be licensed and past its End User License Agreement before it is embedded, for the same reason: an unlicensed instance shows the licensing screen (the agreement, then the free tier until a key is uploaded) inside the object, which reads as a broken embed rather than as setup that was never finished.  Accept the agreement and register the key by opening the deployment directly, then reload the report.
+
 ## Debugging
 
 A hook script can tell an embedded editor from a standalone one without any client-side inspection: `work.browser_info` carries the page URL and `referrer`, and `work.browser_url_vars` carries `embed=va`. See [Browser Variables](/developer-guide/browser-variables/).
@@ -195,4 +205,6 @@ The following snippet can be used in console to dump the values being provided t
 
 ```
 console.log(JSON.stringify(window.__vaLastMessage?.data, null, 2))
-```
+```
+
+Each entry in its `parameters` array carries a `label`, and that label is what a `va_parmap` entry has to match (and what the name match uses when there is no entry).  When a mapping appears to do nothing, compare the labels in this dump with the left-hand side of the entries in the object's URL - a parameter that VA labels differently from what was typed in the URL is silently a different parameter.