Zen-Expression-Kontexte (Referenz)

Diese Seite ist eine technische Referenz der Kontexte, die Certiflow den Zen-Ausdrücken bei der Auswertung übergibt. Sie richtet sich an Integratoren und 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 – ein JSON-Objekt, das als Eingabe an die Ausdrucks-Engine übergeben wird. Felder, die einen Ausdruck enthalten, heißen typischerweise <feld>_expr; auch dynamische Konfigurationswerte sind Ausdrücke.

Die Syntax und die eingebauten Funktionen der Sprache beschreibt der Artikel Ausdrücke (Zen Expressions).

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",       // expression_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
    "employee_count": 120,         // Ganzzahl/Dezimalzahl → number
    "is_active": true,             // Ja/Nein-Attribut     → boolean
    "tolerance_range": { /* … */ } // Bereichs-Attribut    → JSON-Objekt
    // Datei-Attribute (blob) werden nicht unterstützt.
  },
  "tags": ["no_requirements", "priority"],  // Namen der zugewiesenen Tags (Array von Strings)
  "predecessors": {
    // Direkte Vorgänger-Entitäten, gruppiert nach expression_name des Entitätstyps
    "product": [
      { "id": 5, "entity_type": "product", "entity": { /* … */ }, "tags": [], "predecessors": {}, "successors": {} }
    ]
  },
  "successors": {
    // Direkte Nachfolger-Entitäten, gruppiert nach expression_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 `expression_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.
`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.

Hinweis zur Tiefe: Vorgänger werden nur in Vorgänger-Richtung, Nachfolger nur in Nachfolger-Richtung rekursiv verfolgt – um Zyklen zu vermeiden. Die verschachtelten predecessors/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"
    "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
      }
    ]
  }
}

Auswertungsstellen

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

#	Feld	Rückgabetyp	Kontext
1	`rule_set.engine_content`	`boolean`	Entity-Kontext
2	`checklist_item.fulfillment_type_expr`	`string`	Entity-Kontext
3	`checklist_item.auto_approve_rate_expr`	`number` (0–100)	keiner (in Entwicklung)
4	`checklist_item.auto_approve_expiration_time_expr`	`number` (Sekunden)	keiner (in Entwicklung)
5	Message-BCC (dynamische Konfiguration)	`string`	Entity- + Message-Kontext
6	`specification_template_entry.filter_expr`	`boolean`	Entity-Kontext
7	`form_item.visibility_expr`	`boolean`	clientseitig

1. Regelset-Auswertung

Feld: rule_set.engine_content · Rückgabe: boolean · Kontext: Entity-Kontext

Bestimmt für jede Entität, ob ein Regelset zutrifft, und damit, welche Checklisten und Prüfpläne aktiv werden.

entity.country == "DE" and entity.revenue > 1000000

2. Erfüllungstyp eines Checklistenpunkts

Feld: checklist_item.fulfillment_type_expr · Rückgabe: string (expiration_date, file_assigned oder always) · Kontext: Entity-Kontext

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.

entity.requires_expiry_date ? "expiration_date" : "file_assigned"

3. Auto-Genehmigungsrate

Feld: checklist_item.auto_approve_rate_expr · Rückgabe: number (0–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.

4. Auto-Genehmigungsablaufzeit

Feld: checklist_item.auto_approve_expiration_time_expr · Rückgabe: number (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

5. Message-BCC-Empfänger

Felder (dynamische Konfigurationsschlüssel): ReminderBccTo, InitialRequestBccTo, LockMessageBccTo, UnlockMessageBccTo, MiscMessageBccTo, DocumentRejectionBccTo · Rückgabe: string (E-Mail-Adresse oder leerer String) · Kontext: Entity- + Message-Kontext

Bestimmt beim Versand von Nachrichten dynamisch einen BCC-Empfänger.

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

6. Filter eines Spezifikationsvorlagen-Eintrags

Feld: specification_template_entry.filter_expr · Rückgabe: boolean · Kontext: Entity-Kontext

Wird beim Erzeugen eines Spezifikations-PDFs für jeden Eintrag ausgewertet. Nur Einträge, die true ergeben, erscheinen im Dokument. Der Kontext wird mit der target_audience_id der Vorlage aufgebaut – die Attributwerte sind also auf die für diese Zielgruppe sichtbaren Werte gefiltert.

entity.product_category == "food"

7. Sichtbarkeit eines Formularelements

Feld: form_item.visibility_expr · Rückgabe: boolean

Bestimmt, ob ein Formularelement im Lieferantenportal angezeigt wird. Dieser Ausdruck wird nicht serverseitig ausgewertet; der Wert wird nur an den Client übergeben und dort ausgewertet. Der genaue Kontext hängt von der Client-Implementierung ab.