@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

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

@@ -0,0 +1,444 @@
+import {
+    CallExpressionShape,
+    DurationShape,
+    IdentifierShape,
+    ObjectShape,
+    Plugin,
+    StringShape,
+    TimeShape,
+    UnresolvedShape,
+} from '@servicenow/sdk-build-core'
+import { normalizeInputValue } from './flow-instance-plugin'
+import { NowIdShape } from '../../now-id-plugin'
+import { gunzipSync, gzipSync } from 'node:zlib'
+import { COLUMN_API_TO_TYPE } from '../../column/column-helper'
+import {
+    TRIGGER_INSTANCE_API_NAME,
+    TRIGGER_TYPE_KEY_NAME,
+    RUN_ON_EXTENDED,
+    TIME_DATA_TYPE_VALUE,
+    DURATION_DATA_TYPE_VALUE,
+} from '../utils/flow-constants'
+import { DAY_OF_WEEK_DISPLAY_MAP } from '../constants/flow-plugin-constants'
+import { isArray } from 'lodash'
+
+export const TriggerInstancePlugin = Plugin.create({
+    name: 'TriggerInstancePlugin',
+    records: {
+        sys_hub_trigger_instance_v2: {
+            toShape(record, { logger, database }) {
+                const gzStr = record.get('trigger_inputs').as(StringShape).getValue()
+                const inputsObj: globalThis.Record<string, unknown> = {}
+                const triggerType = record.get('trigger_type')?.getValue()
+
+                try {
+                    const arr = JSON.parse(gunzipSync(Buffer.from(gzStr, 'base64')).toString('utf8')) as Array<{
+                        name: string
+                        value: string
+                        parameter: {
+                            type: string
+                            attributes: Record<string, unknown>
+                        }
+                    }>
+
+                    for (const { name, value, parameter } of arr) {
+                        const visibleAttr = parameter?.attributes?.['visible'] as string | undefined
+                        const visibleInFdAttr = parameter?.attributes?.['visible_in_fd'] as string | undefined
+                        const isHidden = visibleAttr === 'false' || visibleInFdAttr === 'false'
+                        // Skip hidden fields during transformation
+                        if (isHidden) {
+                            continue
+                        }
+                        // Safely extract uiType, guarding against missing parameter or attributes
+                        const uiType = (parameter?.attributes?.['uiType'] ?? parameter?.type) as string | undefined
+
+                        let finalValue = value
+                        // For service catalog trigger's run_flow_in, read from sys_flow_catalog_trigger table when empty
+                        if (
+                            name === 'run_flow_in' &&
+                            (value === '' || value === undefined) &&
+                            triggerType === 'service_catalog'
+                        ) {
+                            const flowSysId = record.get('flow')?.ifString()?.getValue()
+                            const flowRecord = flowSysId ? database.get('sys_hub_flow', flowSysId) : undefined
+                            const remoteTriggerIdValue = flowRecord?.get('remote_trigger_id')?.ifString()?.getValue()
+                            const catalogTriggerRecord = remoteTriggerIdValue
+                                ? database.get('sys_flow_catalog_trigger', remoteTriggerIdValue)
+                                : undefined
+                            const runFlowInValue = catalogTriggerRecord?.get('run_flow_in')?.ifString()?.getValue()
+                            finalValue = runFlowInValue || 'background'
+                        }
+
+                        if (name === RUN_ON_EXTENDED) {
+                            inputsObj[name] = finalValue // As this is a choice value, we don't need to normalize it. It should remain as a string. Keep it as 'true' or 'false'
+                        } else {
+                            inputsObj[name] = normalizeInputValue(finalValue, uiType, record, logger)
+                        }
+                    }
+                } catch (err: unknown) {
+                    logger.error(`Corrupt data in trigger instance ${err} in flow ${record.get('flow').getValue()}`)
+                    throw new Error('Corrupt data in trigger instance')
+                }
+
+                //Check if it is a custom trigger - Custom triggers will have trigger_type attribute in the trigger inputs
+                if (inputsObj[TRIGGER_TYPE_KEY_NAME]) {
+                    logger.warn('Customer trigger types are not supported')
+                    return { success: false }
+                }
+
+                let triggerIdentifier: IdentifierShape | undefined
+
+                // Map sys_hub_trigger_instance_v2.trigger_type values to the corresponding
+                // `*.now.ts` TriggerDefinition identifier exported from /automation
+
+                // This allows round-tripping of triggers beyond simple "record_create" events.
+                const triggerMap: Record<string, string> = {
+                    // Record based triggers
+                    record_create: 'trigger.record.created',
+                    record_update: 'trigger.record.updated',
+                    record_create_or_update: 'trigger.record.createdOrUpdated',
+
+                    // SLA triggers
+                    daily: 'trigger.scheduled.daily',
+                    weekly: 'trigger.scheduled.weekly',
+                    monthly: 'trigger.scheduled.monthly',
+                    repeat: 'trigger.scheduled.repeat',
+                    run_once: 'trigger.scheduled.runOnce',
+
+                    // Application triggers
+                    email: 'trigger.application.inboundEmail',
+                    service_catalog: 'trigger.application.serviceCatalog',
+                    remote_table_query: 'trigger.application.remoteTableQuery',
+                    sla_task: 'trigger.application.slaTask',
+                    knowledge_management: 'trigger.application.knowledgeManagement',
+                }
+
+                const identifierName = triggerMap[triggerType as string]
+                if (identifierName) {
+                    triggerIdentifier = new IdentifierShape({ source: record, name: identifierName })
+                } else {
+                    logger.warn(`Unsupported trigger type = ${triggerType}, falling back to Record() API`)
+                    return { success: false }
+                }
+
+                // New 3-argument pattern: wfa.trigger(triggerDefinition, { $id }, inputs)
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: TRIGGER_INSTANCE_API_NAME,
+                        args: [
+                            // Arg 0: Trigger definition identifier
+                            triggerIdentifier,
+                            // Arg 1: Config object with $id and annotation
+                            record.transform(({ $ }) => ({
+                                $id: $.val(NowIdShape.from(record)),
+                                annotation: $.from('comment').def(''),
+                            })),
+                            // Arg 2: Inputs object
+                            new ObjectShape({ source: record, properties: inputsObj }),
+                        ],
+                    }),
+                }
+            },
+        },
+    },
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            async toRecord(callExpression, { factory, diagnostics }) {
+                if (callExpression.getCallee() !== TRIGGER_INSTANCE_API_NAME) {
+                    return { success: false }
+                }
+
+                // New 3-argument pattern: wfa.trigger(triggerDefinition, { $id }, inputs)
+                // Arg 0: Trigger definition (IdentifierShape or CallExpressionShape)
+                // Arg 1: Config object with $id
+                // Arg 2: Inputs object
+                const triggerShape = callExpression.getArgument(0)
+                const configObject = callExpression.getArgument(1)?.asObject()
+                const triggerInputs = callExpression.getArgument(2)?.asObject()
+
+                if (!configObject || !triggerInputs) {
+                    diagnostics.error(
+                        callExpression,
+                        'Trigger instance requires 3 arguments: triggerDefinition, config, and inputs'
+                    )
+                    return { success: false }
+                }
+
+                // Check if trigger definition is unresolved
+                if (triggerShape.is(UnresolvedShape)) {
+                    diagnostics.error(
+                        triggerShape,
+                        'Trigger definition could not be resolved. Make sure the trigger definition is imported and available.'
+                    )
+                    return {
+                        success: false,
+                    }
+                }
+
+                // Handle both IdentifierShape (e.g., trigger.record.created) and CallExpressionShape (inline definition)
+                let triggerDefinitionObject: ObjectShape
+                if (triggerShape.is(CallExpressionShape)) {
+                    const triggerDefinition = triggerShape.as(CallExpressionShape)
+                    triggerDefinitionObject = triggerDefinition.getArgument(0).asObject()
+                } else if (triggerShape.is(IdentifierShape)) {
+                    // For IdentifierShape, we need to resolve it to get the trigger definition
+                    const resolved = triggerShape.resolve()
+                    if (resolved.is(CallExpressionShape)) {
+                        triggerDefinitionObject = resolved.as(CallExpressionShape).getArgument(0).asObject()
+                    } else {
+                        diagnostics.error(triggerShape, 'Could not resolve trigger definition from identifier')
+                        return { success: false }
+                    }
+                } else {
+                    diagnostics.error(triggerShape, 'Trigger definition must be a trigger identifier or definition')
+                    return { success: false }
+                }
+
+                const gzippedInputs = createTriggerInputsForTriggerInstance({
+                    triggerInstanceInputs: triggerInputs,
+                    triggerDefinition: triggerDefinitionObject,
+                })
+
+                const triggerInstanceRecord = await factory.createRecord({
+                    source: callExpression,
+                    table: 'sys_hub_trigger_instance_v2',
+                    explicitId: configObject.get('$id'),
+                    properties: configObject.transform(({ $ }) => ({
+                        name: $.val(triggerDefinitionObject.get('name').getValue()), // Created
+                        trigger_definition: $.val(triggerDefinitionObject.get('$id').getValue()),
+                        trigger_inputs: $.val(gzippedInputs), // Gzip string of inputs
+                        trigger_outputs: $.val(''),
+                        trigger_type: $.val(triggerDefinitionObject.get('type').getValue()),
+                        comment: $.from('annotation').def(''), // Annotation field
+                        // flow: //- This field will be populated in flow plugin
+                        category: $.def(''),
+                    })),
+                })
+
+                return {
+                    success: true,
+                    value: triggerInstanceRecord,
+                }
+            },
+        },
+    ],
+})
+
+type InputDefinitions = Record<string, CallExpressionShape>
+
+/**
+ * Builds the `choiceList` array expected by the record JSON.
+ *
+ * @param choices An object whose keys are the choice values and whose
+ *                values contain at least a `label` property.
+ * @param triggerDefId The $id of the trigger definition currently being processed.
+ */
+function buildChoiceList(
+    choices: Record<string, { label?: string; [k: string]: unknown }> | undefined,
+    _triggerDefId: string
+) {
+    if (!choices) {
+        return []
+    }
+    return Object.entries(choices).map(([value, data]) => ({
+        fValue: value,
+        fLabel:
+            typeof data === 'object' && data && 'label' in data ? (data as { label?: string }).label : String(value),
+        fImage: '',
+        // fParameters: {
+        //     name: `var__m_sys_hub_trigger_input_${triggerDefId}`,
+        // },
+        fSelected: false,
+        fUsed: false,
+        fMissing: false,
+    }))
+}
+
+/**
+ * Maps field types to their display value transformations.
+ * Add new entries here to support additional field transformations.
+ *
+ * @example
+ * // To add month transformation:
+ * // 'month': MONTH_DISPLAY_MAP
+ */
+const FIELD_DISPLAY_MAPS: Record<string, Record<string, string>> = {
+    day_of_week: DAY_OF_WEEK_DISPLAY_MAP,
+    // Add more mappings here as needed
+}
+
+/**
+ * Transforms trigger input values to their display values.
+ * Only applies transformation if the field type is in the transformation map.
+ * Preserves original value type for fields that don't need transformation.
+ *
+ * @param fieldName - The name of the field
+ * @param value - The actual value (preserves original type)
+ * @param columnType - The column type (e.g., 'day_of_week', 'glide_time')
+ * @returns Object with original value and string displayValue
+ *
+ * @example
+ * // With transformation:
+ * transformTriggerInputValue('day_of_week', 1, 'day_of_week')
+ * // Returns: { value: 1, displayValue: 'Monday' }
+ *
+ * @example
+ * // Without transformation:
+ * transformTriggerInputValue('priority', 3, 'integer')
+ * // Returns: { value: 3, displayValue: '3' }
+ */
+function transformTriggerInputValue(
+    fieldName: string,
+    value: unknown,
+    columnType: string,
+    triggerInstanceInputs: ObjectShape
+): { value: unknown; displayValue: string } {
+    // First, check if this field needs transformation
+    const displayMap = FIELD_DISPLAY_MAPS[columnType] || FIELD_DISPLAY_MAPS[fieldName]
+
+    if (!displayMap) {
+        const inputValueShape = triggerInstanceInputs.get(fieldName)
+        // Handle glide_time type by converting TimeShape to string
+        if (columnType === TIME_DATA_TYPE_VALUE && inputValueShape?.is(TimeShape)) {
+            value = inputValueShape.as(TimeShape).toString().getValue()
+        } else if (columnType === DURATION_DATA_TYPE_VALUE && inputValueShape?.is(DurationShape)) {
+            value = inputValueShape.as(DurationShape).toString().getValue()
+        }
+
+        return {
+            value: value ?? '',
+            displayValue: String(value ?? ''),
+        }
+    }
+
+    // Transformation is needed - convert to string for mapping lookup
+    const stringValue = String(value ?? '')
+    const displayValue = displayMap[stringValue]
+
+    return {
+        value: stringValue, // Keep as string since transformation was applied
+        displayValue: displayValue || stringValue, // Fallback if no mapping found
+    }
+}
+
+function createTriggerInputsForTriggerInstance({
+    triggerInstanceInputs,
+    triggerDefinition,
+}: {
+    triggerInstanceInputs: ObjectShape
+    triggerDefinition: ObjectShape
+}): string {
+    // Get trigger input definitions if they exist
+    const inputDefinitions = triggerDefinition.get('inputs').ifObject()?.properties()
+
+    // Return empty array if no valid inputs exist
+    if (!inputDefinitions || Object.keys(inputDefinitions).length === 0) {
+        return gzipSync(JSON.stringify([])).toString('base64')
+    }
+
+    // Get the set of provided input names
+    const providedInputNames = new Set(triggerInstanceInputs.keys())
+
+    // Transform input definitions into trigger inputs
+    const triggerInputs: TriggerInput[] = Object.entries(inputDefinitions as InputDefinitions).map(
+        ([name, inputCallExpr]) => {
+            const fieldProps = inputCallExpr.getArguments()[0]?.getValue() as FieldProperties | undefined
+
+            // Get user-provided value or fall back to default value from definition
+            let userValue = triggerInstanceInputs.get(name)?.getValue()
+
+            // If no value provided and a default exists, use the default
+            if (userValue === undefined && !providedInputNames.has(name) && fieldProps?.default !== undefined) {
+                userValue = fieldProps.default
+            }
+
+            if (isArray(userValue)) {
+                userValue = userValue.join(',') // Convert array to comma-separated string
+            }
+
+            // Apply default value if user didn't specify a value or provided empty string
+            if ((userValue === undefined || userValue === '') && fieldProps?.default !== undefined) {
+                userValue = fieldProps.default
+            }
+
+            const type =
+                inputCallExpr.getCallee() === 'GenericColumn'
+                    ? (fieldProps?.columnType ?? '') // Use columnType for GenericColumn
+                    : (COLUMN_API_TO_TYPE[inputCallExpr.getCallee()] ?? '')
+
+            // Transform value and displayValue using the utility function
+            const { value, displayValue } = transformTriggerInputValue(name, userValue, type, triggerInstanceInputs)
+
+            return {
+                triggerInstanceSysId: '',
+                label: fieldProps?.label ?? '',
+                internalType: type,
+                dependent: '',
+                choiceList: buildChoiceList(fieldProps?.choices, triggerDefinition.get('$id').asString().getValue()),
+                mandatory: fieldProps?.mandatory ?? false,
+                order: 100,
+                name,
+                value,
+                displayValue,
+                displayField: '',
+                scriptActive: false, // TODO: populate later
+                ...(type === 'glide_list' && { valueSysId: '' }),
+                children: [], // Check and remove later
+                parameter: {
+                    type,
+                    name,
+                    label: fieldProps?.label ?? '',
+                    ...(fieldProps?.attributes && typeof fieldProps.attributes === 'object'
+                        ? { attributes: { ...fieldProps.attributes } }
+                        : {}),
+                    ...(fieldProps?.dependent_on
+                        ? {
+                              dependent_on: fieldProps.dependent_on,
+                              use_dependent: true,
+                          }
+                        : {}),
+                    ...(fieldProps?.reference
+                        ? {
+                              reference: fieldProps.reference,
+                              reference_display: fieldProps.reference_display,
+                          }
+                        : {}),
+                },
+            } as TriggerInput
+        }
+    )
+    return gzipSync(JSON.stringify(triggerInputs)).toString('base64')
+}
+
+interface FieldProperties {
+    default?: unknown
+    label?: string
+    mandatory?: boolean
+    columnType?: string
+    choices?: Record<string, { label?: string; [key: string]: unknown }>
+    attributes?: Record<string, unknown>
+    dependent_on?: unknown
+    reference?: unknown
+    reference_display?: unknown
+    [key: string]: unknown
+}
+
+interface TriggerInput {
+    triggerInstanceSysId: string
+    label: string
+    internalType: string
+    dependent: string
+    choiceList: unknown[]
+    mandatory: boolean
+    order: number
+    name: string
+    value: unknown
+    displayValue: string
+    displayField: string
+    scriptActive: boolean
+    parameter: object
+}

package/src/flow/plugins/inline-script-plugin.ts

@@ -0,0 +1,83 @@
+import { CallExpressionShape, Plugin, type Source } from '@servicenow/sdk-build-core'
+
+/**
+ * Shape representing an inline script created via wfa.inlineScript('script content').
+ *
+ * This shape is used for Flow Designer inline scripts that are authored directly
+ * in Fluent code rather than in external files.
+ */
+export class FDInlineScriptCallShape extends CallExpressionShape {
+    private readonly scriptContent: string
+
+    constructor({ source, scriptContent }: { source: Source; scriptContent: string }) {
+        super({ source, callee: 'wfa.inlineScript', args: [scriptContent] })
+        this.scriptContent = scriptContent
+    }
+
+    /**
+     * Gets the inline script content.
+     */
+    getScriptContent(): string {
+        return this.scriptContent
+    }
+
+    /**
+     * Returns the script content as the value.
+     * This is used during serialization to XML.
+     */
+    override getValue(): string {
+        return this.scriptContent
+    }
+}
+
+/**
+ * Plugin to handle wfa.inlineScript() calls in Flow Designer.
+ *
+ * This plugin provides bi-directional conversion between Fluent and XML:
+ *
+ * **Fluent → XML (toSubclass):**
+ * - Detects `wfa.inlineScript('script')` calls in Fluent code
+ * - Converts to FDInlineScriptCallShape for XML serialization
+ * - Serialization handled by flow-instance-plugin via InlineScriptShape
+ *
+ * **XML → Fluent (in flow-instance-plugin):**
+ * - Detects `scriptActive: true` in XML
+ * - Creates FDInlineScriptCallShape via convertInlineScriptToInlineScriptCall()
+ * - Generates `wfa.inlineScript('script')` in Fluent code
+ */
+export const InlineScriptPlugin = Plugin.create({
+    name: 'InlineScriptPlugin',
+    shapes: [
+        {
+            shape: CallExpressionShape,
+            fileTypes: ['fluent'],
+            toSubclass(callExpression, { diagnostics }) {
+                // Only handle wfa.inlineScript() calls
+                if (callExpression.getCallee() !== 'wfa.inlineScript') {
+                    return { success: false }
+                }
+
+                // Validate the argument is a string
+                const arg = callExpression.getArgument(0)
+                if (!arg.isString()) {
+                    diagnostics.error(arg, 'wfa.inlineScript() must have a string argument')
+                    return { success: false }
+                }
+
+                // Extract script content and create specialized shape
+                const scriptContent = arg.getValue()
+
+                return {
+                    success: true,
+                    value: new FDInlineScriptCallShape({
+                        source: callExpression,
+                        scriptContent,
+                    }),
+                }
+            },
+        },
+        // Note: No commit handlers needed for Flow Designer bi-directional workflow
+        // - Fluent → XML uses InlineScriptShape.toFlowDesignerJson() in flow-instance-plugin
+        // - XML → Fluent uses buildInlineScriptShapeFromXml() in flow-instance-plugin
+    ],
+})

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

@@ -0,0 +1,67 @@
+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'
+/**
+ * Plugin for processing StepDefinition calls
+ */
+export const StepDefinitionPlugin = Plugin.create({
+    name: 'StepDefinitionPlugin',
+    records: {
+        sys_flow_step_definition: {
+            relationships: {
+                sys_flow_step_definition_input: {
+                    via: 'model',
+                    descendant: true,
+                    relationships: {
+                        sys_choice: {
+                            via: {
+                                name: 'name',
+                                element: 'element',
+                            },
+                            descendant: true,
+                        },
+                    },
+                },
+                sys_flow_step_definition_output: {
+                    via: 'model',
+                    descendant: true,
+                },
+            },
+            toShape(record, { descendants }) {
+                const inputs = buildVariableShapes(descendants.query('sys_flow_step_definition_input'), descendants)
+                const outputs = buildVariableShapes(descendants.query('sys_flow_step_definition_output'), descendants)
+                return {
+                    success: true,
+                    value: new CallExpressionShape({
+                        source: record,
+                        callee: 'ActionStepDefinition',
+                        args: [
+                            record.transform(({ $ }) => {
+                                return {
+                                    $id: $.val(NowIdShape.from(record)),
+                                    name: $.def(''),
+                                    shortDescription: $.from('short_description').def(''),
+                                    category: $.def(''),
+                                    inputs: $.val(inputs),
+                                    outputs: $.val(outputs),
+                                    allowExtendedInputs: $.toBoolean().def(true),
+                                    allowExtendedOutputs: $.toBoolean().def(true),
+                                }
+                            }),
+                        ],
+                    }),
+                }
+            },
+            toFile(record, { config, database }) {
+                return generateXML(record, { config, database })
+            },
+        },
+        sys_flow_step_definition_input: {
+            coalesce: ['model', 'element'],
+        },
+        sys_flow_step_definition_output: {
+            coalesce: ['model', 'element'],
+        },
+    },
+})