11.2 List Processing & Looping with a!forEach

List Processing & Looping with a!forEach

Quick Summary: In Appian, collections and arrays are processed functionally rather than through imperative for or while loops. The foundational looping construct is a!forEach(), which evaluates a declarative expression for every element in a list. Within a!forEach(), the platform exposes specialized Function Variables (fv!) that provide rich contextual metadata such as the current element, 1-based index, and boundary indicators. Mastering a!forEach(), safe indexing via index(), and avoiding iterative query anti-patterns are critical competencies for the Associate Developer exam.

---

Working with Collections in Appian Expressions

In Appian, a collection is an ordered group of items of the same or compatible data types. Collections are denoted in expression syntax using curly braces {} (e.g., {10, 20, 30} or {"Active", "Pending", "Closed"}).

1. 1-Based Indexing Standard

Unlike traditional programming languages (such as Java, Python, or JavaScript) that use zero-based indexing, Appian indexing is strictly 1-based:

• The first item in an array resides at index 1.
• The final item in an array of N items resides at index N.
• Attempting to access index 0 does not return the first item; it is an out-of-bounds index that returns null or raises an evaluation error.

2. Implicit List Operations

Appian functions frequently exhibit supported list evaluation (sometimes called list vectorization). When a scalar function or arithmetic operator is applied to an array, Appian automatically evaluates the operation across every member of the array without requiring an explicit loop:

/* Implicit Array Multiplication */
{10, 20, 30} * 2
/* Evaluates directly to: {20, 40, 60} */

/* Explicit per-item string formatting */
a!forEach(items: {101, 102, 103}, expression: "ID-" & fv!item)
/* Evaluates directly to: {"ID-101", "ID-102", "ID-103"} */

While implicit evaluation is fast and clean for basic scalar operations, complex transformations—such as mapping objects, inspecting indices, executing conditional logic per item, or calculating running summaries—require the explicit control of a!forEach().

---

The a!forEach() Functional Construct

a!forEach() is the standard, declarative iteration engine in modern Appian applications. It accepts two primary parameters:

a!forEach(
  items: <AnyArray>,
  expression: <ExpressionToEvaluate>
)

+-----------------------------------------------------------------------+
|                   a!forEach() EXECUTION ARCHITECTURE                  |
|                                                                       |
|   items: {"Gold", "Silver", "Bronze"}                                 |
|                                                                       |
|   Iteration 1:                                                        |
|     fv!item = "Gold"    fv!index = 1   fv!isFirst = true  fv!isLast = false|
|     Evaluates expression ---> "Rank 1: Gold"                          |
|                                                                       |
|   Iteration 2:                                                        |
|     fv!item = "Silver"  fv!index = 2   fv!isFirst = false fv!isLast = false|
|     Evaluates expression ---> "Rank 2: Silver"                        |
|                                                                       |
|   Iteration 3:                                                        |
|     fv!item = "Bronze"  fv!index = 3   fv!isFirst = false fv!isLast = true |
|     Evaluates expression ---> "Rank 3: Bronze"                        |
|                                                                       |
|   Output: {"Rank 1: Gold", "Rank 2: Silver", "Rank 3: Bronze"}        |
+-----------------------------------------------------------------------+

Graceful Handling of Empty and Null Inputs

A major architectural benefit of a!forEach() is its built-in null safety:

• If items is passed null, a!forEach() does not throw a NullPointerException. It returns {} (an empty list).
• If items is an empty collection {}, it returns {} immediately without evaluating the expression parameter.
• If items is a single scalar value (e.g., "SingleValue"), Appian automatically coerces it into a one-element array { "SingleValue" } and executes the expression exactly once.

---

Iteration Context Variables (fv!) in a!forEach()

When evaluating the expression parameter for each element, Useful Appian context variables include the following five Function Variables (fv!) into the local scope of the loop:

Practical Application of fv!isLast and fv!index

A common UI and formatting pattern is constructing formatted strings without trailing delimiters:

/* Formatting a comma-separated list of names */
fn!concat(
  a!forEach(
    items: ri!departmentNames,
    expression: fv!item & if(fv!isLast, "", ", ")
  )
)

If ri!departmentNames contains {"Finance", "Legal", "Operations"}, fv!isLast evaluates to false for Finance and Legal (appending , ), and true for Operations (appending nothing), producing "Finance, Legal, Operations" without messy trailing commas.

---

Core List Manipulation Functions

In addition to a!forEach(), Appian provides specialized utility functions in the fn! namespace for querying, indexing, and filtering collections.

+-----------------------------------------------------------------------+
|                   CORE LIST MANIPULATION UTILITIES                    |
|                                                                       |
|  index()          Safe property / array indexing with fallback default|
|  property()       Extracts a named property across single or array data|
|  wherecontains()  Finds integer indices matching a target value       |
|  reject()         Filters out items matching a predicate function     |
|  a!flatten()      Collapses multi-dimensional lists into a single list|
+-----------------------------------------------------------------------+

1. Safe Extraction: index() vs. Direct Bracket Notation

Developers can extract values from collections or complex objects using direct dot/bracket syntax or the index() function. In production applications, index() is useful when a fallback for a missing key or position is required:

/* Unsafe Bracket Syntax */
ri!customerList[ri!selectedIdx].address.city
/* Fails with a fatal error if customerList is null, selectedIdx is out of bounds, or address is null */

/* Safe index() Syntax */
a!defaultValue(
  index(index(index(ri!customerList, ri!selectedIdx, a!map()), "address", a!map()), "city", null),
  "Unknown City"
)

• Signature: index(data, index/property, default).
• If data is null, or if the specified index does not exist, index() gracefully returns the supplied default value instead of crashing the interface or process model.

2. Array Property Extraction: property()

The property() function extracts a specific field across a complex object or collection of complex objects:

/* Extracts all email addresses into a Text array */
property(ri!employees, "emailAddress", {})

This operation "projects" a single attribute from an array of CDTs or dictionaries into a flat array of primitive values without requiring a manual a!forEach() loop.

3. Finding Element Indices: wherecontains()

wherecontains() searches an array for a target value and returns a list of integer indices where matches occur:

/* Finding all inactive users in a status list */
a!localVariables(
  local!statuses: {"ACTIVE", "INACTIVE", "ACTIVE", "INACTIVE", "PENDING"},
  local!matchIndices: fn!wherecontains("INACTIVE", local!statuses),
  local!matchIndices
  /* Returns: {2, 4} */
)

Developers frequently combine wherecontains() with index() to filter parallel arrays or select matching records.

4. Collection Filtering: reject()

reject() removes elements from a collection that satisfy a designated condition or predicate function:

/* Removing all null entries from an array */
fn!reject(fn!isnull, {10, null, 25, null, 50})
/* Returns: {10, 25, 50} */

Notice that the first parameter is fn!isnull passed as a function pointer (requiring the fn! namespace prefix), which reject() invokes against each item.

---

Performance Considerations & Anti-Patterns

Because a!forEach evaluates an expression for each item, and query-containing iterations may execute in parallel, improper design can introduce severe performance degradation:

+-----------------------------------------------------------------------+
|                   THE "QUERY IN A LOOP" ANTI-PATTERN                  |
|                                                                       |
|   CRITICAL ANTI-PATTERN:                                              |
|   a!forEach(                                                          |
|     items: ri!orderIds,              /* 200 orders */                 |
|     expression: a!queryRecordType(   /* 200 separate DB queries! */   |
|       ... recordType!Order ...                                        |
|     )                                                                 |
|   )  ===> 200 network round-trips -> Engine & DB exhaustion!          |
|                                                                       |
|   RECOMMENDED BATCH PATTERN:                                          |
|   1. Query once: Fetch all 200 orders in a single batched query       |
|      using an "in" filter operator.                                   |
|   2. Process once: Transform or display the resulting list in memory. |
+-----------------------------------------------------------------------+

1. The "Query in a Loop" Anti-Pattern (N+1 Queries)

A significant performance anti-pattern is calling a!queryEntity() or a!queryRecordType() inside the expression parameter of a!forEach(). If the input collection contains 100 items, Appian executes 100 independent round-trip database queries. This exhausts connection pools, spikes CPU utilization, and can degrade interface responsiveness; measure the actual workload.

Architectural Rule: Always query in bulk outside the loop using a!queryRecordType() or a!queryEntity() with an "in" filter operator, then correlate records in memory using Record Relationships or wherecontains().

2. Nested a!forEach() Loops

Nesting an a!forEach() inside another a!forEach() produces quadratic computational complexity (O(N * M)). When processing outer lists of 100 items and inner lists of 100 items, the engine executes 10,000 expressions. Keep nested iterations minimal, or flatten data before processing using a!flatten().

---

Realistic Implementation Scenario: Commercial Invoice Calculation

A commercial logistics application processes shipping invoices. Each invoice contains an array of line items with quantities, base prices, and product codes:

a!localVariables(
  /* Sample array of invoice line item CDTs */
  local!lineItems: ri!invoice.lineItems,
  
  /* Process each line item to calculate line totals and discounts */
  local!calculatedItems: a!forEach(
    items: local!lineItems,
    expression: a!localVariables(
      local!rawPrice: fv!item.quantity * fv!item.unitPrice,
      /* Apply a 10% example discount for five or more units */
      local!discountRate: if(fv!item.quantity >= 5, 0.10, 0.0),
      local!discountAmount: fn!round(local!rawPrice * local!discountRate, 2),
      local!lineTotal: local!rawPrice - local!discountAmount,
      
      /* Return transformed line item object */
      {
        itemNumber: fv!index,
        productCode: fv!item.productCode,
        quantity: fv!item.quantity,
        unitPrice: fv!item.unitPrice,
        discount: local!discountAmount,
        lineTotal: local!lineTotal
      }
    )
  ),
  
  /* Aggregate summary */
  {
    lineCount: fn!length(local!calculatedItems),
    items: local!calculatedItems,
    invoiceTotal: fn!sum(property(local!calculatedItems, "lineTotal", 0))
  }
)

In this real-world implementation:

• fv!index assigns sequential item numbering starting at 1.
• fv!item accesses individual properties of each line item.
• property() cleanly extracts all lineTotal values into a flat numeric array for fn!sum().

---

Exam Traps & Development Best Practices

Source checked 2026-10-18: Appian forEach behavior.