Handbuch zu Event Transformer event-transformer-guide

Auf dieser Seite Sie, wie Ereigniszuordnungen eingehende Ereignisse identifizieren und mithilfe von JSONata-Ausdrücken in das Adobe-Treueereignisformat umwandeln, einschließlich Feldanforderungen, übereinstimmendem Verhalten, Beispielen und API-Vorgängen.

Bevor eine Kundentransaktion auf eine Herausforderung bezüglich des Treueprogramms angewendet werden kann, muss sie im Adobe-Treueereignis-Format erfolgen, das der Challenge-Service versteht. Kundenereignisse - aus einem POS-System, einer mobilen App, einer E-Commerce-Plattform oder einer anderen Quelle - verwenden in der Regel das eigene Datenschema des Kunden. Ereignistransformatoren schließen diese Lücke, ohne dass Änderungen am vorgelagerten System erforderlich sind.

Überblick

Eine Ereigniszuordnung teilt der Plattform zwei Dinge mit:

  • Welche Ereignisse zu beanspruchen - wie erkennt man, dass ein eingehendes Ereignis zu dieser Definition gehört (Abgleich)
  • So formen Sie sie um - ein JSONata-Ausdruck, der die Felder des Kunden dem Treueereignisformat (Transformation) zuordnet

Pro Organisation können mehrere Ereigniszuordnungen konfiguriert werden. Die Plattform bewertet sie der Reihe nach und wendet das erste an, das übereinstimmt. Ereignisse, die keiner Zuordnung entsprechen, fallen in die native Aufnahme (siehe Fallback - native Treueereignisse).

Das Adobe-Treueprogramm-Ereignisformat

Jede Ereigniszuordnung muss ein JSON-Objekt im folgenden Format erzeugen. Dies ist der Input, den der Challenge Service verarbeitet.

{
  "_id":              "string — optional; used for duplicate detection if enabled",
  "event_name":       "string — used for internal metrics and reporting only (e.g. 'purchase', 'visit')",
  "timestamp":        "ISO 8601 date-time string — when the event occurred",
  "utc_offset":       "string — UTC offset of the store or device (e.g. '-07:00'); required for daypart matching",
  "location_id":      "string — optional; store or location identifier",
  "transaction_id":   "string — optional; dedup key for the transaction",
  "loyalty_identity": {
    "id": "string — the member's loyalty ID"
  },
  "item_list": [
    {
      "item_set":   ["string", "..."],  // one or more identifiers — SKU, category, event code, etc.
      "item_name":  "string — optional human-readable label",
      "quantity":   1,                  // integer; how many units
      "unit_price": 4.99,               // float; price per unit
      "sub_total":  4.99                // float; line total (quantity × unit_price)
    }
  ]
}

Hinweise zu Feldern

Feld
Erforderlich
Anmerkungen
loyalty_identity
Ja
Muss id enthalten - die Treueprogramm-ID des Mitglieds.
item_list
Ja
Muss ≥1 Element enthalten; leeres item_list wird abgelehnt.
item_set
Ja (pro Artikel)
Aufgabenkennungen, für die Aufgabenlisten ein-/ausgeschlossen werden.
timestamp
Ja
Wird für die Auswertung eines Datumsfensters verwendet. Muss ISO 8601 sein.
utc_offset
Empfohlen
Wird für die Zuordnung von Tagesabschnitten und die Zählung von Streak-Tagen benötigt.
_id
Nein
Wird für die Deduplizierung verwendet, wenn für die Organisation die Duplikaterkennung aktiviert ist.
sub_total
Nein
Für Aufgaben mit Ausgabenschwellenwert wird dies verwendet. „Auslassen“ bedeutet null Ausgaben.

Felder für die Ereigniszuordnung

Feld
Typ
Erforderlich
Beschreibung
guid
Zeichenfolge
Nein (vom System zugewiesen)
Systemspezifische eindeutige ID; schreibgeschützt.
name
Zeichenfolge
Ja
Vom Menschen lesbare Kennzeichnung, z. B. "Starbucks POS Purchase".
xdmSchemaId
Zeichenfolge
Ja
Sucht nach Ereignissen anhand der XDM-Schema-ID (siehe Funktionsweise von Übereinstimmungen).
schema
Zeichenfolge
Ja
JSON-Schema (als Zeichenfolge) zur Validierung eingehender Ereignisse
transformer
Zeichenfolge
Ja
JSONata-Ausdruck, der das Ereignis dem Treueformat zuordnet.

Funktionsweise von Übereinstimmungen

Ereignisse, die über den Data Collection Core Service (DCCS) eingehen, enthalten eine XDM-Schemareferenz in ihrem Umschlag. Die Plattform liest die Schema-ID aus /body/xdmMeta/schemaRef/id und vergleicht sie mit den xdmSchemaId jeder Definition.

Die Plattform führt die Ereigniszuordnungen der Organisation der Reihe nach und wendet die erste Übereinstimmung an. Sobald eine Übereinstimmung gefunden wurde, wird der xdmEntity an den Transformator übergeben.

Schreiben des Transformators

Das transformer ist ein JSONata-Ausdruck. Er empfängt die eingehende Ereignis-JSON als Eingabe und muss ein gültiges Adobe-Treueereignis-Objekt zurückgeben.

Grundlegendes Zuordnungsmuster

Ordnen Sie jedes Feld der obersten Ebene des Zielformats dem entsprechenden Pfad in Ihrem Quellereignis zu:

code language-jsonata
{
  "_id":            sourceEvent._id,
  "event_name":     sourceEvent.eventType,
  "timestamp":      sourceEvent.timestamp,
  "utc_offset":     sourceEvent.storeInfo.utcOffset,
  "location_id":    sourceEvent.storeInfo.storeId,
  "transaction_id": sourceEvent.transaction.id,
  "loyalty_identity": {
    "id": sourceEvent.member.loyaltyId
  },
  "item_list": sourceEvent.transaction.items.{
    "item_set":   [itemSku, itemCategory],
    "item_name":  itemDescription,
    "quantity":   quantity,
    "unit_price": unitPrice,
    "sub_total":  lineTotal
  }
}
Hartkodierung des Ereignisnamens

Wenn alle Ereignisse, die dieser Definition entsprechen, dieselbe logische Aktivität darstellen, hartcodieren Sie die event_name:

code language-jsonata
{
  "event_name": "in-store-purchase",
  ...
}

event_name wird für interne Metriken und Berichte verwendet. Sie wird nicht als Aufgabenfilter verwendet - die Aufgabenqualifizierung wird durch item_set Inhalte bestimmt, nicht durch den Ereignisnamen.

Zuordnen von Identitäten für DCCS-/XDM-Ereignisse

Bei Ereignissen, die über die DCCS-Route eingehen, wird die Identität des Mitglieds normalerweise im standardmäßigen XDM-identityMap statt in einer benutzerdefinierten Mandanteneigenschaft übermittelt. identityMap ist eine vom Namespace verschlüsselte Zuordnung - der Schlüssel selbst ist der Namespace-Name, und der Wert ist ein Array von Identitätsobjekten.

code language-jsonata
"loyalty_identity": {
  "id": identityMap.Email[0].id
}
  • Namespace-Ersetzung: Ersetzen Sie Email durch den Namespace, den Ihre Organisation für Mitglieder des Treueprogramms verwendet - Loyalty, ECID, CRMID usw. Lesen Sie immer aus dem Namespace, der die primäre Identität des Treueprofils enthält.

  • Verwenden Sie immer [0]: identityMap.Email ist ein Array. Ohne den Index gibt JSONata eine Sequenz anstelle eines einzelnen Werts zurück, wenn mehr als eine Identität vorhanden ist und loyalty_identity.id zu einer Liste wird. An das erste Element mit [0] heften.

  • Benutzerdefinierte Mandantenfelder für die Identität vermeiden Benutzerdefinierte Feldergruppen stellen manchmal ein E-Mail-ähnliches Feld bereit (z. B. _yourtenant.identification.core.email). In Beispieldaten gibt dies einen Wert zurück und sieht korrekt aus, in Produktionsereignissen ist es jedoch häufig leer. Die zuverlässige Identitätsquelle ist immer identityMap.

item_set​

item_set ist ein Array von Zeichenfolgenkennungen. Schließen Sie alle Felder ein, nach denen Ihre Challenge-Aufgaben möglicherweise filtern:

code language-jsonata
"item_set": [itemSku, productCategory, departmentCode]

Bei Ereignissen, die keine Transaktionen sind (ein Check-in, ein Umfrageabschluss, ein benutzerdefinierter Trigger), reicht eine einzelne Kennung aus:

code language-jsonata
"item_set": [eventName]
unit_price​

unit_price sollte ein Preis pro Einheit sein. Einige Quellschemata speichern stattdessen eine Zeilensumme (Preis × Menge). Wenn Ihr Quellfeld eine Positionssumme ist, dividieren Sie durch die Menge, um den Stückpreis zu erhalten:

code language-jsonata
"unit_price": priceTotal / quantity

Nur teilen, wenn das Quellfeld eine Zeilensumme ist. Wenn er bereits einen Preis pro Einheit speichert, mappen Sie ihn direkt — durch Division eines Einheitspreises durch die Menge wird im Hintergrund ein falscher Wert erzeugt.

Ableitung von transaction_id

Wenn Ihr Quellereignis keine Transaktionskennung enthält, können Sie eine stabile aus dem Zeitstempel ableiten:

code language-jsonata
"transaction_id": "txn_" & $string($toMillis(timestamp))

Dies konvertiert den ISO-Zeitstempel in Epochenmillisekunden und erzeugt einen deterministischen Wert für ein bestimmtes Ereignis. Verwenden Sie die ID-Generierungsfunktion Ihrer Plattform, falls verfügbar.

Verwenden von JSON-Datenfunktionen

Die vollständige Bibliothek mit JSONata-Funktionen ist verfügbar. Nützliche Beispiele

code language-jsonata
/* String concatenation */
"item_set": [skuId & ':' & categoryId]

/* Number formatting */
"item_set": ["spend:" & $formatNumber(totalAmount, '0.00')]

/* Conditional field */
"event_name": eventType ? eventType : "unknown"

/* Array transformation */
"item_list": items.{ "item_set": [sku], "quantity": qty, "sub_total": price * qty }

Beispiele

Beispiel 1 - Einfaches benutzerspezifisches Ereignis (keine Transaktion)

Szenario: Eine Mobile App sendet ein Eincheckereignis. Es gibt keine Zeileneinträge - das Ereignis selbst ist die qualifizierende Aktivität.

Eingehendes Ereignis:

code language-json
{
  "_id":       "evt-001",
  "eventName": "store-checkin",
  "timestamp": "2025-10-15T14:22:00Z",
  "storeId":   "STORE-042",
  "member": {
    "loyaltyId": "LM-8827361"
  }
}

Ereigniszuordnung:

code language-json
{
  "name":        "Mobile Store Check-In",
  "xdmSchemaId": "https://ns.adobe.com/yourtenant/schemas/store-checkin-v1",
  "transformer": "{\"_id\": _id, \"event_name\": eventName, \"timestamp\": timestamp, \"location_id\": storeId, \"loyalty_identity\": {\"id\": member.loyaltyId}, \"item_list\": [{\"item_set\": [eventName], \"quantity\": 1}]}"
}

Formatierter Transformator (zur besseren Lesbarkeit):

code language-jsonata
{
  "_id":        _id,
  "event_name": eventName,
  "timestamp":  timestamp,
  "location_id": storeId,
  "loyalty_identity": {
    "id": member.loyaltyId
  },
  "item_list": [
    {
      "item_set": [eventName],
      "quantity": 1
    }
  ]
}

Ausgabe Adobe-Treueereignis:

code language-json
{
  "_id":        "evt-001",
  "event_name": "store-checkin",
  "timestamp":  "2025-10-15T14:22:00Z",
  "location_id": "STORE-042",
  "loyalty_identity": { "id": "LM-8827361" },
  "item_list": [{ "item_set": ["store-checkin"], "quantity": 1 }]
}

Eine Challenge-Aufgabe ohne Ein-/Ausschlussbeschränkungen zählt dieses Ereignis als qualifizierten Besuch. Der einzelne item_set-Eintrag entspricht ["store-checkin"] Aufgabe, die alle Elemente zulässt.

Beispiel 2 — POS-Einkauf mit Zeileneinträgen

Szenario: Ein Point-of-Sale-System sendet eine Transaktions-Payload. Jeder Zeileneintrag hat eine SKU und gehört zu einer Kategorie. Challenge-Aufgaben verwenden SKU und Kategorie, um zu bestimmen, was qualifiziert ist.

Eingehendes Ereignis:

code language-json
{
  "_id":       "txn-20251015-4492",
  "timestamp": "2025-10-15T14:35:00Z",
  "storeInfo": {
    "storeId":   "STORE-042",
    "utcOffset": "-07:00"
  },
  "transaction": {
    "transactionId": "4492",
    "items": [
      { "sku": "COFFEE-001", "category": "BEVERAGE", "qty": 2, "unitPrice": 4.50, "lineTotal": 9.00 },
      { "sku": "MUFFIN-007", "category": "FOOD",     "qty": 1, "unitPrice": 3.25, "lineTotal": 3.25 }
    ]
  },
  "member": {
    "loyaltyId": "LM-8827361"
  }
}

Ereigniszuordnung:

code language-json
{
  "name":        "Retail POS Purchase",
  "xdmSchemaId": "https://ns.adobe.com/yourtenant/schemas/retail-pos-purchase-v1",
  "transformer": "{\"_id\": _id, \"event_name\": \"purchase\", \"timestamp\": timestamp, \"utc_offset\": storeInfo.utcOffset, \"location_id\": storeInfo.storeId, \"transaction_id\": transaction.transactionId, \"loyalty_identity\": {\"id\": member.loyaltyId}, \"item_list\": transaction.items.{\"item_set\": [sku, category], \"quantity\": qty, \"unit_price\": unitPrice, \"sub_total\": lineTotal}}"
}

formatierter Transformator:

code language-jsonata
{
  "_id":            _id,
  "event_name":     "purchase",
  "timestamp":      timestamp,
  "utc_offset":     storeInfo.utcOffset,
  "location_id":    storeInfo.storeId,
  "transaction_id": transaction.transactionId,
  "loyalty_identity": {
    "id": member.loyaltyId
  },
  "item_list": transaction.items.{
    "item_set":   [sku, category],
    "quantity":   qty,
    "unit_price": unitPrice,
    "sub_total":  lineTotal
  }
}

Ausgabe Adobe-Treueereignis:

code language-json
{
  "_id":            "txn-20251015-4492",
  "event_name":     "purchase",
  "timestamp":      "2025-10-15T14:35:00Z",
  "utc_offset":     "-07:00",
  "location_id":    "STORE-042",
  "transaction_id": "4492",
  "loyalty_identity": { "id": "LM-8827361" },
  "item_list": [
    { "item_set": ["COFFEE-001", "BEVERAGE"], "quantity": 2, "unit_price": 4.50, "sub_total": 9.00 },
    { "item_set": ["MUFFIN-007", "FOOD"],     "quantity": 1, "unit_price": 3.25, "sub_total": 3.25 }
  ]
}

Bei einer Challenge-Aufgabe mit include: ["BEVERAGE"] würde der Kaffeezeileneintrag qualifiziert (sein item_set enthält "BEVERAGE") und für diese Aufgabe 9,00 USD an Ausgaben angesammelt. Der Zeileneintrag Muffin würde ausgeschlossen.

Beispiel 3: AEP-Erlebnisereignis (XDM-Schemaabgleich)

Szenario: Ereignisse fließen durch Adobe Journey Optimizer. Das eingehende Ereignis ist ein XDM-Erlebnisereignis mit einer bekannten Schema-ID. Die Plattform verwendet die Schema-ID für die Zuordnung anstelle einer Pfad-/Wertprüfung.

Eingehender XDM-Entitätstext (der aus dem AJO-Ereignis extrahierte xdmEntity):

code language-json
{
  "_brandname": {
    "identities": {
      "loyaltyId": "LM-8827361"
    },
    "transactions": {
      "transactionId": "TXN-9901",
      "storeNumber":   "042",
      "utcOffset":     "-07:00",
      "lineItems": [
        { "skuNumber": "11143053", "priceAmount": 345, "qty": 1, "category": "BEVERAGE" },
        { "skuNumber": "11161387", "priceAmount": 495, "qty": 1, "category": "FOOD" }
      ],
      "totalAmount": 840
    }
  },
  "_id":       "87c0cccf-5809-38e0-a703-3994e80173ab",
  "timestamp": "2025-07-04T16:03:32.000Z"
}

Ereigniszuordnung:

code language-json
{
  "name":        "AJO Brand Purchase",
  "xdmSchemaId": "https://ns.adobe.com/brandname/schemas/purchase-event-v1",
  "transformer":  "{\"_id\": _id, \"event_name\": \"purchase\", \"timestamp\": timestamp, \"utc_offset\": _brandname.transactions.utcOffset, \"location_id\": _brandname.transactions.storeNumber, \"transaction_id\": _brandname.transactions.transactionId, \"loyalty_identity\": {\"id\": _brandname.identities.loyaltyId}, \"item_list\": _brandname.transactions.lineItems.{\"item_set\": [skuNumber, category], \"quantity\": qty, \"unit_price\": priceAmount, \"sub_total\": priceAmount * qty}}"
}

formatierter Transformator:

code language-jsonata
{
  "_id":            _id,
  "event_name":     "purchase",
  "timestamp":      timestamp,
  "utc_offset":     _brandname.transactions.utcOffset,
  "location_id":    _brandname.transactions.storeNumber,
  "transaction_id": _brandname.transactions.transactionId,
  "loyalty_identity": {
    "id": _brandname.identities.loyaltyId
  },
  "item_list": _brandname.transactions.lineItems.{
    "item_set":   [skuNumber, category],
    "quantity":   qty,
    "unit_price": priceAmount,
    "sub_total":  priceAmount * qty
  }
}

Hinweis: Wenn ein Ereignis nach XDM-Schema-ID übereinstimmt, erhält der Transformator nur den xdmEntity Teil des Ereignisses - nicht die äußere AJO-Hülle. Alle Pfade in Ihrem Transformatorausdruck sind relativ zum XDM-Entitätshauptteil.

Hinzufügen der JSON-Schemavalidierung

Das schema ist ein Pflichtfeld. Legen Sie sie auf ein JSON-Schema-Dokument fest, das als JSON-Zeichenfolge codiert ist, um die Struktur der eingehenden Ereignisse vor der Ausführung der Transformation zu überprüfen.

Ereignisse, bei denen die Schemavalidierung fehlschlägt, werden vor der Ausführung der Transformation zurückgewiesen. Die Fehlerantwort enthält den spezifischen Validierungsfehler, sodass falsch formatierte Upstream-Ereignisse einfach diagnostiziert werden können.

Beispielschema (Beispiel 2 oben)
code language-json
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "required": ["_id", "timestamp", "transaction", "member"],
  "properties": {
    "_id":       { "type": "string" },
    "timestamp": { "type": "string", "format": "date-time" },
    "member": {
      "type": "object",
      "required": ["loyaltyId"],
      "properties": {
        "loyaltyId": { "type": "string" }
      }
    },
    "transaction": {
      "type": "object",
      "required": ["items"],
      "properties": {
        "transactionId": { "type": "string" },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["sku", "qty", "lineTotal"],
            "properties": {
              "sku":       { "type": "string" },
              "category":  { "type": "string" },
              "qty":       { "type": "number" },
              "unitPrice": { "type": "number" },
              "lineTotal": { "type": "number" }
            }
          }
        }
      }
    }
  }
}

Übergeben Sie dieses Schema als minimierte JSON-Zeichenfolge im Feld schema der Ereigniszuordnung.

Fallback - native Treueereignisse

Wenn eine Ereigniszuordnung nicht mit einem eingehenden Ereignis übereinstimmt, versucht die Plattform, es direkt als natives Adobe-Treueereignis aufzunehmen. Wenn die Payload bereits dem oben beschriebenen Treueprogramm-Ereignisformat entspricht, ist kein Transformator erforderlich und das Ereignis wird unverändert angewendet. Dadurch können Kunden, die ihre Ereignisse vorformatiert haben, die Transformation vollständig umgehen.

API-Referenz

Alle Vorgänge der Ereigniszuordnung verwenden den Basispfad /loyalty/metadata/config/events.

Erstellen einer Ereigniszuordnung
code language-http
POST /loyalty/metadata/config/events
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}
Content-Type: application/json

{
  "name":        "Retail POS Purchase",
  "xdmSchemaId": "https://ns.adobe.com/yourtenant/schemas/retail-pos-purchase-v1",
  "transformer": "{ ... }"
}
Auflisten der Ereigniszuordnungen
code language-http
GET /loyalty/metadata/config/events
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}
Aktualisieren einer Ereigniszuordnung
code language-http
PUT /loyalty/metadata/config/events/{eventId}
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}
Content-Type: application/json

{
  "name":        "Retail POS Purchase (v2)",
  "transformer": "{ ... updated expression ... }"
}
Löschen einer Ereigniszuordnung
code language-http
DELETE /loyalty/metadata/config/events/{eventId}
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}

Validierung von Transformatoren

JSON-Datenausdrücke werden auf Syntax überprüft, wenn die Ereigniszuordnung gespeichert wird. Wenn der Ausdruck ungültig ist, gibt die API einen 422 mit einer Beschreibung des Analysefehlers zurück.

Um einen Transformator vor der Bereitstellung zu testen, verwenden Sie den JSONata Exerciser - fügen Sie Ihr Quellereignis als Eingabe und Ihren Transformatorausdruck ein, um zu überprüfen, ob die Ausgabe dem erwarteten Format des Treueereignisses entspricht.

Häufige Fehler

Diese Fehler laufen alle ohne Fehler auf einer einfachen Test-Payload mit einem einzelnen Element ab, was genau der Grund ist, warum sie unentdeckt durchrutschen. Testen Sie Ihren Transformator vor der Bereitstellung immer mit zwei oder mehr Produkten gegen eine Payload.

Erstellen eines Objekts anstelle einer Zuordnung über das Array

Der häufigste Fehler. Durch die Verwendung eines einzelnen Objektliterals mit productListItems.SKU wird jede SKU und jede Menge in zusammengefasste Sequenzen gezogen, anstatt einen Zeileneintrag pro Produkt zu erzeugen.

✗Reduziert alle Elemente in einer:

code language-jsonata
"item_list": [
  {
    "item_set": [ productListItems.SKU ],
    "quantity": productListItems.quantity
  }
]

Bei zwei Produkten enthält item_set beide SKUs und quantity wird zu einem Array wie [1, 4].

✓Ein Zeileneintrag pro Produkt:

code language-jsonata
"item_list": [
  productListItems.{
    "item_set": [SKU],
    "quantity": quantity
  }
]

Die .{ }-Map wird einmal pro Produkt ausgeführt, sodass jeder Eintrag zu einem eigenen Eintrag wird.

Array-Index für die Identität wird vergessen

identityMap.Email ist ein Array. Wenn ein Profil in diesem Namespace mehrere Identitäten hat, wird id ohne [0] zu einer Liste von Werten anstelle einer einzigen Zeichenfolge.

✗ identityMap.Email.id

✓ identityMap.Email[0].id

Identitätsabruf über ein benutzerdefiniertes Mandantenfeld
Benutzerdefinierte Feldergruppen stellen manchmal ein E-Mail-ähnliches Feld bereit, z. B. _yourtenant.identification.core.email. In Beispieldaten wird ein Wert zurückgegeben und das Aussehen ist korrekt, in Produktionsereignissen ist er jedoch häufig leer, sodass loyalty_identity.id null herauskommt. Verwenden Sie immer identityMap als Quelle der Identität.
Ein verschachteltes Array, das in item_set gelangt

Das Hinzufügen eines Kategoriefelds zu item_set ist einfach, aber wenn productCategories selbst ein Array ist, wird das Ergebnis unvorhersehbar erweitert.

✗führt möglicherweise zu mehr Einträgen als erwartet:

code language-jsonata
"item_set": [SKU, productCategories.categoryID]

Ein Produkt mit drei Kategorien erzeugt eine item_set mit vier Werten.

✓Indizieren Sie das verschachtelte Array, um genau einen Wert zu erhalten:

code language-jsonata
"item_set": [SKU, productCategories[0].categoryID]
item_list ist leer oder fehlt

Ein Ereignis mit einer leeren oder fehlenden item_list wird als ungültig abgelehnt. Bei Ereignissen, die keine Transaktionen sind (Einchecken, benutzerdefinierte Trigger), gibt es keine natürlichen Zeileneinträge. Erstellen Sie daher einen synthetischen:

code language-jsonata
"item_list": [{ "item_set": [eventName], "quantity": 1 }]
timestamp als Unix-Epochenzahl anstelle von ISO 8601

Die Plattform erwartet eine ISO 8601-Zeichenfolge. Wenn das Quellereignis Millisekunden seit der Epoche zurückliegt, konvertieren Sie es:

code language-jsonata
"timestamp": $fromMillis(timestamp)
utc_offset ausgelassen
Ohne utc_offset werden sowohl der Abgleich des DayPart-Fensters als auch das Zählen aufeinander folgender Tage übersprungen. Ordnen Sie den UTC-Versatz des Speichers oder Geräts von Ihrem Quellereignis zu, wo immer er verfügbar ist.
Transformatorpfade relativ zur AJO-Hülle bei einem DCCS-Ereignis
Bei DCCS-Ereignissen empfängt der Transformator nur den xdmEntity, nicht aber die äußere AJO-Hülle. Alle Pfade müssen relativ zum XDM-Entitätsstamm sein. Wenn Ihr Ausdruck auf Felder verweist, die sich in der äußeren Hülle befinden (z. B. /body/xdmMeta/...), werden sie nicht gefunden und erzeugen im Hintergrund null.
AI Knowledge Reference

This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.

For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.

  • TL;DR: This page explains how to configure Event Mapping schema validation and JSONata transformer expressions so that incoming customer events are matched and reshaped into the Adobe Loyalty Event format for Loyalty Challenges.

Intents:

  • Understand how an Event Mapping identifies and claims incoming events through XDM schema ID matching.
  • Write a JSONata transformer expression that reshapes a source event into the Adobe Loyalty Event format.
  • Add JSON Schema validation to an event mapping to reject malformed events before transformation.
  • Avoid common transformer mistakes such as collapsing multiple line items into one object or losing array indices on identity fields.
  • Use the API operations to create, list, update, and delete event mappings.
  • Understand the native Loyalty Event fallback for events that do not match any mapping.

Glossary:

  • Event Mapping: a configuration that tells the platform which events to claim (matching) and how to reshape them (transformation) (product-specific)
  • Adobe Loyalty Event: the JSON object format that the Challenge Service processes (product-specific)
  • Transformer: a JSONata expression that receives the incoming event JSON and returns a valid Adobe Loyalty Event object (product-specific)
  • item_set: an array of string identifiers on a line item that challenge tasks’ include/exclude lists match against (product-specific)
  • xdmSchemaId: the field on an event mapping that is compared against the schema ID read from an incoming event’s envelope to determine a match (product-specific)
  • Data Collection Core Service (DCCS): the service through which events carrying an XDM schema reference in their envelope arrive (product-specific)
  • Native Loyalty Event: an event that is ingested directly, without a transformer, when it already conforms to the Adobe Loyalty Event format (product-specific)

Guardrails:

  • loyalty_identity is required and must contain id, the member’s loyalty ID.
  • item_list is required and must have at least one item; an empty item_list is rejected.
  • item_set is required per item.
  • timestamp is required and must be ISO 8601.
  • utc_offset is recommended; it is needed for daypart matching and streak-day counting, and without it daypart window matching and consecutive-day streak counting are both skipped.
  • _id is optional, used for dedup if the org has duplicate detection enabled.
  • sub_total is optional; omitting it means zero spend for spend-threshold tasks.
  • In the Event Mapping configuration, name, xdmSchemaId, schema, and transformer are required fields; guid is system-assigned and read-only.
  • The platform walks the org’s event mappings in order and applies the first one that matches; events that do not match any mapping fall through to native ingestion.
  • event_name is used only for internal metrics and reporting; it is not used as a task filter — task qualification is determined by item_set contents, not the event name.
  • Events that fail schema validation are rejected before transformation runs.
  • If the transformer’s JSONata expression is invalid, the API returns a 422 error with a description of the parse failure.
  • Once a match is found by xdmSchemaId, the xdmEntity body — not the outer envelope — is passed to the transformer; for DCCS events specifically, paths referencing the outer envelope (e.g. /body/xdmMeta/...) will not be found and will silently produce null.
  • identityMap is an array per namespace; omitting [0] causes JSONata to return a sequence instead of a single value when more than one identity is present, turning loyalty_identity.id into a list.
  • Custom tenant identity-like fields (e.g. _yourtenant.identification.core.email) are frequently empty in production events even though they return a value in sample data; identityMap is the reliable source of identity.
  • Using a single object literal with a path like productListItems.SKU instead of mapping over the array (productListItems.{ ... }) collapses multiple line items into one, with quantity becoming an array instead of a per-item value.
  • If a nested array field (e.g. productCategories) is added to item_set without indexing it, the result can expand to more entries than expected.
  • timestamp must be ISO 8601; a Unix epoch integer must be converted (e.g. with $fromMillis).
  • Dividing unit_price by quantity is only correct if the source field is a line total; dividing an already-per-unit price by quantity silently produces a wrong value.

Terminology:

  • Canonical name: Event Mapping — no documented named variant; the page refers back to an event mapping informally as “this definition” in context, not as a defined synonym.
  • Canonical name: Adobe Loyalty Event — variants: Loyalty Event format
  • Acronym: XDM — Experience Data Model (expansion per the acronyms list; not spelled out on this page, which uses only “XDM”)
  • Acronym: DCCS — expansion not given on the page (“Data Collection Core Service” is the page’s own spelled-out form on first use, not an approved-list acronym)
  • Do not confuse: “the outer AJO envelope” (never passed to the transformer) ≠ “the xdmEntity body” (what the transformer always receives once a match is found, per How Matching Works and the DCCS pitfall)
  • Do not confuse: “Event Mapping” (the matching-and-transformation configuration) ≠ “transformer” (the JSONata expression field within an event mapping)

FAQ:

  • Q: How does the platform decide which event mapping applies to an incoming event? — It reads the XDM schema ID from the event’s envelope, walks the org’s event mappings in order, and applies the first one whose xdmSchemaId matches.
  • Q: What happens to an event that does not match any event mapping? — It falls through to native ingestion as a native Adobe Loyalty Event; if it already conforms to the Loyalty Event format, no transformer is needed.
  • Q: What part of the event does the transformer receive once a match is found? — The xdmEntity body, not the outer envelope.
  • Q: What causes loyalty_identity.id to become a list instead of a single string? — Omitting the [0] index on an identityMap namespace array when more than one identity is present.
  • Q: Why would item_set contain more entries than expected? — Because a nested array field (such as productCategories) was added to item_set without indexing it.
  • Q: What happens if item_list is empty or missing? — The event is rejected as invalid.
  • Q: What happens if the transformer expression has invalid JSONata syntax? — The API returns a 422 error with a description of the parse failure when the event mapping is saved.

Personas:

  • admin: Can create, list, update, and delete event mappings through the API operations at the base path /loyalty/metadata/config/events. Each event mapping requires the name, xdmSchemaId, schema, and transformer fields; guid is system-assigned and read-only. The page states that the platform walks the org’s event mappings in order and applies the first one that matches, and that events failing schema validation are rejected before transformation runs. Where: “API Reference”.

Onboarding:

  • Level: Intermediate
  • First minimal step: Create an event mapping by sending a POST request to /loyalty/metadata/config/events with the name, xdmSchemaId, and transformer fields.
  • Success check: Using the JSONata Exerciser, the transformer expression’s output for the source event matches the expected Adobe Loyalty Event format.
recommendation-more-help
journey-optimizer-help