@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

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

@@ -0,0 +1,296 @@
+import {
+    CallExpressionShape,
+    type Source,
+    ObjectShape,
+    Record,
+    StringShape,
+    TemplateExpressionShape,
+    Shape,
+} from '@servicenow/sdk-build-core'
+import { NowIdShape } from '../../now-id-plugin'
+import type { ApprovalRulesType, ApprovalDueDateType } from '@servicenow/sdk-core/runtime/flow'
+import { approvalRulesJsonToString, approvalRulesStringToJson } from './approval-rules-processor'
+import { APPROVAL_RULES_API_NAME, APPROVAL_DUE_DATE_API_NAME } from './flow-constants'
+
+/**
+ * Abstract base class for all flow definition instances.
+ * Extends CallExpressionShape to provide common functionality for flow constructs.
+ */
+export abstract class FDInstanceShape extends CallExpressionShape {
+    constructor(source: Source, callee: string, args: unknown[]) {
+        super({ source, callee, args })
+    }
+
+    getInstanceType(): string {
+        return this.getCallee()
+    }
+
+    abstract getSysId(): NowIdShape | undefined
+    abstract getAnnotation(): StringShape | undefined
+}
+
+/**
+ * Shape class for Action and Subflow instances.
+ * Handles the pattern: Action(definition, config, props)
+ *
+ * @example
+ * Action(createIncident, { $id: Now.ID['incident_0'], annotation: 'Create incident' }, { shortDescription: 'Issue' })
+ * Subflow(mySubflow, { $id: Now.ID['subflow_0'], annotation: 'Process data' }, { input: 'value' })
+ */
+export class ActionSubflowInstanceShape extends FDInstanceShape {
+    constructor({
+        source,
+        instanceDefinition,
+        instanceProps,
+        instanceType,
+        configObject,
+    }: {
+        source: Source
+        instanceDefinition: Record | StringShape | undefined
+        instanceProps: ObjectShape | undefined
+        instanceType: string
+        configObject: ObjectShape
+    }) {
+        const configObj = configObject
+        super(source, instanceType, [instanceDefinition, configObj, instanceProps])
+    }
+
+    getInstanceDefinition(): Record | StringShape | undefined {
+        const arg0 = this.getArgument(0)
+        if (arg0.isString()) {
+            return arg0.as(StringShape)
+        }
+        return arg0.as(Record)
+    }
+
+    getInstanceProps(): ObjectShape | undefined {
+        return this.getArgument(2).as(ObjectShape)
+    }
+
+    getSysId(): NowIdShape | undefined {
+        const configObj = this.getArgument(1).as(ObjectShape)
+        return configObj.get('$id')?.as(NowIdShape)
+    }
+
+    getAnnotation(): StringShape | undefined {
+        const configObj = this.getArgument(1).as(ObjectShape)
+        const annotation = configObj.get('annotation')
+        return annotation?.isString() ? annotation.asString() : undefined
+    }
+
+    getInstanceUUID(): StringShape | undefined {
+        const configObj = this.getArgument(1).as(ObjectShape)
+        const uuid = configObj.get('uuid')
+        return uuid?.isString() ? uuid.asString() : undefined
+    }
+}
+
+/**
+ * Represents an inline script for ServiceNow Flow Designer actions and subflows.
+ *
+ * Inline scripts allow users to write JavaScript code directly in Flow action/subflow inputs
+ * without creating separate Script Includes or Business Rules. This shape wraps the script
+ * content and provides serialization to Flow Designer's JSON format.
+ *
+ * **Supported Formats:**
+ * - Template literals without substitutions: \`code\`
+ * - External files via Now.include: Now.include('./script.js')
+ *
+ * **Usage Example:**
+ * ```typescript
+ * Action(myAction, Now.ID['action_id'], {
+ *     workNotes: `
+ *         var number = fd_data.trigger.current.number;
+ *         return 'Incident ' + number + ' created';
+ *     `
+ * })
+ * ```
+ *
+ * **Architecture:**
+ * This shape is NOT created via a global plugin. Instead, detection happens contextually
+ * in FlowInstancePlugin.checkAndResolveInlineScripts() to ensure only template literals
+ * used as Action/Subflow inputs are converted to inline scripts. This prevents incorrectly
+ * converting template literals used elsewhere (logging, formatting, etc.).
+ *
+ * @extends TemplateExpressionShape
+ */
+export class InlineScriptShape extends TemplateExpressionShape {
+    private readonly scriptContent: string
+
+    /**
+     * Creates an InlineScriptShape instance.
+     *
+     * @param source - The original TemplateExpressionShape from the AST
+     * @param scriptContent - The JavaScript code to execute (without backticks)
+     */
+    constructor({ source, scriptContent }: { source: TemplateExpressionShape; scriptContent: string }) {
+        super({ source, literalText: scriptContent })
+        this.scriptContent = scriptContent
+    }
+
+    /**
+     * Returns the raw script content without template literal backticks.
+     *
+     * @returns The JavaScript code as a string
+     */
+    getScriptContent(): string {
+        return this.scriptContent
+    }
+
+    /**
+     * Serializes this inline script to ServiceNow Flow Designer JSON format.
+     *
+     * The output structure includes:
+     * - `scriptActive: true` - Indicates this field contains a script
+     * - `script` object - Contains the actual script content keyed by field name
+     * - Empty `value` and `displayValue` - Required by Flow Designer schema
+     *
+     * @param fieldName - The name of the action/subflow input field
+     * @returns Flow Designer JSON structure for inline scripts
+     *
+     * @example
+     * ```typescript
+     * inlineScript.toFlowDesignerJson('workNotes')
+     * // Returns:
+     * // {
+     * //   name: 'workNotes',
+     * //   scriptActive: true,
+     * //   script: { workNotes: { scriptActive: true, script: '...' } },
+     * //   value: '', displayValue: '', children: []
+     * // }
+     * ```
+     */
+    toFlowDesignerJson(fieldName: string) {
+        return {
+            name: fieldName,
+            value: '',
+            displayValue: '',
+            children: [],
+            scriptActive: true,
+            script: {
+                [fieldName]: {
+                    scriptActive: true,
+                    script: this.scriptContent,
+                },
+            },
+        }
+    }
+}
+
+/**
+ * Shape representing ApprovalRules
+ * Used with ApprovalRules() helper - Stores approval rules for Flow Designer
+ */
+export class ApprovalRulesShape extends ObjectShape {
+    constructor({ source, value }: { source: Source; value: globalThis.Record<string, unknown> }) {
+        super({ source, properties: value })
+    }
+
+    getApprovalRules(): ApprovalRulesType {
+        return super.getValue()
+    }
+
+    /**
+     * Returns code representation as ApprovalRules() helper call.
+     * @example 'wfa.approvalRules({"conditionType":"OR","ruleSets":[{"action":"Approves","conditionType":"AND","rules":[[{"rule_type":"Any","users":["_params.trigger.current.assigned_to"],"groups":[],"manual":false}]]},{"action":"Rejects","conditionType":"AND","rules":[[{"rule_type":"Any","users":[],"groups":[],"manual":true}]]}]})'
+     */
+    override getCode(): string {
+        return `${APPROVAL_RULES_API_NAME}(${super.getCode()})`
+    }
+    /**
+     * Returns a StringShape of the Approval Rules JSON
+     */
+    override toString(): StringShape {
+        const approvalRulesString = approvalRulesJsonToString(this.getApprovalRules())
+        return Shape.from(this.getSource(), approvalRulesString).toString()
+    }
+
+    static override from(source: Source, text: StringShape): ApprovalRulesShape {
+        return new ApprovalRulesShape({
+            source,
+            value: approvalRulesStringToJson(text.getValue()),
+        })
+    }
+}
+
+/**
+ * Shape representing ApprovalDueDate
+ * Used with ApprovalDueDate() helper - Stores approval due date configuration for Flow Designer
+ */
+export class ApprovalDueDateShape extends ObjectShape {
+    constructor({ source, value }: { source: Source; value: globalThis.Record<string, unknown> }) {
+        super({ source, properties: value })
+    }
+
+    getApprovalDueDate(): ApprovalDueDateType {
+        return super.getValue() as ApprovalDueDateType
+    }
+
+    /**
+     * Returns code representation as ApprovalDueDate() helper call.
+     * @example 'wfa.approvalDueDate({"action":"none","date_type":"actual","date":"{}","duration":1,"duration_type":"days","schedule":""})'
+     */
+    override getCode(): string {
+        return `${APPROVAL_DUE_DATE_API_NAME}(${super.getCode()})`
+    }
+
+    /**
+     * Returns a StringShape of the Approval Due Date string
+     */
+    override toString(): StringShape {
+        const approvalDueDateValue = this.getApprovalDueDate()
+
+        const formattedApprovalDueDate = {
+            action: 'none',
+            date_type: 'actual',
+            date: '{}',
+            duration: 1,
+            duration_type: 'days',
+            schedule: '',
+        }
+
+        //Convert the Due Date to the format expected by Flow Designer and populate with default values
+        if (approvalDueDateValue) {
+            formattedApprovalDueDate.action = approvalDueDateValue.action || 'none'
+            formattedApprovalDueDate.date_type = approvalDueDateValue.dateType || 'actual'
+            formattedApprovalDueDate.date = approvalDueDateValue.date || '{}'
+            formattedApprovalDueDate.duration = approvalDueDateValue.duration || 1
+            formattedApprovalDueDate.duration_type = approvalDueDateValue.durationType || 'days'
+
+            formattedApprovalDueDate.schedule = approvalDueDateValue.daysSchedule || ''
+        }
+
+        return Shape.from(this.getSource(), JSON.stringify(formattedApprovalDueDate)).toString()
+    }
+
+    static override from(source: Source, text: StringShape): ApprovalDueDateShape {
+        const approvalDueDateValue: ApprovalDueDateType = {
+            action: 'none',
+            dateType: 'actual',
+            date: '{}',
+            duration: 1,
+            durationType: 'days',
+            daysSchedule: '',
+        }
+        try {
+            const parsedValue = JSON.parse(text.getValue())
+
+            //Convert the Due Date to the format expected by Fluent and populate with default values
+            if (parsedValue) {
+                approvalDueDateValue.action = parsedValue.action || 'none'
+                approvalDueDateValue.dateType = parsedValue.date_type || 'actual'
+                approvalDueDateValue.date = parsedValue.date || '{}'
+                approvalDueDateValue.duration = Number(parsedValue.duration) || 1
+                approvalDueDateValue.durationType = parsedValue.duration_type || 'days'
+                approvalDueDateValue.daysSchedule = parsedValue.schedule || ''
+            }
+        } catch {
+            // Failed to parse - will use default values
+        }
+
+        return new ApprovalDueDateShape({
+            source,
+            value: approvalDueDateValue,
+        })
+    }
+}

package/src/flow/utils/flow-to-xml.ts

@@ -0,0 +1,318 @@
+import {
+    recordXml,
+    type Record,
+    type Action,
+    unloadBuilder,
+    type Database,
+    type Relationships,
+} from '@servicenow/sdk-build-core'
+import type { Element } from 'xml-js'
+import { FlowDefinitionPlugin } from '../plugins/flow-definition-plugin'
+
+/**
+ * Tables to exclude from delete_multiple generation.
+ * These tables either don't need cleanup or have special handling.
+ */
+const EXCLUDED_TABLES = new Set([
+    'sys_flow_record_trigger',
+    'sys_flow_timer_trigger',
+    'sys_hub_flow_snapshot',
+    'sys_choice',
+    'sys_documentation',
+    'sys_complex_object',
+    'sys_element_mapping',
+])
+
+/**
+ * Tables that need cascading delete_multiple entries per instance.
+ * For example, sys_hub_alias_mapping needs a delete_multiple for each action/subflow instance.
+ */
+const CASCADING_DELETE_CONFIG: globalThis.Record<string, { table: string; field: string }[]> = {
+    sys_hub_action_instance_v2: [{ table: 'sys_hub_alias_mapping', field: 'source_id' }],
+    sys_hub_sub_flow_instance_v2: [{ table: 'sys_hub_alias_mapping', field: 'source_id' }],
+}
+
+type DeleteMultipleConfig = {
+    parentField: string
+    parentType: 'flow' | 'descendant'
+    parentTable?: string
+}
+
+export function generateXML(
+    record: Record,
+    { config, database }: { config: { scope: string; scopeId: string }; database: Database }
+) {
+    const relationships = FlowDefinitionPlugin.getRelationships()[record.getTable()] ?? {}
+    const updateName = `${record.getTable()}_${record.getId().getValue()}`
+    const recordBuilder = unloadBuilder(config)
+    const table = record.getTable()
+    const flowId = record.getId().getValue()
+    const builder = recordBuilder.record(record, updateName)
+    record
+        .entries()
+        .sort(([a], [b]) => a.localeCompare(b)) // Sort keys to make outputs more deterministic
+        .forEach(([prop, shape]) => builder.field(prop, shape, {}))
+
+    // Get descendants using plugin's getDescendants method and group by table
+    const descendants = FlowDefinitionPlugin.getDescendants(record, database)
+    const recordMap = descendants.reduce(
+        (acc, rec) => {
+            const t = rec.getTable()
+            if (!acc[t]) {
+                acc[t] = []
+            }
+            acc[t].push(rec)
+            return acc
+        },
+        {} as globalThis.Record<string, Record[]>
+    )
+
+    // Build delete_multiple config dynamically from relationships
+    const deleteMultipleConfig = buildDeleteMultipleConfig(relationships)
+
+    // Generate delete_multiple and INSERT_OR_UPDATE entries for each descendant table
+    for (const [tableName, records] of Object.entries(recordMap)) {
+        // Skip sys_choice as it has special handling
+        if (tableName === 'sys_choice') {
+            generateNestedXML(records, recordBuilder.recordUpdateElements, config, true)
+            continue
+        }
+
+        // Generate delete_multiple entry for this table
+        generateDeleteMultiple(
+            tableName,
+            flowId,
+            records,
+            recordMap,
+            recordBuilder.recordUpdateElements,
+            deleteMultipleConfig
+        )
+
+        // Generate INSERT_OR_UPDATE entries for the records
+        generateNestedXML(records, recordBuilder.recordUpdateElements, config, false)
+
+        // Generate cascading delete_multiple entries (e.g., alias_mapping per action instance)
+        generateCascadingDeleteMultiple(tableName, records, recordBuilder.recordUpdateElements)
+    }
+
+    return {
+        success: true,
+        value: {
+            source: record,
+            name: `${table}_${flowId}.xml`,
+            category: record.getInstallCategory(),
+            content: recordBuilder.end(),
+        },
+    }
+}
+
+function generateNestedXML(
+    records: Record[],
+    rootElements: Element[],
+    config: { scope: string; scopeId: string },
+    choiceRecords: boolean = false
+) {
+    if (choiceRecords) {
+        // group records by field/element and table/name
+        const groupedRecords = records.reduce(
+            (acc, record) => {
+                const field = record.get('element')?.asString()?.getValue()
+                const name = record.get('name')?.asString()?.getValue()
+
+                if (!field || !name) {
+                    return acc
+                }
+
+                const key = `${name}:${field}`
+
+                if (!acc[key]) {
+                    acc[key] = []
+                }
+                acc[key].push(record)
+
+                return acc
+            },
+            {} as globalThis.Record<string, Record[]>
+        )
+
+        for (const [key, records] of Object.entries(groupedRecords)) {
+            const [name, field] = key.split(':')
+
+            const choiceElements: Element[] = []
+            const choiceElement: Element = {
+                type: 'element',
+                name: 'sys_choice',
+                attributes: { field, table: name },
+                elements: choiceElements,
+            }
+            rootElements.push(choiceElement)
+
+            generateNestedXML(records, choiceElements, config)
+        }
+        return
+    }
+
+    for (const record of records) {
+        const table = record.getTable()
+        const guid = record.getId().getValue()
+        generateRecordXML(record, rootElements, table, guid, record.getAction(), config)
+    }
+}
+
+function generateRecordXML(
+    record: Record,
+    rootElements: Element[],
+    table: string,
+    guid: string,
+    action: Action = 'INSERT_OR_UPDATE',
+    config: { scope: string; scopeId: string }
+) {
+    const builder = recordXml(rootElements, table, guid, { attr: { action } })
+    builder.addSysScope(config.scope, config.scopeId)
+    record
+        .entries()
+        .sort(([a], [b]) => a.localeCompare(b)) // Sort keys to make outputs more deterministic
+        .forEach(([prop, shape]) => builder.field(prop, shape, {}))
+}
+
+/**
+ * Build delete_multiple configuration dynamically from plugin relationships.
+ * Traverses the relationship tree and extracts parent fields for each descendant table.
+ */
+function buildDeleteMultipleConfig(
+    relationships: Relationships,
+    parentTable?: string
+): globalThis.Record<string, DeleteMultipleConfig> {
+    const config: globalThis.Record<string, DeleteMultipleConfig> = {}
+
+    for (const [tableName, relationship] of Object.entries(relationships)) {
+        // Skip excluded tables
+        if (EXCLUDED_TABLES.has(tableName)) {
+            continue
+        }
+
+        // Only process descendant relationships with string 'via' field
+        if (!relationship.descendant || typeof relationship.via !== 'string') {
+            continue
+        }
+
+        // Skip inverse relationships (parent references child, not child references parent)
+        if (relationship.inverse) {
+            continue
+        }
+
+        // Add config for this table
+        if (parentTable) {
+            // Nested relationship - references another descendant table
+            config[tableName] = {
+                parentField: relationship.via,
+                parentType: 'descendant',
+                parentTable,
+            }
+        } else {
+            // Direct relationship - references the flow
+            config[tableName] = {
+                parentField: relationship.via,
+                parentType: 'flow',
+            }
+        }
+
+        // Recursively process nested relationships
+        if (relationship.relationships) {
+            const nestedConfig = buildDeleteMultipleConfig(relationship.relationships, tableName)
+            Object.assign(config, nestedConfig)
+        }
+    }
+
+    return config
+}
+
+/**
+ * Generate a delete_multiple XML element for a descendant table.
+ * The query follows the pattern: parentField=parentId^sys_idNOT IN<comma_separated_ids>
+ */
+function generateDeleteMultiple(
+    tableName: string,
+    flowId: string,
+    records: Record[],
+    recordMap: globalThis.Record<string, Record[]>,
+    rootElements: Element[],
+    deleteMultipleConfig: globalThis.Record<string, DeleteMultipleConfig>
+) {
+    const config = deleteMultipleConfig[tableName]
+    if (!config) {
+        return
+    }
+
+    let query: string
+
+    if (config.parentType === 'flow') {
+        // Direct reference to flow
+        const recordIds = records.map((r) => r.getId().getValue()).join(',')
+        if (recordIds) {
+            query = `${config.parentField}=${flowId}^sys_idNOT IN${recordIds}`
+        } else {
+            query = `${config.parentField}=${flowId}`
+        }
+    } else if (config.parentType === 'descendant' && config.parentTable) {
+        // Reference to another descendant table
+        const parentRecords = recordMap[config.parentTable] || []
+        if (parentRecords.length === 0) {
+            return
+        }
+
+        // Generate delete_multiple for each parent record
+        for (const parentRecord of parentRecords) {
+            const parentId = parentRecord.getId().getValue()
+            const childRecords = records.filter((r) => {
+                const refValue = r.get(config.parentField)?.getValue()
+                return refValue === parentId
+            })
+            const childIds = childRecords.map((r) => r.getId().getValue()).join(',')
+
+            const childQuery = childIds
+                ? `${config.parentField}=${parentId}^sys_idNOT IN${childIds}`
+                : `${config.parentField}=${parentId}`
+
+            rootElements.push({
+                type: 'element',
+                name: tableName,
+                attributes: { action: 'delete_multiple', query: childQuery },
+            })
+        }
+        return
+    } else {
+        return
+    }
+
+    rootElements.push({
+        type: 'element',
+        name: tableName,
+        attributes: { action: 'delete_multiple', query },
+    })
+}
+
+/**
+ * Generate cascading delete_multiple entries for tables that need per-instance cleanup.
+ * For example, sys_hub_alias_mapping needs a delete_multiple for each action/subflow instance.
+ */
+function generateCascadingDeleteMultiple(tableName: string, records: Record[], rootElements: Element[]) {
+    const cascadeEntries = CASCADING_DELETE_CONFIG[tableName]
+    if (!cascadeEntries) {
+        return
+    }
+
+    for (const { table, field } of cascadeEntries) {
+        // Generate a delete_multiple for each instance record
+        for (const record of records) {
+            const instanceId = record.getId().getValue()
+            const query = `${field}=${instanceId}`
+
+            rootElements.push({
+                type: 'element',
+                name: table,
+                attributes: { action: 'delete_multiple', query },
+            })
+        }
+    }
+}