Collections and Source Data

A collection is a list of related records — the line items on an order, the comments on a line item, the inventories at each warehouse. This article covers how to access individual items in a collection, how to navigate nested data, and how to reach raw integration data when you need a field DropStream hasn’t mapped.

Collections you can access

Three ways to work with a collection:

• Iterate with for ... end — see Loops.
• Quantify with any|all|none — see Quantifiers.
• Aggregate with accumulate — see Accumulators.

This article covers a fourth way: directly accessing a specific item by index or by key.

Indexed access (by position)

Use brackets to grab an item by position, starting at 0:

order_line.comments[0].text          # the first comment's text
order_line.options[1].name           # the second option's name
order.order_lines[0].sku             # the first line item's SKU

This is most useful when:

• You know there’s exactly one item (e.g., a single comment).
• You specifically care about the first or last by position.
• The collection is documented as ordered.

If the index might be out of range — e.g., comments[0] when there are no comments — see Null Handling for safety patterns.

Map access (by key)

Some collections are addressable by key — the field name itself acts as a lookup. The convention is {collection}_map_from_{key}:

order.custom_map_from_key.my_key
order_line.options_map_from_name.color

This grabs the entry whose key (here my_key or color) matches. Map access is more readable than indexed access when the items have meaningful names.

Dynamic key access

If the key you want is computed at runtime, use bracket syntax with an expression:

order.custom["field_" & order.id]
order.custom["prefix_" & $variable]

Inside the brackets is any text expression. Useful for parameterized lookups — e.g., looking up a custom field whose name depends on the order itself.

Nested access

Collections nest naturally. Drill in with chained dots:

order.shipping_address.postal_code
order.billing_address.country
order_line.options[0].metadata.color

Address-like sub-objects (shipping_address, billing_address) are themselves models with their own fields.

Source data — the raw integration payload

Sometimes the integration delivers a field DropStream’s domain model doesn’t expose. The fix isn’t to add a new mapping — it’s to reach into source_data, which is the raw JSON or XML the integration received.

order.source_data.custom.field
order.source_data.nested.path.to.value
purchase_order.source_data.extra_data

Path structure depends on the integration. Sales channels expose data differently from EDI partners, which expose data differently from custom uploads. Look at a real record in DropStream’s UI and follow the path you see in the source view.

Heads up: source_data fields are typed as text by default. To use one as a number or date, cast it: order.source_data.custom.priority as number.

Common patterns

Get the first line’s first comment:

set order.notes to order_lines[0].comments[0].text

Look up a custom value by name:

set order.custom.tier to order.custom_map_from_key.priority_tier

Read a custom field that came in as text:

when order.source_data.custom.priority as number > 5 then
  set order.custom.tag to "priority"
end

Drill into a nested object on a line item:

for order_lines in order
  when order_line.options[0].name is "Color" then
    set order_line.custom.color_note to "Color: " & order_line.options[0].value
  end
end

What’s not supported

• Slicing or take(N) — you can’t write order_lines.take(5) or order_lines[0..4]. Iteration always covers the whole collection.
• Conditional access (e.g., “find the line where SKU = X”) — there’s no built-in find or where. Use a for loop with a when filter, or a $variable flag pattern (see Loops).
• Modifying a collection’s structure — you can’t remove or reorder items mid-rule. To remove an item, use the reject order_line action inside a loop. To add an item, use the add action.