@servicenow/sdk-build-plugins 4.4.1 → 4.6.0

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

@@ -1,4 +1,5 @@
 import type { Logger } from '@servicenow/sdk-build-core'
+import { parseSinglePill } from './pill-string-parser'
 
 interface LabelCacheEntry {
     name: string
@@ -13,10 +14,20 @@ interface LabelCacheEntry {
     attributes?: Record<string, string>
 }
 
+/** Action label cache uses pill category ("action", "step", "static") as the type field */
+const ACTION_PILL_CATEGORIES = new Set(['action', 'step', 'static'])
+
 /**
- * Creates a map of name to type from a label_cache string
+ * Creates a map of name to type from a label_cache string.
+ *
+ * Flow/subflow label cache entries use the actual data type in the `type` field and
+ * plain names without braces (e.g., name="flow_variable.userName", type="string").
+ *
+ * Action label cache entries use a pill category in `type` (e.g., "action") and store the
+ * actual data type in `base_type`. Names include braces (e.g., "{{action.variable}}").
+ *
  * @param labelCacheString - The stringified JSON array from label_cache
- * @returns Map where key is the name field and value is the type field
+ * @returns Map where key is the pill name (without braces) and value is the data type
  */
 export function createLableCacheNameToTypeMap(labelCacheString: string, logger: Logger): Map<string, string> {
     const nameToTypeMap = new Map<string, string>()
@@ -25,8 +36,26 @@ export function createLableCacheNameToTypeMap(labelCacheString: string, logger:
         const entries: LabelCacheEntry[] = JSON.parse(labelCacheString)
 
         for (const entry of entries) {
-            if (entry.name && entry.type) {
-                nameToTypeMap.set(entry.name, entry.type)
+            if (!entry.name) {
+                continue
+            }
+
+            if (ACTION_PILL_CATEGORIES.has(entry.type)) {
+                // Action label cache: strip braces from name, use base_type for actual data type
+                const parsed = parseSinglePill(entry.name, true)
+                const key = parsed ? `${parsed.prefix}.${parsed.path}` : entry.name
+                nameToTypeMap.set(key, entry.base_type || 'string')
+            } else if (entry.type) {
+                // Flow/subflow label cache: name is plain, type is the actual data type
+                let type = entry.type
+                // DEF0792627: The platform sometimes stores 'reference' for the sys_id field
+                // when the pill is used in a reference field context (e.g., sysapproval).
+                // sys_id is always a string/GUID field never a reference — except for
+                // step output Record.sys_id which IS a reference to the record itself.
+                if (type === 'reference' && entry.name.endsWith('.sys_id') && !entry.name.includes('.Record.sys_id')) {
+                    type = 'string'
+                }
+                nameToTypeMap.set(entry.name, type)
             }
         }
     } catch (error) {

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

@@ -78,6 +78,15 @@ export function extractTriggerInputs(triggerInstanceShape: CallExpressionShape |
     return triggerInputsMap
 }
 
+/**
+ * Maps FlowArray/FlowObject callee names to their base internal types,
+ * consistent with complex-objects.ts uiType logic.
+ */
+export const COMPLEX_OBJECT_TYPE: globalThis.Record<string, string> = {
+    FlowObject: 'object',
+    FlowArray: 'array.object',
+}
+
 /**
  * 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
@@ -123,7 +132,7 @@ export function extractTriggerOutputs(
         const columnApiName = lastDotIndex >= 0 ? callee.substring(lastDotIndex + 1) : callee
 
         // Map to internal type
-        const internalType = COLUMN_API_TO_TYPE[columnApiName] || columnApiName
+        const internalType = COLUMN_API_TO_TYPE[columnApiName] || COMPLEX_OBJECT_TYPE[columnApiName] || columnApiName
         if (!internalType) {
             continue
         }
@@ -536,9 +545,12 @@ function extractDataPillsFromChildren(children: any[], stepUuid: string, labelCa
         // Extract datapills from this child's value using shared logic
         extractPillsFromValue(child.value, child.name, stepUuid, labelCacheMap)
 
-        // Strip |dataType from pills in-place
+        // Strip |dataType from pills in-place (both value and displayValue, same as parent-level entries)
         if (typeof child.value === 'string') {
             child.value = child.value.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+            if (typeof child.displayValue === 'string') {
+                child.displayValue = child.displayValue.replace(STRIP_DATATYPE_FROM_PILL_REGEX, '{{$1}}')
+            }
         }
 
         // Recursively process nested children (for nested FlowObjects)

package/src/flow/utils/pill-shape-helpers.ts

@@ -0,0 +1,42 @@
+import {
+    CallExpressionShape,
+    type IdentifierShape,
+    type PropertyAccessShape,
+    StringLiteralShape,
+    type Source,
+} from '@servicenow/sdk-build-core'
+
+/**
+ * Wraps a PropertyAccessShape or IdentifierShape with wfa.dataPill(expression, type).
+ * Used by both flow-definition-plugin and flow-action-definition-plugin.
+ *
+ * @param expression - The property access or identifier to wrap
+ * @param source - Source for the shape
+ * @param dataType - The data type for the pill
+ */
+export function wrapWithDataPillCall(
+    expression: PropertyAccessShape | IdentifierShape,
+    source: Source,
+    dataType = 'string'
+): CallExpressionShape {
+    return new CallExpressionShape({
+        source,
+        callee: 'wfa.dataPill',
+        args: [expression, new StringLiteralShape({ source, literalText: dataType })],
+    })
+}
+
+/**
+ * Extracts all datapill names (without type annotations) from a string containing {{...}} patterns.
+ * Used by both flow-definition-plugin and flow-action-definition-plugin.
+ */
+export function extractDataPillNames(stringValue: string): string[] {
+    const names: string[] = []
+    for (const match of stringValue.matchAll(/\{\{([^}]+)\}\}/g)) {
+        const pillContent = match[1]?.split('|')[0]
+        if (pillContent) {
+            names.push(pillContent)
+        }
+    }
+    return names
+}

package/src/flow/utils/pill-string-parser.ts

@@ -121,6 +121,7 @@ export function mapPillPrefixToTsRoot(prefix: string, parameterName: string = 'p
         inputs: `${parameterName}.inputs`,
         outputs: `${parameterName}.outputs`, // Schema reference (no property access)
         subflow: `${parameterName}.inputs`, // ServiceNow uses {{subflow.x}} for subflow inputs
+        action: `${parameterName}.inputs`, // ServiceNow uses {{action.x}} for action inputs → params.inputs.x
 
         // Record triggers (prefixed with trigger name + _1)
         Created_1: `${parameterName}.trigger`,

package/src/flow/utils/schema-to-flow-object.ts

@@ -38,20 +38,129 @@ const SCHEMA_TYPE_TO_COLUMN_API: Record<string, string> = {
     reference: ReferenceColumn.name,
 }
 
+// ------------------------------------------------------------
+// Snapshot value extraction helpers
+// ------------------------------------------------------------
+
+/**
+ * Recursively walk a snapshot's `complexObjectSchema` and extract all
+ * datapill mappings from `mapped` fields inside `$field_facets.SimpleMapFacet`.
+ */
+export function extractAllMappedValues(obj: any, result: globalThis.Record<string, string>): void {
+    if (typeof obj !== 'object' || obj === null) {
+        return
+    }
+
+    if (Array.isArray(obj)) {
+        for (const item of obj) {
+            extractAllMappedValues(item, result)
+        }
+        return
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.endsWith('.$field_facets')) {
+            const facet = (value as any)?.SimpleMapFacet
+            if (facet) {
+                try {
+                    const parsed = JSON.parse(facet)
+                    if (parsed.mapped) {
+                        const mappedObj = JSON.parse(parsed.mapped)
+                        for (const [childName, datapill] of Object.entries(mappedObj)) {
+                            if (typeof datapill === 'string' && datapill) {
+                                result[childName] = datapill
+                            }
+                        }
+                    }
+                } catch {
+                    // skip unparseable facets
+                }
+            }
+        } else if (typeof value === 'object' && value !== null) {
+            extractAllMappedValues(value, result)
+        }
+    }
+}
+
+/**
+ * Recursively walk a snapshot's `complexObject` and extract static values
+ * from `{ $cv: { $c: "type", $v: "value" } }` structures.
+ */
+function extractAllStaticValues(obj: any, result: globalThis.Record<string, string>): void {
+    if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
+        return
+    }
+
+    for (const [key, value] of Object.entries(obj)) {
+        if (key.startsWith('$') || key.endsWith('$')) {
+            continue
+        }
+        if (typeof value === 'object' && value !== null && (value as any).$cv) {
+            const staticVal = (value as any).$cv.$v
+            if (staticVal !== undefined && staticVal !== '') {
+                result[key] = String(staticVal)
+            }
+        } else if (typeof value === 'object' && value !== null) {
+            extractAllStaticValues(value, result)
+        }
+    }
+}
+
+/**
+ * Parse a snapshot value JSON for a complex object output and extract
+ * per-child value mappings (datapills take priority over static values).
+ */
+function parseSnapshotChildValues(snapshotValue: string | undefined): globalThis.Record<string, string> {
+    if (!snapshotValue) {
+        return {}
+    }
+
+    try {
+        const parsed = JSON.parse(snapshotValue)
+        const result: globalThis.Record<string, string> = {}
+
+        // Extract datapill mappings from schema (higher priority)
+        const schema = parsed.complexObjectSchema
+        if (schema) {
+            extractAllMappedValues(schema, result)
+        }
+
+        // Extract static values from complexObject (lower priority — only if no datapill)
+        const complexObj = parsed.complexObject
+        if (complexObj) {
+            const staticValues: globalThis.Record<string, string> = {}
+            extractAllStaticValues(complexObj, staticValues)
+            for (const [k, v] of Object.entries(staticValues)) {
+                if (!result[k]) {
+                    result[k] = v
+                }
+            }
+        }
+
+        return result
+    } catch {
+        return {}
+    }
+}
+
 /**
  * Build a `CallExpressionShape` for a simple (non-object) field given its
  * schema primitive type and associated facets.
  */
-function buildPrimitiveFieldCallExpr(fieldFacet: ObjectShape, source: FluentRecord): CallExpressionShape {
+function buildPrimitiveFieldCallExpr(
+    fieldFacet: ObjectShape,
+    source: FluentRecord,
+    childValue?: string
+): CallExpressionShape {
     const childType = fieldFacet.get('childType').ifDefined()?.asString()?.getValue()
     const schemaType = childType ?? fieldFacet.get('type')?.asString()?.getValue()
     const callee = SCHEMA_TYPE_TO_COLUMN_API[schemaType] ?? StringColumn.name
 
     const additionalProps: globalThis.Record<string, unknown> = {}
 
-    // Extract referenceTable for ReferenceColumn type
+    // Extract referenceTable for reference and records column types
     const referenceTable = fieldFacet.get('reference')?.ifString()?.getValue()
-    if (referenceTable && schemaType === 'reference') {
+    if (referenceTable && (schemaType === 'reference' || schemaType === 'records')) {
         additionalProps['referenceTable'] = referenceTable
     }
 
@@ -99,6 +208,7 @@ function buildPrimitiveFieldCallExpr(fieldFacet: ObjectShape, source: FluentReco
                             })
                             .def(choiceDropdown[ChoiceDropdown.DROPDOWN_WITH_NONE]),
                     }),
+                    ...(childValue ? { default: $.val(childValue) } : {}),
                 }))
                 .merge(additionalProps),
         ],
@@ -115,7 +225,8 @@ function buildFlowArrayFromSchema(
     source: FluentRecord,
     parentTypeFacet: ObjectShape,
     complexObjectSysId?: string,
-    co_type_name?: string
+    co_type_name?: string,
+    childValues?: globalThis.Record<string, string>
 ): CallExpressionShape {
     const rootContent = schemaContent['$COCollectionField']
     if (!rootContent) {
@@ -129,7 +240,14 @@ function buildFlowArrayFromSchema(
     let elementType: CallExpressionShape
     if (type === 'array.object') {
         const childKey = parentTypeFacet.get('childName')?.asString()?.getValue()
-        elementType = buildFlowObjectFromSchema(rootContent[0][childKey], source, rootTypeFacet)
+        elementType = buildFlowObjectFromSchema(
+            rootContent[0][childKey],
+            source,
+            rootTypeFacet,
+            undefined,
+            undefined,
+            childValues
+        )
     } else {
         elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
     }
@@ -163,7 +281,8 @@ function buildFlowArrayFromSchema(
 function buildNestedFlowArrayFromSchema(
     schemaContent: Record<string, any>,
     source: FluentRecord,
-    parentTypeFacet: ObjectShape
+    parentTypeFacet: ObjectShape,
+    childValues?: globalThis.Record<string, string>
 ): CallExpressionShape {
     const type = parentTypeFacet.get('type')?.asString()?.getValue()
     let elementType: CallExpressionShape
@@ -175,7 +294,14 @@ function buildNestedFlowArrayFromSchema(
         const keys = Object.keys(schemaContent)
         const wrapperKey = keys.find((k) => /^\$\d+_/.test(k)) ?? keys.find((k) => !k.endsWith('.$field_facets'))
         const innerContent = wrapperKey ? schemaContent[wrapperKey] : schemaContent
-        elementType = buildFlowObjectFromSchema(innerContent, source, parentTypeFacet)
+        elementType = buildFlowObjectFromSchema(
+            innerContent,
+            source,
+            parentTypeFacet,
+            undefined,
+            undefined,
+            childValues
+        )
     } else {
         elementType = buildPrimitiveFieldCallExpr(parentTypeFacet, source)
     }
@@ -214,7 +340,9 @@ function buildFlowObjectFromSchema(
     source: FluentRecord,
     parentTypeFacet: ObjectShape,
     complexObjectSysId?: string,
-    co_type_name?: string
+    co_type_name?: string,
+    childValues?: globalThis.Record<string, string>,
+    topLevelDefault?: string
 ): CallExpressionShape {
     const properties: Record<string, unknown> = {}
 
@@ -230,15 +358,22 @@ function buildFlowObjectFromSchema(
                 throw new Error(`Invalid complex object schema: ${key} facet not found`)
             }
             if (typeof value === 'string') {
-                // Primitive field
-                properties[key] = buildPrimitiveFieldCallExpr(fieldFacet, source)
+                // Primitive field — pass per-child snapshot value if available
+                properties[key] = buildPrimitiveFieldCallExpr(fieldFacet, source, childValues?.[key])
             } else if (typeof value === 'object' && value !== null) {
                 if (Array.isArray(value)) {
                     // Nested FlowArray
-                    properties[key] = buildNestedFlowArrayFromSchema(value[0], source, fieldFacet)
+                    properties[key] = buildNestedFlowArrayFromSchema(value[0], source, fieldFacet, childValues)
                 } else {
                     // Nested FlowObject
-                    properties[key] = buildFlowObjectFromSchema(value, source, fieldFacet)
+                    properties[key] = buildFlowObjectFromSchema(
+                        value,
+                        source,
+                        fieldFacet,
+                        undefined,
+                        undefined,
+                        childValues
+                    )
                 }
             }
         }
@@ -256,6 +391,7 @@ function buildFlowObjectFromSchema(
                     .map((label, child) => (child.isDefined() ? child : label))
                     .def(''),
                 mandatory: $.toBoolean().def(false),
+                ...(topLevelDefault ? { default: $.val(topLevelDefault) } : {}),
             })),
         ],
     })
@@ -274,7 +410,8 @@ export function buildComplexObjectFromSchema(
     schema: Record<string, any>,
     attributes: COAttributes,
     complexObjectSysId?: string,
-    co_type_name?: string
+    co_type_name?: string,
+    snapshotValue?: string
 ): CallExpressionShape {
     const { co_type_name: attrCoTypeName, uiType, ...rest } = attributes
     const rootKey = `FlowDesigner:${attrCoTypeName}`
@@ -292,11 +429,42 @@ export function buildComplexObjectFromSchema(
         type: uiType,
         ...rest,
     })
+    // Parse snapshot value into per-child value mappings (datapills and static values)
+    const childValues = parseSnapshotChildValues(snapshotValue)
+    const hasChildValues = Object.keys(childValues).length > 0 ? childValues : undefined
+
+    // Detect plain-string snapshot values (e.g. a whole-object datapill like
+    // {{step[UUID].__step_status__}}) that are not valid JSON complex-object
+    // structures. These map to a top-level `default` on the FlowObject.
+    let topLevelDefault: string | undefined
+    if (snapshotValue && !hasChildValues) {
+        try {
+            JSON.parse(snapshotValue)
+        } catch {
+            topLevelDefault = snapshotValue
+        }
+    }
+
     // Pass the explicit co_type_name parameter (undefined for deterministic, value for non-deterministic)
     if (uiType.startsWith('array.')) {
-        return buildFlowArrayFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+        return buildFlowArrayFromSchema(
+            rootContent,
+            source,
+            rootTypeFacet,
+            complexObjectSysId,
+            co_type_name,
+            hasChildValues
+        )
     }
-    return buildFlowObjectFromSchema(rootContent, source, rootTypeFacet, complexObjectSysId, co_type_name)
+    return buildFlowObjectFromSchema(
+        rootContent,
+        source,
+        rootTypeFacet,
+        complexObjectSysId,
+        co_type_name,
+        hasChildValues,
+        topLevelDefault
+    )
 }
 
 function parseTypeFacet(source: FluentRecord, schema: Record<string, any>, key: string): ObjectShape | undefined {

package/src/flow/utils/service-catalog.ts

@@ -32,7 +32,11 @@ import {
  * @returns true if the action is getCatalogVariables or createCatalogTask, false otherwise
  */
 export function isCatalogAction(actionDefinition: Shape | undefined): boolean {
-    const actionName = CORE_ACTIONS_SYS_ID_NAME_MAP[actionDefinition?.getValue() as string]
+    // When actionDefinition is a Record (during XML→Fluent transform), getValue() returns
+    // the record's data object, not its sys_id. Use getId() to extract the sys_id in that case.
+    // When it's a StringShape (raw XML import without existing Fluent project), getValue() returns the sys_id string directly.
+    const sysId = actionDefinition?.ifRecord()?.getId().getValue() ?? actionDefinition?.ifString()?.getValue()
+    const actionName = CORE_ACTIONS_SYS_ID_NAME_MAP[sysId || '']
     return actionName ? CATALOG_VARIABLE_ACTIONS.includes(actionName) : false
 }
 
@@ -140,7 +144,6 @@ export function convertSlushBucketToCatalogVariableArray(
             variableRecordBySysId.set(rec.getId().getValue(), rec)
         }
     }
-
     for (const entry of entries) {
         const [sysId] = entry.split(':')
         if (!sysId || !sysId.trim()) {

package/src/flow/utils/utils.ts

@@ -20,7 +20,13 @@ import { CallExpressionPlugin } from '../../call-expression-plugin'
 import { FlowLogicPlugin } from '../flow-logic/flow-logic-plugin'
 import { FlowInstancePlugin } from '../plugins/flow-instance-plugin'
 import { FDInstanceShape } from './flow-shapes'
-import { CORE_ACTIONS_PREFIX, CORE_ACTIONS_SYS_ID_NAME_MAP, UNSUPPORTED_FLOW_DESCENDANTS } from './flow-constants'
+import {
+    CORE_ACTIONS_PREFIX,
+    CORE_ACTIONS_SYS_ID_NAME_MAP,
+    BUILT_IN_STEP_PREFIX,
+    BUILT_IN_STEP_SYS_ID_NAME_MAP,
+    UNSUPPORTED_FLOW_DESCENDANTS,
+} from './flow-constants'
 
 export function sysIdToUuid(id: string): string {
     return id.length === 32
@@ -383,6 +389,11 @@ export const getCoreActionIdentifier = (sysId: string) => {
     return actionName ? `${CORE_ACTIONS_PREFIX}.${actionName}` : undefined
 }
 
+export const getBuiltInStepIdentifier = (sysId: string) => {
+    const stepName = BUILT_IN_STEP_SYS_ID_NAME_MAP[sysId]
+    return stepName ? `${BUILT_IN_STEP_PREFIX}.${stepName}` : undefined
+}
+
 /**
  * Extracts the order value from a record for sorting purposes.
  * Converts the 'order' field to a number, defaulting to 0 if not present or invalid.