Merge pull request 'docs(va): in-report screenshots for the mapping and the banner' (#30 ) from docs/va-in-report-images into main

Reviewed-on: #30
docs(va): in-report screenshots for the mapping and the banner
2026-10-29 14:38:26 +00:00 · 2026-10-29 14:25:32 +00:00 · 2026-10-29 14:05:23 +00:00 · 2026-10-29 13:26:13 +00:00 · 2026-10-29 13:14:15 +00:00 · 2026-10-29 12:59:06 +00:00
16 changed files with 250 additions and 75 deletions
@@ -3,6 +3,13 @@ on:
  push:
    branches:
      - main
  workflow_dispatch:
 # One deploy at a time: `surfer deploy` swaps the site atomically, so two runs
 # racing is not corruption, but it is a wasted build and the last swap wins.
 concurrency:
  group: surfer-docs
  cancel-in-progress: false
 jobs:
  build:
@@ -19,7 +26,7 @@ jobs:
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
-          python-version: '3.12'  # Specify your desired version (e.g., 3.10 or 3.12)
+          python-version: '3.12'  # Specify your desired version (e.g. 3.10 or 3.12)
        env:
          AGENT_TOOLSDIRECTORY: /opt/hostedtoolcache
          RUNNER_TOOL_CACHE: /opt/hostedtoolcache
@@ -31,13 +38,6 @@ jobs:
          apt install -y ./google-chrome*.deb;
          export CHROME_BIN=/usr/bin/google-chrome
      # Deploy tooling is pinned to exact versions: the workflow builds whatever
      # is committed, and an unpinned `latest` would let a breaking or
      # compromised upstream release ship straight to the live site.
      - name: Install Surfer
        run: |
          npm -g install cloudron-surfer@6.4.1
      - name: build site
        run: |
          pip install mkdocs==1.6.1
@@ -48,5 +48,29 @@ jobs:
          mkdir site/slides
          npx @marp-team/marp-cli@4.5.1 slides/innovation/innovation.md -o ./site/slides/innovation/index.html
          npx @marp-team/marp-cli@4.5.1 slides/if/if.md -o site/if.pdf --allow-local-files --html=true
      # Deploy tooling is pinned to exact versions: the workflow builds whatever
      # is committed, and an unpinned `latest` would let a breaking or
      # compromised upstream release ship straight to the live site.
      #
      # `deploy` (v7) replaces the site atomically - it extracts to a staging
      # folder and swaps it in, so a failed upload leaves the current site
      # serving.  The v6 `put` this replaces was token authenticated, and v7
      # takes the Cloudron username plus an app password instead.
      #
      # The docs live in a NAMED site, `docs`, served at its own alias domain -
      # not the app's default site - so the name and the domain are both passed.
      - name: Deploy docs
-        run: surfer put --token ${{ secrets.SURFERKEY }} --server docs.datacontroller.io site/* /
+        env:
          SURFER_PASSWORD: ${{ secrets.SURFER_PASSWORD }}
          REF_NAME: ${{ gitea.ref_name }}
          COMMIT_SHA: ${{ gitea.sha }}
        run: |
          set -euo pipefail
          npx --yes @cloudron/surfer@7.2.0 deploy site \
            --server docs.datacontroller.io \
            --username allan \
            --password "$SURFER_PASSWORD" \
            --site-name docs \
            --domain docs.datacontroller.io \
            --message "Build from ${REF_NAME} @ ${COMMIT_SHA:0:8}"
@@ -175,4 +175,4 @@ It is possible to embed a Data Controller table within SAS Visual Analytics by s
 To make the portlet more visually appealing, the Data Controller title bar can be removed by adding `?embed=true` to the URL.  When opening in a new window, the title bar will be gone.
-For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead.  See the [SAS Visual Analytics Embed](/embed-va/) page for details on filter modes, configuration, and debugging.
+For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead.  See the [SAS Visual Analytics Embed](/visual-analytics/) page for details on filter modes, configuration, and debugging.
@@ -1,62 +0,0 @@
 ---
 layout: article
 title: SAS Visual Analytics Embed
 description: Embed the Data Controller editor inside a SAS VA report as a data-driven content object.  Row selections in the VA report drive filters and column visibility in the editor.
 ---
 # Embedding inside SAS Visual Analytics
 Data Controller can be embedded inside a SAS Visual Analytics report as a **data-driven content** (DDC) object.  This unlocks scenarios where a user can safely modify the values in an underlying SAS table, and have the visualisation updated- all from inside the same report.
 ## URL
 Open the editor as a DDC by appending `?embed=va` to the editor route:
 ```
 `https://yourserver/DC/#/editor/<library>/<table>?embed=va`
 ```
 The `?embed=` parameter accepts three values:
 | Value | Behaviour |
 |---|---|
 | `true`  | Chrome (header, back button, sub-nav) is hidden.  Editor functions normally. |
 | `va`    | Same chrome-hiding as `true`, **plus** editor becomes "VA-aware" - any report filters are captured, and columns can be displayed / hidden using the Edit Report interface.  Filter button is disabled (use VA filters instead)|
 | `false` (or omitted) | Standard interactive UI. |
 ## How VA drives the editor
 VA pushes a JSON payload to the iframe via `window.postMessage` whenever the selected rows change.  Data Controller listens for these messages and:
 1. Resolves each VA `parameter` to a DC column by matching on column label.
 2. Builds a filter (using existing [Filter](/filter/) machinery) over the selected values.
 3. Hides any VA columns marked as `brush` so the grid stays focused on the user-editable columns (except primary key cols which are always shown)
 If VA sends an empty / unmatched message the editor falls back to the unfiltered view but stays in VA mode.
 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).
 ## Filter Modes
 When running in `embed=va` mode, the editor provides two filter modes, controlled by the **Auto-apply** checkbox:
 * **Live (default)** - the editor updates automatically as you select rows in the VA report, so the data you see always matches your current selection.
 * **Confirm** - filter changes are held until you click the **Apply** button.  This is useful when editing, where an automatic reload would discard unsaved changes.
 A status indicator shows whether a filter change is pending, loading, or idle.  In edit mode, a pending filter is held until you leave edit mode, so your unsaved edits are never lost.
 ## Configuration in VA
 In the VA Report Designer, add a **Data-Driven Content** object and set the URL to the editor route shown above.  Be sure that any report level filters have their corresponding parameters added to the DDC object itself.
 ## 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/).
 The following snippet can be used in console to dump the values being provided to DC from VA:
 ```
 console.log(JSON.stringify(window.__vaLastMessage?.data, null, 2))
 ```
@@ -7,7 +7,7 @@ og_image:  https://docs.datacontroller.io/img/filter_dynamic_on.png
 # Filtering
-Data Controller for SAS&reg; enables you to create complex table filters. The "dynamic" setting enables the dropdown values to be pre-filtered by previous filter clauses.  Filtered views are shareable!  They are also used when [embedded in VA.](/embed-va)
+Data Controller for SAS&reg; enables you to create complex table filters. The "dynamic" setting enables the dropdown values to be pre-filtered by previous filter clauses.  Filtered views are shareable!  They are also used when [embedded in VA.](/visual-analytics/)
 The clause shown above the grid is the resolved WHERE clause that was applied, so it uses SAS syntax - a date, datetime or time filter reads as a SAS literal, eg `SOME_DATE = '20APR2042'd`, rather than the internal day or second count.
@@ -42,7 +42,7 @@ Data Controller is regularly updated with new features.  If you see something th
 * [Row Level Security](/row-level-security)
 * Excel [formula support](excel)
 * Dynamic [cell dropdown](/dynamic-cell-dropdown)
-* [SAS Visual Analytics embed](/embed-va/) - drive the editor from VA report selections
+* [SAS Visual Analytics embed](/visual-analytics/) - drive the editor from VA report selections
 * Works on ALL flavours of SAS (Base, EBI, Viya)
@@ -0,0 +1,212 @@
 ---
 layout: article
 title: SAS Visual Analytics Embed
 description: Embed the Data Controller editor inside a SAS Visual Analytics report as a data-driven content object, so report selections drive filters and column visibility in the editor.
 og_title: Embedding Data Controller in SAS Visual Analytics
 og_image: https://docs.datacontroller.io/img/va-embed-og.png
 ---
 # Embedding inside SAS Visual Analytics
 Data Controller can be embedded inside a SAS Visual Analytics report as a **data-driven content** (DDC) object.  This unlocks scenarios where a user can safely modify the values in an underlying SAS table, and have the visualisation updated - all from inside the same report.
 ## URL
 Open the editor as a DDC by appending `?embed=va` to the editor route:
 ```text
 https://yourserver/DC/#/editor/<library>/<table>?embed=va
 ```
 The `?embed=` parameter accepts three values:
 | Value | Data Controller header and navigation | Filter button | Report drives filtering and columns |
 |---|---|---|---|
 | `true` | hidden | **shown** - Data Controller's own filter builder works as usual | no |
 | `va` | hidden | **hidden** - filtering comes from the report instead | yes |
 | `false` (or omitted) | shown | shown | no |
 The header and navigation means the Data Controller title bar (with its user menu), the back button and the sub-nav - everything Data Controller would normally show around the grid.
 `embed=true` hides that and nothing else: the editor behaves exactly as it does outside a report, including the Filter button, Add Record, and any filtering you apply yourself.
 `embed=va` hides the same furniture **and** hands these over to the report:
 - **filtering** - the report's filters are captured and applied as selections change, in either live mode or confirm mode (see Filter Modes below).  The first table load is already filtered, so there is no unfiltered flash.
 - **column visibility** - the grid shows the columns the report sends, controlled from the report's Edit Report interface; primary-key columns are always kept visible.
 - **the Filter button is not offered** - filtering belongs to the report in this mode.
 - **Add Record is not offered** - rows are still added from Edit mode's "Add Row".
 - **a "Back to Edit table" bar** appears on the stage, approve and review pages, so a user who follows the review workflow can return to the editor without knowing Data Controller's page paths.
 The two filters are not combined.  A filter built inside Data Controller and a filter driven by the report are alternatives, not layers: applying one replaces the other, and in `va` mode the report's filter is re-applied the next time the selection changes.  Showing the button there would offer a filter that silently stops applying as soon as the report is touched, which is why it is hidden rather than disabled.
 ## How VA drives the editor
 VA pushes a JSON payload to the iframe via `window.postMessage` whenever the selected rows change.  Data Controller listens for these messages and:
 1. Resolves each VA `parameter` to a DC column by matching on column label.
 2. Builds a filter (using existing [Filter](/filter/) machinery) over the selected values.
 3. Hides any VA columns marked as `brush` so the grid stays focused on the user-editable columns (primary key columns are always shown).
 If VA sends an empty / unmatched message the editor falls back to the unfiltered view but stays in VA mode.
 In the report below, two report parameters - `SOME_DROPDOWN` and `SOME_DATE` - reach one Data Controller object, and the editor shows both the combined filter and the rows it matches:
 ![A value and a date parameter filtering 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
 By default each VA `parameter` is matched to a DC column by name: a parameter whose label is a column of the table filters that column.  That means two DC instances in the same report can only filter the same column from a parameter of the same name - so two report tabs cannot hold different filters on one column.
 The `va_parmap` URL parameter overrides the name match, one entry per mapping, `<VA parameter>-<DC column>`:
 ```text
 https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=REGION_TAB1-REGION
 ```
 Repeat the parameter to add mappings.  A report with two tabs, each holding its own instance of the same table and filtering the same column from its own report parameter:
 | Report tab | DDC URL |
 |---|---|
 | Tab 1 | `...?embed=va&va_parmap=REGION_TAB1-REGION` |
 | Tab 2 | `...?embed=va&va_parmap=REGION_TAB2-REGION` |
 The applied filter is visible in the editor, above the grid - here the parameter `DROPDOWN_TAB1` filtering `SOME_DROPDOWN`, which is not its name (the date parameter beside it is name-matched, which is the default):
 ![A va_parmap mapping filtering a column](img/va-parmap-filtered.png)
 The mapping is per parameter, and additive:
 - a mapped parameter always filters the column it names; that column's type in the table decides how the value is formatted, exactly as for a name match
 - a parameter with no mapping keeps the default name match, so a single instance can mix mapped and unmapped parameters
 - the key is matched case-insensitively against the parameter's label
 - an entry is split at its last `-`, so a label may itself contain hyphens (`Sales-2024-DEPT` maps the label `Sales-2024` to `DEPT`)
 - if the named column is not in the table being opened, the parameter is ignored rather than falling back to the name match - a typo cannot silently filter the wrong column
 - a column name that is not a plain SAS name is ignored
 - the mapping applies to filtering only; which columns the grid displays still follows the columns VA sends
 ## When a mapping cannot be used
 A wrong mapping would otherwise look like a working filter over the whole table, so the editor puts a banner above the grid naming the parameter, the column, the table, and what to change:
 ![The va_parmap warning banner](img/va-parmap-banner.png)
 Each line names one cause, and the parameter it concerns is skipped rather than falling back to the name match - a typo never silently filters the wrong column:
 | What the banner says | What it means |
 |---|---|
 | `is not a column of <libref>.<table>` | the mapped column does not exist in the table being opened |
 | `is not a date or datetime column` | a date anchor (`ADD`/`RANGE`) was applied to a column that holds something else |
 | `VA is not sending` | no message has named that parameter - usually a spelling mistake in the parameter side of the entry |
 | `all filter <COLUMN> ... different values will show no rows` | two parameters map to one column with different values, so the AND can never match |
 | `a range needs one value` | a `RANGE` mapping was sent several values - one `BETWEEN` carries one period |
 | `N of its M values was not a date` | part of a multi-value parameter could not be read as a date, so only the rest is applied |
 | `was ignored: it needs a "-"` / `is not a transform` | the entry itself is malformed |
 | `the VA parameter name is missing` | the entry starts with the `-`, so there is no parameter to map |
 | `already maps to <COLUMN>, and a parameter can filter only one column` | the same parameter is mapped twice; the first entry wins |
 The banner is shown to the report author, inside the report, because that is where the entry is edited: the only fix available from the editor is to change the `va_parmap` entries in the URL of the Data Controller object.
 !!! note
    A parameter label containing `&` must be percent-encoded (`%26`), because `&` separates query parameters.  A space may be written as `+` or `%20`.
 ## Deriving dates from a parameter value
 A mapping can resolve the parameter value through a **named date anchor** before the filter is built, by appending a transform to the column name:
 ```text
 https://yourserver/DC/#/editor/<library>/<table>?embed=va&va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1)
 ```
 A report that sends `SELECTED_DATE = 27FEB1961` then filters `D_DATE` on 1961-02-27 **and** 1960-10-01 - the selected date, plus the same point one quarter earlier.
 The clause carries both values, so the row for the selected date and the row for the previous quarter are both included.
 | Transform | Result | Filter |
 |---|---|---|
 | `ADD(<anchor>,<offset>)` | the value, plus one anchor beside it | `D_DATE IN (01OCT2026, 01JUL2026)` |
 | `RANGE(<period>,<offset>)` | one closed period | `D_DATE BETWEEN 01APR2026 AND 30JUN2026` |
 The anchors are `QUARTER_START`, `QUARTER_END`, `MONTH_START`, `MONTH_END`, `YEAR_START` and `YEAR_END`; the periods are `QUARTER`, `MONTH` and `YEAR`.  The offset is a whole number of periods - negative for earlier - and defaults to `0`.  Names and arguments are case-insensitive.
 ```text
 va_parmap=SELECTED_DATE-D_DATE:ADD(QUARTER_START,-1)
 va_parmap=SELECTED_DATE-D_DATE:ADD(MONTH_END,-1)
 va_parmap=SELECTED_DATE-D_DATE:RANGE(QUARTER,-1)
 va_parmap=SELECTED_DATE-D_DATE:ADD(YEAR_START,-1)
 ```
 Notes:
 - the arithmetic is anchored on the parameter's value, never on today, so a saved report selects the same rows whenever it is opened
 - the result is always a single filter clause, so a transform combines with other parameters exactly as an unmapped one does
 - a transform only applies to date and datetime columns; on any other column the parameter is ignored and the warning banner says so
 - the offset is a whole number; unknown anchors, periods and operations are rejected with a warning naming the entry
 ## Filter Modes
 When running in `embed=va` mode, the editor provides two filter modes, controlled by the **Auto-apply** checkbox:
 * **Live (default)** - the editor updates automatically as you select rows in the VA report, so the data you see always matches your current selection.
 * **Confirm** - filter changes are held until you click the **Apply** button.  This is useful when editing, where an automatic reload would discard unsaved changes.
 A status indicator shows whether a filter change is pending, loading, or idle.  In edit mode, a pending filter is held until you leave edit mode, so your unsaved edits are never lost.
 ## Configuration in VA
 The mapping lives entirely in the URL of the report object, so the job is to get the right URL onto a **Data-driven content** object and make sure the parameters it names actually reach it.
 1. **Add the object.**  In the VA Report Designer, insert a **Data-Driven Content** object, or select the one already on the page.
 2. **Point it at Data Controller.**  Open **Options** on the right and paste the SAS Job Execution URL of your DC deployment into **Web Content URL**, with `embed=va` and one `va_parmap` entry per parameter:
    ```text
    https://yourserver/SASJobExecution/?_file=/YOUR/APPLOC/services/DC.html#/editor/YOURLIB.YOURTABLE?embed=va&va_parmap=REGION_TAB1-REGION
    ```
    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:
    ```text
    FILTER : ( ( REGION = 'Europe' ) )
    ```
    A date parameter arrives as a display date and is rendered as a SAS date literal, the same as a date filter built inside Data Controller:
    ```text
    FILTER : ( ( SOME_DROPDOWN = 'Option 1' AND SOME_DATE BETWEEN '01JAN1960'd AND '31MAR1960'd ) )
    ```
    Something wrong shows the banner instead, with the cause and the fix - see [When a mapping cannot be used](#when-a-mapping-cannot-be-used) above.
 !!! note
    The URL is read when the object loads, so a change to `va_parmap` takes effect when the report (or the page holding the object) is next opened.
 ### Who the object runs as
 The object runs as the person **viewing** the report, using their SAS identity - there is no service account behind it. That person must therefore be a registered Data Controller user: if they are not, DC shows its login card inside the object instead of the editor, which looks like a broken embed rather than a permissions matter.
 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/).
 The following snippet can be used in console to dump the values being provided to DC from VA:
 ```
 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.
@@ -73,7 +73,7 @@ nav:
    - Selectboxes: dcc-selectbox.md
    - Tables: dcc-tables.md
    - Validations: dcc-validations.md
-    - Visual Analytics: embed-va.md
+    - Visual Analytics: visual-analytics.md
 - Macros: macros.md
 - Installation:
    - System Requirements: dci-requirements.md
@@ -113,6 +113,7 @@ plugins:
      redirect_maps:
          'dci-evaluation.md': 'dci-deploysas9.md'
          'dcu-fileupload.md': 'files.md'
          'embed-va.md': 'visual-analytics.md'
 # Repository
 repo_name: 'dc/docs.datacontroller.io'
Author	SHA1	Message	Date
allan	428e8e7fa1	Merge pull request 'docs(va): in-report screenshots for the mapping and the banner' (#30 ) from docs/va-in-report-images into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m4s Details Reviewed-on: #30	2026-10-29 14:38:26 +00:00
dc	c7bbdee3c6	docs(va): in-report screenshots for the mapping and the banner Both images on the embed page were still captured from a local sandbox with the editor as the top-level document, so neither showed the report around it. - va-parmap-filtered.png: the report viewer, prompt DROPDOWN_TAB1 (relabelled on the report, not matching any column) and SOME_DATE, with FILTER : ( ( SOME_DROPDOWN = 'Option 1' AND SOME_DATE = '01JUL1960'd ) ) over 21 rows - the mapped parameter filtering a column that is not its name - va-parmap-banner.png: the same object with a malformed entry (va_parmap=SOME_DATE, no hyphen), showing the warning banner over a populated, filtered grid The caption for the mapping now says the date parameter beside it is name-matched, which is what the picture shows. va-parmap-transform.png is removed rather than replaced: the deployment used for these captures predates the ADD/RANGE work, so there is no honest in-report picture of a date anchor to take, and a sandbox capture would be the one image on the page without the report around it. The section keeps the syntax, the anchors and the examples table.	2026-10-29 14:25:32 +00:00
dc	b20c3f3507	docs(va): filter shot with rows to see, and no wrapperless crop Captured from the report viewer at 1920x1100: two prompts (a value list and a date), 21 rows returned by FILTER : ( ( SOME_DROPDOWN = 'Option 1' AND SOME_DATE = '01JUL1960'd ) ). - drops the header/FILTER crop, which had no VA chrome, and the sentence it illustrated - drops the "single row it matches" wording, which no longer describes the picture - documents the date clause as a code block instead of a second image	2026-10-29 14:05:23 +00:00
allan	86eab571c0	Merge pull request 'docs(va): two-parameter report shot with a date literal' (#29 ) from docs/va-report-screenshots into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m6s Details Reviewed-on: #29	2026-10-29 13:26:13 +00:00
dc	f803656936	docs(va): two-parameter report shot with a date literal Replaces the three-parameter screenshot with a two-parameter one - a value list and a date - and adds a zoomed crop of the DC header and FILTER line. The date parameter arrives as a display date and is rendered as a SAS date literal ('12FEB1960'd), the same as a date filter built inside Data Controller. That is worth showing because VA's own prompt containers in the report header show only the parameter label: the FILTER line is where the selected values are legible.	2026-10-29 13:14:15 +00:00
allan	bd736bc91c	Merge pull request 'docs(va): show Data Controller inside a real VA report' (#28 ) from docs/va-report-screenshots into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m6s Details Reviewed-on: #28	2026-10-29 12:59:06 +00:00
dc	5d9a133261	docs(va): show Data Controller inside a real VA report Adds the two screenshots the embed page was missing, both captured from a Viya deployment with Data Controller embedded as a data-driven content object: - three report parameters (SOME_CHAR, SOME_DROPDOWN, SOME_NUM) reaching one object, with the combined FILTER line and the single matching row in the editor - the object's Options pane, showing the URL as a Web Content property rather than a data source Also documents two things that make an embedded object look broken when the deployment is fine: the URL is an object property and the object needs no data assigned, and an unlicensed / not yet accepted deployment shows its licensing screen inside the object. The debugging section now says the parameter label in the postMessage payload is the key va_parmap matches.	2026-10-29 12:52:26 +00:00
allan	6af8d77d80	Merge pull request 'docs(va): move the embed page to /visual-analytics, redirect the old path' (#27 ) from docs/visualanalytics into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m22s Details Reviewed-on: #27	2026-10-29 10:36:01 +00:00
dc	8839ebd8ce	docs(va): use /visual-analytics/ for the embed page The route is hyphenated like the other multi-word docs paths (dcc-*, pre-edit-hook). The page has not been published under /visualanalytics/, so only the embed-va redirect map needs to point at the final path.	2026-10-29 10:35:44 +00:00
dc	3435c17c26	docs(va): move the embed page to /visualanalytics - rename docs/embed-va.md -> docs/visualanalytics.md, so the page is served at /visualanalytics/ - redirect the old /embed-va/ path to the new one - point the three inbound links (index, filter, deploy-viya) at the new path - fill in og_title and og_image so link previews carry the page title and a card image instead of the site defaults - the object's author often has elevated permissions, not usually an admin	2026-10-29 10:29:07 +00:00
allan	1587530d9c	Merge pull request 'docs(embed): document va_parmap and the Filter button per embed mode' (#26 ) from docs/va-param-map into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m23s Details Reviewed-on: #26	2026-10-28 17:56:05 +00:00
dc	6af7692f97	docs(embed): review pass before the release - 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.	2026-10-28 17:14:27 +00:00
dc	6367ed2f43	docs(embed): the object runs as the viewer, who must be a DC user 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.	2026-10-28 15:44:29 +00:00
dc	91c49a27c5	docs(embed): a configuration walkthrough for the VA Report Designer 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.	2026-10-28 13:07:22 +00:00
dc	24e088d663	docs(embed): show the mapping, the warning banner and a date anchor 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.	2026-10-28 12:59:22 +00:00
dc	d4e7c26f13	docs(embed): the mapping key matches the parameter label only	2026-10-28 12:32:42 +00:00
dc	4623bfa5e2	docs(embed): document va_parmap date anchors	2026-10-28 11:53:23 +00:00
dc	73222aa9bd	docs(embed): drop the jargon, name the header and navigation instead	2026-10-28 10:52:17 +00:00
dc	17bdecff89	docs(embed): describe everything va mode changes, not just the Filter button	2026-10-28 10:51:37 +00:00
dc	75a97e6300	docs(embed): say why the Filter button is hidden in va mode	2026-10-28 10:47:46 +00:00
dc	b88002a752	docs(embed): document va_parmap, the mapping warnings and the Filter button per mode 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	2026-10-28 10:47:14 +00:00
allan	c5b5acbcbc	Merge pull request 'ci(publish): deploy the docs site with surfer 7 and an app password' (#25 ) from ci/surfer-app-password into main Publish to docs.datacontroller.io / Deploy docs (push) Successful in 1m19s Details Reviewed-on: #25	2026-10-28 00:42:12 +00:00
dc	982cf5b28e	ci(publish): deploy the docs site with surfer 7 and an app password The publish job installed cloudron-surfer 6.4.1 and uploaded with a token; the current major takes a Cloudron username plus an app password instead. Pin @cloudron/surfer 7.2.0, user allan, password from SURFER_PASSWORD. `deploy` rather than `put`: it swaps the site atomically, so a failed upload leaves the current site serving, and it records the ref and commit in the site's deploy history. The docs are a named site (`docs`) on its own alias domain, so both are passed. Also adds workflow_dispatch, so a deploy can be run by hand.	2026-10-28 00:40:41 +00:00
allan	41a8961905	Merge pull request 'docs(7.19): publish derived variables - banners off, nav titles clean, roadmap entry' (#24 ) from docs/7.19-release into main Publish to docs.datacontroller.io / Deploy docs (push) Failing after 1m33s Details Reviewed-on: #24 Reviewed-by: Allan <allan@4gl.io>	2026-10-28 00:23:50 +00:00
dc	9fd1d1ef65	docs(derived): the stills are framed for the page, not for the browser The 1920x900 captures left two thirds of each image as empty grid canvas, and shrank the UI to about a third of its CSS size once the page rendered them at content width - unreadable on a tablet. Re-taken at 1024 CSS px and captured at 2x device pixels, so they stay crisp on a retina screen, and clipped to just below the data rows, so the image is mostly table. The configuration still stays in the viewer: the EDIT screen adds a current-version filter bar whose text is a macro expression.	2026-10-28 00:15:38 +00:00
`@@ -175,4 +175,4 @@ It is possible to embed a Data Controller table within SAS Visual Analytics by s`

	To make the portlet more visually appealing, the Data Controller title bar can be removed by adding `?embed=true` to the URL. When opening in a new window, the title bar will be gone.	To make the portlet more visually appealing, the Data Controller title bar can be removed by adding `?embed=true` to the URL. When opening in a new window, the title bar will be gone.

	For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead. See the [SAS Visual Analytics Embed](/embed-va/) page for details on filter modes, configuration, and debugging.	For a deeper VA integration - where report row selections drive filters and column visibility in the Data Controller editor - append `?embed=va` instead. See the [SAS Visual Analytics Embed](/visual-analytics/) page for details on filter modes, configuration, and debugging.