@epistola.app/valtimo-plugin 0.10.0 → 0.11.0

package/lib/components/check-job-status-configuration/check-job-status-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent } from '@valtimo/plugin';
+import { FunctionConfigurationComponent, FunctionConfigurationData } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { CheckJobStatusConfig } from '../../models';
@@ -10,7 +10,7 @@ export declare class CheckJobStatusConfigurationComponent implements FunctionCon
     pluginId: string;
     prefillConfiguration$: Observable<CheckJobStatusConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<CheckJobStatusConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;

package/lib/components/download-document-configuration/download-document-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent } from '@valtimo/plugin';
+import { FunctionConfigurationComponent, FunctionConfigurationData } from '@valtimo/plugin';
 import { FormOutput, SelectItem } from '@valtimo/components';
 import { BehaviorSubject, Observable } from 'rxjs';
 import { DownloadDocumentConfig } from '../../models';
@@ -10,7 +10,7 @@ export declare class DownloadDocumentConfigurationComponent implements FunctionC
     pluginId: string;
     prefillConfiguration$: Observable<DownloadDocumentConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<DownloadDocumentConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     private saveSubscription;
     private readonly formValue$;
     private readonly valid$;

package/lib/components/epistola-admin-page/epistola-admin-page.component.d.ts

@@ -1,7 +1,7 @@
 import { OnInit } from '@angular/core';
 import { ActivatedRoute, Router } from '@angular/router';
 import { EpistolaAdminService } from '../../services/epistola-admin.service';
-import { BpmnValidationReport, BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, FormCarrierIssue, PendingJob, PluginUsageEntry } from '../../models';
+import { BpmnValidationReport, BpmnValidationViolation, ChangelogRelease, ClasspathCatalog, FormCarrierIssue, LegacyOverrideForm, PendingJob, PluginUsageEntry } from '../../models';
 import * as i0 from "@angular/core";
 /**
  * Combined view model for a single plugin configuration card.
@@ -55,6 +55,8 @@ export declare class EpistolaAdminPageComponent implements OnInit {
         type: 'success' | 'error';
         message: string;
     } | null;
+    legacyOverrideForms: LegacyOverrideForm[] | null;
+    legacyOverrideLoading: boolean;
     private connectionStatuses;
     private usageEntries;
     private pendingJobs;
@@ -67,11 +69,16 @@ export declare class EpistolaAdminPageComponent implements OnInit {
     get validationViolations(): BpmnValidationViolation[];
     /** Scan cadence in whole minutes, for the "refreshes every N min" note. */
     get refreshIntervalMinutes(): number;
+    /** Combined "forms needing attention" count for the tab badge (carrier + legacy override). */
+    get formsAttentionCount(): number;
+    /** Whether the forms tab has loaded at least one of its two scans. */
+    get formsScanLoaded(): boolean;
     ngOnInit(): void;
     selectConfiguration(card: ConfigurationCard): void;
     backToOverview(): void;
     setActiveTab(tab: 'actions' | 'pending' | 'catalogs'): void;
     setOverviewTab(tab: 'configurations' | 'validations' | 'changelog' | 'forms'): void;
+    private loadLegacyOverrideForms;
     private loadFormIssues;
     isRepairingForm(issue: FormCarrierIssue): boolean;
     repairForm(issue: FormCarrierIssue): void;

package/lib/components/epistola-configuration/epistola-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { PluginConfigurationComponent } from '@valtimo/plugin';
+import { PluginConfigurationComponent, PluginConfigurationData } from '@valtimo/plugin';
 import { FormOutput } from '@valtimo/components';
 import { Observable } from 'rxjs';
 import { EpistolaPluginConfig } from '../../models';
@@ -10,7 +10,7 @@ export declare class EpistolaConfigurationComponent implements PluginConfigurati
     pluginId: string;
     prefillConfiguration$: Observable<EpistolaPluginConfig>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<EpistolaPluginConfig>;
+    configuration: EventEmitter<PluginConfigurationData>;
     /** Epistola slug pattern: lowercase alphanumeric with hyphens, no leading/trailing hyphens. */
     private static readonly SLUG_PATTERN;
     private saveSubscription;

package/lib/components/epistola-document-preview/epistola-document-preview.component.d.ts

@@ -14,12 +14,42 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     label: string;
     processDefinitionKey?: string;
     sourceActivityId?: string;
-    overrideMapping?: Record<string, any>;
+    /**
+     * The override mapping: a JSONata expression string over `$form`, or — for
+     * not-yet-re-saved forms — the legacy `form:`-ref object.
+     */
+    overrideMapping?: string | Record<string, any>;
     /**
      * Task id forwarded by the Formio wrapper from the server-prefilled form
      * ({@code epistola:taskId} value resolver), populated in every Valtimo task-open flow.
      */
     taskInstanceId?: string | null;
+    /**
+     * The computed input overrides (`{ doc, pv }`) the preview renders with, pushed
+     * by the Formio wrapper. Kept separate from the Formio `value`: Valtimo's custom
+     * component bridge only mirrors `value` to the DOM (never to Formio's data
+     * model), so Formio resets it to `emptyValue` on every redraw — which would
+     * cancel the preview. This dedicated input is never touched by Formio.
+     */
+    inputOverrides?: Record<string, any> | null;
+    /**
+     * Forces the Formio wrapper to recompute the input overrides from the live form
+     * data. Set by the wrapper for override-driven previews; lets the Refresh button
+     * work before the first change (e.g. on initial load with pre-filled fields).
+     */
+    requestOverrides?: () => void;
+    /**
+     * Current auto-refresh state, forwarded by the wrapper (seeded from the builder's
+     * `autoRefresh` option, default on). Seeds the header toggle's initial state.
+     */
+    autoRefresh?: boolean;
+    /**
+     * Tells the wrapper to enable/disable auto-refresh (recompute on change/blur).
+     * Set by the wrapper for override-driven previews; called by the header toggle.
+     */
+    setAutoRefresh?: (enabled: boolean) => void;
+    /** Runtime state of the header auto-refresh toggle. */
+    autoRefreshEnabled: boolean;
     loading: boolean;
     error: string | null;
     previewUrl: SafeResourceUrl | null;
@@ -34,14 +64,16 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
      * (e.g. Formio builder), in which case the component fails closed.
      */
     private get currentTaskId();
-    get overrideMappingScopes(): string[];
-    overrideMappingEntries(scope: string): {
-        path: string;
-        field: string;
-    }[];
+    /**
+     * The override mapping as a JSONata expression for the design-mode summary.
+     * Legacy `form:`-ref objects are converted on the fly for display.
+     */
+    get overrideExpression(): string;
     ngOnChanges(changes: SimpleChanges): void;
     ngOnDestroy(): void;
     refresh(): void;
+    /** Toggle auto-refresh for this session; flipping it on triggers an immediate refresh. */
+    onToggleAutoRefresh(event: Event): void;
     /**
      * Load the preview only when there is enough data for it. Override-driven
      * previews (those with an override mapping) wait until the mapped form data
@@ -60,5 +92,5 @@ export declare class EpistolaDocumentPreviewComponent implements FormioCustomCom
     private handlePreviewError;
     private revokeBlobUrl;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaDocumentPreviewComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaDocumentPreviewComponent, "epistola-document-preview-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; "overrideMapping": { "alias": "overrideMapping"; "required": false; }; "taskInstanceId": { "alias": "taskInstanceId"; "required": false; }; "inputOverrides": { "alias": "inputOverrides"; "required": false; }; "requestOverrides": { "alias": "requestOverrides"; "required": false; }; "autoRefresh": { "alias": "autoRefresh"; "required": false; }; "setAutoRefresh": { "alias": "setAutoRefresh"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }

package/lib/components/epistola-document-preview/preview-utils.d.ts

@@ -1,5 +1,10 @@
-import { OverrideMapping } from '../override-builder/override-builder.component';
-export declare const FORM_REF_PREFIX = "form:";
+/** Re-exported for backward compatibility with existing imports/tests. */
+export { FORM_REF_PREFIX } from '../override-builder/legacy-override-converter';
+/**
+ * An override mapping is either the new JSONata expression **string** (over
+ * `$form`) or — for not-yet-re-saved forms — the legacy `form:`-ref **object**.
+ */
+export type OverrideMappingValue = string | Record<string, any> | null | undefined;
 /**
  * Detect if a string value is a JSONata expression (vs a plain literal).
  * Checks for characters that indicate JSONata operators: $, &, (, {, ?, [
@@ -16,7 +21,7 @@ export declare function expandDotNotation(flat: Record<string, any>): Record<str
  * before it can render. Previews without a mapping load straight from the base
  * doc/case data.
  */
-export declare function isOverrideDriven(mapping?: OverrideMapping | null): boolean;
+export declare function isOverrideDriven(mapping?: OverrideMappingValue): boolean;
 /**
  * Whether the computed input overrides carry any usable data yet.
  */
@@ -31,10 +36,16 @@ export declare function hasUsableOverrides(overrides?: Record<string, any> | nul
  *   required fields).
  * - Previews without a mapping always load (base data is the whole input).
  */
-export declare function shouldLoadPreview(mapping?: OverrideMapping | null, overrides?: Record<string, any> | null): boolean;
+export declare function shouldLoadPreview(mapping?: OverrideMappingValue, overrides?: Record<string, any> | null): boolean;
 /**
- * Given an override mapping (scope -> { inputPath -> "form:<componentKey>" })
- * and form data, produce the inputOverrides object for the backend.
- * The "form:" prefix identifies form field references; the remainder is the Formio component key.
+ * Given an override mapping and the live form data, produce the inputOverrides
+ * object (`{ doc, pv }`) the backend overlays onto the real document / process
+ * variables before the data mapping runs.
+ *
+ * The mapping is a JSONata expression over `$form`; legacy `form:`-ref objects
+ * are converted on the fly via {@link legacyOverrideToJsonata}. Evaluation is
+ * asynchronous because `jsonata().evaluate()` returns a Promise. Only `doc` and
+ * `pv` scopes (with at least one resolved field) are kept — matching what the
+ * backend consumes.
  */
-export declare function computeInputOverrides(mapping: OverrideMapping, formData: Record<string, any>): Record<string, any>;
+export declare function computeInputOverrides(mapping: OverrideMappingValue, formData: Record<string, any>): Promise<Record<string, any>>;

package/lib/components/generate-document-configuration/generate-document-configuration.component.d.ts

@@ -1,5 +1,5 @@
 import { ChangeDetectorRef, EventEmitter, OnDestroy, OnInit } from '@angular/core';
-import { FunctionConfigurationComponent, PluginConfigurationData } from '@valtimo/plugin';
+import { FunctionConfigurationComponent, FunctionConfigurationData, PluginConfigurationData } from '@valtimo/plugin';
 import { FormOutput, SelectedValue, SelectItem } from '@valtimo/components';
 import { CaseManagementParams, ManagementContext } from '@valtimo/shared';
 import { ProcessLinkStateService } from '@valtimo/process-link';
@@ -19,7 +19,7 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     selectedPluginConfigurationData$?: Observable<PluginConfigurationData>;
     context$?: Observable<[ManagementContext, CaseManagementParams]>;
     valid: EventEmitter<boolean>;
-    configuration: EventEmitter<GenerateDocumentConfig>;
+    configuration: EventEmitter<FunctionConfigurationData>;
     catalogs$: BehaviorSubject<AsyncResource<SelectItem[]>>;
     templates$: BehaviorSubject<AsyncResource<SelectItem[]>>;
     variants$: BehaviorSubject<AsyncResource<SelectItem[]>>;
@@ -68,6 +68,8 @@ export declare class GenerateDocumentConfigurationComponent implements FunctionC
     processVariables: string[];
     expressionFunctions: ExpressionFunctionInfo[];
     variableSuggestions: VariableSuggestions | null;
+    /** Context variables for the JSONata editor's autocomplete ($doc/$pv/$case). */
+    editorContextVariables: Record<string, string[]>;
     prefillDataMapping: Record<string, any>;
     validationErrors$: BehaviorSubject<JsonataFieldError[]>;
     private readonly destroy$;

package/lib/components/jsonata-editor/jsonata-editor.component.d.ts

@@ -1,11 +1,19 @@
 import { EventEmitter, OnChanges, OnDestroy, SimpleChanges } from '@angular/core';
-import { ExpressionFunctionInfo, VariableSuggestions } from '../../models';
+import { ExpressionFunctionInfo } from '../../models';
 import * as i0 from "@angular/core";
 export declare class JsonataEditorComponent implements OnChanges, OnDestroy {
     expression: string;
     disabled: boolean;
-    suggestions: VariableSuggestions | null;
+    /**
+     * Context variables in scope, keyed by name (without `$`), each mapping to its
+     * field/path suggestions — e.g. `{ doc: [...], pv: [...] }` for the data
+     * mapping, `{ form: [...] }` for the override builder. Drives both the
+     * `$`-variable list and `$<name>.` field completion.
+     */
+    contextVariables: Record<string, string[]>;
     functions: ExpressionFunctionInfo[];
+    /** Footer hint listing the context variables in scope. */
+    variablesHint: string;
     expressionChange: EventEmitter<string>;
     validChange: EventEmitter<boolean>;
     editorModel: {
@@ -25,5 +33,5 @@ export declare class JsonataEditorComponent implements OnChanges, OnDestroy {
     private tryRegisterLanguage;
     private validateExpression;
     static ɵfac: i0.ɵɵFactoryDeclaration<JsonataEditorComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<JsonataEditorComponent, "epistola-jsonata-editor", never, { "expression": { "alias": "expression"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "suggestions": { "alias": "suggestions"; "required": false; }; "functions": { "alias": "functions"; "required": false; }; }, { "expressionChange": "expressionChange"; "validChange": "validChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsonataEditorComponent, "epistola-jsonata-editor", never, { "expression": { "alias": "expression"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "contextVariables": { "alias": "contextVariables"; "required": false; }; "functions": { "alias": "functions"; "required": false; }; "variablesHint": { "alias": "variablesHint"; "required": false; }; }, { "expressionChange": "expressionChange"; "validChange": "validChange"; }, never, never, true, never>;
 }

package/lib/components/override-builder/legacy-override-converter.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Prefix that marked a form-field reference in the legacy override-mapping
+ * object format (e.g. `"form:motivationField"`).
+ */
+export declare const FORM_REF_PREFIX = "form:";
+/**
+ * Whether a stored override-mapping value is in the legacy **object** format
+ * (`{ scope: { inputPath: "form:fieldKey" } }`) rather than the new JSONata
+ * **string** format.
+ */
+export declare function isLegacyOverrideMapping(value: unknown): value is Record<string, any>;
+/**
+ * TEMPORARY migration shim.
+ *
+ * Converts a legacy override-mapping object into the equivalent JSONata string
+ * over `$form`. Funnelling every legacy value through this one function keeps
+ * the rest of the codebase JSONata-only.
+ *
+ * @deprecated Remove once all deployed forms have been re-saved in the JSONata
+ *   format. The admin page's "legacy override format" warning tracks which
+ *   forms still need migrating.
+ */
+export declare function legacyOverrideToJsonata(mapping: Record<string, any>): string;

package/lib/components/override-builder/override-builder.component.d.ts

@@ -1,42 +1,74 @@
-import { ChangeDetectorRef, EventEmitter } from '@angular/core';
+import { ChangeDetectorRef, EventEmitter, OnDestroy, SimpleChanges } from '@angular/core';
 import { FormioCustomComponent } from '@valtimo/components';
+import { OverrideRow } from './override-jsonata';
+import { EpistolaPluginService } from '../../services';
+import { ReferencedPath } from '../../utils/extract-referenced-paths';
 import * as i0 from "@angular/core";
-interface OverrideRow {
-    scope: 'doc' | 'pv';
-    inputPath: string;
-    formFieldKey: string;
-}
 export interface FormFieldOption {
     key: string;
     label: string;
 }
 /**
- * Override mapping format: scope → { inputPath → "form:<componentKey>" }
- * The "form:" prefix identifies this as a reference to a Formio component.
+ * Override mapping value: a JSONata expression (over `$form`) that produces the
+ * `{ doc, pv }` overlay applied during preview. Legacy form definitions may
+ * still carry the old `{ scope: { inputPath: "form:key" } }` object; it is
+ * converted to JSONata on load (see {@link legacyOverrideToJsonata}).
  */
 export type OverrideMapping = Record<string, Record<string, string>>;
-export declare class EpistolaOverrideBuilderComponent implements FormioCustomComponent<OverrideMapping | null> {
+export declare class EpistolaOverrideBuilderComponent implements FormioCustomComponent<string | OverrideMapping | null>, OnDestroy {
     private readonly cdr;
-    value: OverrideMapping | null;
-    valueChange: EventEmitter<OverrideMapping>;
+    private readonly pluginService;
+    value: string | OverrideMapping | null;
+    valueChange: EventEmitter<string | OverrideMapping>;
     disabled: boolean;
     label: string;
     availableFields: FormFieldOption[];
+    /**
+     * Identify the selected generate-document process link, forwarded from the
+     * preview component's editForm. Used to fetch the link's data mapping and
+     * surface which `$doc`/`$pv` paths it consumes — purely informational guidance.
+     */
+    processDefinitionKey: string;
+    sourceActivityId: string;
     rows: OverrideRow[];
     advancedMode: boolean;
-    jsonText: string;
-    jsonError: string | null;
+    /** True when the current expression can't be represented by the simple table. */
+    simpleUnavailable: boolean;
+    expression: string;
+    /** `$doc`/`$pv`/`$case` paths the selected template's data mapping references. */
+    referencedPaths: ReferencedPath[];
+    readonly exampleExpression = "{ \"doc\": { \"naam\": $form.voornaam & ' ' & $form.achternaam } }";
     private initialized;
-    constructor(cdr: ChangeDetectorRef);
-    ngOnChanges(): void;
+    private readonly destroy$;
+    /** Link last fetched, so we refetch only when the selected process link changes. */
+    private lastFetchedLinkKey;
+    constructor(cdr: ChangeDetectorRef, pluginService: EpistolaPluginService);
+    get formFieldKeys(): string[];
+    get hasReferencedPaths(): boolean;
+    /** Referenced paths for a scope, excluding whole-scope refs (empty path) that aren't completions. */
+    referencedPathsForScope(scope: ReferencedPath['scope']): string[];
+    /** Autocomplete context for the advanced editor: form fields plus the mapping's referenced paths. */
+    get editorContextVariables(): Record<string, string[]>;
+    /** Render a referenced path as a `$scope.path` reference (or `$scope` for a whole-scope ref). */
+    formatReferencedPath(ref: ReferencedPath): string;
+    ngOnChanges(_changes?: SimpleChanges): void;
+    ngOnDestroy(): void;
+    /**
+     * Fetch the selected process link's data mapping and extract the `$doc`/`$pv`/`$case`
+     * paths it references, so the author sees what this template consumes. Refetches only
+     * when the selected link changes; clears when no link is selected. Best-effort and
+     * non-blocking — a failed fetch simply shows no suggestions.
+     */
+    private refreshReferencedPaths;
     toggleMode(): void;
     addRow(): void;
     removeRow(index: number): void;
+    /** Simple-table change: serialize rows back to a JSONata expression. */
     emitChange(): void;
-    onJsonChange(text: string): void;
-    private rowsToMapping;
-    private mappingToRows;
+    /** Advanced-editor change. */
+    onExpressionChange(expr: string): void;
+    private loadFromExpression;
+    private emit;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaOverrideBuilderComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaOverrideBuilderComponent, "epistola-override-builder-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "availableFields": { "alias": "availableFields"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<EpistolaOverrideBuilderComponent, "epistola-override-builder-component", never, { "value": { "alias": "value"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; "label": { "alias": "label"; "required": false; }; "availableFields": { "alias": "availableFields"; "required": false; }; "processDefinitionKey": { "alias": "processDefinitionKey"; "required": false; }; "sourceActivityId": { "alias": "sourceActivityId"; "required": false; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }
-export {};

package/lib/components/override-builder/override-jsonata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * A single row in the override builder's simple table: a form field feeding a
+ * `doc`/`pv` input path during preview.
+ */
+export interface OverrideRow {
+    scope: 'doc' | 'pv';
+    inputPath: string;
+    formFieldKey: string;
+}
+/**
+ * Serialize simple-table rows into a JSONata expression that maps `$form` onto
+ * a `{ doc, pv }` overlay. Dot-notation input paths expand into nested object
+ * literals (so `beslissing.tekst` becomes `{ "beslissing": { "tekst": ... } }`),
+ * preserving the legacy override semantics.
+ */
+export declare function serializeOverrideRows(rows: OverrideRow[]): string;
+/**
+ * Parse a JSONata override expression back into simple-table rows, or `null`
+ * when the expression is richer than the simple table can represent (anything
+ * beyond `doc`/`pv` objects whose leaves are plain `$form.<key>` references).
+ * A `null` result is the builder's signal to fall back to advanced mode.
+ */
+export declare function parseOverrideJsonata(expression: string): OverrideRow[] | null;
+/** Whether the expression can be edited in the simple table (round-trippable). */
+export declare function isRoundTrippable(expression: string): boolean;

package/lib/models/admin.d.ts

@@ -33,6 +33,12 @@ export interface PendingJob {
     tenantId: string;
     requestId: string;
     configurationTitle: string;
+    /**
+     * 'WAITING' — has the epistolaWaitFor token; the collector can correlate it.
+     * 'UNWIRED' — has the subscription but no token, so it can never be correlated (stuck); requestId is
+     * absent and reconcile cannot recover it. Surfaced so operators can see and fix the process model.
+     */
+    status: 'WAITING' | 'UNWIRED';
 }
 export interface PluginUsageEntry {
     processLinkId: string;
@@ -143,6 +149,19 @@ export interface FormCarrierIssue {
     missingComponents: number;
     readOnly: boolean;
 }
+/**
+ * TEMPORARY. A form whose `epistola-document-preview` components still use the legacy
+ * override-mapping object format (`{ scope: { path: "form:key" } }`) instead of the new
+ * JSONata string over `$form`. Surfaced on the admin page so it can be re-saved in the
+ * form builder, which migrates it. `readOnly` flags classpath-deployed forms (migrate
+ * the source instead).
+ */
+export interface LegacyOverrideForm {
+    formId: string;
+    name: string;
+    legacyComponents: number;
+    readOnly: boolean;
+}
 /** TEMPORARY (removed in 1.0.0). Outcome of repairing one form's carrier. */
 export interface FormCarrierRepairResult {
     formId: string;

package/lib/models/config.d.ts

@@ -83,6 +83,15 @@ export interface VariableSuggestions {
     doc: string[];
     pv: string[];
 }
+/**
+ * Raw `dataMapping` JSONata of a generate-document process link, keyed server-side by
+ * `(processDefinitionKey, activityId)`. Empty when the link or its mapping can't be resolved.
+ * The override builder statically extracts the referenced `$doc`/`$pv` paths from it to show
+ * the author which inputs this template's mapping consumes.
+ */
+export interface ProcessLinkMapping {
+    dataMapping: string;
+}
 export interface EvaluationResult {
     success: boolean;
     result: Record<string, any> | null;

package/lib/services/epistola-admin.service.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '@angular/common/http';
 import { ConfigService } from '@valtimo/shared';
 import { Observable } from 'rxjs';
-import { BpmnValidationReport, CatalogRedeployResult, ChangelogRelease, ClasspathCatalog, ConnectionStatus, FormCarrierIssue, FormCarrierRepairResult, FormCarrierRepairSummary, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
+import { BpmnValidationReport, CatalogRedeployResult, ChangelogRelease, ClasspathCatalog, ConnectionStatus, FormCarrierIssue, FormCarrierRepairResult, FormCarrierRepairSummary, LegacyOverrideForm, PendingJob, PluginUsageEntry, ReconcileResult, VersionInfo } from '../models';
 import * as i0 from "@angular/core";
 /**
  * Service for Epistola plugin administrative operations.
@@ -70,6 +70,8 @@ export declare class EpistolaAdminService {
     repairFormCarrier(formId: string): Observable<FormCarrierRepairResult>;
     /** Repair every flagged form. */
     repairAllFormCarriers(): Observable<FormCarrierRepairSummary>;
+    /** Forms whose preview components still use the legacy override-mapping object format. */
+    getLegacyOverrideForms(): Observable<LegacyOverrideForm[]>;
     static ɵfac: i0.ɵɵFactoryDeclaration<EpistolaAdminService, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<EpistolaAdminService>;
 }

package/lib/services/epistola-plugin.service.d.ts

@@ -1,7 +1,7 @@
 import { HttpClient } from '@angular/common/http';
 import { ConfigService } from '@valtimo/shared';
 import { Observable } from 'rxjs';
-import { AttributeDefinition, CatalogInfo, EnvironmentInfo, ExpressionFunctionInfo, JsonataValidationResult, TemplateDetails, TemplateInfo, EvaluationResult, ValidateJsonataRequest, VariableSuggestions, VariantInfo } from '../models';
+import { AttributeDefinition, CatalogInfo, EnvironmentInfo, ExpressionFunctionInfo, JsonataValidationResult, ProcessLinkMapping, TemplateDetails, TemplateInfo, EvaluationResult, ValidateJsonataRequest, VariableSuggestions, VariantInfo } from '../models';
 import * as i0 from "@angular/core";
 /**
  * Body of a {@link EpistolaPluginService.previewToBlob} call. Mirrors the
@@ -68,6 +68,12 @@ export declare class EpistolaPluginService {
      * Discover process variable names for a given process definition.
      */
     getProcessVariables(processDefinitionKey: string): Observable<string[]>;
+    /**
+     * Get the raw `dataMapping` JSONata of a generate-document process link, identified by its
+     * process definition key and activity id. The override builder extracts the referenced
+     * `$doc`/`$pv` paths from it to guide the author. Returns an empty mapping when unresolved.
+     */
+    getProcessLinkMapping(processDefinitionKey: string, activityId: string): Observable<ProcessLinkMapping>;
     /**
      * Get variable suggestions for JSONata autocompletion.
      */

package/lib/utils/extract-referenced-paths.d.ts

@@ -0,0 +1,19 @@
+/** A `$doc`/`$pv`/`$case` path referenced by a JSONata expression. */
+export interface ReferencedPath {
+    scope: 'doc' | 'pv' | 'case';
+    /** Dotted path under the scope, e.g. `aanvrager.naam`. Empty for a whole-scope reference. */
+    path: string;
+}
+/**
+ * Statically extract every `$doc`/`$pv`/`$case` path referenced anywhere in a JSONata
+ * expression. Used to surface — informationally — which inputs a template's data mapping
+ * consumes, so the override-builder author sees what is worth overriding during preview.
+ *
+ * This is a best-effort static read: paths built dynamically (`$lookup`, custom functions,
+ * computed keys) can't be resolved and simply won't appear. Treat the result as suggestions,
+ * never as validation — an empty result (e.g. on a parse error) means "nothing to suggest".
+ *
+ * Generalizes the variable-path primitive in `utils/jsonata-converter.ts` (`classifyValue`)
+ * to recurse over the whole AST rather than only top-level object values.
+ */
+export declare function extractReferencedPaths(expression: string | null | undefined): ReferencedPath[];

package/lib/utils/jsonata-monaco.d.ts

@@ -1,10 +1,10 @@
-import { ExpressionFunctionInfo, VariableSuggestions } from '../models';
+import { ExpressionFunctionInfo } from '../models';
 /**
  * Shared state for the JSONata completion provider.
  * Updated by the editor component when suggestions/functions change.
  */
 export declare const jsonataCompletionData: {
-    suggestions: VariableSuggestions | null;
+    variables: Record<string, string[]>;
     functions: ExpressionFunctionInfo[];
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epistola.app/valtimo-plugin",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Epistola document generation plugin for Valtimo",
   "license": "EUPL-1.2",
   "repository": {
@@ -28,6 +28,7 @@
     "@angular/core": ">=17.0.0",
     "@angular/forms": ">=17.0.0",
     "@angular/router": ">=17.0.0",
+    "@formio/angular": "^7.0.0",
     "@valtimo/components": "^13.21.0",
     "@valtimo/plugin": "^13.21.0",
     "@valtimo/process-link": "^13.21.0",