@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/plugins/flow-definition-plugin.ts

@@ -0,0 +1,2173 @@
+import {
+    CallExpressionShape,
+    Plugin,
+    UndefinedShape,
+    Record,
+    type Relationship,
+    type Relationships,
+    IdentifierShape,
+    ObjectShape,
+    VariableStatementShape,
+    StringShape,
+    PropertyAccessShape,
+    type Shape,
+    TemplateExpressionShape,
+    TemplateSpanShape,
+    TemplateValueShape,
+    type Diagnostics,
+    ts,
+    deleteMultipleDiff,
+    StringLiteralShape,
+    type Logger,
+} from '@servicenow/sdk-build-core'
+import { gzipSync } from 'node:zlib'
+
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { NowIdShape } from '../../now-id-plugin'
+import { buildVariableShapes, complexObjectMatchesIoRecord } from '../utils/flow-io-to-record'
+import { FLOW_API_NAME, slugifyString, SUBFLOW_API_NAME, TRIGGER_INSTANCE_API_NAME } from '../utils/flow-constants'
+import { generateXML } from '../utils/flow-to-xml'
+import { DO_IN_PARALLEL_BLOCK_SYS_ID, FLOW_LOGIC, FlowLogicSysId } from '../flow-logic/flow-logic-constants'
+import { TriggerInstancePlugin } from './flow-trigger-instance-plugin'
+import { FlowLogicPlugin } from '../flow-logic/flow-logic-plugin'
+import { FlowInstancePlugin } from './flow-instance-plugin'
+import {
+    checkForUnsupportedFlowDescendants,
+    getIdentifierFromRecord,
+    getRecordFromFlowInstaceShape,
+    uuidToSysId,
+    validateFlowVariableCall,
+} from '../utils/utils'
+import { getCallExpressionName } from '../../utils'
+import {
+    extractLabelCache,
+    createDefinitionMap,
+    extractTriggerInputs,
+    extractTriggerOutputs,
+    updateForEachMetadata,
+    extractDataPillsFromValuesArray,
+} from '../utils/label-cache-processor'
+import { createLableCacheNameToTypeMap } from '../utils/label-cache-parser'
+import {
+    parseSinglePill,
+    isUuidPrefix,
+    mapPillPrefixToTsRoot,
+    createPropertyAccessFromPath,
+} from '../utils/pill-string-parser'
+import { isDataPill } from '../utils/complex-object-resolver'
+import { ArrayShape } from '@servicenow/sdk-build-core'
+import { processFlowInputs, processFlowOutputs, processFlowVariables } from '../utils/flow-variable-processor'
+import { buildUuidToIdentifierMap, processInstanceForDatapills, uuidToRecordMap } from '../utils/datapill-transformer'
+import {
+    DEFAULT_PARAM_NAME,
+    PARALLEL_ORDER_SEPARATOR,
+    FLOW_PRIORITY_DEFAULT,
+    RUN_AS_DEFAULT,
+    ACCESS_DEFAULT,
+    GENERATION_SOURCE,
+    EMPTY_STRING,
+    BOOLEAN_FALSE_STRING,
+    FLOW_STATUS_DRAFT,
+    FLOW_VERSION,
+    FLOW_TYPE_FLOW,
+    FLOW_TYPE_SUBFLOW,
+} from '../constants/flow-plugin-constants'
+import { resolveComplexInput } from '../utils/complex-object-resolver'
+
+/** Field name for complex object collection arrays in JSON payload */
+const COMPLEX_OBJECT_COLLECTION_FIELD = '$COCollectionField'
+
+// ============================================================================
+// TYPE DEFINITIONS FOR COMPLEX OBJECTS
+// ============================================================================
+
+/** Represents a field facet map with UI metadata */
+interface FieldFacetMap {
+    choiceOption?: string
+    uiTypeLabel?: string
+    mapped?: string
+}
+
+/** Represents a parameter object for a flow variable or field */
+interface ParameterObject {
+    children: ChildParameter[]
+    type_label: string
+    id: string
+    label: string
+    name: string
+    type: string
+    order: number
+    extended: boolean
+    mandatory: boolean
+    readOnly: boolean
+    hint: string
+    maxsize: number
+    reference: string
+    reference_display: string
+    choiceOption: string
+    table: string
+    columnName: string
+    defaultValue: string
+    defaultDisplayValue?: string
+    use_dependent: boolean
+    fShowReferenceFinder: boolean
+    local: boolean
+    attributes: { [key: string]: unknown }
+    ref_qual: string
+    dependent_on: string
+    uiDisplayType?: string
+}
+
+/** Represents a child parameter within a complex object */
+interface ChildParameter {
+    fieldFacetMap?: FieldFacetMap
+    value: string
+    displayValue?: string
+    scriptActive: boolean
+    script: { [key: string]: unknown }
+    children: ChildParameter[]
+    uiDisplayType: string
+    type_label: string
+    id: string
+    label: string
+    name: string
+    type: string
+    order: number
+    extended: boolean
+    mandatory: boolean
+    readOnly: boolean
+    hint: string
+    maxsize: number
+    reference: string
+    reference_display: string
+    choiceOption: string
+    table: string
+    columnName: string
+    defaultValue: string
+    defaultDisplayValue?: string
+    use_dependent: boolean
+    fShowReferenceFinder: boolean
+    local: boolean
+    attributes: { [key: string]: unknown }
+    ref_qual: string
+    dependent_on: string
+    parameter?: ParameterObject
+}
+
+/** Represents a variable entry in the values JSON */
+interface VariableEntry {
+    name: string
+    value?: string
+    displayValue?: string
+    children?: ChildParameter[]
+    parameter?: ParameterObject | { [key: string]: unknown }
+    scriptActive?: boolean
+    script?: { [key: string]: unknown }
+    id?: string
+}
+
+/** Represents the structure of values JSON containing variables and inputs */
+interface ValuesJSON {
+    variables?: VariableEntry[] | undefined
+    inputs?: VariableEntry[] | undefined
+    outputsToAssign?: VariableEntry[] | undefined
+    [key: string]: unknown
+}
+import { ApprovalDueDateShape, ApprovalRulesShape } from '../utils/flow-shapes'
+
+// ============================================================================
+// DATAPILL TRANSFORMATION ARCHITECTURE
+// ============================================================================
+// This section contains all datapill transformation logic for Flow Definitions.
+// Datapills are placeholders in XML that reference other flow elements.
+//
+// TWO TYPES OF DATAPILLS:
+//
+// 1. **UUID-based pills** - References to action/subflow instances
+//    Format: {{uuid.property}}
+//    Example: {{f56a03c1-18f6-4f7b-9c61-0d4ff472b334.name}}
+//    Transforms to: actionInstance_1.name
+//    Uses: uuidToIdentifierMap built from instance variable names
+//
+// 2. **Semantic pills** - References to flow parameters
+//    Format: {{prefix.property}}
+//    Supported prefixes:
+//      - trigger: {{trigger.table_name}} → params.trigger.table_name
+//      - flow_variable: {{flow_variable.myVar}} → params.flowVariables.myVar
+//      - inputs: {{inputs.empName}} → params.inputs.empName (subflows only)
+//      - outputs: {{outputs.result}} → params.outputs.result (subflows only)
+//      - subflow: {{subflow.value}} → params.inputs.value (alias for inputs)
+//    Uses: convertPillStringToShape from pill-string-parser utility
+//
+// TRANSFORMATION STRATEGY:
+// The transformDataPill function tries transformations in order:
+//   1. Try UUID-based transformation (transformUuidBasedPill)
+//   2. Try semantic transformation (convertPillStringToShape)
+//   3. Return null if neither matches (keep original string value)
+//
+// This unified approach ensures all datapill types are handled consistently
+// in a single location, making the code maintainable and extensible.
+// ============================================================================
+
+/**
+ * Traverse ancestors to find the topmost ArrowFunction and extract its parameter name
+ * This finds the ArrowFunction that's an argument to Flow/SubflowDefinition, ignoring nested
+ * ArrowFunctions from control flow APIs like If, ElseIf, ForEach.
+ *
+ * @param shape - The shape to start traversing from
+ * @returns The parameter name from the topmost ArrowFunction if found, otherwise undefined
+ */
+function getArrowFunctionParamName(shape: Shape): string | undefined {
+    try {
+        let currentNode = shape.getOriginalNode()
+        let topmostArrowFunction: ReturnType<typeof currentNode.getParentIfKind> | undefined
+
+        // Traverse up the tree to find ALL ArrowFunctions and keep the topmost one
+        while (currentNode) {
+            const arrowFunc = currentNode.getParentIfKind(ts.SyntaxKind.ArrowFunction)
+            if (arrowFunc) {
+                // Found an ArrowFunction, keep track of it as potentially the topmost
+                topmostArrowFunction = arrowFunc
+                // Continue traversing to find if there's a parent ArrowFunction
+                currentNode = arrowFunc
+            } else {
+                // Try to go up one level
+                const parent = currentNode.getParent()
+                if (!parent || parent === currentNode) {
+                    break
+                }
+                currentNode = parent
+            }
+        }
+
+        // Extract parameter name from the topmost ArrowFunction
+        if (topmostArrowFunction && 'getParameters' in topmostArrowFunction) {
+            const params = topmostArrowFunction.getParameters()
+            if (params && params.length > 0) {
+                const firstParam = params[0]
+                if (firstParam) {
+                    const paramName = firstParam.getName()
+                    if (paramName) {
+                        return paramName
+                    }
+                }
+            }
+        }
+    } catch (_e) {
+        // If any error occurs during traversal, just return undefined to fallback to default
+    }
+
+    return undefined
+}
+
+/**
+ * Recursively process a shape to find and transform datapills
+ * Handles nested ObjectShape and ArrayShape structures
+ *
+ * @param value - The shape to process
+ * @param uuidToIdentifierMap - Map of UUID to variable identifiers
+ * @param source - Source for shape creation
+ * @param diagnostics - Diagnostics for error reporting
+ * @param parameterName - Optional parameter name
+ * @param logger - Logger for error reporting
+ * @returns Object with transformed shape and propsChanged flag
+ */
+function processShapeForDatapills(
+    value: Shape,
+    uuidToIdentifierMap: Map<string, IdentifierShape>,
+    source: Record,
+    diagnostics: Diagnostics,
+    logger: Logger,
+    parameterName?: string
+): { shape: Shape; propsChanged: boolean } {
+    // Check if value is already a datapill shape (PropertyAccessShape or TemplateExpressionShape)
+    if (value.if(PropertyAccessShape) || value.if(TemplateExpressionShape)) {
+        return {
+            shape: value,
+            propsChanged: false, // Already a datapill, no transformation needed
+        }
+    }
+    // Handle StringShape - may contain datapills
+    if (value.isString()) {
+        const stringValue = value.as(StringShape).getValue()
+        const transformed = transformDataPill(
+            stringValue,
+            uuidToIdentifierMap,
+            source,
+            diagnostics,
+            logger,
+            parameterName
+        )
+
+        if (transformed !== null) {
+            return {
+                shape: transformed,
+                propsChanged: true, // String was transformed into a datapill
+            }
+        }
+
+        return {
+            shape: value,
+            propsChanged: false,
+        }
+    }
+
+    // Handle ObjectShape - recursively process properties
+    if (
+        value.is(ObjectShape) ||
+        value.is(TemplateValueShape) ||
+        value.is(ApprovalRulesShape) ||
+        value.is(ApprovalDueDateShape)
+    ) {
+        const objEntries = value.isObject() ? value.entries() : value.getTemplateValue().entries()
+        const transformedObj: { [key: string]: Shape } = {}
+        let objPropsChanged = false
+
+        for (const entry of objEntries) {
+            const key: string = entry[0]
+            const propValue: Shape = entry[1]
+            const result = processShapeForDatapills(
+                propValue,
+                uuidToIdentifierMap,
+                source,
+                diagnostics,
+                logger,
+                parameterName
+            )
+            transformedObj[key] = result.shape
+
+            if (result.propsChanged) {
+                objPropsChanged = true
+            }
+        }
+
+        // If any property changed, rebuild the ObjectShape
+        if (objPropsChanged) {
+            let newObjectShape: ObjectShape | TemplateValueShape | ApprovalRulesShape | ApprovalDueDateShape
+            if (value.is(TemplateValueShape)) {
+                newObjectShape = new TemplateValueShape({
+                    source: value.getSource(),
+                    value: transformedObj,
+                })
+            } else if (value.is(ApprovalDueDateShape)) {
+                newObjectShape = new ApprovalDueDateShape({
+                    source: value.getSource(),
+                    value: transformedObj,
+                })
+            } else if (value.is(ApprovalRulesShape)) {
+                newObjectShape = new ApprovalRulesShape({
+                    source: value.getSource(),
+                    value: transformedObj,
+                })
+            } else {
+                newObjectShape = new ObjectShape({
+                    source: value.getSource(),
+                    properties: transformedObj,
+                })
+            }
+            return {
+                shape: newObjectShape,
+                propsChanged: true,
+            }
+        }
+
+        return {
+            shape: value,
+            propsChanged: false,
+        }
+    }
+
+    // Handle ArrayShape - recursively process elements
+    if (value instanceof ArrayShape) {
+        const elements = value.getElements()
+        const transformedElements: Shape[] = []
+        let arrayPropsChanged = false
+
+        for (const element of elements) {
+            const result = processShapeForDatapills(
+                element,
+                uuidToIdentifierMap,
+                source,
+                diagnostics,
+                logger,
+                parameterName
+            )
+            transformedElements.push(result.shape)
+
+            if (result.propsChanged) {
+                arrayPropsChanged = true
+            }
+        }
+
+        // If any element changed, rebuild the ArrayShape
+        if (arrayPropsChanged) {
+            const newArrayShape = new ArrayShape({
+                source: value.getSource(),
+                elements: transformedElements,
+            })
+            return {
+                shape: newArrayShape,
+                propsChanged: true,
+            }
+        }
+
+        return {
+            shape: value,
+            propsChanged: false,
+        }
+    }
+
+    // For any other shape type, pass through
+    return {
+        shape: value,
+        propsChanged: false,
+    }
+}
+
+/**
+ * Transform data pill expressions in string values
+ * Handles two types of datapills:
+ * 1. UUID-based pills: {{uuid.property}} → references to action/subflow instances (e.g., actionInstance_1.name)
+ * 2. Semantic pills: {{trigger.property}}, {{flow_variable.name}} → references to params (e.g., params.trigger.name)
+ *
+ * @param stringValue - String that may contain datapill patterns
+ * @param uuidToIdentifierMap - Map of UUID to variable identifiers (for action/subflow references)
+ * @param source - Source for shape creation
+ * @param diagnostics - Diagnostics for error reporting
+ * @param parameterName - Optional parameter name to use instead of "params" (e.g., from ArrowFunction)
+ * @returns Transformed shape or null if no transformation needed
+ */
+/**
+ * Wrap a PropertyAccessShape or IdentifierShape with wfa.dataPill(expression, 'type') call
+ * This creates a CallExpressionShape that wraps the expression
+ *
+ * @param expression - The PropertyAccessShape or IdentifierShape to wrap
+ * @param source - Source for shape creation
+ * @param dataType - The data type string (default: 'string')
+ * @returns CallExpressionShape wrapping the expression with wfa.dataPill()
+ */
+function wrapWithDataPillCall(
+    expression: PropertyAccessShape | IdentifierShape,
+    source: Record,
+    dataType = 'string'
+): CallExpressionShape {
+    return new CallExpressionShape({
+        source,
+        callee: 'wfa.dataPill',
+        args: [expression, new StringLiteralShape({ source, literalText: dataType })],
+    })
+}
+
+/**
+ * Extract all datapill names from a string value containing datapill patterns
+ * Handles both UUID-based pills ({{uuid.property}}) and semantic pills ({{prefix.path}})
+ *
+ * @param stringValue - String that may contain datapill patterns
+ * @returns Array of datapill names (e.g., ["trigger.table_name", "uuid.record.number"])
+ */
+function extractDataPillNames(stringValue: string): string[] {
+    const dataPillNames: string[] = []
+
+    // Match all datapill patterns: {{...}}
+    const pillPattern = /\{\{([^}]+)\}\}/g
+    const matches = Array.from(stringValue.matchAll(pillPattern))
+
+    for (const match of matches) {
+        if (match[1]) {
+            // Extract the content inside {{}} and split by | to get just the name part
+            // (some pills may have type info like {{pill.name|string}})
+            const pillContent = match[1].split('|')[0]
+            if (pillContent) {
+                dataPillNames.push(pillContent)
+            }
+        }
+    }
+
+    return dataPillNames
+}
+
+/**
+ * Wrap all PropertyAccessShape expressions in a TemplateExpressionShape with wfa.dataPill()
+ * Creates a new TemplateExpressionShape with wrapped expressions in each span
+ *
+ * @param templateExpr - The TemplateExpressionShape, PropertyAccessShape, or IdentifierShape to process
+ * @param source - Source for shape creation
+ * @param labelCacheMap - Optional map of datapill names to their types
+ * @param originalString - Optional original string value to extract datapill name from
+ * @returns New TemplateExpressionShape with wrapped expressions
+ */
+function wrapWithWfaDataPillExpression(
+    templateExpr: TemplateExpressionShape | PropertyAccessShape | IdentifierShape,
+    source: Record,
+    labelCacheMap?: Map<string, string>,
+    originalString?: string
+): TemplateExpressionShape | CallExpressionShape {
+    // Extract all datapill names from the original string
+    const dataPillNames = originalString ? extractDataPillNames(originalString) : []
+
+    if (templateExpr.is(PropertyAccessShape)) {
+        let dataType = 'string'
+        if (labelCacheMap && dataPillNames.length > 0) {
+            // For a single PropertyAccessShape, use the first (and likely only) datapill name
+            const firstPillName = dataPillNames[0]
+            if (firstPillName) {
+                // labelCacheMap returns the type string directly, not an object
+                dataType = labelCacheMap.get(firstPillName) || 'string'
+            }
+        }
+        return wrapWithDataPillCall(templateExpr, source, dataType)
+    }
+
+    if (templateExpr.is(IdentifierShape)) {
+        return wrapWithDataPillCall(templateExpr, source)
+    }
+
+    const originalSpans = templateExpr.getSpans()
+    const wrappedSpans: TemplateSpanShape[] = []
+    let pillIndex = 0
+
+    for (const span of originalSpans) {
+        const expression = span.getExpression()
+        const literalText = span.getLiteralText()
+
+        // Wrap the expression with wfa.dataPill() if it's a PropertyAccessShape or IdentifierShape
+        if (expression instanceof PropertyAccessShape || expression instanceof IdentifierShape) {
+            let dataType = 'string'
+            if (labelCacheMap && pillIndex < dataPillNames.length) {
+                // Use the corresponding datapill name for this expression
+                const pillName = dataPillNames[pillIndex]
+                if (pillName) {
+                    // labelCacheMap returns the type string directly, not an object
+                    dataType = labelCacheMap.get(pillName) || 'string'
+                }
+                pillIndex++
+            }
+            const wrappedExpr = wrapWithDataPillCall(expression, source, dataType)
+
+            wrappedSpans.push(
+                new TemplateSpanShape({
+                    source,
+                    expression: wrappedExpr,
+                    literalText,
+                })
+            )
+        } else {
+            // Keep as-is if not a PropertyAccessShape or IdentifierShape
+            wrappedSpans.push(span)
+        }
+    }
+
+    return new TemplateExpressionShape({
+        source,
+        literalText: templateExpr.getLiteralText(),
+        spans: wrappedSpans,
+    })
+}
+
+/**
+ * Information about a single datapill found in a string
+ */
+interface PillInfo {
+    matchStart: number
+    matchEnd: number
+    matchText: string // Original {{...}} pattern
+    expression: PropertyAccessShape | IdentifierShape
+    type: 'uuid' | 'semantic' // For debugging/tracking
+}
+
+/**
+ * Extract all datapills (both UUID-based and semantic) from a string.
+ * Uses a single regex to find all {{...}} patterns, then determines type using conditional logic.
+ *
+ * @param stringValue - String that may contain datapill patterns
+ * @param uuidToIdentifierMap - Map of UUID to variable identifiers (includes forEach parameter names)
+ * @param source - Source for shape creation
+ * @param diagnostics - Diagnostics for error reporting
+ * @param parameterName - Parameter name for semantic pills (default 'params')
+ * @returns Array of pills with their positions and transformed expressions
+ */
+function extractAllPills(
+    stringValue: string,
+    uuidToIdentifierMap: Map<string, IdentifierShape>,
+    source: Record,
+    _diagnostics: Diagnostics,
+    parameterName?: string
+): PillInfo[] {
+    const pills: PillInfo[] = []
+
+    // SINGLE regex to find ALL pill patterns: {{anything}}
+    const pillRegex = /\{\{([^}]+)\}\}/g
+
+    // Loop through ALL matches
+    for (const match of stringValue.matchAll(pillRegex)) {
+        const fullMatch = match[0] // e.g., "{{uuid.field}}" or "{{trigger.name}}"
+        const content = match[1] // e.g., "uuid.field" or "trigger.name"
+
+        if (!content) {
+            continue
+        }
+
+        const matchStart = match.index ?? 0
+        const matchEnd = matchStart + fullMatch.length
+
+        // Try UUID pattern first (more specific)
+        // UUID format: 8-4-4-4-12 hex digits followed by dot and property path
+        const uuidMatch = content.match(
+            /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([a-zA-Z_][a-zA-Z0-9_.]*[a-zA-Z0-9_])$/
+        )
+
+        if (uuidMatch) {
+            // This is a UUID-based pill
+            const uuid = uuidMatch[1]
+            const property = uuidMatch[2]
+
+            if (!uuid || !property) {
+                continue
+            }
+
+            const identifier = uuidToIdentifierMap.get(uuid)
+
+            if (identifier) {
+                // PRESERVE EXISTING LOGIC: Apply forEach parameter handling
+                const isForEachParam = isForEachParameter(identifier, uuid)
+                let expression: PropertyAccessShape | IdentifierShape
+
+                if (isForEachParam) {
+                    // Special case for forEach: if property is exactly 'item', return just the identifier
+                    if (property === 'item') {
+                        expression = identifier
+                    } else if (property.startsWith('item.')) {
+                        // Strip 'item.' prefix for forEach parameters
+                        const propertyPath = property.substring(5)
+                        expression = new PropertyAccessShape({
+                            source,
+                            elements: [identifier, propertyPath],
+                        })
+                    } else {
+                        // Property doesn't start with 'item.' - preserve as is
+                        expression = new PropertyAccessShape({
+                            source,
+                            elements: [identifier, property],
+                        })
+                    }
+                } else {
+                    // NOT a forEach parameter - preserve full property path
+                    expression = new PropertyAccessShape({
+                        source,
+                        elements: [identifier, property],
+                    })
+                }
+
+                pills.push({
+                    matchStart,
+                    matchEnd,
+                    matchText: fullMatch,
+                    expression,
+                    type: 'uuid',
+                })
+            }
+            // If UUID not in map, skip this pill (existing behavior)
+            continue
+        }
+
+        // Not a UUID pill - try semantic transformation
+        const parsed = parseSinglePill(fullMatch, true)
+
+        if (!parsed) {
+            // Invalid pill format - skip
+            continue
+        }
+
+        if (isUuidPrefix(parsed.prefix)) {
+            // This is a UUID prefix but wasn't caught above - skip
+            continue
+        }
+
+        const tsRoot = mapPillPrefixToTsRoot(parsed.prefix, parameterName)
+
+        if (!tsRoot) {
+            // Unknown prefix - skip
+            continue
+        }
+
+        // Handle schema references (no property access) like {{flowVariables}} or {{outputs}}
+        let expression: PropertyAccessShape | null
+        if (parsed.path === '') {
+            // Schema reference - tsRoot already contains full path
+            expression = createPropertyAccessFromPath(tsRoot, source)
+        } else {
+            // Property access like {{trigger.table_name}}
+            const fullPath = `${tsRoot}.${parsed.path}`
+            expression = createPropertyAccessFromPath(fullPath, source)
+        }
+
+        if (expression) {
+            pills.push({
+                matchStart,
+                matchEnd,
+                matchText: fullMatch,
+                expression,
+                type: 'semantic',
+            })
+        }
+    }
+
+    // Pills are already in order since we process matches sequentially
+    // No need to sort or remove duplicates - each match is processed once
+    return pills
+}
+
+/**
+ * Build a TemplateExpressionShape from a list of pills with their positions.
+ * Preserves all text (leading, in-between, trailing) from the original string.
+ *
+ * @param stringValue - Original string containing pills and text
+ * @param pills - List of pills with positions (in order)
+ * @param source - Source for shape creation
+ * @returns TemplateExpressionShape with all pills and text
+ */
+function buildTemplateExpression(stringValue: string, pills: PillInfo[], source: Record): TemplateExpressionShape {
+    const spans: TemplateSpanShape[] = []
+
+    // Head: text before first pill (leading text)
+    const firstPill = pills[0]
+    if (!firstPill) {
+        // Should never happen, but TypeScript wants this check
+        throw new Error('buildTemplateExpression called with empty pills array')
+    }
+    const literalText = stringValue.substring(0, firstPill.matchStart)
+
+    // Create spans for each pill (handles 1, 2, 20, or any number of pills)
+    for (let i = 0; i < pills.length; i++) {
+        const pill = pills[i]
+        if (!pill) {
+            continue
+        }
+
+        const nextPill = pills[i + 1]
+
+        // Text after this pill (in-between text or trailing text)
+        // - If there's a next pill: text between current and next pill
+        // - If this is the last pill: text after this pill to end of string (trailing)
+        const afterText = stringValue.substring(pill.matchEnd, nextPill ? nextPill.matchStart : stringValue.length)
+
+        spans.push(
+            new TemplateSpanShape({
+                source,
+                expression: pill.expression,
+                literalText: afterText,
+            })
+        )
+    }
+
+    return new TemplateExpressionShape({
+        source,
+        literalText, // head (leading text)
+        spans, // pills with in-between and trailing text
+    })
+}
+
+function transformDataPill(
+    stringValue: string,
+    uuidToIdentifierMap: Map<string, IdentifierShape>,
+    source: Record,
+    diagnostics: Diagnostics,
+    logger: Logger,
+    parameterName?: string
+): CallExpressionShape | TemplateExpressionShape | PropertyAccessShape | null {
+    // Special case: Schema references for SetFlowVariables/AssignSubflowOutputs
+    // {{flowVariables}} and {{outputs}} should remain as bare PropertyAccessShape without wrapping
+    if (stringValue === '{{flowVariables}}' || stringValue === '{{outputs}}') {
+        const allPills = extractAllPills(stringValue, uuidToIdentifierMap, source, diagnostics, parameterName)
+        if (allPills.length === 1 && allPills[0]?.expression.is(PropertyAccessShape)) {
+            return allPills[0].expression as PropertyAccessShape
+        }
+    }
+
+    // Extract label_cache from source Record and create type map
+    let labelCacheMap: Map<string, string> | undefined
+    try {
+        const labelCacheValue = source.get('label_cache')?.getValue()
+        if (labelCacheValue && typeof labelCacheValue === 'string') {
+            labelCacheMap = createLableCacheNameToTypeMap(labelCacheValue, logger)
+        }
+    } catch (_error) {
+        // If label_cache extraction fails, continue with default 'string' type
+        labelCacheMap = undefined
+    }
+
+    // Extract all pills (both UUID-based and semantic) from the string
+    const allPills = extractAllPills(stringValue, uuidToIdentifierMap, source, diagnostics, parameterName)
+
+    if (allPills.length === 0) {
+        return null // No pills found
+    }
+
+    // Check if single standalone pill (optimization)
+    const firstPill = allPills[0]
+    if (allPills.length === 1 && firstPill && firstPill.matchStart === 0 && firstPill.matchEnd === stringValue.length) {
+        // Single pill covering entire string - return PropertyAccessShape/IdentifierShape directly
+        return wrapWithWfaDataPillExpression(firstPill.expression, source, labelCacheMap, stringValue)
+    }
+
+    // Build template expression from all pills
+    const templateExpr = buildTemplateExpression(stringValue, allPills, source)
+
+    return wrapWithWfaDataPillExpression(templateExpr, source, labelCacheMap, stringValue)
+}
+
+/**
+ * Helper function to check if a UUID corresponds to a forEach flow logic instance
+ * @param uuid - The UUID to check
+ * @returns true if the UUID maps to a forEach logic instance, false otherwise
+ */
+function isForEachByUuid(uuid: string): boolean {
+    const record = uuidToRecordMap.get(uuid)
+    if (record && record.getTable() === 'sys_hub_flow_logic_instance_v2') {
+        const logicDefId = record.get('logic_definition')?.ifString()?.getValue()
+        if (logicDefId) {
+            const logicName = FlowLogicSysId.getLogicName(logicDefId)
+            return logicName === FLOW_LOGIC.FOR_EACH
+        }
+    }
+    return false
+}
+
+/**
+ * Checks if an identifier is actually a forEach parameter by inspecting its AST context.
+ * This prevents incorrectly stripping 'item' from property paths when 'item' is an actual field name.
+ *
+ * @param identifier - The IdentifierShape to check
+ * @param uuid - Optional UUID of the flow logic instance (used during XML→Fluent)
+ * @returns true if the identifier is a forEach parameter, false otherwise
+ */
+function isForEachParameter(identifier: IdentifierShape, uuid?: string): boolean {
+    const originalSource = identifier.getOriginalSource()
+    const identifierName = identifier.getName()
+
+    // Branch 1: XML → Fluent (originalSource is a Record)
+    if (!ts.Node.isNode(originalSource)) {
+        // Check if Record is a forEach logic definition
+        if (originalSource instanceof Record && originalSource.getTable() === 'sys_hub_flow_logic_v2') {
+            const logicDefId = originalSource.get('logic_definition')?.ifString()?.getValue()
+            if (logicDefId) {
+                const logicName = FlowLogicSysId.getLogicName(logicDefId)
+                return logicName === FLOW_LOGIC.FOR_EACH
+            }
+        }
+        // Fallback: check name pattern for backwards compatibility
+        return /^item(_\d+)?$/.test(identifierName)
+    }
+
+    // Branch 2: Fluent → XML (originalSource is a ts.Node)
+    // Try AST-based detection first
+    const arrowFn = (originalSource as ts.Node).getFirstAncestorByKind(ts.SyntaxKind.ArrowFunction)
+    if (arrowFn) {
+        const callExpr = arrowFn.getParentIfKind(ts.SyntaxKind.CallExpression)
+        if (callExpr) {
+            const callExprName = getCallExpressionName(callExpr)
+            const isThirdArgument = callExpr.getArguments()[2] === arrowFn
+            if (callExprName === FLOW_LOGIC.FOR_EACH && isThirdArgument) {
+                return true // AST check succeeded
+            }
+        }
+    }
+
+    // AST check failed or arrow function not found - use UUID fallback
+    return uuid ? isForEachByUuid(uuid) : false
+}
+
+/**
+ * Clean up config object by removing uuid (if it matches sys_id) and empty string fields
+ *
+ * @param configShape - The config ObjectShape to clean up
+ * @param instanceShape - The instance shape (used to get the source record)
+ * @returns Cleaned up config shape or original if no cleanup needed
+ */
+function cleanupConfigShape(configShape: Shape, instanceShape: Shape): Shape {
+    if (!(configShape instanceof ObjectShape)) {
+        return configShape
+    }
+
+    const configObj = configShape
+    const uuid = configObj.get('uuid')?.ifString()?.getValue()
+    const sysIdShape = configObj.get('$id')
+
+    if (!uuid || !sysIdShape) {
+        return configShape
+    }
+
+    // Get the sys_id value (could be a NowIdShape or string)
+    let sysId: string | undefined
+    const instanceSource = instanceShape.getSource()
+    if (sysIdShape.if(NowIdShape)) {
+        sysId = instanceSource instanceof Record ? String(instanceSource.getId().getValue()) : undefined
+    } else if (sysIdShape.isString()) {
+        sysId = sysIdShape.asString().getValue()
+    }
+
+    // Only clean up if uuid matches the sys_id (after converting uuid to sys_id format)
+    if (!sysId || uuidToSysId(uuid) !== sysId) {
+        return configShape
+    }
+
+    // Create new config without uuid property and empty string values
+    const configEntries = configObj.entries()
+    const newConfigProps: { [key: string]: Shape } = {}
+
+    for (const [key, value] of configEntries) {
+        // Skip uuid field
+        if (key === 'uuid') {
+            continue
+        }
+        // Skip fields with empty string values
+        if (value.isString() && value.asString().getValue() === '') {
+            continue
+        }
+        newConfigProps[key] = value
+    }
+
+    return new ObjectShape({
+        source: configObj.getSource(),
+        properties: newConfigProps,
+    })
+}
+
+const documentationRelationship: Relationship = {
+    descendant: true,
+    via: { name: 'name', element: 'element' },
+}
+
+const complexObjectRelationship: Relationship = {
+    descendant: true,
+    via: [complexObjectMatchesIoRecord],
+}
+
+const inputOutputRelationships: Relationship = {
+    via: 'model',
+    descendant: true,
+    relationships: {
+        sys_documentation: documentationRelationship,
+        sys_choice: {
+            via: { name: 'name', element: 'element' },
+            descendant: true,
+        },
+        sys_complex_object: complexObjectRelationship,
+    },
+}
+
+const variableRelationship: Relationship = {
+    via: 'model',
+    descendant: true,
+    relationships: {
+        sys_documentation: documentationRelationship,
+        sys_complex_object: complexObjectRelationship,
+    },
+}
+
+const legacyRelationship: Relationship = {
+    via: 'flow',
+    descendant: true,
+    relationships: {
+        sys_variable_value: {
+            via: 'document_key',
+            descendant: true,
+        },
+        sys_element_mapping: {
+            via: 'id',
+            descendant: true,
+        },
+        sys_hub_input_scripts: {
+            via: 'instance',
+            descendant: true,
+        },
+    },
+}
+
+const commonFlowRelationships: Relationships = {
+    sys_hub_flow_input: inputOutputRelationships,
+    sys_hub_flow_output: inputOutputRelationships,
+    sys_hub_flow_variable: variableRelationship,
+    sys_hub_flow_stage: {
+        via: 'flow',
+        descendant: true,
+    },
+    sys_hub_action_instance: legacyRelationship,
+    sys_hub_sub_flow_instance: {
+        ...legacyRelationship,
+        relationships: {
+            ...legacyRelationship.relationships,
+            sys_hub_sub_flow_instance_inputs: {
+                via: 'model',
+                descendant: true,
+            },
+        },
+    },
+    sys_hub_trigger_instance: legacyRelationship,
+    sys_hub_flow_logic: {
+        via: 'flow',
+        descendant: true,
+        relationships: {
+            sys_element_mapping: {
+                via: 'id',
+                descendant: true,
+            },
+            sys_hub_flow_logic_ext_input: {
+                via: 'model',
+                descendant: true,
+            },
+            sys_hub_input_scripts: {
+                via: 'instance',
+                descendant: true,
+            },
+        },
+    },
+    sys_hub_pill_compound: {
+        via: 'attached_to',
+        descendant: true,
+    },
+    sys_hub_alias_mapping: {
+        via: 'source_id',
+        descendant: true,
+    },
+    sys_flow_cat_variable_model: {
+        via: 'id',
+        descendant: true,
+        relationships: {
+            sys_flow_cat_variable: {
+                via: 'flow_catalog_model',
+                descendant: true,
+            },
+        },
+    },
+}
+
+const commonInstanceV2Relationships: Relationships = {
+    sys_hub_trigger_instance_v2: {
+        via: 'flow',
+        descendant: true,
+    },
+    sys_hub_action_instance_v2: {
+        via: 'flow',
+        descendant: true,
+    },
+    sys_hub_flow_logic_instance_v2: {
+        via: 'flow',
+        descendant: true,
+    },
+    sys_hub_sub_flow_instance_v2: {
+        via: 'flow',
+        descendant: true,
+    },
+}
+
+/**
+ * Checks if children array contains datapill references (e.g., "{{trigger.field}}")
+ */
+function childrenContainDatapills(children: ChildParameter[]): boolean {
+    if (!Array.isArray(children)) {
+        return false
+    }
+
+    for (const child of children) {
+        // Check if value contains datapill markers
+        if (isDataPill(child.value)) {
+            return true
+        }
+        // Recursively check nested children
+        if (child.children && Array.isArray(child.children) && childrenContainDatapills(child.children)) {
+            return true
+        }
+    }
+
+    return false
+}
+
+/**
+ * Builds the parameter object for a variable with schema information
+ */
+function buildParameterObject(
+    varName: string,
+    _children: ChildParameter[],
+    serviceNowValue: string,
+    logger: Logger
+): ParameterObject | { [key: string]: unknown } {
+    // Parse the ServiceNow formatted value to extract schema
+    try {
+        const parsed = JSON.parse(serviceNowValue)
+        if (!parsed.complexObjectSchema) {
+            return {}
+        }
+
+        // Extract the schema key (e.g., "FlowDesigner:FDxxx")
+        const schemaKeys = Object.keys(parsed.complexObjectSchema)
+        const mainSchemaKey = schemaKeys.find((key) => key.startsWith('FlowDesigner:') && !key.includes('.$'))
+
+        if (!mainSchemaKey) {
+            return {}
+        }
+
+        const schema = parsed.complexObjectSchema[mainSchemaKey]
+        const typeFacetsKey = `${mainSchemaKey}.$type_facets`
+        const typeFacets = parsed.complexObjectSchema[typeFacetsKey]?.SimpleMapFacet
+
+        if (!typeFacets) {
+            return {}
+        }
+
+        const typeFacetsObj = JSON.parse(typeFacets)
+
+        // Build parameter object
+        const parameter: ParameterObject = {
+            children: [],
+            type_label: typeFacetsObj.uiTypeLabel || 'Object',
+            id: typeFacetsObj.id || '',
+            label: typeFacetsObj.label || varName,
+            name: varName,
+            type: typeFacetsObj.uiType || 'object',
+            order: parseInt(typeFacetsObj.order || '0', 10),
+            extended: false,
+            mandatory: typeFacetsObj.mandatory === 'true',
+            readOnly: typeFacetsObj.read_only === 'true',
+            hint: typeFacetsObj.hint || '',
+            maxsize: parseInt(typeFacetsObj.max_length || '0', 10),
+            reference: '',
+            reference_display: '',
+            choiceOption: typeFacetsObj.choiceOption || '',
+            table: '',
+            columnName: '',
+            defaultValue: typeFacetsObj.default_value || '',
+            use_dependent: false,
+            fShowReferenceFinder: false,
+            local: false,
+            attributes: {},
+            ref_qual: '',
+            dependent_on: '',
+        }
+
+        // Copy attributes
+        for (const [key, value] of Object.entries(typeFacetsObj)) {
+            if (
+                ![
+                    'label',
+                    'type',
+                    'order',
+                    'mandatory',
+                    'read_only',
+                    'hint',
+                    'max_length',
+                    'choiceOption',
+                    'default_value',
+                ].includes(key)
+            ) {
+                parameter.attributes[key] = value
+            }
+        }
+
+        // Build children array from schema
+        for (const [fieldName, _fieldType] of Object.entries(schema)) {
+            if (fieldName.includes('.$') || fieldName === 'name$' || fieldName === COMPLEX_OBJECT_COLLECTION_FIELD) {
+                continue
+            }
+
+            const fieldFacetsKey = `${fieldName}.$field_facets`
+            const fieldFacets = schema[fieldFacetsKey]?.SimpleMapFacet
+
+            if (!fieldFacets) {
+                continue
+            }
+
+            const fieldFacetsObj = JSON.parse(fieldFacets)
+
+            // Build fieldFacetMap with mapped datapills
+            const fieldFacetMap: FieldFacetMap = {
+                choiceOption: fieldFacetsObj.choiceOption || '',
+                uiTypeLabel: fieldFacetsObj.uiTypeLabel || '',
+            }
+
+            // Check if this field has a datapill mapping
+            if (fieldFacetsObj.mapped) {
+                fieldFacetMap.mapped = fieldFacetsObj.mapped
+            }
+
+            const childParam: ChildParameter = {
+                fieldFacetMap,
+                value: fieldFacetsObj.default_value || '',
+                scriptActive: false,
+                script: {},
+                children: [],
+                uiDisplayType: fieldFacetsObj.uiType || '',
+                type_label: fieldFacetsObj.uiTypeLabel || '',
+                id: '',
+                label: fieldFacetsObj.label || fieldName,
+                name: fieldName,
+                type: fieldFacetsObj.uiType || 'string',
+                order: parseInt(fieldFacetsObj.order || '0', 10),
+                extended: false,
+                mandatory: fieldFacetsObj.mandatory === 'true',
+                readOnly: fieldFacetsObj.read_only === 'true',
+                hint: fieldFacetsObj.hint || '',
+                maxsize: parseInt(fieldFacetsObj.max_length || '0', 10),
+                reference: '',
+                reference_display: '',
+                choiceOption: fieldFacetsObj.choiceOption || '',
+                table: '',
+                columnName: '',
+                defaultValue: fieldFacetsObj.default_value || '',
+                defaultDisplayValue: '',
+                use_dependent: false,
+                fShowReferenceFinder: false,
+                local: false,
+                attributes: {},
+                ref_qual: '',
+                dependent_on: '',
+            }
+
+            parameter.children.push(childParam)
+        }
+
+        return parameter
+    } catch (e) {
+        logger.error(`Error building parameter object for variable ${varName}: ${e}`)
+        return {}
+    }
+}
+
+/**
+ * Enriches children array with parameter metadata from ServiceNow formatted value
+ */
+function enrichChildrenWithParameters(
+    children: ChildParameter[],
+    serviceNowValue: string,
+    logger: Logger,
+    clearValues = false
+): ChildParameter[] {
+    if (!children || !Array.isArray(children)) {
+        return children
+    }
+
+    try {
+        const parsed = JSON.parse(serviceNowValue)
+        if (!parsed.complexObjectSchema) {
+            return children
+        }
+
+        // Extract the schema
+        const schemaKeys = Object.keys(parsed.complexObjectSchema)
+        const mainSchemaKey = schemaKeys.find((key) => key.startsWith('FlowDesigner:') && !key.includes('.$'))
+
+        if (!mainSchemaKey) {
+            return children
+        }
+
+        const schema = parsed.complexObjectSchema[mainSchemaKey]
+
+        return children.map((child) => {
+            const fieldFacetsKey = `${child.name}.$field_facets`
+            const fieldFacets = schema[fieldFacetsKey]?.SimpleMapFacet
+
+            if (!fieldFacets) {
+                return child
+            }
+
+            const fieldFacetsObj = JSON.parse(fieldFacets)
+
+            const parameter: ParameterObject = {
+                children: [],
+                uiDisplayType: fieldFacetsObj.uiType || '',
+                type_label: fieldFacetsObj.uiTypeLabel || '',
+                id: '',
+                label: fieldFacetsObj.label || child.name,
+                name: child.name,
+                type: fieldFacetsObj.uiType || 'string',
+                order: parseInt(fieldFacetsObj.order || '0', 10),
+                extended: false,
+                mandatory: fieldFacetsObj.mandatory === 'true',
+                readOnly: fieldFacetsObj.read_only === 'true',
+                hint: fieldFacetsObj.hint || '',
+                maxsize: parseInt(fieldFacetsObj.max_length || '0', 10),
+                reference: '',
+                reference_display: '',
+                choiceOption: fieldFacetsObj.choiceOption || '',
+                table: '',
+                columnName: '',
+                defaultValue: fieldFacetsObj.default_value || '',
+                defaultDisplayValue: '',
+                use_dependent: false,
+                fShowReferenceFinder: false,
+                local: false,
+                attributes: {},
+                ref_qual: '',
+                dependent_on: '',
+            }
+
+            return {
+                ...child,
+                id: '',
+                value: clearValues ? '' : child.value,
+                displayValue: clearValues ? '' : child.displayValue || '',
+                parameter,
+                scriptActive: false,
+                script: {},
+            }
+        })
+    } catch (e) {
+        logger.error('Error enriching children with parameters:', e)
+        return children
+    }
+}
+
+/**
+ * Post-processes setFlowVariables values to apply ServiceNow complex object serialization.
+ * For variables with FlowObject/FlowArray types, replaces plain JSON with the proper
+ * ServiceNow format including $cv wrappers, schema, version, and serializationFormat.
+ *
+ * @param valuesJSON - The values array from the flow logic instance
+ * @param flowDefinitionRecord - The flow definition record containing variable definitions
+ * @returns Updated values array with complex objects properly serialized
+ */
+function postProcessSetFlowVariables(valuesJSON: ValuesJSON, flowDefinitionRecord: Record, logger: Logger): ValuesJSON {
+    if (!valuesJSON) {
+        return valuesJSON
+    }
+
+    // Helper function to process a single variable entry
+    const processVariable = (variable: VariableEntry): VariableEntry => {
+        // Check if this variable has children array
+        // Note: Empty arrays should still be processed to generate ServiceNow complex object format
+        if (!variable.children || !Array.isArray(variable.children)) {
+            return variable
+        }
+
+        // For variables with empty children, check if the value is an empty array that needs processing
+        const hasEmptyArrayValue = variable.children.length === 0 && variable.value === '[]'
+        if (variable.children.length === 0 && !hasEmptyArrayValue) {
+            return variable
+        }
+
+        // Check if children contain datapills
+        const hasDatapills = childrenContainDatapills(variable.children)
+
+        // If value is empty but has datapills, we need to get the ServiceNow format from variables array
+        if (!variable.value && hasDatapills) {
+            // Find the corresponding entry in the variables array
+            const correspondingVar = valuesJSON.variables?.find((v: VariableEntry) => v.name === variable.name)
+            if (correspondingVar?.value) {
+                // Build parameter using the variables array value (which has ServiceNow format)
+                const parameter = buildParameterObject(variable.name, variable.children, correspondingVar.value, logger)
+                // Enrich children with parameter objects
+                const enrichedChildren = enrichChildrenWithParameters(variable.children, correspondingVar.value, logger)
+                return {
+                    ...variable,
+                    children: enrichedChildren,
+                    parameter,
+                }
+            }
+            return variable
+        }
+
+        // If no value and no datapills, skip processing
+        if (!variable.value) {
+            return variable
+        }
+
+        // Try to parse the value to see if it's plain JSON (not already in ServiceNow format)
+        let parsedValue: unknown
+        try {
+            parsedValue = JSON.parse(variable.value)
+        } catch (_e) {
+            // If it's not valid JSON, leave it as is
+            logger.error('Error parsing value:', variable.value)
+            return variable
+        }
+
+        // Check if parsedValue is null or not an object
+        if (!parsedValue || typeof parsedValue !== 'object') {
+            return variable
+        }
+
+        // Check if it's already in ServiceNow format (has version, complexObjectSchema, etc.)
+        if ('version' in parsedValue || 'complexObjectSchema' in parsedValue || 'serializationFormat' in parsedValue) {
+            // Already in ServiceNow format, check if we need to add parameter
+            if (hasDatapills) {
+                const parameter = buildParameterObject(variable.name, variable.children, variable.value, logger)
+                // Enrich children with parameter objects
+                const enrichedChildren = enrichChildrenWithParameters(variable.children, variable.value, logger)
+                return {
+                    ...variable,
+                    children: enrichedChildren,
+                    parameter,
+                }
+            }
+            return variable
+        }
+
+        // Check if it's a plain object or array (potential FlowObject/FlowArray)
+        const isObject = parsedValue && typeof parsedValue === 'object' && !Array.isArray(parsedValue)
+        const isArray = Array.isArray(parsedValue)
+
+        if (!isObject && !isArray) {
+            return variable
+        }
+
+        // Use resolveComplexInput to get the proper ServiceNow format
+        const resolved = resolveComplexInput(
+            variable.name,
+            parsedValue,
+            flowDefinitionRecord,
+            'sys_hub_flow_variable'
+        ) as { value: unknown; internalType: string | undefined; children?: unknown[] }
+
+        if (resolved?.value && typeof resolved.value === 'string' && resolved.value !== variable.value) {
+            // Use children from resolveComplexInput if available (has correct child_name), otherwise use existing
+            const childrenToUse = (resolved.children as ChildParameter[]) || variable.children
+
+            // Build parameter object if children contain datapills
+            const parameter = hasDatapills
+                ? buildParameterObject(variable.name, childrenToUse, resolved.value, logger)
+                : {}
+
+            // Enrich children with parameter objects
+            const enrichedChildren = enrichChildrenWithParameters(childrenToUse, resolved.value, logger)
+
+            return {
+                ...variable,
+                value: resolved.value,
+                displayValue: resolved.value,
+                children: enrichedChildren,
+                parameter,
+            }
+        }
+
+        return variable
+    }
+
+    // Process variables array first
+    const updatedVariables =
+        valuesJSON.variables && Array.isArray(valuesJSON.variables)
+            ? valuesJSON.variables.map((v: VariableEntry) => processVariable(v))
+            : valuesJSON.variables
+
+    // Create intermediate object with updated variables for inputs processing
+    const intermediateJSON = {
+        ...valuesJSON,
+        variables: updatedVariables,
+    }
+
+    // Then process inputs array, which can now reference the updated variables
+    const updatedInputs =
+        intermediateJSON.inputs && Array.isArray(intermediateJSON.inputs)
+            ? intermediateJSON.inputs.map((v: VariableEntry) => {
+                  // Update the closure to use intermediateJSON instead of valuesJSON
+                  const hasDatapills = v.children && Array.isArray(v.children) && childrenContainDatapills(v.children)
+                  if (!v.value && hasDatapills && v.children) {
+                      const correspondingVar = intermediateJSON.variables?.find(
+                          (variable: VariableEntry) => variable.name === v.name
+                      )
+                      if (correspondingVar?.value) {
+                          const parameter = buildParameterObject(v.name, v.children, correspondingVar.value, logger)
+                          // Enrich children with parameter objects, clearing values for inputs array
+                          const enrichedChildren = enrichChildrenWithParameters(
+                              v.children,
+                              correspondingVar.value,
+                              logger,
+                              true
+                          )
+                          return { ...v, children: enrichedChildren, parameter }
+                      }
+                  }
+                  return processVariable(v)
+              })
+            : intermediateJSON.inputs
+
+    return {
+        ...intermediateJSON,
+        inputs: updatedInputs,
+    }
+}
+
+/**
+ * Post-processes assignSubflowOutputs to apply complex object serialization for FlowObject and FlowArray outputs.
+ * This is necessary because assignSubflowOutputs generates plain JSON for FlowObject/FlowArray values,
+ * but ServiceNow requires them to be in the complex object format with schemas.
+ *
+ * Similar to postProcessSetFlowVariables, but processes outputsToAssign array instead of variables array.
+ *
+ * @param valuesJSON - The values JSON containing outputsToAssign array
+ * @param subflowDefinitionRecord - The subflow definition record for schema lookup
+ * @returns Updated valuesJSON with properly formatted complex objects
+ */
+function postProcessAssignSubflowOutputs(
+    valuesJSON: ValuesJSON,
+    subflowDefinitionRecord: Record,
+    logger: Logger
+): ValuesJSON {
+    if (!valuesJSON || !valuesJSON.outputsToAssign || !Array.isArray(valuesJSON.outputsToAssign)) {
+        return valuesJSON
+    }
+
+    // Helper function to process a single output entry
+    const processOutput = (output: VariableEntry): VariableEntry => {
+        // Check if this output has children array
+        // Note: Empty arrays should still be processed to generate ServiceNow complex object format
+        if (!output.children || !Array.isArray(output.children)) {
+            return output
+        }
+
+        // For outputs with empty children, check if the value is an empty array that needs processing
+        const hasEmptyArrayValue = output.children.length === 0 && output.value === '[]'
+        if (output.children.length === 0 && !hasEmptyArrayValue) {
+            return output
+        }
+
+        // Check if children contain datapills
+        const hasDatapills = childrenContainDatapills(output.children)
+
+        // If no value and no datapills, skip processing
+        if (!output.value) {
+            return output
+        }
+
+        // Try to parse the value to see if it's plain JSON (not already in ServiceNow format)
+        let parsedValue: unknown
+        try {
+            parsedValue = JSON.parse(output.value)
+        } catch (_e) {
+            // If it's not valid JSON, leave it as is
+            logger.error('Error parsing value:', output.value)
+            return output
+        }
+
+        // Check if parsedValue is null or not an object
+        if (!parsedValue || typeof parsedValue !== 'object') {
+            return output
+        }
+
+        // Check if it's already in ServiceNow format (has version, complexObjectSchema, etc.)
+        if ('version' in parsedValue || 'complexObjectSchema' in parsedValue || 'serializationFormat' in parsedValue) {
+            // Already in ServiceNow format, check if we need to add parameter
+            if (hasDatapills) {
+                const parameter = buildParameterObject(output.name, output.children, output.value, logger)
+                // Enrich children with parameter objects
+                const enrichedChildren = enrichChildrenWithParameters(output.children, output.value, logger)
+                return {
+                    ...output,
+                    children: enrichedChildren,
+                    parameter,
+                }
+            }
+            return output
+        }
+
+        // Check if it's a plain object or array (potential FlowObject/FlowArray)
+        const isObject = parsedValue && typeof parsedValue === 'object' && !Array.isArray(parsedValue)
+        const isArray = Array.isArray(parsedValue)
+
+        if (!isObject && !isArray) {
+            // Not a complex type, leave as is
+            return output
+        }
+
+        // Use resolveComplexInput to get the proper ServiceNow format
+        // For subflow outputs, we look in sys_hub_flow_output table (same as flow outputs)
+        const resolved = resolveComplexInput(
+            output.name,
+            parsedValue,
+            subflowDefinitionRecord,
+            'sys_hub_flow_output'
+        ) as { value: unknown; internalType: string | undefined; children?: unknown[] }
+
+        if (resolved?.value && typeof resolved.value === 'string' && resolved.value !== output.value) {
+            // Use children from resolveComplexInput if available (has correct child_name), otherwise use existing
+            const childrenToUse = (resolved.children as ChildParameter[]) || output.children
+
+            // Build parameter object if children contain datapills
+            const parameter = hasDatapills
+                ? buildParameterObject(output.name, childrenToUse, resolved.value, logger)
+                : {}
+
+            // Enrich children with parameter objects
+            let enrichedChildren = enrichChildrenWithParameters(childrenToUse, resolved.value, logger)
+
+            // For assignSubflowOutputs, prepend parent output name to child names (dotted format)
+            // e.g., "tag" becomes "tags.tag"
+            enrichedChildren = enrichedChildren.map((child) => ({
+                ...child,
+                name: `${output.name}.${child.name}`,
+            }))
+
+            return {
+                ...output,
+                value: resolved.value,
+                displayValue: resolved.value,
+                children: enrichedChildren,
+                parameter,
+            }
+        }
+
+        return output
+    }
+
+    // Process outputsToAssign array
+    const updatedOutputs = valuesJSON.outputsToAssign.map((output: VariableEntry) => processOutput(output))
+
+    return {
+        ...valuesJSON,
+        outputsToAssign: updatedOutputs,
+    }
+}
+
+export const FlowDefinitionPlugin = Plugin.create({
+    name: 'FlowDefinitionPlugin',
+    records: {
+        sys_hub_flow: {
+            relationships: {
+                ...commonFlowRelationships,
+                ...commonInstanceV2Relationships,
+                sys_flow_record_trigger: {
+                    via: 'remote_trigger_id',
+                    inverse: true,
+                    descendant: true,
+                },
+                sys_trigger_runner_mapping: {
+                    via: 'identifier',
+                    descendant: true,
+                },
+                sys_flow_trigger_plan: {
+                    via: 'plan_id',
+                    descendant: true,
+                },
+                sys_flow_timer_trigger: {
+                    via: 'remote_trigger_id',
+                    inverse: true,
+                    descendant: true,
+                    relationships: {
+                        sys_flow_trigger_auto_script: {
+                            via: 'trigger',
+                            descendant: true,
+                        },
+                    },
+                },
+                sys_variable_value: {
+                    via: 'document_key',
+                    descendant: true,
+                },
+                sys_translated_text: {
+                    via: 'documentkey',
+                    descendant: true,
+                },
+                sys_hub_flow_snapshot: {
+                    via: 'parent_flow',
+                    descendant: true,
+                    relationships: {
+                        ...commonFlowRelationships,
+                        ...commonInstanceV2Relationships,
+                    },
+                },
+                sys_flow_subflow_plan: {
+                    via: 'plan_id',
+                    descendant: true,
+                },
+                sys_hub_flow_variable: {
+                    via: 'model',
+                    descendant: true,
+                },
+                sys_hub_flow_stage: {
+                    via: 'flow',
+                    descendant: true,
+                },
+            },
+            getUpdateName(record) {
+                return { success: true, value: `${record.getTable()}_${record.getId().getValue()}` }
+            },
+            toFile(record, { config, database }) {
+                return generateXML(record, { config, database })
+            },
+            async diff(existing, incoming, descendants, context) {
+                return deleteMultipleDiff(existing, incoming, descendants, context)
+            },
+            async toShape(record, { descendants, diagnostics, transform, database, logger }) {
+                let type = record.get('type')?.getValue()
+                if (!type) {
+                    logger.warn(`sys_hub_flow record has no type specified, defaulting to 'flow'`)
+                    type = 'flow'
+                } else if (type !== 'flow' && type !== 'subflow') {
+                    logger.error(
+                        `Skipping sys_hub_flow record: expected type 'flow' or 'subflow', but received '${type}'`
+                    )
+                    return { success: false }
+                }
+                const isSubflow = type === 'subflow'
+                const isFlow = type === 'flow'
+
+                const inputs = buildVariableShapes(descendants.query('sys_hub_flow_input'), descendants, logger)
+                const outputs = buildVariableShapes(descendants.query('sys_hub_flow_output'), descendants, logger)
+
+                //If Flow has unsupported datatypes for inputs/outputs, fallback to Record() API
+                if (inputs === undefined || outputs === undefined) {
+                    return { success: false }
+                }
+
+                const flowVariables = buildVariableShapes(descendants.query('sys_hub_flow_variable'), descendants)
+
+                //Check if flow has unsupported descendants are present
+                if (checkForUnsupportedFlowDescendants(descendants, record, logger)) {
+                    return { success: false }
+                }
+
+                const trigger = descendants.query('sys_hub_trigger_instance_v2')[0] // There will be only 1 trigger per flow
+
+                let triggerShape: CallExpressionShape | UndefinedShape = new UndefinedShape({
+                    source: record.getSource(),
+                })
+
+                if (isFlow) {
+                    if (trigger) {
+                        const triggerShapeResult = await transform.recordToShape(
+                            trigger,
+                            database,
+                            TriggerInstancePlugin
+                        )
+                        if (triggerShapeResult.success) {
+                            triggerShape = triggerShapeResult.value.as(CallExpressionShape)
+                        } else {
+                            return { success: false }
+                        }
+                    }
+                }
+
+                const actionInstances = descendants.query('sys_hub_action_instance_v2', {
+                    flow: record.getId().getValue(), // This is to skip snapshot records
+                })
+                const flowLogicInstance = descendants.query('sys_hub_flow_logic_instance_v2', {
+                    flow: record.getId().getValue(),
+                })
+                const subflowInstance = descendants.query('sys_hub_sub_flow_instance_v2', {
+                    flow: record.getId().getValue(),
+                })
+
+                const order = (rec: Record) => Number(rec.get('order')?.getValue())
+
+                // Build UUID map from ALL instances (actions, subflows, and flow logic)
+                const allInstances = [...actionInstances, ...subflowInstance, ...flowLogicInstance]
+                const recordToShapeMap = new Map<Record, Shape>()
+                const allInstanceShapes: Shape[] = []
+
+                for (const instance of allInstances) {
+                    const instanceShapeResult = await transform.recordToShape(
+                        instance,
+                        database,
+                        FlowInstancePlugin,
+                        FlowLogicPlugin
+                    )
+                    if (instanceShapeResult.success) {
+                        const shape = instanceShapeResult.value
+                        recordToShapeMap.set(instance, shape)
+                        allInstanceShapes.push(shape)
+                    }
+                }
+
+                // Build UUID map from all transformed shapes and their records
+                // Use recordToShapeMap to access ui_id from records (datapills reference ui_id, not $id)
+                const uuidToIdentifierMap = buildUuidToIdentifierMap(recordToShapeMap)
+
+                // For the flow body, only use top-level instances (those without parent_ui_id)
+                const topLevelInstances = allInstances
+                    .filter(
+                        (instance) =>
+                            !instance.get('parent_ui_id').isDefined() || instance.get('parent_ui_id').getValue() === ''
+                    )
+                    .sort((a, b) => order(a) - order(b))
+
+                const instanceShapes: Shape[] = []
+                for (const instance of topLevelInstances) {
+                    const shape = recordToShapeMap.get(instance)
+                    if (!shape) {
+                        logger.error(`Failed to find shape for instance ${instance.getId().getValue()}`)
+                        return { success: false }
+                    }
+                    instanceShapes.push(shape)
+                }
+
+                // Transform datapill expressions in instance props
+                // This section handles TWO types of datapills:
+                // 1. UUID-based pills: {{uuid.property}} → references to previous action/subflow instances (e.g., {{f56a03c1-18f6-4f7b-9c61-0d4ff472b334.name}} → actionInstance_1.name)
+                // 2. Semantic pills: {{trigger.property}}, {{flow_variable.name}} → references to flow parameters (e.g., {{trigger.table_name}} → params.trigger.table_name)
+
+                // Extract parameter name from the topmost ArrowFunction
+                // This allows us to use the actual parameter name instead of hardcoding "params"
+                let paramName = DEFAULT_PARAM_NAME // Default fallback
+                const firstInstance = instanceShapes[0]
+                if (firstInstance) {
+                    paramName = getArrowFunctionParamName(firstInstance) || DEFAULT_PARAM_NAME
+                }
+
+                // Process all instances (Action, Subflow, and Flow Logic) recursively
+                // This handles datapill transformation for all instance types and their nested children
+                instanceShapes.forEach((instanceShape: Shape, index) => {
+                    const result = processInstanceForDatapills(
+                        instanceShape,
+                        uuidToIdentifierMap,
+                        record,
+                        diagnostics,
+                        paramName,
+                        logger,
+                        processShapeForDatapills,
+                        cleanupConfigShape
+                    )
+
+                    // Only update if transformations occurred
+                    if (result.propsChanged) {
+                        instanceShapes[index] = result.shape
+                    }
+                })
+                const flowBody = new ArrowFunctionShape({
+                    source: record,
+                    parameters: [new IdentifierShape({ source: record, name: paramName })],
+                    statements: instanceShapes,
+                })
+
+                // Create the CallExpressionShape for both flow and subflow
+                const callExpression = new CallExpressionShape({
+                    source: record,
+                    callee: isSubflow ? SUBFLOW_API_NAME : FLOW_API_NAME,
+                    args: [
+                        record.transform(({ $ }) => ({
+                            $id: $.val(NowIdShape.from(record)),
+                            name: $,
+                            description: $.def(EMPTY_STRING),
+                            protection: $.from('sys_policy').def(EMPTY_STRING),
+                            runAs: $.from('run_as').def(RUN_AS_DEFAULT),
+                            runWithRoles: $.from('run_with_roles')
+                                .map((r) => {
+                                    const roles = r.ifString()?.getValue() ?? ''
+                                    return roles
+                                        .split(',')
+                                        .map((role) => role.trim())
+                                        .filter((role) => role)
+                                })
+                                .def([]),
+                            flowPriority: $.from('flow_priority')
+                                .map((p) => p.ifString()?.getValue() || FLOW_PRIORITY_DEFAULT)
+                                .def(FLOW_PRIORITY_DEFAULT),
+                            ...(isSubflow
+                                ? {
+                                      annotation: $.def(EMPTY_STRING),
+                                      category: $.def(EMPTY_STRING),
+                                      access: $.def(ACCESS_DEFAULT),
+                                      inputs: $.val(inputs).def({}),
+                                      outputs: $.val(outputs).def({}),
+                                  }
+                                : {}),
+                            flowVariables: $.val(flowVariables).def({}),
+                        })),
+                        ...(isFlow ? [triggerShape, flowBody] : [flowBody]),
+                    ],
+                })
+
+                // For subflows, wrap in VariableStatementShape with isExported true
+                // For flows, return the CallExpressionShape directly
+                if (isSubflow) {
+                    // Try to get the existing identifier from the record source, fallback to slugified name
+                    const flowName =
+                        getIdentifierFromRecord(record) ??
+                        slugifyString(String(record.get('internal_name')?.getValue() || record.get('name')?.getValue()))
+                    return {
+                        success: true,
+                        value: new VariableStatementShape({
+                            source: record,
+                            variableName: flowName,
+                            initializer: callExpression,
+                            isExported: true,
+                        }),
+                    }
+                } else {
+                    return {
+                        success: true,
+                        value: callExpression,
+                    }
+                }
+            },
+        },
+        sys_hub_flow_input: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_flow_output: {
+            coalesce: ['model', 'element'],
+        },
+        sys_complex_object: {
+            coalesce: ['name'],
+        },
+        sys_hub_flow_variable: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_flow_stage: {
+            coalesce: ['flow', 'value'],
+        },
+        sys_variable_value: {
+            coalesce: ['document_key', 'variable'],
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics, transform, logger }) {
+                const isFlow = callExpression.getCallee() === FLOW_API_NAME
+                const isSubflow = callExpression.getCallee() === SUBFLOW_API_NAME
+
+                if (!isFlow && !isSubflow) {
+                    return { success: false }
+                }
+
+                let flowConfiguration: ObjectShape,
+                    triggerInstance: Record | undefined,
+                    flowBody: ArrowFunctionShape | undefined
+                const relatedRecords: Record[] = []
+
+                if (isFlow) {
+                    flowConfiguration = callExpression.getArgument(0).asObject()
+
+                    const triggerInstanceCE = callExpression.getArgument(1)?.if(UndefinedShape)
+                        ? undefined
+                        : callExpression.getArgument(1)?.as(CallExpressionShape)
+                    const triggerInstanceRecord = triggerInstanceCE
+                        ? await transform.toRecord(triggerInstanceCE, TriggerInstancePlugin)
+                        : undefined
+                    triggerInstance = triggerInstanceRecord?.success ? triggerInstanceRecord.value : undefined
+
+                    flowBody = !callExpression.getArgument(2)?.if(UndefinedShape)
+                        ? callExpression.getArgument(2)?.as(ArrowFunctionShape)
+                        : undefined
+                } else {
+                    flowConfiguration = callExpression.getArgument(0).asObject()
+                    flowBody = !callExpression.getArgument(1)?.if(UndefinedShape)
+                        ? callExpression.getArgument(1)?.as(ArrowFunctionShape)
+                        : undefined
+                }
+
+                const roles = flowConfiguration.get('runWithRoles').ifArray()?.getElements() ?? []
+                const flowDefinitionRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_flow',
+                    explicitId: flowConfiguration.get('$id'),
+                    properties: flowConfiguration.transform(({ $ }) => ({
+                        name: $,
+                        internal_name: $.from('name').map((n) => slugifyString(n.getValue())),
+                        annotation: $.def(EMPTY_STRING),
+                        description: $.def(EMPTY_STRING),
+                        access: $.def(ACCESS_DEFAULT),
+                        category: $.def(EMPTY_STRING),
+                        sys_policy: $.from('protection').def(EMPTY_STRING),
+                        run_as: $.from('runAs').def(RUN_AS_DEFAULT),
+                        generation_source: $.def(GENERATION_SOURCE),
+                        show_draft_actions: $.def(BOOLEAN_FALSE_STRING),
+                        flow_priority: $.from('flowPriority').def(FLOW_PRIORITY_DEFAULT),
+                        run_with_roles: $.val(
+                            Array.from(
+                                new Set(roles.map((r) => r.ifRecord()?.getId().getValue() ?? r.getValue()))
+                            ).join(',')
+                        ),
+                        active: $.val(false),
+                        status: $.val(FLOW_STATUS_DRAFT),
+                        type: isFlow ? $.def(FLOW_TYPE_FLOW) : $.def(FLOW_TYPE_SUBFLOW),
+                        version: $.def(FLOW_VERSION),
+                        label_cache: $.val('[]'),
+                    })),
+                })
+                if (isFlow && triggerInstance) {
+                    // Push updated trigger instance record
+                    relatedRecords.push(
+                        triggerInstance.merge({
+                            flow: flowDefinitionRecord.getId().getValue(),
+                        })
+                    )
+                }
+
+                // ------------------------------------------------------------
+                // Handle FlowVariables() argument (flow-level variables)
+                // Each variable becomes a separate sys_hub_flow_variable record
+                // ------------------------------------------------------------
+                if (flowConfiguration.has('flowVariables')) {
+                    const variablesConfig = flowConfiguration.get('flowVariables').asObject()
+
+                    // --------------------------------------------------------------------
+                    // Validate each variable is created using a supported FlowValueType
+                    // --------------------------------------------------------------------
+                    variablesConfig.entries().forEach(([key, value]) => {
+                        if (!value.if(CallExpressionShape)) {
+                            diagnostics.error(
+                                value.getOriginalNode(),
+                                `flowVariables.${key} is not a valid variable expression.`
+                            )
+                            return
+                        }
+                        // Use the shared validation function
+                        validateFlowVariableCall(value.as(CallExpressionShape), `flowVariables.${key}`, diagnostics)
+                    })
+
+                    const flowVarRecords = await processFlowVariables(
+                        variablesConfig,
+                        flowDefinitionRecord,
+                        factory,
+                        diagnostics
+                    )
+                    relatedRecords.push(...flowVarRecords)
+                }
+
+                if (isSubflow) {
+                    // Process subflow inputs and outputs
+                    const inputsConfig = flowConfiguration.get('inputs').ifObject()?.asObject()
+                    const inputRecords = await processFlowInputs(
+                        inputsConfig,
+                        flowDefinitionRecord,
+                        factory,
+                        diagnostics
+                    )
+                    relatedRecords.push(...inputRecords)
+
+                    const outputsConfig = flowConfiguration.get('outputs').ifObject()?.asObject()
+                    const outputRecords = await processFlowOutputs(
+                        outputsConfig,
+                        flowDefinitionRecord,
+                        factory,
+                        diagnostics
+                    )
+                    relatedRecords.push(...outputRecords)
+                }
+
+                const allInstances = flowBody?.getStatements().filter((stmt) => !(stmt instanceof UndefinedShape))
+
+                // Create lookup maps for flow variables and subflow inputs
+                const flowVarDefMap = createDefinitionMap(relatedRecords, 'sys_hub_flow_variable')
+                const subflowInputDefMap = createDefinitionMap(relatedRecords, 'sys_hub_flow_input')
+
+                // Extract trigger data to be used during label cache generation
+                const triggerInstanceShape = isFlow
+                    ? callExpression.getArgument(1)?.if(UndefinedShape)
+                        ? undefined
+                        : callExpression.getArgument(1)?.as(CallExpressionShape)
+                    : undefined
+
+                const triggerData = triggerInstanceShape
+                    ? {
+                          inputs: extractTriggerInputs(triggerInstanceShape),
+                          outputs: extractTriggerOutputs(triggerInstanceShape),
+                      }
+                    : undefined
+                // Map to aggregate data pill metadata for label_cache
+                // biome-ignore lint/suspicious/noExplicitAny: Dynamic label cache entries
+                let labelCacheMap = new Map<string, any>()
+                // Map to track forEach instances with their metadata for label generation
+                let forEachMetadataMap = new Map<string, { stepNumber: number; tableName: string | null }>()
+
+                let order = 1
+                for (const [, v] of (allInstances ?? []).entries()) {
+                    // Validate trigger placement: triggers must be the second argument to Flow(), not in the body
+                    const callExpr = v instanceof VariableStatementShape ? v.getInitializer() : v
+                    if (callExpr instanceof CallExpressionShape && callExpr.getCallee() === TRIGGER_INSTANCE_API_NAME) {
+                        diagnostics.error(
+                            callExpr.getOriginalNode(),
+                            'Trigger instances must be passed as the second argument to Flow(), not inside the flow body'
+                        )
+                        continue
+                    }
+                    const instanceRecord = await getRecordFromFlowInstaceShape(v, transform)
+
+                    if (instanceRecord) {
+                        instanceRecord.flat().forEach((rec) => {
+                            // For subflow instances, values will be in subflow_inputs, for other instances (action/flow logic) it will be in values
+                            const inputsKey =
+                                rec.getTable() === 'sys_hub_sub_flow_instance_v2' ? 'subflow_inputs' : 'values'
+                            let valuesJSON: ValuesJSON =
+                                (rec.get(inputsKey)?.getValue() as ValuesJSON) || ({} as ValuesJSON)
+
+                            // Post-process setFlowVariables to apply complex object serialization
+                            if (rec.getTable() === 'sys_hub_flow_logic_instance_v2') {
+                                const valuesObj = valuesJSON
+
+                                // Process setFlowVariables
+                                if (valuesObj.variables && valuesObj.variables.length > 0) {
+                                    // Create a record-like object that includes all related records for resolveComplexInput
+                                    // resolveComplexInput calls .flat() on the parentDef to get all records
+                                    const combinedRecord = {
+                                        ...flowDefinitionRecord,
+                                        flat: () => [...flowDefinitionRecord.flat(), ...relatedRecords],
+                                    } as Record
+                                    valuesJSON = postProcessSetFlowVariables(valuesJSON, combinedRecord, logger)
+                                }
+
+                                // Process assignSubflowOutputs
+                                if (valuesObj.outputsToAssign && valuesObj.outputsToAssign.length > 0) {
+                                    // Create a record-like object that includes all related records for resolveComplexInput
+                                    // resolveComplexInput calls .flat() on the parentDef to get all records
+                                    const combinedRecord = {
+                                        ...flowDefinitionRecord,
+                                        flat: () => [...flowDefinitionRecord.flat(), ...relatedRecords],
+                                    } as Record
+                                    valuesJSON = postProcessAssignSubflowOutputs(valuesJSON, combinedRecord, logger)
+                                }
+                            }
+
+                            const recUiId = rec.get('ui_id').asString()?.getValue()
+                            // Extract data pills from values array and track their usage
+                            labelCacheMap = extractDataPillsFromValuesArray(valuesJSON, recUiId, labelCacheMap)
+                            let finalOrder = order.toString()
+
+                            const previousOrder = order - 1
+                            if (previousOrder > 0) {
+                                const previousRecord = relatedRecords.find(
+                                    (r) => r.get('order')?.getValue() === previousOrder.toString()
+                                )
+
+                                if (
+                                    previousRecord &&
+                                    previousRecord.get('logic_definition')?.getValue() === DO_IN_PARALLEL_BLOCK_SYS_ID
+                                ) {
+                                    finalOrder = `${previousOrder}${PARALLEL_ORDER_SEPARATOR}${order}`
+                                }
+                            }
+                            // Update forEach metadata for label cache generation
+                            forEachMetadataMap = updateForEachMetadata(rec, order, flowVarDefMap, forEachMetadataMap)
+                            labelCacheMap = extractLabelCache(
+                                flowVarDefMap,
+                                subflowInputDefMap,
+                                relatedRecords,
+                                labelCacheMap,
+                                triggerData,
+                                forEachMetadataMap
+                            )
+
+                            relatedRecords.push(
+                                rec.merge({
+                                    flow: flowDefinitionRecord.getId().getValue(),
+                                    order: finalOrder,
+                                    [inputsKey]: gzipSync(JSON.stringify(valuesJSON)).toString('base64'),
+                                })
+                            )
+                            order++
+                        })
+                    } else {
+                        diagnostics.error(
+                            v.getOriginalNode(),
+                            `Unknown instance type in Flow ${flowDefinitionRecord.getId().getValue()}`
+                        )
+                    }
+                }
+
+                const labelCacheData = Array.from(labelCacheMap.values())
+                const flowDefWithMetadata =
+                    labelCacheData.length > 0
+                        ? flowDefinitionRecord.merge({
+                              label_cache: JSON.stringify(labelCacheData),
+                          })
+                        : flowDefinitionRecord
+
+                return {
+                    success: true,
+                    value: flowDefWithMetadata.with(...relatedRecords),
+                }
+            },
+        },
+    ],
+})