Kapitel 6: Trigger

Was sind Trigger?

Trigger sind ein erweiterter Mechanismus in BillingEngine, der automatisch neue Datensätze erstellt, wenn definierte Bedingungen erfüllt sind. Während Preisregeln entscheiden, welche Preisliste für jeden Datensatz verwendet wird, reagieren Trigger auf den Eingang eines Datensatzes und generieren einen neuen DR auf Basis einer Vorlage (action_template).

Grundprinzip: Ein Trigger ändert nicht die Bewertung eines bestehenden Datensatzes — er erstellt einen separaten neuen Datensatz, der dann durch die Standard-Rating-Engine über Preisregeln bewertet wird.

Typische Anwendungsfälle:

• Aufschläge pro Datensatz — jeder SMS-Datensatz mit Menge > 500 generiert einen zusätzlichen Gebührendatensatz
• Mengenboni — ein Kunde, der 200 Gesprächsminuten im Monat überschreitet, erhält einen Bonusdatensatz
• Treueprogramme — ein Kunde mit mehr als 1.000 Datensätzen insgesamt erhält ein Treueguthaben
• Überschreitungsgebühren — ein Kunde mit mehr als 1.000 SMS im Monat wird für jede weitere SMS belastet

Trigger-Struktur

Ein Trigger besteht aus folgenden Feldern:

POST /api/v1/triggers
Content-Type: application/json

{
  "name": "Aufschlag für große SMS-Charge",
  "conditions": {
    "code": "SMS",
    "quantity": { "op": "gt", "value": 500 }
  },
  "action_template": {
    "code": "SMS_AUFSCHLAG",
    "quantity": 1
  },
  "is_active": true
}

action_template: Die Vorlage für den neuen Datensatz

action_template definiert, wie der bei Triggerauslösung erstellte neue DR aussehen wird. Mindestens muss er code enthalten. Der neue Datensatz erbt automatisch partner_id, customer_id, time_from und time_to vom auslösenden Datensatz.

Spezialwerte:

• "code": "{original}" — der neue Datensatz übernimmt den code des auslösenden Datensatzes
• "external_id": "{original}" — der neue Datensatz übernimmt die external_id des auslösenden Datensatzes

Der neue Datensatz wird nach der Erstellung sofort durch die Standard-Engine bewertet — über Ihre konfigurierten Preisregeln. Damit ein Trigger funktioniert, muss eine Preisregel für den in action_template verwendeten Code existieren.

Skalare Bedingungen

Das Feld conditions ist ein Objekt, dessen Schlüssel Datensatz-Feldnamen entsprechen und dessen Werte entweder ein Skalar (Gleichheit) oder ein Objekt mit Operator sind:

{
  "conditions": {
    "code": "SMS",
    "quantity": { "op": "gt", "value": 500 }
  }
}

Wenn skalare Bedingungen erfüllt sind, wird ein neuer Datensatz für jeden qualifizierenden DR erstellt.

Unterstützte Operatoren:

Aggregatbedingungen

Aggregatbedingungen ermöglichen Entscheidungen basierend auf kumulativen Werten für den aktuellen Monat. Wenn sie erfüllt sind, erstellt der Trigger einen neuen Datensatz pro Kunde (nicht pro DR).

{
  "aggregate_conditions": [
    {
      "func": "sum",
      "field": "quantity",
      "filter": { "code": "VOICE_MIN" },
      "op": "gt",
      "value": 200,
      "group_by": "customer_id"
    }
  ]
}

Struktur einer Aggregatbedingung:

• func — Aggregatfunktion: sum, count, avg, min, max
• field — Datensatzfeld für die Aggregation (quantity, id usw.)
• filter — optionale Bedingungen für die Datensatzauswahl in die Aggregation
• op — Vergleichsoperator (gt Standard, gte, lt, lte, eq)
• value — Schwellenwert
• group_by — Aggregationsdimension (typischerweise customer_id)

Kombinieren von Bedingungen

Ein Trigger kann beide Bedingungssätze gleichzeitig haben. Beide müssen gleichzeitig erfüllt sein (logisches UND):

{
  "name": "SMS-Treuebonus",
  "conditions": {
    "code": "SMS"
  },
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "filter": { "code": "SMS" },
      "op": "gt",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "SMS_LOYALTY",
    "quantity": 1
  },
  "is_active": true
}

Dieser Trigger wird für einen Kunden ausgelöst, der insgesamt mehr als 1.000 SMS gesendet hat UND dessen aktueller Datensatz ebenfalls eine SMS ist. Das Ergebnis ist EIN neuer SMS_LOYALTY-Datensatz pro Kunde.

Integration mit Preisregeln

Der gesamte Preismechanismus für Trigger funktioniert über Standard-Preisregeln:

1. Erstellen Sie eine Preisliste mit einer Position für den in action_template verwendeten Code (z.B. SMS_AUFSCHLAG)
2. Erstellen Sie eine Preisregel, die auf diese Preisliste verweist
3. Wenn der Trigger auslöst, erstellt er einen DR mit dem angegebenen Code — die Regel bewertet ihn automatisch

Beispiel: Trigger generiert SMS_AUFSCHLAG-Datensätze → eine Regel mit billing_category: "retail" verweist auf eine Preisliste mit Position code: "SMS_AUFSCHLAG" und Preis 0,50 EUR → der Kunde wird für jede Triggerauslösung belastet.

Praxisbeispiele

Beispiel 1: SMS-Überschreitungsgebühr

Ein Betreiber hat einen Grundtarif für die ersten 1.000 SMS pro Monat. Für jede SMS über diesem Limit zahlt der Kunde einen höheren Tarif.

{
  "name": "SMS-Überschreitungsgebühr",
  "conditions": {
    "code": "SMS"
  },
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "filter": { "code": "SMS" },
      "op": "gte",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "SMS_UEBERSCHREITUNG",
    "quantity": 1
  },
  "is_active": true
}

Nach Erreichen von 1.000 SMS im Monat generiert die Engine für jede weitere SMS einen SMS_UEBERSCHREITUNG-Datensatz, der zum höheren Tarif bewertet wird.

Beispiel 2: Monatlicher Sprachbonus

Kunden, die mehr als 200 Gesprächsminuten im Monat haben, erhalten einen Bonusdatensatz mit negativem Preis (Rabatt).

{
  "name": "Sprach-Volumen — monatlicher Bonus",
  "conditions": {
    "code": "VOICE_MIN"
  },
  "aggregate_conditions": [
    {
      "func": "sum",
      "field": "quantity",
      "filter": { "code": "VOICE_MIN" },
      "op": "gt",
      "value": 200,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "VOICE_BONUS",
    "quantity": 1
  },
  "is_active": true
}

Beispiel 3: Treueprogramm

Ein Kunde, der im Monat mehr als 1.000 Datensätze überschreitet, erhält ein Treueguthaben.

{
  "name": "Treueprogramm — 1000+ Datensätze",
  "conditions": {},
  "aggregate_conditions": [
    {
      "func": "count",
      "field": "id",
      "op": "gt",
      "value": 1000,
      "group_by": "customer_id"
    }
  ],
  "action_template": {
    "code": "LOYALTY_GUTHABEN",
    "quantity": 1
  },
  "is_active": true
}

Trigger vs. Preisregeln

Preisregeln und Trigger ergänzen sich gegenseitig — Regeln bewerten ursprüngliche Datensätze, Trigger fügen ergänzende Datensätze für Sonderszenarien hinzu.

Best Practices

Immer eine Regel für den action_template-Code erstellen. Trigger generieren neue DRs — ohne eine passende Preisregel endet der neue Datensatz im Fehlerstatus.

action_template-Codes klar benennen. SMS_UEBERSCHREITUNG, VOICE_BONUS, LOYALTY_GUTHABEN sind aussagekräftige Namen. Ein klarer Code erleichtert die Preislistenkonfiguration und das Debugging.

Auf historischen Daten testen. Aggregatbedingungen hängen von der Kundenhistorie ab — überprüfen Sie beim Bereitstellen eines neuen Triggers, wie er sich für Kunden mit unterschiedlichem Volumen verhält.

Datensätze mit source=trigger überwachen. Von Triggern erstellte Datensätze haben das Flag source: "trigger". Verfolgen Sie deren Anzahl — unerwartet hohe Häufigkeit signalisiert einen schlecht kalibrierten Schwellenwert.

Mit Preisregeln kombinieren. Trigger + Regel = vollständige Preislogik. Standardtarife über Regeln, Boni und Aufschläge über Trigger.

Fazit

Trigger sind das letzte Puzzlestück von BillingEngine. Durch die Kombination skalarer Bedingungen für den aktuellen Datensatz und Aggregatbedingungen für historische Daten ermöglichen sie die Modellierung beliebig komplexer Preisstrategien — von einfachen Aufschlägen bis hin zu ausgefeilten Treueprogrammen. Damit schließt sich der Überblick über die Kernentitäten von BillingEngine. Für spezifische Integrationsszenarien empfehlen wir die API-Dokumentation und die Testumgebung.