@servicenow/sdk-build-plugins 4.6.0 → 4.7.0

package/src/flow/flow-logic/flow-logic-plugin.ts

@@ -1,24 +1,40 @@
 import {
     Plugin,
     CallExpressionShape,
+    ObjectShape,
     type Record,
     UndefinedShape,
     type Shape,
     VariableStatementShape,
     type Logger,
 } from '@servicenow/sdk-build-core'
-import { FLOW_LOGIC, FLOW_LOGIC_SYS_ID_MAP, FlowLogicSysId, DO_IN_PARALLEL_BLOCK_SYS_ID } from './flow-logic-constants'
+import {
+    FLOW_LOGIC,
+    FLOW_LOGIC_SYS_ID_MAP,
+    FlowLogicSysId,
+    DO_IN_PARALLEL_BLOCK_SYS_ID,
+    TRY_CATCH_CATCH_SYS_ID,
+} from './flow-logic-constants'
+import { STAGE_API_NAME } from '../utils/flow-constants'
 import { FlowInstancePlugin } from '../plugins/flow-instance-plugin'
 import { FlowLogicInstanceShape } from './flow-logic-shapes'
 import {
     isConditionalLogicShape,
     isForEachShape,
     isDoInParallelShape,
+    isTryCatchShape,
     createEmptyFlowLogicValues,
 } from './flow-logic-plugin-helpers'
 import { getFlowLogicArguments, getFlowLogicInstanceRecord } from './flow-logic-plugin-helpers'
-import { getRecordFromFlowInstaceShape, sysIdToUuid, getOrder, getDirectVariableIdentifier } from '../utils/utils'
-import type { ArrowFunctionShape } from '../../arrow-function-plugin'
+import {
+    getRecordFromFlowInstaceShape,
+    sysIdToUuid,
+    getOrder,
+    getOrderSuffix,
+    getDirectVariableIdentifier,
+} from '../utils/utils'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { NowIdShape } from '../../now-id-plugin'
 
 /**
  * FlowLogicPlugin handles flow logic instances (If, ElseIf, Else, GoBackTo) in flow definitions.
@@ -72,7 +88,6 @@ import type { ArrowFunctionShape } from '../../arrow-function-plugin'
  */
 export const FlowLogicPlugin = Plugin.create({
     name: 'FlowLogicPlugin',
-    docs: [],
     records: {
         sys_hub_flow_logic_instance_v2: {
             relationships: {
@@ -97,12 +112,219 @@ export const FlowLogicPlugin = Plugin.create({
                 if (!logicName || !(logicName in FLOW_LOGIC_SYS_ID_MAP)) {
                     return { success: false }
                 }
-                const logicBodyShapes: Shape[] = []
+
                 const flowSysId = record.get('flow').getValue()
+
+                // Parallel branches are metadata containers. Collapse them into arrow-function arguments rather than
+                // emitting standalone shapes.
+                if (logicName === FLOW_LOGIC.DO_IN_PARALLEL) {
+                    const branchRecords = descendants
+                        .query('sys_hub_flow_logic_instance_v2', {
+                            parent_ui_id: record.get('ui_id').getValue(),
+                            flow: flowSysId,
+                            logic_definition: DO_IN_PARALLEL_BLOCK_SYS_ID,
+                        })
+                        .sort((a, b) => getOrder(a) - getOrder(b))
+
+                    const branchArrows: ArrowFunctionShape[] = []
+                    for (const branch of branchRecords) {
+                        const branchUiId = branch.get('ui_id').getValue()
+                        const branchDescendants = [
+                            ...descendants.query('sys_hub_sub_flow_instance_v2', {
+                                parent_ui_id: branchUiId,
+                                flow: flowSysId,
+                            }),
+                            ...descendants.query('sys_hub_action_instance_v2', {
+                                parent_ui_id: branchUiId,
+                                flow: flowSysId,
+                            }),
+                            ...descendants.query('sys_hub_flow_logic_instance_v2', {
+                                parent_ui_id: branchUiId,
+                                flow: flowSysId,
+                            }),
+                        ]
+                            // Catch records share their paired Try's parent (the branch ui_id). They are
+                            // consumed by the Try's `wfa.flowLogic.tryCatch(...)` toShape via `connected_to`,
+                            // so calling recordToShape on a Catch here would return `{ success: false }`
+                            // (its `logic_definition` is not in FLOW_LOGIC_SYS_ID_MAP) and cascade the entire
+                            // DoInParallel back to raw Records.
+                            .filter(
+                                (r) =>
+                                    r.getTable() !== 'sys_hub_flow_logic_instance_v2' ||
+                                    r.get('logic_definition').asString().getValue() !== TRY_CATCH_CATCH_SYS_ID
+                            )
+                            .sort((a, b) => getOrder(a) - getOrder(b))
+
+                        const branchStatements: Shape[] = []
+                        for (const descendant of branchDescendants) {
+                            const result = await transform.recordToShape(
+                                descendant,
+                                database,
+                                FlowInstancePlugin,
+                                FlowLogicPlugin
+                            )
+
+                            if (!result.success) {
+                                return result
+                            }
+
+                            branchStatements.push(result.value)
+                        }
+
+                        branchArrows.push(
+                            new ArrowFunctionShape({
+                                source: branch,
+                                parameters: [],
+                                statements: branchStatements,
+                            })
+                        )
+                    }
+
+                    const annotation = record.get('comment').asString().getValue()
+                    const configArg = new ObjectShape({
+                        source: record,
+                        properties: {
+                            ...(annotation ? { annotation } : {}),
+                            $id: NowIdShape.from(record),
+                        },
+                    })
+
+                    return {
+                        success: true,
+                        value: new CallExpressionShape({
+                            source: record,
+                            callee: FLOW_LOGIC.DO_IN_PARALLEL,
+                            args: [configArg, ...branchArrows],
+                        }),
+                    }
+                }
+
+                // TryCatch is stored as two sibling top-level records linked by `connected_to`. Collapse the Try +
+                // paired Catch + each side's descendants into one `wfa.flowLogic.tryCatch(config, { try, catch })` call.
+                if (logicName === FLOW_LOGIC.TRY_CATCH) {
+                    const tryUiId = record.get('ui_id').getValue()
+                    const catchRecord = database.get('sys_hub_flow_logic_instance_v2', {
+                        connected_to: tryUiId,
+                        logic_definition: TRY_CATCH_CATCH_SYS_ID,
+                        flow: flowSysId,
+                    })
+
+                    if (!catchRecord) {
+                        return { success: false }
+                    }
+
+                    const catchUiId = catchRecord.get('ui_id').getValue()
+
+                    // Try's body descendants. Filter out any sibling Catch records that share the same parent_ui_id;
+                    // they are consumed by their paired Try sibling and are not part of the Try's body.
+                    const tryDescendants = [
+                        ...descendants.query('sys_hub_sub_flow_instance_v2', {
+                            parent_ui_id: tryUiId,
+                            flow: flowSysId,
+                        }),
+                        ...descendants.query('sys_hub_action_instance_v2', {
+                            parent_ui_id: tryUiId,
+                            flow: flowSysId,
+                        }),
+                        ...descendants.query('sys_hub_flow_logic_instance_v2', {
+                            parent_ui_id: tryUiId,
+                            flow: flowSysId,
+                        }),
+                    ]
+                        .filter(
+                            (r) =>
+                                r.getTable() !== 'sys_hub_flow_logic_instance_v2' ||
+                                r.get('logic_definition').asString().getValue() !== TRY_CATCH_CATCH_SYS_ID
+                        )
+                        .sort((a, b) => getOrder(a) - getOrder(b))
+
+                    // Catch's body descendants. The Catch can be a top-level sibling of the Try (not in `descendants`)
+                    // or a nested sibling inside another block, so query the flat database to handle both uniformly.
+                    const matchesCatchBody = (r: Record) =>
+                        r.get('parent_ui_id').getValue() === catchUiId && r.get('flow').getValue() === flowSysId
+
+                    const catchDescendants = [
+                        ...database.query('sys_hub_sub_flow_instance_v2').filter(matchesCatchBody),
+                        ...database.query('sys_hub_action_instance_v2').filter(matchesCatchBody),
+                        ...database.query('sys_hub_flow_logic_instance_v2').filter(matchesCatchBody),
+                    ].sort((a, b) => getOrder(a) - getOrder(b))
+
+                    const tryStatements: Shape[] = []
+                    for (const desc of tryDescendants) {
+                        const result = await transform.recordToShape(
+                            desc,
+                            database,
+                            FlowInstancePlugin,
+                            FlowLogicPlugin
+                        )
+
+                        if (!result.success) {
+                            return result
+                        }
+
+                        tryStatements.push(result.value)
+                    }
+
+                    const catchStatements: Shape[] = []
+                    for (const desc of catchDescendants) {
+                        const result = await transform.recordToShape(
+                            desc,
+                            database,
+                            FlowInstancePlugin,
+                            FlowLogicPlugin
+                        )
+
+                        if (!result.success) {
+                            return result
+                        }
+
+                        catchStatements.push(result.value)
+                    }
+
+                    const tryArrow = new ArrowFunctionShape({
+                        source: record,
+                        parameters: [],
+                        statements: tryStatements,
+                    })
+
+                    const catchArrow = new ArrowFunctionShape({
+                        source: catchRecord,
+                        parameters: [],
+                        statements: catchStatements,
+                    })
+
+                    const handlersArg = new ObjectShape({
+                        source: record,
+                        properties: {
+                            try: tryArrow,
+                            catch: catchArrow,
+                        },
+                    })
+
+                    const annotation = record.get('comment').asString().getValue()
+                    const configArg = new ObjectShape({
+                        source: record,
+                        properties: {
+                            ...(annotation ? { annotation } : {}),
+                            $id: NowIdShape.from(record),
+                        },
+                    })
+
+                    return {
+                        success: true,
+                        value: new CallExpressionShape({
+                            source: record,
+                            callee: FLOW_LOGIC.TRY_CATCH,
+                            args: [configArg, handlersArg],
+                        }),
+                    }
+                }
+
+                const logicBodyShapes: Shape[] = []
                 const allDescendants = [
                     ...descendants.query('sys_hub_sub_flow_instance_v2', {
                         parent_ui_id: record.get('ui_id').getValue(),
-                        flow: flowSysId, // This is to skip snapshot records
+                        flow: flowSysId,
                     }),
                     ...descendants.query('sys_hub_action_instance_v2', {
                         parent_ui_id: record.get('ui_id').getValue(),
@@ -113,6 +335,15 @@ export const FlowLogicPlugin = Plugin.create({
                         flow: flowSysId,
                     }),
                 ]
+                    // Skip Catch records — they share `parent_ui_id` with their paired Try sibling and are consumed
+                    // by that Try's `wfa.flowLogic.tryCatch(...)` shape via `connected_to`. Including them here would
+                    // call the standard flow-logic toShape on a Catch sys_id (which isn't in FLOW_LOGIC_SYS_ID_MAP)
+                    // and cascade a `{ success: false }` up, dropping the entire enclosing flow back to raw Records.
+                    .filter(
+                        (r) =>
+                            r.getTable() !== 'sys_hub_flow_logic_instance_v2' ||
+                            r.get('logic_definition').asString().getValue() !== TRY_CATCH_CATCH_SYS_ID
+                    )
 
                 // Sort descendants by order field to ensure correct statement sequencing
                 allDescendants.sort((a, b) => getOrder(a) - getOrder(b))
@@ -125,12 +356,7 @@ export const FlowLogicPlugin = Plugin.create({
                     logicBodyShapes.push(result.value)
                 }
 
-                const flowLogicArguments: Shape<unknown>[] = getFlowLogicArguments(
-                    logicName,
-                    record,
-                    logicBodyShapes,
-                    database
-                )
+                const flowLogicArguments: Shape[] = getFlowLogicArguments(logicName, record, logicBodyShapes, database)
 
                 const callExpression = new CallExpressionShape({
                     source: record,
@@ -139,7 +365,9 @@ export const FlowLogicPlugin = Plugin.create({
                 })
 
                 if (logicName === FLOW_LOGIC.WAIT_FOR_A_DURATION) {
-                    const order = record.get('order')?.getValue()
+                    // A `WaitForADuration` inside a `DoInParallel` branch carries a composite order like `17➛18`;
+                    // strip the separator so the generated identifier is valid JS.
+                    const order = getOrderSuffix((record.get('order')?.getValue() as string | undefined) ?? '')
                     const variableName =
                         getDirectVariableIdentifier(record.getOriginalSource()) ?? `waitForDuration_${order}`
 
@@ -171,14 +399,12 @@ export const FlowLogicPlugin = Plugin.create({
                     return result
                 }
                 const instanceRecord = result.value
-                const allInstances: Shape[] = []
-                const functions: ArrowFunctionShape[] = []
                 const relatedRecords: Record[] = []
-                // Special handling for DoInParallel - create separate flow logic records for each arrow function
+
                 if (isDoInParallelShape(expr)) {
                     const parallelFunctions = expr.getParallelFunctions()
                     const mainUiId = instanceRecord.get('ui_id').getValue()
-                    const mainNowId = instanceRecord.getId().getNowIdKey()
+                    const mainNowIdKey = instanceRecord.getId().getNowIdKey() ?? instanceRecord.getId().getValue()
 
                     for (let index = 0; index < parallelFunctions.length; index++) {
                         const parallelFunction = parallelFunctions[index]
@@ -188,16 +414,25 @@ export const FlowLogicPlugin = Plugin.create({
                         const statements = parallelFunction
                             .getStatements()
                             .filter((stmt) => !(stmt instanceof UndefinedShape))
+
+                        // Empty `() => {}` branches are intentionally elided. There is no Flow Designer state
+                        // to represent an empty parallel branch, and emitting one wouldn't round-trip. `index`
+                        // still advances so non-empty branches keep their `_block_${index}` slot stable across
+                        // rebuilds even when an earlier branch is empty.
                         if (statements.length === 0) {
                             continue
                         }
 
-                        const parallelBlockSysId = `${mainNowId}_block_${index}`
+                        // Deterministic `NowID` so rebuilds produce the same `sys_id`.
+                        const parallelBlockNowId = new NowIdShape({
+                            source: parallelFunction,
+                            id: `${mainNowIdKey}_block_${index}`,
+                        })
 
                         const parallelRecord = await factory.createRecord({
                             source: parallelFunction,
                             table: 'sys_hub_flow_logic_instance_v2',
-                            explicitId: parallelBlockSysId,
+                            explicitId: parallelBlockNowId,
                             properties: {
                                 logic_definition: DO_IN_PARALLEL_BLOCK_SYS_ID,
                                 values: createEmptyFlowLogicValues(),
@@ -205,40 +440,103 @@ export const FlowLogicPlugin = Plugin.create({
                         })
 
                         const parallelUiId = sysIdToUuid(parallelRecord.getId().getValue())
-                        const finalParallelRecord = await parallelRecord.merge({
+                        const finalParallelRecord = parallelRecord.merge({
                             ui_id: parallelUiId,
                             parent_ui_id: mainUiId,
                         })
 
                         relatedRecords.push(finalParallelRecord)
 
-                        // Process statements within this parallel function
-                        parallelFunction
-                            .getStatements()
-                            .filter((stmt) => !(stmt instanceof UndefinedShape))
-                            .forEach((stmt) => {
-                                const record = stmt.is(VariableStatementShape)
-                                    ? stmt.getInitializer()?.asRecord()
-                                    : stmt.asRecord()
-                                if (record) {
-                                    relatedRecords.push(record.merge({ parent_ui_id: parallelUiId }))
-                                }
-                            })
+                        for (const statement of statements) {
+                            const childRecord = await getRecordFromFlowInstaceShape(statement, transform)
+                            if (childRecord) {
+                                relatedRecords.push(mergeParentChildUIID(childRecord, parallelUiId))
+                            }
+                        }
+                    }
+
+                    return { success: true, value: instanceRecord.with(...relatedRecords) }
+                }
+
+                // Special handling for TryCatch — Flow Designer stores TryCatch as two top-level sibling records: a
+                // Try (logic_definition = TRY_CATCH) and a paired Catch (logic_definition = TRY_CATCH_CATCH) linked
+                // via `connected_to` from Catch → Try.ui_id. Try-body statements have `parent_ui_id = Try.ui_id`;
+                // catch-body statements have `parent_ui_id = Catch.ui_id`.
+                if (isTryCatchShape(expr)) {
+                    const tryUiId = instanceRecord.get('ui_id').getValue() as string
+                    const mainNowId = instanceRecord.getId().getNowIdKey()
+                    const catchSysId = `${mainNowId}_catch`
+
+                    const catchPartialRecord = await factory.createRecord({
+                        source: expr,
+                        table: 'sys_hub_flow_logic_instance_v2',
+                        explicitId: catchSysId,
+                        properties: {
+                            logic_definition: TRY_CATCH_CATCH_SYS_ID,
+                            values: createEmptyFlowLogicValues(),
+                        },
+                    })
+
+                    const catchUiId = sysIdToUuid(catchPartialRecord.getId().getValue())
+                    const catchRecord = catchPartialRecord.merge({
+                        ui_id: catchUiId,
+                        connected_to: tryUiId,
+                    })
+
+                    const tryStatements =
+                        expr
+                            .getTryHandler()
+                            ?.getStatements()
+                            .filter((stmt) => !(stmt instanceof UndefinedShape)) ?? []
+
+                    for (const stmt of tryStatements) {
+                        const childRecord = await getRecordFromFlowInstaceShape(stmt, transform)
+                        if (childRecord) {
+                            relatedRecords.push(mergeParentChildUIID(childRecord, tryUiId))
+                        }
+                    }
+
+                    // Push Catch *after* the Try-body statements so the flat-order assignment in
+                    // flow-definition-plugin produces Try → tryBody → Catch → catchBody. Flow Designer
+                    // uses the `order` field to render the visual flow; emitting Catch at order=Try+1
+                    // makes FD interleave the Try body under the Catch arm.
+                    relatedRecords.push(catchRecord)
+
+                    const catchStatements =
+                        expr
+                            .getCatchHandler()
+                            ?.getStatements()
+                            .filter((stmt) => !(stmt instanceof UndefinedShape)) ?? []
+
+                    for (const stmt of catchStatements) {
+                        const childRecord = await getRecordFromFlowInstaceShape(stmt, transform)
+                        if (childRecord) {
+                            relatedRecords.push(mergeParentChildUIID(childRecord, catchUiId))
+                        }
                     }
 
                     return { success: true, value: instanceRecord.with(...relatedRecords) }
                 }
 
                 // Standard handling for other flow logic types
+                const allInstances: Shape[] = []
+                const functions: ArrowFunctionShape[] = []
                 if (isConditionalLogicShape(expr) || isForEachShape(expr)) {
                     functions.push(expr.getBody())
                 }
+
                 functions.forEach((fn) => {
                     allInstances.push(...(fn.getStatements().filter((stmt) => !(stmt instanceof UndefinedShape)) ?? []))
                 })
 
-                // for instances with body, set parent_ui_id for child records
-                for (const [, v] of (allInstances ?? []).entries()) {
+                // For instances with body, set `parent_ui_id` for child records.
+                for (const v of allInstances) {
+                    // Skip wfa.stage() calls — they are handled by the flow definition plugin
+                    const callExpr = v instanceof VariableStatementShape ? v.getInitializer() : v
+                    if (callExpr instanceof CallExpressionShape && callExpr.getCallee() === STAGE_API_NAME) {
+                        continue
+                    }
+
                     const record = await getRecordFromFlowInstaceShape(v, transform)
 
                     if (record) {
@@ -256,12 +554,12 @@ export const FlowLogicPlugin = Plugin.create({
                             )
 
                             relatedRecords.push(
-                                updatedRecord.merge({
-                                    parent_ui_id: instanceRecord.get('ui_id').getValue(),
-                                })
+                                mergeParentChildUIID(updatedRecord, instanceRecord.get('ui_id').getValue() as string)
                             )
                         } else {
-                            relatedRecords.push(record.merge({ parent_ui_id: instanceRecord.get('ui_id').getValue() }))
+                            relatedRecords.push(
+                                mergeParentChildUIID(record, instanceRecord.get('ui_id').getValue() as string)
+                            )
                         }
                     }
                 }
@@ -272,6 +570,38 @@ export const FlowLogicPlugin = Plugin.create({
     ],
 })
 
+/**
+ * Merges `parent_ui_id` onto a flow-logic child record and propagates the same `parent_ui_id` onto any TryCatch Catch
+ * sibling record nested in the child's direct `related` list.
+ *
+ * Catch records are emitted by the TryCatch toRecord branch as siblings of their paired Try (linked via
+ * `connected_to`), but they live in `Try.getRelated()` because `toRecord` can return only one record. When an outer
+ * flow-logic walker (forEach, conditional, doInParallel, tryCatch) assigns `parent_ui_id` to the child Try, a plain
+ * `record.merge(...)` does not touch the related Catch, leaving its `parent_ui_id` empty.
+ *
+ * Flow Designer requires the Catch and its paired Try to share the same `parent_ui_id` (they are sibling blocks).
+ * This helper propagates the value to any direct-related Catch record.
+ *
+ * @param record - The child flow-logic record being parented under an outer container. Typically, a Try record
+ * returned from a nested TryCatch's `toRecord`, but may be any flow-logic instance record. Its direct `related` list
+ * is scanned for Catch siblings; deeper descendants are left untouched (each layer of the walker is responsible for
+ * its own children).
+ * @param parentUiId - The `ui_id` of the enclosing flow-logic block (the outer forEach / conditional / DoInParallel
+ * block / Try / Catch). Set as `parent_ui_id` on `record` and on every direct-related Catch record.
+ * @returns A new `Record` with `parent_ui_id` applied to the top-level record and to any direct-related Catch
+ * siblings; all other related records are preserved unchanged.
+ */
+function mergeParentChildUIID(record: Record, parentUiId: string): Record {
+    const related = record.getRelated()
+    const updatedRelated = related.map((r) => {
+        if (r.get('logic_definition')?.getValue() === TRY_CATCH_CATCH_SYS_ID) {
+            return r.merge({ parent_ui_id: parentUiId })
+        }
+        return r
+    })
+    return record.merge({ parent_ui_id: parentUiId }).with(...updatedRelated)
+}
+
 /**
  * Recursively updates data pill references in forEach loop records
  *

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

@@ -130,6 +130,29 @@ export class SetFlowVariablesInstanceShape extends FlowLogicInstanceShape {
     }
 }
 
+/**
+ * Shape class for AppendToFlowVariables logic.
+ * Handles the pattern: AppendToFlowVariables(config, variables, values)
+ *
+ * @example
+ * AppendToFlowVariables(
+ *   { $id: Now.ID['append_1'] },
+ *   params.flowVariables,
+ *   { objects: { name: 'item' } }
+ * )
+ */
+export class AppendToFlowVariablesInstanceShape extends FlowLogicInstanceShape {
+    getValuesToAppend(): ObjectShape {
+        return this.getArgument(2)?.as(ObjectShape)
+    }
+
+    getValuesToAppendAsString(): string {
+        const variables = this.getValuesToAppend()
+        const entries = variables.entries({ resolve: false })
+        return Array.from(entries, ([key]) => key).join(',')
+    }
+}
+
 /**
  * Shape class for AssignSubflowOutputs logic.
  * Handles the pattern: AssignSubflowOutputs(config, outputs)
@@ -200,6 +223,8 @@ export function createFlowLogicInstanceShape(expr: Source, callee: string, args:
             return new DoInParallelInstanceShape(expr, callee, args)
         case FLOW_LOGIC.SET_FLOW_VARIABLES:
             return new SetFlowVariablesInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.APPEND_TO_FLOW_VARIABLES:
+            return new AppendToFlowVariablesInstanceShape(expr, callee, args)
         case FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS:
             return new AssignSubflowOutputsInstanceShape(expr, callee, args)
         case FLOW_LOGIC.WAIT_FOR_A_DURATION:

package/src/flow/plugins/approval-rules-plugin.ts

@@ -5,7 +5,6 @@ import { getCallExpressionName } from '../../utils'
 
 export const ApprovalRulesPlugin = Plugin.create({
     name: 'ApprovalRulesPlugin',
-    docs: [],
     nodes: [
         {
             node: 'CallExpression',