@wemake4u/dmn-editor
v1.0.1
Published
Complete DMN 1.5 editor (DRD + boxed expressions)
Maintainers
Readme
@wemake4u/dmn-editor
A complete DMN 1.5 editor for Angular 22: the DRD diagram, the editors of every boxed expression, data types and decision services, validation and decision table analysis, in one component. Files are read lossless (DMN 1.2–1.5, DMNDI, vendor extensions) and always saved as DMN 1.5.
The user interface is in English (default) and Italian.
Installation
npm install @wemake4u/dmn-editor @wemake4u/dmn-drd @wemake4u/dmn-boxed @wemake4u/dmn-core @wemake4u/code-editorPeer dependencies: @angular/core, @angular/common, @angular/forms and @angular/platform-browser
22.2.x, @wemake4u/dmn-core, @wemake4u/dmn-drd and @wemake4u/dmn-boxed 1.x, and @wemake4u/code-editor 2.x
(needed by @wemake4u/feel-editor, the FEEL editor of the cells, installed with dmn-boxed). The editor is zoneless-ready
(signals, OnPush) and has no global stylesheet. It uses the IBM Plex Sans and IBM Plex Mono
fonts when available, for example:
<link
rel="stylesheet"
href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap"
/>Usage
import { Component, signal } from '@angular/core';
import { DmnEditor, type DmnSaveHandler } from '@wemake4u/dmn-editor';
@Component({
selector: 'app-root',
imports: [DmnEditor],
template: `
<dmn-editor
[xml]="xml()"
fileName="idoneita.dmn"
[readOnly]="readOnly()"
[saveHandler]="save"
[autoSave]="true"
/>
`,
styles: `
dmn-editor {
height: 100vh;
}
`,
})
export class App {
readonly xml = signal<string | undefined>(undefined); // undefined: a new empty model
readonly readOnly = signal(false);
// event.xml is the DMN 1.5 document, event.fileName its name, event.auto true for auto-saves
readonly save: DmnSaveHandler = (event) =>
fetch('/api/models', { method: 'PUT', body: event.xml }).then((response) => {
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
});
}The component fills the height it is given: set a height on dmn-editor (or on its container).
Inputs and outputs
| Name | Type | Description |
| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| xml | string \| undefined | DMN document to open (DMN 1.2–1.5). undefined starts from an empty model. Setting a new value opens it. |
| fileName | string | Name used by "Esporta" and in the saved event. Default diagramma.dmn. |
| readOnly | boolean | Read-only mode: the whole model can be explored (diagram, logic, data types, XML, problems, table analysis) but nothing can be changed, saved or imported. Export stays. |
| extensions | readonly DmnExtension[] | Properties of the host for the elements of the diagram, in tabs of the Properties panel (see "Properties of the host"). |
| importResolver | ImportResolver | Handler that describes the imported models (see below). |
| showImportedElements | boolean | Shows the elements of the imported models in the diagram (palette group, notation, connections to local elements). Default false. |
| importCatalogs | ImportCatalogList | Handler that lists the catalogs of importable models, for the "Importa da catalogo" window (see below). |
| importSearch | ImportSearch | Handler that searches the models of a catalog (or of one of its libraries) by keywords (see below). |
| importLibraries | ImportLibraryList | Handler that lists the libraries of a catalog divided into libraries (see below). |
| feelEvaluator | FeelEvaluator | Handler that evaluates an element for the "Prova" panels (see below). Without it "Valuta" is disabled. |
| performanceThresholds | Partial<PerformanceThresholds> | When a time is a point of attention in «Prestazioni»: slowCallMs (5000), slowCallShare (0.5), slowElementMs (1000), slowElementShare (0.25), slowLogicMs (50), sequentialCallsMs (2000). |
| performanceArguments | 'masked' | 'plain' | 'hidden' | How «Prestazioni» shows the arguments and results of the external functions (also in the HTML downloaded). Default 'masked': texts shortened to their ends, dates and structures without content. |
| diagnosticsOnlyPath | boolean | The diagnostics start with «Solo il percorso» on (only the elements the evaluation went through are shown); the user can switch it, and the choice stays for the session. Default false. |
| modelValidator | ModelValidator | Handler that validates the model on the host, typically a service (see "Validation" below). |
| feelFunctions | FeelFunctions | Functions of the host callable from FEEL, offered by the completion and the side panel (see below). |
| tableData | Partial<TableDataOptions> | Loading the values of relations and lists from files and exporting them: formats, reader of the host (e.g. Excel), modes, limits (see "Values of relations and lists from files"). |
| validation | Partial<ValidationSettings> | When and where the model is validated: mode, serverTrigger, delay, validateReadOnly (see "Validation" below). |
| locale | string | Language of the editor (it, en, a language given with provideDmnLocale, or auto for the browser's). Undefined follows the application; English by default (see "Language"). |
| messages | DmnMessagesOverride | Texts to correct in the language in use. |
| features | Partial<DmnEditorFeatures> | Features to turn off (see "Features"); the others stay on. |
| trace | EvaluationResult \| TraceDocument | A trace to analyse (see "Analysing a trace you already have"): the editor opens on its diagnostics. |
| initialView | DmnEditorView | View a document opens on: 'diagram' (default), 'dataTypes', 'xml' or 'catalog:<namespace>#<id>'; the diagram when that view is turned off or not declared. |
| namespaceReadOnly | boolean | The namespace of the model is set by the host: the Definitions panel shows it, read-only, with a note (default false). |
| nameReadOnly | boolean | The name of the model is set by the host: the Definitions panel shows it, read-only, with a note (default false). |
| descriptionReadOnly | boolean | The description of the model (<description> of the definitions) is set by the host: the Definitions panel shows it, read-only, with a note; the descriptions of the elements stay editable (default false). |
| elementIdMode | ElementIdMode | The id of the selected element in the Properties panel: 'editable' (default; the references are updated), 'readOnly' (shown with a note, not editable) or 'hidden' (the name takes the whole row). Only the interface: changeElementId stays available to the host. |
| importMode | 'any' \| 'catalog' | 'catalog': imports are added only from the catalogs of importCatalogs/importSearch and cannot be edited, only removed; no catalogs, no way to add them (default 'any'). |
| importPrefixEditable | boolean | The user chooses the prefix of an import of a catalog: "Importa…" proposes a free prefix that can be changed, checked while it is written (not empty, letters, digits and _, not a FEEL keyword, not used by another import or by an element or type of the model; a case-only difference is a warning); in catalog mode "Rinomina prefisso" renames it and rewrites the FEEL texts that use it. false: the proposed prefix is used at once and cannot be changed. Default true. |
| importPageSize | number | How many models of a catalog the «Importa da catalogo» window asks for at a time (take of importSearch); «Mostra altri» asks for the next page. Default 20. |
| importedElementKinds | readonly ImportedElementKind[] | The kinds of elements of the imported models the model can use. Default DEFAULT_IMPORTED_ELEMENT_KINDS: only the business knowledge models and the decision services (an imported model is used through its functions); the types (itemDefinition) are always usable. The other elements are left out of the palette «Elementi importati», of the FEEL completion and of «Prova», are listed as «Non esposti» in the details of the import, and their uses (a requirement, or prefix.name in a FEEL text) are errors import-element-hidden. ALL_IMPORTED_ELEMENT_KINDS exposes every element. |
| saveHandler | DmnSaveHandler | Handler that stores the document (see "Saving" below). The model is marked as saved only when it succeeds. |
| openImportedModel | ImportedModelOpener | Handler that opens an imported model of a trace (e.g. its module, read-only): the diagnostics offer «Apri il modello» inside an imported model and for its elements, and call it with an ImportedModelTarget (key, namespace, name, version, prefix, element). Without it they do not offer to open them. |
| autoSave | boolean | Saves automatically after a pause in the changes. Default false; never in read-only mode. Two-way ([(autoSave)], autoSaveChange) with the feature autoSaveToggle. |
| autoSaveDelay | number | Pause after the last change before the auto-save, in milliseconds. Default 2000. |
| saved | DmnSaveEvent | Emitted after each successful save (button, Ctrl+S or auto-save) with { xml, fileName, auto }. |
| leadingAction | DmnLeadingAction | A button of the host first in the header, typically "Indietro" (see "Leading action" below). None by default. |
| leadingActionClick | void | Emitted by the leading action once the pending changes are saved; not emitted when the save fails. |
open(xml, fileName) and save() are also available on the component instance.
Imported models
The user adds, edits and removes the imports of the model in the Definitions panel (nothing
selected in the diagram). The editor does not load the imported files itself: give it an
importResolver, a handler that receives the imports and returns what the host knows of the
imported models. Their elements are then offered by the FEEL completion with the import prefix
(their item definitions by the type fields, as anagrafica.tCliente)
(anagrafica.Cliente, anagrafica.Età(…)) and listed in the details window of each import.
import { describeImportedModel, DmnStore, type ImportResolver } from '@wemake4u/dmn-core';
// e.g. load the .dmn file of each import from the server
export const resolveImports: ImportResolver = async (imports) => {
const models = [];
for (const imported of imports) {
if (imported.locationURI) {
const xml = await (await fetch(imported.locationURI)).text();
models.push(describeImportedModel((await DmnStore.open(xml)).model()));
}
}
return models; // matched to the imports by namespace
};<dmn-editor [xml]="xml" [importResolver]="resolveImports" />The handler may return the elements from any source (a catalog, a service), as
ImportedModel objects: { namespace, name?, elements: [{ name, kind, typeRef?,
parameters?, fields?, description? }] }, where kind is decision, inputData,
businessKnowledgeModel, decisionService or itemDefinition. It is called when a model is
opened, when its imports change and from the "Ricarica" button of the details window; a
rejected promise is shown as an error of the import.
With [showImportedElements]="true" the palette gets an "Elementi importati" group: the
elements returned with an id can be placed in the diagram (DMNDI prefix:id, with the XML
prefix declared on the definitions) and connected to the local decisions and business knowledge
models (href="namespace#id"); removing them from the diagram removes those requirements.
Import catalog
With importCatalogs and importSearch the Definitions panel offers "Importa da catalogo…": a
window where the user first chooses one of the catalogs of the host, then searches its models by
keywords (words, or phrases between quotes) and imports them with one click ("Cambia catalogo"
goes back to the list; with a single catalog the search opens at once). A catalog may be divided
into libraries: the window then lists them beside the search ("Tutte le librerie" first; a
drop-down list on narrow screens) and the search can be restricted to one of them.
importCatalogs()returnsImportCatalogInfoobjects:{ name, label?, description?, hasLibraries? }.importLibraries(catalog)is called for the catalogs withhasLibrariesand returnsImportLibraryInfoobjects:{ name, label?, description? }(without the handler the whole catalog is searched).importSearch(query)receives anImportQuery—{ catalog, library?, keywords, skip, take }: the name of the chosen catalog, of the chosen library (none: the whole catalog), the keywords (an empty array for every model) and the page asked for (takeisimportPageSize, 20 by default) — and returns a page{ items, total }(ImportSearchPage: the models fromskip, at mosttake, and how many were found in all) or, as before, an array of every model found (the editor then divides it into pages without asking again). The models areImportCandidateobjects:{ namespace, name, prefix?, locationURI?, importType?, description?, library? }(libraryis shown when searching every library). The window shows the total, the first page and «Mostra altri», which asks for the next page and adds it under the others (the focus goes to the first new model); with many models and no keywords it suggests to search better. The import name isprefix, or the name without spaces and accents (Anagrafica clienti→anagraficaClienti).
import type { ImportCatalogList, ImportLibraryList, ImportSearch } from '@wemake4u/dmn-core';
export const catalogs: ImportCatalogList = () =>
this.http.get<ImportCatalogInfo[]>('/api/dmn/catalogs');
export const libraries: ImportLibraryList = (catalog) =>
this.http.get<ImportLibraryInfo[]>(`/api/dmn/catalogs/${catalog}/libraries`);
export const searchModels: ImportSearch = ({ catalog, library, keywords, skip, take }) =>
this.http.get<ImportSearchPage>(`/api/dmn/catalogs/${catalog}/models`, {
params: { q: keywords.join(' '), skip, take, ...(library ? { library } : {}) },
});Saving
"Salva", Ctrl+S and the auto-save serialize the model and call saveHandler with
{ xml, fileName, auto }. The handler may return at once, a promise or an observable; when it
throws or rejects the header shows "Salvataggio non riuscito" with the reason and "Riprova", and
the model stays unsaved. The header shows "Salvataggio…", "Modifiche non salvate" and "Salvato alle
HH:MM". Changes made while a save is running stay unsaved and are saved by the next one; a save
requested meanwhile (e.g. Ctrl+S during an auto-save) runs right after it.
With autoSave the editor saves autoSaveDelay milliseconds after the last change. After a
failed auto-save it tries again at the next change or with "Riprova", never in a loop.
The auto-save can be always off ([autoSave]="false"), always on ([autoSave]="true") or chosen
by the user: with the feature autoSaveToggle the header shows the switch «Salvataggio
automatico» (not in read-only mode), which starts from autoSave and changes it. Turned off, a
pending auto-save is cancelled and the changes stay unsaved until "Salva" or Ctrl+S; turned on,
the changes not saved yet are saved after autoSaveDelay. The host keeps the choice, e.g. in the
browser storage:
<dmn-editor
[xml]="xml"
[features]="{ autoSaveToggle: true }"
[autoSave]="autoSave()"
(autoSaveChange)="rememberAutoSave($event)"
/>Without saveHandler the editor only emits saved and marks the model as saved at once.
"Prova": evaluation service
The editors of decisions, business knowledge models and decision services have a "Prova" panel:
one field per input, where the user types FEEL values, and "Valuta". The editor has no FEEL
engine: feelEvaluator receives an EvaluationRequest and returns an EvaluationResult,
typically by calling a FEEL service.
interface EvaluationRequest {
xml: string; // the model as DMN 1.5, with the unsaved changes
namespace: string;
elementId: string;
elementName: string;
elementKind: 'decision' | 'businessKnowledgeModel' | 'decisionService';
inputs: { name: string; value: string; typeRef?: string }[]; // value: FEEL text
}
interface EvaluationResult {
value?: unknown; // JSON (dates and durations as strings)
text?: string; // the result written as FEEL, shown as is when present
type?: string; // e.g. "number", "tEsito", "list<number>"
messages?: {
severity: 'error' | 'warning' | 'info';
message: string;
code?: string;
elementId?: string;
input?: string; // the input the message refers to
line?: number;
column?: number;
}[];
steps?: { elementId?: string; name: string; value?: unknown; text?: string; type?: string }[];
durationMs?: number;
}The inputs are:
- for a decision, the decisions and input data it requires; a value given for a required decision replaces its evaluation, the empty ones are evaluated from the model;
- for a BKM, its parameters (the BKM is invoked with them);
- for a decision service, its input decisions and input data.
Empty fields are left out. The evaluation succeeded when no message has severity error;
errors and warnings are listed under the result, steps (intermediate results) in a
collapsible list. When the handler fails or does not answer within 30 s the panel shows why;
editing is never blocked.
export const evaluate: FeelEvaluator = (request) =>
this.http.post<EvaluationResult>('/api/feel/evaluate', request);For a decision the panel also offers the input data needed by the required decisions, used when their fields are left empty.
The elements of imported models follow the local inputs, grouped by import, named
prefix.name (the name of the <import> and the name of the element in the imported model,
e.g. lib.maggiorenne): a field for each imported decision or input data the decision requires
(a value for an imported decision replaces its evaluation), then the imported input data the
required decisions need. They come from the models returned by importResolver: an unresolved
import gives no fields, and the indirect input data are offered only when the imported elements
list their requirements (ImportedElement.requires, filled by describeImportedModel). The
type of an imported field is prefix.tType when it is a type of the imported model (a FEEL
field, with an example built from its fields).
Diagnostics
The "Prova" panel sends trace: true (or { maxItems }). When the result has a trace, the
panel offers "Diagnostica", which shows the evaluation on the diagram:
- every element shows its value, its evaluation order and its state (evaluated, current, still to be evaluated, not involved); a BKM shows how many times it was invoked; the value of each required element is written along its requirement;
- "Riproduci", ◀ ▶ and the chips of the evaluation order go through the elements; clicking a shape (or a chip) selects it. The chips scroll in their own area, which keeps the current one in view; when the area is narrower than 260 px they show the order only, with the name in the tooltip. The result is at most 260 px wide (longer values end with "…") and opens in the window of the value viewer;
- the panel on the right explains how the selected element got its value: the values it received (with the step they come from), its evaluated logic (the rules of a decision table with the outcome of each test, the entries of a context, the elements of a list, the cells of a relation, the items of for / some / every / filter, the chosen branch of a conditional, the parameters of an invocation, the calls of a BKM), the elements it passes its value to, and the tabs "Passi interni", "Variabili" and "Messaggi";
- values (of the step, of its inputs, of its variables, of its nested steps, and the result of
"Prova") are shown by a value viewer: simple values on one line (long texts shortened, "Tutto"),
contexts and lists as a one-line summary that opens as a tree, lists of contexts with the same
entries also as a table, long lists 50 elements at a time; values with more than 200 leaves,
and any value with "Apri" or ⤢, open in a window with search (and the path of the found part,
ready for a FEEL expression), sortable tables, the JSON, copy and download; on the diagram the
tooltip of a shape shows the first entries of its value. The tree is built from the JSON
valueof steps, variables and bindings: without it the FEELtextis shown as is; - the panel is "Compatto" (380 px), "Ampio" (60%, with the reason of each rule) or "Schermo
intero"; its left border can be dragged (or moved with the arrow keys) and
[/]change the width; a double click on a shape opens its detail in the wide panel; - when the service measures the steps (
durationMsof eachTraceStep), "Tempi" shows on every element its own time (without the elements it required or invoked, so the times add up to the total) instead of its value, "input" for input data and "valore dato" for given values; the slowest element is highlighted with its share of the total and named in the tooltip of "Tempi". The panel shows the time of the element (own, share, with what it requires) and, in "Passi interni", the time of each inner step with a bar of its share of the logic (steps over half of it are highlighted). The total isdurationMsof the result, or of the root step. "Tempi" stays as chosen for the session; - "Valuta di nuovo" evaluates the same element with the same values on the current model, "Esporta traccia (JSON)" downloads request (without the model) and result, "Apri nell'editor" and "Torna all'editor" go back to the editors.
- "Spiegazione" explains the evaluation to people who do not know DMN, in a window with a page to
print (also as PDF) or download as HTML: the result, the data used, then a step for each decision
in evaluation order written in plain sentences (the rule of a table that applies and why, with
its conditions in words and the rules missed by one condition; a calculation with the values in
place of the names; the functions used, also of the imported models; the case of a condition).
"Sintetica" shows the path to the result, "Completa" also every rule of the tables, the formulas
of the model, the warnings and a technical appendix. It uses the labels and the descriptions of
the elements and the annotations of the rules, and says only what the trace says. Feature
explanation; the page isexplanationHtml(explainEvaluation(model, result))of dmn-core. - "Prestazioni" shows where the time of the evaluation went, in a window with a page to print or
download as HTML (when the trace has durations): a summary, the time by kind of work (external
functions, FEEL expressions, decision tables, relations, engine), the critical path, the external
functions one after the other on a time axis, the slowest elements, the calls with their
arguments and results, and the points of attention (a slow external function, independent calls
run one after the other, an external function whose error became null, a slow element or part
of a logic, the time saved by reusing). For an evaluation of a session the values computed by
other evaluations count once, with the time they took then; «Tutta l'elaborazione» adds a row
for each evaluation.
performanceThresholdssets when a time is a point of attention andperformanceArgumentshow the arguments and results are shown ('masked'by default,'plain','hidden': they can hold personal data). Featureperformance; the page isperformanceDocumentHtml(document)of dmn-core, which a host can also call without the editor. - Imported models: when the steps name their model (
TraceStep.model, with the models inEvaluationResult.models, see dmn-core), the imported elements placed in the diagram show their calls, the panel shows the imported model of an element and «Modelli importati usati» lists the calls of the logic to other models, with the model of each inner step and message. «Entra nel modello» (or a double click on the shape of an imported element) shows the diagram of that model read-only, with the same replay, values and panel: the path in the header and «Torna a…» go back, «Chiamato da» names the elements that called it, and its own imported models can be entered in turn. A model can be entered when the result gives its XML andaccessis notnone; otherwise only its calls (inputs, result, errors) are shown. WithopenImportedModelthe diagnostics also offer «Apri il modello».
interface TraceStep {
id: string; // unique in the trace
elementId?: string; // DRG element of the step
model?: string; // imported model of the step (a key of EvaluationResult.models)
path?: (string | number)[]; // part of its expression, an ExpressionPath of the editor
kind: TraceStepKind; // decision, inputData, businessKnowledgeModel, decisionService, literal,
// decisionTable, context, contextEntry, list, relation, invocation, conditional, filter, for,
// some, every, function
label: string;
source?: 'evaluated' | 'input' | 'override' | 'skipped';
value?: unknown; // JSON
text?: string; // the value written as FEEL
type?: string;
durationMs?: number; // the time of the step, including its children
messages?: EvaluationMessage[]; // the problems of this step
variables?: { name: string; text: string; value?: unknown; type?: string }[];
children?: TraceStep[]; // in evaluation order
detail?: TraceDetail; // see below
truncated?: boolean; // children cut by maxItems
}
type TraceDetail =
| {
kind: 'decisionTable';
hitPolicy: string;
aggregation?: string;
inputs: { text: string; type?: string }[];
rules: {
index: number;
tests: (boolean | null)[];
matched: boolean;
selected: boolean;
outputs?: string[];
}[];
} // every rule, 0-based index
| { kind: 'conditional'; condition: string; branch: 'then' | 'else' | null }
| {
kind: 'iteration';
variable: string; // for, some, every, filter
items: {
text: string;
result?: string;
test?: boolean | null;
decisive?: boolean;
evaluated: boolean;
}[];
}
| {
kind: 'invocation';
function: string;
bindings: {
parameter: string;
expression?: string;
text: string;
value?: unknown;
type?: string;
}[];
}
| { kind: 'relation'; columns: string[]; rows: string[][] };Contexts and lists have no detail: their entries and elements are children with their own
path. The paths use the property names of the DMN model (decisionLogic, contextEntry,
index, value, rule, inputEntry, elements, row, binding, bindingFormula,
if/then/else/in/return/satisfies + expression, encapsulatedLogic, body).
Properties of the host
The host can add its own properties to the elements of the diagram (decisions, input data, BKMs, knowledge sources, decision services, annotations, groups). Each extension has its own namespace in the DMN file and adds tabs to the Properties panel, after General, Requirements and Documentation; several extensions can be used together.
const governance: DmnExtension = {
namespace: 'https://acme.example/dmn/governance',
prefix: 'gov',
tabs: [
{
id: 'governance',
label: { it: 'Governance', en: 'Governance' },
appliesTo: ['decision', 'businessKnowledgeModel'], // all the elements when omitted
fields: [
{ name: 'owner', label: { it: 'Responsabile', en: 'Owner' }, required: true },
{
name: 'status',
label: 'Status',
type: 'select',
options: [
{ value: 'draft' },
{ value: 'approved', label: { it: 'Approvata', en: 'Approved' } },
],
},
{
name: 'review',
label: 'Next review',
type: 'date',
description: 'Date of the next review.',
},
{ name: 'tag', label: 'Tags', type: 'list' },
{ name: 'notes', label: 'Notes', type: 'textarea' },
],
},
],
};<dmn-editor [xml]="xml" [extensions]="[governance, compliance]" />A tab can also describe the whole model: with appliesTo: ['definitions'] (or a test that accepts
the target of kind definitions) it appears in the panel of the definitions, shown when nothing
is selected, after General and Imported models, and its values are saved on <definitions>.
Tabs without appliesTo never apply to the definitions. The badges of an extension with a tab for
the model appear beside the name of the file (a click opens the tab), and its issues name the
model in the list of problems, with «Apri la scheda».
const publication: DmnExtension = {
namespace: 'https://acme.example/dmn/publication',
prefix: 'pub',
badges: (element, values) => values['public'] === true && { text: 'Public', tone: 'success' },
tabs: [
{
id: 'publication',
label: 'Publication',
appliesTo: ['definitions'],
fields: [
{ name: 'public', label: 'Public model', type: 'boolean' },
{ name: 'version', label: 'Version' },
],
},
],
};Fields: text (default), textarea, number, boolean (checkbox), select (options),
date (YYYY-MM-DD), list (texts added and removed one by one); options required,
description (help under the field), readOnly and validate(value, element), which returns
a message when the value is not valid. Labels, descriptions and messages are a text, texts by
language ({ it, en }) or a function of the language.
In the file, text, number, boolean, select and date are attributes and textarea and
list children of extensionElements (storage changes it); the namespace is declared on the
definitions, with another prefix (gov1) when the file binds the wanted one to another
namespace, and a prefix already bound to the namespace in the file is kept:
<decision id="Decision_1" name="Eligibility" gov:owner="Credit office" gov:status="approved">
<extensionElements>
<gov:tag>credit</gov:tag>
<gov:notes>Review the thresholds.</gov:notes>
</extensionElements>
</decision>An extension can also show badges on the shapes, from the values of its fields:
const governance: DmnExtension = {
// …
badges: (element, values, locale) =>
values['status'] === 'approved'
? { text: { it: 'Approvata', en: 'Approved' }, tone: 'success', tab: 'governance' }
: undefined, // or an array of badges (false, null and undefined are skipped)
};A badge has a short text, a tone (neutral by default, info, success, warning,
danger, accent: fixed colors, readable on the diagram), a title for the tooltip (after the
name of the tab; the text when missing) and the tab opened by a click. The badges are on the
bottom edge of the shape, leaving its middle free (selection handle, incoming connections): at
most three, then "+n" with the others in its tooltip; below 60% of zoom they are colored dots.
They are part of the accessible name of the shape, are not saved in the file and are hidden in
the diagnostics. A badges function that throws gives no badges for that element (with a
warning in development mode).
Every change is a command (undo and redo, unsaved state). Required fields left empty and values
that are not valid (numbers, dates, choices, validate) are errors among the problems
(extension-invalid), with a badge on the shape and a dot on the tab; "Open the tab" selects the
element and moves the focus to the field. In read-only mode the fields are shown and not
editable. Properties of other namespaces in the file are kept as they are.
Catalogs
An extension can also keep a catalog beside the model: two levels of entries (e.g.
requirements and their controls) with fields and links with a role to elements of the model.
It is saved in the extensionElements of the definitions, in the namespace of the extension.
const requirements: DmnExtension = {
namespace: 'https://acme.it/compliance',
prefix: 'cmp',
tabs: [],
catalogs: [
{
id: 'requirements',
label: { it: 'Requisiti di conformità', en: 'Compliance requirements' },
element: 'requirements',
links: [{ name: 'output', label: 'Overall output', kinds: ['decision'] }],
items: {
id: 'requirement',
label: 'Requirement',
element: 'requirement',
codeField: 'code',
fields: [
{ name: 'code', label: 'Code', required: true },
{ name: 'name', label: 'Name', required: true },
{ name: 'description', label: 'Description', type: 'textarea' },
],
links: [
{
name: 'applies',
label: 'Applicability',
kinds: ['decision'],
type: 'boolean',
emptyText: 'always',
},
],
children: {
id: 'control',
label: 'Control',
element: 'control',
codeField: 'code',
fields: [
{ name: 'code', label: 'Code', required: true },
{ name: 'name', label: 'Name', required: true },
],
links: [
{ name: 'applies', label: 'Applicability', kinds: ['decision'], type: 'boolean' },
{
name: 'check',
label: 'Check',
kinds: ['decision'],
type: 'boolean',
required: true,
multiple: true,
},
{ name: 'output', label: 'Output', kinds: ['decision'] },
],
},
},
// optional: a badge on the decisions that check a control
badges: (use) =>
use.role.level === 'child' && use.role.link.name === 'check'
? { text: use.code, tone: 'info' }
: undefined,
},
],
};<cmp:requirements outputRef="#Decision_Outcome">
<cmp:requirement code="REQ-01" name="Creditworthiness" appliesRef="#Decision_Private">
<cmp:description>…</cmp:description>
<cmp:control code="C-01.1" name="Repayment capacity"
checkRef="#Decision_Capacity #Decision_Instalment" outputRef="#Decision_Detail"/>
</cmp:requirement>
</cmp:requirements>viewPosition places the view in the bar of the views ('first', before the diagram, 'afterDiagram', 'afterDataTypes'
by default, 'end') and tabPosition the tab in the Properties panel ('first', which is also
the tab shown when an element it can link is selected, 'afterGeneral', 'beforeExtensions',
before the tabs of the extensions, 'end' by default). The code of an entry is unique in the
whole catalog; with codeScope: 'parent' on the second level it is unique in its item and the
entries are named by the qualified code "R1·C1" in badges, marks, issues and "Open in the
catalog" (badges receives code, parentCode, qualifiedCode and path; without a title
the tooltip of a badge is the path and the role).
With numbering on a level the editor gives the codes and the code field is read-only:
{ prefix: 'R' } gives R1, R2…, { format: (n, parentCode) => parentCode + '.' + n } any other form (R1.1).
With renumber: 'onChange' (default) the codes follow the position: adding, moving or removing an
entry renumbers its level in the same command (the children that follow the position too, when
the items are renumbered). With renumber: 'manual' a new entry gets the code after the highest
one, moves keep the codes and "Renumber", next to "+ …", gives them again in the current order.
Opening a file never changes its codes.
A link is an attribute (${name}Ref unless attribute is given) with one reference, or several
separated by spaces with multiple; kinds are the kinds of element it accepts, type the
expected type of the linked element and required makes an empty link a warning. The fields
are those of the tabs (attributes, or child elements for textarea and list); the code field
must be unique in its level. What the declaration does not describe (other attributes and
children) is kept when the catalog is written.
The editor shows each catalog as a view next to "Data types" (links of the catalog, list of the
items, fields and links of the selected item, table of its children and the selected child below,
↑ ↓, the ⋮⋮ handle to drag an item or a child among its siblings, and Delete), a tab of the Properties panel of the elements it can link (the entries that link
the element with their role, "Open in the catalog", "Unlink", "+ Link to an entry…"), "Show in the
diagram" (the roles drawn on the linked elements in the colors of the view, a notice with "Hide",
Esc) and the badges of badges. The issues are catalog-field-invalid and
catalog-code-duplicate (errors), catalog-link-missing (warning), catalog-link-broken
(error), catalog-link-kind and catalog-link-type (warnings on the linked element), with "Open
in the catalog" in the list of problems. Every change is one command; in read-only mode the
catalog is only shown.
Testing a catalog
A catalog with evaluation can be evaluated as a whole: its view shows below the entries the
same «Prova» panel as the editors of the logic, with «Ambito» (the whole catalog, the selected
item or the selected child; scopes limits them). The fields are the inputs of the decisions and
decision services linked in the scope (inputLinks limits the links), once each, with the
entries that need them after the type. The editor does not know what the roles mean: the host
evaluates the catalog and returns a session.
evaluation: {
scopes: ['catalog', 'item', 'child'], // default: all
inputLinks: ['applies', 'check', 'output'], // default: every link
evaluate: (request: CatalogEvaluationRequest) =>
http.post<TraceDocument>('/api/catalog/evaluate', request),
},The request has the model (xml, with the unsaved changes), namespace, the catalog
(namespace, id, element), the scope (references of the entries, e.g. ['REQ-01·C2'],
empty for the whole catalog), the inputs with a value and trace. The answer is a
TraceDocument of a session (root step of kind session, evaluations with group and
groupCodes, groupOutcomes): the groups name the entries by code (or title), a group without
headings is the catalog as a whole, and the value of the session is shown as the result. After
the test the outcome of each entry (passed, failed, not applicable, indeterminate) is shown in the
list of the items and in a column of the table of the children, counted below the panel with
«Nascondi esiti», and given to badges (use.outcome, use.outcomeStale once the model has
changed), so that the host can show it on the diagram. «Diagnostica» opens the session on the
diagram, one evaluation at a time; «Torna all'editor» goes back to the catalog. The feature test
turns it off.
Logo and title
The header shows a logo and the title "DMN Editor"; the host can replace them:
<dmn-editor [xml]="xml" brandTitle="Regole del credito" brandLogo="/assets/logo.svg" />brandTitle: the text next to the logo; an empty string shows the logo alone.brandLogo: the URL of an image (adata:URI too), shown 26 px high;undefined(default) for the default logo,nullfor no logo.- The
brandfeature hides both.
Leading action
The host can put a button of its own first in the header, before the logo and the views, with a
separator after it: typically "Indietro" to go back to a list of the application. The editor does
not know what it is for: it only emits leadingActionClick, and the host navigates.
<!-- icon and label: "← Moduli" -->
<dmn-editor
[xml]="xml"
[saveHandler]="save"
[leadingAction]="{ label: 'Moduli' }"
(leadingActionClick)="router.navigate(['/modules'])"
/>
<!-- icon only: the label becomes aria-label and title -->
<dmn-editor
[xml]="xml"
[saveHandler]="save"
[leadingAction]="{ label: 'Moduli', icon: 'back', display: 'icon' }"
(leadingActionClick)="router.navigate(['/modules'])"
/>label: the text of the button; withdisplay: 'icon'itsaria-labelandtitle.icon: a built-in icon,'back'(default, an arrow to the left),'close'or'home'; the URL of an image (adata:URI too), whose shape is drawn in the color of the text; or the classes of an icon font loaded by the host (for example'fa fa-arrow-left').display:'text'(default) for icon and label,'icon'for the icon only.
Before emitting, the editor saves: it waits for the save in progress (also an auto-save) and saves
the changes not saved yet with saveHandler, also with autoSave off. When the save fails it does
not emit and shows the error in the header, as for any save ("Riprova", or the button again). In
read-only mode it emits at once.
Features
features turns off parts of the editor; the keys not given stay on
(DEFAULT_EDITOR_FEATURES), except autoSaveToggle, off unless given. A feature turned off is not
shown at all.
<dmn-editor [xml]="xml" [features]="{ xmlView: false, importModel: false, minimap: false }" />| Key | What it controls |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| brand | the logo and the title in the header (see brandLogo and brandTitle) |
| fileName | the name of the file in the header |
| xmlView | the "XML" view |
| dataTypes | the "Tipi di dato" view |
| importModel | "Importa" (always off in read-only mode) |
| exportModel | "Esporta" |
| importTrace | "Importa traccia…" |
| exportTrace | "Esporta traccia (JSON)" in the diagnostics |
| explanation | "Spiegazione" in the diagnostics (the evaluation explained in plain words, to print or download) |
| performance | "Prestazioni" in the diagnostics (where the time of the evaluation went, to print or download) |
| onlyPath | «Solo il percorso» in the diagnostics: hides the elements the evaluation did not go through |
| test | the "Prova" panel of the editors |
| diagnostics | "Diagnostica" and the diagnostics view (also for the trace input); without it "Prova" asks for no trace |
| imports | the "Modelli importati" section of the Definitions panel (and the imported elements in the diagram) |
| minimap | the minimap |
| problems | the problems in the status bar |
| tableImport | «Carica da file…», dropping a file and pasting cells in relations and lists |
| tableExport | «Esporta» (CSV, JSON) of relations and lists |
| autoSaveToggle | the switch «Salvataggio automatico» in the header, for the user to turn autoSave on and off (off by default; never in read-only mode) |
A view turned off while it is shown goes back to the diagram. The public methods (open,
save) stay available to the host.
Analysing a trace you already have
To show a model read-only and analyse a trace produced elsewhere (a log, an audit, a test run), give both to the editor:
<dmn-editor [xml]="xml" [readOnly]="true" [trace]="evaluation" />trace is an EvaluationResult with its trace, or the { request, result } written by
"Esporta traccia" (TraceDocument). The editor opens on the diagnostics on the diagram;
"Mostra il modello" shows the diagram and the editors (read-only when readOnly is set) and
the "Diagnostica" button of the header goes back to the trace. "Valuta di nuovo" is offered only
with a feelEvaluator and a request with the element and its inputs.
"Importa traccia…" in the header (also in read-only mode) opens such a JSON file. When the trace has elements the model does not have, or the request names another namespace, the diagnostics say so; those elements stay in the order of evaluation and in the panel, without a shape.
Language
The editor is in English unless the application says otherwise. The locale input wins; without
it the editor follows provideDmnLocale of the application, which also takes a signal to follow
the language of the application, and finally English. A language without texts falls back to
English (with a warning in development mode); auto uses the first browser language the editor
has. The lang attribute of the editor and the format of times and numbers follow the language,
and it can be changed while the editor is open.
providers: [provideDmnLocale('it')];
// or: provideDmnLocale(languageSignal, { dictionaries: { de: GERMAN }, messages: { it: { … } } })<dmn-editor [xml]="xml" locale="it" [messages]="{ meta: { name: 'Italiano' } }" />The editor ships English (EN_MESSAGES, the default) and Italian (IT_MESSAGES, the reference
for the shape of the dictionary) in dmn-core.
To add a language, give a complete dictionary typed DmnMessages (a missing text is a compile
error) with provideDmnLocale(locale, { dictionaries: { de: GERMAN } }); to correct some texts
use messages (input, or the messages option by language). The issues of a validation service
written in English stay in English in a language without templates for them (issues). The
documentation of the FEEL functions in the completion comes from @wemake4u/feel-editor
and is in English.
Validation
The editor always checks the model itself (names, types, references, logic, overlaps and gaps
of the decision tables…). A host may add its own validator, typically a service with more rules
(e.g. DmnModelValidator of a .NET engine): modelValidator receives
{ xml, namespace } with the unsaved changes and returns ModelIssue[]
({ code, severity: 'error' | 'warning' | 'info', message, elementId?, path?, line?, column?, args? }).
validation (all o
