In questa pagina: acquisisci il payload di risposta restituito dalla chiamata API di un’azione personalizzata in modo da poter orchestrare i percorsi, personalizzare i messaggi e gestire gli errori in base ai dati provenienti dal sistema esterno.
Puoi sfruttare le risposte alle chiamate API nelle azioni personalizzate e orchestrare i percorsi in base a tali risposte.
Note importanti custom-action-enhancements-notes
-
Gli array scalari sono supportati nel payload di risposta:
code language-none "dummyScalarArray": [ "val1", "val2" ] -
Gli array eterogenei non sono supportati nel payload di risposta:
code language-none "dummyRandomArray": [ 20, "aafw", false ]
Configurare l’azione personalizzata config-response
-
Crea l’azione personalizzata. Consulta questa pagina.
-
Fai clic all’interno del campo Risposta (risposta di successo).
-
Incolla un esempio del payload restituito dalla chiamata. Verifica che i tipi di campo siano corretti (stringa, numero intero, ecc.). Ecco un esempio di payload di risposta acquisito durante la chiamata. L’endpoint locale invia il numero di punti fedeltà e lo stato di un profilo.
code language-none { "customerID" : "xY12hye", "status":"gold", "points": 1290 }
Ogni volta che viene chiamata l’API, il sistema recupera tutti i campi inclusi nell’esempio di payload.
-
(Facoltativo) Abilita un payload di risposta di errore per acquisire il formato restituito quando la chiamata non riesce, quindi incolla un payload di esempio. A questo scopo, seleziona Definisci un payload di risposta all’errore nella configurazione dell’azione personalizzata. Ulteriori informazioni sulla configurazione dei campi payload in Configurare un’azione personalizzata.
code language-none { "errorResponse" : "customer not found" }Il payload di risposta dell’errore è disponibile solo se lo abiliti nella configurazione dell’azione personalizzata.
-
Aggiungiamo anche il customerID come parametro di query.
-
Fai clic su Salva.
Sfruttare la risposta in un percorso response-in-journey
È sufficiente aggiungere l’azione personalizzata a un percorso. Puoi quindi sfruttare i campi del payload di risposta in condizioni, altre azioni e personalizzazione dei messaggi.
Se hai definito un payload di risposta di errore, questo viene esposto in Attributi contestuali > Journey Orchestration > Azioni > <action name> > errorResponse. Puoi utilizzarlo nel ramo di timeout ed errore per indirizzare la logica di fallback e la gestione degli errori.
Ad esempio, puoi aggiungere una condizione per verificare il numero di punti fedeltà. Quando la persona accede al ristorante, l’endpoint locale invia una chiamata con le informazioni sulla fedeltà del profilo. Puoi inviare un messaggio push se il profilo è un cliente Gold. E se nella chiamata viene rilevato un errore, invia un’azione personalizzata per informare l’amministratore di sistema.
-
Aggiungi l’evento e l’azione personalizzata Fedeltà creata in precedenza.
-
Nell’azione personalizzata Fedeltà, mappa il parametro di query dell’ID cliente con l’ID profilo. Seleziona l’opzione Aggiungi un percorso alternativo in caso di timeout o errore.
-
Nel primo ramo, aggiungi una condizione e utilizza l’editor avanzato per sfruttare i campi di risposta dell’azione, nel nodo Context.
-
Quindi aggiungi il push e personalizza il messaggio utilizzando i campi di risposta. Nel nostro esempio, personalizziamo il contenuto utilizzando il numero di punti fedeltà e lo stato del cliente. I campi di risposta dell’azione sono disponibili in Attributi contestuali > Journey Orchestration > Azioni.
note NOTE Ogni profilo che accede all’azione personalizzata attiva una chiamata. Anche se la risposta è sempre la stessa, il Percorso eseguirà comunque una chiamata per profilo. -
Nel ramo timeout ed errore, aggiungi una condizione e sfrutta il campo jo_status_code integrato. Nel nostro esempio, utilizziamo
Tipo di errore http_400. Vedi questa sezione.code language-none @action{ActionLoyalty.jo_status_code} == "http_400"Se è stato definito un payload di risposta di errore, puoi anche eseguire il targeting dei relativi campi, ad esempio:
code language-none @action{ActionLoyalty.errorResponse.errorResponse} == "customer not found"
-
Aggiungi un’azione personalizzata che verrà inviata alla tua organizzazione.
Registri della modalità di test test-mode-logs
Puoi accedere ai registri di stato relativi alle risposte alle azioni personalizzate tramite la modalità di test. Se hai definito azioni personalizzate con risposte nel tuo percorso, visualizzerai una sezione actionsHistory in tali registri in cui viene visualizzato il payload restituito dall’endpoint esterno (come risposta da tale azione personalizzata). Quando viene definito un payload di risposta di errore, questo viene incluso per le chiamate non riuscite. Questo può essere molto utile in termini di debug.
Stato errore error-status
Il campo jo_status_code è sempre disponibile anche quando non è definito alcun payload di risposta.
Di seguito sono riportati i possibili valori per questo campo:
- codice di stato http: http_
<HTTP API call returned code>, ad esempio http_200 o http_400 - errore di timeout: timeout
- errore di limite: limitato
- errore interno: internalError
Una chiamata di azione viene considerata in errore quando il codice http restituito è maggiore di 2xx o se si verifica un errore. In questi casi, il percorso passa al ramo dedicato relativo al timeout o all’errore.
Se per l’azione personalizzata è stato configurato un payload di risposta di errore, i relativi campi vengono esposti nel nodo errorResponse per le chiamate non riuscite. Se non è configurato alcun payload di risposta di errore, tale nodo non è disponibile.
Sintassi delle espressioni exp-syntax
Di seguito è riportata la sintassi:
#@action{myAction.myField}
Di seguito sono riportati alcuni esempi:
// action response field
@action{<action name>.<path to the field>}
@action{ActionLoyalty.status}
// action response field
@action{<action name>.<path to the field>, defaultValue: <default value expression>}
@action{ActionLoyalty.points, defaultValue: 0}
@action{ActionLoyalty.points, defaultValue: @event{myEvent.newPoints}}
Durante la manipolazione delle raccolte in una risposta di azione personalizzata, è possibile fare affidamento su currentActionField per accedere all’elemento corrente:
count(
@action{MyAction.MyCollection.all(
currentActionField.description == "abc"
)}
)
Utilizzo di risposte alle azioni personalizzate nei canali nativi response-in-channels
I campi del payload di risposta da azioni personalizzate possono essere utilizzati nei canali nativi (e-mail, push, SMS) per la personalizzazione dei messaggi. Ciò include la possibilità di eseguire iterazioni su array e strutture di dati nidificate restituite da API esterne.
Per esempi dettagliati e sintassi per l’iterazione dei dati di risposta delle azioni personalizzate nei messaggi, fare riferimento a Eseguire l’iterazione dei dati contestuali con Handlebars.
Risorse aggiuntive
Per ulteriori informazioni, consulta le seguenti pagine:
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 capture the response payload returned by a custom action’s API call and leverage it to orchestrate journeys, personalize messages, and handle errors.
Intents:
- Configure a custom action to capture success and failure response payloads
- Leverage response payload fields in conditions, other actions, and message personalization
- Handle errors and timeouts using the jo_status_code field and the errorResponse node
- Inspect custom action responses through test mode logs
- Use the expression syntax to reference response fields, including default values and collections
Glossary:
- Response payload: The example payload pasted in the Response (success response) field whose fields are retrieved on each call (product-specific)
- Error response payload: The payload captured when a call fails, enabled by selecting Define a failure response payload, exposed under the errorResponse node (product-specific)
- jo_status_code: A built-in field, always available even when no response payload is defined, that carries the call outcome (product-specific)
- actionsHistory: A section shown in test mode logs that displays the payload returned by the external endpoint (product-specific)
- currentActionField: A reference used to access the current item when manipulating collections in a custom action response (product-specific)
- Test mode: The mode through which you access status logs related to custom action responses (product-specific)
Guardrails:
- Scalar arrays are supported in the response payload, but heterogeneous arrays are not supported.
- Only newly created custom actions include the jo_status_code field out-of-the-box; to use it with an existing custom action you need to update the action, for example by updating the description and saving.
- An action call is considered in error when the returned http code is greater than 2xx or if an error occurs, and the journey flows to the dedicated timeout or error branch.
- If an error response payload is configured, its fields are exposed under the errorResponse node for failed calls; if none is configured, that node is not available.
- Each profile entering the custom action triggers one call, even if the response is always the same.
Terminology:
- Canonical name: API call response in custom actions — Acronym: n/a — variants: custom action response, response payload
- Synonyms: “success response” = “Response field”
- Do not confuse: “Response” (success response payload) ≠ “Error Response” (failure response payload defined via Define a failure response payload)
- jo_status_code values: http_
(for example http_200 or http_400), timedout (timeout error), capped (capping error), internalError (internal error)``
`FAQ:
Q: Which array types are supported in the response payload? — Scalar arrays are supported; heterogeneous arrays are not supported. Q: Why does an existing custom action not expose the jo_status_code field? — Only newly created custom actions include it out-of-the-box; update the existing action, for example by updating the description and saving, to add it. Q: When is an action call considered in error? — When the returned http code is greater than 2xx or an error occurs, after which the journey flows to the dedicated timeout or error branch. Q: Where can the returned payload be inspected? — Through test mode logs, in the actionsHistory section that displays the payload returned by the external endpoint. Q: Can response payload fields be used in native channels? — Yes, response payload fields from custom actions can be used in native channels (email, push, SMS) for message personalization.`
``