@servicenow/sdk-build-plugins 4.7.2 → 4.8.1

package/src/flow/utils/datapill-transformer.ts

@@ -5,11 +5,18 @@ import {
     Shape,
     VariableStatementShape,
     ObjectShape,
+    gunzipSync,
     type Diagnostics,
     type Logger,
 } from '@servicenow/sdk-build-core'
 import { ArrowFunctionShape } from '../../arrow-function-plugin'
-import { FLOW_LOGIC, FLOW_LOGIC_PREFIX } from '../flow-logic/flow-logic-constants'
+import {
+    DO_IN_PARALLEL_BLOCK_SYS_ID,
+    FLOW_LOGIC,
+    FLOW_LOGIC_PREFIX,
+    FLOW_LOGIC_SYS_ID_MAP,
+    TRY_CATCH_CATCH_SYS_ID,
+} from '../flow-logic/flow-logic-constants'
 
 /**
  * Result of datapill transformation
@@ -22,7 +29,7 @@ export interface DatapillTransformResult {
 /**
  * Information about a flow instance shape for processing
  */
-export interface FlowInstanceShapeInfo {
+interface FlowInstanceShapeInfo {
     callExpression: CallExpressionShape
     variableStatement: VariableStatementShape | CallExpressionShape
 }
@@ -57,7 +64,7 @@ export function buildUuidToIdentifierMap(recordToShapeMap: Map<Record, Shape>):
 
     for (const [record, instanceShape] of recordToShapeMap.entries()) {
         // Extract ui_id from the record (this is what datapills reference)
-        const uiId = record.get('ui_id')?.getValue() as string | undefined
+        const uiId = record.get('ui_id')?.ifString()?.getValue()
 
         if (!uiId) {
             continue
@@ -66,6 +73,14 @@ export function buildUuidToIdentifierMap(recordToShapeMap: Map<Record, Shape>):
         // Handle VariableStatementShape (actions/subflows with variable assignments)
         if (instanceShape instanceof VariableStatementShape) {
             const variableStatement = instanceShape.as(VariableStatementShape)
+            const initCallee =
+                variableStatement.getInitializer() instanceof CallExpressionShape
+                    ? (variableStatement.getInitializer() as CallExpressionShape).getCallee()
+                    : undefined
+            if (initCallee === FLOW_LOGIC.DO_IN_PARALLEL || initCallee === FLOW_LOGIC.TRY_CATCH) {
+                continue
+            }
+
             const variableName = variableStatement.getVariableName()
             const callExpression = variableStatement.getInitializer().as(CallExpressionShape)
 
@@ -119,6 +134,227 @@ export function buildUuidToIdentifierMap(recordToShapeMap: Map<Record, Shape>):
     return uuidToIdentifierMap
 }
 
+/**
+ * Build a ui_id → ancestor-chain map for the given instances. Each entry's value is the set of all `ui_id`s in the
+ * record's ancestor chain, including the record itself. Useful when resolving pills: a source record that lives
+ * "inside the same branch" as the target action shares the target's branch `ui_id` in this set, and the bare
+ * identifier can be used (no outer-binding dot-walk needed).
+ */
+function buildAncestorChainMap(allInstances: ReadonlyArray<Record>): Map<string, Set<string>> {
+    const recordByUiId = new Map<string, Record>()
+
+    for (const inst of allInstances) {
+        const ui = inst.get('ui_id')?.ifString()?.getValue()
+        if (ui) {
+            recordByUiId.set(ui, inst)
+        }
+    }
+
+    const chainByUiId = new Map<string, Set<string>>()
+
+    const computeChain = (uiId: string, seen: Set<string>): Set<string> => {
+        const cached = chainByUiId.get(uiId)
+        if (cached) {
+            return cached
+        }
+
+        if (seen.has(uiId)) {
+            return new Set([uiId]) // Cycle guard.
+        }
+
+        seen.add(uiId)
+
+        const chain = new Set<string>([uiId])
+        const rec = recordByUiId.get(uiId)
+        const parent = rec?.get('parent_ui_id')?.ifString()?.getValue()
+        if (parent) {
+            for (const ancestor of computeChain(parent, seen)) {
+                chain.add(ancestor)
+            }
+        }
+
+        chainByUiId.set(uiId, chain)
+        return chain
+    }
+
+    for (const inst of allInstances) {
+        const ui = inst.get('ui_id')?.ifString()?.getValue()
+        if (ui) {
+            computeChain(ui, new Set())
+        }
+    }
+
+    return chainByUiId
+}
+
+/**
+ * Detect whether any action/subflow nested inside a DoInParallel branch or TryCatch arm has its output
+ * referenced from outside that branch/arm. Returns true if hoisting is detected (caller should fall back
+ * to Record() API), false otherwise.
+ */
+export function detectHoistedOutputBindings(allInstances: ReadonlyArray<Record>): boolean {
+    if (allInstances.length === 0) {
+        return false
+    }
+
+    const tryCatchLogicId = FLOW_LOGIC_SYS_ID_MAP[FLOW_LOGIC.TRY_CATCH]
+
+    // Collect ui_ids of all DoInParallel branches and TryCatch arms.
+    const branchUiIds = new Set<string>()
+    for (const inst of allInstances) {
+        if (inst.getTable() !== 'sys_hub_flow_logic_instance_v2') {
+            continue
+        }
+        const logicDef = inst.get('logic_definition')?.ifString()?.getValue()
+        if (
+            logicDef === DO_IN_PARALLEL_BLOCK_SYS_ID ||
+            logicDef === TRY_CATCH_CATCH_SYS_ID ||
+            (tryCatchLogicId && logicDef === tryCatchLogicId)
+        ) {
+            const uiId = inst.get('ui_id')?.ifString()?.getValue()
+            if (uiId) {
+                branchUiIds.add(uiId)
+            }
+        }
+    }
+
+    if (branchUiIds.size === 0) {
+        return false
+    }
+
+    // Build ancestor chain map and reference index.
+    const ancestorChainMap = buildAncestorChainMap(allInstances)
+    const referenceIndex = buildReferenceIndex(allInstances)
+
+    // Map: action/subflow UUID → the branch/arm ui_id that contains it (directly or transitively).
+    // Uses the full ancestor chain so actions nested inside If/ForEach within a branch are also caught.
+    const innerActionBranch = new Map<string, string>()
+    for (const [uuid, record] of uuidToRecordMap.entries()) {
+        const uiId = record.get('ui_id')?.ifString()?.getValue()
+        if (!uiId) {
+            continue
+        }
+        const chain = ancestorChainMap.get(uiId)
+        if (!chain) {
+            continue
+        }
+        for (const branchUiId of branchUiIds) {
+            if (chain.has(branchUiId)) {
+                innerActionBranch.set(uuid, branchUiId)
+                break
+            }
+        }
+    }
+
+    if (innerActionBranch.size === 0) {
+        return false
+    }
+
+    // For each inner action UUID, check if any source record referencing it lives outside its branch.
+    for (const [uuid, branchUiId] of innerActionBranch.entries()) {
+        const sources = referenceIndex.get(uuid)
+        if (!sources) {
+            continue
+        }
+
+        for (const sourceUiId of sources) {
+            if (!sourceUiId) {
+                continue
+            }
+            const ancestorChain = ancestorChainMap.get(sourceUiId)
+            const isInside = ancestorChain ? ancestorChain.has(branchUiId) : false
+            if (!isInside) {
+                return true
+            }
+        }
+    }
+
+    return false
+}
+
+function buildReferenceIndex(allInstances: ReadonlyArray<Record>): Map<string, Set<string | undefined>> {
+    const result = new Map<string, Set<string | undefined>>()
+    const uuidRe = /\{\{(?:step\[)?([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})/g
+    for (const inst of allInstances) {
+        const valuesStr = readValuesForPillScan(inst)
+        if (!valuesStr) {
+            continue
+        }
+
+        const sourceUiId = inst.get('ui_id')?.ifString()?.getValue()
+        for (const m of valuesStr.matchAll(uuidRe)) {
+            const uuid = m[1]
+            if (!uuid) {
+                continue
+            }
+
+            let sources = result.get(uuid)
+            if (!sources) {
+                sources = new Set<string | undefined>()
+                result.set(uuid, sources)
+            }
+
+            sources.add(sourceUiId)
+        }
+    }
+    return result
+}
+
+/**
+ * Read an instance record's `values` column for substring-search of datapill UUIDs. ServiceNow stores the values field
+ * as a gzipped+base64 string. Returns the decompressed JSON-stringified payload, or `undefined` if the column is
+ * missing / unreadable. Errors are swallowed because pill-scan failure is non-critical — the worst case is
+ * over-keeping a binding.
+ */
+// Memoizes the decoded `values` column per record. Decoding gzips (via `gunzipSync`) which is expensive, and the same
+// records are scanned repeatedly — once by `buildReferenceIndex`, once per catch arm in `buildCatchParamMap`, etc.
+// Keyed by Record identity (WeakMap), so entries are collected once a flow's records go out of scope.
+const valuesScanCache = new WeakMap<Record, string | undefined>()
+
+function readValuesForPillScan(record: Record): string | undefined {
+    const cached = valuesScanCache.get(record)
+    if (cached !== undefined || valuesScanCache.has(record)) {
+        return cached
+    }
+
+    const decoded = decodeValuesForPillScan(record)
+    valuesScanCache.set(record, decoded)
+
+    return decoded
+}
+
+function decodeValuesForPillScan(record: Record): string | undefined {
+    const raw = record.get('values')?.getValue()
+    if (raw === undefined || raw === null) {
+        return undefined
+    }
+
+    if (typeof raw !== 'string') {
+        // Already deserialized — stringify so callers can do substring search.
+        try {
+            return JSON.stringify(raw)
+        } catch {
+            return undefined
+        }
+    }
+
+    if (raw === '') {
+        return ''
+    }
+
+    // gzip magic bytes are `H4sI` when base64-encoded. `gunzipSync` (fflate) takes/returns a Uint8Array, so decode the
+    // base64 to bytes on the way in and back to utf8 on the way out.
+    if (raw.startsWith('H4sI')) {
+        try {
+            return Buffer.from(gunzipSync(Buffer.from(raw, 'base64'))).toString('utf8')
+        } catch {
+            return undefined
+        }
+    }
+
+    return raw
+}
+
 /**
  * Extract CallExpression and VariableStatement from an instance shape
  * Handles both VariableStatementShape (for Action/Subflow) and bare CallExpressionShape (for flow logic)
@@ -126,7 +362,7 @@ export function buildUuidToIdentifierMap(recordToShapeMap: Map<Record, Shape>):
  * @param instanceShape - The shape to extract from
  * @returns Object containing callExpression and variableStatement
  */
-export function extractInstanceShapeInfo(instanceShape: Shape): FlowInstanceShapeInfo {
+function extractInstanceShapeInfo(instanceShape: Shape): FlowInstanceShapeInfo {
     let callExpression: CallExpressionShape
     let variableStatement: VariableStatementShape | CallExpressionShape
 
@@ -141,32 +377,6 @@ export function extractInstanceShapeInfo(instanceShape: Shape): FlowInstanceShap
     return { callExpression, variableStatement }
 }
 
-/**
- * Rebuild a CallExpressionShape with transformed properties
- * Creates a new CallExpression with the transformed props and cleaned config
- *
- * @param originalCallExpression - The original CallExpression
- * @param transformedProps - The transformed properties object
- * @param configShape - The config shape (possibly cleaned)
- * @param record - The source record for shape creation
- * @returns New CallExpressionShape with transformed properties
- */
-export function rebuildCallExpressionWithDatapills(
-    originalCallExpression: CallExpressionShape,
-    transformedProps: { [key: string]: Shape },
-    configShape: Shape,
-    record: Record
-): CallExpressionShape {
-    const originalActionDef = originalCallExpression.getArgument(0, false)
-    const newPropsArg = Shape.from(record, transformedProps)
-
-    return new CallExpressionShape({
-        source: originalCallExpression.getSource(),
-        callee: originalCallExpression.getCallee(),
-        args: [originalActionDef, configShape, newPropsArg],
-    })
-}
-
 /**
  * Rebuild an instance shape (VariableStatement or CallExpression) with transformed datapills
  *
@@ -175,7 +385,7 @@ export function rebuildCallExpressionWithDatapills(
  * @param instanceShapeInfo - Information extracted from the instance shape
  * @returns Rebuilt VariableStatementShape or the new CallExpression
  */
-export function rebuildInstanceWithDatapills(
+function rebuildInstanceWithDatapills(
     instanceShape: Shape,
     newCallExpression: CallExpressionShape,
     instanceShapeInfo: FlowInstanceShapeInfo
@@ -203,7 +413,7 @@ export function rebuildInstanceWithDatapills(
  * @param callee - The callee string (e.g., 'wfa.flowLogic.if', 'wfa.action')
  * @returns true if the callee is a flow logic call
  */
-export function isFlowLogicCallee(callee: string): boolean {
+function isFlowLogicCallee(callee: string): boolean {
     return callee.startsWith(FLOW_LOGIC_PREFIX)
 }
 
@@ -212,7 +422,7 @@ export function isFlowLogicCallee(callee: string): boolean {
  * @param callee - The flow logic callee (e.g., 'wfa.flowLogic.if')
  * @returns true if the flow logic has a body
  */
-export function flowLogicHasBody(callee: string): boolean {
+function flowLogicHasBody(callee: string): boolean {
     // Flow logic with bodies: if, elseIf, else, forEach, tryCatch, doInParallel
     // Flow logic without bodies: goBackTo, waitForADuration, exitLoop, endFlow, skipIteration
     return [
@@ -237,7 +447,7 @@ export function flowLogicHasBody(callee: string): boolean {
  * @param callee - The flow logic callee
  * @returns Array of arrow function shapes
  */
-export function extractFlowLogicBodies(callExpression: CallExpressionShape, callee: string): ArrowFunctionShape[] {
+function extractFlowLogicBodies(callExpression: CallExpressionShape, callee: string): ArrowFunctionShape[] {
     const bodies: ArrowFunctionShape[] = []
 
     if (callee === FLOW_LOGIC.TRY_CATCH) {
@@ -288,7 +498,7 @@ export function extractFlowLogicBodies(callExpression: CallExpressionShape, call
  * @param record - The source record
  * @returns Rebuilt CallExpressionShape
  */
-export function rebuildFlowLogicWithDatapills(
+function rebuildFlowLogicWithDatapills(
     callExpression: CallExpressionShape,
     transformedConfig: ObjectShape,
     transformedBodies: ArrowFunctionShape[],
@@ -544,12 +754,14 @@ export function processInstanceForDatapills(
                 }
             }
 
-            // Rebuild body if children changed
+            // Rebuild body if children changed. Preserve the arrow's `returnValue` if present.
+            const returnValue = body.getReturnValue()
             const transformedBody = anyChildChanged
                 ? new ArrowFunctionShape({
                       source: body.getSource(),
                       parameters: body.getParameters(),
                       statements: transformedChildren,
+                      ...(returnValue !== undefined && { returnValue }),
                   })
                 : body
 

package/src/flow/utils/flow-constants.ts

@@ -545,6 +545,14 @@ export const ELEMENT_MAPPING_FIELD_ALIASES: { [platformName: string]: string } =
     __snc_dont_fail_on_error: 'dont_fail_flow_on_error',
 }
 
+/**
+ * Reverse of ELEMENT_MAPPING_FIELD_ALIASES — maps Fluent API names back to their
+ * platform-internal names for serialization into sys_hub_action_instance_v2.
+ */
+export const ELEMENT_MAPPING_FIELD_ALIASES_REVERSE: { [fluentName: string]: string } = Object.fromEntries(
+    Object.entries(ELEMENT_MAPPING_FIELD_ALIASES).map(([platform, fluent]) => [fluent, platform])
+)
+
 export enum ChoiceDropdown {
     DROPDOWN_WITH_NONE = 1,
     DROPDOWN_WITHOUT_NONE = 3,

package/src/flow/utils/flow-io-to-record.ts

@@ -194,6 +194,16 @@ export async function buildVariableRecords(options: {
                     additionalProperties['reference'] = referenceTable
                 }
             }
+
+            // Handle field_list and template_value columns - extract dependent field.
+            // Always write all three fields so that removing 'dependent' from fluent
+            // explicitly clears the old value in ServiceNow rather than leaving it stale.
+            if (internal_type === 'field_list' || internal_type === 'template_value') {
+                const dependent = config.get('dependent')?.ifString()?.getValue() ?? ''
+                additionalProperties['dependent'] = dependent
+                additionalProperties['dependent_on_field'] = dependent
+                additionalProperties['use_dependent_field'] = dependent !== ''
+            }
             additionalProperties['internal_type'] = internal_type
             additionalProperties['max_length'] =
                 config.get('maxLength')?.ifNumber()?.getValue() ?? getDefaultMaxLength(internal_type)
@@ -400,7 +410,11 @@ function buildBasicVariableShape(
     // Add dependent field for template_value and field_list column types
     if (fieldType === 'template_value' || fieldType === 'field_list') {
         const dependent = variable.get('dependent')?.ifString()?.getValue()
-        additionalProps['dependent'] = dependent ?? ''
+        // For field_list, dependent is optional — only emit it when non-empty.
+        // For template_value, dependent is required by its type, so always include it.
+        if (fieldType === 'template_value' || dependent) {
+            additionalProps['dependent'] = dependent ?? ''
+        }
     }
 
     return new CallExpressionShape({
@@ -521,7 +535,7 @@ function validateAndPopulateChoiceProperties(
     }
 
     // Default to dropdown_with_none
-    let choiceValue = ChoiceDropdown.DROPDOWN_WITHOUT_NONE
+    let choiceValue = ChoiceDropdown.DROPDOWN_WITH_NONE
 
     // Handle dropdown type configuration
     const defaultValue = config.get('default')
@@ -531,23 +545,23 @@ function validateAndPopulateChoiceProperties(
         const choiceTypeValue = choiceTypeNode.getValue() as choiceDropdownType
         const choiceDropdownValue = choiceDropdown.indexOf(choiceTypeValue)
 
-        if (choiceDropdownValue === ChoiceDropdown.DROPDOWN_WITHOUT_NONE) {
-            // Validate default value exists for dropdown_without_none
-            if (defaultValue.isUndefined()) {
-                diagnostics.error(config, 'Default value is required for dropdown type "dropdown_without_none"')
-                return
-            }
-            choiceValue = ChoiceDropdown.DROPDOWN_WITHOUT_NONE
-        } else if (choiceDropdownValue !== ChoiceDropdown.DROPDOWN_WITH_NONE) {
-            // Only dropdown_with_none and dropdown_without_none are valid
+        if (choiceDropdownValue === -1) {
+            // Not a recognized dropdown type
             diagnostics.error(
                 choiceTypeNode,
-                'Invalid dropdown type, expected "dropdown_with_none" or "dropdown_without_none"'
+                `Invalid dropdown type "${choiceTypeValue}", expected one of: ${choiceDropdown.join(', ')}`
             )
             return
-        } else {
-            choiceValue = choiceDropdownValue
         }
+
+        // dropdown_without_none has no "--None--" entry, so a default value is required
+        if (choiceDropdownValue === ChoiceDropdown.DROPDOWN_WITHOUT_NONE && defaultValue.isUndefined()) {
+            diagnostics.error(config, 'Default value is required for dropdown type "dropdown_without_none"')
+            return
+        }
+
+        // Preserve whatever valid dropdown type came through (none/with_none/suggestion/without_none)
+        choiceValue = choiceDropdownValue
     }
 
     // Set the choice value

package/src/flow/utils/flow-shapes.ts

@@ -12,6 +12,25 @@ import type { ApprovalRulesType, ApprovalDueDateType } from '@servicenow/sdk-cor
 import { approvalRulesJsonToString, approvalRulesStringToJson } from './approval-rules-processor'
 import { APPROVAL_RULES_API_NAME, APPROVAL_DUE_DATE_API_NAME } from './flow-constants'
 
+/**
+ * Safely extracts a sysId string from a shape that may be either a plain StringShape
+ * or a FK-resolved Record. After build+install the SDK resolves FK fields to Record
+ * objects, so calling .asString() directly would throw.
+ */
+export function getRefSysId(shape: Shape | undefined): string | undefined {
+    if (!shape) {
+        return undefined
+    }
+    const str = shape.ifString()?.getValue()
+    if (str !== undefined) {
+        return str
+    }
+    if (shape instanceof Record) {
+        return shape.getId().getValue()
+    }
+    return undefined
+}
+
 /**
  * Abstract base class for all flow definition instances.
  * Extends CallExpressionShape to provide common functionality for flow constructs.

package/src/flow/utils/flow-variable-processor.ts

@@ -7,9 +7,9 @@ import { buildVariableRecords } from './flow-io-to-record'
 export type VariableTableType = 'sys_hub_flow_input' | 'sys_hub_flow_output' | 'sys_hub_flow_variable'
 
 /**
- * Parent table type (always sys_hub_flow for flows)
+ * Parent table type for flow variable/IO records
  */
-export type ParentTableType = 'sys_hub_flow'
+export type ParentTableType = 'sys_hub_flow' | 'sys_hub_flow_snapshot'
 
 /**
  * Process a flow variable configuration (inputs, outputs, or flow variables)
@@ -27,7 +27,8 @@ export async function processVariableConfig(
     varTable: VariableTableType,
     parentRecord: Record,
     factory: Factory,
-    diagnostics: Diagnostics
+    diagnostics: Diagnostics,
+    parentTable: ParentTableType = 'sys_hub_flow'
 ): Promise<Record[]> {
     if (!config) {
         return []
@@ -38,7 +39,7 @@ export async function processVariableConfig(
         parentRecord,
         factory,
         diagnostics,
-        parentTable: 'sys_hub_flow' as ParentTableType,
+        parentTable,
         varTable,
     })
 
@@ -58,9 +59,10 @@ export async function processFlowInputs(
     inputsConfig: ObjectShape | undefined,
     parentRecord: Record,
     factory: Factory,
-    diagnostics: Diagnostics
+    diagnostics: Diagnostics,
+    parentTable: ParentTableType = 'sys_hub_flow'
 ): Promise<Record[]> {
-    return processVariableConfig(inputsConfig, 'sys_hub_flow_input', parentRecord, factory, diagnostics)
+    return processVariableConfig(inputsConfig, 'sys_hub_flow_input', parentRecord, factory, diagnostics, parentTable)
 }
 
 /**
@@ -76,9 +78,10 @@ export async function processFlowOutputs(
     outputsConfig: ObjectShape | undefined,
     parentRecord: Record,
     factory: Factory,
-    diagnostics: Diagnostics
+    diagnostics: Diagnostics,
+    parentTable: ParentTableType = 'sys_hub_flow'
 ): Promise<Record[]> {
-    return processVariableConfig(outputsConfig, 'sys_hub_flow_output', parentRecord, factory, diagnostics)
+    return processVariableConfig(outputsConfig, 'sys_hub_flow_output', parentRecord, factory, diagnostics, parentTable)
 }
 
 /**
@@ -94,7 +97,15 @@ export async function processFlowVariables(
     flowVariablesConfig: ObjectShape | undefined,
     parentRecord: Record,
     factory: Factory,
-    diagnostics: Diagnostics
+    diagnostics: Diagnostics,
+    parentTable: ParentTableType = 'sys_hub_flow'
 ): Promise<Record[]> {
-    return processVariableConfig(flowVariablesConfig, 'sys_hub_flow_variable', parentRecord, factory, diagnostics)
+    return processVariableConfig(
+        flowVariablesConfig,
+        'sys_hub_flow_variable',
+        parentRecord,
+        factory,
+        diagnostics,
+        parentTable
+    )
 }