DocumentationJourney OptimizerJourney Optimizer Guide

Use API call responses in custom actions custom-action-enhancements

Last update: Fri Jan 26 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Developer
  • Admin

You can leverage API call responses in custom actions and orchestrate your journeys based on these responses.

Important notes custom-action-enhancements-notes

  • Scalar arrays are supported in response payload:

    code language-none 
    "dummyScalarArray": [
"val1",
"val2"
]

  • Heterogeneous arrays are not supported in response payload:

    code language-none 
    "dummyRandomArray": [
20,
"aafw",
false
]

Configure the custom action config-response

  1. Create the custom action. Refer to this page.

  2. Click inside the Response field.

    {width="80%"}

  3. Paste an example of the payload returned by the call. Verify that the field types are correct (string, integer, etc.). Here is an example of response payload captured during the call. Our local endpoint sends the number of loyalty points and the status of a profile.

    code language-none 
    {
"customerID" : "xY12hye",
"status":"gold",
"points": 1290 }

    {width="80%"}

    Each time the API is called, the system will retrieve all the fields included in the payload example.

  4. Let’s also add the customerID as a query parameter.

    {width="80%"}

  5. Click Save.

Leverage the response in a journey response-in-journey

Simply add the custom action to a journey. You can then leverage the response payload fields in conditions, other actions and message personalization.

For example, you can add a condition to check the number of loyalty points. When the person enters the restaurant, your local endpoint sends a call with the profile’s loyalty information. You can send a push if the profile is a gold customer. And if an error is detected in the call, send a custom action to notify your system administrator.

  1. Add your event and the Loyalty custom action created earlier.

  2. In the Loyalty custom action, map the customer ID query parameter with the profile ID. Check the option Add an alternative path in case of a timeout or error.

  3. In the first branch, add a condition and use the advanced editor to leverage the action response fields, under the Context node.

  4. Then add your push, and personalize your message using the response fields. In our example, we personalize the content using the number of loyalty points and the customer status. The action response fields are available under Contextual attributes > Journey Orchestration > Actions.

    note note
    NOTE
    Each profile entering the custom action will trigger a call. Even if the response is always the same, Journey will still perform one call per profile.

  5. In the timeout and error branch, add a condition and leverage the built-in jo_status_code field. In our example, we’re using the
    http_400 error type. See this section.

    code language-none 
    @action{ActionLoyalty.jo_status_code} == "http_400"

  6. Add a custom action that will be sent to your organization.

Test mode logs test-mode-logs

You can access, through test mode, status logs related to custom action responses. If you have defined custom actions with responses in your journey, you will see an actionsHistory section on those logs displaying the payload returned by the external endpoint (as a response from that custom action). This can be very useful in terms of debugging.

Error status error-status

The jo_status_code field is always available even when no response payload is defined.

Here are the possible values for this field:

  • http status code: http_<HTTP API call returned code>, for instance http_200 or http_400
  • timeout error: timedout
  • capping error: capped
  • internal error: internalError

An action call is considered in error when the returned http code is greater than 2xx or if an error occurs. The journey flows to the dedicated timeout or error branch in such cases.

WARNING
Only newly created custom actions include the jo_status_code field out-of-the-box. If you want to use it with an existing custom action, you need to update the action. For example, you can update the description and save.

Expression syntax exp-syntax

Here is the syntax:

#@action{myAction.myField}

Here are a few examples:

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

While manipulating collections in a custom action response, you can rely on currentActionField to access the current item:

count(
@action{MyAction.MyCollection.all(
currentActionField.description == "abc"
)}
)

Additional resources

For more information, refer to these pages:

recommendation-more-help
b22c9c5d-9208-48f4-b874-1cefb8df4d76