DocumentazioneJourney OptimizerGuida di Journey Optimizer

Riferimenti campo field-references

Ultimo aggiornamento: 5 settembre 2026
  • Si applica a:
  • Journey Orchestration

Creato per:

  • Experienced
  • Sviluppatore

Un riferimento di campo può essere allegato a un evento o a un gruppo di campi. L’unica informazione significativa è il nome del campo e il relativo percorso.

Se in un campo si utilizzano caratteri speciali, è necessario utilizzare virgolette doppie o semplici. Di seguito sono riportati i casi in cui sono necessarie virgolette:

  • il campo inizia con caratteri numerici
  • il campo inizia con il carattere “-”
  • il campo contiene elementi diversi da: a-z, A-Z, 0-9, ,-_

Ad esempio, se il campo è 3h: #{OpenWeather.weatherData.rain.‘3h’} > 0

// event field
@event{<event name>.<XDM path to the field>}
@event{LobbyBeacon.endUserIDs._experience.emailid.id}

// field group
#{<data source name>.<field group name>.<path to the field>}
#{ExperiencePlatform.ProfileFieldGroup.profile.personalEmail.address}

Nell’espressione, ai campi evento viene fatto riferimento con “@” e ai campi dell’origine dati viene fatto riferimento con “#”.

Un colore di sintassi viene utilizzato per distinguere visivamente i campi degli eventi (verde) dai gruppi di campi (blu).

Valori predefiniti per riferimenti campo default-value

Un valore predefinito può essere associato a un nome di campo. La sintassi è la seguente:

// event field
@event{<event name>.<XDM path to the field>, defaultValue: <default value expression>}
@event{LobbyBeacon.endUserIDs._experience.emailid.id, defaultValue: "example@adobe.com"}
// field group
#{<data source name>.<field group name>.<path to the field>, defaultValue: <default value expression>}
#{ExperiencePlatform.ProfileFieldGroup.profile.personalEmail.address, defaultValue: "example@adobe.com"}
NOTE
Il tipo del campo e il valore predefinito devono essere uguali. @event{LobbyBeacon.endUserIDs._experience.emailid.id, defaultValue : 2}, ad esempio, non è valido perché il valore predefinito è un numero intero, mentre il valore previsto deve essere una stringa.

Esempi:

// for an event 'OrderEvent' having the following payload:
{
    "orderId": "12345"
}

expression example:
- @event{OrderEvent.orderId}                                    -> "12345"
- @event{OrderEvent.productId, defaultValue : "not specified" } -> "not specified" // default value, productId is not a field present in the payload
- @event{OrderEvent.productId}                                  -> null


// for an entity 'Profile' on datasource 'ACP' having fields person/lastName, with fetched data such as:
{
    "person": {
        "lastName":"Snow"
    },
    "emails": [
        { "email":"john.snow@winterfell.westeros" },
        { "email":"snow@thewall.westeros" }
    ]
}

expression examples:
- #{ACP.Profile.person.lastName}                 -> "Snow"
- #{ACP.Profile.emails.at(1).email}              -> "snow@thewall.westeros"
- #{ACP.Profile.person.age, defaultValue : -1}   -> -1 // default value, age is not a field present in the payload
- #{ACP.Profile.person.age}                      -> null

È possibile aggiungere qualsiasi tipo di espressione come valore predefinito. L’unico vincolo è che l’espressione deve restituire il tipo di dati previsto. Quando si utilizza una funzione, è necessario incapsularla con ().

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.any.time, defaultValue : (now())}
== date("2022-02-10T00:00:00Z")

Riferimento a un campo all’interno di raccolte

Si fa riferimento agli elementi definiti nelle raccolte utilizzando le funzioni specifiche all, first e last. Per ulteriori informazioni, consulta questa pagina.

Esempio:

@event{LobbyBeacon._experience.campaign.message.profile.pushNotificationTokens.all()

Riferimento a un campo definito in una mappa

Funzione entry

Per recuperare un elemento in una mappa, utilizziamo la funzione di immissione con una determinata chiave. Ad esempio, viene utilizzato quando si definisce la chiave di un evento, in base allo spazio dei nomi selezionato. Per ulteriori informazioni, vedere questa pagina.

@event{MyEvent.identityMap.entry('Email').first().id}

In questa espressione, si ottiene la voce per la chiave “E-mail” del campo “IdentityMap” di un evento. La voce “E-mail” è una raccolta, dalla quale prendiamo il “id” nel primo elemento utilizzando “first()”. Per ulteriori informazioni, vedere questa pagina.

Funzione firstEntryKey

Per recuperare la prima chiave di ingresso di una mappa, utilizzare la funzione firstEntryKey.

Questo esempio mostra come recuperare il primo indirizzo e-mail degli abbonati di un elenco specifico:

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.email.subscriptions.entry('daily-email').subscribers.firstEntryKey()}

In questo esempio, l’elenco iscrizioni è denominato daily-email. Gli indirizzi di posta elettronica sono definiti come chiavi nella mappa subscribers, collegata alla mappa dell’elenco iscrizioni.

Funzione keys

Per recuperare in tutte le chiavi di una mappa, utilizzare la funzione keys.

Questo esempio mostra come recuperare, per un profilo specifico, tutti gli indirizzi e-mail associati agli abbonati di un elenco specifico:

#{ExperiencePlatform.Subscriptions.profile.consents.marketing.email.subscriptions.entry('daily-mail').subscribers.keys()

Valori dei parametri di un’origine dati (valori dinamici dell’origine dati)

Se selezioni un campo da un’origine dati esterna che richiede la chiamata di un parametro, a destra viene visualizzata una nuova scheda che consente di specificare questo parametro. Consulta questa pagina.

Per casi d’uso più complessi, se desideri includere i parametri dell’origine dati nell’espressione principale, puoi definirne i valori utilizzando la parola chiave params. Un parametro può essere qualsiasi espressione valida anche da un’altra origine dati che include anche un altro parametro.

NOTE
Quando definite i valori dei parametri nell'espressione, la linguetta a destra scompare.

Utilizza la seguente sintassi:

#{<datasource>.<field group>.fieldName, params: {<params-1-name>: <params-1-value>, <params-2-name>: <params-2-value>}}
  • <params-1-name>: nome esatto del primo parametro dell’origine dati.
  • <params-1-value>: valore del primo parametro. Può essere qualsiasi espressione valida.

Esempio:

#{Weather.main.temperature, params: {localisation: @event{Profile.address.localisation}}}
#{Weather.main.temperature, params: {localisation: #{GPSLocalisation.main.coordinates, params: {city: @event{Profile.address.city}}}}}
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 reference event fields and data source field groups in journey expressions, including default value syntax, map access functions (entry, firstEntryKey, keys), and inline data source parameter passing with the params keyword.

Intents:

  • Reference an event field in an expression using the @event{eventName.fieldPath} syntax
  • Reference a data source field group using the #{dataSourceName.fieldGroupName.fieldPath} syntax
  • Assign a fallback default value to a field reference so expressions do not return null
  • Retrieve a specific entry from an identity map or subscription map using the entry() function
  • Retrieve all keys from a map field using the keys() function
  • Pass parameter values to an external data source inline using the params keyword

Glossary:

  • Field reference: An expression syntax that points to a named field within an event payload or data source field group (product-specific)
  • defaultValue: An optional fallback expression appended to a field reference that is returned when the field is absent or null (product-specific)
  • entry(key): A map function that retrieves the collection entry associated with the given key (product-specific)
  • firstEntryKey(): A map function that returns the first key of a map field (product-specific)
  • keys(): A map function that returns all keys of a map field (product-specific)
  • params keyword: Inline syntax for specifying parameter values for external data source fields within the main expression (product-specific)

Guardrails:

  • Field names containing special characters (starting with a digit, containing -, or characters outside a-z A-Z 0-9 _) must be wrapped in single or double quotes
  • The default value expression must return the same data type as the field — mismatched types are invalid
  • When the params keyword is used to define parameter values inline, the separate parameter tab on the right of the editor disappears
  • Functions used as default values must be encapsulated in parentheses

Terminology:

  • Canonical name: Field References — Acronym: none — variants: field path, field expression
  • Synonyms: @event{...} = “event field reference”; #{...} = “data source field reference”
  • Do not confuse: event fields (prefixed @) ≠ data source fields (prefixed #)

FAQ:

  • Q: How do I reference a field whose name starts with a number? — Wrap the field name in single or double quotes, e.g. #{OpenWeather.weatherData.rain.'3h'}.
  • Q: What happens when a referenced field is missing from the event payload and no default value is set? — The expression returns null.
  • Q: How do I set a dynamic default value using a function? — Wrap the function call in parentheses, e.g. defaultValue: (now()).
  • Q: How do I retrieve the email address stored as the first key in a subscriber map? — Use the firstEntryKey() function on the subscribers map field.
  • Q: How do I pass a parameter to an external data source without using the right-side tab? — Use the params keyword inline: #{DataSource.group.field, params: {paramName: value}}.
recommendation-more-help
journey-optimizer-help