From 4623bfa5e2d2ede9fbf447047e7a20932957f04e Mon Sep 17 00:00:00 2001 From: dc Date: Wed, 28 Oct 2026 11:53:23 +0000 Subject: [PATCH] docs(embed): document va_parmap date anchors --- docs/embed-va.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/embed-va.md b/docs/embed-va.md index 2abfcdd..c335661 100644 --- a/docs/embed-va.md +++ b/docs/embed-va.md @@ -84,6 +84,40 @@ If an entry cannot be used the editor shows a warning banner above the grid nami !!! 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//?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(,)` | the value, plus one anchor beside it | `D_DATE IN (01OCT2026, 01JUL2026)` | +| `RANGE(,)` | 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: