@servicenow/sdk-build-plugins 4.5.0 → 4.6.0

package/src/flow/plugins/step-instance-plugin.ts

@@ -1,16 +1,43 @@
 import {
     Plugin,
     CallExpressionShape,
+    DurationShape,
+    IdentifierShape,
     ObjectShape,
+    PropertyAccessShape,
+    TemplateExpressionShape,
+    TemplateValueShape,
     type Record as BuildRecord,
     type Factory,
     type Shape,
     type Source,
+    type Diagnostics,
 } from '@servicenow/sdk-build-core'
-import type { NowIdShape } from '../../now-id-plugin'
-import { sysIdToUuid } from '../utils/utils'
+import { NowIdShape } from '../../now-id-plugin'
+import { getBuiltInStepIdentifier, sysIdToUuid } from '../utils/utils'
 import { COLUMN_API_TO_TYPE } from '../../column/column-helper'
-import { ACTION_STEP_INSTANCE_API_NAME } from '../utils/flow-constants'
+import {
+    ACTION_STEP_INSTANCE_API_NAME,
+    BUILT_IN_STEP_DEFINITIONS,
+    BUILT_IN_STEP_NAME_TO_SYSID,
+    BUILT_IN_STEP_PREFIX,
+    buildExtVarAttributes,
+    getVarEntryName,
+    getVarEntryType,
+    FLOW_OBJECT_API_NAME,
+    FLOW_ARRAY_API_NAME,
+} from '../utils/flow-constants'
+import { normalizeInputValue } from './flow-instance-plugin'
+import { ApprovalRulesShape, ApprovalDueDateShape } from '../utils/flow-shapes'
+import { createSdkDocEntry } from '../../utils'
+import {
+    generateSchemaFromObject,
+    getComplexObjectAttributes,
+    formatComplexObjectAttributes,
+} from '../utils/complex-objects'
+
+import { PillShape } from '../utils/data-pill-shapes'
+import { findAncestorByCalleeName } from '../utils/utils'
 
 // Error handling type mapping: string to number
 const ERROR_HANDLING_TYPE_MAP: Record<string, number> = {
@@ -18,6 +45,148 @@ const ERROR_HANDLING_TYPE_MAP: Record<string, number> = {
     dont_stop_the_action: 2,
 }
 
+/**
+ * Resolves a TemplateValue field shape to a datapill string (e.g., "{{action.desc|string}}").
+ * Handles two cases:
+ * 1. Already resolved PillShape — call getValue() directly
+ * 2. Unresolved wfa.dataPill() CallExpressionShape — extract pill info from arguments
+ * @param cidMap - Optional map of step variable name → CID for direct lookup (avoids AST walking)
+ * Returns undefined if the field is not a datapill.
+ */
+function resolveFieldToPillString(fieldShape: Shape, cidMap?: Map<string, string>): string | undefined {
+    // Case 1: Already a PillShape (e.g., processed by the datapill plugin)
+    if (fieldShape instanceof PillShape) {
+        return fieldShape.getValue()
+    }
+
+    // Case 2: Unresolved wfa.dataPill(expression, type) CallExpressionShape
+    if (fieldShape instanceof CallExpressionShape) {
+        const callee = fieldShape.getCallee()
+        if (callee !== 'wfa.dataPill') {
+            return undefined
+        }
+
+        const typeArg = fieldShape.getArgument(1)
+
+        // Extract property path — try Shape API first, then AST node directly
+        const propertyNames: string[] = []
+        const expressionArg = fieldShape.getArgument(0, false) // 0, false
+        if (expressionArg instanceof PropertyAccessShape) {
+            expressionArg.getElements().forEach((el: Shape) => {
+                if (el instanceof IdentifierShape) {
+                    propertyNames.push(el.getName())
+                }
+            })
+        }
+
+        if (propertyNames.length < 2) {
+            return undefined
+        }
+
+        let prefix = 'action'
+        let pathParts: string[]
+
+        if (propertyNames[1] === 'inputs') {
+            // params.inputs.xxx → action pill
+            const originalNode = fieldShape.getOriginalNode?.()
+            if (originalNode) {
+                const actionAncestor = findAncestorByCalleeName(originalNode, 'Action')
+                prefix = actionAncestor ? 'action' : 'subflow'
+            }
+            pathParts = propertyNames.slice(2)
+        } else {
+            // Could be a step variable reference: create_record_step.record.short_description
+            // Resolve CID via cidMap lookup (O(1))
+            const varName = propertyNames[0]
+            const stepCid = varName ? cidMap?.get(varName) : undefined
+            if (stepCid) {
+                prefix = `step[${stepCid}]`
+                pathParts = propertyNames.slice(1)
+            } else {
+                // Cannot resolve step CID — return undefined so the caller can handle the failure
+                return undefined
+            }
+        }
+
+        const dataType = typeArg?.ifString()?.getValue()
+        const typeSuffix = dataType ? `|${dataType}` : ''
+
+        return `{{${prefix}.${pathParts.join('.')}${typeSuffix}}}`
+    }
+
+    // Case 3: Already a resolved pill string
+    const val = fieldShape.getValue()
+    if (typeof val === 'string' && val.startsWith('{{') && val.endsWith('}}')) {
+        return val
+    }
+
+    return undefined
+}
+
+/**
+ * Extracts pill type annotations from a pill string and stores them in the pillTypeMap.
+ * Captures types from both step pills ({{step[CID].path|type}}) and action pills
+ * ({{action.path|type}}). The "|type" portion is captured before it gets stripped
+ * for the element_mapping value. The collected types are used later when building the label_cache.
+ */
+const STEP_PILL_TYPE_REGEX = /\{\{step\[([^\]]+)\]\.([^|}]+)(?:\|([^}]+))?\}\}/g
+const ACTION_PILL_TYPE_REGEX = /\{\{action\.([^|}]+)(?:\|([^}]+))?\}\}/g
+function collectPillTypes(pillString: string, pillTypeMap?: Map<string, string>): void {
+    if (!pillTypeMap) {
+        return
+    }
+    for (const match of pillString.matchAll(STEP_PILL_TYPE_REGEX)) {
+        const [, cid, pillPath, dataType] = match
+        if (cid && pillPath && dataType) {
+            pillTypeMap.set(`${cid}::${pillPath}`, dataType)
+        }
+    }
+    for (const match of pillString.matchAll(ACTION_PILL_TYPE_REGEX)) {
+        const [, path, dataType] = match
+        if (path && dataType) {
+            pillTypeMap.set(`action::${path}`, dataType)
+        }
+    }
+}
+
+/**
+ * Strips the |type suffix from a pill string.
+ * e.g., "{{action.desc|string}}" → "{{action.desc}}"
+ *
+ * Note: This is called on individual pill strings (from resolveFieldToPillString),
+ * never on concatenated multi-pill strings — so no `g` flag is needed.
+ */
+function stripPillType(pill: string): string {
+    return pill.replace(/\|[^}]+/, '')
+}
+
+/**
+ * Resolves a TemplateExpressionShape into a concatenated string, replacing
+ * datapill spans with their pill strings (type-stripped) and collecting pill types.
+ * Returns the resolved string and whether any pills were found.
+ */
+function resolveTemplateExpression(
+    templateShape: TemplateExpressionShape,
+    cidMap?: Map<string, string>,
+    pillTypeMap?: Map<string, string>
+): { result: string; hasPills: boolean } {
+    let result = templateShape.getLiteralText()
+    let hasPills = false
+    for (const span of templateShape.getSpans()) {
+        const expr = span.getExpression()
+        const pillStr = resolveFieldToPillString(expr as Shape, cidMap)
+        if (pillStr) {
+            collectPillTypes(pillStr, pillTypeMap)
+            result += stripPillType(pillStr)
+            hasPills = true
+        } else {
+            result += String(expr.getValue?.() ?? '')
+        }
+        result += span.getLiteralText()
+    }
+    return { result, hasPills }
+}
+
 /**
  * StepInstanceShape represents a step instance within a custom action's body
  * This class handles the shape transformation for step instances
@@ -29,6 +198,10 @@ export class StepInstanceShape extends CallExpressionShape {
     private stepLabel: string
     private inputs: ObjectShape | undefined
     private inputDefinitions: ObjectShape | undefined
+    /** Map of step variable name → CID, set by ActionDefinitionPlugin for step pill resolution in Action() bodies */
+    private _cidMap?: Map<string, string>
+    /** Map of "CID::pillPath" → dataType, populated during toRecord for label_cache type propagation */
+    private _pillTypeMap?: Map<string, string>
 
     constructor(args: {
         source: Source
@@ -41,7 +214,7 @@ export class StepInstanceShape extends CallExpressionShape {
         inputDefinitions?: ObjectShape
     }) {
         const { source, sysId, config, stepDefinitionSysId, stepLabel, inputs, inputDefinitions } = args
-        super({ source, callee: 'StepInstance', args: [sysId, config, stepDefinitionSysId] })
+        super({ source, callee: 'wfa.actionStep', args: [sysId, config, stepDefinitionSysId] })
         this.config = config
         this.sysId = sysId
         this.stepDefinitionSysId = stepDefinitionSysId
@@ -73,11 +246,27 @@ export class StepInstanceShape extends CallExpressionShape {
     getInputDefinitions(): ObjectShape | undefined {
         return this.inputDefinitions
     }
+
+    setCidMap(cidMap: Map<string, string>): void {
+        this._cidMap = cidMap
+    }
+
+    getCidMap(): Map<string, string> | undefined {
+        return this._cidMap
+    }
+
+    setPillTypeMap(pillTypeMap: Map<string, string>): void {
+        this._pillTypeMap = pillTypeMap
+    }
+
+    getPillTypeMap(): Map<string, string> | undefined {
+        return this._pillTypeMap
+    }
 }
 
 export const StepInstancePlugin = Plugin.create({
     name: 'StepInstancePlugin',
-    docs: [],
+    docs: [createSdkDocEntry('wfa.actionStep', ['sys_hub_step_instance'])],
     shapes: [
         {
             shape: CallExpressionShape,
@@ -99,12 +288,8 @@ export const StepInstancePlugin = Plugin.create({
 
                 const [stepDefinition, stepInstanceConfig, inputs] = args
 
-                // Validate first argument is a StepDefinition
-                if (
-                    !(stepDefinition instanceof CallExpressionShape) ||
-                    stepDefinition.getCallee() !== 'ActionStepDefinition'
-                ) {
-                    diagnostics.error(callExpression, 'Expected first argument to be a ActionStepDefinition')
+                if (!stepDefinition) {
+                    diagnostics.error(callExpression, 'Missing step definition argument')
                     return { success: false }
                 }
 
@@ -120,7 +305,51 @@ export const StepInstancePlugin = Plugin.create({
                     return { success: false }
                 }
 
-                const stepConfig = stepDefinition.getArgument(0).asObject()
+                let stepDefinitionSysId: string
+                let stepLabel: string
+                let inputDefinitions: ObjectShape | undefined
+
+                // First argument can be a string (built-in step name), IdentifierShape (actionStep.xxx),
+                // or ActionStepDefinition() call
+                const stepNameValue = stepDefinition.ifString()?.getValue()
+                if (stepNameValue) {
+                    // Built-in step referenced by name string
+                    stepDefinitionSysId = BUILT_IN_STEP_NAME_TO_SYSID[stepNameValue] ?? ''
+                    stepLabel = stepNameValue
+                    if (!stepDefinitionSysId) {
+                        diagnostics.error(callExpression, `Unknown built-in step type '${stepNameValue}'`)
+                        return { success: false }
+                    }
+                } else if (stepDefinition instanceof IdentifierShape) {
+                    // Built-in step referenced via actionStep.xxx identifier
+                    const identifierName = stepDefinition.getName()
+                    const prefix = `${BUILT_IN_STEP_PREFIX}.`
+                    const resolvedName = identifierName.startsWith(prefix)
+                        ? identifierName.slice(prefix.length)
+                        : identifierName
+                    stepDefinitionSysId = BUILT_IN_STEP_NAME_TO_SYSID[resolvedName] ?? ''
+                    stepLabel = resolvedName
+                    if (!stepDefinitionSysId) {
+                        diagnostics.error(callExpression, `Unknown built-in step type '${identifierName}'`)
+                        return { success: false }
+                    }
+                } else if (
+                    stepDefinition instanceof CallExpressionShape &&
+                    stepDefinition.getCallee() === 'ActionStepDefinition'
+                ) {
+                    // Custom step definition
+                    const stepConfig = stepDefinition.getArgument(0).asObject()
+                    stepDefinitionSysId = stepConfig.get('$id')?.getValue() as string
+                    stepLabel = stepConfig.get('name')?.getValue() as string
+                    inputDefinitions = stepConfig.get('inputs')?.ifObject()?.asObject()
+                } else {
+                    diagnostics.error(
+                        callExpression,
+                        'Expected first argument to be a step type name string, actionStep.xxx identifier, or ActionStepDefinition'
+                    )
+                    return { success: false }
+                }
+
                 const shapeArgs: {
                     source: Source
                     config: ObjectShape
@@ -133,10 +362,10 @@ export const StepInstancePlugin = Plugin.create({
                     source: callExpression,
                     sysId: stepInstanceConfig.get('$id')?.getValue() as NowIdShape | Shape,
                     config: stepInstanceConfig,
-                    stepDefinitionSysId: stepConfig.get('$id')?.getValue() as string,
-                    stepLabel: stepConfig.get('name')?.getValue() as string,
-                    inputDefinitions: stepConfig.get('inputs')?.asObject(),
+                    stepDefinitionSysId,
+                    stepLabel,
                     inputs: inputs,
+                    ...(inputDefinitions ? { inputDefinitions } : {}),
                 }
 
                 return {
@@ -148,10 +377,11 @@ export const StepInstancePlugin = Plugin.create({
         {
             shape: StepInstanceShape,
             fileTypes: ['fluent'],
-            async toRecord(callExpression, { factory }) {
+            async toRecord(callExpression, { factory, diagnostics }) {
                 const stepInstanceRecord = await buildStepInstanceRecord({
                     callExpression,
                     factory,
+                    diagnostics,
                     values: callExpression.getInputs() as ObjectShape,
                     sysId: callExpression.getSysId(),
                     stepDefinitionSysId: callExpression.getStepDefinitionSysId(),
@@ -169,6 +399,12 @@ export const StepInstancePlugin = Plugin.create({
         sys_hub_step_ext_output: {
             coalesce: ['model', 'element'],
         },
+        sys_complex_object: {
+            coalesce: ['name'],
+        },
+        sys_element_mapping: {
+            coalesce: ['field', 'id'],
+        },
         sys_hub_step_instance: {
             relationships: {
                 sys_variable_value: {
@@ -192,87 +428,137 @@ export const StepInstancePlugin = Plugin.create({
                     descendant: true,
                 },
             },
-            // toShape(record, { descendants, diagnostics }) {
-            //     // Get the step definition reference
-            //     const stepDefinitionRecords = descendants.query('sys_flow_step_definition')
-            //     if (stepDefinitionRecords.length === 0) {
-            //         diagnostics.error(record, 'Could not find step definition for step instance')
-            //         return { success: false }
-            //     }
-
-            //     const stepDefinition = stepDefinitionRecords[0]
-            //     if (!stepDefinition) {
-            //         diagnostics.error(record, 'Step definition is undefined')
-            //         return { success: false }
-            //     }
-
-            //     // Build the config object from sys_variable_value records
-            //     const variableValues = descendants.query('sys_variable_value')
-            //     const configObj: globalThis.Record<string, any> = {}
-
-            //     for (const varValue of variableValues) {
-            //         const variableSysId = varValue.get('variable')?.asString()?.getValue()
-            //         const value = varValue.get('value')?.asString()?.getValue()
-
-            //         // Find the matching input definition to get the element name
-            //         const inputRecords = descendants.query('sys_flow_step_definition_input', { sysId: variableSysId })
-            //         if (inputRecords.length > 0) {
-            //             const elementName = inputRecords[0]?.get('element')?.asString()?.getValue()
-            //             if (elementName) {
-            //                 // Try to parse JSON values, otherwise use as string
-            //                 try {
-            //                     configObj[elementName] = JSON.parse(value || '')
-            //                 } catch {
-            //                     configObj[elementName] = value
-            //                 }
-            //             }
-            //         }
-            //     }
-
-            //     // Add error_handling_type and label from the step instance record itself
-            //     const errorHandlingType = record.get('error_handling_type')?.asNumber()?.getValue()
-            //     if (errorHandlingType !== undefined && errorHandlingType !== 1) {
-            //         configObj['error_handling_type'] = errorHandlingType
-            //     }
-
-            //     const label = record.get('label')?.asString()?.getValue()
-            //     const stepName = stepDefinition.get('name')?.asString()?.getValue()
-            //     if (label && label !== stepName) {
-            //         configObj['label'] = label
-            //     }
-
-            //     // Create the StepDefinition CallExpressionShape reference
-            //     const stepDefinitionShape = new CallExpressionShape({
-            //         source: stepDefinition,
-            //         callee: 'StepDefinition',
-            //         args: [
-            //             stepDefinition.transform(({ $ }) => ({
-            //                 $id: $.val(NowIdShape.from(stepDefinition)),
-            //                 name: $,
-            //             })),
-            //         ],
-            //     })
-
-            //     // Create the config ObjectShape
-            //     const configProperties: globalThis.Record<string, any> = {}
-            //     for (const [key, value] of Object.entries(configObj)) {
-            //         configProperties[key] = value
-            //     }
-
-            //     const configShape = new ObjectShape({
-            //         source: record,
-            //         properties: configProperties,
-            //     })
-
-            //     return {
-            //         success: true,
-            //         value: new CallExpressionShape({
-            //             source: record,
-            //             callee: 'StepInstance',
-            //             args: [stepDefinitionShape, NowIdShape.from(record), configShape],
-            //         }),
-            //     }
-            // },
+            toShape(record, { descendants, logger }) {
+                // Skip step instances that belong to an action definition —
+                // those are handled by ActionDefinitionPlugin's toShape for Action() definitions
+                const actionRef = record.get('action')?.asString()?.getValue()
+                if (actionRef) {
+                    return { success: false }
+                }
+
+                const stepDefinitionRecords = descendants.query('sys_flow_step_definition')
+                const variableValues = descendants.query('sys_variable_value')
+                const configObj: globalThis.Record<string, unknown> = {}
+
+                let stepDefinitionShape: CallExpressionShape | IdentifierShape | string
+                let stepName: string | undefined
+
+                if (stepDefinitionRecords.length > 0) {
+                    // Custom step definition found in descendants
+                    const stepDefinition = stepDefinitionRecords[0]
+                    if (!stepDefinition) {
+                        logger.warn('Step definition is undefined')
+                        return { success: false }
+                    }
+
+                    stepName = stepDefinition.get('name')?.asString()?.getValue()
+
+                    // Resolve variable values using input definition records from descendants
+                    for (const varValue of variableValues) {
+                        const variableSysId = varValue.get('variable')?.asString()?.getValue()
+                        const value = varValue.get('value')?.asString()?.getValue()
+
+                        const inputRecords = descendants.query('sys_flow_step_definition_input', {
+                            sysId: variableSysId,
+                        })
+                        if (inputRecords.length > 0) {
+                            const elementName = inputRecords[0]?.get('element')?.asString()?.getValue()
+                            if (elementName) {
+                                try {
+                                    configObj[elementName] = JSON.parse(value || '')
+                                } catch {
+                                    configObj[elementName] = value
+                                }
+                            }
+                        }
+                    }
+
+                    stepDefinitionShape = new CallExpressionShape({
+                        source: stepDefinition,
+                        callee: 'ActionStepDefinition',
+                        args: [
+                            stepDefinition.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(stepDefinition)),
+                                name: $,
+                            })),
+                        ],
+                    })
+                } else {
+                    // OOB/built-in step definition — not in XML export
+                    const stepTypeSysId = record.get('step_type')?.asString()?.getValue()
+                    if (!stepTypeSysId) {
+                        logger.warn(`Step instance ${record.getId().getValue()} has no step_type reference`)
+                        return { success: false }
+                    }
+
+                    const builtInDef = BUILT_IN_STEP_DEFINITIONS[stepTypeSysId]
+                    if (!builtInDef) {
+                        logger.warn(
+                            `Unknown OOB step definition ${stepTypeSysId} for step instance ${record.getId().getValue()}`
+                        )
+                        return { success: false }
+                    }
+
+                    stepName = builtInDef.name
+
+                    // Resolve variable values using the built-in definition's input/output mappings
+                    for (const varValue of variableValues) {
+                        const variableSysId = varValue.get('variable')?.asString()?.getValue()
+                        const value = varValue.get('value')?.asString()?.getValue()
+                        if (variableSysId) {
+                            const entry = builtInDef.inputs[variableSysId] ?? builtInDef.outputs[variableSysId]
+                            const elementName = entry ? getVarEntryName(entry) : undefined
+                            const uiType = entry ? getVarEntryType(entry) : undefined
+                            if (elementName && value != null) {
+                                configObj[elementName] = uiType ? normalizeInputValue(value, uiType, record) : value
+                            }
+                        }
+                    }
+
+                    // Built-in/OOB step: emit actionStep.xxx reference
+                    const stepIdentifier = getBuiltInStepIdentifier(stepTypeSysId)
+                    stepDefinitionShape = stepIdentifier
+                        ? new IdentifierShape({ source: record, name: stepIdentifier })
+                        : builtInDef.name
+                }
+
+                // Build step instance config (2nd arg): $id, label, error_handling_type
+                const configProperties: globalThis.Record<string, unknown> = {
+                    $id: NowIdShape.from(record),
+                }
+
+                const errorHandlingRaw = record.get('error_handling_type')
+                const errorHandlingType =
+                    errorHandlingRaw?.ifNumber()?.getValue() ?? Number(errorHandlingRaw?.ifString()?.getValue())
+                if (errorHandlingType && errorHandlingType !== 1 && !Number.isNaN(errorHandlingType)) {
+                    configProperties['error_handling_type'] = errorHandlingType
+                }
+
+                const label = record.get('label')?.asString()?.getValue()
+                if (label && label !== stepName) {
+                    configProperties['label'] = label
+                }
+
+                const stepInstanceConfig = new ObjectShape({
+                    source: record,
+                    properties: configProperties,
+                })
+
+                // Build inputs (3rd arg): resolved variable values only
+                const inputsShape = new ObjectShape({
+                    source: record,
+                    properties: { ...configObj },
+                })
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'wfa.actionStep',
+                        args: [stepDefinitionShape, stepInstanceConfig, inputsShape],
+                    }),
+                }
+            },
         },
     },
 })
@@ -280,6 +566,7 @@ export const StepInstancePlugin = Plugin.create({
 async function buildStepInstanceRecord({
     callExpression,
     factory,
+    diagnostics,
     values,
     sysId,
     stepDefinitionSysId,
@@ -288,12 +575,19 @@ async function buildStepInstanceRecord({
 }: {
     callExpression: StepInstanceShape
     factory: Factory
+    diagnostics: Diagnostics
     values: ObjectShape
     sysId: NowIdShape | Shape
     stepDefinitionSysId: string
     stepLabel: string
     inputs: ObjectShape | undefined
 }): Promise<BuildRecord> {
+    // resolve: false — keep PillShapes and other ResolvableShapes intact (same reason as createVariableRecords).
+    // Using .getValue() on the parent ObjectShape would deeply resolve nested PillShapes into symbols.
+    const valuesArray = values.properties({ resolve: false })
+    const cidMap = callExpression.getCidMap()
+    const pillTypeMap = callExpression.getPillTypeMap()
+
     // Create step instance record
     const stepInstanceRecord = await factory.createRecord({
         source: callExpression,
@@ -303,7 +597,8 @@ async function buildStepInstanceRecord({
             step_type: stepDefinitionSysId,
             order: 1,
             active: true,
-            error_handling_type: ERROR_HANDLING_TYPE_MAP[values.get('errorHandlingType')?.getValue() as string] ?? 1,
+            error_handling_type:
+                ERROR_HANDLING_TYPE_MAP[valuesArray['errorHandlingType']?.ifString()?.getValue() ?? ''] ?? 1,
             label: stepLabel,
         },
     })
@@ -312,20 +607,31 @@ async function buildStepInstanceRecord({
     })
     const stepInstanceSysId = updatedStepInstanceRecord.getId().getValue()
     // Create sys_variable_value records for each input value
-    const variableValueRecords = await createVariableRecords(values, inputs, factory, callExpression, stepInstanceSysId)
+    const stepDataRecords = await createVariableRecords(
+        valuesArray,
+        inputs,
+        factory,
+        callExpression,
+        stepInstanceSysId,
+        stepDefinitionSysId,
+        cidMap
+    )
     const extendedInputRecords: BuildRecord[] = []
     const extendedOutputRecords: BuildRecord[] = []
     const extendedVariableValueRecords: BuildRecord[] = []
+    const inputVariablesShape = valuesArray['inputVariables']
+    if (inputVariablesShape) {
+        const inputVarObj = inputVariablesShape.asObject()
+        const inputVarProps = inputVarObj.properties({ resolve: false })
+
+        const extInputTableName = `var__m_sys_hub_step_ext_input_${stepInstanceSysId}`
 
-    const valuesArray = values.properties()
-    // biome-ignore lint/suspicious/noExplicitAny: Dynamic input variable config
-    const inputVariables = valuesArray['inputVariables']?.getValue() as Record<string, any>
-    if (inputVariables) {
-        for (const [name, config] of Object.entries(inputVariables)) {
-            const label = config.label
-            const mandatory = config.mandatory
-            const defaultValue = config.defaultValue ?? ''
-            const value = config.value
+        for (const [name, configShapeRaw] of Object.entries(inputVarProps)) {
+            const configObj = configShapeRaw.asObject()
+            const configProps = configObj.properties({ resolve: false })
+            const label = (configProps['label']?.ifString?.()?.getValue() ?? name) as string
+            const defaultValue = (configProps['defaultValue']?.ifString?.()?.getValue() ?? '') as string
+            const valueShape = configProps['value']
             const extInputRecord = await factory.createRecord({
                 source: callExpression,
                 table: 'sys_hub_step_ext_input',
@@ -334,89 +640,397 @@ async function buildStepInstanceRecord({
                     model: stepInstanceSysId,
                     model_id: stepInstanceSysId,
                     model_table: 'sys_hub_step_instance',
-                    name: `var__m_sys_hub_step_ext_input_${stepInstanceSysId}`,
+                    name: extInputTableName,
                     element: name,
                     label: label,
-                    mandatory: mandatory,
                     default_value: defaultValue,
+                    attributes: buildExtVarAttributes('string'),
+                    internal_type: 'string',
                 },
             })
             extendedInputRecords.push(extInputRecord)
-            extendedVariableValueRecords.push(
-                await factory.createRecord({
-                    source: callExpression,
-                    table: 'sys_variable_value',
-                    properties: {
-                        document: 'sys_hub_step_instance',
-                        document_key: stepInstanceSysId,
-                        order: 100,
-                        value: value,
-                        variable: extInputRecord.getId().getValue(),
-                    },
-                })
-            )
+
+            if (!valueShape) {
+                // No value provided — still create a sys_variable_value record with empty value
+                // so the platform recognizes the ext input variable exists
+                extendedVariableValueRecords.push(
+                    await factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_variable_value',
+                        properties: {
+                            document: 'sys_hub_step_instance',
+                            document_key: stepInstanceSysId,
+                            order: 100,
+                            value: '',
+                            variable: extInputRecord.getId().getValue(),
+                        },
+                    })
+                )
+            } else {
+                // Check if value is a datapill — if so, create sys_element_mapping instead of sys_variable_value
+                const pillString = resolveFieldToPillString(valueShape as Shape, cidMap)
+                if (pillString) {
+                    collectPillTypes(pillString, pillTypeMap)
+                    extendedVariableValueRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_element_mapping',
+                            properties: {
+                                field: name,
+                                id: stepInstanceSysId,
+                                table: extInputTableName,
+                                value: stripPillType(pillString),
+                            },
+                        })
+                    )
+                } else if (valueShape.is(TemplateExpressionShape)) {
+                    const { result, hasPills } = resolveTemplateExpression(
+                        valueShape as TemplateExpressionShape,
+                        cidMap,
+                        pillTypeMap
+                    )
+                    if (hasPills) {
+                        extendedVariableValueRecords.push(
+                            await factory.createRecord({
+                                source: callExpression,
+                                table: 'sys_element_mapping',
+                                properties: {
+                                    field: name,
+                                    id: stepInstanceSysId,
+                                    table: extInputTableName,
+                                    value: result,
+                                },
+                            })
+                        )
+                    } else {
+                        extendedVariableValueRecords.push(
+                            await factory.createRecord({
+                                source: callExpression,
+                                table: 'sys_variable_value',
+                                properties: {
+                                    document: 'sys_hub_step_instance',
+                                    document_key: stepInstanceSysId,
+                                    order: 100,
+                                    value: result,
+                                    variable: extInputRecord.getId().getValue(),
+                                },
+                            })
+                        )
+                    }
+                } else {
+                    // Simple value → store in sys_variable_value
+                    const rawVal = valueShape.ifString()?.getValue() ?? valueShape.getValue?.()
+                    const resolvedValue = typeof rawVal === 'symbol' ? '' : (rawVal ?? '')
+                    extendedVariableValueRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_variable_value',
+                            properties: {
+                                document: 'sys_hub_step_instance',
+                                document_key: stepInstanceSysId,
+                                order: 100,
+                                value: resolvedValue,
+                                variable: extInputRecord.getId().getValue(),
+                            },
+                        })
+                    )
+                }
+            }
         }
     }
 
     const outputVariables = valuesArray['outputVariables']
+    const complexObjectRecords: BuildRecord[] = []
     if (outputVariables) {
         const outputItemShape = outputVariables.asObject()
-        const outputProperties = outputItemShape.properties()
+        const outputProperties = outputItemShape.properties({ resolve: false })
 
         for (const [columnName, columnCallExpr] of Object.entries(outputProperties)) {
             const callExpr = columnCallExpr.as(CallExpressionShape)
-            const columnType = callExpr.getCallee() // e.g., 'StringColumn', 'IntegerColumn'
+            const columnType = callExpr.getCallee() // e.g., 'StringColumn', 'IntegerColumn', 'FlowObject', 'FlowArray'
             const columnConfig = callExpr.getArgument(0)?.asObject()
             const columnLabel = columnConfig?.get('label')?.getValue() as string
             const mandatory = columnConfig?.get('mandatory')?.getValue() as boolean
-            const internalType = COLUMN_API_TO_TYPE[columnType] || 'string'
-            const extOutputRecord = await factory.createRecord({
-                source: callExpression,
-                table: 'sys_hub_step_ext_output',
-                properties: {
-                    active: true,
-                    model: stepInstanceSysId,
-                    model_id: stepInstanceSysId,
-                    model_table: 'sys_hub_step_instance',
-                    name: `var__m_sys_hub_step_ext_output_${stepInstanceSysId}`,
-                    element: columnName,
-                    label: columnLabel || columnName,
-                    internal_type: internalType,
-                    mandatory: mandatory,
-                },
-            })
-            extendedOutputRecords.push(extOutputRecord)
+
+            // Handle FlowObject and FlowArray complex objects
+            if (columnType === FLOW_OBJECT_API_NAME || columnType === FLOW_ARRAY_API_NAME) {
+                const coTypeName = columnConfig?.get('co_type_name')?.ifString()?.getValue()
+                const varSysId = `${stepInstanceSysId}_${columnName}`
+                const complexObjectId = coTypeName || `FD${varSysId}`
+                const isArray = columnType === FLOW_ARRAY_API_NAME
+
+                // Generate schema for complex object
+                const schemaObj = generateSchemaFromObject(
+                    columnConfig,
+                    complexObjectId,
+                    columnName,
+                    stepInstanceSysId,
+                    0,
+                    isArray,
+                    diagnostics,
+                    false
+                )
+
+                // Create sys_complex_object record
+                const explicitId = columnConfig?.get('$id')?.ifString()?.getValue()
+                const complexRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_complex_object',
+                    properties: {
+                        name: complexObjectId,
+                        namespace: 'FlowDesigner',
+                        type: isArray ? 'complex_object_collection' : 'complex_object_schema',
+                        serialized_content: JSON.stringify(schemaObj),
+                        ...(explicitId ? { sys_id: explicitId } : {}),
+                    },
+                })
+                complexObjectRecords.push(complexRecord)
+
+                // Get complex object attributes
+                const systemAttributes = getComplexObjectAttributes(schemaObj, complexObjectId, isArray)
+                const attributesStr = formatComplexObjectAttributes(systemAttributes)
+
+                // Create ext_output record with complex object type
+                const extOutputRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_step_ext_output',
+                    properties: {
+                        active: true,
+                        model: stepInstanceSysId,
+                        model_id: stepInstanceSysId,
+                        model_table: 'sys_hub_step_instance',
+                        name: `var__m_sys_hub_step_ext_output_${stepInstanceSysId}`,
+                        element: columnName,
+                        label: columnLabel || columnName,
+                        internal_type: 'string',
+                        max_length: 65000,
+                        mandatory: mandatory,
+                        attributes: attributesStr,
+                    },
+                })
+                extendedOutputRecords.push(extOutputRecord)
+            } else {
+                // Handle regular column types (StringColumn, IntegerColumn, etc.)
+                const internalType = COLUMN_API_TO_TYPE[columnType] || 'string'
+                const maxLength = columnConfig?.get('maxLength')?.ifNumber()?.getValue()
+                const hint = columnConfig?.get('hint')?.ifString()?.getValue()
+                const defaultValue = columnConfig?.get('default')?.ifString()?.getValue()
+                const extOutputRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_step_ext_output',
+                    properties: {
+                        active: true,
+                        model: stepInstanceSysId,
+                        model_id: stepInstanceSysId,
+                        model_table: 'sys_hub_step_instance',
+                        name: `var__m_sys_hub_step_ext_output_${stepInstanceSysId}`,
+                        element: columnName,
+                        label: columnLabel || columnName,
+                        internal_type: internalType,
+                        mandatory: mandatory,
+                        ...(maxLength != null ? { max_length: maxLength } : {}),
+                        ...(hint ? { hint } : {}),
+                        ...(defaultValue ? { default_value: defaultValue } : {}),
+                        attributes: buildExtVarAttributes(internalType),
+                    },
+                })
+                extendedOutputRecords.push(extOutputRecord)
+            }
         }
     }
 
     return updatedStepInstanceRecord.with(
-        ...variableValueRecords,
+        ...stepDataRecords,
         ...extendedInputRecords,
         ...extendedVariableValueRecords,
-        ...extendedOutputRecords
+        ...extendedOutputRecords,
+        ...complexObjectRecords
     )
 }
 async function createVariableRecords(
-    values: ObjectShape,
+    valuesProperties: globalThis.Record<string, Shape>,
     inputs: ObjectShape | undefined,
     factory: Factory,
     callExpression: StepInstanceShape,
-    stepInstanceSysId: string
+    stepInstanceSysId: string,
+    stepDefinitionSysId: string,
+    cidMap?: Map<string, string>
 ) {
-    const properties = values.properties()
     // Filter out inputVariables, outputVariables and errorHandlingType as they are handled separately
-    const filteredEntries = Object.entries(properties).filter(
+    const filteredEntries = Object.entries(valuesProperties).filter(
         ([key]) => key !== 'inputVariables' && key !== 'outputVariables' && key !== 'errorHandlingType'
     )
-    return await Promise.all(
-        filteredEntries.map(([key, valueShape]) => {
+
+    // Build reverse lookup (elementName → varSysId) from BUILT_IN_STEP_DEFINITIONS
+    const builtInDef = BUILT_IN_STEP_DEFINITIONS[stepDefinitionSysId]
+    const elementToVarSysId: globalThis.Record<string, string> = {}
+    if (builtInDef) {
+        for (const [varSysId, entry] of Object.entries(builtInDef.inputs)) {
+            elementToVarSysId[getVarEntryName(entry)] = varSysId
+        }
+        for (const [varSysId, entry] of Object.entries(builtInDef.outputs)) {
+            elementToVarSysId[getVarEntryName(entry)] = varSysId
+        }
+    }
+
+    const pillTypeMap = callExpression.getPillTypeMap()
+    const allRecords: BuildRecord[] = []
+    await Promise.all(
+        filteredEntries.map(async ([key, valueShape]) => {
+            // Try resolving from inputDefinitions shape first, then fall back to built-in map
+            let variableSysId = ''
             const input = inputs?.get(key)
-            const variableSysId =
-                input instanceof CallExpressionShape
-                    ? (input.getArgument(0).asObject().get('sysId')?.getValue() as string)
-                    : ''
-            const actualValue = valueShape.getValue?.() ?? valueShape.toString()
-            return factory.createRecord({
+            if (input instanceof CallExpressionShape) {
+                variableSysId = (input.getArgument(0).asObject().get('sysId')?.getValue() as string) ?? ''
+            }
+            if (!variableSysId) {
+                variableSysId = elementToVarSysId[key] ?? ''
+            }
+
+            // ApprovalDueDateShape: store JSON in sys_element_mapping.value (ServiceNow reads from there)
+            // and create sys_variable_value with empty value
+            if (valueShape.is(ApprovalDueDateShape)) {
+                const jsonValue = (valueShape as ApprovalDueDateShape).toString().getValue()
+                const [elementMappingRecord, variableValueRecord] = await Promise.all([
+                    factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_element_mapping',
+                        properties: {
+                            field: key,
+                            id: stepInstanceSysId,
+                            table: `var__m_sys_flow_step_definition_input_${stepDefinitionSysId}`,
+                            value: jsonValue,
+                        },
+                    }),
+                    factory.createRecord({
+                        source: callExpression,
+                        table: 'sys_variable_value',
+                        properties: {
+                            document: 'sys_hub_step_instance',
+                            document_key: stepInstanceSysId,
+                            order: 100,
+                            // value intentionally empty: ServiceNow reads due_date JSON from sys_element_mapping, not here
+                            value: '',
+                            variable: variableSysId,
+                        },
+                    }),
+                ])
+                allRecords.push(elementMappingRecord, variableValueRecord)
+                return
+            }
+
+            // Handle TemplateValueShape specially - serialize to ServiceNow format.
+            // When TemplateValue contains datapills, the platform stores the entire encoded string
+            // (with pills inline) in a single sys_element_mapping record with field=<parent input name>.
+            let actualValue: unknown
+            if (valueShape.is(TemplateValueShape)) {
+                const templateObj = (valueShape as TemplateValueShape).getTemplateValue()
+                const entries: string[] = []
+                let hasPills = false
+
+                for (const [field, fieldShape] of templateObj.entries({ resolve: false })) {
+                    const pillString = resolveFieldToPillString(fieldShape, cidMap)
+                    if (pillString) {
+                        collectPillTypes(pillString, pillTypeMap)
+                        entries.push(`${field}=${stripPillType(pillString)}`)
+                        hasPills = true
+                    } else if (fieldShape.is(TemplateExpressionShape)) {
+                        const resolved = resolveTemplateExpression(
+                            fieldShape as TemplateExpressionShape,
+                            cidMap,
+                            pillTypeMap
+                        )
+                        if (resolved.hasPills) {
+                            hasPills = true
+                        }
+                        const escapedValue = resolved.result.replace(/\^/g, '^^')
+                        entries.push(`${field}=${escapedValue}`)
+                    } else {
+                        const resolved = fieldShape.getValue()
+                        const escapedValue = String(resolved).replace(/\^/g, '^^')
+                        entries.push(`${field}=${escapedValue}`)
+                    }
+                }
+
+                const encodedValue = entries.join('^')
+
+                if (hasPills) {
+                    // TemplateValue with datapills → single sys_element_mapping record
+                    // No sys_variable_value for this field — platform reads from element_mapping only
+                    allRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_element_mapping',
+                            properties: {
+                                field: key,
+                                id: stepInstanceSysId,
+                                table: `var__m_sys_flow_step_definition_input_${stepDefinitionSysId}`,
+                                value: encodedValue,
+                            },
+                        })
+                    )
+                    return
+                }
+
+                // No datapills — standard encoded string in sys_variable_value
+                actualValue = encodedValue ? `${encodedValue}^EQ` : ''
+            } else if (valueShape.is(DurationShape)) {
+                // DurationShape.getValue() returns a symbol, so use toString() instead
+                actualValue = (valueShape as DurationShape).toString().getValue()
+            } else if (valueShape.is(ApprovalRulesShape)) {
+                // ApprovalRulesShape.getValue() returns a JSON object, not a string.
+                // Previously fell through to the generic getValue() path which stored a raw [object Object].
+                // toString() correctly serializes it to the JSON string ServiceNow expects.
+                actualValue = valueShape.toString().getValue()
+            } else if (valueShape.is(TemplateExpressionShape)) {
+                const { result, hasPills } = resolveTemplateExpression(
+                    valueShape as TemplateExpressionShape,
+                    cidMap,
+                    pillTypeMap
+                )
+                if (hasPills) {
+                    allRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_element_mapping',
+                            properties: {
+                                field: key,
+                                id: stepInstanceSysId,
+                                table: `var__m_sys_flow_step_definition_input_${stepDefinitionSysId}`,
+                                value: result,
+                            },
+                        })
+                    )
+                    return
+                }
+                actualValue = result
+            } else {
+                // Check if it's a wfa.dataPill() CallExpressionShape (step output reference)
+                // that needs to be resolved to a pill string for sys_element_mapping
+                const pillString = resolveFieldToPillString(valueShape as Shape, cidMap)
+                if (pillString) {
+                    collectPillTypes(pillString, pillTypeMap)
+                    allRecords.push(
+                        await factory.createRecord({
+                            source: callExpression,
+                            table: 'sys_element_mapping',
+                            properties: {
+                                field: key,
+                                id: stepInstanceSysId,
+                                table: `var__m_sys_flow_step_definition_input_${stepDefinitionSysId}`,
+                                value: stripPillType(pillString),
+                            },
+                        })
+                    )
+                    return
+                }
+                const rawValue = valueShape.getValue?.()
+                // Guard against symbol values (e.g., DurationShape, unresolved shapes with { resolve: false })
+                // since factory.createRecord cannot serialize symbols. Fall back to empty string.
+                actualValue = typeof rawValue === 'symbol' ? '' : (rawValue ?? '')
+            }
+
+            const record = await factory.createRecord({
                 source: callExpression,
                 table: 'sys_variable_value',
                 properties: {
@@ -427,6 +1041,8 @@ async function createVariableRecords(
                     variable: variableSysId,
                 },
             })
+            allRecords.push(record)
         })
     )
+    return allRecords
 }