@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

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

@@ -0,0 +1,337 @@
+import {
+    Plugin,
+    CallExpressionShape,
+    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 { FlowInstancePlugin } from '../plugins/flow-instance-plugin'
+import { FlowLogicInstanceShape } from './flow-logic-shapes'
+import {
+    isConditionalLogicShape,
+    isForEachShape,
+    isDoInParallelShape,
+    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'
+
+/**
+ * FlowLogicPlugin handles flow logic instances (If, ElseIf, Else, GoBackTo) in flow definitions.
+ *
+ * ## Architecture Overview
+ *
+ * This plugin provides bidirectional conversion between Fluent TypeScript code and ServiceNow XML flow records:
+ *
+ * **Fluent → XML (Build Time):**
+ * ```
+ * If({ condition: "user.role === 'admin'" }, () => { ... })
+ * ↓ (FlowLogicValueProcessor.prepare)
+ * sys_hub_flow_logic_instance_v2 record with gzipped JSON values
+ * ```
+ *
+ * **XML → Fluent (transform):**
+ * ```
+ * sys_hub_flow_logic_instance_v2 record with gzipped values
+ * ↓ (FlowLogicValueProcessor.parse)
+ * If({ condition: "user.role === 'admin'" }, () => { ... })
+ * ```
+ *
+ * ## Adding New Flow Logic Types
+ *
+ * To add a new flow logic type (e.g., `DoInParallel`, `ForEach`), follow these steps:
+ *
+ * ### 1. Update Constants (`flow-logic-constants.ts`)
+ * Add new enum values to FLOW_LOGIC, and FLOW_LOGIC_MAP
+ *
+ * ### 2. Create Shape Types (`flow-logic-shapes.ts`)
+ * Define TypeScript interfaces extending FlowLogicInstanceShape with specific methods
+ *
+ * ### 3. Update FlowLogicValueProcessor
+ * - **Add Value Preparers**: Functions to convert Fluent config to FlowLogicValues (forward flow)
+ * - **Add Value Parsers**: Functions to convert FlowLogicValues back to config objects (reverse flow)
+ *
+ * ### 4. Add Argument Builders
+ * Create functions in FLOW_LOGIC_ARGUMENT_BUILDERS to reconstruct Fluent function arguments
+ *
+ * ### 5. Add Type Guards and Validation
+ * Create type guard functions and add validation rules in flow-logic-diagnostics.ts
+ *
+ *
+ * ## Data Flow Summary
+ *
+ * ```
+ * Fluent Code → FlowLogicInstanceShape → prepare() → XML Record
+ *      ↑                                                    ↓
+ * CallExpressionShape ← buildArguments() ← parse() ← XML Record
+ * ```
+ */
+export const FlowLogicPlugin = Plugin.create({
+    name: 'FlowLogicPlugin',
+    records: {
+        sys_hub_flow_logic_instance_v2: {
+            relationships: {
+                sys_hub_sub_flow_instance_v2: {
+                    via: { parent_ui_id: 'ui_id' },
+                    descendant: true,
+                },
+                sys_hub_action_instance_v2: {
+                    via: { parent_ui_id: 'ui_id' },
+                    descendant: true,
+                },
+                sys_hub_flow_logic_instance_v2: {
+                    via: { parent_ui_id: 'ui_id' },
+                    descendant: true,
+                },
+            },
+
+            async toShape(record, { transform, database, descendants }) {
+                const logicDefinition = record.get('logic_definition').asString().getValue()
+                const logicName = FlowLogicSysId.getLogicName(logicDefinition) as FLOW_LOGIC
+
+                if (!logicName || !(logicName in FLOW_LOGIC_SYS_ID_MAP)) {
+                    return { success: false }
+                }
+                const logicBodyShapes: Shape[] = []
+                const flowSysId = record.get('flow').getValue()
+                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
+                    }),
+                    ...descendants.query('sys_hub_action_instance_v2', {
+                        parent_ui_id: record.get('ui_id').getValue(),
+                        flow: flowSysId,
+                    }),
+                    ...descendants.query('sys_hub_flow_logic_instance_v2', {
+                        parent_ui_id: record.get('ui_id').getValue(),
+                        flow: flowSysId,
+                    }),
+                ]
+
+                // Sort descendants by order field to ensure correct statement sequencing
+                allDescendants.sort((a, b) => getOrder(a) - getOrder(b))
+
+                for (const record of allDescendants) {
+                    const result = await transform.recordToShape(record, database, FlowInstancePlugin, FlowLogicPlugin)
+                    if (!result.success) {
+                        return result
+                    }
+                    logicBodyShapes.push(result.value)
+                }
+
+                const flowLogicArguments: Shape<unknown>[] = getFlowLogicArguments(
+                    logicName,
+                    record,
+                    logicBodyShapes,
+                    database
+                )
+
+                const callExpression = new CallExpressionShape({
+                    source: record,
+                    callee: logicName,
+                    args: flowLogicArguments,
+                })
+
+                if (logicName === FLOW_LOGIC.WAIT_FOR_A_DURATION) {
+                    const order = record.get('order')?.getValue()
+                    const variableName =
+                        getDirectVariableIdentifier(record.getOriginalSource()) ?? `waitForDuration_${order}`
+
+                    return {
+                        success: true,
+                        value: new VariableStatementShape({
+                            source: record,
+                            variableName,
+                            initializer: callExpression,
+                            isExported: false,
+                        }),
+                    }
+                }
+
+                return {
+                    success: true,
+                    value: callExpression,
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: FlowLogicInstanceShape,
+            fileTypes: ['fluent'],
+            async toRecord(expr, { diagnostics, factory, transform, logger }) {
+                const result = await getFlowLogicInstanceRecord(expr, { diagnostics, factory, transform })
+                if (!result.success) {
+                    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()
+
+                    for (let index = 0; index < parallelFunctions.length; index++) {
+                        const parallelFunction = parallelFunctions[index]
+                        if (!parallelFunction) {
+                            continue
+                        }
+                        const statements = parallelFunction
+                            .getStatements()
+                            .filter((stmt) => !(stmt instanceof UndefinedShape))
+                        if (statements.length === 0) {
+                            continue
+                        }
+
+                        const parallelBlockSysId = `${mainNowId}_block_${index}`
+
+                        const parallelRecord = await factory.createRecord({
+                            source: parallelFunction,
+                            table: 'sys_hub_flow_logic_instance_v2',
+                            explicitId: parallelBlockSysId,
+                            properties: {
+                                logic_definition: DO_IN_PARALLEL_BLOCK_SYS_ID,
+                                values: createEmptyFlowLogicValues(),
+                            },
+                        })
+
+                        const parallelUiId = sysIdToUuid(parallelRecord.getId().getValue())
+                        const finalParallelRecord = await 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 }))
+                                }
+                            })
+                    }
+
+                    return { success: true, value: instanceRecord.with(...relatedRecords) }
+                }
+
+                // Standard handling for other flow logic types
+                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()) {
+                    const record = await getRecordFromFlowInstaceShape(v, transform)
+
+                    if (record) {
+                        if (isForEachShape(expr)) {
+                            // Get the parameter name from the forEach arrow function
+                            const forEachBody = expr.getBody()
+                            const parameters = forEachBody.getParameters()
+                            const parameterName =
+                                parameters.length > 0 && parameters[0] ? parameters[0].getName() : 'item'
+                            const updatedRecord = updateRecordsWithDataPills(
+                                record,
+                                instanceRecord,
+                                parameterName,
+                                logger
+                            )
+
+                            relatedRecords.push(
+                                updatedRecord.merge({
+                                    parent_ui_id: instanceRecord.get('ui_id').getValue(),
+                                })
+                            )
+                        } else {
+                            relatedRecords.push(record.merge({ parent_ui_id: instanceRecord.get('ui_id').getValue() }))
+                        }
+                    }
+                }
+
+                return { success: true, value: instanceRecord.with(...relatedRecords) }
+            },
+        },
+    ],
+})
+
+/**
+ * Recursively updates data pill references in forEach loop records
+ *
+ * When a forEach loop is processed, data pills referencing the loop item need to be updated
+ * to use the forEach instance's UUID instead of the generic 'forEach' prefix.
+ *
+ * This function:
+ * - Recursively processes a record and all its related records
+ * - Data pill references are updated by decompressing the 'values' field, performing string replacement,
+ *   and re-compressing the result
+ * - Relationships between records are preserved through the recursive update process
+ * - Only replaces data pills that match the specific parameter name to handle nested forEach loops correctly
+ * - The parameterName is used for matching, but the output always uses 'item' (ServiceNow platform requirement)
+ *
+ * @param record - The record to update
+ * @param instanceRecord - The forEach instance record containing the UUID
+ * @param parameterName - The arrow function parameter name used for matching (e.g., 'dept', 'category')
+ *
+ * @example
+ * // Outer forEach with parameterName='dept'
+ * // Before: `{{forEach.dept.name}}`
+ * // After: `{{outerUUID.item.name}}`
+ *
+ * @example
+ * // Nested forEach: inner loop with parameterName='category' won't replace `{{forEach.dept.name}}`
+ * // Before: `{{forEach.category.name}}` and `{{forEach.dept.manager}}`
+ * // After: `{{innerUUID.item.name}}` and `{{forEach.dept.manager}}` (dept unchanged by inner loop)
+ */
+function updateRecordsWithDataPills(
+    record: Record,
+    instanceRecord: Record,
+    parameterName: string,
+    logger: Logger
+): Record {
+    const relatedRecords = record.getRelated()
+
+    const valuesJson = record.get('values')?.getValue()
+
+    if (!valuesJson) {
+        return record
+    }
+
+    try {
+        // Create a regex that matches {{forEach.parameterName followed by . or }} or |
+        // This ensures we only replace pills for this specific forEach parameter
+        // The parameterName is used for matching, but always replaced with 'item' in the output
+        // The pattern must include | to handle type annotations like {{forEach.user|reference}}
+        const pattern = new RegExp(`\\{\\{forEach\\.${parameterName}([.}|])`, 'g')
+        const replacement = `{{${instanceRecord.get('ui_id').getValue()}.item$1`
+        const updatedValuesJson = JSON.stringify(valuesJson).replace(pattern, replacement)
+
+        const updatedRecord = record.merge({
+            values: JSON.parse(updatedValuesJson),
+        })
+        const updatedRelatedRecords: Record[] = []
+        for (const rec of relatedRecords) {
+            updatedRelatedRecords.push(updateRecordsWithDataPills(rec, instanceRecord, parameterName, logger))
+        }
+        return updatedRecord.with(...updatedRelatedRecords)
+    } catch (error) {
+        logger.error(`Failed to update data pills in forEach record: ${error instanceof Error ? error.message : error}`)
+        return record.with(...relatedRecords)
+    }
+}

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

@@ -0,0 +1,215 @@
+import {
+    type Source,
+    ObjectShape,
+    type Record,
+    type StringShape,
+    PropertyAccessShape,
+} from '@servicenow/sdk-build-core'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { NowIdShape } from '../../now-id-plugin'
+import { FLOW_LOGIC } from './flow-logic-constants'
+import { FDInstanceShape } from '../utils/flow-shapes'
+
+/**
+ * Base class for flow logic constructs that use config + additional arguments pattern.
+ * Provides common functionality for accessing config, sysId, and annotation.
+ */
+export class FlowLogicInstanceShape extends FDInstanceShape {
+    getConfig(): ObjectShape {
+        return this.getArgument(0).as(ObjectShape)
+    }
+
+    getSysId(): NowIdShape {
+        return this.getConfig().get('$id').as(NowIdShape)
+    }
+
+    getAnnotation(): StringShape | undefined {
+        const annotationShape = this.getConfig().get('annotation')
+        if (annotationShape?.isUndefined()) {
+            return undefined
+        }
+        return annotationShape?.asString() ?? undefined
+    }
+}
+
+/**
+ * Shape class for conditional flow logic constructs (If/ElseIf/Else).
+ * Handles the pattern: If/ElseIf/Else(config, body)
+ *
+ * @example
+ * If({ $id: Now.ID['if_1'], condition: 'user.role === "admin"', label: 'Admin Check' }, () => { ... })
+ * ElseIf({ $id: Now.ID['elseif_1'], condition: 'user.role === "user"' }, () => { ... })
+ * Else({ $id: Now.ID['else_1'], annotation: 'Default case' }, () => { ... })
+ */
+export class ConditionalLogicInstanceShape extends FlowLogicInstanceShape {
+    getBody(): ArrowFunctionShape {
+        return this.getArgument(1).as(ArrowFunctionShape)
+    }
+
+    getCondition(): StringShape | undefined {
+        return this.getConfig().get('condition')?.asString()
+    }
+
+    getLabel(): StringShape | undefined {
+        return this.getConfig().get('label')?.asString()
+    }
+}
+
+/**
+ * Shape class for ForEach loop logic.
+ * Handles the pattern: ForEach(config, items, body)
+ *
+ * @example
+ * ForEach({ $id: Now.ID['foreach_1'], annotation: 'Process items' }, ['a', 'b', 'c'], (item) => { ... })
+ */
+export class ForEachInstanceShape extends FlowLogicInstanceShape {
+    override getConfig(): ObjectShape {
+        return this.getArgument(1).as(ObjectShape)
+    }
+
+    getItems(): PropertyAccessShape {
+        return this.getArgument(0, false).as(PropertyAccessShape)
+    }
+
+    getBody(): ArrowFunctionShape {
+        return this.getArgument(2).as(ArrowFunctionShape)
+    }
+}
+
+/**
+ * Shape class for GoBackTo navigation logic.
+ * Handles the pattern: GoBackTo(config, step)
+ *
+ * @example
+ * GoBackTo({ $id: Now.ID['goback_1'], annotation: 'Retry logic' }, previousStep)
+ */
+export class GoBackToInstanceShape extends FlowLogicInstanceShape {
+    getStep(): Record | StringShape {
+        const step = this.getArgument(1)
+        return step?.isRecord() ? step.asRecord() : step?.asString()
+    }
+}
+
+/**
+ * Shape class for TryCatch error handling logic.
+ * Handles the pattern: TryCatch(config, handlers)
+ *
+ * @example
+ * TryCatch({ $id: Now.ID['trycatch_1'] }, { try: tryFn, catch: catchFn })
+ */
+export class TryCatchInstanceShape extends FlowLogicInstanceShape {
+    getHandlers(): ObjectShape {
+        return this.getArgument(1)?.as(ObjectShape)
+    }
+
+    getTryHandler(): ArrowFunctionShape {
+        return this.getHandlers()?.get('try')?.as(ArrowFunctionShape)
+    }
+
+    getCatchHandler(): ArrowFunctionShape {
+        return this.getHandlers()?.get('catch')?.as(ArrowFunctionShape)
+    }
+}
+
+/**
+ * Shape class for SetFlowVariables logic.
+ * Handles the pattern: SetFlowVariables(config, variables)
+ *
+ * @example
+ * SetFlowVariables({ $id: Now.ID['set_flow_variables_1'] }, _params.flow_variables, { variable1: 'value1', variable2: 'value2' })
+ */
+export class SetFlowVariablesInstanceShape extends FlowLogicInstanceShape {
+    getVariablesToSet(): ObjectShape {
+        return this.getArgument(2)?.as(ObjectShape)
+    }
+
+    getVariablesToSetAsString(): string {
+        const variables = this.getVariablesToSet()
+        const entries = variables.entries({ resolve: false })
+        return Array.from(entries, ([key]) => key).join(',')
+    }
+}
+
+/**
+ * Shape class for AssignSubflowOutputs logic.
+ * Handles the pattern: AssignSubflowOutputs(config, outputs)
+ *
+ * @example
+ * AssignSubflowOutputs({ $id: Now.ID['assign_subflow_outputs_1'] }, _params.outputs, { output1: 'value1', output2: 'value2' })
+ */
+export class AssignSubflowOutputsInstanceShape extends FlowLogicInstanceShape {
+    getAssignedSubflowOutputs(): ObjectShape {
+        return this.getArgument(2)?.as(ObjectShape)
+    }
+
+    getAssignedSubflowOutputsAsString(): string {
+        const assignedSubflowOutputs = this.getAssignedSubflowOutputs()
+        const entries = assignedSubflowOutputs.entries({ resolve: false })
+        return Array.from(entries, ([key]) => key).join(',')
+    }
+}
+
+/**
+ * Shape class for DoInParallel execution logic.
+ * Handles the pattern: DoInParallel(config, ...functions)
+ *
+ * @example
+ * DoInParallel({ $id: Now.ID['do_in_parallel_1'] }, fn1, fn2, fn3)
+ */
+export class DoInParallelInstanceShape extends FlowLogicInstanceShape {
+    getParallelFunctions(): ArrowFunctionShape[] {
+        const functions: ArrowFunctionShape[] = []
+        const allArgs = this.getArguments()
+        // Start from argument 1 (after config) and collect all arrow functions
+        for (let i = 1; i < allArgs.length; i++) {
+            const arg = this.getArgument(i)
+            if (arg) {
+                functions.push(arg.as(ArrowFunctionShape))
+            }
+        }
+        return functions
+    }
+
+    getParallelFunctionCount(): number {
+        return this.getArguments().length - 1 // Subtract 1 for config argument
+    }
+}
+
+/**
+ * Factory function to create the appropriate specific flow logic shape based on the logic type.
+ * This provides type-safe access to flow logic constructs while maintaining backward compatibility.
+ *
+ * @param expr - The CallExpressionShape to convert
+ * @param callee - The flow logic type (If, ElseIf, Else, ForEach, etc.)
+ * @param args - The arguments for the flow logic construct
+ * @returns The appropriate specific shape instance
+ */
+export function createFlowLogicInstanceShape(expr: Source, callee: string, args: unknown[]): FlowLogicInstanceShape {
+    switch (callee) {
+        case FLOW_LOGIC.IF:
+        case FLOW_LOGIC.ELSEIF:
+        case FLOW_LOGIC.ELSE:
+            return new ConditionalLogicInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.FOR_EACH:
+            return new ForEachInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.GOBACKTO:
+            return new GoBackToInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.TRY_CATCH:
+            return new TryCatchInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.DO_IN_PARALLEL:
+            return new DoInParallelInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.SET_FLOW_VARIABLES:
+            return new SetFlowVariablesInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS:
+            return new AssignSubflowOutputsInstanceShape(expr, callee, args)
+        case FLOW_LOGIC.WAIT_FOR_A_DURATION:
+        case FLOW_LOGIC.ENDFLOW:
+        case FLOW_LOGIC.EXITLOOP:
+        case FLOW_LOGIC.SKIP_ITERATION:
+            return new FlowLogicInstanceShape(expr, callee, args)
+
+        default:
+            // Fallback to the deprecated generic shape for unknown types
+            throw new Error(`Unknown flow logic type: ${callee}`)
+    }
+}

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

@@ -0,0 +1,48 @@
+import { Plugin } from '@servicenow/sdk-build-core'
+import { APPROVAL_DUE_DATE_API_NAME, APPROVAL_RULES_API_NAME } from '../utils/flow-constants'
+import { ApprovalDueDateShape, ApprovalRulesShape } from '../utils/flow-shapes'
+import { getCallExpressionName } from '../../utils'
+
+export const ApprovalRulesPlugin = Plugin.create({
+    name: 'ApprovalRulesPlugin',
+    nodes: [
+        {
+            node: 'CallExpression',
+            fileTypes: ['fluent'],
+            entryPoint: true,
+            async toShape(node, { transform }) {
+                const callee = getCallExpressionName(node)
+                if (callee !== APPROVAL_RULES_API_NAME && callee !== APPROVAL_DUE_DATE_API_NAME) {
+                    return { success: false }
+                }
+                const nodeData = node.getArguments()[0]
+
+                if (!nodeData) {
+                    return { success: false }
+                }
+
+                const result = await transform.toShape(nodeData)
+                if (!result.success) {
+                    return result
+                }
+                const value = result.value.asObject().properties({ resolve: false })
+                if (callee === APPROVAL_DUE_DATE_API_NAME) {
+                    return {
+                        success: true,
+                        value: new ApprovalDueDateShape({
+                            source: node,
+                            value: value,
+                        }),
+                    }
+                }
+                return {
+                    success: true,
+                    value: new ApprovalRulesShape({
+                        source: node,
+                        value: value,
+                    }),
+                }
+            },
+        },
+    ],
+})