Relaties

Relaties geven je toegang tot gekoppelde entiteiten zoals acties, resultaten en dimensiewaarden. Relaties worden aangegeven met het @-teken.

Basis relaties

@actions

Geeft alle acties die gekoppeld zijn aan de huidige richting/resultaat.

@actions                                   // Alle acties
@actions.count()                           // Aantal acties
@actions[status == "done"]                 // Voltooide acties
@actions.budget.sum()                      // Totaal budget

Actie velden

Veld	Type	Beschrijving
name	Text	Naam van de actie
guid	Text	Unieke identifier
status	Text	Status: "todo", "inprogress", "onhold", "in_review", "done", "canceled", "postponed"
deadline	Date	Deadline (ook beschikbaar als due_date)
due_date	Date	Alias voor deadline
startdate	Date	Startdatum (ook beschikbaar als start_date)
start_date	Date	Alias voor startdate
budget	Number	Budget van de actie

@actions[0].name                           // "Product lanceren"
@actions[status == "done"].count()         // Aantal voltooide acties
@actions.deadline.min()                    // Vroegste deadline
@actions[deadline < today].count()         // Verlopen acties

@results

Geeft alle resultaten die gekoppeld zijn aan de huidige richting.

@results                                   // Alle resultaten
@results.count()                           // Aantal resultaten
@results[status == "on_track"]             // Resultaten op koers
@results.value.sum()                       // Som van alle waarden

Resultaat velden

Veld	Type	Beschrijving
name	Text	Naam van het resultaat
guid	Text	Unieke identifier
result_type	Text	Type: "kpi" of "rating"
value	Number	Huidige meetwaarde (laatste meting)
target	Number	Doelwaarde/norm voor vandaag
status	Text	"on_track", "off_track", of "no_data" (vergelijking value vs norm)

@results[0].value                          // Huidige waarde van eerste resultaat
@results[status == "on_track"].count()     // Aantal resultaten op koers
@results.target.avg()                      // Gemiddelde doelwaarde

Resultaat methodes

Methode	Beschrijving
norm()	Geeft de doelwaarde/norm voor vandaag
norm_at(date)	Geeft de geïnterpoleerde norm op een specifieke datum
value_at(date)	Geeft de meetwaarde op een specifieke datum (dichtstbijzijnde meting)

// Huidige norm vergelijken met waarde
@results[0].value >= @results[0].norm()

// Norm op een specifieke datum
@results[0].norm_at(2024-12-31)

// Historische waarde opvragen
@results[0].value_at(2024-01-15)

// Voortgang berekenen (waarde als percentage van norm)
@results[0].value / @results[0].norm() * 100

Dimensie-relaties

Dimensies zijn categorisaties die aan richtingen kunnen worden gekoppeld, zoals kans, impact, prioriteit, etc.

@dim:{slug}

Geeft de dimensiewaarde met de opgegeven slug (of GUID).

// Met slug (aanbevolen)
@dim:kans

// Of met volledige GUID
@dim:550e8400-e29b-41d4-a716-446655440001

// Typisch gebruik: haal de naam op
@dim:kans.name

Dimensie velden

Een dimensiewaarde-entity heeft deze velden:

Veld	Beschrijving
name	De naam/label van de waarde
color	Kleurcode (hex)
icon	Optioneel icoon

@dim:kans.name                             // "Waarschijnlijk"
@dim:kans.color                            // "#ff9800"

Matchen op dimensiewaarde

Match op de .name eigenschap van de dimensiewaarde:

match @dim:kans.name {
    "Zeer laag" => "Minimaal risico",
    "Laag" => "Laag risico",
    "Gemiddeld" => "Gemiddeld risico",
    "Hoog" | "Zeer hoog" => "Hoog risico",
    _ => "Onbekend"
}

Direction type relaties

@dir:{guid}

Geeft alle richtingwaarden van een bepaald richtingtype.

// Alle risico's van type "operationeel"
@dir:operationeel-risico-guid

// Tel aantal risico's
@dir:operationeel-risico-guid.count()

Voorbeeld: Risicoanalyse

Stel je hebt een risico-template met twee dimensies:

• Kans (slug: kans) - waarden: "Zeer laag", "Laag", "Gemiddeld", "Hoog", "Zeer hoog"
• Impact (slug: impact) - waarden: "Minimaal", "Beperkt", "Ernstig", "Zeer ernstig", "Catastrofaal"

Risico categoriseren

Match op de .name van de dimensiewaarde:

match @dim:kans.name {
    "Zeer laag" | "Laag" => "Laag risico",
    "Gemiddeld" => "Gemiddeld risico",
    "Hoog" | "Zeer hoog" => "Hoog risico",
    _ => "Onbekend"
}

Kleur bepalen

match @dim:kans.name {
    "Hoog" | "Zeer hoog" => "red",
    "Gemiddeld" => "orange",
    _ => "green"
}

Gecombineerde dimensie-evaluatie

if @dim:impact.name == "Catastrofaal" then "Kritiek"
else if @dim:impact.name == "Zeer ernstig" && @dim:kans.name == "Hoog" then "Kritiek"
else if @dim:impact.name == "Ernstig" || @dim:kans.name == "Hoog" then "Hoog"
else "Normaal"

Geneste relaties

Je kunt relaties dieper volgen:

// Alle acties van alle resultaten
@results.actions

// Eigenaren van alle acties
@actions.owner

// Namen van alle eigenaren (met auto-mapping)
@actions.owner.name

Flatten voor aggregatie

Als je geneste relaties hebt die arrays opleveren, gebruik flat() om ze samen te voegen:

// Alle acties van alle resultaten (plat)
@results.actions.flat()

// Totaal budget van alle acties van alle resultaten
@results.actions.flat().budget.sum()

Filteren op relaties

Filter op veld

@actions[status == "done"]
@actions[budget > 1000]
@results[value >= target]

Filter op relatie

// Resultaten met minstens één actie
@results[actions.count() > 0]

// Resultaten waar alle acties af zijn
@results[actions.count() == actions[status == "done"].count()]

Meerdere filters

@actions[status == "todo" && due_date < today]
@results[status == "off_track" && value > 0]

Context en scope

De beschikbare relaties hangen af van de context waarin de DXL-expressie wordt geëvalueerd:

Op een richting (Direction)

• @actions - Acties van deze richting
• @results - Resultaten van deze richting
• @dim:{guid} - Dimensiewaarden van deze richting
• @dir:{guid} - Richtingen van een bepaald type

Op een resultaat (Result)

• Velden: name, guid, result_type, value, target, status
• Methodes: norm(), norm_at(date), value_at(date)
• .dir:{guid} - Gekoppelde richtingen van een bepaald type
• .dim:{guid} - Gekoppelde dimensies van een bepaald type

Op een actie (Action)

• Velden: name, guid, status, deadline, due_date, startdate, start_date, budget
• .dir:{guid} - Gekoppelde richtingen van een bepaald type
• .dim:{guid} - Gekoppelde dimensies van een bepaald type

Velden vs relaties

Het verschil tussen velden en relaties:

Aspect	Veld	Relatie
Syntax	name	@actions
Retourneert	Enkele waarde	Array van entities
Voorbeeld	budget, status	@actions, @results

// Veld: enkele waarde
status                                     // "done"

// Relatie: array
@actions                                   // [Action, Action, ...]

// Veld op array (auto-map)
@actions.status                            // ["done", "todo", ...]

Slugs en GUID's

DXL ondersteunt twee manieren om naar entiteiten te verwijzen:

Slugs (aanbevolen)

Slugs zijn leesbare namen gebaseerd op de entiteitnaam. Ze worden automatisch gegenereerd in snake_case:

Naam	Slug
"Marketing Q1"	marketing_q1
"Kans"	kans
"High Impact"	high_impact

// Met slugs (leesbaar)
@dim:kans.name

// Filter met slug
@actions[product_launch].deadline

GUID's

Je kunt ook directe GUID's gebruiken:

// Met GUID's (technisch)
@dim:550e8400-e29b-41d4-a716-446655440001.name

Slugs vs GUID's

Gebruik slugs voor leesbaarheid. DXL compileert slugs automatisch naar GUID's bij opslag, zodat expressies blijven werken als entiteitnamen veranderen.

GUID's vinden

De GUID's voor dimensies en richtingtypes vind je in:

1. Template configuratie - Bij het definiëren van dimensies
2. Browser developer tools - Inspecteer API responses
3. Admin interface - Beheer van templates

Consistente GUID's

GUID's zijn stabiel binnen een template. Als je een metric definieert voor een template, blijven de GUID's hetzelfde voor alle plannen die dat template gebruiken.