@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/complex-object-resolver.ts

@@ -0,0 +1,875 @@
+import {
+    type Record,
+    UndefinedShape,
+    type Diagnostics,
+    CallExpressionShape,
+    type Logger,
+} from '@servicenow/sdk-build-core'
+import { parseAttributesToObject } from './schema-to-flow-object'
+import { STRING_API_NAME, STRING_FULL_UTF8_ATTRIBUTE_NAME, STRING_FULL_UTF8_DATA_TYPE_VALUE } from './flow-constants'
+
+/**
+ * Utility module responsible for resolving complex-object and array inputs to the
+ * JSON payload expected by Flow Designer.  Keeping the logic in a standalone
+ * file makes it unit-testable and keeps plugin code succinct.
+ */
+
+/* -------------------------------------------------------------------------- */
+/*                                 Constants                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Prefix for Flow Designer complex object schema keys */
+const FLOW_DESIGNER_PREFIX = 'FlowDesigner:'
+
+/** Suffix for field facets in complex object schema */
+const FIELD_FACETS_SUFFIX = '.$field_facets'
+
+/** Key for SimpleMapFacet in field facets */
+const SIMPLE_MAP_FACET_KEY = 'SimpleMapFacet'
+
+/** Prefix for Java language types in complex objects */
+const JAVA_LANG_PREFIX = 'java.lang.'
+
+/** Field name for complex object name in JSON payload */
+const COMPLEX_OBJECT_NAME_FIELD = 'name$'
+
+/** Field name for complex object collection arrays in JSON payload */
+const COMPLEX_OBJECT_COLLECTION_FIELD = '$COCollectionField'
+
+/** UI type value for object type fields */
+const UI_TYPE_OBJECT = 'object'
+
+/** UI type prefix for array type fields */
+const UI_TYPE_ARRAY_PREFIX = 'array'
+
+/* -------------------------------------------------------------------------- */
+/*                            Type Definitions                                */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Represents the complete complex object schema structure.
+ * The key is typically in the format "FlowDesigner:{typeName}".
+ * Extends Record for compatibility with existing code that uses unknown types.
+ */
+interface ComplexObjectSchema extends globalThis.Record<string, unknown> {
+    [key: `FlowDesigner:${string}`]: ComplexObjectTemplate
+}
+
+/**
+ * Template defining the structure of a complex object with field definitions and metadata.
+ * Can contain field names mapped to types (string), nested objects, or field facets.
+ */
+interface ComplexObjectTemplate extends globalThis.Record<string, unknown> {
+    [fieldName: string]: string | ComplexObjectTemplate | FieldFacets | unknown
+}
+
+/**
+ * Field facets containing metadata for a complex object field.
+ * The key is in the format "{fieldName}.$field_facets".
+ */
+interface FieldFacets extends globalThis.Record<string, unknown> {
+    SimpleMapFacet?: string // JSON-stringified SimpleMapFacet object
+    [facetType: string]: string | unknown
+}
+
+/**
+ * Simple map facet containing field label, type, and mapped datapill values.
+ * This is typically stored as a JSON-stringified object in the schema.
+ */
+interface SimpleMapFacet {
+    label?: string
+    uiType?: string
+    mapped?: string // JSON-stringified object mapping dotted paths to datapill values
+    [key: string]: unknown
+}
+
+/* -------------------------------------------------------------------------- */
+/*                                Public API                                  */
+/* -------------------------------------------------------------------------- */
+
+export function resolveComplexInput(
+    name: string,
+    value: unknown,
+    parentDef: Record,
+    inputTableName: string,
+    diagnostics?: Diagnostics,
+    logger?: Logger
+): { value: unknown; internalType: unknown; children?: unknown[] } {
+    const inputDef = parentDef
+        ?.flat()
+        .filter((obj) => obj.getTable() === inputTableName)
+        .find((obj) => obj.get('element').asString().getValue() === name)
+
+    if (!inputDef) {
+        return { value: value, internalType: undefined }
+    }
+
+    let internalType = inputDef?.get('internal_type').asString().getValue()
+
+    //Logic to check if the StringColumn has isFullUTF8 set to true and update internalType to String (Full UTF-8)
+    const inputDefSource = inputDef.getSource()
+    if (inputDefSource instanceof CallExpressionShape && inputDefSource.getCallee() === STRING_API_NAME) {
+        const isFullUTF8 = inputDefSource.getArgument?.(0)?.asObject()?.get(STRING_FULL_UTF8_ATTRIBUTE_NAME)
+        if (isFullUTF8?.ifBoolean()?.getValue() === true) {
+            internalType = STRING_FULL_UTF8_DATA_TYPE_VALUE
+        }
+    }
+
+    const attributesShape = inputDef.get('attributes')
+    const attributesStr =
+        attributesShape && !attributesShape.is(UndefinedShape) ? attributesShape.ifString()?.getValue() : undefined
+
+    // If attributes is not present then its a primitive input, return the value as is.
+    if (!attributesStr) {
+        return { value: value, internalType: internalType }
+    }
+
+    const { coType, uiType } = parseAttributes(attributesStr)
+    if (!coType || !uiType) {
+        return { value: value, internalType: internalType }
+    }
+
+    const complexSchema = getComplexObjectSchema(parentDef, coType, diagnostics)
+    if (!complexSchema) {
+        return { value: value, internalType: internalType }
+    }
+
+    if (uiType === UI_TYPE_OBJECT) {
+        const result = buildObjectPayloadWithChildren(value, complexSchema, coType)
+        return {
+            value: result.value,
+            internalType: internalType,
+            children: result.children,
+        }
+    }
+
+    const uiTypeRoot = uiType.split('.')[0]
+    if (uiTypeRoot === UI_TYPE_ARRAY_PREFIX) {
+        const result = buildArrayPayloadWithChildren(value, complexSchema, coType, logger)
+        return {
+            value: result.value,
+            internalType: internalType,
+            children: result.children,
+        }
+    }
+
+    // Fallback - unsupported uiType
+    return { value: value, internalType: internalType }
+}
+
+/* -------------------------------------------------------------------------- */
+/*                               Implementation                               */
+/* -------------------------------------------------------------------------- */
+
+interface ParsedAttributes {
+    coType?: string
+    uiType?: string
+}
+
+function parseAttributes(attr: string): ParsedAttributes {
+    const attributes = parseAttributesToObject(attr)
+    const coType = attributes['co_type_name']
+    const uiType = attributes['uiType']
+    const result: ParsedAttributes = {}
+    if (coType !== undefined) {
+        result.coType = coType
+    }
+    if (uiType !== undefined) {
+        result.uiType = uiType
+    }
+    return result
+}
+
+function getComplexObjectSchema(
+    parent: Record,
+    coType: string,
+    diagnostics?: Diagnostics
+): ComplexObjectSchema | undefined {
+    // get complex object schema from parent record for the given coType
+    const complexObject = parent
+        ?.flat()
+        .find((obj) => obj.getTable() === 'sys_complex_object' && obj.get('name').asString().getValue() === coType)
+
+    if (!complexObject) {
+        diagnostics?.error(parent, `Complex object '${coType}' not found.`)
+        return undefined
+    }
+
+    const serialized = complexObject?.get('serialized_content')?.ifString()?.getValue()
+    if (!serialized) {
+        diagnostics?.error(complexObject ?? parent, `Serialized schema missing for complex object '${coType}'.`)
+        return undefined
+    }
+
+    return safeJsonParse(serialized, coType, complexObject, diagnostics)
+}
+
+function safeJsonParse(
+    text: string,
+    coType: string,
+    node: Record,
+    diagnostics?: Diagnostics
+): ComplexObjectSchema | undefined {
+    try {
+        return JSON.parse(text) as ComplexObjectSchema
+    } catch (e: unknown) {
+        const message = e instanceof Error ? e.message : String(e)
+        diagnostics?.error(node, `Invalid schema JSON for complex object '${coType}': ${message}`)
+        return undefined
+    }
+}
+
+/* ------------------------------ Object Types ------------------------------ */
+
+/** Enriches schema with mapped datapill values for nested objects */
+function addMappedFieldsToSchema(
+    schema: ComplexObjectSchema,
+    coType: string,
+    rawValue: globalThis.Record<string, unknown>
+): ComplexObjectSchema {
+    // Deep clone the schema to avoid mutating the original
+    const enrichedSchema = JSON.parse(JSON.stringify(schema)) as ComplexObjectSchema
+    const template = enrichedSchema[`${FLOW_DESIGNER_PREFIX}${coType}`]
+
+    if (!template) {
+        return enrichedSchema
+    }
+
+    // Recursively process all fields (including nested objects)
+    processFieldsForMappedValues(template as globalThis.Record<string, unknown>, rawValue, '')
+
+    return enrichedSchema
+}
+
+/**
+ * Processes a single field to add mapped datapill value to its facets.
+ * @param facets - The field facets object
+ * @param mappedKey - The dotted path key (e.g., 'name.firstName')
+ * @param dataPillValue - The datapill value to map
+ */
+function addMappedValueToFacet(facets: FieldFacets, mappedKey: string, dataPillValue: string): void {
+    const simpleMapFacetStr = facets[SIMPLE_MAP_FACET_KEY]
+
+    if (typeof simpleMapFacetStr !== 'string') {
+        return
+    }
+
+    try {
+        const facetObj = JSON.parse(simpleMapFacetStr) as SimpleMapFacet
+        const strippedValue = stripDataPillType(dataPillValue)
+        facetObj['mapped'] = JSON.stringify({ [mappedKey]: strippedValue })
+        facets[SIMPLE_MAP_FACET_KEY] = JSON.stringify(facetObj)
+    } catch (e) {
+        // Skip fields without proper facet structure
+    }
+}
+
+/** Recursively processes fields to add mapped datapill values for nested objects */
+function processFieldsForMappedValues(
+    template: globalThis.Record<string, unknown>,
+    rawValue: globalThis.Record<string, unknown>,
+    parentPath: string
+): void {
+    for (const key of Object.keys(rawValue)) {
+        const fieldValue = rawValue[key]
+        const fieldTemplate = template[key]
+
+        // Handle arrays (FlowArray with FlowObject elements)
+        if (Array.isArray(fieldValue) && Array.isArray(fieldTemplate)) {
+            processArrayForMappedValues(fieldTemplate, fieldValue, parentPath, key)
+            continue
+        }
+
+        // Handle nested objects recursively
+        if (isNestedObject(fieldValue) && isNestedObject(fieldTemplate)) {
+            const newPath = buildFieldPath(parentPath, key)
+            processFieldsForMappedValues(fieldTemplate, fieldValue, newPath)
+            continue
+        }
+
+        // Handle datapill fields - add mapped value to facets
+        if (!isDataPill(fieldValue)) {
+            continue
+        }
+
+        const facetKey = `${key}${FIELD_FACETS_SUFFIX}`
+        const facets = template[facetKey]
+
+        if (!isNestedObject(facets)) {
+            continue
+        }
+
+        const mappedKey = buildFieldPath(parentPath, key)
+        addMappedValueToFacet(facets as FieldFacets, mappedKey, fieldValue as string)
+    }
+}
+
+/** Processes array elements to add mapped datapill values for FlowArray fields */
+function processArrayForMappedValues(
+    templateArray: unknown[],
+    rawArray: unknown[],
+    parentPath: string,
+    arrayKey: string
+): void {
+    // FlowArray schema is wrapped: [{"wrapperKey": {field1: "String", field2: "Integer"}}]
+    if (templateArray.length !== 1) {
+        return
+    }
+
+    const wrapperElement = templateArray[0]
+    if (!isNestedObject(wrapperElement)) {
+        return
+    }
+
+    const wrapperKeys = Object.keys(wrapperElement)
+    if (wrapperKeys.length !== 1 || !wrapperKeys[0]) {
+        return
+    }
+
+    const elementTemplate = wrapperElement[wrapperKeys[0]]
+    if (!isNestedObject(elementTemplate)) {
+        return
+    }
+
+    // Process each array element
+    rawArray.forEach((element, index) => {
+        if (!isNestedObject(element)) {
+            return
+        }
+
+        // Build path with array index: "tasks[0]"
+        const arrayPath = `${arrayKey}[${index}]`
+        const fullPath = buildFieldPath(parentPath, arrayPath)
+
+        // Process fields in this array element
+        processFieldsForMappedValues(elementTemplate, element, fullPath)
+    })
+}
+
+/** Builds complex object payload with children array for UI display */
+function buildObjectPayloadWithChildren(
+    rawValue: unknown,
+    schema: ComplexObjectSchema,
+    coType: string
+): { value: string; children: unknown[] } {
+    if (typeof rawValue !== 'object' || rawValue === null) {
+        return { value: String(rawValue), children: [] }
+    }
+
+    const template = schema[`${FLOW_DESIGNER_PREFIX}${coType}`]
+    const picked = deepPick(template, rawValue)
+    const cvObject = buildCv(picked, rawValue)
+
+    const enrichedSchema = addMappedFieldsToSchema(schema, coType, rawValue as globalThis.Record<string, unknown>)
+    const value = stringifyPayload(enrichedSchema, cvObject as globalThis.Record<string, unknown>)
+
+    // Build children array recursively for nested objects
+    const children = buildChildrenArray(
+        rawValue as globalThis.Record<string, unknown>,
+        template as globalThis.Record<string, unknown>
+    )
+
+    return { value, children }
+}
+
+/* ------------------------------ Array Types ------------------------------- */
+
+function buildArrayPayload(rawValue: unknown, schema: ComplexObjectSchema, coType: string): string {
+    const collectionValue =
+        Array.isArray(rawValue) && rawValue.length === 0
+            ? (createEmptyArrayPlaceholder(schema, coType) ?? rawValue)
+            : rawValue
+
+    return stringifyPayload(schema, {
+        [COMPLEX_OBJECT_NAME_FIELD]: coType,
+        [COMPLEX_OBJECT_COLLECTION_FIELD]: collectionValue,
+    })
+}
+
+/**
+ * Builds complex object array payload with children array for UI display.
+ * Extracts child_name from schema and uses it for array element names.
+ */
+function buildArrayPayloadWithChildren(
+    rawValue: unknown,
+    schema: ComplexObjectSchema,
+    coType: string,
+    logger?: Logger
+): { value: string; children: unknown[] } {
+    // Build the payload value
+    const value = buildArrayPayload(rawValue, schema, coType)
+
+    // Extract child_name from schema
+    const childName = extractChildNameFromSchema(schema, coType, logger)
+
+    // Build children array with proper names
+    const children: unknown[] = []
+    if (Array.isArray(rawValue)) {
+        const template = schema[`${FLOW_DESIGNER_PREFIX}${coType}`]
+        const collectionField = template?.[COMPLEX_OBJECT_COLLECTION_FIELD]
+        const elementTemplate =
+            Array.isArray(collectionField) && collectionField.length > 0 ? collectionField[0] : undefined
+
+        for (const element of rawValue) {
+            if (typeof element === 'object' && element !== null && elementTemplate) {
+                // Unwrap childName layer if present
+                // The schema wraps FlowObject fields with childName: { "tag": { "value": "String", ... } }
+                // We need to extract the inner object: { "value": "String", ... }
+                let actualTemplate = elementTemplate as globalThis.Record<string, unknown>
+                if (childName && childName in actualTemplate) {
+                    const innerTemplate = actualTemplate[childName]
+                    if (typeof innerTemplate === 'object' && innerTemplate !== null && !Array.isArray(innerTemplate)) {
+                        actualTemplate = innerTemplate as globalThis.Record<string, unknown>
+                    }
+                }
+
+                // For complex elements (objects), recursively build children
+                const elementChildren = buildChildrenArray(
+                    element as globalThis.Record<string, unknown>,
+                    actualTemplate
+                )
+                children.push({
+                    name: childName || '',
+                    value: '',
+                    displayValue: '',
+                    children: elementChildren,
+                })
+            } else {
+                // For primitive elements
+                children.push({
+                    name: childName || '',
+                    value: String(element),
+                    displayValue: String(element),
+                })
+            }
+        }
+    }
+
+    return { value, children }
+}
+
+/**
+ * Extracts child_name from a complex object schema.
+ * The child_name is stored in the $COCollectionField.$type_facets.SimpleMapFacet.
+ */
+function extractChildNameFromSchema(schema: ComplexObjectSchema, coType: string, logger?: Logger): string | undefined {
+    try {
+        const template = schema[`${FLOW_DESIGNER_PREFIX}${coType}`]
+        const typeFacets = template?.['$COCollectionField.$type_facets']
+
+        if (typeFacets && typeof typeFacets === 'object' && 'SimpleMapFacet' in typeFacets) {
+            const simpleMapFacet = typeFacets.SimpleMapFacet
+            if (typeof simpleMapFacet === 'string') {
+                const facetData = JSON.parse(simpleMapFacet)
+                return facetData.child_name
+            }
+        }
+    } catch (error) {
+        logger?.warn(
+            'Failed to extract child_name from schema:',
+            error instanceof Error ? error.message : String(error)
+        )
+    }
+    return undefined
+}
+
+/**
+ * Creates a placeholder element for empty FlowArrays with FlowObject elements.
+ * ServiceNow expects a single placeholder with empty $cv values for each field.
+ *
+ * @param schema - The complex object schema containing array structure
+ * @param coType - The complex object type name
+ * @returns Array with single placeholder element, or undefined if schema is invalid
+ */
+function createEmptyArrayPlaceholder(schema: ComplexObjectSchema, coType: string): unknown[] | undefined {
+    const template = schema[`${FLOW_DESIGNER_PREFIX}${coType}`]
+    const collectionField = template?.[COMPLEX_OBJECT_COLLECTION_FIELD]
+
+    if (!Array.isArray(collectionField) || collectionField.length === 0) {
+        return undefined
+    }
+
+    const elementTemplate = collectionField[0]
+    if (!isNestedObject(elementTemplate)) {
+        return undefined
+    }
+
+    const childSchemaKey = Object.keys(elementTemplate)[0]
+    if (!childSchemaKey) {
+        return undefined
+    }
+
+    const childSchema = elementTemplate[childSchemaKey]
+    if (!isNestedObject(childSchema)) {
+        return undefined
+    }
+
+    const placeholder = buildPlaceholderFromSchema(childSchema)
+    return [placeholder]
+}
+
+/**
+ * Builds a placeholder object with empty $cv wrappers for each non-metadata field.
+ *
+ * @param schema - Schema object mapping field names to types
+ * @returns Placeholder object with $cv wrappers
+ */
+function buildPlaceholderFromSchema(schema: globalThis.Record<string, unknown>): globalThis.Record<string, unknown> {
+    const placeholder: globalThis.Record<string, unknown> = {}
+
+    for (const [fieldKey, fieldType] of Object.entries(schema)) {
+        if (isMetadataField(fieldKey) || typeof fieldType !== 'string') {
+            continue
+        }
+
+        placeholder[fieldKey] = {
+            $cv: {
+                $c: toJavaType(fieldType),
+                $v: '',
+            },
+        }
+    }
+
+    return placeholder
+}
+
+/* ------------------------------ Formatting -------------------------------- */
+
+function stringifyPayload(schema: ComplexObjectSchema, complexObject: globalThis.Record<string, unknown>): string {
+    return JSON.stringify({
+        version: '1.0',
+        complexObjectSchema: schema,
+        complexObject,
+        serializationFormat: 'JSON',
+    })
+}
+
+/* ------------------------------ Helpers ----------------------------------- */
+
+function deepPick(template: unknown, source: unknown): unknown {
+    if (typeof template !== 'object' || template === null) {
+        return template
+    }
+
+    // Handle FlowArray with FlowObject elements (wrapped schema format)
+    const unwrappedArray = tryUnwrapFlowArraySchema(template, source)
+    if (unwrappedArray !== null) {
+        return unwrappedArray
+    }
+
+    return pickMatchingFields(template, source)
+}
+
+/**
+ * Attempts to unwrap FlowArray schema and map source elements.
+ *
+ * FlowArray with FlowObject elements uses wrapped schema format:
+ * - Template: [{"fieldName": {field1: "String", field2: "Integer"}}]
+ * - Source:   [{field1: "value1", field2: 123}, {field1: "value2", field2: 456}]
+ *
+ * @param template - The schema template (potentially wrapped array)
+ * @param source - The source data (array of actual objects)
+ * @returns Mapped array if successful, null if not a wrapped array schema
+ */
+function tryUnwrapFlowArraySchema(template: unknown, source: unknown): unknown[] | null {
+    if (!Array.isArray(template) || !Array.isArray(source) || template.length !== 1) {
+        return null
+    }
+
+    const wrapperElement = template[0]
+    if (!isNestedObject(wrapperElement)) {
+        return null
+    }
+
+    const wrapperKeys = Object.keys(wrapperElement)
+    if (wrapperKeys.length !== 1 || !wrapperKeys[0]) {
+        return null
+    }
+
+    const unwrappedSchema = wrapperElement[wrapperKeys[0]]
+    if (!isNestedObject(unwrappedSchema)) {
+        return null
+    }
+
+    // Successfully unwrapped - map each source element through the schema
+    return source.map((sourceElement) => deepPick(unwrappedSchema, sourceElement))
+}
+
+/**
+ * Picks fields from source that exist in template, recursively.
+ *
+ * @param template - The schema template defining which fields to pick
+ * @param source - The source data to pick from
+ * @returns Object/array with only the fields that exist in both template and source
+ */
+function pickMatchingFields(template: unknown, source: unknown): unknown {
+    const tmpl = template as globalThis.Record<string, unknown>
+    const src = source as globalThis.Record<string, unknown>
+    const result = (Array.isArray(template) ? [] : {}) as globalThis.Record<string, unknown>
+
+    for (const key of Object.keys(tmpl)) {
+        if (src && key in src) {
+            result[key] = deepPick(tmpl[key], src[key])
+        }
+    }
+
+    return result
+}
+
+function toJavaType(t: string): string {
+    // Date/DateTime fields should serialize as java.lang.String, not java.lang.Date
+    // ServiceNow Flow Designer UI expects date values to be strings in complexObject
+    // This matches the behavior when creating FlowObjects with Date fields through the UI
+    if (t === 'Date') {
+        return `${JAVA_LANG_PREFIX}String`
+    }
+    return `${JAVA_LANG_PREFIX}${t}`
+}
+
+/** Detects if value is a datapill ({{path}} or {{path|type}}) */
+export function isDataPill(value: unknown): boolean {
+    if (typeof value !== 'string') {
+        return false
+    }
+    return value.startsWith('{{') && value.endsWith('}}')
+}
+
+/** Strips type annotation from datapill ({{path|type}} -> {{path}}) */
+function stripDataPillType(value: unknown): string {
+    if (typeof value !== 'string' || !isDataPill(value)) {
+        return String(value)
+    }
+
+    const pipeIndex = value.lastIndexOf('|')
+    if (pipeIndex > 0 && value.endsWith('}}')) {
+        return value.substring(0, pipeIndex) + '}}'
+    }
+
+    return value
+}
+
+/** Checks if value is a nested object (not null or array) */
+function isNestedObject(value: unknown): value is globalThis.Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Builds dotted path for nested fields (e.g., 'name.firstName') */
+function buildFieldPath(parentPath: string, key: string): string {
+    return parentPath ? `${parentPath}.${key}` : key
+}
+
+/** Checks if field key is metadata (contains $ or .) */
+function isMetadataField(key: string): boolean {
+    return key.includes('$') || key.includes('.')
+}
+
+/** Checks if field value should be included in children array */
+function shouldIncludeField(fieldValue: unknown): boolean {
+    return fieldValue !== undefined && fieldValue !== null && fieldValue !== ''
+}
+
+/** Child parameter metadata */
+interface ChildParameter {
+    children: unknown[]
+    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: globalThis.Record<string, unknown>
+    ref_qual: string
+    dependent_on: string
+}
+
+/** Child element in children array */
+interface ChildElement {
+    id: string
+    name: string
+    value: string
+    displayValue: string
+    children: unknown[]
+    parameter: ChildParameter
+    scriptActive: boolean
+    script: globalThis.Record<string, unknown>
+}
+
+/** Creates parameter object with default values */
+function createChildParameter(key: string, type: string, uiDisplayType: string, typeLabel: string): ChildParameter {
+    return {
+        children: [],
+        uiDisplayType,
+        type_label: typeLabel,
+        id: '',
+        label: key,
+        name: key,
+        type,
+        order: 0,
+        extended: false,
+        mandatory: false,
+        readOnly: false,
+        hint: '',
+        maxsize: 0,
+        reference: '',
+        reference_display: '',
+        choiceOption: '',
+        table: '',
+        columnName: '',
+        defaultValue: '',
+        defaultDisplayValue: '',
+        use_dependent: false,
+        fShowReferenceFinder: false,
+        local: false,
+        attributes: {},
+        ref_qual: '',
+        dependent_on: '',
+    }
+}
+
+/** Creates child element */
+function createChildElement(key: string, value: string, children: unknown[], parameter: ChildParameter): ChildElement {
+    return {
+        id: '',
+        name: key,
+        value,
+        displayValue: '',
+        children,
+        parameter,
+        scriptActive: false,
+        script: {},
+    }
+}
+
+/** Maps Java type to UI display type */
+function getUiDisplayType(javaType: string): string {
+    switch (javaType) {
+        case 'String':
+            return 'string'
+        case 'Integer':
+            return 'integer'
+        case 'Boolean':
+            return 'boolean'
+        case 'Decimal':
+            return 'decimal'
+        case 'Number':
+            return 'decimal' // Number maps to decimal in UI
+        case 'Date':
+            return 'glide_date_time'
+        case 'Choice':
+            return 'choice'
+        default:
+            return 'string'
+    }
+}
+
+/** Maps Java type to type label */
+function getTypeLabel(javaType: string): string {
+    switch (javaType) {
+        case 'String':
+            return 'String'
+        case 'Integer':
+            return 'Integer'
+        case 'Boolean':
+            return 'True/False'
+        case 'Decimal':
+            return 'Decimal'
+        case 'Number':
+            return 'Number'
+        case 'Date':
+            return 'Date/Time'
+        case 'Choice':
+            return 'Choice'
+        default:
+            return 'String'
+    }
+}
+
+/** Recursively builds children array for nested objects */
+function buildChildrenArray(
+    rawValue: globalThis.Record<string, unknown>,
+    template: globalThis.Record<string, unknown>
+): unknown[] {
+    const children: unknown[] = []
+
+    Object.keys(template).forEach((key) => {
+        if (isMetadataField(key)) {
+            return
+        }
+
+        const fieldValue = rawValue[key]
+        const fieldType = template[key]
+
+        if (isNestedObject(fieldType)) {
+            // Nested object: recurse
+            const nestedChildren = isNestedObject(fieldValue) ? buildChildrenArray(fieldValue, fieldType) : []
+
+            const parameter = createChildParameter(key, 'object', 'object', 'Object')
+            children.push(createChildElement(key, '', nestedChildren, parameter))
+        } else if (typeof fieldType === 'string') {
+            // Primitive field with value
+            if (shouldIncludeField(fieldValue)) {
+                const value = isDataPill(fieldValue) ? stripDataPillType(fieldValue) : ''
+                const parameter = createChildParameter(
+                    key,
+                    fieldType.toLowerCase(),
+                    getUiDisplayType(fieldType),
+                    getTypeLabel(fieldType)
+                )
+                children.push(createChildElement(key, value, [], parameter))
+            }
+        }
+    })
+
+    return children
+}
+
+function buildCv(typeNode: unknown, valueNode: unknown): unknown {
+    if (typeof typeNode === 'object' && typeNode !== null) {
+        const typedNode = typeNode as globalThis.Record<string, unknown>
+        const valuedNode = valueNode as globalThis.Record<string, unknown> | undefined
+
+        // Special handling for primitive arrays (schema: ["Any"], value: ["item1", "item2", ...])
+        if (Array.isArray(typeNode) && Array.isArray(valueNode)) {
+            if (typeNode.length === 1 && typeNode[0] === 'Any') {
+                // Primitive array: return plain string values without $cv wrapping
+                return valueNode.map((v) => String(v))
+            }
+        }
+
+        const obj = (Array.isArray(typeNode) ? [] : {}) as globalThis.Record<string, unknown>
+        Object.keys(typedNode).forEach((k) => {
+            obj[k] = buildCv(typedNode[k], valuedNode ? valuedNode[k] : undefined)
+        })
+        return obj
+    }
+
+    if (typeof typeNode === 'string') {
+        // Set $v to empty for datapills; Flow Designer handles the pill notation
+        const cvValue = isDataPill(valueNode) ? '' : (valueNode ?? '')
+
+        return {
+            $cv: {
+                $c: toJavaType(typeNode),
+                $v: cvValue,
+            },
+        }
+    }
+
+    return {}
+}