@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/utils/label-cache-processor.ts

@@ -0,0 +1,870 @@
+// biome-ignore-all lint/suspicious/noExplicitAny: This file processes dynamic JSON structures for label caching
+import type { Record } from '@servicenow/sdk-build-core'
+import { getAttributeValue, parseAttributesToObject } from './schema-to-flow-object'
+import { CallExpressionShape, ObjectShape, UndefinedShape } from '@servicenow/sdk-build-core'
+import { COLUMN_API_TO_TYPE } from '../../column/column-helper'
+import { FLOW_LOGIC_SYS_ID_MAP, FLOW_LOGIC } from '../flow-logic/flow-logic-constants'
+import { isUuidPrefix, parseSinglePill, PILL_REGEX } from './pill-string-parser'
+import { isDataPill } from './complex-object-resolver'
+
+/**
+ * Label Cache and Data Pill Metadata Utilities
+ *
+ * This module contains all utilities for:
+ * - Processing label cache for flow definitions
+ * - Extracting data pill metadata from instances
+ * - Resolving labels from complex objects
+ * - Generating initial data pill metadata for instances
+ */
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Maps trigger name prefixes (from data pill names) to their display labels
+ * This mapping is derived from the actual trigger definitions and their labels
+ */
+/**
+ * Regex pattern to strip |dataType suffix from datapill expressions
+ * Matches: {{pillName|dataType}} and captures pillName to replace with {{pillName}}
+ */
+const STRIP_DATATYPE_FROM_PILL_REGEX = /\{\{([^|}]+)\|[^}]+\}\}/g
+
+const TRIGGER_NAME_TO_LABEL_MAP: { [key: string]: string } = {
+    Created: 'Trigger - Record Created',
+    Updated: 'Trigger - Record Updated',
+    'Created or Updated': 'Trigger - Record Created or Updated',
+    Daily: 'Trigger - Run Daily',
+    Monthly: 'Trigger - Run Monthly',
+    Repeat: 'Trigger - Run Repeat',
+    'Run Once': 'Trigger - Run Once',
+    Weekly: 'Trigger - Run Weekly',
+    'Inbound Email': 'Trigger - Inbound Email',
+    'Service Catalog': 'Trigger - Service Catalog',
+    'Knowledge Management': 'Trigger - Knowledge Management',
+    'Remote Table Query': 'Trigger - Remote Table Query',
+    'SLA Task': 'Trigger - SLA Task',
+}
+
+// ============================================================================
+// Trigger Output and Input Extraction
+// ============================================================================
+
+/**
+ * Helper function to extract trigger inputs from trigger instance shape
+ * Returns a map of input name to value for use in label cache processing
+ */
+export function extractTriggerInputs(triggerInstanceShape: CallExpressionShape | undefined): Map<string, unknown> {
+    const triggerInputsMap = new Map<string, unknown>()
+
+    if (!triggerInstanceShape) {
+        return triggerInputsMap
+    }
+
+    // Extract trigger inputs from argument(2)
+    const triggerInputsObj = triggerInstanceShape.getArgument(2)?.as(ObjectShape)
+    if (triggerInputsObj) {
+        for (const [inputName, inputValue] of triggerInputsObj.entries()) {
+            if (!inputValue) {
+                continue
+            }
+            // Extract the actual value from different shape types
+            const value = inputValue.getValue()
+            triggerInputsMap.set(inputName, value)
+        }
+    }
+
+    return triggerInputsMap
+}
+
+/**
+ * Helper function to extract trigger output definitions from trigger instance shape
+ * Returns a map of output name to { label, type } for use in label cache processing
+ */
+export function extractTriggerOutputs(
+    triggerInstanceShape: CallExpressionShape | undefined
+): Map<string, { label: string; type: string }> {
+    const triggerOutputShapeMap = new Map<string, { label: string; type: string }>()
+
+    if (!triggerInstanceShape || triggerInstanceShape instanceof UndefinedShape) {
+        return triggerOutputShapeMap
+    }
+
+    const triggerDefArg = triggerInstanceShape.getArgument(0)
+    if (!(triggerDefArg instanceof CallExpressionShape)) {
+        return triggerOutputShapeMap
+    }
+
+    const triggerConfigArg = triggerDefArg.getArgument(0)
+    if (!(triggerConfigArg instanceof ObjectShape)) {
+        return triggerOutputShapeMap
+    }
+
+    const outputsObj = triggerConfigArg.get('outputs')
+    if (!(outputsObj instanceof ObjectShape)) {
+        return triggerOutputShapeMap
+    }
+
+    // Iterate through all output properties and extract column metadata
+    for (const [outputName, outputValue] of outputsObj.entries()) {
+        if (!outputValue) {
+            continue
+        }
+
+        const outputDefCE = outputValue.as(CallExpressionShape)
+        const callee = outputDefCE.getCallee()
+        if (!callee) {
+            continue
+        }
+
+        // Extract column type name (optimized: lastIndexOf instead of split)
+        const lastDotIndex = callee.lastIndexOf('.')
+        const columnApiName = lastDotIndex >= 0 ? callee.substring(lastDotIndex + 1) : callee
+
+        // Map to internal type
+        const internalType = COLUMN_API_TO_TYPE[columnApiName] || columnApiName
+        if (!internalType) {
+            continue
+        }
+
+        // Extract label from argument object
+        const outputDefArg = outputDefCE.getArgument(0)
+        const label = outputDefArg ? outputDefArg.as(ObjectShape).get('label')?.getValue() : undefined
+
+        triggerOutputShapeMap.set(outputName, {
+            label: label ? String(label) : outputName,
+            type: internalType,
+        })
+    }
+
+    return triggerOutputShapeMap
+}
+
+/**
+ * Creates a lookup map from records by element name.
+ * Used to build maps of flow variables, subflow inputs, etc.
+ *
+ * @param records - Array of records to filter and map
+ * @param tableName - Table name to filter by
+ * @returns Map of element names to records
+ */
+export function createDefinitionMap(records: Record[], tableName: string): Map<string, Record> {
+    const map = new Map<string, Record>()
+    records
+        .filter((rec) => rec.getTable() === tableName)
+        .forEach((record) => {
+            const element = record.get('element')?.asString()?.getValue()
+            if (element) {
+                map.set(element, record)
+            }
+        })
+    return map
+}
+
+// ============================================================================
+// Complex Object Label Extraction
+// ============================================================================
+
+/**
+ * Extracts labels from complex object schema and determines field types.
+ * Traverses nested complex object structures to build label paths.
+ */
+export function extractLabelsFromComplexObject(
+    segments: string[],
+    coRecord: Record,
+    labelParts: string[]
+): string | null {
+    const serializedContent = coRecord.get('serialized_content')?.ifString()?.getValue()
+    if (!serializedContent) {
+        return null
+    }
+
+    const schema = JSON.parse(serializedContent)
+    const rootKey = Object.keys(schema).find((k) => k.startsWith('FlowDesigner:'))
+    if (!rootKey) {
+        return null
+    }
+
+    let currentSchema = schema[rootKey]
+    let extractedType: string | null = null
+
+    // If accessing root object itself (segments.length === 2), extract type from root .$type_facets
+    if (segments.length === 2) {
+        const rootTypeFacets = schema[`${rootKey}.$type_facets`]?.SimpleMapFacet
+        if (rootTypeFacets) {
+            const rootFacetData = JSON.parse(rootTypeFacets)
+            if (rootFacetData.uiType) {
+                extractedType = rootFacetData.uiType
+            }
+        }
+        return extractedType
+    }
+
+    for (let i = 2; i < segments.length; i++) {
+        const fieldName = segments[i]
+        if (!fieldName) {
+            continue
+        }
+
+        const facetKey = `${fieldName}.$field_facets`
+        const facet = currentSchema[facetKey]?.SimpleMapFacet
+
+        if (!facet) {
+            throw new Error(
+                `Missing field facets for '${fieldName}' in complex object schema. ` +
+                    `Path: ${segments.join('.')}. This indicates the schema is incomplete or the field doesn't exist.`
+            )
+        }
+
+        const facetData = JSON.parse(facet)
+        labelParts.push(facetData.label || fieldName)
+
+        if (i === segments.length - 1 && facetData.uiType) {
+            extractedType = facetData.uiType
+        }
+
+        if (
+            currentSchema[fieldName] &&
+            typeof currentSchema[fieldName] === 'object' &&
+            !Array.isArray(currentSchema[fieldName])
+        ) {
+            currentSchema = currentSchema[fieldName]
+        }
+    }
+
+    return extractedType
+}
+
+/**
+ * Parses a data pill string and extracts the prefix and path.
+ * Supports all data pill formats: {{prefix.path}}
+ *
+ * @param pillString - The data pill string (e.g., "{{flow_variable.varName}}", "{{trigger.current.sys_id}}")
+ * @returns Object with prefix and path, or null if not a valid pill
+ *
+ * @example
+ * parseDataPill("{{flow_variable.varName}}") // { prefix: 'flow_variable', path: 'varName' }
+ * parseDataPill("{{trigger.current.sys_id}}") // { prefix: 'trigger', path: 'current.sys_id' }
+ * parseDataPill("{{subflow.output}}") // { prefix: 'subflow', path: 'output' }
+ */
+function parseDataPill(pillString: string): { prefix: string; path: string } | null {
+    // Use the existing parseSinglePill utility from pill-string-parser
+    const parsed = parseSinglePill(pillString, false)
+    if (!parsed) {
+        return null
+    }
+    return {
+        prefix: parsed.prefix,
+        path: parsed.path,
+    }
+}
+
+/**
+ * Extracts table name from a flow variable definition record.
+ * Handles both ReferenceColumn (reference_table) and FlowArray (childName) types.
+ *
+ * @param flowVar - The flow variable definition record
+ * @returns Table name or null if not found
+ */
+function extractTableNameFromFlowVariable(flowVar: Record): string | null {
+    // Try to get table name from reference_table field (for simple reference columns)
+    const refTable = flowVar.get('reference_table')?.getValue() as string | undefined
+    if (refTable) {
+        return refTable
+    }
+
+    // For FlowArray, extract child type from source shape
+    const sourceShape = flowVar.getSource()
+    if (sourceShape instanceof CallExpressionShape) {
+        const firstArg = sourceShape.getArgument(0)
+        if (firstArg instanceof ObjectShape) {
+            return (firstArg.get('childName')?.getValue() as string) || null
+        }
+    }
+
+    return null
+}
+
+/**
+ * Extracts forEach metadata from a flow logic instance record.
+ * This includes the step number and table name (if available) for forEach loops.
+ *
+ * @param rec - The flow logic instance record
+ * @param order - The step order number
+ * @param flowVarDefMap - Map of flow variable names to their definition records
+ * @returns Object with stepNumber and tableName
+ */
+export function extractForEachMetadata(
+    rec: Record,
+    order: number,
+    flowVarDefMap: Map<string, Record>
+): { stepNumber: number; tableName: string | null } {
+    const valuesJson = rec.get('values')?.getValue()
+    let tableName: string | null = null
+
+    // Early return if no values or inputs array
+    if (
+        !valuesJson ||
+        typeof valuesJson !== 'object' ||
+        !('inputs' in valuesJson) ||
+        !Array.isArray(valuesJson.inputs)
+    ) {
+        return { stepNumber: order, tableName }
+    }
+
+    // Find the 'items' input in the forEach values
+    const itemsInput = valuesJson.inputs.find((inp: { name?: string }) => inp?.name === 'items')
+    if (!itemsInput?.value || typeof itemsInput.value !== 'string') {
+        return { stepNumber: order, tableName }
+    }
+
+    // Parse the data pill to extract prefix and path
+    const parsed = parseDataPill(itemsInput.value)
+    if (!parsed) {
+        return { stepNumber: order, tableName }
+    }
+
+    // Handle flow_variable pills specifically (can extract table name from flow variable definitions)
+    if (parsed.prefix === 'flow_variable') {
+        // TODO: Fix this: below parsed.path comes as "flow_variable|dataTypes".
+        const varName = parsed.path.split('|')[0] || ''
+        const flowVar = flowVarDefMap.get(varName)
+        if (flowVar) {
+            tableName = extractTableNameFromFlowVariable(flowVar)
+        }
+    }
+
+    return { stepNumber: order, tableName }
+}
+
+/**
+ * Updates the forEach metadata map if the record is a forEach instance.
+ * Extracts metadata (step number and table name) and adds it to the map.
+ *
+ * @param rec - The flow logic instance record to check
+ * @param order - The step order number
+ * @param flowVarDefMap - Map of flow variable names to their definition records
+ * @param forEachMetadataMap - Map containing forEach metadata
+ * @returns Updated forEachMetadataMap with new forEach metadata if found
+ */
+export function updateForEachMetadata(
+    rec: Record,
+    order: number,
+    flowVarDefMap: Map<string, Record>,
+    forEachMetadataMap: Map<string, { stepNumber: number; tableName: string | null }>
+): Map<string, { stepNumber: number; tableName: string | null }> {
+    const logicDefId = rec.get('logic_definition')?.getValue()
+    if (logicDefId === FLOW_LOGIC_SYS_ID_MAP[FLOW_LOGIC.FOR_EACH]) {
+        const uiId = rec.get('ui_id')?.getValue() as string
+        if (uiId) {
+            const metadata = extractForEachMetadata(rec, order, flowVarDefMap)
+            if (metadata) {
+                forEachMetadataMap.set(uiId, metadata)
+            }
+        }
+    }
+    return forEachMetadataMap
+}
+
+/**
+ * Helper function to extract data pills from a string value and update the label cache.
+ * Shared logic used by both extractDataPillsFromChildren and extractDataPillsFromValuesArray.
+ * @param value - The string value potentially containing data pills
+ * @param fieldName - The name of the field containing this value
+ * @param stepUuid - UUID of the step where these data pills are used
+ * @param labelCacheMap - Existing label cache map to update (modified in place)
+ */
+function extractPillsFromValue(
+    value: string,
+    fieldName: string,
+    stepUuid: string,
+    labelCacheMap: Map<string, any>
+): void {
+    if (typeof value !== 'string' || !value.includes('{{')) {
+        return
+    }
+
+    const matches = value.matchAll(PILL_REGEX)
+    for (const match of matches) {
+        const pillString = match[0] // e.g., "{{trigger.table_name|string}}" or "{{trigger.current.company|glide_list|meta:user_criteria:company:core_company}}"
+        const pillContent = pillString.slice(2, -2) // Remove {{ and }}
+        const parts = pillContent.split('|')
+
+        const dataPillName = parts[0]
+        const dataPillType = parts[1]
+        const metaPart = parts[2] // e.g., "meta:user_criteria:company:core_company"
+
+        if (!dataPillName) {
+            continue
+        }
+
+        // Parse metadata if present
+        let metadata: { parentTableName?: string; columnName?: string; reference?: string } | undefined
+        if (metaPart && metaPart.startsWith('meta:')) {
+            const metaValues = metaPart.substring(5).split(':') // Remove "meta:" prefix and split
+            const parentTableName = metaValues[0]?.trim() || undefined
+            const columnName = metaValues[1]?.trim() || undefined
+            const reference = metaValues[2]?.trim() || undefined
+
+            // Only create metadata object if at least one field has a non-empty value
+            if (parentTableName || columnName || reference) {
+                metadata = {}
+                // Only add properties with actual non-empty values
+                if (parentTableName && parentTableName.length > 0) {
+                    metadata.parentTableName = parentTableName
+                }
+                if (columnName && columnName.length > 0) {
+                    metadata.columnName = columnName
+                }
+                if (reference && reference.length > 0) {
+                    metadata.reference = reference
+                }
+            }
+        }
+
+        updateLabelCacheForPill(dataPillName, dataPillType, stepUuid, fieldName, labelCacheMap, metadata)
+    }
+}
+
+/**
+ * Updates the label cache map with data pill usage information.
+ * Shared logic for tracking pill usage across different step instances.
+ * @param pillName - The data pill name (e.g., "trigger.table_name")
+ * @param pillType - The data pill type (e.g., "string")
+ * @param stepUuid - UUID of the step where this pill is used
+ * @param fieldName - The field name where this pill is used
+ * @param labelCacheMap - Existing label cache map to update (modified in place)
+ * @param metadata - Optional metadata containing parentTableName, columnName, and reference
+ */
+function updateLabelCacheForPill(
+    pillName: string,
+    pillType: string | undefined,
+    stepUuid: string,
+    fieldName: string,
+    labelCacheMap: Map<string, any>,
+    metadata?: { parentTableName?: string; columnName?: string; reference?: string }
+): void {
+    if (labelCacheMap.has(pillName)) {
+        const existingPill = labelCacheMap.get(pillName)
+
+        // Update type if we have a better type (non-undefined) and existing is undefined
+        if (pillType && !existingPill.type) {
+            existingPill.type = pillType
+            existingPill.base_type = pillType
+        }
+
+        // Update usedInstances - add this step's UUID and field name
+        if (existingPill.usedInstances[stepUuid]) {
+            // Step UUID already exists, add field name if not already present
+            if (!existingPill.usedInstances[stepUuid].includes(fieldName)) {
+                existingPill.usedInstances[stepUuid].push(fieldName)
+            }
+        } else {
+            // New step UUID, create new entry
+            existingPill.usedInstances[stepUuid] = [fieldName]
+        }
+
+        // Update metadata fields if provided and not already set
+        if (metadata) {
+            if (metadata.parentTableName && metadata.parentTableName.length > 0 && !existingPill.parent_table_name) {
+                existingPill.parent_table_name = metadata.parentTableName
+            }
+            if (metadata.columnName && metadata.columnName.length > 0 && !existingPill.column_name) {
+                existingPill.column_name = metadata.columnName
+            }
+            if (metadata.reference && metadata.reference.length > 0 && !existingPill.reference) {
+                existingPill.reference = metadata.reference
+            }
+        }
+    } else {
+        // New data pill, create entry
+        const pillEntry: any = {
+            name: pillName,
+            label: '', // Will be populated later by resolveDataPillMetadata
+            type: pillType,
+            base_type: pillType,
+            usedInstances: {
+                [stepUuid]: [fieldName],
+            },
+            attributes: {},
+        }
+
+        // Add metadata fields only if they have non-empty values
+        if (metadata) {
+            if (metadata.parentTableName && metadata.parentTableName.length > 0) {
+                pillEntry.parent_table_name = metadata.parentTableName
+            }
+            if (metadata.columnName && metadata.columnName.length > 0) {
+                pillEntry.column_name = metadata.columnName
+            }
+            if (metadata.reference && metadata.reference.length > 0) {
+                pillEntry.reference = metadata.reference
+            }
+        }
+
+        labelCacheMap.set(pillName, pillEntry)
+    }
+}
+
+/**
+ * Recursively extracts data pills from children array (used for FlowObject fields)
+ * @param children - Array of child field objects
+ * @param stepUuid - UUID of the step where these data pills are used
+ * @param labelCacheMap - Existing label cache map to update (modified in place)
+ */
+function extractDataPillsFromChildren(children: any[], stepUuid: string, labelCacheMap: Map<string, any>): void {
+    for (const child of children) {
+        if (!child) {
+            continue
+        }
+
+        // Add type annotation to datapill strings based on parameter.type before extraction
+        // This ensures the label cache can extract and store the correct type
+        if (isDataPill(child.value)) {
+            const paramType = child.parameter?.type
+            if (paramType && paramType !== 'string' && paramType !== 'glide_date_time') {
+                // Add type annotation: {{path}} -> {{path|type}}
+                const pillContent = child.value.slice(2, -2) // Remove {{ and }}
+                // Check if it already has a type annotation
+                if (!pillContent.includes('|')) {
+                    child.value = `{{${pillContent}|${paramType}}}`
+                }
+            }
+        }
+
+        // Extract datapills from this child's value using shared logic
+        extractPillsFromValue(child.value, child.name, stepUuid, labelCacheMap)
+
+        // Strip |dataType from pills in-place
+        if (typeof child.value === 'string') {
+            child.value = child.value.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+        }
+
+        // Recursively process nested children (for nested FlowObjects)
+        if (child.children && Array.isArray(child.children) && child.children.length > 0) {
+            extractDataPillsFromChildren(child.children, stepUuid, labelCacheMap)
+        }
+    }
+}
+
+/**
+ * Extracts data pills from a values structure and tracks their usage.
+ * Data pills are in the format {{dataPillName}} within string values.
+ *
+ * Handles three different table types:
+ * - sys_hub_action_instance_v2: Array of objects with name/value pairs
+ * - sys_hub_flow_logic_instance_v2: Object with keys (inputs, outputsToAssign, etc.) containing arrays
+ * - sys_hub_sub_flow_instance_v2: Handled as needed
+ *
+ * @param valuesData - Values data (array or object depending on table type)
+ * @param stepUuid - UUID of the step where these data pills are used
+ * @param labelCacheMap - Existing label cache map to update (modified in place)
+ * @param tableName - The table name to determine data structure
+ * @returns Updated label cache map with data pill usage tracked
+ */
+export function extractDataPillsFromValuesArray(
+    valuesData: any,
+    stepUuid: string,
+    labelCacheMap: Map<string, any>
+    // tableName?: string
+): Map<string, any> {
+    if (!valuesData) {
+        return labelCacheMap
+    }
+
+    // Handle sys_hub_action_instance_v2: Array of objects
+    if (Array.isArray(valuesData)) {
+        for (const input of valuesData) {
+            const inputName = input.name
+            const inputValue = input.value
+
+            // Handle children array for FlowObject fields with datapills
+            if (input.children && Array.isArray(input.children) && input.children.length > 0) {
+                // For FlowObjects with children, extract from children only (not parent value)
+                extractDataPillsFromChildren(input.children, stepUuid, labelCacheMap)
+            } else {
+                // For regular fields without children, extract from the value using shared logic
+                extractPillsFromValue(inputValue, inputName, stepUuid, labelCacheMap)
+            }
+
+            // Strip |dataType from pills in-place
+            if (typeof input.value === 'string') {
+                input.value = input.value.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+                input.displayValue = input.displayValue.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+            }
+        }
+    }
+    // Handle sys_hub_flow_logic_instance_v2: Object with keys containing arrays
+    else if (typeof valuesData === 'object') {
+        // Iterate over all keys (inputs, outputsToAssign, variables, etc.)
+        for (const [key, arrayValue] of Object.entries(valuesData)) {
+            if (Array.isArray(arrayValue)) {
+                // Process each item in the array
+                for (const item of arrayValue) {
+                    if (item && typeof item === 'object') {
+                        const itemName = item.name || key
+                        const itemValue = item.value
+
+                        // Handle children array for FlowObject fields with datapills
+                        if (item.children && Array.isArray(item.children) && item.children.length > 0) {
+                            // For FlowObjects with children, extract from children only (not parent value)
+                            extractDataPillsFromChildren(item.children, stepUuid, labelCacheMap)
+                        } else {
+                            // For regular fields without children, extract from the value using shared logic
+                            extractPillsFromValue(itemValue, itemName, stepUuid, labelCacheMap)
+                        }
+
+                        // Strip |dataType from pills in-place
+                        if (typeof item.value === 'string') {
+                            item.value = item.value.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+                            item.displayValue = item.displayValue.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    return labelCacheMap
+}
+
+/**
+ * Resolves data pill metadata including label parts, variable definition, and type information.
+ * Handles flow variables, subflow inputs, trigger pills, and forEach item pills.
+ */
+export function resolveDataPillMetadata(
+    segments: string[],
+    flowVarDefMap: Map<string, Record>,
+    subflowInputDefMap: Map<string, Record>,
+    relatedRecords: Record[],
+    triggerData?: { inputs: Map<string, any>; outputs: Map<string, { label: string; type: string }> },
+    forEachMetadataMap?: Map<string, { stepNumber: number; tableName: string | null }>
+    // parentUiId?: string
+): {
+    labelParts: string[]
+    varDef: Record | undefined
+    extractedType: string | null
+} {
+    const labelParts: string[] = []
+    let varDef: Record | undefined
+    let extractedType: string | null = null
+    const [prefix, varName] = segments
+
+    const getLabel = (record: Record | undefined) => record?.get('label')?.ifString()?.asString()?.getValue()
+
+    // Handle forEach item pills (format: "uuid.item.fieldName" or "uuid.item")
+    // Check if prefix is a UUID (forEach instance ui_id)
+    if (prefix && isUuidPrefix(prefix) && varName === 'item' && forEachMetadataMap) {
+        const forEachMetadata = forEachMetadataMap.get(prefix)
+        if (forEachMetadata) {
+            // Build label: "2 - For Each➛Problem Record➛Number"
+            labelParts.push(`${forEachMetadata.stepNumber} - For Each - `)
+
+            // Add table name or generic "Record"
+            if (forEachMetadata.tableName) {
+                labelParts.push(`${forEachMetadata.tableName} Record`)
+            } else {
+                labelParts.push('item')
+            }
+
+            // Add remaining field segments with capitalized names
+            if (segments.length > 2) {
+                const fieldSegments = segments.slice(2).map((segment) =>
+                    segment
+                        .split('_')
+                        .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+                        .join(' ')
+                )
+                labelParts.push(...fieldSegments)
+            }
+        }
+    }
+    // Handle trigger data pills (format: "Created_1.table_name" or "Inbound Email_1.body_text")
+    else if (prefix?.endsWith('_1') && varName && triggerData) {
+        const triggerOutput = triggerData.outputs.get(varName)
+        const triggerName = prefix.slice(0, -2) // Remove "_1" suffix
+        const firstLabelPart = TRIGGER_NAME_TO_LABEL_MAP[triggerName] || `Trigger - ${triggerName}`
+        labelParts.push(firstLabelPart)
+        const tableName = triggerData.inputs.get('table') as string | undefined
+
+        if (varName === 'current') {
+            labelParts.push(`${tableName} Record`)
+            const formattedSegments = segments.slice(2).map((segment) =>
+                segment
+                    .split('_')
+                    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+                    .join(' ')
+            )
+            labelParts.push(...formattedSegments)
+        } else if (triggerOutput) {
+            // Map trigger name to its display label, or construct default if not in map
+            labelParts.push(varName === 'table_name' && tableName ? `${tableName} Table` : triggerOutput.label)
+            extractedType = triggerOutput.type
+        }
+    } else if (prefix === 'flow_variable' && varName) {
+        varDef = flowVarDefMap.get(varName)
+        labelParts.push('Flow Variables')
+        const defLabel = getLabel(varDef)
+        if (defLabel) {
+            labelParts.push(defLabel)
+        }
+
+        if (varDef) {
+            const attributesStr = varDef.get('attributes')?.ifString()?.getValue() ?? ''
+            // const attributes = parseAttributesToObject(attributesStr)
+            const coTypeName = getAttributeValue(attributesStr, 'co_type_name')
+
+            if (coTypeName) {
+                const coRecord = relatedRecords.find(
+                    (rec) =>
+                        rec.getTable() === 'sys_complex_object' &&
+                        rec.get('name')?.asString()?.getValue() === coTypeName
+                )
+
+                if (coRecord) {
+                    extractedType = extractLabelsFromComplexObject(segments, coRecord, labelParts)
+                }
+            }
+        }
+    } else if (prefix === 'subflow' && varName) {
+        varDef = subflowInputDefMap.get(varName)
+        labelParts.push('Input')
+        const defLabel = getLabel(varDef)
+        if (defLabel) {
+            labelParts.push(defLabel)
+        }
+
+        if (varDef) {
+            const attributesStr = varDef.get('attributes')?.ifString()?.getValue() ?? ''
+            const attributes = parseAttributesToObject(attributesStr)
+            const coTypeName = attributes.co_type_name
+
+            if (coTypeName) {
+                const coRecord = relatedRecords.find(
+                    (rec) =>
+                        rec.getTable() === 'sys_complex_object' &&
+                        rec.get('name')?.asString()?.getValue() === coTypeName
+                )
+
+                if (coRecord) {
+                    extractedType = extractLabelsFromComplexObject(segments, coRecord, labelParts)
+                }
+            }
+        }
+    } else {
+        // Handle other data pill types (trigger, inputs, outputs, etc.)
+        // Add all path segments which will be joined with ➛ in processDataPill
+        labelParts.push(...segments)
+    }
+
+    return { labelParts, varDef, extractedType }
+}
+
+/**
+ * Processes a single data pill and enriches it with label, type, and reference metadata
+ */
+function processDataPill(
+    varMeta: any,
+    flowVarDefMap: Map<string, Record>,
+    subflowInputDefMap: Map<string, Record>,
+    relatedRecords: Record[],
+    triggerData?: { inputs: Map<string, any>; outputs: Map<string, { label: string; type: string }> },
+    forEachMetadataMap?: Map<string, { stepNumber: number; tableName: string | null }>
+): void {
+    const varKey = varMeta.name
+    // Now the datapill structure is {{datapill.path|datatype}}, hence we need to split below
+    const segments = varKey.split('.')
+
+    const { labelParts, varDef, extractedType } = resolveDataPillMetadata(
+        segments,
+        flowVarDefMap,
+        subflowInputDefMap,
+        relatedRecords,
+        triggerData,
+        forEachMetadataMap
+    )
+
+    if (labelParts.length > 0) {
+        varMeta.label = labelParts.join('➛')
+    }
+
+    if (extractedType) {
+        varMeta.type = extractedType
+        varMeta.base_type = extractedType
+    }
+
+    // Note: parent_table_name, column_name, and reference are already set
+    // by updateLabelCacheForPill when parsing the pill string metadata
+
+    if (varDef && !varMeta.type) {
+        const internalType = varDef.get('internal_type')?.ifString()?.asString()?.getValue() || varMeta.column_type
+        varMeta.type = internalType
+        varMeta.base_type = internalType
+    }
+
+    if (varDef) {
+        varMeta.reference_table = varDef.get('reference_table')?.ifString()?.asString()?.getValue() || null
+        varMeta.reference_display = varDef.get('reference_display')?.ifString()?.asString()?.getValue() || null
+    }
+}
+
+/**
+ * Extracts and aggregates label cache data from instance record attributes.
+ * Returns a new map with enriched data pill metadata.
+ */
+export function extractLabelCache(
+    flowVarDefMap: Map<string, Record>,
+    subflowInputDefMap: Map<string, Record>,
+    relatedRecords: Record[],
+    existingLabelCacheMap?: Map<string, any>,
+    triggerData?: { inputs: Map<string, any>; outputs: Map<string, { label: string; type: string }> },
+    forEachMetadataMap?: Map<string, { stepNumber: number; tableName: string | null }>
+): Map<string, any> {
+    const labelCacheMap = new Map(existingLabelCacheMap)
+    for (const key of labelCacheMap.keys()) {
+        const varMeta = labelCacheMap.get(key)
+        if (!varMeta.label) {
+            processDataPill(varMeta, flowVarDefMap, subflowInputDefMap, relatedRecords, triggerData, forEachMetadataMap)
+        }
+    }
+    return labelCacheMap
+}
+
+// ============================================================================
+// Instance Data Pill Metadata Generation
+// ============================================================================
+
+/**
+ * Builds data pill metadata attributes for instance records.
+ * Used by action and subflow instances to track data pill usage.
+ *
+ * This metadata is stored in the instance's attributes field and later enriched in
+ * the flow definition's label_cache with proper labels, types, and references.
+ *
+ * @param dataPillMetadata - Map of data pill metadata collected during instance processing
+ * @param instanceUiId - The UUID of the instance
+ * @returns Array of data pill metadata attributes ready for instance record
+ */
+
+export function buildDataPillAttributes(dataPillMetadata: Map<string, any>, instanceUiId: string): any[] {
+    const dataPillAttributes: any[] = []
+    for (const [, pillInfo] of dataPillMetadata.entries()) {
+        dataPillAttributes.push({
+            name: pillInfo.dataPillPath,
+            label: '', // Will be enriched by processDataPill in extractLabelCacheFromAttributes
+            reference: null,
+            reference_display: null,
+            type: 'string',
+            base_type: 'string',
+            parent_table_name: null,
+            column_name: null,
+            choices: [],
+            usedInstances: {
+                [instanceUiId]: [pillInfo.inputFieldName],
+            },
+            attributes: {},
+        })
+    }
+    return dataPillAttributes
+}