@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

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

@@ -0,0 +1,431 @@
+import {
+    Plugin,
+    CallExpressionShape,
+    ObjectShape,
+    type Record as BuildRecord,
+    type Factory,
+    type Shape,
+    type Source,
+} from '@servicenow/sdk-build-core'
+import type { NowIdShape } from '../../now-id-plugin'
+import { sysIdToUuid } from '../utils/utils'
+import { COLUMN_API_TO_TYPE } from '../../column/column-helper'
+import { ACTION_STEP_INSTANCE_API_NAME } from '../utils/flow-constants'
+
+// Error handling type mapping: string to number
+const ERROR_HANDLING_TYPE_MAP: Record<string, number> = {
+    stop_the_action: 1,
+    dont_stop_the_action: 2,
+}
+
+/**
+ * StepInstanceShape represents a step instance within a custom action's body
+ * This class handles the shape transformation for step instances
+ */
+export class StepInstanceShape extends CallExpressionShape {
+    private config: ObjectShape
+    private sysId: NowIdShape | Shape
+    private stepDefinitionSysId: string
+    private stepLabel: string
+    private inputs: ObjectShape | undefined
+    private inputDefinitions: ObjectShape | undefined
+
+    constructor(args: {
+        source: Source
+        config: ObjectShape
+        sysId: NowIdShape | Shape
+        stepDefinitionSysId: string
+        stepLabel: string
+        inputs: ObjectShape | undefined
+        extendedConfig?: ObjectShape
+        inputDefinitions?: ObjectShape
+    }) {
+        const { source, sysId, config, stepDefinitionSysId, stepLabel, inputs, inputDefinitions } = args
+        super({ source, callee: 'StepInstance', args: [sysId, config, stepDefinitionSysId] })
+        this.config = config
+        this.sysId = sysId
+        this.stepDefinitionSysId = stepDefinitionSysId
+        this.stepLabel = stepLabel
+        this.inputs = inputs
+        this.inputDefinitions = inputDefinitions
+    }
+
+    getConfig(): ObjectShape {
+        return this.config
+    }
+
+    getSysId(): NowIdShape | Shape {
+        return this.sysId
+    }
+
+    getStepDefinitionSysId(): string {
+        return this.stepDefinitionSysId
+    }
+
+    getStepLabel(): string {
+        return (this.config.get('label')?.getValue() as string) ?? this.stepLabel
+    }
+
+    getInputs(): ObjectShape | undefined {
+        return this.inputs
+    }
+
+    getInputDefinitions(): ObjectShape | undefined {
+        return this.inputDefinitions
+    }
+}
+
+export const StepInstancePlugin = Plugin.create({
+    name: 'StepInstancePlugin',
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(callExpression, { diagnostics }) {
+                if (callExpression.getCallee() !== ACTION_STEP_INSTANCE_API_NAME) {
+                    return { success: false }
+                }
+
+                const args = callExpression.getArguments()
+                // Accept 3 arguments
+                if (args.length !== 3) {
+                    diagnostics.error(
+                        callExpression,
+                        `Expected 3 arguments for StepInstance, but received ${args.length}`
+                    )
+                    return { success: false }
+                }
+
+                const [stepDefinition, stepInstanceConfig, inputs] = args
+
+                // Validate first argument is a StepDefinition
+                if (
+                    !(stepDefinition instanceof CallExpressionShape) ||
+                    stepDefinition.getCallee() !== 'ActionStepDefinition'
+                ) {
+                    diagnostics.error(callExpression, 'Expected first argument to be a ActionStepDefinition')
+                    return { success: false }
+                }
+
+                // Validate second argument is a valid ID
+                if (!(stepInstanceConfig instanceof ObjectShape)) {
+                    diagnostics.error(callExpression, 'Expected second argument to be a valid ID')
+                    return { success: false }
+                }
+
+                // Validate third argument is an object
+                if (!(inputs instanceof ObjectShape)) {
+                    diagnostics.error(callExpression, 'Expected third argument to be an object')
+                    return { success: false }
+                }
+
+                const stepConfig = stepDefinition.getArgument(0).asObject()
+                const shapeArgs: {
+                    source: Source
+                    config: ObjectShape
+                    sysId: NowIdShape | Shape
+                    stepDefinitionSysId: string
+                    stepLabel: string
+                    inputs: ObjectShape | undefined
+                    inputDefinitions?: ObjectShape
+                } = {
+                    source: callExpression,
+                    sysId: stepInstanceConfig.get('$id')?.getValue() as NowIdShape | Shape,
+                    config: stepInstanceConfig,
+                    stepDefinitionSysId: stepConfig.get('$id')?.getValue() as string,
+                    stepLabel: stepConfig.get('name')?.getValue() as string,
+                    inputDefinitions: stepConfig.get('inputs')?.asObject(),
+                    inputs: inputs,
+                }
+
+                return {
+                    success: true,
+                    value: new StepInstanceShape(shapeArgs),
+                }
+            },
+        },
+        {
+            shape: StepInstanceShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory }) {
+                const stepInstanceRecord = await buildStepInstanceRecord({
+                    callExpression,
+                    factory,
+                    values: callExpression.getInputs() as ObjectShape,
+                    sysId: callExpression.getSysId(),
+                    stepDefinitionSysId: callExpression.getStepDefinitionSysId(),
+                    stepLabel: callExpression.getStepLabel(),
+                    inputs: callExpression.getInputDefinitions(),
+                })
+                return { success: true, value: stepInstanceRecord }
+            },
+        },
+    ],
+    records: {
+        sys_hub_step_ext_input: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_step_ext_output: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_step_instance: {
+            relationships: {
+                sys_variable_value: {
+                    via: 'document_key',
+                    descendant: true,
+                },
+                sys_flow_step_definition: {
+                    via: 'step_type',
+                    descendant: false,
+                },
+                sys_hub_step_ext_input: {
+                    via: 'model',
+                    descendant: true,
+                },
+                sys_hub_step_ext_output: {
+                    via: 'model',
+                    descendant: true,
+                },
+                sys_translated_text: {
+                    via: 'documentkey',
+                    descendant: true,
+                },
+            },
+            // toShape(record, { descendants, diagnostics }) {
+            //     // Get the step definition reference
+            //     const stepDefinitionRecords = descendants.query('sys_flow_step_definition')
+            //     if (stepDefinitionRecords.length === 0) {
+            //         diagnostics.error(record, 'Could not find step definition for step instance')
+            //         return { success: false }
+            //     }
+
+            //     const stepDefinition = stepDefinitionRecords[0]
+            //     if (!stepDefinition) {
+            //         diagnostics.error(record, 'Step definition is undefined')
+            //         return { success: false }
+            //     }
+
+            //     // Build the config object from sys_variable_value records
+            //     const variableValues = descendants.query('sys_variable_value')
+            //     const configObj: globalThis.Record<string, any> = {}
+
+            //     for (const varValue of variableValues) {
+            //         const variableSysId = varValue.get('variable')?.asString()?.getValue()
+            //         const value = varValue.get('value')?.asString()?.getValue()
+
+            //         // Find the matching input definition to get the element name
+            //         const inputRecords = descendants.query('sys_flow_step_definition_input', { sysId: variableSysId })
+            //         if (inputRecords.length > 0) {
+            //             const elementName = inputRecords[0]?.get('element')?.asString()?.getValue()
+            //             if (elementName) {
+            //                 // Try to parse JSON values, otherwise use as string
+            //                 try {
+            //                     configObj[elementName] = JSON.parse(value || '')
+            //                 } catch {
+            //                     configObj[elementName] = value
+            //                 }
+            //             }
+            //         }
+            //     }
+
+            //     // Add error_handling_type and label from the step instance record itself
+            //     const errorHandlingType = record.get('error_handling_type')?.asNumber()?.getValue()
+            //     if (errorHandlingType !== undefined && errorHandlingType !== 1) {
+            //         configObj['error_handling_type'] = errorHandlingType
+            //     }
+
+            //     const label = record.get('label')?.asString()?.getValue()
+            //     const stepName = stepDefinition.get('name')?.asString()?.getValue()
+            //     if (label && label !== stepName) {
+            //         configObj['label'] = label
+            //     }
+
+            //     // Create the StepDefinition CallExpressionShape reference
+            //     const stepDefinitionShape = new CallExpressionShape({
+            //         source: stepDefinition,
+            //         callee: 'StepDefinition',
+            //         args: [
+            //             stepDefinition.transform(({ $ }) => ({
+            //                 $id: $.val(NowIdShape.from(stepDefinition)),
+            //                 name: $,
+            //             })),
+            //         ],
+            //     })
+
+            //     // Create the config ObjectShape
+            //     const configProperties: globalThis.Record<string, any> = {}
+            //     for (const [key, value] of Object.entries(configObj)) {
+            //         configProperties[key] = value
+            //     }
+
+            //     const configShape = new ObjectShape({
+            //         source: record,
+            //         properties: configProperties,
+            //     })
+
+            //     return {
+            //         success: true,
+            //         value: new CallExpressionShape({
+            //             source: record,
+            //             callee: 'StepInstance',
+            //             args: [stepDefinitionShape, NowIdShape.from(record), configShape],
+            //         }),
+            //     }
+            // },
+        },
+    },
+})
+
+async function buildStepInstanceRecord({
+    callExpression,
+    factory,
+    values,
+    sysId,
+    stepDefinitionSysId,
+    stepLabel,
+    inputs,
+}: {
+    callExpression: StepInstanceShape
+    factory: Factory
+    values: ObjectShape
+    sysId: NowIdShape | Shape
+    stepDefinitionSysId: string
+    stepLabel: string
+    inputs: ObjectShape | undefined
+}): Promise<BuildRecord> {
+    // Create step instance record
+    const stepInstanceRecord = await factory.createRecord({
+        source: callExpression,
+        explicitId: sysId,
+        table: 'sys_hub_step_instance',
+        properties: {
+            step_type: stepDefinitionSysId,
+            order: 1,
+            active: true,
+            error_handling_type: ERROR_HANDLING_TYPE_MAP[values.get('errorHandlingType')?.getValue() as string] ?? 1,
+            label: stepLabel,
+        },
+    })
+    const updatedStepInstanceRecord = stepInstanceRecord.merge({
+        cid: sysIdToUuid(stepInstanceRecord.getId().getValue()),
+    })
+    const stepInstanceSysId = updatedStepInstanceRecord.getId().getValue()
+    // Create sys_variable_value records for each input value
+    const variableValueRecords = await createVariableRecords(values, inputs, factory, callExpression, stepInstanceSysId)
+    const extendedInputRecords: BuildRecord[] = []
+    const extendedOutputRecords: BuildRecord[] = []
+    const extendedVariableValueRecords: BuildRecord[] = []
+
+    const valuesArray = values.properties()
+    // biome-ignore lint/suspicious/noExplicitAny: Dynamic input variable config
+    const inputVariables = valuesArray['inputVariables']?.getValue() as Record<string, any>
+    if (inputVariables) {
+        for (const [name, config] of Object.entries(inputVariables)) {
+            const label = config.label
+            const mandatory = config.mandatory
+            const defaultValue = config.defaultValue ?? ''
+            const value = config.value
+            const extInputRecord = await factory.createRecord({
+                source: callExpression,
+                table: 'sys_hub_step_ext_input',
+                properties: {
+                    active: true,
+                    model: stepInstanceSysId,
+                    model_id: stepInstanceSysId,
+                    model_table: 'sys_hub_step_instance',
+                    name: `var__m_sys_hub_step_ext_input_${stepInstanceSysId}`,
+                    element: name,
+                    label: label,
+                    mandatory: mandatory,
+                    default_value: defaultValue,
+                },
+            })
+            extendedInputRecords.push(extInputRecord)
+            extendedVariableValueRecords.push(
+                await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_variable_value',
+                    properties: {
+                        document: 'sys_hub_step_instance',
+                        document_key: stepInstanceSysId,
+                        order: 100,
+                        value: value,
+                        variable: extInputRecord.getId().getValue(),
+                    },
+                })
+            )
+        }
+    }
+
+    const outputVariables = valuesArray['outputVariables']
+    if (outputVariables) {
+        const outputItemShape = outputVariables.asObject()
+        const outputProperties = outputItemShape.properties()
+
+        for (const [columnName, columnCallExpr] of Object.entries(outputProperties)) {
+            const callExpr = columnCallExpr.as(CallExpressionShape)
+            const columnType = callExpr.getCallee() // e.g., 'StringColumn', 'IntegerColumn'
+            const columnConfig = callExpr.getArgument(0)?.asObject()
+            const columnLabel = columnConfig?.get('label')?.getValue() as string
+            const mandatory = columnConfig?.get('mandatory')?.getValue() as boolean
+            const internalType = COLUMN_API_TO_TYPE[columnType] || 'string'
+            const extOutputRecord = await factory.createRecord({
+                source: callExpression,
+                table: 'sys_hub_step_ext_output',
+                properties: {
+                    active: true,
+                    model: stepInstanceSysId,
+                    model_id: stepInstanceSysId,
+                    model_table: 'sys_hub_step_instance',
+                    name: `var__m_sys_hub_step_ext_output_${stepInstanceSysId}`,
+                    element: columnName,
+                    label: columnLabel || columnName,
+                    internal_type: internalType,
+                    mandatory: mandatory,
+                },
+            })
+            extendedOutputRecords.push(extOutputRecord)
+        }
+    }
+
+    return updatedStepInstanceRecord.with(
+        ...variableValueRecords,
+        ...extendedInputRecords,
+        ...extendedVariableValueRecords,
+        ...extendedOutputRecords
+    )
+}
+async function createVariableRecords(
+    values: ObjectShape,
+    inputs: ObjectShape | undefined,
+    factory: Factory,
+    callExpression: StepInstanceShape,
+    stepInstanceSysId: string
+) {
+    const properties = values.properties()
+    // Filter out inputVariables, outputVariables and errorHandlingType as they are handled separately
+    const filteredEntries = Object.entries(properties).filter(
+        ([key]) => key !== 'inputVariables' && key !== 'outputVariables' && key !== 'errorHandlingType'
+    )
+    return await Promise.all(
+        filteredEntries.map(([key, valueShape]) => {
+            const input = inputs?.get(key)
+            const variableSysId =
+                input instanceof CallExpressionShape
+                    ? (input.getArgument(0).asObject().get('sysId')?.getValue() as string)
+                    : ''
+            const actualValue = valueShape.getValue?.() ?? valueShape.toString()
+            return factory.createRecord({
+                source: callExpression,
+                table: 'sys_variable_value',
+                properties: {
+                    document: 'sys_hub_step_instance',
+                    document_key: stepInstanceSysId,
+                    order: 100,
+                    value: actualValue,
+                    variable: variableSysId,
+                },
+            })
+        })
+    )
+}

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

@@ -0,0 +1,95 @@
+import { CallExpressionShape, Plugin } from '@servicenow/sdk-build-core'
+import { buildVariableShapes, complexObjectMatchesIoRecord } from '../utils/flow-io-to-record'
+import { NowIdShape } from '../../now-id-plugin'
+
+export const TriggerPlugin = Plugin.create({
+    name: 'TriggerPlugin',
+    records: {
+        sys_hub_trigger_definition: {
+            relationships: {
+                sys_hub_trigger_input: {
+                    via: 'model_id',
+                    descendant: true,
+                    relationships: {
+                        sys_documentation: {
+                            via: { name: 'name', element: 'element' },
+                            descendant: true,
+                        },
+                        sys_choice: {
+                            via: { name: 'name', element: 'element' },
+                            descendant: true,
+                        },
+                        sys_variable_value: {
+                            via: 'variable',
+                            descendant: true,
+                        },
+                        sys_complex_object: {
+                            via: [complexObjectMatchesIoRecord],
+                            descendant: true,
+                            inverse: true,
+                        },
+                    },
+                },
+                sys_hub_trigger_output: {
+                    via: 'model',
+                    descendant: true,
+                    relationships: {
+                        sys_documentation: {
+                            via: { name: 'name', element: 'element' },
+                            descendant: true,
+                        },
+                        sys_choice: {
+                            via: { name: 'name', element: 'element' },
+                            descendant: true,
+                        },
+                        sys_variable_value: {
+                            via: 'variable',
+                            descendant: true,
+                        },
+                        sys_complex_object: {
+                            via: [complexObjectMatchesIoRecord],
+                            descendant: true,
+                            inverse: true,
+                        },
+                    },
+                },
+            },
+            toShape(record, { descendants }) {
+                const inputRecords = descendants.query('sys_hub_trigger_input')
+                const outputRecords = descendants.query('sys_hub_trigger_output')
+
+                const inputs = inputRecords.length > 0 ? buildVariableShapes(inputRecords, descendants) : {}
+                const outputs = outputRecords.length > 0 ? buildVariableShapes(outputRecords, descendants) : {}
+
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'TriggerDefinition',
+                        args: [
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                name: $,
+                                type: $,
+                                ...(Object.keys(inputs ?? {}).length > 0 ? { inputs: $.val(inputs) } : {}),
+                                ...(Object.keys(outputs ?? {}).length > 0 ? { outputs: $.val(outputs) } : {}),
+                            })),
+                        ],
+                    }),
+                }
+            },
+        },
+        sys_hub_trigger_input: {
+            coalesce: ['model', 'element'],
+        },
+        sys_hub_trigger_output: {
+            coalesce: ['model', 'element'],
+        },
+        sys_variable_value: {
+            coalesce: ['document_key', 'variable'],
+        },
+        sys_complex_object: {
+            coalesce: ['name'],
+        },
+    },
+})