事件轉換器指南 event-transformer-guide

將目標格式的每個最上層欄位對應至來源事件中的對應路徑：

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

如果符合此定義的所有事件都代表相同的邏輯活動，請對event_name進行硬式編碼：

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

event_name用於內部量度和報告。 它不用作任務篩選 — 任務資格由item_set內容決定，而不是事件名稱。

對於透過DCCS路由到達的事件，成員的身分通常會在標準XDM identityMap欄位中攜帶，而不是在自訂租使用者屬性中攜帶。 identityMap是由名稱空間輸入的對應 — 索引鍵本身就是名稱空間名稱，而值是身分識別物件的陣列。

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

• 名稱空間替代：​以貴組織用於忠誠會員的任何名稱空間取代Email — Loyalty、ECID、CRMID等。永遠從儲存主要忠誠度設定檔身分的名稱空間讀取。

• 一律使用[0]： identityMap.Email為陣列。 如果沒有索引，如果存在多個身分，則JSONata會傳回序列而不是單一值，並且loyalty_identity.id會成為清單。 將其釘選到第一個具有[0]的專案。

• 避免身分識別的自訂租使用者欄位：​自訂欄位群組有時會公開電子郵件形式的欄位（例如_yourtenant.identification.core.email）。 在範例資料中，這會傳回值且看起來是正確的，但在生產事件中，它通常是空的。 可靠的身分來源一律為identityMap。

item_set是字串識別碼的陣列。 包含您的挑戰任務可能篩選的每個欄位：

"item_set": [itemSku, productCategory, departmentCode]

對於非交易事件（簽入、調查完成、自訂觸發器），單一識別碼就足夠了：

"item_set": [eventName]

unit_price應為單價。 有些來源結構描述會儲存明細總計（價格×數量）。 如果您的來源欄位是明細行總計，請除以數量以取得單價：

"unit_price": priceTotal / quantity

僅當來源欄位為行總計時除。 如果已經儲存單價，請直接對應 — 將單價除以數量將會自動產生錯誤值。

若您的來源事件不包含交易識別碼，則可從時間戳記衍生出穩定識別碼：

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

這會將ISO時間戳記轉換為epoch毫秒，並為指定事件產生決定性的值。 使用您平台自己的ID產生函式（如有）。

提供完整的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 }

案例：​行動應用程式傳送簽到事件。 沒有條列專案 — 事件本身是符合資格的活動。

傳入事件：

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

事件對應：

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

格式化的轉換器（可讀性）：

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

輸出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 }]
}

沒有包含/排除限制的挑戰任務會將此事件計為合格造訪 — 單一item_set專案["store-checkin"]符合允許所有專案的任何任務。

案例：​銷售點系統傳送交易裝載。 每個明細專案都有一個SKU且屬於類別。 挑戰任務使用SKU和類別來判斷符合條件。

傳入事件：

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

事件對應：

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

格式化的轉換器：

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

輸出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 }
  ]
}

具有include: ["BEVERAGE"]的挑戰任務會看到咖啡條列專案符合資格（其item_set包含"BEVERAGE"）並累積$9.00的支出用於該任務。 將會排除鬆餅條列專案。

案例：​事件流經Adobe Journey Optimizer。 傳入事件是具有已知結構描述ID的XDM體驗事件。 平台使用結構描述ID進行比對，而非路徑/值檢查。

傳入的XDM實體內文 （從AJO事件擷取的xdmEntity）：

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

事件對應：

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

格式化的轉換器：

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

注意：​當事件符合XDM結構描述ID時，轉換器只會接收事件的xdmEntity部分，而不是外部AJO信封。 您的轉換器運算式中的所有路徑都是相對於XDM實體本文。

最常見的錯誤。 將單一物件常值與productListItems.SKU搭配使用，會將每個SKU和每個數量拉入集中順序，而非針對每項產品產生一個條列專案。

✗將所有專案摺疊為一個：

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

使用兩個產品時，item_set會同時儲存兩個SKU，quantity會變成類似[1, 4]的陣列。

✓每個產品一個條列專案：

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

每個產品會執行一次.{ }對應，因此每個產品都會成為自己的專案。

identityMap.Email是一個陣列。 若沒有[0]，如果設定檔在該名稱空間中有多個身分，id會變成值清單，而非單一字串。

✗ identityMap.Email.id

✓ identityMap.Email[0].id

將類別欄位新增到item_set看起來很簡單，但如果productCategories本身是陣列，則結果會以無法預測的方式展開。

✗可能會產生比預期更多的專案：

"item_set": [SKU, productCategories.categoryID]

具有三個類別的產品會產生具有四個值的item_set。

✓為巢狀陣列建立索引，以取得正好一個值：

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

具有空白或不存在item_list的事件會因無效而被拒絕。 對於非異動事件（簽入、自訂觸發器），沒有自然的條列專案，因此產生合成的專案：

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

平台必須有ISO 8601字串。 如果您的來源事件包含紀元以來的毫秒數，請將其轉換：

"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.