@sonisoft/now-sdk-ext-core 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -57,6 +57,8 @@ export * from './sn/codesearch/CodeSearch.js';
 export * from './sn/codesearch/CodeSearchModels.js';
 export * from './sn/discovery/DiscoveryModels.js';
 export * from './sn/discovery/InstanceDiscovery.js';
+export * from './sn/flow/FlowManager.js';
+export * from './sn/flow/FlowModels.js';
 export * from './sn/health/HealthModels.js';
 export * from './sn/health/InstanceHealth.js';
 export * from './sn/knowledge/KnowledgeManager.js';

package/dist/index.js

@@ -57,6 +57,8 @@ export * from './sn/codesearch/CodeSearch.js';
 export * from './sn/codesearch/CodeSearchModels.js';
 export * from './sn/discovery/DiscoveryModels.js';
 export * from './sn/discovery/InstanceDiscovery.js';
+export * from './sn/flow/FlowManager.js';
+export * from './sn/flow/FlowModels.js';
 export * from './sn/health/HealthModels.js';
 export * from './sn/health/InstanceHealth.js';
 export * from './sn/knowledge/KnowledgeManager.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wCAAwC,CAAC;AACvD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,qCAAqC,CAAC;AACpD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wCAAwC,CAAC;AACvD,cAAc,kCAAkC,CAAC;AACjD,cAAc,uCAAuC,CAAC;AACtD,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,oCAAoC,CAAC;AACnD,cAAc,0CAA0C,CAAC;AACzD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,wBAAwB,CAAC;AACvC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,qCAAqC,CAAC;AACpD,cAAc,uCAAuC,CAAC;AACtD,cAAc,yCAAyC,CAAC;AACxD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,qBAAqB,CAAC;AACpC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,sCAAsC,CAAC;AACrD,cAAc,qCAAqC,CAAC;AACpD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,gCAAgC,CAAC;AAC/C,cAAc,oCAAoC,CAAC;AACnD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,mCAAmC,CAAC;AAClD,cAAc,qCAAqC,CAAC;AACpD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,mCAAmC,CAAC;AAClD,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,0BAA0B,CAAC;AACzC,cAAc,yBAAyB,CAAC"}

package/dist/sn/flow/FlowManager.d.ts

@@ -0,0 +1,69 @@
+import { ServiceNowInstance } from "../ServiceNowInstance.js";
+import { BackgroundScriptExecutionResult } from "../BackgroundScriptExecutor.js";
+import { ExecuteFlowOptions, ExecuteFlowByNameOptions, ExecuteSubflowOptions, ExecuteActionOptions, FlowExecutionResult, FlowScriptResultEnvelope, FlowContextStatusResult, FlowOutputsResult, FlowErrorResult, FlowCancelResult, FlowSendMessageResult } from './FlowModels.js';
+/**
+ * Provides operations for executing ServiceNow Flow Designer flows,
+ * subflows, and actions remotely via BackgroundScriptExecutor.
+ *
+ * Uses the sn_fd.FlowAPI.getRunner() (ScriptableFlowRunner) API
+ * on the server side to execute and capture results.
+ */
+export declare class FlowManager {
+    private _logger;
+    private _bgExecutor;
+    private _instance;
+    private _defaultScope;
+    /**
+     * @param instance ServiceNow instance connection
+     * @param scope Default scope for script execution (default: "global")
+     */
+    constructor(instance: ServiceNowInstance, scope?: string);
+    /** Execute any flow object (flow, subflow, or action). */
+    execute(options: ExecuteFlowOptions): Promise<FlowExecutionResult>;
+    /** Execute a flow by scoped name. */
+    executeFlow(options: ExecuteFlowByNameOptions): Promise<FlowExecutionResult>;
+    /** Execute a subflow by scoped name. */
+    executeSubflow(options: ExecuteSubflowOptions): Promise<FlowExecutionResult>;
+    /** Execute an action by scoped name. */
+    executeAction(options: ExecuteActionOptions): Promise<FlowExecutionResult>;
+    /** Query the status of a flow context by its sys_id. */
+    getFlowContextStatus(contextId: string): Promise<FlowContextStatusResult>;
+    /** Retrieve outputs from a completed flow/subflow/action by context ID. */
+    getFlowOutputs(contextId: string): Promise<FlowOutputsResult>;
+    /** Retrieve error messages from a flow/subflow/action by context ID. */
+    getFlowError(contextId: string): Promise<FlowErrorResult>;
+    /** Cancel a running or paused flow/subflow/action. */
+    cancelFlow(contextId: string, reason?: string): Promise<FlowCancelResult>;
+    /** Send a message to a paused flow to resume it (for Wait for Message actions). */
+    sendFlowMessage(contextId: string, message: string, payload?: string): Promise<FlowSendMessageResult>;
+    /** Build the ServiceNow server-side script string. */
+    _buildFlowScript(options: ExecuteFlowOptions): string;
+    /** Serialize inputs for embedding in the generated script. */
+    _serializeInputs(inputs: Record<string, unknown>): string;
+    /**
+     * Decode HTML entities and strip HTML tags from a string.
+     * ServiceNow's background script output encodes quotes as &quot;
+     * and appends <BR/> tags that must be removed before JSON parsing.
+     */
+    _decodeHtmlEntities(str: string): string;
+    /** Try to parse a line containing the result marker into a FlowScriptResultEnvelope. */
+    private _tryParseEnvelopeFromLine;
+    /** Extract the JSON envelope from script output lines. */
+    _extractResultEnvelope(bgResult: BackgroundScriptExecutionResult): FlowScriptResultEnvelope | null;
+    /** Parse BackgroundScriptExecutionResult into FlowExecutionResult. */
+    _parseFlowResult(bgResult: BackgroundScriptExecutionResult, options: ExecuteFlowOptions): FlowExecutionResult;
+    /** Validate that a context ID is non-empty. */
+    private _validateContextId;
+    /** Escape a string for embedding in a generated SN script single-quoted string. */
+    private _escapeForScript;
+    /** Build script to query sys_flow_context status. */
+    _buildContextStatusScript(contextId: string): string;
+    /** Build script to retrieve flow outputs via FlowAPI.getOutputs(). */
+    _buildGetOutputsScript(contextId: string): string;
+    /** Build script to retrieve flow error via FlowAPI.getErrorMessage(). */
+    _buildGetErrorScript(contextId: string): string;
+    /** Build script to cancel a flow via FlowAPI.cancel(). */
+    _buildCancelScript(contextId: string, reason: string): string;
+    /** Build script to send a message to a paused flow via FlowAPI.sendMessage(). */
+    _buildSendMessageScript(contextId: string, message: string, payload: string): string;
+}

package/dist/sn/flow/FlowManager.js

@@ -0,0 +1,571 @@
+import { BackgroundScriptExecutor } from "../BackgroundScriptExecutor.js";
+import { Logger } from "../../util/Logger.js";
+const RESULT_MARKER = '___FLOW_EXEC_RESULT___';
+const VALID_TYPES = ['flow', 'subflow', 'action'];
+/**
+ * Provides operations for executing ServiceNow Flow Designer flows,
+ * subflows, and actions remotely via BackgroundScriptExecutor.
+ *
+ * Uses the sn_fd.FlowAPI.getRunner() (ScriptableFlowRunner) API
+ * on the server side to execute and capture results.
+ */
+export class FlowManager {
+    _logger = new Logger("FlowManager");
+    _bgExecutor;
+    _instance;
+    _defaultScope;
+    /**
+     * @param instance ServiceNow instance connection
+     * @param scope Default scope for script execution (default: "global")
+     */
+    constructor(instance, scope = 'global') {
+        this._instance = instance;
+        this._defaultScope = scope;
+        this._bgExecutor = new BackgroundScriptExecutor(instance, scope);
+    }
+    // ================================================================
+    // Public API
+    // ================================================================
+    /** Execute any flow object (flow, subflow, or action). */
+    async execute(options) {
+        if (!options.scopedName || options.scopedName.trim().length === 0) {
+            throw new Error('Flow scoped name is required (e.g. "global.my_flow")');
+        }
+        if (!options.type) {
+            throw new Error('Flow object type is required ("flow", "subflow", or "action")');
+        }
+        if (!VALID_TYPES.includes(options.type)) {
+            throw new Error(`Invalid flow object type "${options.type}". Must be one of: ${VALID_TYPES.join(', ')}`);
+        }
+        this._logger.info(`Executing ${options.type}: ${options.scopedName}`);
+        const script = this._buildFlowScript(options);
+        const scope = options.scope || this._defaultScope;
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, scope, this._instance);
+            const flowResult = this._parseFlowResult(bgResult, options);
+            this._logger.info(`${options.type} execution complete: ${flowResult.success ? 'SUCCESS' : 'FAILED'}`);
+            return flowResult;
+        }
+        catch (error) {
+            const err = error;
+            this._logger.error(`Error executing ${options.type} "${options.scopedName}": ${err.message}`);
+            return {
+                success: false,
+                flowObjectName: options.scopedName,
+                flowObjectType: options.type,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    /** Execute a flow by scoped name. */
+    async executeFlow(options) {
+        return this.execute({ ...options, type: 'flow' });
+    }
+    /** Execute a subflow by scoped name. */
+    async executeSubflow(options) {
+        return this.execute({ ...options, type: 'subflow' });
+    }
+    /** Execute an action by scoped name. */
+    async executeAction(options) {
+        return this.execute({ ...options, type: 'action' });
+    }
+    // ================================================================
+    // Flow Context Lifecycle API
+    // ================================================================
+    /** Query the status of a flow context by its sys_id. */
+    async getFlowContextStatus(contextId) {
+        this._validateContextId(contextId);
+        this._logger.info(`Getting context status: ${contextId}`);
+        const script = this._buildContextStatusScript(contextId);
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, this._defaultScope, this._instance);
+            const envelope = this._extractResultEnvelope(bgResult);
+            if (envelope) {
+                return {
+                    success: envelope.success,
+                    contextId,
+                    found: envelope.found ?? false,
+                    state: envelope.state ?? undefined,
+                    name: envelope.name ?? undefined,
+                    started: envelope.started ?? undefined,
+                    ended: envelope.ended ?? undefined,
+                    errorMessage: envelope.errorMessage ?? undefined,
+                    rawScriptResult: bgResult
+                };
+            }
+            return {
+                success: false, contextId, found: false,
+                errorMessage: 'Could not parse context status result from script output.',
+                rawScriptResult: bgResult
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false, contextId, found: false,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    /** Retrieve outputs from a completed flow/subflow/action by context ID. */
+    async getFlowOutputs(contextId) {
+        this._validateContextId(contextId);
+        this._logger.info(`Getting outputs for context: ${contextId}`);
+        const script = this._buildGetOutputsScript(contextId);
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, this._defaultScope, this._instance);
+            const envelope = this._extractResultEnvelope(bgResult);
+            if (envelope) {
+                return {
+                    success: envelope.success,
+                    contextId,
+                    outputs: envelope.outputs ?? undefined,
+                    errorMessage: envelope.errorMessage ?? undefined,
+                    rawScriptResult: bgResult
+                };
+            }
+            return {
+                success: false, contextId,
+                errorMessage: 'Could not parse outputs result from script output.',
+                rawScriptResult: bgResult
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false, contextId,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    /** Retrieve error messages from a flow/subflow/action by context ID. */
+    async getFlowError(contextId) {
+        this._validateContextId(contextId);
+        this._logger.info(`Getting error for context: ${contextId}`);
+        const script = this._buildGetErrorScript(contextId);
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, this._defaultScope, this._instance);
+            const envelope = this._extractResultEnvelope(bgResult);
+            if (envelope) {
+                return {
+                    success: envelope.success,
+                    contextId,
+                    flowErrorMessage: envelope.flowErrorMessage ?? undefined,
+                    errorMessage: envelope.errorMessage ?? undefined,
+                    rawScriptResult: bgResult
+                };
+            }
+            return {
+                success: false, contextId,
+                errorMessage: 'Could not parse error result from script output.',
+                rawScriptResult: bgResult
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false, contextId,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    /** Cancel a running or paused flow/subflow/action. */
+    async cancelFlow(contextId, reason) {
+        this._validateContextId(contextId);
+        this._logger.info(`Cancelling context: ${contextId}`);
+        const script = this._buildCancelScript(contextId, reason || 'Cancelled via FlowManager');
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, this._defaultScope, this._instance);
+            const envelope = this._extractResultEnvelope(bgResult);
+            if (envelope) {
+                return {
+                    success: envelope.success,
+                    contextId,
+                    errorMessage: envelope.errorMessage ?? undefined,
+                    rawScriptResult: bgResult
+                };
+            }
+            return {
+                success: false, contextId,
+                errorMessage: 'Could not parse cancel result from script output.',
+                rawScriptResult: bgResult
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false, contextId,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    /** Send a message to a paused flow to resume it (for Wait for Message actions). */
+    async sendFlowMessage(contextId, message, payload) {
+        this._validateContextId(contextId);
+        if (!message || message.trim().length === 0) {
+            throw new Error('Message is required');
+        }
+        this._logger.info(`Sending message to context: ${contextId}`);
+        const script = this._buildSendMessageScript(contextId, message, payload || '');
+        try {
+            const bgResult = await this._bgExecutor.executeScript(script, this._defaultScope, this._instance);
+            const envelope = this._extractResultEnvelope(bgResult);
+            if (envelope) {
+                return {
+                    success: envelope.success,
+                    contextId,
+                    errorMessage: envelope.errorMessage ?? undefined,
+                    rawScriptResult: bgResult
+                };
+            }
+            return {
+                success: false, contextId,
+                errorMessage: 'Could not parse send message result from script output.',
+                rawScriptResult: bgResult
+            };
+        }
+        catch (error) {
+            const err = error;
+            return {
+                success: false, contextId,
+                errorMessage: `Script execution error: ${err.message}`,
+                rawScriptResult: null
+            };
+        }
+    }
+    // ================================================================
+    // Internal Methods
+    // ================================================================
+    /** Build the ServiceNow server-side script string. */
+    _buildFlowScript(options) {
+        const mode = options.mode || 'foreground';
+        const modeMethod = mode === 'background' ? 'inBackground' : 'inForeground';
+        const inputsJson = options.inputs ? this._serializeInputs(options.inputs) : '{}';
+        const scopedName = options.scopedName.replace(/'/g, "\\'");
+        const type = options.type;
+        let optionalChain = '';
+        if (options.timeout !== undefined && options.timeout !== null) {
+            optionalChain += `\n            .timeout(${options.timeout})`;
+        }
+        if (options.quick === true) {
+            optionalChain += `\n            .quick()`;
+        }
+        const hasInputs = options.inputs && Object.keys(options.inputs).length > 0;
+        const inputsChain = hasInputs ? `\n            .withInputs(inputs)` : '';
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        var inputs = ${inputsJson};
+
+        var result = sn_fd.FlowAPI.getRunner()
+            .${type}('${scopedName}')
+            .${modeMethod}()${optionalChain}${inputsChain}
+            .run();
+
+        var envelope = {
+            __flowResult: true,
+            success: true,
+            flowObjectName: '' + result.getFlowObjectName(),
+            flowObjectType: '' + result.getFlowObjectType(),
+            contextId: result.getContextId() ? '' + result.getContextId() : null,
+            executionDate: result.getDate() ? '' + result.getDate() : null,
+            domainId: result.getDomainId() ? '' + result.getDomainId() : null,
+            outputs: null,
+            debugOutput: '' + result.debug(),
+            errorMessage: null
+        };
+
+        try {
+            var rawOutputs = result.getOutputs();
+            if (rawOutputs) {
+                var outputObj = {};
+                for (var key in rawOutputs) {
+                    if (rawOutputs.hasOwnProperty(key)) {
+                        outputObj[key] = '' + rawOutputs[key];
+                    }
+                }
+                envelope.outputs = outputObj;
+            }
+        } catch (outErr) {
+            envelope.outputs = null;
+        }
+
+        gs.info(__RESULT_MARKER + JSON.stringify(envelope));
+    } catch (ex) {
+        var errorEnvelope = {
+            __flowResult: true,
+            success: false,
+            flowObjectName: '${scopedName}',
+            flowObjectType: '${type}',
+            contextId: null,
+            executionDate: null,
+            domainId: null,
+            outputs: null,
+            debugOutput: '',
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        };
+        gs.info(__RESULT_MARKER + JSON.stringify(errorEnvelope));
+    }
+})();`;
+    }
+    /** Serialize inputs for embedding in the generated script. */
+    _serializeInputs(inputs) {
+        const cleanInputs = {};
+        for (const [key, value] of Object.entries(inputs)) {
+            if (value !== undefined) {
+                cleanInputs[key] = value;
+            }
+        }
+        return JSON.stringify(cleanInputs);
+    }
+    /**
+     * Decode HTML entities and strip HTML tags from a string.
+     * ServiceNow's background script output encodes quotes as "
+     * and appends <BR/> tags that must be removed before JSON parsing.
+     */
+    _decodeHtmlEntities(str) {
+        return str
+            .replace(/<BR\s*\/?>/gi, '')
+            .replace(/&quot;/g, '"')
+            .replace(/&amp;/g, '&')
+            .replace(/&lt;/g, '<')
+            .replace(/&gt;/g, '>')
+            .replace(/&#39;/g, "'")
+            .replace(/&apos;/g, "'")
+            .trim();
+    }
+    /** Try to parse a line containing the result marker into a FlowScriptResultEnvelope. */
+    _tryParseEnvelopeFromLine(line) {
+        if (!line || !line.includes(RESULT_MARKER)) {
+            return null;
+        }
+        const afterMarker = line.substring(line.indexOf(RESULT_MARKER) + RESULT_MARKER.length);
+        const jsonStr = this._decodeHtmlEntities(afterMarker);
+        try {
+            const parsed = JSON.parse(jsonStr);
+            if (parsed && parsed.__flowResult === true) {
+                return parsed;
+            }
+        }
+        catch {
+            this._logger.warn(`Failed to parse flow result JSON: ${jsonStr.substring(0, 200)}`);
+        }
+        return null;
+    }
+    /** Extract the JSON envelope from script output lines. */
+    _extractResultEnvelope(bgResult) {
+        // Search through scriptResults for our marker line
+        if (bgResult.scriptResults && bgResult.scriptResults.length > 0) {
+            for (const outputLine of bgResult.scriptResults) {
+                const envelope = this._tryParseEnvelopeFromLine(outputLine.line);
+                if (envelope)
+                    return envelope;
+            }
+        }
+        // Fallback: search through consoleResult string array
+        if (bgResult.consoleResult && bgResult.consoleResult.length > 0) {
+            for (const line of bgResult.consoleResult) {
+                const envelope = this._tryParseEnvelopeFromLine(line);
+                if (envelope)
+                    return envelope;
+            }
+        }
+        return null;
+    }
+    /** Parse BackgroundScriptExecutionResult into FlowExecutionResult. */
+    _parseFlowResult(bgResult, options) {
+        const envelope = this._extractResultEnvelope(bgResult);
+        if (envelope) {
+            return {
+                success: envelope.success,
+                flowObjectName: envelope.flowObjectName || options.scopedName,
+                flowObjectType: envelope.flowObjectType || options.type,
+                contextId: envelope.contextId || undefined,
+                executionDate: envelope.executionDate || undefined,
+                domainId: envelope.domainId || undefined,
+                outputs: envelope.outputs || undefined,
+                debugOutput: envelope.debugOutput || undefined,
+                errorMessage: envelope.errorMessage || undefined,
+                rawScriptResult: bgResult
+            };
+        }
+        this._logger.warn('Could not extract flow result envelope from script output');
+        return {
+            success: false,
+            flowObjectName: options.scopedName,
+            flowObjectType: options.type,
+            errorMessage: 'Could not parse flow execution result from script output. ' +
+                'The script may have failed before producing output.',
+            rawScriptResult: bgResult
+        };
+    }
+    // ================================================================
+    // Lifecycle Script Builders
+    // ================================================================
+    /** Validate that a context ID is non-empty. */
+    _validateContextId(contextId) {
+        if (!contextId || contextId.trim().length === 0) {
+            throw new Error('Context ID is required');
+        }
+    }
+    /** Escape a string for embedding in a generated SN script single-quoted string. */
+    _escapeForScript(str) {
+        return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+    }
+    /** Build script to query sys_flow_context status. */
+    _buildContextStatusScript(contextId) {
+        const escapedId = this._escapeForScript(contextId);
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        var gr = new GlideRecord('sys_flow_context');
+        if (gr.get('${escapedId}')) {
+            gs.info(__RESULT_MARKER + JSON.stringify({
+                __flowResult: true,
+                success: true,
+                contextId: '${escapedId}',
+                found: true,
+                state: '' + gr.getValue('state'),
+                name: '' + gr.getValue('name'),
+                started: gr.getValue('started') ? '' + gr.getValue('started') : null,
+                ended: gr.getValue('ended') ? '' + gr.getValue('ended') : null,
+                errorMessage: null
+            }));
+        } else {
+            gs.info(__RESULT_MARKER + JSON.stringify({
+                __flowResult: true,
+                success: true,
+                contextId: '${escapedId}',
+                found: false,
+                state: null,
+                name: null,
+                started: null,
+                ended: null,
+                errorMessage: null
+            }));
+        }
+    } catch (ex) {
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: false,
+            contextId: '${escapedId}',
+            found: false,
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        }));
+    }
+})();`;
+    }
+    /** Build script to retrieve flow outputs via FlowAPI.getOutputs(). */
+    _buildGetOutputsScript(contextId) {
+        const escapedId = this._escapeForScript(contextId);
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        var outputs = sn_fd.FlowAPI.getOutputs('${escapedId}');
+        var outputObj = {};
+        if (outputs) {
+            for (var key in outputs) {
+                if (outputs.hasOwnProperty(key)) {
+                    outputObj[key] = '' + outputs[key];
+                }
+            }
+        }
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: true,
+            contextId: '${escapedId}',
+            outputs: outputObj,
+            errorMessage: null
+        }));
+    } catch (ex) {
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: false,
+            contextId: '${escapedId}',
+            outputs: null,
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        }));
+    }
+})();`;
+    }
+    /** Build script to retrieve flow error via FlowAPI.getErrorMessage(). */
+    _buildGetErrorScript(contextId) {
+        const escapedId = this._escapeForScript(contextId);
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        var errorMsg = sn_fd.FlowAPI.getErrorMessage('${escapedId}');
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: true,
+            contextId: '${escapedId}',
+            flowErrorMessage: errorMsg ? '' + errorMsg : null,
+            errorMessage: null
+        }));
+    } catch (ex) {
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: false,
+            contextId: '${escapedId}',
+            flowErrorMessage: null,
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        }));
+    }
+})();`;
+    }
+    /** Build script to cancel a flow via FlowAPI.cancel(). */
+    _buildCancelScript(contextId, reason) {
+        const escapedId = this._escapeForScript(contextId);
+        const escapedReason = this._escapeForScript(reason);
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        sn_fd.FlowAPI.cancel('${escapedId}', '${escapedReason}');
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: true,
+            contextId: '${escapedId}',
+            errorMessage: null
+        }));
+    } catch (ex) {
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: false,
+            contextId: '${escapedId}',
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        }));
+    }
+})();`;
+    }
+    /** Build script to send a message to a paused flow via FlowAPI.sendMessage(). */
+    _buildSendMessageScript(contextId, message, payload) {
+        const escapedId = this._escapeForScript(contextId);
+        const escapedMessage = this._escapeForScript(message);
+        const escapedPayload = this._escapeForScript(payload);
+        return `(function() {
+    var __RESULT_MARKER = '${RESULT_MARKER}';
+    try {
+        sn_fd.FlowAPI.sendMessage('${escapedId}', '${escapedMessage}', '${escapedPayload}');
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: true,
+            contextId: '${escapedId}',
+            errorMessage: null
+        }));
+    } catch (ex) {
+        gs.info(__RESULT_MARKER + JSON.stringify({
+            __flowResult: true,
+            success: false,
+            contextId: '${escapedId}',
+            errorMessage: '' + (ex.getMessage ? ex.getMessage() : ex)
+        }));
+    }
+})();`;
+    }
+}
+//# sourceMappingURL=FlowManager.js.map

package/dist/sn/flow/FlowManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowManager.js","sourceRoot":"","sources":["../../../src/sn/flow/FlowManager.ts"],"names":[],"mappings":"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"}

package/dist/sn/flow/FlowModels.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Models for Flow Designer execution operations.
+ * Supports executing flows, subflows, and actions via BackgroundScriptExecutor
+ * using the sn_fd.FlowAPI.getRunner() (ScriptableFlowRunner) API.
+ */
+/** Type of Flow Designer object to execute. */
+export type FlowObjectType = 'flow' | 'subflow' | 'action';
+/** Execution mode: synchronous (foreground) or asynchronous (background). */
+export type FlowExecutionMode = 'foreground' | 'background';
+/** Options for executing a Flow Designer object (flow, subflow, or action). */
+export interface ExecuteFlowOptions {
+    /** Scoped name of the flow/subflow/action, e.g. "global.my_flow" */
+    scopedName: string;
+    /** Type of object to execute */
+    type: FlowObjectType;
+    /** Input name-value pairs to pass to the flow/subflow/action */
+    inputs?: Record<string, unknown>;
+    /**
+     * Execution mode: 'foreground' (sync) or 'background' (async).
+     * Default: 'foreground'
+     */
+    mode?: FlowExecutionMode;
+    /** Timeout in milliseconds (optional, SN default is 30s) */
+    timeout?: number;
+    /**
+     * Quick mode: skip execution detail records for better performance.
+     * Default: false
+     */
+    quick?: boolean;
+    /**
+     * Scope context for BackgroundScriptExecutor.
+     * Can be a scope name ("global", "x_myapp_custom") or a 32-character sys_id.
+     * Default: uses the FlowManager's default scope.
+     */
+    scope?: string;
+}
+/** Convenience options for executing a flow (type is implied). */
+export interface ExecuteFlowByNameOptions extends Omit<ExecuteFlowOptions, 'type'> {
+}
+/** Convenience options for executing a subflow (type is implied). */
+export interface ExecuteSubflowOptions extends Omit<ExecuteFlowOptions, 'type'> {
+}
+/** Convenience options for executing an action (type is implied). */
+export interface ExecuteActionOptions extends Omit<ExecuteFlowOptions, 'type'> {
+}
+/** Structured result from executing a flow/subflow/action. */
+export interface FlowExecutionResult {
+    /** Whether the execution completed without error */
+    success: boolean;
+    /** The scoped name of the executed flow object, e.g. "global.my_flow" */
+    flowObjectName: string;
+    /** Type of flow object that was executed */
+    flowObjectType: FlowObjectType;
+    /** sys_id of the execution context record (if not quick mode) */
+    contextId?: string;
+    /** Execution date/time as a string from the SN server */
+    executionDate?: string;
+    /** Domain sys_id (for domain-separated instances) */
+    domainId?: string;
+    /** Output name-value pairs returned by the flow/subflow/action */
+    outputs?: Record<string, unknown>;
+    /** Raw debug() output from ScriptableFlowRunnerResult */
+    debugOutput?: string;
+    /** Error message if execution failed */
+    errorMessage?: string;
+    /** The raw BackgroundScriptExecutionResult for advanced inspection */
+    rawScriptResult?: unknown;
+}
+/**
+ * JSON envelope structure used for communication between
+ * the generated SN server-side script and the FlowManager parser.
+ * @internal
+ */
+export interface FlowScriptResultEnvelope {
+    __flowResult: true;
+    success: boolean;
+    flowObjectName: string;
+    flowObjectType: string;
+    contextId: string | null;
+    executionDate: string | null;
+    domainId: string | null;
+    outputs: Record<string, unknown> | null;
+    debugOutput: string;
+    errorMessage: string | null;
+}
+/** Known states of a flow context record in sys_flow_context. */
+export type FlowContextState = 'QUEUED' | 'IN_PROGRESS' | 'WAITING' | 'COMPLETE' | 'CANCELLED' | 'ERROR' | string;
+/** Result from querying a flow context's status. */
+export interface FlowContextStatusResult {
+    success: boolean;
+    contextId: string;
+    found: boolean;
+    state?: FlowContextState;
+    name?: string;
+    started?: string;
+    ended?: string;
+    errorMessage?: string;
+    rawScriptResult?: unknown;
+}
+/** Result from retrieving outputs of a completed flow context. */
+export interface FlowOutputsResult {
+    success: boolean;
+    contextId: string;
+    outputs?: Record<string, unknown>;
+    errorMessage?: string;
+    rawScriptResult?: unknown;
+}
+/** Result from retrieving error messages of a flow context. */
+export interface FlowErrorResult {
+    success: boolean;
+    contextId: string;
+    flowErrorMessage?: string;
+    errorMessage?: string;
+    rawScriptResult?: unknown;
+}
+/** Result from cancelling a flow context. */
+export interface FlowCancelResult {
+    success: boolean;
+    contextId: string;
+    errorMessage?: string;
+    rawScriptResult?: unknown;
+}
+/** Result from sending a message to a paused flow. */
+export interface FlowSendMessageResult {
+    success: boolean;
+    contextId: string;
+    errorMessage?: string;
+    rawScriptResult?: unknown;
+}
+/**
+ * JSON envelope for lifecycle operations (status, outputs, errors, cancel, message).
+ * @internal
+ */
+export interface FlowLifecycleEnvelope {
+    __flowResult: true;
+    success: boolean;
+    contextId: string;
+    errorMessage: string | null;
+    found?: boolean;
+    state?: string | null;
+    name?: string | null;
+    started?: string | null;
+    ended?: string | null;
+    outputs?: Record<string, unknown> | null;
+    flowErrorMessage?: string | null;
+}

package/dist/sn/flow/FlowModels.js

@@ -0,0 +1,7 @@
+/**
+ * Models for Flow Designer execution operations.
+ * Supports executing flows, subflows, and actions via BackgroundScriptExecutor
+ * using the sn_fd.FlowAPI.getRunner() (ScriptableFlowRunner) API.
+ */
+export {};
+//# sourceMappingURL=FlowModels.js.map

package/dist/sn/flow/FlowModels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FlowModels.js","sourceRoot":"","sources":["../../../src/sn/flow/FlowModels.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonisoft/now-sdk-ext-core",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Comprehensive TypeScript library extending ServiceNow SDK with application management, ATF testing, real-time log monitoring, AMB event subscriptions, and automation tools",
   "keywords": [
     "servicenow",