Guide du transformateur d’événements event-transformer-guide

Mappez chaque champ de niveau supérieur du format cible au chemin d’accès correspondant dans votre événement source :

{
  "_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
  }
}

Si tous les événements correspondant à cette définition représentent la même activité logique, codez en dur le event_name :

{
  "event_name": "in-store-purchase",
  ...
}

event_name est utilisé pour les mesures et les rapports internes. Il n’est pas utilisé comme filtre de tâche — la qualification de la tâche est déterminée par item_set contenu, et non par le nom de l’événement.

Pour les événements arrivant via l’itinéraire DCCS, l’identité du membre est généralement conservée dans le champ de identityMap XDM standard plutôt que dans une propriété de client personnalisée. identityMap est un mappage indexé par espace de noms : la clé elle-même est le nom de l’espace de noms et la valeur est un tableau d’objets d’identité.

"loyalty_identity": {
  "id": identityMap.Email[0].id
}

• Substitution d’espace de noms : remplacez Email par l’espace de noms que votre organisation utilise pour les membres du programme de fidélité (Loyalty, ECID, CRMID, etc.). Toujours lu à partir de l’espace de noms qui contient l’identité du profil de fidélité principal.

• Utilisez toujours [0]: identityMap.Email est un tableau. Sans l’index, JSONata renvoie une séquence plutôt qu’une valeur unique si plusieurs identités sont présentes et loyalty_identity.id devient une liste. Épinglez-le au premier élément avec [0].

• Évitez les champs client personnalisés pour l’identité : les groupes de champs personnalisés exposent parfois un champ qui ressemble à un e-mail (par exemple, _yourtenant.identification.core.email). Dans les données d’exemple, cela renvoie une valeur qui semble correcte, mais dans les événements de production, elle est souvent vide. La source fiable d’identité est toujours identityMap.

item_set est un tableau d’identifiants de chaîne. Incluez chaque champ sur lequel vos tâches de défis peuvent filtrer :

"item_set": [itemSku, productCategory, departmentCode]

Pour les événements non transactionnels (enregistrement, fin d’enquête, déclencheur personnalisé), un identifiant unique suffit :

"item_set": [eventName]

unit_price doit être un prix à l’unité. Certains schémas source stockent plutôt un total de ligne (prix × quantité). Si votre champ d’origine est un total de ligne, divisez par quantité pour obtenir le prix unitaire :

"unit_price": priceTotal / quantity

Divisez uniquement si votre champ source est un total de ligne. S’il stocke déjà un prix unitaire, mappez-le directement - diviser un prix unitaire par la quantité produira silencieusement une valeur incorrecte.

Si votre événement source n’inclut pas d’identifiant de transaction, vous pouvez en dériver un stable à partir de la date et de l’heure :

"transaction_id": "txn_" & $string($toMillis(timestamp))

Cette opération convertit l’horodatage ISO en millisecondes Epoch et produit une valeur déterministe pour un événement donné. Utilisez la fonction de génération d’identifiants de votre plateforme si elle est disponible.

La bibliothèque complète de fonctions JSONata est disponible. Exemples utiles :

/* 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 }

Scénario : une application mobile envoie un événement d’enregistrement. Il n’y a aucun élément de ligne — l’événement lui-même est l’activité admissible.

Événement entrant :

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

Mappage d’événements :

{
  "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}]}"
}

Transformateur formaté (pour la lisibilité) :

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

Événement de fidélité Output Adobe :

{
  "_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 }]
}

Une tâche de défi sans restriction d’inclusion/exclusion comptabilise cet événement comme une visite de qualification, c’est-à-dire que la ["store-checkin"] d’entrée de item_set unique correspond à toute tâche qui autorise tous les éléments.

Scénario : un système de point de vente envoie une payload de transaction. Chaque élément de ligne possède un SKU et appartient à une catégorie. Les tâches de défi utilisent le SKU et la catégorie pour déterminer ce qui est admissible.

Événement entrant :

{
  "_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"
  }
}

Mappage d’événements :

{
  "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}}"
}

Transformateur formaté:

{
  "_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
  }
}

Événement de fidélité Output Adobe :

{
  "_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 }
  ]
}

Une tâche de type Défi avec include: ["BEVERAGE"] verrait l’élément de ligne de café qualifié (son item_set contient "BEVERAGE") et accumulerait 9,00 $ de dépenses pour cette tâche. La ligne de muffin serait exclue.

Scénario : les événements se propagent dans Adobe Journey Optimizer. L’événement entrant est un événement d’expérience XDM avec un identifiant de schéma connu. La plateforme utilise l’ID de schéma pour la correspondance plutôt qu’une vérification de chemin/valeur.

Corps d’entité XDM entrant (le xdmEntity extrait de l’événement AJO) :

{
  "_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"
}

Mappage d’événements :

{
  "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}}"
}

Transformateur formaté:

{
  "_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
  }
}

Remarque : lorsqu’un événement correspond par identifiant de schéma XDM, le transformateur ne reçoit que la partie xdmEntity de l’événement, et non l’enveloppe externe d’AJO. Tous les chemins de votre expression de transformateur sont relatifs au corps de l’entité XDM.

L’erreur la plus fréquente. L’utilisation d’un seul littéral d’objet avec productListItems.SKU extrait chaque SKU et chaque quantité en séquences groupées au lieu de produire un élément de ligne par produit.

✗Réduit tous les éléments en un seul :

"item_list": [
  {
    "item_set": [ productListItems.SKU ],
    "quantity": productListItems.quantity
  }
]

Avec deux produits, item_set contient les deux SKU et quantity devient un tableau comme [1, 4].

✓Un élément de ligne par produit :

"item_list": [
  productListItems.{
    "item_set": [SKU],
    "quantity": quantity
  }
]

La carte .{ } s’exécute une fois par produit, de sorte que chacune d’elles devient sa propre entrée.

identityMap.Email est un tableau. Sans [0], si un profil possède plusieurs identités dans cet espace de noms, id devient une liste de valeurs au lieu d’une seule chaîne.

✗ identityMap.Email.id

✓ identityMap.Email[0].id

L’ajout d’un champ de catégorie à item_set semble simple, mais si productCategories est lui-même un tableau, le résultat se développe de manière imprévisible.

✗peut produire plus d’entrées que prévu :

"item_set": [SKU, productCategories.categoryID]

Un produit avec trois catégories génère un item_set avec quatre valeurs.

✓indexez le tableau imbriqué pour obtenir exactement une valeur :

"item_set": [SKU, productCategories[0].categoryID]

Un événement avec un item_list vide ou absent est rejeté comme non valide. Pour les événements non transactionnels (archivages, déclencheurs personnalisés), il n’existe aucun élément de ligne naturel. Produisez donc un élément synthétique :

"item_list": [{ "item_set": [eventName], "quantity": 1 }]

La plateforme attend une chaîne ISO 8601. Si votre événement source dure plusieurs millisecondes depuis l’époque Unix, convertissez-le :

"timestamp": $fromMillis(timestamp)

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.