@servicenow/sdk-build-plugins 4.7.2 → 4.8.1

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

@@ -36,7 +36,7 @@ import { STEP_PILL_TYPE_REGEX, stripPillType, collectPillTypes } from '../utils/
 import { COLUMN_TYPE_TO_API } from '../../column/column-helper'
 import { buildComplexObjectFromSchema, parseAttributesToObject } from '../utils/schema-to-flow-object'
 import { normalizeInputValue } from './flow-instance-plugin'
-import { ApprovalRulesShape, ApprovalDueDateShape } from '../utils/flow-shapes'
+import { ApprovalRulesShape, ApprovalDueDateShape, getRefSysId } from '../utils/flow-shapes'
 import { ArrowFunctionShape } from '../../arrow-function-plugin'
 import { FDInlineScriptCallShape } from './inline-script-plugin'
 import { StepInstanceShape, StepInstancePlugin } from './step-instance-plugin'
@@ -62,9 +62,7 @@ function resolveInlineScripts(
     allInputScripts: Record[],
     stepInstance: Record
 ): void {
-    const inputScriptRecords = allInputScripts.filter(
-        (r: Record) => r.get('instance')?.asString()?.getValue() === stepSysId
-    )
+    const inputScriptRecords = allInputScripts.filter((r: Record) => getRefSysId(r.get('instance')) === stepSysId)
 
     for (const scriptRecord of inputScriptRecords) {
         const inputName = scriptRecord.get('input_name')?.asString()?.getValue()
@@ -1650,14 +1648,12 @@ export const ActionDefinitionPlugin = Plugin.create({
                 // sys_hub_status_condition holds the individual conditions.
                 const actionStatusMetadata = descendants
                     .query('sys_hub_action_status_metadata')
-                    .filter((r) => r.get('action_type_id')?.asString()?.getValue() === actionSysId)
+                    .filter((r) => getRefSysId(r.get('action_type_id')) === actionSysId)
                 const actionStatusMetadataIds = actionStatusMetadata.map((r) => r.getId().getValue())
                 const statusConditions = descendants
                     .query('sys_hub_status_condition')
                     .filter((r) =>
-                        actionStatusMetadataIds.includes(
-                            r.get('action_status_metadata_id')?.asString()?.getValue() ?? ''
-                        )
+                        actionStatusMetadataIds.includes(getRefSysId(r.get('action_status_metadata_id')) ?? '')
                     )
 
                 // Filter inputs/outputs to only those belonging to this action definition,
@@ -1668,11 +1664,11 @@ export const ActionDefinitionPlugin = Plugin.create({
                     Number(b.get('order')?.asString()?.getValue() ?? 0)
                 const actionInputs = descendants
                     .query('sys_hub_action_input')
-                    .filter((r) => r.get('model')?.asString()?.getValue() === actionSysId)
+                    .filter((r) => getRefSysId(r.get('model')) === actionSysId)
                     .sort(sortByOrder)
                 const actionOutputs = descendants
                     .query('sys_hub_action_output')
-                    .filter((r) => r.get('model')?.asString()?.getValue() === actionSysId)
+                    .filter((r) => getRefSysId(r.get('model')) === actionSysId)
                     .sort(sortByOrder)
 
                 const inputs = buildVariableShapes(actionInputs, descendants)
@@ -1694,7 +1690,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                 // excluding snapshot-parented step instances
                 const stepInstances = descendants
                     .query('sys_hub_step_instance')
-                    .filter((s) => s.get('action')?.asString()?.getValue() === actionSysId)
+                    .filter((s) => getRefSysId(s.get('action')) === actionSysId)
                 const stepShapes: Shape[] = []
                 const cidToIdentifierMap = new Map<string, IdentifierShape>()
 
@@ -1730,7 +1726,7 @@ export const ActionDefinitionPlugin = Plugin.create({
 
                         // Filter variable values for this step instance
                         const stepVarValues = allVariableValues.filter(
-                            (v) => v.get('document_key')?.asString()?.getValue() === stepSysId
+                            (v) => getRefSysId(v.get('document_key')) === stepSysId
                         )
 
                         // Build reverse lookup: element name → uiType
@@ -1764,7 +1760,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                         // Build a lookup of ext input datapill values from element_mappings
                         const extInputMappingValues: globalThis.Record<string, string> = {}
                         const stepElementMappings = allElementMappings.filter(
-                            (m) => m.get('id')?.asString()?.getValue() === stepSysId
+                            (m) => getRefSysId(m.get('id')) === stepSysId
                         )
                         for (const mapping of stepElementMappings) {
                             const rawFieldName = mapping.get('field')?.asString()?.getValue()
@@ -1834,9 +1830,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                         }
 
                         // Build inputVariables from sys_hub_step_ext_input records
-                        const stepExtInputs = allExtInputs.filter(
-                            (r) => r.get('model_id')?.asString()?.getValue() === stepSysId
-                        )
+                        const stepExtInputs = allExtInputs.filter((r) => getRefSysId(r.get('model_id')) === stepSysId)
                         if (stepExtInputs.length > 0) {
                             const inputVariablesObj: Props = {}
                             for (const extInput of stepExtInputs) {
@@ -1849,7 +1843,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                                 // Find value from sys_variable_value or element_mapping (datapill)
                                 // Prioritize pills from sys_element_mapping over static values from sys_variable_value
                                 const varValueRecord = stepVarValues.find(
-                                    (v) => v.get('variable')?.asString()?.getValue() === extInputSysId
+                                    (v) => getRefSysId(v.get('variable')) === extInputSysId
                                 )
                                 const value =
                                     extInputMappingValues[elementName] ??
@@ -1869,9 +1863,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                         }
 
                         // Build outputVariables from sys_hub_step_ext_output records
-                        const stepExtOutputs = allExtOutputs.filter(
-                            (r) => r.get('model_id')?.asString()?.getValue() === stepSysId
-                        )
+                        const stepExtOutputs = allExtOutputs.filter((r) => getRefSysId(r.get('model_id')) === stepSysId)
                         if (stepExtOutputs.length > 0) {
                             const outputVariablesObj: Props = {}
                             for (const extOutput of stepExtOutputs) {
@@ -2085,7 +2077,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                     const candidateIds = new Set<string>([actionSysId])
                     const snapshots = descendants
                         .query('sys_hub_action_type_snapshot')
-                        .filter((s) => s.get('parent_action')?.asString()?.getValue() === actionSysId)
+                        .filter((s) => getRefSysId(s.get('parent_action')) === actionSysId)
                     for (const snap of snapshots) {
                         candidateIds.add(snap.getId().getValue())
                     }
@@ -2095,7 +2087,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                         .query('sys_element_mapping')
                         .filter(
                             (m) =>
-                                candidateIds.has(m.get('id')?.asString()?.getValue() ?? '') &&
+                                candidateIds.has(getRefSysId(m.get('id')) ?? '') &&
                                 (m.get('table')?.asString()?.getValue() ?? '').startsWith(ACTION_OUTPUT_TABLE_PREFIX)
                         )
 
@@ -2104,7 +2096,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                     const varSysIdToElement = new Map<string, string>()
                     const snapshotOutputs = descendants
                         .query('sys_hub_action_output')
-                        .filter((r) => candidateIds.has(r.get('model')?.asString()?.getValue() ?? ''))
+                        .filter((r) => candidateIds.has(getRefSysId(r.get('model')) ?? ''))
                     for (const outputRec of [...snapshotOutputs, ...actionOutputs]) {
                         const element = outputRec.get('element')?.asString()?.getValue()
                         if (element) {
@@ -2193,9 +2185,11 @@ export const ActionDefinitionPlugin = Plugin.create({
                 }
 
                 // Build args: config + optional body with step instances
+                const masterSnapshotId = record.get('master_snapshot')?.ifString()?.getValue()
                 const actionConfig = record.transform(({ $ }) => ({
                     $id: $.val(NowIdShape.from(record)),
                     name: $,
+                    internalName: $.from('internal_name'),
                     annotation: $.def(''),
                     description: $.def(''),
                     access: $.def('public'),
@@ -2203,6 +2197,7 @@ export const ActionDefinitionPlugin = Plugin.create({
                     protectionPolicy: $.from('sys_policy').def(''),
                     inputs: $.val(inputs),
                     outputs: $.val(outputs),
+                    ...(masterSnapshotId ? { masterSnapshot: $.val(masterSnapshotId) } : {}),
                 }))
 
                 const args: unknown[] = [actionConfig]
@@ -2280,12 +2275,14 @@ export const ActionDefinitionPlugin = Plugin.create({
 
                 const inputsConfig = actionConfiguration.get('inputs').ifObject()?.asObject()
 
+                const actionInternalName = actionConfiguration.get('internalName').ifString()?.getValue()
                 let actionDefinitionRecord = await factory.createRecord({
                     source: callExpression,
                     table: 'sys_hub_action_type_definition',
                     explicitId: actionConfiguration.get('$id'),
                     properties: actionConfiguration.transform(({ $ }) => ({
                         name: $,
+                        ...(actionInternalName ? { internal_name: $.val(actionInternalName) } : {}),
                         annotation: $.def(''),
                         description: $.def(''),
                         access: $.def('public'),
@@ -2574,8 +2571,9 @@ export const ActionDefinitionPlugin = Plugin.create({
                 const collectedStepPills = extractStepPillsFromRecords(relatedRecords, cidToLabelMap, pillTypeMap)
                 const dotWalkPills = extractActionDotWalkPills(relatedRecords, pillTypeMap)
 
+                let labelCacheJson: string | undefined
                 if (inputsConfig) {
-                    const labelCacheJson = buildActionLabelCache(inputsConfig, {
+                    labelCacheJson = buildActionLabelCache(inputsConfig, {
                         stepPills: collectedStepPills,
                         dotWalkPills,
                         cidToLabelMap,
@@ -2585,9 +2583,78 @@ export const ActionDefinitionPlugin = Plugin.create({
                     }
                 }
 
+                const masterSnapshotFromConfig = actionConfiguration.get('masterSnapshot')?.ifString()?.getValue()
+
+                if (!masterSnapshotFromConfig) {
+                    return {
+                        success: true,
+                        value: actionDefinitionRecord.with(...relatedRecords),
+                    }
+                }
+
+                let snapshotRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_action_type_snapshot',
+                    explicitId: masterSnapshotFromConfig,
+                    properties: actionConfiguration.transform(({ $ }) => ({
+                        access: $.def('public'),
+                        active: $.val(false),
+                        annotation: $.def(''),
+                        callable_by_client_api: $.val(false),
+                        category: $.def(''),
+                        description: $.def(''),
+                        master: $.val(true),
+                        name: $,
+                        natlang: $.def(''),
+                        parent_action: $.val(actionDefinitionRecord.getId().getValue()),
+                        state: $.val('draft'),
+                        sys_policy: $.from('protectionPolicy').def(''),
+                        system_level: $.val(false),
+                    })),
+                })
+
+                if (labelCacheJson) {
+                    snapshotRecord = snapshotRecord.merge({ label_cache: labelCacheJson })
+                }
+
+                const snapshotRelatedRecords: Record[] = []
+
+                if (inputsConfig) {
+                    const { variableRecords: snapInputRecords, complexObjectRecords: snapInputComplexObjects } =
+                        await buildVariableRecords({
+                            variablesConfig: inputsConfig,
+                            parentRecord: snapshotRecord,
+                            factory,
+                            diagnostics,
+                            parentTable: 'sys_hub_action_type_snapshot',
+                            varTable: 'sys_hub_action_input',
+                        })
+                    snapshotRelatedRecords.push(...snapInputRecords, ...snapInputComplexObjects)
+                }
+
+                if (outputsConfig) {
+                    const { variableRecords: snapOutputRecords, complexObjectRecords: snapOutputComplexObjects } =
+                        await buildVariableRecords({
+                            variablesConfig: outputsConfig,
+                            parentRecord: snapshotRecord,
+                            factory,
+                            diagnostics,
+                            parentTable: 'sys_hub_action_type_snapshot',
+                            varTable: 'sys_hub_action_output',
+                            isOutput: true,
+                        })
+                    snapshotRelatedRecords.push(...snapOutputRecords, ...snapOutputComplexObjects)
+                }
+
+                const snapshotId = snapshotRecord.getId().getValue()
+                const finalActionRecord = actionDefinitionRecord.merge({
+                    latest_snapshot: snapshotId,
+                    master_snapshot: snapshotId,
+                })
+
                 return {
                     success: true,
-                    value: actionDefinitionRecord.with(...relatedRecords),
+                    value: finalActionRecord.with(...relatedRecords, snapshotRecord, ...snapshotRelatedRecords),
                 }
             },
         },

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

@@ -82,7 +82,12 @@ import { isDataPill } from '../utils/complex-object-resolver'
 import { wrapWithDataPillCall, extractDataPillNames } from '../utils/pill-shape-helpers'
 import { ArrayShape } from '@servicenow/sdk-build-core'
 import { processFlowInputs, processFlowOutputs, processFlowVariables } from '../utils/flow-variable-processor'
-import { buildUuidToIdentifierMap, processInstanceForDatapills, uuidToRecordMap } from '../utils/datapill-transformer'
+import {
+    buildUuidToIdentifierMap,
+    detectHoistedOutputBindings,
+    processInstanceForDatapills,
+    uuidToRecordMap,
+} from '../utils/datapill-transformer'
 import {
     DEFAULT_PARAM_NAME,
     PARALLEL_ORDER_SEPARATOR,
@@ -646,7 +651,6 @@ function extractAllPills(
                         })
                     }
                 } else {
-                    // NOT a forEach parameter - preserve full property path
                     expression = new PropertyAccessShape({
                         source,
                         elements: [identifier, property],
@@ -774,6 +778,7 @@ function transformDataPill(
     // {{flowVariables}} and {{outputs}} should remain as bare PropertyAccessShape without wrapping
     if (stringValue === '{{flowVariables}}' || stringValue === '{{outputs}}') {
         const allPills = extractAllPills(stringValue, uuidToIdentifierMap, source, diagnostics, parameterName)
+
         if (allPills.length === 1 && allPills[0]?.expression.is(PropertyAccessShape)) {
             return allPills[0].expression as PropertyAccessShape
         }
@@ -1497,7 +1502,7 @@ function postProcessAssignSubflowOutputs(
     subflowDefinitionRecord: Record,
     logger: Logger
 ): ValuesJSON {
-    if (!valuesJSON || !valuesJSON.outputsToAssign || !Array.isArray(valuesJSON.outputsToAssign)) {
+    if (!valuesJSON?.outputsToAssign || !Array.isArray(valuesJSON.outputsToAssign)) {
         return valuesJSON
     }
 
@@ -1682,6 +1687,8 @@ export const FlowDefinitionPlugin = Plugin.create({
                 return deleteMultipleDiff(existing, incoming, descendants, context)
             },
             async toShape(record, { descendants, diagnostics, transform, database, logger }) {
+                const masterSnapshotId = record.get('master_snapshot')?.ifString()?.getValue()
+
                 let type = record.get('type')?.getValue()
                 if (!type) {
                     logger.warn(`sys_hub_flow record has no type specified, defaulting to 'flow'`)
@@ -1771,6 +1778,15 @@ export const FlowDefinitionPlugin = Plugin.create({
                 // Use recordToShapeMap to access ui_id from records (datapills reference ui_id, not $id)
                 const uuidToIdentifierMap = buildUuidToIdentifierMap(recordToShapeMap)
 
+                // Hoisting guard: if any action nested inside a DoInParallel or TryCatch block has its output
+                // referenced from outside that block, fall back to Record() API.
+                if (detectHoistedOutputBindings(allInstances)) {
+                    logger.warn(
+                        `Hoisting detected: action instance outputs are referenced outside their DoInParallel/TryCatch scope, falling back to Record() api. Flow = ${record.getId().getValue()}`
+                    )
+                    return { success: false }
+                }
+
                 // For the flow body, only use top-level instances (those without parent_ui_id). Also exclude Catch
                 // records — they are subsumed into their paired Try's `wfa.flowLogic.tryCatch(...)` shape via
                 // `connected_to`, and emitting them separately would produce a duplicate top-level statement.
@@ -1830,7 +1846,6 @@ export const FlowDefinitionPlugin = Plugin.create({
                 // 2. Semantic pills: {{trigger.property}}, {{flow_variable.name}} → references to flow parameters (e.g., {{trigger.table_name}} → params.trigger.table_name)
 
                 // Process all instances (Action, Subflow, and Flow Logic) recursively
-                // This handles datapill transformation for all instance types and their nested children
                 instanceShapes.forEach((instanceShape: Shape, index) => {
                     const result = processInstanceForDatapills(
                         instanceShape,
@@ -1848,6 +1863,7 @@ export const FlowDefinitionPlugin = Plugin.create({
                         instanceShapes[index] = result.shape
                     }
                 })
+
                 const flowBody = new ArrowFunctionShape({
                     source: record,
                     parameters: [new IdentifierShape({ source: record, name: paramName })],
@@ -1862,6 +1878,7 @@ export const FlowDefinitionPlugin = Plugin.create({
                         record.transform(({ $ }) => ({
                             $id: $.val(NowIdShape.from(record)),
                             name: $,
+                            internalName: $.from('internal_name'),
                             description: $.def(EMPTY_STRING),
                             protectionPolicy: $.from('sys_policy').def(EMPTY_STRING),
                             runAs: $.from('run_as').def(RUN_AS_DEFAULT),
@@ -1877,6 +1894,7 @@ export const FlowDefinitionPlugin = Plugin.create({
                             flowPriority: $.from('flow_priority')
                                 .map((p) => p.ifString()?.getValue() || FLOW_PRIORITY_DEFAULT)
                                 .def(FLOW_PRIORITY_DEFAULT),
+                            ...(masterSnapshotId ? { masterSnapshot: $.val(masterSnapshotId) } : {}),
                             ...(isSubflow
                                 ? {
                                       annotation: $.def(EMPTY_STRING),
@@ -1975,12 +1993,14 @@ export const FlowDefinitionPlugin = Plugin.create({
                 }
 
                 const roles = flowConfiguration.get('runWithRoles').ifArray()?.getElements() ?? []
+                const internalName = flowConfiguration.get('internalName').ifString()?.getValue()
                 const flowDefinitionRecord = await factory.createRecord({
                     source: callExpression,
                     table: 'sys_hub_flow',
                     explicitId: flowConfiguration.get('$id'),
                     properties: flowConfiguration.transform(({ $ }) => ({
                         name: $,
+                        ...(internalName ? { internal_name: $.val(internalName) } : {}),
                         annotation: $.def(EMPTY_STRING),
                         description: $.def(EMPTY_STRING),
                         access: $.def(ACCESS_DEFAULT),
@@ -2046,9 +2066,11 @@ export const FlowDefinitionPlugin = Plugin.create({
                     relatedRecords.push(...flowVarRecords)
                 }
 
+                const inputsConfig = isSubflow ? flowConfiguration.get('inputs').ifObject()?.asObject() : undefined
+                const outputsConfig = isSubflow ? flowConfiguration.get('outputs').ifObject()?.asObject() : undefined
+
                 if (isSubflow) {
                     // Process subflow inputs and outputs
-                    const inputsConfig = flowConfiguration.get('inputs').ifObject()?.asObject()
                     const inputRecords = await processFlowInputs(
                         inputsConfig,
                         flowDefinitionRecord,
@@ -2057,7 +2079,6 @@ export const FlowDefinitionPlugin = Plugin.create({
                     )
                     relatedRecords.push(...inputRecords)
 
-                    const outputsConfig = flowConfiguration.get('outputs').ifObject()?.asObject()
                     const outputRecords = await processFlowOutputs(
                         outputsConfig,
                         flowDefinitionRecord,
@@ -2260,16 +2281,101 @@ export const FlowDefinitionPlugin = Plugin.create({
                 )
 
                 const labelCacheData = Array.from(labelCacheMap.values())
+                const labelCacheValue = labelCacheData.length > 0 ? JSON.stringify(labelCacheData) : '[]'
+
                 const flowDefWithMetadata =
                     labelCacheData.length > 0
                         ? flowDefinitionRecord.merge({
-                              label_cache: JSON.stringify(labelCacheData),
+                              label_cache: labelCacheValue,
                           })
                         : flowDefinitionRecord
 
+                const masterSnapshotFromConfig = flowConfiguration.get('masterSnapshot')?.ifString()?.getValue()
+
+                if (!masterSnapshotFromConfig) {
+                    return {
+                        success: true,
+                        value: flowDefWithMetadata.with(...relatedRecords),
+                    }
+                }
+
+                const snapshotRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_flow_snapshot',
+                    explicitId: masterSnapshotFromConfig,
+                    properties: flowConfiguration.transform(({ $ }) => ({
+                        access: $.def(ACCESS_DEFAULT),
+                        active: $.val(false),
+                        allow_high_security_roles: $.def(BOOLEAN_FALSE_STRING),
+                        annotation: $.def(EMPTY_STRING),
+                        attributes: $.def(EMPTY_STRING),
+                        callable_by_client_api: $.def(BOOLEAN_FALSE_STRING),
+                        category: $.def(EMPTY_STRING),
+                        description: $.def(EMPTY_STRING),
+                        flow_priority: $.from('flowPriority').def(FLOW_PRIORITY_DEFAULT),
+                        label_cache: $.val(labelCacheValue),
+                        master: $.val(true),
+                        name: $,
+                        natlang: $.def(EMPTY_STRING),
+                        outputs: $.def(EMPTY_STRING),
+                        parent_flow: $.val(flowDefinitionRecord.getId().getValue()),
+                        remote_trigger_id: $.def(EMPTY_STRING),
+                        run_as: $.from('runAs').def(RUN_AS_DEFAULT),
+                        run_with_roles: $.val(
+                            Array.from(
+                                new Set(roles.map((r) => r.ifRecord()?.getId().getValue() ?? r.getValue()))
+                            ).join(',')
+                        ),
+                        sc_callable: $.def(BOOLEAN_FALSE_STRING),
+                        status: $.val(FLOW_STATUS_DRAFT),
+                        sys_policy: $.from('protectionPolicy').def(EMPTY_STRING),
+                        type: isFlow ? $.def(FLOW_TYPE_FLOW) : $.def(FLOW_TYPE_SUBFLOW),
+                        version: $.def(FLOW_VERSION),
+                    })),
+                })
+
+                const snapshotRelatedRecords: Record[] = []
+
+                if (isSubflow) {
+                    const snapshotInputRecords = await processFlowInputs(
+                        inputsConfig,
+                        snapshotRecord,
+                        factory,
+                        diagnostics,
+                        'sys_hub_flow_snapshot'
+                    )
+                    snapshotRelatedRecords.push(...snapshotInputRecords)
+
+                    const snapshotOutputRecords = await processFlowOutputs(
+                        outputsConfig,
+                        snapshotRecord,
+                        factory,
+                        diagnostics,
+                        'sys_hub_flow_snapshot'
+                    )
+                    snapshotRelatedRecords.push(...snapshotOutputRecords)
+                }
+
+                if (flowConfiguration.has('flowVariables')) {
+                    const snapshotVarRecords = await processFlowVariables(
+                        flowConfiguration.get('flowVariables').asObject(),
+                        snapshotRecord,
+                        factory,
+                        diagnostics,
+                        'sys_hub_flow_snapshot'
+                    )
+                    snapshotRelatedRecords.push(...snapshotVarRecords)
+                }
+
+                const snapshotId = snapshotRecord.getId().getValue()
+                const finalFlowRecord = flowDefWithMetadata.merge({
+                    latest_snapshot: snapshotId,
+                    master_snapshot: snapshotId,
+                })
+
                 return {
                     success: true,
-                    value: flowDefWithMetadata.with(...relatedRecords),
+                    value: finalFlowRecord.with(...relatedRecords, snapshotRecord, ...snapshotRelatedRecords),
                 }
             },
         },