docs.datacontroller.io/docs/embed-va.md

---
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 | 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 (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).

## 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 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

If an entry cannot be used the editor shows a warning banner above the grid naming the parameter, the column and the table - for example when the column is not in the table being opened, or the entry is not in the `parameter-column` form.  The parameter is then ignored rather than falling back to the name match, so a typo never silently filters the wrong column, and the banner is what distinguishes "the mapping is wrong" from a view that simply has no filter.

!!! 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 = 01OCT2026` then filters `D_DATE` on 2026-10-01 **and** 2026-07-01 - the selected date's quarter, plus the same point one quarter earlier.

| 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

!!! note
    The anchor names describe the resulting date rather than mirroring SAS `intnx` arguments.  The arithmetic runs in the browser, so a URL that reads like an `intnx` call would not always behave like one.

## 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))
```