@servicenow/sdk-build-plugins 4.5.0 → 4.6.0

package/src/flow/plugins/flow-data-pill-plugin.ts

@@ -91,10 +91,13 @@ export function determineRootIdentifierAndPath(
     let pathStr = ''
 
     switch (propertyNames[1]) {
-        case 'inputs':
-            rootIdentifier = 'subflow' // <-- Hardcoded: But need to handle if this input is in action/subflow body when we do action body impl.
+        case 'inputs': {
+            // Detect if inside Action() body → emit {{action.xxx}}, otherwise {{subflow.xxx}}
+            const actionAncestor = findAncestorByCalleeName(propertyAccessShape.getOriginalNode(), 'Action')
+            rootIdentifier = actionAncestor ? 'action' : 'subflow'
             pathStr = propertyNames.slice(2).join('.')
             break
+        }
         case 'flowVariables':
             // For params.flowVariables (schema reference), use 'flowVariables' as identifier with empty path
             // For params.flowVariables.someVar (property access), use 'flow_variable' as identifier

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

@@ -17,7 +17,6 @@ import {
     type Diagnostics,
     ts,
     deleteMultipleDiff,
-    StringLiteralShape,
     type Logger,
 } from '@servicenow/sdk-build-core'
 import { gzipSync } from 'node:zlib'
@@ -55,6 +54,7 @@ import {
     createPropertyAccessFromPath,
 } from '../utils/pill-string-parser'
 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'
@@ -211,7 +211,7 @@ import { ApprovalDueDateShape, ApprovalRulesShape } from '../utils/flow-shapes'
 
 /**
  * Traverse ancestors to find the topmost ArrowFunction and extract its parameter name
- * This finds the ArrowFunction that's an argument to Flow/SubflowDefinition, ignoring nested
+ * This finds the ArrowFunction that's an argument to Flow/Subflow, ignoring nested
  * ArrowFunctions from control flow APIs like If, ElseIf, ForEach.
  *
  * @param shape - The shape to start traversing from
@@ -446,45 +446,6 @@ function processShapeForDatapills(
  * @param dataType - The data type string (default: 'string')
  * @returns CallExpressionShape wrapping the expression with wfa.dataPill()
  */
-function wrapWithDataPillCall(
-    expression: PropertyAccessShape | IdentifierShape,
-    source: Record,
-    dataType = 'string'
-): CallExpressionShape {
-    return new CallExpressionShape({
-        source,
-        callee: 'wfa.dataPill',
-        args: [expression, new StringLiteralShape({ source, literalText: dataType })],
-    })
-}
-
-/**
- * Extract all datapill names from a string value containing datapill patterns
- * Handles both UUID-based pills ({{uuid.property}}) and semantic pills ({{prefix.path}})
- *
- * @param stringValue - String that may contain datapill patterns
- * @returns Array of datapill names (e.g., ["trigger.table_name", "uuid.record.number"])
- */
-function extractDataPillNames(stringValue: string): string[] {
-    const dataPillNames: string[] = []
-
-    // Match all datapill patterns: {{...}}
-    const pillPattern = /\{\{([^}]+)\}\}/g
-    const matches = Array.from(stringValue.matchAll(pillPattern))
-
-    for (const match of matches) {
-        if (match[1]) {
-            // Extract the content inside {{}} and split by | to get just the name part
-            // (some pills may have type info like {{pill.name|string}})
-            const pillContent = match[1].split('|')[0]
-            if (pillContent) {
-                dataPillNames.push(pillContent)
-            }
-        }
-    }
-
-    return dataPillNames
-}
 
 /**
  * Wrap all PropertyAccessShape expressions in a TemplateExpressionShape with wfa.dataPill()
@@ -615,16 +576,17 @@ function extractAllPills(
         const pipeIndex = content.indexOf('|')
         const cleanContent = pipeIndex !== -1 ? content.substring(0, pipeIndex) : content
 
-        // Try UUID pattern first (more specific)
-        // UUID format: 8-4-4-4-12 hex digits followed by dot and property path
+        // Match UUID-based pills: both bare UUID (action/subflow outputs) and step[UUID] (action step outputs)
+        // Bare:  {{uuid.property}}           → e.g., action/subflow instance output
+        // Step:  {{step[uuid].property}}     → e.g., action step output
         const uuidMatch = cleanContent.match(
-            /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([a-zA-Z_][a-zA-Z0-9_.]*[a-zA-Z0-9_])$/
+            /^(?:step\[([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\]|([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}))\.([a-zA-Z_][a-zA-Z0-9_.]*[a-zA-Z0-9_])$/
         )
 
         if (uuidMatch) {
             // This is a UUID-based pill
-            const uuid = uuidMatch[1]
-            const property = uuidMatch[2]
+            const uuid = uuidMatch[1] ?? uuidMatch[2]
+            const property = uuidMatch[3]
 
             if (!uuid || !property) {
                 continue
@@ -633,7 +595,10 @@ function extractAllPills(
             const identifier = uuidToIdentifierMap.get(uuid)
 
             if (identifier) {
-                // PRESERVE EXISTING LOGIC: Apply forEach parameter handling
+                // PRESERVE EXISTING LOGIC: Apply forEach parameter handling.
+                // Note: With the consolidated regex, this is now called for step[UUID] pills too
+                // (previously only bare UUID pills hit this code). This is harmless since action
+                // step CIDs are never forEach parameters, so isForEachParam will always be false.
                 const isForEachParam = isForEachParameter(identifier, uuid)
                 let expression: PropertyAccessShape | IdentifierShape
 

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

@@ -90,8 +90,8 @@ function isInsideFlowContext(node: ts.Node): boolean {
  * - wfa.flowLogic.goBackTo
  * - wfa.flowLogic.tryCatch
  * - wfa.flowLogic.doInParallel
- * - FlowObject (must be within Flow/Subflow/ActionDefinition/SubflowDefinition/TriggerDefinition)
- * - FlowArray (must be within Flow/Subflow/ActionDefinition/SubflowDefinition/TriggerDefinition)
+ * - FlowObject (must be within Flow/Subflow/Action/TriggerDefinition)
+ * - FlowArray (must be within Flow/Subflow/Action/TriggerDefinition)
  */
 export const FlowDiagnosticsPlugin = Plugin.create({
     name: 'FlowDiagnosticsPlugin',

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

@@ -166,10 +166,13 @@ export function normalizeInputValue(value: string, uiType?: string, source?: Sou
                 // Create a StringShape from the value and use ApprovalRulesShape.from() to parse it
                 return ApprovalRulesShape.from(source, Shape.from(source, value).asString())
             } else if (uiType === APPROVAL_DUE_DATE_DATA_TYPE_VALUE) {
-                // Check if source is a Record before accessing action_type
+                // Check if source is a Record before accessing action_type or step_type.
+                // Flow context uses action_type; action definition context uses step_type.
                 if (source instanceof Record) {
                     const actionType = source.get(ACTION_TYPE_KEY_NAME)?.ifDefined()?.asString()?.getValue()
-                    if (APPROVAL_DUE_DATE_INPUT_FIELD_ACTIONS.includes(actionType as string)) {
+                    const stepType = source.get('step_type')?.ifDefined()?.asString()?.getValue()
+                    const typeId = actionType ?? stepType
+                    if (typeId && APPROVAL_DUE_DATE_INPUT_FIELD_ACTIONS.includes(typeId)) {
                         // Create a StringShape from the value and use ApprovalDueDateShape.from() to parse it
                         return ApprovalDueDateShape.from(source, Shape.from(source, value).asString())
                     }
@@ -277,10 +280,6 @@ function buildInstanceToShape({
                 }
 
                 const coreActionIdentifier = getCoreActionIdentifier(sysId)
-                if (callee === ACTION_INSTANCE_API_NAME && !coreActionIdentifier) {
-                    logger.warn(`Custom actions are not supported, action = ${sysId}`)
-                    return { success: false }
-                }
 
                 const action = database
                     .query('sys_hub_action_type_definition')
@@ -327,13 +326,12 @@ function buildInstanceToShape({
         if (inputsShape === undefined) {
             return { success: false as const }
         }
-        const waitForCompletion =
-            record.get('wait_for_completion')?.getValue() === true ||
-            record.get('wait_for_completion')?.getValue() === 'true'
-        if (waitForCompletion) {
+        const waitForCompletionValue = record.get('wait_for_completion')?.getValue()
+        const isWaitForCompletionFalse = waitForCompletionValue === false || waitForCompletionValue === 'false'
+        if (isWaitForCompletionFalse) {
             inputsShape = inputsShape
-                ? inputsShape.merge({ waitForCompletion })
-                : Shape.from(record, { waitForCompletion }).asObject()
+                ? inputsShape.merge({ waitForCompletion: false })
+                : Shape.from(record, { waitForCompletion: false }).asObject()
         }
 
         const configArg = new ObjectShape({
@@ -533,6 +531,7 @@ export const FlowInstancePlugin = Plugin.create({
                         factory,
                         source: callExpression,
                         transform,
+                        diagnostics,
                     })
                 }
 
@@ -728,6 +727,7 @@ async function buildActionInstance({
     const values = actionDef
         ? await prepareActionInstanceValueJson(inputs, actionDef, transform, logger, diagnostics)
         : undefined
+
     const actionDefRecord = actionDef instanceof Record ? actionDef : undefined
     const instanceProps = inputs.transform(({ $ }) => ({
         active: $.val(true),
@@ -767,6 +767,7 @@ async function buildSubflowInstance({
     uuid,
     source,
     transform,
+    diagnostics,
 }: {
     subflowDef: Record | StringShape | undefined
     inputs: ObjectShape
@@ -776,8 +777,11 @@ async function buildSubflowInstance({
     uuid: string | undefined
     source: Source
     transform: Transform
+    diagnostics: Diagnostics
 }): Promise<Record | undefined> {
-    const values = subflowDef ? await prepareSubflowInstanceValueJson(inputs, subflowDef, transform) : undefined
+    const values = subflowDef
+        ? await prepareSubflowInstanceValueJson(inputs, subflowDef, transform, diagnostics)
+        : undefined
 
     const subflowDefRecord = subflowDef instanceof Record ? subflowDef : undefined
     const instanceProps = inputs.transform(({ $ }) => ({
@@ -789,7 +793,7 @@ async function buildSubflowInstance({
         generation_source: $.val(''),
         subflow: $.val(subflowDefRecord?.getId()?.getValue() || subflowDef?.getValue() || ''),
         subflow_inputs: $.val(values),
-        wait_for_completion: $.from('waitForCompletion').def(false),
+        wait_for_completion: $.from('waitForCompletion').def(true),
         sys_class_name: $.val('sys_hub_sub_flow_instance_v2'),
         parent_ui_id: $.def(''),
     }))
@@ -1052,6 +1056,61 @@ function processDefaultOrHiddenInput(
     return undefined
 }
 
+/**
+ * Validates mandatory fields on raw shapes before datapill or inline script resolution. Only `StringShape`
+ * values are validated for emptiness. Runtime-evaluated shapes (data pills, template expressions, inline
+ * scripts, identifiers) are exempt because their values cannot be determined at build time.
+ *
+ * @param definition - The action or subflow definition record containing input definitions.
+ * @param instanceInputs - The raw ObjectShape of user-provided input values before resolution.
+ * @param diagnostics - Diagnostics instance for reporting validation errors.
+ * @param inputTable - The table name for input definitions (e.g., 'sys_hub_action_input' or 'sys_hub_flow_input').
+ * @param definitionName - Optional name of the action or subflow for more specific error messages.
+ * @returns The filtered input definition records for reuse, or undefined if no definition.
+ */
+function validateMandatoryFields(
+    definition: Record | undefined,
+    instanceInputs: ObjectShape,
+    diagnostics: Diagnostics,
+    inputTable: string,
+    definitionName?: string
+): Record[] | undefined {
+    const inputDefinitions = definition
+        ? definition.flat().filter((record) => record.getTable() === inputTable)
+        : undefined
+
+    if (inputDefinitions) {
+        const rawEntries = new Map(instanceInputs.entries({ resolve: false }))
+
+        for (const inputDefinition of inputDefinitions) {
+            const inputName = inputDefinition.get('element')?.asString()?.getValue() ?? ''
+            if (!inputName) {
+                continue
+            }
+
+            const isMandatory = inputDefinition.get('mandatory')?.ifBoolean()?.getValue() ?? false
+            if (!isMandatory) {
+                continue
+            }
+
+            const rawShape = rawEntries.get(inputName)
+            if (!rawShape) {
+                continue
+            }
+
+            if (rawShape.isString() && rawShape.isEmpty()) {
+                const context = definitionName ? ` in action '${definitionName}'` : ''
+                diagnostics.error(
+                    rawShape,
+                    `Mandatory field '${inputName}'${context} cannot be an empty string. Please provide a non-empty value.`
+                )
+            }
+        }
+    }
+
+    return inputDefinitions
+}
+
 /**
  * Resolve a catalog item record from a Shape (direct Record, TemplateExpressionShape, or IdentifierShape).
  */
@@ -1237,14 +1296,24 @@ async function prepareActionInstanceValueJson(
     }
     const isActionDefString = actionDef instanceof StringShape
 
+    // Resolve action name early for use in validation messages and special handling
+    const actionSysId = actionDefRecord?.getId()?.getValue()
+    const actionName = typeof actionSysId === 'string' ? CORE_ACTIONS_SYS_ID_NAME_MAP[actionSysId] : undefined
+
+    const definitionInputs = validateMandatoryFields(
+        actionDefRecord,
+        instanceInputs,
+        diagnostics,
+        'sys_hub_action_input',
+        actionName
+    )
+
     // Special handling for getCatalogVariables action
     let overrideValues = new Map<string, string>()
     let displayValues = new Map<string, string>()
     let unsupportedFieldsForAction: string[] | undefined
 
     if (actionDefRecord) {
-        const actionSysId = actionDefRecord.getId().getValue()
-        const actionName = typeof actionSysId === 'string' ? CORE_ACTIONS_SYS_ID_NAME_MAP[actionSysId] : undefined
         unsupportedFieldsForAction = actionName ? INLINE_SCRIPT_UNSUPPORTED_FIELDS[actionName] : undefined
 
         // Check if this is the getCatalogVariables action or createCatalogTask action
@@ -1287,9 +1356,8 @@ async function prepareActionInstanceValueJson(
 
     // When isActionDefString is true, there's no action definition in fluent
     // We expect arbitrary inputs and should process all provided inputs directly
-    if (actionDefRecord) {
-        // When action definition record is present, process only definition inputs
-        const definitionInputs = actionDefRecord.flat().filter((v) => v.getTable() === 'sys_hub_action_input')
+    if (actionDefRecord && definitionInputs) {
+        // When action definition record is present, process only the definition inputs.
         const providedInputNames = new Set(objShape.keys())
 
         for (const inputDef of definitionInputs) {
@@ -1351,8 +1419,15 @@ async function prepareActionInstanceValueJson(
 async function prepareSubflowInstanceValueJson(
     instanceInputs: ObjectShape,
     subflowDef: Record | StringShape,
-    transform: Transform
+    transform: Transform,
+    diagnostics: Diagnostics
 ) {
+    const subflowDefRecord = subflowDef.isRecord() ? subflowDef.as(Record) : undefined
+    const subflowName = subflowDefRecord?.get('name')?.ifString()?.getValue()
+
+    // Validate mandatory fields on raw shapes before any resolution.
+    validateMandatoryFields(subflowDefRecord, instanceInputs, diagnostics, 'sys_hub_flow_input', subflowName)
+
     // Check for datapills and resolve them
     const dataPillResults = await checkAndResolveDataPills(instanceInputs, transform)
 
@@ -1386,8 +1461,9 @@ async function prepareSubflowInstanceValueJson(
                 value: primitiveValue,
                 internalType: undefined,
             }
-            if (subflowDef.isRecord()) {
-                resolvedValue = resolveComplexInput(key, primitiveValue, subflowDef.as(Record), 'sys_hub_flow_input')
+
+            if (subflowDefRecord) {
+                resolvedValue = resolveComplexInput(key, primitiveValue, subflowDefRecord, 'sys_hub_flow_input')
             }
 
             const result: globalThis.Record<string, unknown> = {

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

@@ -2,12 +2,13 @@ import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
 import { buildVariableShapes } from '../utils/flow-io-to-record'
 import { NowIdShape } from '../../now-id-plugin'
 import { generateXML } from '../utils/flow-to-xml'
+import { createSdkDocEntry } from '../../utils'
 /**
  * Plugin for processing StepDefinition calls
  */
 export const StepDefinitionPlugin = Plugin.create({
     name: 'StepDefinitionPlugin',
-    docs: [],
+    docs: [createSdkDocEntry('ActionStepDefinition', ['sys_flow_step_definition'])],
     records: {
         sys_flow_step_definition: {
             relationships: {