12.3 Error Handling, Type Coercion & Expression Debugging

Types, Missing Data, and Expression Debugging

Reliable Appian expressions require a clear data contract. Know whether an input is a number, text, list, map, CDT, or record value before choosing an operation. Many defects attributed to a mysterious interface failure are actually a missing field, unexpected list shape, or conversion that changed a value.

The Associate Developer exam tests recognizing these problems and selecting a deliberate repair. The objective is predictable behavior, not suppressing every error with an empty value. An unavailable data source and a successful query returning no rows are different situations.

Inspect Values and Types

Reproduce the failing input in the expression editor. Inspect the returned value and type. A query result may be a DataSubset whose .data field is the list; treating the wrapper as a row creates incorrect property access. A typed record uses record-field references, while a map may use property names. Do not assume that visually similar outputs have identical structures.

Use typeof() or the editor's type display when necessary. Check list cardinality as well as element type. An expression expecting one customer cannot safely assume that a query returning several matches has identified the intended customer. Fix the identifier or selection rule instead of always taking the first item.

Navigate Missing Properties Deliberately

index(data, keyOrPosition, default) and property() support deliberate extraction. Direct bracket access is appropriate when the schema and bounds are known, especially as a save target. Optional external maps need validation because fields may be missing or have an unexpected type.

The default supplied to index() addresses missing keys or positions; it should not be confused with replacing every present-but-null field. Use a!defaultValue() when the policy explicitly requires substituting for null or empty content.

a!localVariables(
  local!address: index(ri!customer, "address", a!map()),
  local!city: index(local!address, "city", null),
  a!defaultValue(local!city, "Not Provided")
)

This is a map-oriented display example. Validate incoming structure and select the correct field access for typed records. A display fallback does not establish that a required address is valid for order fulfillment. If the address is required, return a clear validation outcome instead of submitting the fallback as actual source data.

Null and Collection Behavior

a!isNullOrEmpty() recognizes null, empty text, and empty lists. It does not strip spaces; use trim() for Text inputs when appropriate. A map with required fields set to null may still exist, so check those fields individually.

a!forEach() with null or an empty items list returns an empty list without evaluating its expression. A null element inside a nonempty list is different: the expression must handle that element. Test both cases. Do not claim that a null list inherently crashes a forEach expression.

Explicit Conversions

Use a conversion when the input contract requires one, and check its documented behavior. Converting does not validate every business rule. A numeric conversion may accept input more broadly than the application intends, so normalize and validate before relying on its result.

For integer conversion, do not teach truncation as the rule. If a business calculation requires rounding down, choose the appropriate mathematical function explicitly. For dates and timestamps, use unambiguous construction or the parser intended for the source format, and consider time zones when a time is included.

Boolean Text Is Not Generic Truthiness

Appian's toboolean() does not treat every nonempty string as true. Numeric zero becomes false and other numbers become true. Strings beginning with t, T, y, Y, or 1 become true; other strings become false. Null remains null.

That conversion is broader than a strict true/false text protocol. For a source promising only true and false, validate the normalized text against that allowed set, then compare it explicitly. An unexpected value such as "temporary" could become true under the conversion's documented first-character rule. Decide whether to reject such data rather than quietly accepting it.

Read the Error in Context

For an undefined variable, inspect spelling and whether the variable exists in this evaluation context. An interface uses rule inputs; a process wrapper may pass pv! or ac! values into those inputs. An fv! variable is supplied only by the function that documents it.

For an invalid index, inspect the collection length and requested position. For a type error, compare the actual values with the expected types before adding casts. For a failed query, inspect authorization, filters, source availability, and sync status. Returning an empty list for every failure would conceal operational problems.

Reduce a complex expression to the smallest failing subexpression, correct it, and restore surrounding logic incrementally. Re-run saved tests for normal, boundary, and missing-data scenarios after the fix. If a shared rule changes its output shape, test its dependents as well.

Measure Performance Before Choosing a Fix

Use the editor's performance details to identify slow evaluations. If a query wrapper accounts for most of the time, inspect its internal work and the data-access path. The name alone does not prove whether the delay is database I/O, several repeated queries, or expensive processing after retrieval.

For an illustrative trace of 3200 milliseconds total and 3050 milliseconds in one rule, that rule accounts for 95.3125% of the measured time. Investigate it first, then compare another measurement with the same inputs. Do not infer a guaranteed production improvement or invent memory metrics that the tool has not supplied.

Takeaway: Diagnose the actual value, type, shape, and context; apply explicit conversion and missing-data policies; then verify behavior and performance with evidence.

Sources checked 2026-10-18: Boolean conversion, integer conversion, forEach behavior, and null/empty checks.