Ausdruck-Kontexte (Referenz)

Alle Ausdrücke in Certiflow sind Ausdrücke in der Sprache CEL (Common Expression Language, cel.dev). Diese Seite ist eine technische Referenz der Kontexte, die Certiflow den Ausdrücken bei der Auswertung übergibt. Sie richtet sich an Administratoren, die Ausdrücke schreiben und genau wissen müssen, welche Daten an welcher Stelle zur Verfügung stehen.

Jede Auswertungsstelle erhält einen eigenen Kontext, also die Gesamtheit der Daten, die der Ausdruck lesen kann. Die Syntax und die eingebauten Funktionen der Sprache beschreibt der Artikel Ausdrücke. Welche Kontexte an einer Stelle gelten, sehen Sie auch im Ausdruckseditor: Wählen Sie unter Testen gegen eine Entität aus, können Sie den Kontext dieser Entität aufklappen.

Die Namen der Entitätstypen, die in den Ausdrücken verwendet werden (zum Beispiel supplier für Lieferanten), werden bei der Einrichtung festgelegt. Wenden Sie sich bei Fragen dazu an den Support.

Entity-Kontext

Der Entity-Kontext ist der gemeinsame Basis-Kontext für alle Ausdrücke, die auf einer Entität arbeiten.

{
  "id": 42, // Entitäts-ID (Ganzzahl)
  "entity_type": "supplier", // Name des Entitätstyps
  "entity": {
    // Alle Attributwerte der Entität, adressiert über den Attributnamen.
    // Der Typ richtet sich nach dem Datentyp des Attributs:
    "Name": "Acme GmbH", // Text-Attribut        → string
    "Mitarbeiterzahl": 120, // Ganzzahl/Dezimalzahl → number
    "Aktiv": true, // Ja/Nein-Attribut     → boolean
    "Toleranzbereich": {/* … */}, // Bereichs-Attribut    → JSON-Objekt
    "Allergene": ["Gluten", "Soja"], // Attribut mit mehreren Werten → immer eine Liste
    // Datei-Attribute sind nicht enthalten.
  },
  "tags": ["no_requirements", "priority"], // Namen der zugewiesenen Tags (Array von Strings)
  "predecessors": {
    // Direkte Vorgänger-Entitäten, gruppiert nach Name des Entitätstyps
    "product": [
      {
        "id": 5,
        "entity_type": "product",
        "entity": {/* … */},
        "tags": [],
        "predecessors": {},
        "successors": {},
      },
    ],
  },
  "successors": {
    // Direkte Nachfolger-Entitäten, gruppiert nach Name des Entitätstyps
    "location": [
      {
        "id": 7,
        "entity_type": "location",
        "entity": {/* … */},
        "tags": [],
        "predecessors": {},
        "successors": {},
      },
    ],
  },
}

Feldübersicht:

Feld	Typ	Bedeutung
`id`	Ganzzahl	Eindeutige ID der Entität.
`entity_type`	String	Der Name des Entitätstyps (z. B. `supplier`).
`entity`	Objekt	Alle Attributwerte der Entität, adressiert über den Attributnamen. Der Werttyp richtet sich nach dem Datentyp des Attributs. Ein Attribut ohne Wert fehlt im Objekt.
`tags`	String-Array	Namen der dieser Entität zugewiesenen Tags.
`predecessors`	Objekt	Direkte Vorgänger, gruppiert nach Entitätstyp. Jeder Eintrag ist selbst ein Entity-Kontext.
`successors`	Objekt	Direkte Nachfolger, gruppiert nach Entitätstyp. Jeder Eintrag ist selbst ein Entity-Kontext.

Hinweise:

Fehlende Attribute: Ein Attribut ohne Wert ist im Objekt entity nicht enthalten, es hat also nicht den Wert null. Der Zugriff in der Index-Schreibweise, zum Beispiel entity["Umsatz"], liefert dafür null. Ob ein Attribut einen Wert hat, prüfen Sie mit "Umsatz" in entity. Näheres steht im Abschnitt Fehlende Werte.
Mehrere Werte: Attribute, die mehrere Werte aufnehmen können, sind immer Listen, auch wenn nur ein Wert hinterlegt ist. Soll eine Bedingung für alle Werte gelten, verwenden Sie das Listen-Makro all, genügt ein passender Wert, das Makro exists. Einwertige Attribute bleiben Einzelwerte. Beispiele für ein Attribut Messwerte mit mehreren Zahlenwerten: entity["Messwerte"].all(v, v <= 0.1) und entity["Messwerte"].exists(v, v <= 0.1).
Tags: Auch die Tags der verknüpften Entitäten sind lesbar. Ein Tag an einem Lieferanten kann damit über die Regelsets seiner Produkte entscheiden, zum Beispiel mit predecessors["supplier"].exists(p, p.tags.exists(t, t == "kritisch")).
Tiefe: Vorgänger werden nur in Vorgänger-Richtung, Nachfolger nur in Nachfolger-Richtung berücksichtigt, um Zyklen zu vermeiden. Die verschachtelten predecessors- und successors-Objekte innerhalb verknüpfter Entitäten sind daher immer leer.

Message-Kontext

Beim Versand von Nachrichten wird der Entity-Kontext um Nachrichten-spezifische Felder erweitert.

{
  // Felder des Entity-Kontexts:
  "id": 42,
  "entity_type": "supplier",
  "entity": {/* … */},
  "tags": [],
  "predecessors": {/* … */},
  "successors": {/* … */},

  // Zusätzliche Felder des Message-Kontexts:
  "is_message": true,
  "message": {
    "contact": "supplier@example.com", // E-Mail-Adresse des Empfängers
    "type": "reminder", // "reminder" | "misc" | "lock" | "unlock" | "document_rejection" | "campaign"
    "is_initial_reminder": false, // true, wenn für diese Entität noch keine Erinnerung versendet wurde
    "items": [
      {
        "name": "ISO-Zertifikat", // Name des Checklistenpunkts
        "name_en": "ISO Certificate", // Name des Checklistenpunkts (Englisch)
        "document_type_id": 3, // ID des Dokumenttyps
      },
    ],
  },
}

Eine Erstanfrage ist technisch eine Erinnerung, für die is_initial_reminder den Wert true hat. Einen eigenen Typ dafür gibt es nicht.

Config-Kontext

Ausdrücke können Werte aus den Einstellungen lesen. Dafür steht die Variable config zur Verfügung, die zusätzlich zum Entity-Kontext bereitgestellt wird.

{
  "config": {
    // Ein Eintrag pro lesbarem Schlüssel, adressiert über den vollständigen Schlüssel.
    "message.reminder.interval_days": 7, // Schlüssel vom Typ Ganzzahl → Zahl
    "checklist_item.default_grace_period_days": 0,
    "message.reminder.bcc_to": null, // nirgends gesetzt oder vom Datensatz abhängig
    "custom.countries": ["DE", "AT"], // eigener Wert → Typ des gespeicherten Werts
  },
}

Für das Lesen gelten diese Regeln:

Nur die Index-Schreibweise. Lesen Sie einen Wert immer mit dem vollständigen Schlüssel, zum Beispiel config["message.reminder.interval_days"]. Die Punkt-Schreibweise funktioniert nicht, weil die Schlüssel selbst Punkte enthalten.
Auflösung für die Entität. Der Wert gilt für die Entität, für die der Ausdruck ausgewertet wird: zuerst der Wert an der Entität selbst, sonst der nächste Wert an einer übergeordneten Entität, sonst der globale Wert, sonst der Standardwert. Ein Ausdruck an einer Bezugsquelle sieht also den Wert, der an ihrem Lieferanten gesetzt ist. Die Vererbung beschreibt der Artikel Einstellungen.
Typ. Der Wert hat den Typ des Schlüssels: Ein Schlüssel vom Typ Ganzzahl liefert eine Zahl, ein JSON-Schlüssel ein Objekt oder eine Liste. Ein eigener Wert (custom.<name>) behält den Typ des gespeicherten Werts.
null. Ist ein lesbarer Schlüssel nirgends gesetzt, liefert config den Wert null. Das gilt auch für einen gespeicherten Wert, der selbst von den Daten der Entität abhängt, etwa eine Blindkopie-Adresse, die aus entity berechnet wird. Sichern Sie Größenvergleiche daher ab, zum Beispiel mit config["x"] != null && config["x"] > 5.
Lesbare Schlüssel. Alle Schlüssel sind lesbar mit Ausnahme des Firmenlogos. Steht im Ausdruck ein Schlüssel als fester Text, den es nicht gibt oder der nicht lesbar ist, wird der Ausdruck beim Speichern abgelehnt. Bei eigenen Werten wird dagegen jeder korrekt gebildete Name akzeptiert, auch ein noch nicht angelegter. Ein Tippfehler im Namen fällt deshalb nicht auf und liest null.

Lässt sich ein Wert für eine Entität nicht auflösen, etwa wegen eines Konflikts zwischen zwei übergeordneten Entitäten oder weil der gespeicherte Wert nicht zum Typ des Schlüssels passt, ist das bei der Auswertung ein Fehler. Ein Regelset überspringt dann diese Entität, ihre Checklisten bleiben unverändert. Die Erzeugung eines Spezifikations-PDFs schlägt in diesem Fall fehl.

Wo `config` verfügbar ist

config können Sie in Regelsets, im Erfüllungstyp-Ausdruck, im Karenzzeit-Ausdruck, im Filter eines Spezifikationseintrags und in den Platzhaltern von Kampagnen-Nachrichten verwenden. Nicht verfügbar ist es:

in den Auto-Genehmigungsausdrücken, die gar keine Daten erhalten,
in den Werten der Einstellungen selbst,
in den Formularausdrücken (Sichtbarkeit und Validierung). Das Lieferantenportal wertet diese Ausdrücke ebenfalls aus und kennt config nicht. Ein Ausdruck, der config liest, wird dort beim Speichern abgelehnt.

Änderungen an Einstellungen

Ändern oder löschen Sie einen Wert, den ein gespeicherter Ausdruck eines Regelsets, eines Erfüllungstyps oder einer Karenzzeit liest, werden die Regelsets neu ausgewertet. Bei einem Wert an einer Entität betrifft das diese Entität und alle darunter, bei einem globalen Wert alle Entitäten. Die Neuauswertung läuft im Hintergrund. Nicht neu berechnet werden dagegen die Karenzfristen bestehender Checklistenpunkte und bereits erzeugte Spezifikations-PDFs.

Formular-Kontext

Die Ausdrücke von Formularelementen erhalten zusätzlich zum Entity-Kontext die Variable form. Sie enthält die bisherigen Antworten des Lieferanten. Pro Formularelement gibt es einen Eintrag unter dem Schlüssel des Elements, auch wenn es noch nicht beantwortet wurde:

Elementtyp	Wert in `form.schluessel`
Textfeld, Mehrzeiliges Textfeld, Auswahlfeld, Datumsfeld, Uhrzeitfeld, Entitäts-Dropdown	Text
Checkbox	Wahrheitswert
Zahlenfeld	Zahl
Nicht beantwortet, Überschrift, Freitext, Gruppe	`null`

Mit form.frage == null lässt sich daher für jeden Typ prüfen, ob eine Frage unbeantwortet ist.

Das Lieferantenportal wertet die Sichtbarkeit und den Optionsfilter eines Elements serverseitig mit den Daten der Entität und den bisherigen Antworten aus, beim Einreichen werden sie erneut geprüft. Ein fehlerhafter Sichtbarkeits-Ausdruck lässt das Feld sichtbar, damit ein Pflichtfeld nicht unbemerkt verschwindet. Die Einrichtung von Formularen beschreibt der Artikel Formulare.

Auswertungsstellen

Die folgende Tabelle listet die Stellen auf, an denen Certiflow Ausdrücke auswertet, mit dem jeweils übergebenen Kontext.

#	Feld in der Oberfläche	Ergebnis	Kontext
1	Regelset: Ausdruck	Wahrheitswert	Entity-Kontext, `config`
2	Checklistenpunkt: Erfüllungstyp-Ausdruck	Text	Entity-Kontext, `config`
3	Checklistenpunkt: Karenzzeit-Ausdruck (Sekunden)	Ganze Zahl	Entity-Kontext, `config`
4	Checklistenpunkt: Auto-Genehmigungsrate-Ausdruck	Zahl von 0 bis 100	keiner
5	Checklistenpunkt: Auto-Genehmigungsablaufzeit-Ausdruck	Ganze Zahl (Sekunden)	keiner
6	Blindkopie-Adressen von Nachrichten (Einstellungen)	Text	Entity- und Message-Kontext
7	Spezifikationsvorlage: Filter	Wahrheitswert	Entity-Kontext, `config`
8	Formularelement: Sichtbarkeits-Ausdruck	Wahrheitswert	Entity-Kontext, Formular-Kontext
9	Formularelement: Validierungs-Ausdruck	Text	Entity-Kontext, Formular-Kontext
10	Freigabepflicht von Portal-Änderungen (ohne Oberfläche)	Wahrheitswert	Entity-Kontext
11	Auswahlfeld: Optionsfilter-Ausdruck	Liste von Texten	Entity-Kontext, Formular-Kontext

Dazu kommen der Vorfilter von Automatisierungsregeln und die Platzhalter in den Nachrichten von Kampagnen. Deren Kontexte beschreiben die jeweiligen Artikel.

1. Regelset-Auswertung

Ergebnis: Wahrheitswert · Kontext: Entity-Kontext und config

Bestimmt für jede Entität, ob ein Regelset zutrifft, und damit, welche Checklisten und Prüfpläne aktiv werden. Ein Fehler und ein leerer Ausdruck zählen als false: Die Entität wird dann nicht erfasst.

entity_type == "supplier" && entity["Land"] == "DE" && "Umsatz" in entity && entity["Umsatz"] > 1000000

2. Erfüllungstyp eines Checklistenpunkts

Ergebnis: Text (expiration_date, file_assigned oder always) · Kontext: Entity-Kontext und config

Bestimmt beim Erstellen oder Aktualisieren einer Checklisten-Instanz dynamisch den Erfüllungstyp jedes Punkts. Schlägt die Auswertung fehl oder ergibt sie einen ungültigen Wert, wird always als Rückfallwert verwendet.

"Ablaufdatum erforderlich" in entity && entity["Ablaufdatum erforderlich"] ? "expiration_date" : "file_assigned"

3. Karenzzeit

Ergebnis: ganze Zahl in Sekunden · Kontext: Entity-Kontext und config

Bestimmt, wie lange ein neu erforderlicher Checklistenpunkt unerfüllt bleiben darf, bevor er die Entität blockiert (siehe Karenzzeit). Der Kontext ist die Entität, für die der Checklisteneintrag entsteht. Der Ausdruck wird einmal ausgewertet, wenn der Eintrag an der Entität neu entsteht, auch bei manuell zugewiesenen Checklisten. Spätere Änderungen wirken sich nicht auf bestehende Einträge aus. Fehlt der Ausdruck, bleibt das Feld leer oder schlägt die Auswertung fehl, gilt die allgemeine Standard-Karenzzeit aus den Einstellungen, die ohne weitere Konfiguration 0 Tage beträgt, also keine Karenzzeit. Der Ausdruck wird beim Speichern des Checklistenpunkts geprüft, ein Ergebnis mit Nachkommastelle wird abgelehnt.

"Umsatz" in entity && entity["Umsatz"] > 1000000 ? 30 * 86400 : 7 * 86400

4. Auto-Genehmigungsrate

Ergebnis: Zahl von 0 bis 100 · Kontext: keiner

Beim Zuweisen einer neuen Datei zu einem Checklistenpunkt bestimmt dieser Prozentwert per Zufallsstichprobe, ob die Datei automatisch genehmigt wird. Der Ausdruck erhält keine Eingabedaten und muss daher selbstständig sein.

5. Auto-Genehmigungsablaufzeit

Ergebnis: ganze Zahl in Sekunden · Kontext: keiner

Wird eine Datei automatisch genehmigt, bestimmt dieser Ausdruck, wie lange die Genehmigung gültig ist. Ohne Angabe gelten 365 Tage.

90 * 24 * 60 * 60

6. Blindkopie-Adressen von Nachrichten

Ergebnis: Text (E-Mail-Adresse oder leerer Text) · Kontext: Entity- und Message-Kontext

Die Blindkopie-Adresse einer Nachricht ist ein Wert in den Einstellungen. Sie wird beim Versand ausgewertet und kann dabei die Daten der Entität und der Nachricht lesen. Ein leerer Text bedeutet, dass keine Blindkopie gesendet wird. Es gibt je Nachrichtenart einen Schlüssel:

Nachrichtenart	Schlüssel
Erinnerungen	`message.reminder.bcc_to`
Erstanfragen	`message.initial_request.bcc_to`
Sperrnachrichten	`message.lock_message.bcc_to`
Entsperrnachrichten	`message.unlock_message.bcc_to`
Sonstige Nachrichten	`message.misc.bcc_to`
Dokumentablehnungen	`message.document_rejection.bcc_to`
Kampagnen	`message.campaign.bcc_to`

message.type == "lock" ? "compliance@example.com" : ""

Weil der Ausdruck Daten der Entität liest, lässt er sich nur als Wert an einer Entität speichern. Als globaler Wert wird er im Dialog als „Ungültiger Ausdruck” markiert (siehe Einstellungen).

7. Filter eines Spezifikationsvorlagen-Eintrags

Ergebnis: Wahrheitswert · Kontext: Entity-Kontext und config

Wird beim Erzeugen eines Spezifikations-PDFs für jeden Eintrag ausgewertet. Nur Einträge, die true ergeben, erscheinen im Dokument. Der Kontext wird für die Zielgruppe der Vorlage aufgebaut, die Attributwerte sind also auf die für diese Zielgruppe sichtbaren Werte gefiltert. Ein Fehler bei der Auswertung verhindert die Erzeugung des gesamten Dokuments. Schon beim Speichern wird der Filter gegen einen Entitätskontext geprüft, ein syntaktisch falscher Ausdruck oder einer ohne Wahrheitswert wird abgelehnt.

entity["Produktkategorie"] == "lebensmittel"

8. Sichtbarkeit eines Formularelements

Ergebnis: Wahrheitswert · Kontext: Entity-Kontext und Formular-Kontext

Der Ausdruck liefert true, wenn das Element gezeigt werden soll, und false, wenn es ausgeblendet wird. Das Lieferantenportal wertet ihn beim Ausfüllen serverseitig aus, beim Einreichen wird er erneut geprüft. Der Kontext ist der Kontext der Entität, für die das Formular ausgefüllt wird, zuzüglich form. Ein fehlerhafter Ausdruck oder ein Ergebnis, das kein Wahrheitswert ist, lässt das Element sichtbar. Der Kontext verlässt den Server nicht, an den Browser wird nur das Ergebnis übergeben.

9. Validierung eines Formularelements

Ergebnis: Text · Kontext: Entity-Kontext und Formular-Kontext

Prüft eine Bedingung, die sich mit den Einstellungen eines einzelnen Feldes nicht ausdrücken lässt. Das Ergebnis ist der Text, den der Lieferant als Begründung sieht. Ein leeres Ergebnis oder null bedeutet, dass die Antwort gültig ist. Das Lieferantenportal prüft den Ausdruck bereits während der Eingabe, bei der Einreichung wird er erneut geprüft. Ausgeblendete Felder werden nicht geprüft. Typisch ist eine Gruppe, in der mindestens eine Frage mit „Ja“ beantwortet sein muss:

form.frage_a == "Ja" || form.frage_b == "Ja"
  ? ""
  : "Mindestens eine dieser Fragen muss mit Ja beantwortet werden."

10. Freigabepflicht von Portal-Änderungen

Ergebnis: Wahrheitswert · Kontext: Entity-Kontext

Bei jeder Änderung über das Lieferantenportal, also beim Anlegen oder Ändern von Stammdaten, entscheidet ein Ausdruck am Entitätstyp, ob ein Administrator die Änderung freigeben muss (true) oder nicht (false). Beim Anlegen existiert der Datensatz noch nicht. Der Kontext beschreibt ihn dann so, als gäbe es ihn bereits, mit den übergeordneten Datensätzen, die der Lieferant angegeben hat. Die eingereichten Attributwerte sind bewusst nicht Teil des Kontexts. Ist der Ausdruck nicht gesetzt, leer, fehlerhaft oder kein Wahrheitswert, ist immer eine Freigabe nötig. Dieser Ausdruck hat keine Oberfläche und wird bei der Einrichtung festgelegt, wenden Sie sich dazu an den Support. Die Prüfung erfolgt unter Portal-Einreichungen.

11. Optionsfilter eines Auswahlfelds

Ergebnis: Liste von Texten · Kontext: Entity-Kontext und Formular-Kontext

Der Ausdruck liefert die Optionen, die ein Auswahlfeld anbietet. Der Kontext ist derselbe wie bei der Sichtbarkeit (Stelle 8): die Entität, für die das Formular ausgefüllt wird, zuzüglich der bisherigen Antworten unter form. Das Lieferantenportal wertet ihn beim Ausfüllen serverseitig aus und gibt nur das Ergebnis an den Browser weiter. Beim Einreichen wird er für den Modus Ausblenden erneut geprüft, ebenso beim automatischen Ausfüllen aus einem früheren Eintrag.

Ein leeres Ergebnis, null, ein Fehler im Ausdruck oder ein Ergebnis, das keine Liste von Texten ist, bedeutet: kein Filter, alle Optionen bleiben verfügbar. Eine leere Liste heißt also nie „nichts ist erlaubt“. Namen in der Liste, die keine Option des Felds sind, haben keine Wirkung. Das Beispiel steht im Artikel Formulare.

Vorfilter einer Automatisierungsregel

Der Vorfilter einer Automatisierungsregel wird über die Variable trigger ausgewertet. Welche Angaben darin zur Verfügung stehen, hängt vom Auslöser ab.

Angabe	Auslöser	Bedeutung
`kind`, `entity_id`, `entity_type`	alle	Art des Ereignisses sowie Kennung und Typ der betroffenen Entität
`message_id`	Eingehende Mail	Kennung der E-Mail
`mail_contact`	Eingehende Mail	Absender
`subject`	Eingehende Mail	Betreff
`recipients`	Eingehende Mail	alle Empfängeradressen in Kleinbuchstaben (An, Kopie, Zustellkopfzeilen)
`mailbox`	Eingehende Mail	das Postfach, in dem die E-Mail eingegangen ist
`attachment_names`, `attachment_mimetypes`, `attachment_document_type_ids`	Eingehende Mail	Namen, Dateitypen und Dokumenttypen der Anhänge
`file_id`, `file_name`, `file_mimetype`, `document_type_id`	Dokumenttyp erkannt	Angaben zur Datei. `document_type_id` ist nur gesetzt, wenn die Datei einen Dokumenttyp hat

Fehlende Texte gelten als leerer Text und fehlende Listen als leere Liste, damit ein Ausdruck nicht an einer fehlenden Angabe scheitert. Beim Speichern wird der Vorfilter gegen die Angaben seines Auslösers geprüft, ein fehlerhafter Ausdruck oder ein nicht vorhandenes Feld wird dabei abgelehnt. Lässt sich ein gespeicherter Vorfilter bei einem Ereignis dennoch nicht auswerten, trifft er still nicht zu, es erscheint keine Fehlermeldung.

Prüfung beim Speichern

Beim Speichern wertet Certiflow jeden Ausdruck einmal probeweise aus. Die Prüfung läuft gegen die erste aktive Entität des Systems, bei den Auto-Genehmigungsausdrücken ohne Daten. Gibt es noch keine Entität, wird gegen leere Daten geprüft. Ein leerer Ausdruck wird ohne Prüfung angenommen. Weil die Beispielentität nicht zum vorgesehenen Typ passen muss, kann ein Ausdruck abgelehnt werden, der für die vorgesehenen Entitäten richtig wäre, wenn ihr ein gelesenes Attribut fehlt und der Ausdruck dadurch einen Fehler ergibt. Sichern Sie Größenvergleiche deshalb wie im Abschnitt Fehlende Werte beschrieben ab.