@servicenow/sdk-build-plugins 4.6.0 → 4.7.0

package/src/flow/flow-logic/flow-logic-diagnostics.ts

@@ -1,4 +1,4 @@
-import type { FlowLogicInstanceShape, DoInParallelInstanceShape } from './flow-logic-shapes'
+import type { FlowLogicInstanceShape } from './flow-logic-shapes'
 import {
     ts,
     PropertyAccessShape,
@@ -8,11 +8,19 @@ import {
     ObjectShape,
     CallExpressionShape,
     type Diagnostics,
+    type Shape,
 } from '@servicenow/sdk-build-core'
 import { FLOW_LOGIC } from './flow-logic-constants'
 import { getCallExpressionName } from '../../utils'
 import { findAncestorByCalleeName } from '../utils/utils'
-import { isDoInParallelShape, isSetFlowVariablesShape, isAssignSubflowOutputsShape } from './flow-logic-plugin-helpers'
+import {
+    isDoInParallelShape,
+    isSetFlowVariablesShape,
+    isAppendToFlowVariablesShape,
+    isAssignSubflowOutputsShape,
+    isTryCatchShape,
+} from './flow-logic-plugin-helpers'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
 import { PillShape } from '../utils/data-pill-shapes'
 import { ARRAY_FLOW_DATA_TYPES, type ArrayFlowDataType } from '@servicenow/sdk-core/runtime/flow'
 import { FDInlineScriptCallShape } from '../plugins/inline-script-plugin'
@@ -30,8 +38,9 @@ const FLOW_LOGIC_VALIDATORS: { [K in FLOW_LOGIC]: FlowLogicValidator } = {
     [FLOW_LOGIC.WAIT_FOR_A_DURATION]: validateWaitForADuration,
     [FLOW_LOGIC.FOR_EACH]: validateForEach,
     [FLOW_LOGIC.DO_IN_PARALLEL]: validateDoInParallel,
-    [FLOW_LOGIC.TRY_CATCH]: () => undefined,
+    [FLOW_LOGIC.TRY_CATCH]: validateTryCatch,
     [FLOW_LOGIC.SET_FLOW_VARIABLES]: validateSetFlowVariables,
+    [FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES]: validateAppendToFlowVariables,
     [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: validateAssignSubflowOutputs,
 }
 
@@ -137,8 +146,8 @@ function findParentFlowLogic(node: ts.Node | undefined): ts.CallExpression | und
 
     const callName = getCallExpressionName(current)
 
-    if ([FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF, FLOW_LOGIC.ELSE, 'TryCatch', 'MakeADecision'].includes(callName)) {
-        if (callName === 'TryCatch') {
+    if ([FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF, FLOW_LOGIC.ELSE, FLOW_LOGIC.TRY_CATCH, 'MakeADecision'].includes(callName)) {
+        if (callName === FLOW_LOGIC.TRY_CATCH) {
             // For TryCatch, GoBackTo should only be in the catch block, not in try block
             if (!isInCatchBlock(node)) {
                 return undefined // Invalid placement - not in catch block
@@ -311,13 +320,36 @@ function validateForEach(expr: FlowLogicInstanceShape): string | undefined {
     return undefined
 }
 
+// TypeScript enforces argument count, $id, and `() => void` shape of try/catch.
+// The plugin's transform logic requires arrow functions specifically, which TS does not distinguish from other
+// function forms — so check that here.
+function validateTryCatch(expr: FlowLogicInstanceShape): string | undefined {
+    if (!isTryCatchShape(expr)) {
+        return undefined
+    }
+
+    const handlers = expr.getArgument(1)?.if(ObjectShape)
+    const tryHandler = handlers?.get('try')
+    const catchHandler = handlers?.get('catch')
+
+    if (!tryHandler?.if(ArrowFunctionShape)) {
+        return "TryCatch: 'try' handler must be an arrow function"
+    }
+
+    if (!catchHandler?.if(ArrowFunctionShape)) {
+        return "TryCatch: 'catch' handler must be an arrow function"
+    }
+
+    return undefined
+}
+
 function validateDoInParallel(expr: FlowLogicInstanceShape): string | undefined {
     if (isDoInParallelShape(expr)) {
-        const doInParallelExpr = expr as DoInParallelInstanceShape
-        const originalNode = doInParallelExpr.getOriginalNode()
+        // Check for nested `DoInParallel`. `findAncestorByCalleeName` returns the node itself when it matches, so
+        // start the search from the parent call expression. Otherwise, every `DoInParallel` would flag itself.
+        const parentCall = expr.getOriginalNode()?.getFirstAncestorByKind(ts.SyntaxKind.CallExpression)
+        const parentDoInParallel = findAncestorByCalleeName(parentCall, FLOW_LOGIC.DO_IN_PARALLEL)
 
-        // Check for nested DoInParallel
-        const parentDoInParallel = findAncestorByCalleeName(originalNode, FLOW_LOGIC.DO_IN_PARALLEL)
         if (parentDoInParallel) {
             return 'Nested DoInParallel calls are not allowed. DoInParallel cannot be used within another DoInParallel block.'
         }
@@ -327,83 +359,69 @@ function validateDoInParallel(expr: FlowLogicInstanceShape): string | undefined
 }
 
 /**
- * Validates SetFlowVariables flow logic instance.
- * Performs comprehensive validation of arguments, types, and structure.
+ * Shared validator for "variable assignment"-style flow logic shapes (SetFlowVariables and AppendToFlowVariables).
+ * Both shapes share the (config, schema, values) argument layout and the same value-type rules; only the type guard,
+ * the values' accessor, and the error-message prefix differ. Routing both through one helper prevents the two
+ * implementations from drifting independently and ensures any future validation change applies to both call sites at
+ * once.
  *
- * **Validations performed:**
- * 1. Argument count: Must have exactly 3 arguments
- * 2. Config object: Must contain required $id property
- * 3. Schema argument: Must be params.flowVariables (schema reference)
- * 4. Values object: Must be non-empty
- * 5. Variable names: Cannot be empty or whitespace
- * 6. Variable values: Must be valid types (string, number, boolean, or datapill)
+ * Validations performed:
+ *   1. Argument count must be exactly 3 (config, schema, values).
+ *   2. Config must expose a valid $id (`expr.getSysId()` must not throw).
+ *   3. Values argument must be a defined, non-empty object.
+ *   4. Every key must be a non-empty string.
+ *   5. Every value must be a string / number / boolean / object / array / datapill / inline script.
  *
- * **Valid value types:**
- * - String literals: "hello"
- * - Numbers: 42, 3.14
- * - Booleans: true, false
- * - Objects: { a: "value", b: 42 } (ObjectShape - for FlowObject types)
- * - Arrays: [1, 2, 3] (ArrayShape - for FlowArray types)
- * - Datapills: params.trigger.name, params.complexObject (PropertyAccessShape)
- * - Template expressions: `Hello ${params.trigger.name}` (TemplateExpressionShape)
- *
- * @param expr - The SetFlowVariables flow logic instance shape
- * @returns Error message if validation fails, undefined if valid
- *
- * @example
- * // Valid usage
- * wfa.flowLogic.setFlowVariables(
- *   { $id: Now.ID['...'] },
- *   params.flowVariables,  // ← Schema reference (2nd argument)
- *   { user: params.trigger.name, count: 42, active: true }
- * )
+ * @param expr     - The flow logic instance shape to validate.
+ * @param name     - API name used as the error-message prefix (e.g., 'SetFlowVariables').
+ * @param isShape  - Type-guard distinguishing the specific assignment shape.
+ * @param getValues - Accessor returning the values ObjectShape from the narrowed shape.
+ * @returns Error message if validation fails, undefined otherwise.
  */
-function validateSetFlowVariables(expr: FlowLogicInstanceShape): string | undefined {
-    if (!isSetFlowVariablesShape(expr)) {
+function validateVariableAssignmentShape<S extends FlowLogicInstanceShape>(
+    expr: FlowLogicInstanceShape,
+    name: string,
+    isShape: (e: FlowLogicInstanceShape) => e is S,
+    getValues: (shape: S) => ObjectShape | undefined
+): string | undefined {
+    if (!isShape(expr)) {
         return undefined
     }
 
-    // Validate argument count
     const args = expr.getArguments()
     if (args.length !== 3) {
-        return `SetFlowVariables requires exactly 3 arguments (config, schema, values), but received ${args.length}`
+        return `${name} requires exactly 3 arguments (config, schema, values), but received ${args.length}`
     }
 
-    // Validate config argument
     try {
         expr.getSysId()
-    } catch (error) {
-        return 'SetFlowVariables: First argument (config) must be an object with valid $id property'
+    } catch {
+        return `${name}: First argument (config) must be an object with valid $id property`
     }
 
-    // Validate values argument (third argument)
-    const valuesArg = expr.getVariablesToSet()
+    const valuesArg = getValues(expr)
     if (!valuesArg || valuesArg.isUndefined()) {
-        return 'SetFlowVariables: Third argument (values) is required'
+        return `${name}: Third argument (values) is required`
     }
 
     if (!valuesArg.isObject()) {
-        return 'SetFlowVariables: Third argument (values) must be an object'
+        return `${name}: Third argument (values) must be an object`
     }
 
-    // Validate that values object is not empty
     const entries = Array.from(valuesArg.entries({ resolve: false }))
     if (entries.length === 0) {
-        return 'SetFlowVariables: Values object cannot be empty - at least one variable must be set'
+        return `${name}: Values object cannot be empty - at least one variable is required`
     }
 
-    // Validate each value in the object
     for (const [key, valueShape] of entries) {
         if (!key || key.trim() === '') {
-            return 'SetFlowVariables: Variable names cannot be empty'
+            return `${name}: Variable names cannot be empty`
         }
 
-        // Check if value is valid (string, datapill, template expression, or inline script)
         if (valueShape.isUndefined()) {
-            return `SetFlowVariables: Variable '${key}' has undefined value`
+            return `${name}: Variable '${key}' has undefined value`
         }
 
-        // Values can be: strings, numbers, booleans, objects, arrays, datapills, template expressions, or inline scripts
         const isDatapill = valueShape instanceof PropertyAccessShape || valueShape instanceof TemplateExpressionShape
         const isInlineScript = valueShape instanceof FDInlineScriptCallShape
         const isIdentifier = valueShape instanceof IdentifierShape
@@ -417,17 +435,177 @@ function validateSetFlowVariables(expr: FlowLogicInstanceShape): string | undefi
             isInlineScript
 
         if (!isValidType) {
-            // Provide specific error message for unsupported types
             if (isIdentifier) {
-                return `SetFlowVariables: Variable '${key}' cannot use local variable references. Use direct values (literals) or datapills (e.g., params.someField) instead`
+                return `${name}: Variable '${key}' cannot use local variable references. Use direct values (literals) or datapills (e.g., params.someField) instead`
             }
-            return `SetFlowVariables: Variable '${key}' has invalid value type. Expected string, number, boolean, object, array, or datapill expression`
+
+            return `${name}: Variable '${key}' has invalid value type. Expected string, number, boolean, object, array, or datapill expression`
+        }
+    }
+
+    return undefined
+}
+
+function validateSetFlowVariables(expr: FlowLogicInstanceShape): string | undefined {
+    return validateVariableAssignmentShape(expr, 'SetFlowVariables', isSetFlowVariablesShape, (s) =>
+        s.getVariablesToSet()
+    )
+}
+
+/**
+ * Validates AppendToFlowVariables flow logic instance.
+ *
+ * The "target must be array-typed" constraint is enforced at compile time by the API type signature
+ * (`KV[K] extends Array<infer E> ? ... : never`). The platform only supports appending to Array.Object flow variables —
+ * other array element types (string / integer / boolean / datetime) are runtime no-ops, so this validator emits an
+ * error for any target whose flow variable is not declared as `FlowArray({ elementType: FlowObject(...) })`. The
+ * remaining argument / structural checks are shared with SetFlowVariables via `validateVariableAssignmentShape`.
+ *
+ * Additionally, when an array literal is provided as the value for an Array.Object target, every element must itself
+ * be an object literal or a datapill expression — primitive literals are not valid array.object elements and the TS
+ * `unknown[]` arm of the value union lets them slip past the compile-time check.
+ *
+ * @param expr - The AppendToFlowVariables flow logic instance shape
+ * @returns Error message if validation fails, undefined if valid
+ */
+function validateAppendToFlowVariables(expr: FlowLogicInstanceShape): string | undefined {
+    const shapeError = validateVariableAssignmentShape(
+        expr,
+        'AppendToFlowVariables',
+        isAppendToFlowVariablesShape,
+        (s) => s.getValuesToAppend()
+    )
+    if (shapeError) {
+        return shapeError
+    }
+
+    if (!isAppendToFlowVariablesShape(expr)) {
+        return undefined
+    }
+
+    const parentFlow = findAncestorByCalleeName(expr.getOriginalNode(), 'Flow', 'Subflow')
+    if (!parentFlow) {
+        // Placement is already validated by the umbrella check; nothing further to assert here.
+        return undefined
+    }
+
+    const flowVariableInitializers = getFlowVariableInitializers(parentFlow)
+    const valuesArg = expr.getValuesToAppend()
+    for (const [key, valueShape] of valuesArg.entries({ resolve: false })) {
+        const initializer = flowVariableInitializers.get(key)
+        // If the variable isn't declared in flowVariables, the TS signature has already rejected the key at compile
+        // time — skip rather than double-reporting.
+        if (!initializer) {
+            continue
+        }
+        if (!isArrayObjectFlowVariable(initializer)) {
+            return `AppendToFlowVariables: Variable '${key}' is not an Array.Object flow variable. AppendToFlowVariables only supports Array.Object targets — declare the variable as FlowArray({ elementType: FlowObject(...) }).`
+        }
+        const elementError = validateArrayObjectElements(key, valueShape)
+        if (elementError) {
+            return elementError
+        }
+    }
+
+    return undefined
+}
+
+/**
+ * For an Array.Object target, every element of an array-literal value must be an object literal or a datapill
+ * expression. A primitive literal (string / number / boolean) inside the array is silently accepted by TypeScript
+ * (via the `unknown[]` arm of the value union) but rejected by the platform at runtime, so we flag it here.
+ *
+ * Non-array values (single object literal, whole-field template string, whole-field datapill) are accepted as-is —
+ * those arms are already covered by the shared `validateVariableAssignmentShape` checks and by the platform's own
+ * runtime handling.
+ */
+function validateArrayObjectElements(key: string, valueShape: Shape): string | undefined {
+    if (!valueShape.isArray()) {
+        return undefined
+    }
+
+    const elements = valueShape.asArray().getElements(false)
+    for (const [i, element] of elements.entries()) {
+        if (isArrayObjectElement(element)) {
+            continue
         }
+
+        return `AppendToFlowVariables: Variable '${key}' has an invalid element at index ${i}. Array.Object variables only accept object literals or datapill expressions as elements — primitive values are not allowed.`
     }
 
     return undefined
 }
 
+function isArrayObjectElement(element: Shape): boolean {
+    if (element instanceof ObjectShape) {
+        return true
+    }
+    if (
+        element instanceof PropertyAccessShape ||
+        element instanceof TemplateExpressionShape ||
+        element instanceof PillShape ||
+        element instanceof FDInlineScriptCallShape
+    ) {
+        return true
+    }
+
+    // `wfa.dataPill(...)` calls are unwrapped to PillShape by the DataPillPlugin in normal builds. However, raw
+    // CallExpressionShape can still arrive here for fixtures that haven't been subclassed yet — accept any call
+    // expression whose callee resolves to wfa.dataPill so the order of plugin subclassing does not matter.
+    return element instanceof CallExpressionShape && element.getCallee() === 'wfa.dataPill'
+}
+
+/**
+ * Reads a Flow / Subflow's `flowVariables` config property and returns a map from variable name to its initializer
+ * expression. Returns an empty map when `flowVariables` is missing or shaped unexpectedly — those cases are handled by
+ * other validators (or by the TypeScript type system) and should not be re-flagged here.
+ */
+function getFlowVariableInitializers(flowOrSubflow: ts.CallExpression): Map<string, ts.Expression> {
+    const result = new Map<string, ts.Expression>()
+    const configArg = flowOrSubflow.getArguments()[0]
+    if (!configArg || !ts.Node.isObjectLiteralExpression(configArg)) {
+        return result
+    }
+    const flowVarsProp = configArg.getProperty('flowVariables')?.asKind(ts.SyntaxKind.PropertyAssignment)
+    const flowVarsObject = flowVarsProp?.getInitializer()?.asKind(ts.SyntaxKind.ObjectLiteralExpression)
+    if (!flowVarsObject) {
+        return result
+    }
+    for (const prop of flowVarsObject.getProperties()) {
+        const propertyAssignment = prop.asKind(ts.SyntaxKind.PropertyAssignment)
+        const initializer = propertyAssignment?.getInitializer()
+        if (!propertyAssignment || !initializer) {
+            continue
+        }
+        result.set(getPropertyAssignmentName(propertyAssignment), initializer)
+    }
+    return result
+}
+
+function getPropertyAssignmentName(node: ts.PropertyAssignment): string {
+    const nameNode = node.getNameNode()
+    return ts.Node.isStringLiteral(nameNode) || ts.Node.isNoSubstitutionTemplateLiteral(nameNode)
+        ? nameNode.getLiteralValue()
+        : nameNode.getText()
+}
+
+/**
+ * Returns true when the given flow-variable initializer expression is a `FlowArray({ elementType: FlowObject(...) })`
+ * call — the only flow-variable shape that AppendToFlowVariables can target at runtime.
+ */
+function isArrayObjectFlowVariable(initializer: ts.Expression): boolean {
+    if (!ts.Node.isCallExpression(initializer) || getCallExpressionName(initializer) !== 'FlowArray') {
+        return false
+    }
+    const flowArrayConfig = initializer.getArguments()[0]?.asKind(ts.SyntaxKind.ObjectLiteralExpression)
+    const elementTypeProp = flowArrayConfig?.getProperty('elementType')?.asKind(ts.SyntaxKind.PropertyAssignment)
+    const elementTypeInit = elementTypeProp?.getInitializer()
+    if (!elementTypeInit || !ts.Node.isCallExpression(elementTypeInit)) {
+        return false
+    }
+    return getCallExpressionName(elementTypeInit) === 'FlowObject'
+}
+
 /**
  * Validates AssignSubflowOutputs flow logic instance.
  * Performs comprehensive validation of arguments, types, structure, and placement.

package/src/flow/flow-logic/flow-logic-plugin-helpers.ts

@@ -7,6 +7,7 @@ import type {
     TryCatchInstanceShape,
     DoInParallelInstanceShape,
     SetFlowVariablesInstanceShape,
+    AppendToFlowVariablesInstanceShape,
     AssignSubflowOutputsInstanceShape,
 } from './flow-logic-shapes'
 import {
@@ -33,7 +34,7 @@ import {
     DURATION_TYPE_PROPS,
     WAIT_FOR_A_DURATION_INPUT_DESCRIPTORS,
 } from './flow-logic-constants'
-import { resolveDataPillShape, sysIdToUuid } from '../utils/utils'
+import { getOrderSuffix, resolveDataPillShape, sysIdToUuid } from '../utils/utils'
 import { ArrowFunctionShape } from '../../arrow-function-plugin'
 import { NowIdShape } from '../../now-id-plugin'
 import { validateFlowLogic, validateSibling } from './flow-logic-diagnostics'
@@ -222,6 +223,9 @@ export namespace FlowLogicValueProcessor {
         [FLOW_LOGIC.SET_FLOW_VARIABLES]: (data) => {
             return prepareSetFlowVariables(data.asObject(), '')
         },
+        [FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES]: (data) => {
+            return prepareSetFlowVariables(data.asObject(), '')
+        },
         [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: (data) => {
             return prepareAssignSubflowOutputs(data.asObject())
         },
@@ -266,7 +270,7 @@ export namespace FlowLogicValueProcessor {
         return {
             outputsToAssign: logicType === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS ? preparedData : [],
             variables:
-                logicType === FLOW_LOGIC.SET_FLOW_VARIABLES
+                logicType === FLOW_LOGIC.SET_FLOW_VARIABLES || logicType === FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES
                     ? prepareSetFlowVariables(data.asObject(), 'variables')
                     : [],
             decisionTableInputs: [],
@@ -655,7 +659,12 @@ export namespace FlowLogicValueProcessor {
         [FLOW_LOGIC.FOR_EACH]: parseForEach,
         [FLOW_LOGIC.DO_IN_PARALLEL]: () => ({}),
         [FLOW_LOGIC.TRY_CATCH]: () => ({}),
+        // Unreachable: parse() short-circuits for SET_FLOW_VARIABLES, APPEND_TO_FLOW_VARIABLES, and
+        // ASSIGN_SUBFLOW_OUTPUTS before this lookup runs — their payloads live in `variables` / `outputsToAssign`, not
+        // `inputs`, so they take dedicated branches that delegate to `parseEntriesFromArray`. The entries below exist
+        // only to satisfy the `{ [K in FLOW_LOGIC]: ValueParser }` exhaustiveness constraint.
         [FLOW_LOGIC.SET_FLOW_VARIABLES]: () => ({}),
+        [FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES]: () => ({}),
         [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: () => ({}),
     }
 
@@ -688,8 +697,9 @@ export namespace FlowLogicValueProcessor {
     ): FlowLogicParseResult {
         const valuesJson = parseGzippedJson(gZippedString)
 
-        // Special handling for SET_FLOW_VARIABLES - data is in variables array
-        if (logicType === FLOW_LOGIC.SET_FLOW_VARIABLES) {
+        // Special handling for SET_FLOW_VARIABLES and APPEND_TO_FLOW_VARIABLES - data is in the variable array.
+        // Both flow logics share the same wire format; only the platform-side semantics differ (overwrite vs. append).
+        if (logicType === FLOW_LOGIC.SET_FLOW_VARIABLES || logicType === FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES) {
             if (valuesJson?.variables?.length) {
                 return parseEntriesFromArray(valuesJson.variables, typeMap, labelCacheMap)
             }
@@ -1642,6 +1652,10 @@ export function isSetFlowVariablesShape(expr: FlowLogicInstanceShape): expr is S
     return expr.getCallee() === FLOW_LOGIC.SET_FLOW_VARIABLES
 }
 
+export function isAppendToFlowVariablesShape(expr: FlowLogicInstanceShape): expr is AppendToFlowVariablesInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES
+}
+
 export function isAssignSubflowOutputsShape(expr: FlowLogicInstanceShape): expr is AssignSubflowOutputsInstanceShape {
     return expr.getCallee() === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS
 }
@@ -1905,6 +1919,11 @@ async function extractDataFromShape(
         return await resolveConfigDataPills(variablesToSet, transform, diagnostics)
     }
 
+    if (isAppendToFlowVariablesShape(expr)) {
+        const valuesToAppend = expr.getValuesToAppend()
+        return await resolveConfigDataPills(valuesToAppend, transform, diagnostics)
+    }
+
     if (isAssignSubflowOutputsShape(expr)) {
         const assignedSubflowOutputs = expr.getAssignedSubflowOutputs()
         return await resolveConfigDataPills(assignedSubflowOutputs, transform, diagnostics)
@@ -1969,6 +1988,12 @@ export async function getFlowLogicInstanceRecord(
         })
     }
 
+    if (isAppendToFlowVariablesShape(expr)) {
+        instanceRecord = instanceRecord.merge({
+            flow_variables_assigned: expr.getValuesToAppendAsString(),
+        })
+    }
+
     instanceRecord = instanceRecord.merge({
         values: values,
     })
@@ -2084,6 +2109,7 @@ const FLOW_LOGIC_ARGUMENT_BUILDERS: { [K in FLOW_LOGIC]: FlowLogicArgumentBuilde
     [FLOW_LOGIC.DO_IN_PARALLEL]: buildBasicArguments,
     [FLOW_LOGIC.TRY_CATCH]: buildBasicArguments,
     [FLOW_LOGIC.SET_FLOW_VARIABLES]: buildSetFlowVariablesArguments,
+    [FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES]: buildAppendToFlowVariablesArguments,
     [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: buildAssignSubflowOutputsArguments,
 }
 
@@ -2226,6 +2252,31 @@ function buildSetFlowVariablesArguments(
     )
 }
 
+/**
+ * Builds arguments for AppendToFlowVariables when converting XML to Fluent.
+ * Mirrors SetFlowVariables — both target the flow's `sys_hub_flow_variable` schema and use the `{{flowVariables}}`
+ * schema reference. The platform-side semantics differ (append vs. overwrite), but the wire format and argument shape
+ * are identical.
+ *
+ * @param record - ServiceNow sys_hub_flow_logic_instance_v2 record
+ * @param _logicBodyShapes - Unused (required by FlowLogicArgumentBuilder interface)
+ * @param database - Database to query for the flow variable schemas
+ * @returns Array of three Shape arguments for AppendToFlowVariables call
+ */
+function buildAppendToFlowVariablesArguments(
+    record: Record,
+    _logicBodyShapes: Shape[],
+    database: Database
+): Shape<unknown>[] {
+    return buildVariableOrOutputArguments(
+        record,
+        database,
+        'sys_hub_flow_variable',
+        FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES,
+        '{{flowVariables}}'
+    )
+}
+
 /**
  * Builds arguments for AssignSubflowOutputs when converting XML to Fluent.
  * Creates the three arguments required by the AssignSubflowOutputs API:
@@ -2431,11 +2482,13 @@ function extractForEachParameterName(record: Record): string {
 }
 
 /**
- * Gets the fallback parameter name based on order or default.
+ * Gets the fallback parameter name based on order or default. A ForEach inside
+ * a DoInParallel branch carries a composite order like `19➛20`; strip the
+ * separator so the generated identifier is valid JS.
  */
 function getFallbackParameterName(record: Record): string {
     const order = record.get('order')?.getValue() as string | undefined
-    return order ? `item_${order}` : 'item'
+    return order ? `item_${getOrderSuffix(order)}` : 'item'
 }
 
 function buildForEachArguments(record: Record, logicBodyShapes: Shape[]): Shape<unknown>[] {