Skip to main content
Question

When nesting a!forEach() loops—or invoking array-producing functions like split(), whereContains(), or sub-rules returning lists inside an outer a!forEach()—Appian's SAIL engine often either auto-flattens the structure or truncates each iteration's result to only the first element when passed downstream to typed variables, index(), or UI components.


Why does this happen under the hood in Appian's type system, and how do you architecturally preserve true multi-dimensional structures using a!map() encapsulation?

A
Anonymous
November 12, 2026

Answer

a!forEach() can return a two-dimensional array when each iteration produces more than one value.

Not every Appian function or data type supports multidimensional arrays, though. When a nested array is stored in certain typed contexts, Appian flattens it automatically. These contexts include process variables, node inputs, typed rule inputs and CDT fields. To keep the values grouped, use a!map() inside the outer a!forEach() and store each inner array as a field of its map.


1. Practical scenario

Take a User Management application where each user’s roles are stored as comma-separated text.

Input:

{
"admin,editor,viewer",
"viewer,auditor"
}

Expected result:

Each user’s roles should stay separate, not merged into one array.

{
a!map(
userId: 1,
roles: {"admin", "editor", "viewer"}
),
a!map(
userId: 2,
roles: {"viewer", "auditor"}
)
}


2. How nested arrays behave

Take this expression:

a!localVariables(
local!rawRows: {
"admin,editor,viewer",
"viewer,auditor"
},

a!forEach(
items: local!rawRows,
expression: split(fv!item, ",")
)
)

How it works:

  1. The outer a!forEach() goes through each input string.
  2. split() turns each string into an array of roles.
  3. So each iteration returns more than one value.

Conceptually, the result looks like this:

{
{"admin", "editor", "viewer"},
{"viewer", "auditor"}
}

A local variable can hold this two-dimensional result as it is.

If you save it into a typed context that only supports a single-level array, Appian flattens it automatically:

{
"admin",
"editor",
"viewer",
"viewer",
"auditor"
}

Now there’s no way to tell which roles belong to which user.

Whether flattening happens depends on the context. Nested a!forEach() doesn’t automatically cut every inner array down to its first element. You might get an unexpected single value when data goes to an operation or field that expects a scalar, but you’ll need to check how the specific function and data type behave.


3. Solution: preserve nested arrays with a!map()

Don’t return the array directly from each iteration. Wrap it in a!map().

Appian expression:

a!localVariables(
local!rawRows: {
"admin,editor,viewer",
"viewer,auditor"
},

local!structured: a!forEach(
items: local!rawRows,
expression: a!map(
userId: fv!index,
roles: a!forEach(
items: split(fv!item, ","),
expression: trim(fv!item)
)
)
),

local!structured
)

Output:

{
a!map(
userId: 1,
roles: {"admin", "editor", "viewer"}
),
a!map(
userId: 2,
roles: {"viewer", "auditor"}
)
}


4. How the solution works

Step 1: Iterate through each user

The outer a!forEach() goes through each string in local!rawRows.

Step 2: Split the roles

split() turns each comma-separated string into an array.

For example, split("admin,editor,viewer", ",") returns {"admin", "editor", "viewer"}.

Step 3: Keep the array in a!map()

The roles array goes into the roles field of a map. It isn’t returned on its own.

Each outer iteration now returns one map with the user ID and that user’s roles.

Step 4: Access individual values

Since each inner array sits inside a map, you can pull one user’s roles and the grouping stays intact.


5. Accessing values in the nested structure

All roles for the first user:

index(
local!structured[1],
"roles",
{}
)

Output:

{"admin", "editor", "viewer"}


The second role of the first user:

index(
local!structured[1].roles,
2,
null
)

Output:

"editor"


All roles for the second user:

index(
local!structured[2],
"roles",
{}
)

Output:

{"viewer", "auditor"}


6. When to use a!flatten() instead

If you actually want all the inner arrays combined into one list, use a!flatten().

a!flatten(
a!forEach(
items: {
"admin,editor,viewer",
"viewer,auditor"
},
expression: split(fv!item, ",")
)
)

Output:

{
"admin",
"editor",
"viewer",
"viewer",
"auditor"
}

Use a!flatten() when you don’t need the grouping, for example when you want to process every role as one collection.

Use a!map() when each group of values has to stay tied to its parent record.


7. Practical use cases

This approach helps with:

  1. Users and roles, where each user has several roles.
  2. Orders and order items, where each order has several products.
  3. Loan applications and documents, where each application has several uploaded documents.
  4. Departments and employees, where each department has several employees.
  5. Nested expression rules, where each rule call returns several values that need to stay grouped.

For a reusable, typed structure, a CDT with an array field can also represent the parent-child relationship, as long as the destination data type is designed to hold it.


Key takeaways

  1. a!forEach() can return two-dimensional arrays.
  2. Local variables keep nested arrays, but some typed storage contexts flatten them automatically.
  3. a!map() lets you store each inner array as a field on a parent object.
  4. a!flatten() deliberately merges nested arrays into a single-level list.
  5. When parent records need to keep their child arrays, use maps or a CDT designed for that structure.


Interview tip: With nested arrays in Appian, first work out whether the requirement calls for a flat list or a structured collection. If parent-child relationships have to be kept, use a list of maps or a suitable CDT. Raw nested arrays aren’t reliable for that.

Try it yourself

Change the inputs or the expression and run it to see what it returns.

Examples:
ri!rawRows=

Independent evaluator: it approximates the Appian expression language and may differ from a real Appian environment. Verify anything that matters. Terms

SeniorExpressions