Use case: pass collections dynamically using custom actions passing-collection
Custom actions in 51黑料不打烊 Journey Optimizer enable you to pass collections dynamically as parameters during runtime. Collections group related data, such as lists of devices or sets of product details, which can then be processed dynamically within journeys. 51黑料不打烊 Journey Optimizer supports two types of collections:
-
Simple collections: Arrays containing simple data types, such as strings or numbers. For example, a list of device types might look like this:
code language-yaml { "deviceTypes": [ "android", "ios" ] } -
Object collections: Arrays of JSON objects where each object contains multiple key-value pairs. For example, a list of products might look like this:
code language-yaml { "products": [ { "id": "productA", "name": "A", "price": 20.1 }, { "id": "productB", "name": "B", "price": 10.0 }, { "id": "productC", "name": "C", "price": 5.99 } ] }
Limitations limitations
Collections provide significant flexibility, but certain constraints apply when designing schemas and journeys:
-
Nested arrays of objects within an object array are not supported. For example, the following structure, which includes 鈥渓ocations鈥 as an array within an object, is invalid:
code language-yaml { "products": [ { "id": "productA", "name": "A", "price": 20, "locations": [ { "name": "Paris" }, { "name": "London" } ] } ] } -
Testing collections in test mode requires code view mode. Code view mode is not supported for business events. Additionally, collections in test mode are limited to a single element.
Ensuring data structures adhere to supported configurations guarantees proper functionality during implementation.
General procedure general-procedure
To dynamically pass collections, refer to the following JSON payload example. This example represents an array of objects, with each object including various fields such as simple collections:
{
"ctxt": {
"products": [
{
"id": "productA",
"name": "A",
"price": 20.1,
"color": "blue",
"locations": [
"Paris",
"London"
]
},
{
"id": "productB",
"name": "B",
"price": 10.99
}
]
}
}
In this example, 鈥減roducts鈥 is an array containing two objects. Each object represents a product with fields such as 鈥渋d鈥, 鈥渘ame鈥, and 鈥減rice鈥. At least one object must exist for the collection to be valid.
-
Create a custom action. For more details, see About custom action configuration.
-
In the Action parameters section, paste the JSON example. The displayed structure is static鈥攚hen the payload is pasted, all fields are defined as constants.
-
Adjust the field types as needed. Supported field types for collections include:
listString,listInteger,listDecimal,listBoolean,listDateTime,listDateTimeOnly,listDateOnly, andlistObject.The system infers the field type automatically based on the payload example. For instance, an array of numbers is interpreted as either
listDecimalorlistInteger, depending on the data. -
To pass objects dynamically, set them as variables. In this example, 鈥減roducts鈥 is set as a variable. The system automatically sets all object fields within the first object of the payload as variables.
-
Define the label for each field that appears in the journey canvas. Labels help identify and work with fields during journey design.
-
Create a journey and add the custom action created earlier. For more details, see Using custom actions.
-
In the Action parameters section, define the array parameter (鈥減roducts鈥 in this example) using the advanced expression editor. This step maps dynamic data to the parameter during runtime.
-
For each object field, type the corresponding field name from the source XDM schema. If the field names match exactly, this step is unnecessary. In the example, only 鈥減roduct id鈥 and 鈥渃olor鈥 require manual mapping.
The advanced expression editor allows data manipulation for array fields. For example, filter products or find intersections using functions such as filter and intersect. An example is shown below:
Particular cases examples
Certain edge cases, such as heterogeneous types and arrays of arrays, require special handling. These arrays use the listAny type, which allows individual item mapping but does not support changing the array to a variable.
Example of a heterogeneous type:
{
"data_mixed-types": [
"test",
"test2",
null,
0
]
}
Example of an array of arrays:
{
"data_multiple-arrays": [
[
"test",
"test1",
"test2"
]
]
}
These examples highlight edge cases where collections have limited flexibility. Understanding their structure ensures effective handling within these constraints.
Related Topics