snow-flow 3.0.14 → 3.0.16

package/dist/mcp/servicenow-deployment-mcp.js

@@ -53,7 +53,7 @@ class ServiceNowDeploymentMCP {
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            type: { type: 'string', enum: ['widget', 'workflow', 'application'] },
+                            type: { type: 'string', enum: ['widget', 'application'] }, // removed 'workflow' - deprecated
                             artifact: { type: 'object', description: 'The artifact to validate' },
                         },
                         required: ['type', 'artifact'],
@@ -83,11 +83,11 @@ class ServiceNowDeploymentMCP {
                 },
                 {
                     name: 'snow_export_artifact',
-                    description: 'Exports ServiceNow artifacts (widgets, workflows, applications) to JSON/XML format for backup, version control, or migration purposes.',
+                    description: 'Exports ServiceNow artifacts (widgets, applications) to JSON/XML format for backup, version control, or migration purposes.', // removed workflows
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            type: { type: 'string', enum: ['widget', 'workflow', 'application'] },
+                            type: { type: 'string', enum: ['widget', 'application'] }, // removed 'workflow' - deprecated
                             sys_id: { type: 'string', description: 'Sys ID of the artifact' },
                             format: { type: 'string', enum: ['json', 'xml', 'update_set'], default: 'json' },
                         },
@@ -100,7 +100,7 @@ class ServiceNowDeploymentMCP {
                     inputSchema: {
                         type: 'object',
                         properties: {
-                            type: { type: 'string', enum: ['widget', 'workflow', 'application'] },
+                            type: { type: 'string', enum: ['widget', 'application'] }, // removed 'workflow' - deprecated
                             file_path: { type: 'string', description: 'Path to the artifact file' },
                             format: { type: 'string', enum: ['json', 'xml', 'update_set'], default: 'json' },
                         },
@@ -115,7 +115,7 @@ class ServiceNowDeploymentMCP {
                         properties: {
                             source_instance: { type: 'string', description: 'Source instance URL' },
                             target_instance: { type: 'string', description: 'Target instance URL' },
-                            type: { type: 'string', enum: ['widget', 'workflow', 'application'] },
+                            type: { type: 'string', enum: ['widget', 'application'] }, // removed 'workflow' - deprecated
                             sys_id: { type: 'string', description: 'Sys ID of the artifact to clone' },
                         },
                         required: ['source_instance', 'target_instance', 'type', 'sys_id'],
@@ -461,11 +461,11 @@ class ServiceNowDeploymentMCP {
      */
     getTableForType(type) {
         const tableMap = {
-            'flow': 'sys_hub_flow',
+            // 'flow': 'sys_hub_flow', // REMOVED - flows deprecated
             'widget': 'sp_widget',
             'script': 'sys_script_include',
             'business_rule': 'sys_script',
-            'workflow': 'wf_workflow',
+            // 'workflow': 'wf_workflow', // REMOVED - workflows deprecated
             'application': 'sys_app',
             'ui_action': 'sys_ui_action',
             'ui_page': 'sys_ui_page',
@@ -637,7 +637,9 @@ Your widget is deployed and ready for testing in Service Portal.`
                         this.logger.info('✅ Direct deployment successful');
                     }
                     else {
-                        throw new Error(`Widget creation failed: ${result?.error || 'Unknown error'}`);
+                        // Include detailed error information
+                        const errorDetails = result?.details ? JSON.stringify(result.details, null, 2) : '';
+                        throw new Error(`Widget creation failed: ${result?.error || 'Unknown error'}${errorDetails ? '\nDetails: ' + errorDetails : ''}`);
                     }
                 }
                 catch (error) {
@@ -1675,435 +1677,474 @@ ${args.widgets && args.widgets.length > 0 ? args.widgets.map((w, i) => `
 `;
         return css;
     }
-    async deployFlow(args) {
-        try {
-            // Enhanced authentication check with token refresh for deployment
-            const authResult = await this.deploymentAuthManager.ensureDeploymentAuth();
-            if (!authResult.isValid) {
-                this.logger.error('Deployment authentication failed:', authResult.error);
-                // If auth failed, try to refresh token
-                const refreshResult = await this.deploymentAuthManager.forceTokenRefresh();
-                if (!refreshResult.success) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `❌ Deployment authentication failed.\n\nError: ${authResult.error || 'Unable to authenticate'}\n\nRecommendations:\n${(authResult.recommendations || ['Run: snow-flow auth login']).map(r => `• ${r}`).join('\n')}\n\nNote: Deployment requires valid OAuth tokens with write permissions.`,
-                            },
-                        ],
-                    };
-                }
-            }
-            // Warn if token may lack write permissions
-            if (!authResult.hasWriteScope) {
-                this.logger.warn('⚠️ Token may lack write permissions, deployment might fail with 403');
-            }
-            // Ensure we have a flow definition
-            if (!args.flow_definition) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: '❌ Flow deployment failed: No flow_definition provided.\n\n💡 You need to provide a flow_definition with activities.\n\nExample:\n```json\n{\n  "name": "approval_flow",\n  "flow_definition": {\n    "activities": [\n      {\n        "id": "activity_1",\n        "name": "Check Condition",\n        "type": "condition"\n      }\n    ]\n  }\n}\n```\n\nOr use snow_create_flow with natural language for easier flow creation.',
-                        },
-                    ],
-                };
-            }
-            const flowType = args.flow_type || 'flow';
-            this.logger.info(`Deploying ${flowType} to ServiceNow`, { name: args.name, type: flowType });
-            // Validate flow definition first if requested
-            let validatedDefinition = args.flow_definition;
-            if (args.validate_before_deploy !== false) {
-                const validationResult = await this.validateFlowDefinition({
-                    definition: args.flow_definition,
-                    flow_type: flowType,
-                    show_preview: false,
-                    test_mode: false,
-                    check_dependencies: true
-                });
-                // Check if validation failed
-                const validationText = validationResult.content?.[0]?.text || '';
-                if (validationText.includes('❌') || validationText.includes('ERROR')) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `❌ Flow validation failed. Please fix the following issues:\n\n${validationText}\n\nUse snow_validate_flow_definition to preview and test your flow before deployment.`
-                            }
-                        ]
-                    };
-                }
-                // CRITICAL: Use the corrected definition from validation
-                // The validateFlowDefinition method may have auto-corrected "steps" or "actions" to "activities"
-                if (validationText.includes('Auto-converted "steps" to "activities"') ||
-                    validationText.includes('Auto-converted "actions" to "activities"') ||
-                    validationText.includes('Smart Auto-Corrections Applied')) {
-                    // Re-parse the corrected definition from the validation process
-                    const tempDef = typeof args.flow_definition === 'string' ? JSON.parse(args.flow_definition) : args.flow_definition;
-                    if (tempDef.steps && !tempDef.activities) {
-                        tempDef.activities = tempDef.steps;
-                        delete tempDef.steps;
-                    }
-                    else if (tempDef.actions && !tempDef.activities) {
-                        tempDef.activities = tempDef.actions;
-                        delete tempDef.actions;
-                    }
-                    validatedDefinition = JSON.stringify(tempDef);
-                    this.logger.info('Using auto-corrected flow definition for deployment');
-                }
-            }
-            // Ensure Update Set is active
-            const { updateSetId, updateSetName } = await this.ensureUpdateSet('Flow', args.name);
-            // Check if this is a master flow with linked artifacts
-            const isComposedFlow = args.composed_flow || args.linked_artifacts;
-            const linkedArtifacts = args.linked_artifacts || [];
-            // Deploy linked artifacts first if this is a composed flow
-            const deployedArtifacts = [];
-            if (isComposedFlow && linkedArtifacts.length > 0) {
-                this.logger.info('Deploying linked artifacts for composed flow', { count: linkedArtifacts.length });
-                for (const artifact of linkedArtifacts) {
-                    try {
-                        const deployResult = await this.deployLinkedArtifact(artifact);
-                        deployedArtifacts.push(deployResult);
-                    }
-                    catch (error) {
-                        this.logger.error('Failed to deploy linked artifact', { artifact, error });
-                        throw new Error(`Failed to deploy linked artifact ${artifact.name}: ${error}`);
-                    }
+    // DEPRECATED: Flow deployment is no longer supported - flows, workflows, and subflows have been removed
+    /* private async deployFlow(args: any) {
+      try {
+        // Enhanced authentication check with token refresh for deployment
+        const authResult = await this.deploymentAuthManager.ensureDeploymentAuth();
+        if (!authResult.isValid) {
+          this.logger.error('Deployment authentication failed:', authResult.error);
+          
+          // If auth failed, try to refresh token
+          const refreshResult = await this.deploymentAuthManager.forceTokenRefresh();
+          if (!refreshResult.success) {
+            return {
+            content: [
+              {
+                type: 'text',
+                text: `❌ Deployment authentication failed.\n\nError: ${authResult.error || 'Unable to authenticate'}\n\nRecommendations:\n${(authResult.recommendations || ['Run: snow-flow auth login']).map(r => `• ${r}`).join('\n')}\n\nNote: Deployment requires valid OAuth tokens with write permissions.`,
+              },
+            ],
+          };
+          }
+        }
+        
+        // Warn if token may lack write permissions
+        if (!authResult.hasWriteScope) {
+          this.logger.warn('⚠️ Token may lack write permissions, deployment might fail with 403');
+        }
+  
+        // Ensure we have a flow definition
+        if (!args.flow_definition) {
+          return {
+            content: [
+              {
+                type: 'text',
+                text: '❌ Flow deployment failed: No flow_definition provided.\n\n💡 You need to provide a flow_definition with activities.\n\nExample:\n```json\n{\n  "name": "approval_flow",\n  "flow_definition": {\n    "activities": [\n      {\n        "id": "activity_1",\n        "name": "Check Condition",\n        "type": "condition"\n      }\n    ]\n  }\n}\n```\n\nOr use snow_create_flow with natural language for easier flow creation.',
+              },
+            ],
+          };
+        }
+  
+        const flowType = args.flow_type || 'flow';
+        this.logger.info(`Deploying ${flowType} to ServiceNow`, { name: args.name, type: flowType });
+  
+        // Validate flow definition first if requested
+        let validatedDefinition = args.flow_definition;
+        if (args.validate_before_deploy !== false) {
+          const validationResult = await this.validateFlowDefinition({
+            definition: args.flow_definition,
+            flow_type: flowType,
+            show_preview: false,
+            test_mode: false,
+            check_dependencies: true
+          });
+          
+          // Check if validation failed
+          const validationText = validationResult.content?.[0]?.text || '';
+          if (validationText.includes('❌') || validationText.includes('ERROR')) {
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: `❌ Flow validation failed. Please fix the following issues:\n\n${validationText}\n\nUse snow_validate_flow_definition to preview and test your flow before deployment.`
                 }
-            }
-            // Parse flow definition to inject deployed artifact references
-            // Use the validated and corrected definition
-            let flowDefinition = validatedDefinition;
-            if (typeof flowDefinition === 'string') {
-                flowDefinition = JSON.parse(flowDefinition);
-            }
-            // Update flow activities with deployed artifact sys_ids
-            if (flowDefinition.activities && deployedArtifacts.length > 0) {
-                flowDefinition.activities = flowDefinition.activities.map((activity) => {
-                    if (activity.artifact_reference) {
-                        const deployed = deployedArtifacts.find(d => d.originalId === activity.artifact_reference.sys_id ||
-                            d.name === activity.artifact_reference.name);
-                        if (deployed) {
-                            activity.artifact_sys_id = deployed.sys_id;
-                            activity.artifact_api_name = deployed.api_name;
-                        }
-                    }
-                    return activity;
-                });
-            }
-            // Create flow data based on flow type
-            const flowData = {
-                name: args.name,
-                description: args.description,
-                active: args.active !== false,
-                flow_definition: JSON.stringify(flowDefinition),
-                category: args.category || 'automation',
-                // Additional fields for composed flows
-                is_composed: isComposedFlow,
-                linked_artifact_count: linkedArtifacts.length,
-                artifact_references: deployedArtifacts.map(a => a.sys_id).join(',')
+              ]
             };
-            // Configure based on flow type
-            switch (flowType) {
-                case 'flow':
-                    flowData.table = args.table || '';
-                    flowData.trigger_type = args.trigger_type;
-                    flowData.condition = args.condition || '';
-                    flowData.type = 'flow';
-                    break;
-                case 'subflow':
-                    // Subflows don't have triggers, they're called by other flows
-                    flowData.type = 'subflow';
-                    flowData.inputs = flowDefinition.inputs || [];
-                    flowData.outputs = flowDefinition.outputs || [];
-                    break;
-                case 'action':
-                    // Actions are reusable components
-                    flowData.type = 'action';
-                    flowData.action_type = args.action_type || 'custom';
-                    flowData.inputs = flowDefinition.inputs || [];
-                    flowData.outputs = flowDefinition.outputs || [];
-                    break;
-            }
-            // Deploy to ServiceNow using appropriate API based on flow type
-            let result;
-            let usedFallback = false;
-            let fallbackBusinessRule = null;
+          }
+          
+          // CRITICAL: Use the corrected definition from validation
+          // The validateFlowDefinition method may have auto-corrected "steps" or "actions" to "activities"
+          if (validationText.includes('Auto-converted "steps" to "activities"') ||
+              validationText.includes('Auto-converted "actions" to "activities"') ||
+              validationText.includes('Smart Auto-Corrections Applied')) {
+            // Re-parse the corrected definition from the validation process
+            const tempDef = typeof args.flow_definition === 'string' ? JSON.parse(args.flow_definition) : args.flow_definition;
+            if (tempDef.steps && !tempDef.activities) {
+              tempDef.activities = tempDef.steps;
+              delete tempDef.steps;
+            } else if (tempDef.actions && !tempDef.activities) {
+              tempDef.activities = tempDef.actions;
+              delete tempDef.actions;
+            }
+            validatedDefinition = JSON.stringify(tempDef);
+            this.logger.info('Using auto-corrected flow definition for deployment');
+          }
+        }
+  
+        // Ensure Update Set is active
+        const { updateSetId, updateSetName } = await this.ensureUpdateSet('Flow', args.name);
+  
+        // Check if this is a master flow with linked artifacts
+        const isComposedFlow = args.composed_flow || args.linked_artifacts;
+        const linkedArtifacts = args.linked_artifacts || [];
+  
+        // Deploy linked artifacts first if this is a composed flow
+        const deployedArtifacts: any[] = [];
+        if (isComposedFlow && linkedArtifacts.length > 0) {
+          this.logger.info('Deploying linked artifacts for composed flow', { count: linkedArtifacts.length });
+          
+          for (const artifact of linkedArtifacts) {
             try {
-                // Real ServiceNow Flow deployment using proper API calls
-                switch (flowType) {
-                    case 'flow':
-                        // Create workflow record in ServiceNow
-                        result = await this.client.createRecord('wf_workflow', {
-                            name: flowData.name || `flow_${Date.now()}`,
-                            description: flowData.description || 'Created by Snow-Flow',
-                            table: flowData.table || 'incident',
-                            active: flowData.active !== false,
-                            condition: flowData.condition || '',
-                            script: flowData.script || '// Flow logic here',
-                            order: flowData.order || 100
-                        });
-                        break;
-                    case 'subflow':
-                        // Create subflow as a workflow activity
-                        result = await this.client.createRecord('wf_workflow', {
-                            name: flowData.name || `subflow_${Date.now()}`,
-                            description: `${flowData.description || 'Subflow created by Snow-Flow'} [SUBFLOW]`,
-                            table: flowData.table || 'incident',
-                            active: flowData.active !== false,
-                            condition: flowData.condition || '',
-                            script: flowData.script || '// Subflow logic here',
-                            order: flowData.order || 200
-                        });
-                        break;
-                    case 'action':
-                        // Create workflow activity/action
-                        if (!flowData.workflow_id) {
-                            throw new Error('workflow_id is required for flow actions');
-                        }
-                        result = await this.client.createRecord('wf_activity', {
-                            workflow: flowData.workflow_id,
-                            name: flowData.name || `action_${Date.now()}`,
-                            script: flowData.script || '// Action script here',
-                            condition: flowData.condition || '',
-                            order: flowData.order || 100,
-                            active: flowData.active !== false
-                        });
-                        break;
-                    default:
-                        throw new Error(`Unknown flow type: ${flowType}. Supported types: flow, subflow, action`);
-                }
-            }
-            catch (flowError) {
-                this.logger.warn('Flow Designer deployment failed, attempting Business Rule fallback', {
-                    error: flowError,
-                    flowName: args.name
-                });
-                // Try to create equivalent Business Rule instead
-                try {
-                    fallbackBusinessRule = await this.createBusinessRuleFallback(args, flowDefinition);
-                    result = {
-                        success: true,
-                        data: fallbackBusinessRule,
-                        fallback_used: true,
-                        original_error: flowError instanceof Error ? flowError.message : String(flowError)
-                    };
-                    usedFallback = true;
-                    this.logger.info('Successfully created Business Rule fallback', {
-                        businessRuleId: fallbackBusinessRule.sys_id,
-                        originalFlowName: args.name
-                    });
-                }
-                catch (fallbackError) {
-                    this.logger.error('Both Flow Designer and Business Rule fallback failed', {
-                        flowError,
-                        fallbackError
-                    });
-                    throw new Error(`🚨 Flow deployment failed and fallback unsuccessful:
-
-📍 **Errors:**
-- Flow Designer Error: ${flowError instanceof Error ? flowError.message : String(flowError)}
-- Business Rule Fallback Error: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}
-
-🔧 **Update Set Troubleshooting:**
-1. Check current Update Set: snow_smart_update_set with action="track"
-2. Verify Update Set is active for tracking
-3. Use mock testing: snow_test_flow_with_mock instead
-4. Check flow exists: snow_get_by_sysid
-
-💡 **Alternative Solutions:**
-- Use snow_test_flow_with_mock for safe testing
-- Verify flow creation with snow_get_by_sysid
-- Check Update Set contains the flow artifact
-- Create Business Rule manually if needed
-
-📚 Please check your flow definition JSON format or use manual deployment.`);
-                }
-            }
-            const credentials = await this.oauth.loadCredentials();
-            const flowUrl = result.success && result.data
-                ? (usedFallback
-                    ? `https://${credentials?.instance}/sys_script.do?sys_id=${result.data.sys_id}`
-                    : `https://${credentials?.instance}/nav_to.do?uri=sys_hub_flow.do?sys_id=${result.data.sys_id}`)
-                : `https://${credentials?.instance}/flow-designer.do`;
-            const artifactSummary = deployedArtifacts.length > 0
-                ? `\n🔗 **Linked Artifacts Deployed:**\n${deployedArtifacts.map((a, i) => `${i + 1}. ${a.type}: ${a.name} (${a.sys_id})`).join('\n')}\n`
-                : '';
-            const activitySummary = flowDefinition.activities
-                ? `\n📊 **Flow Activities:**\n${flowDefinition.activities.map((a, i) => `${i + 1}. ${a.name} (${a.type})${a.artifact_reference ? ` - Uses: ${a.artifact_reference.name}` : ''}`).join('\n')}\n`
-                : '';
-            const successMessage = usedFallback
-                ? `🔄 **INTELLIGENT FALLBACK SUCCESSFUL!**
-
-⚠️ Flow Designer deployment failed, but Snow-Flow automatically created a Business Rule that achieves the same result!
-
-🛠️ **Business Rule Details:**
-- Name: ${args.name}
-- Type: 🔧 Business Rule (Fallback from Flow Designer)
-- Table: ${args.table || 'sys_user'}
-- When: ${this.getTriggerWhen(args.trigger_type)}
-- Active: ${args.active !== false ? 'Yes' : 'No'}
-- Original Error: ${result.original_error}
-
-✨ **Why This Works Better:**
-- ✅ More reliable than Flow Designer for simple automations
-- ✅ Faster execution (server-side JavaScript)
-- ✅ Better error handling and debugging
-- ✅ Direct database access capabilities`
-                : `✅ Flow Designer flow deployed successfully!
-            
-🔄 **${flowType.charAt(0).toUpperCase() + flowType.slice(1)} Details:**
-- Name: ${args.name}
-- Flow Type: ${flowType === 'flow' ? '📋 Flow' : flowType === 'subflow' ? '🔄 Subflow' : '⚡ Action'}
-- Composed: ${isComposedFlow ? '🧠 Yes - Intelligent Composed Flow' : '❌ No - Standard'}
-${flowType === 'flow' ? `- Trigger Type: ${args.trigger_type}
-- Table: ${args.table || 'N/A'}` : ''}
-${flowType !== 'flow' ? `- Inputs: ${flowDefinition.inputs?.length || 0}
-- Outputs: ${flowDefinition.outputs?.length || 0}` : ''}
-- Category: ${args.category || 'automation'}
-- Active: ${args.active !== false ? 'Yes' : 'No'}`;
-            const continuationMessage = usedFallback
-                ? `
-📦 **Update Set:**
-- Name: ${updateSetName}
-- ID: ${updateSetId}
-
-🔗 **Direct Links:**
-- Business Rule: ${flowUrl}
-- Business Rules List: https://${credentials?.instance}/sys_script_list.do
-
-📝 **Business Rule Components Created:**
-1. ✅ Trigger configured (${this.getTriggerWhen(args.trigger_type)})
-2. ✅ Condition logic applied
-3. ✅ Server-side script generated
-4. ✅ Error handling implemented
-5. ✅ Activation settings configured
-
-📋 **Next Steps:**
-1. Test business rule execution by triggering the event
-2. Check logs in System Logs > Script Log Statements  
-3. Modify the script if additional logic is needed
-4. Monitor performance and error handling
-
-🔄 **Snow-Flow Intelligent Fallback:**
-Snow-Flow automatically detected Flow Designer issues and created a functionally equivalent Business Rule. This is often more reliable and performant for simple automation tasks.`
-                : `
-📦 **Update Set:**
-- Name: ${updateSetName}
-- ID: ${updateSetId}
-${artifactSummary}${activitySummary}
-🔗 **Direct Links:**
-- Flow Designer: ${flowUrl}
-- Flow Designer Home: https://${credentials?.instance}/flow-designer.do?sysparm_nostack=true
-
-📝 **Flow Components Created:**
-1. ✅ Trigger configured (${args.trigger_type})
-2. ✅ Condition logic applied
-3. ✅ Flow definition structured with ${flowDefinition.activities?.length || 0} activities
-4. ✅ ${linkedArtifacts.length} artifacts linked and deployed
-5. ✅ Activation settings configured
-
-${isComposedFlow ? `
-🧠 **Intelligent Flow Features:**
-- ✅ Natural language instruction processed
-- ✅ Artifacts automatically discovered and linked
-- ✅ Dependencies resolved and deployed
-- ✅ Error handling configured
-- ✅ Variables and connections mapped
-` : ''}
-
-📋 **Next Steps:**
-1. Test flow execution with sample data
-2. Monitor flow performance and logs
-3. Review artifact connections
-4. Customize error handling if needed
-
-💡 **Composed Flow Capabilities:**
-- Automatic artifact orchestration
-- Intelligent output-to-input mapping
-- Multi-artifact dependency resolution
-- Natural language configuration`;
-            // ENHANCED: Ensure artifact is tracked in Update Set
-            if (result.success && result.data) {
-                await this.ensureUpdateSetTracking({
-                    sys_id: result.data.sys_id,
-                    type: usedFallback ? 'Business Rule' : 'Flow',
-                    name: args.name,
-                    table: usedFallback ? 'sys_script' : 'sys_hub_flow'
-                });
+              const deployResult = await this.deployLinkedArtifact(artifact);
+              deployedArtifacts.push(deployResult);
+            } catch (error) {
+              this.logger.error('Failed to deploy linked artifact', { artifact, error });
+              throw new Error(`Failed to deploy linked artifact ${artifact.name}: ${error}`);
             }
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: successMessage + continuationMessage,
-                    },
-                ],
-            };
+          }
         }
-        catch (error) {
-            const enhancedError = `🚨 Flow Deployment Failed
-
-📍 Error: ${error instanceof Error ? error.message : String(error)}
-
-🔧 Troubleshooting Steps:
-1. Check authentication: snow_auth_diagnostics()
-2. Validate flow definition: snow_validate_flow_definition()
-3. Check Update Set: snow_update_set_current()
-4. Verify flow_designer role permissions
-
-💡 Alternative Approaches:
-• Use snow_create_flow with natural language (recommended)
-• Test with snow_test_flow_with_mock() first
-• Use snow_flow_wizard for step-by-step creation
-• Try Business Rule fallback if flow creation fails
-
-📚 Documentation: See CLAUDE.md for Flow Development Guidelines`;
-            throw new Error(enhancedError);
+  
+        // Parse flow definition to inject deployed artifact references
+        // Use the validated and corrected definition
+        let flowDefinition = validatedDefinition;
+        if (typeof flowDefinition === 'string') {
+          flowDefinition = JSON.parse(flowDefinition);
         }
-    }
-    /**
-     * Deploy a linked artifact (script include, business rule, etc.)
-     */
-    async deployLinkedArtifact(artifact) {
-        this.logger.info('Deploying linked artifact', { type: artifact.type, name: artifact.name });
-        switch (artifact.type) {
-            case 'script_include':
-                return await this.deployScriptInclude(artifact);
-            case 'business_rule':
-                return await this.deployBusinessRule(artifact);
-            case 'table':
-                return await this.deployTable(artifact);
-            default:
-                throw new Error(`Unknown artifact type: ${artifact.type}`);
+  
+        // Update flow activities with deployed artifact sys_ids
+        if (flowDefinition.activities && deployedArtifacts.length > 0) {
+          flowDefinition.activities = flowDefinition.activities.map((activity: any) => {
+            if (activity.artifact_reference) {
+              const deployed = deployedArtifacts.find(d =>
+                d.originalId === activity.artifact_reference.sys_id ||
+                d.name === activity.artifact_reference.name
+              );
+              if (deployed) {
+                activity.artifact_sys_id = deployed.sys_id;
+                activity.artifact_api_name = deployed.api_name;
+              }
+            }
+            return activity;
+          });
         }
-    }
-    /**
-     * Deploy a script include artifact
-     */
-    async deployScriptInclude(artifact) {
-        const scriptIncludeData = {
-            name: artifact.name,
-            api_name: artifact.api_name || artifact.name,
-            description: artifact.description || `Script include for ${artifact.purpose}`,
-            script: artifact.script || artifact.fallback_script,
-            active: true,
-            access: 'public'
+  
+        // Create flow data based on flow type
+        const flowData: any = {
+          name: args.name,
+          description: args.description,
+          active: args.active !== false,
+          flow_definition: JSON.stringify(flowDefinition),
+          category: args.category || 'automation',
+          // Additional fields for composed flows
+          is_composed: isComposedFlow,
+          linked_artifact_count: linkedArtifacts.length,
+          artifact_references: deployedArtifacts.map(a => a.sys_id).join(',')
         };
-        const result = await this.client.createScriptInclude(scriptIncludeData);
-        if (!result.data?.sys_id) {
-            throw new Error(`Script Include deployment failed: No sys_id returned from ServiceNow. Result: ${JSON.stringify(result)}`);
+  
+        // Configure based on flow type
+        switch (flowType) {
+          case 'flow':
+            flowData.table = args.table || '';
+            flowData.trigger_type = args.trigger_type;
+            flowData.condition = args.condition || '';
+            flowData.type = 'flow';
+            break;
+          case 'subflow':
+            // Subflows don't have triggers, they're called by other flows
+            flowData.type = 'subflow';
+            flowData.inputs = flowDefinition.inputs || [];
+            flowData.outputs = flowDefinition.outputs || [];
+            break;
+          case 'action':
+            // Actions are reusable components
+            flowData.type = 'action';
+            flowData.action_type = args.action_type || 'custom';
+            flowData.inputs = flowDefinition.inputs || [];
+            flowData.outputs = flowDefinition.outputs || [];
+            break;
         }
-        return {
-            originalId: artifact.sys_id,
+  
+        // Deploy to ServiceNow using appropriate API based on flow type
+        let result;
+        let usedFallback = false;
+        let fallbackBusinessRule = null;
+        
+        try {
+          // Real ServiceNow Flow deployment using proper API calls
+          switch (flowType) {
+            case 'flow':
+              // Create workflow record in ServiceNow
+              result = await (this.client as any).createRecord('wf_workflow', {
+                name: flowData.name || `flow_${Date.now()}`,
+                description: flowData.description || 'Created by Snow-Flow',
+                table: flowData.table || 'incident',
+                active: flowData.active !== false,
+                condition: flowData.condition || '',
+                script: flowData.script || '// Flow logic here',
+                order: flowData.order || 100
+              });
+              break;
+            case 'subflow':
+              // Create subflow as a workflow activity
+              result = await (this.client as any).createRecord('wf_workflow', {
+                name: flowData.name || `subflow_${Date.now()}`,
+                description: `${flowData.description || 'Subflow created by Snow-Flow'} [SUBFLOW]`,
+                table: flowData.table || 'incident',
+                active: flowData.active !== false,
+                condition: flowData.condition || '',
+                script: flowData.script || '// Subflow logic here',
+                order: flowData.order || 200
+              });
+              break;
+            case 'action':
+              // Create workflow activity/action
+              if (!flowData.workflow_id) {
+                throw new Error('workflow_id is required for flow actions');
+              }
+              result = await (this.client as any).createRecord('wf_activity', {
+                workflow: flowData.workflow_id,
+                name: flowData.name || `action_${Date.now()}`,
+                script: flowData.script || '// Action script here',
+                condition: flowData.condition || '',
+                order: flowData.order || 100,
+                active: flowData.active !== false
+              });
+              break;
+            default:
+              throw new Error(`Unknown flow type: ${flowType}. Supported types: flow, subflow, action`);
+          }
+        } catch (flowError) {
+          this.logger.warn('Flow Designer deployment failed, attempting Business Rule fallback', {
+            error: flowError,
+            flowName: args.name
+          });
+          
+          // Try to create equivalent Business Rule instead
+          try {
+            fallbackBusinessRule = await this.createBusinessRuleFallback(args, flowDefinition);
+            result = {
+              success: true,
+              data: fallbackBusinessRule,
+              fallback_used: true,
+              original_error: flowError instanceof Error ? flowError.message : String(flowError)
+            };
+            usedFallback = true;
+            
+            this.logger.info('Successfully created Business Rule fallback', {
+              businessRuleId: fallbackBusinessRule.sys_id,
+              originalFlowName: args.name
+            });
+            
+          } catch (fallbackError) {
+            this.logger.error('Both Flow Designer and Business Rule fallback failed', {
+              flowError,
+              fallbackError
+            });
+            throw new Error(
+              `🚨 Flow deployment failed and fallback unsuccessful:
+  
+  📍 **Errors:**
+  - Flow Designer Error: ${flowError instanceof Error ? flowError.message : String(flowError)}
+  - Business Rule Fallback Error: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}
+  
+  🔧 **Update Set Troubleshooting:**
+  1. Check current Update Set: snow_smart_update_set with action="track"
+  2. Verify Update Set is active for tracking
+  3. Use mock testing: snow_test_flow_with_mock instead
+  4. Check flow exists: snow_get_by_sysid
+  
+  💡 **Alternative Solutions:**
+  - Use snow_test_flow_with_mock for safe testing
+  - Verify flow creation with snow_get_by_sysid
+  - Check Update Set contains the flow artifact
+  - Create Business Rule manually if needed
+  
+  📚 Please check your flow definition JSON format or use manual deployment.`
+            );
+          }
+        }
+        
+        const credentials = await this.oauth.loadCredentials();
+        const flowUrl = result.success && result.data
+          ? (usedFallback
+             ? `https://${credentials?.instance}/sys_script.do?sys_id=${result.data.sys_id}`
+             : `https://${credentials?.instance}/nav_to.do?uri=sys_hub_flow.do?sys_id=${result.data.sys_id}`)
+          : `https://${credentials?.instance}/flow-designer.do`;
+  
+        const artifactSummary = deployedArtifacts.length > 0
+          ? `\n🔗 **Linked Artifacts Deployed:**\n${deployedArtifacts.map((a, i) =>
+              `${i + 1}. ${a.type}: ${a.name} (${a.sys_id})`
+            ).join('\n')}\n`
+          : '';
+  
+        const activitySummary = flowDefinition.activities
+          ? `\n📊 **Flow Activities:**\n${flowDefinition.activities.map((a: any, i: number) =>
+              `${i + 1}. ${a.name} (${a.type})${a.artifact_reference ? ` - Uses: ${a.artifact_reference.name}` : ''}`
+            ).join('\n')}\n`
+          : '';
+  
+        const successMessage = usedFallback
+          ? `🔄 **INTELLIGENT FALLBACK SUCCESSFUL!**
+  
+  ⚠️ Flow Designer deployment failed, but Snow-Flow automatically created a Business Rule that achieves the same result!
+  
+  🛠️ **Business Rule Details:**
+  - Name: ${args.name}
+  - Type: 🔧 Business Rule (Fallback from Flow Designer)
+  - Table: ${args.table || 'sys_user'}
+  - When: ${this.getTriggerWhen(args.trigger_type)}
+  - Active: ${args.active !== false ? 'Yes' : 'No'}
+  - Original Error: ${result.original_error}
+  
+  ✨ **Why This Works Better:**
+  - ✅ More reliable than Flow Designer for simple automations
+  - ✅ Faster execution (server-side JavaScript)
+  - ✅ Better error handling and debugging
+  - ✅ Direct database access capabilities`
+          : `✅ Flow Designer flow deployed successfully!
+              
+  🔄 **${flowType.charAt(0).toUpperCase() + flowType.slice(1)} Details:**
+  - Name: ${args.name}
+  - Flow Type: ${flowType === 'flow' ? '📋 Flow' : flowType === 'subflow' ? '🔄 Subflow' : '⚡ Action'}
+  - Composed: ${isComposedFlow ? '🧠 Yes - Intelligent Composed Flow' : '❌ No - Standard'}
+  ${flowType === 'flow' ? `- Trigger Type: ${args.trigger_type}
+  - Table: ${args.table || 'N/A'}` : ''}
+  ${flowType !== 'flow' ? `- Inputs: ${flowDefinition.inputs?.length || 0}
+  - Outputs: ${flowDefinition.outputs?.length || 0}` : ''}
+  - Category: ${args.category || 'automation'}
+  - Active: ${args.active !== false ? 'Yes' : 'No'}`;
+  
+        const continuationMessage = usedFallback
+          ? `
+  📦 **Update Set:**
+  - Name: ${updateSetName}
+  - ID: ${updateSetId}
+  
+  🔗 **Direct Links:**
+  - Business Rule: ${flowUrl}
+  - Business Rules List: https://${credentials?.instance}/sys_script_list.do
+  
+  📝 **Business Rule Components Created:**
+  1. ✅ Trigger configured (${this.getTriggerWhen(args.trigger_type)})
+  2. ✅ Condition logic applied
+  3. ✅ Server-side script generated
+  4. ✅ Error handling implemented
+  5. ✅ Activation settings configured
+  
+  📋 **Next Steps:**
+  1. Test business rule execution by triggering the event
+  2. Check logs in System Logs > Script Log Statements
+  3. Modify the script if additional logic is needed
+  4. Monitor performance and error handling
+  
+  🔄 **Snow-Flow Intelligent Fallback:**
+  Snow-Flow automatically detected Flow Designer issues and created a functionally equivalent Business Rule. This is often more reliable and performant for simple automation tasks.`
+          : `
+  📦 **Update Set:**
+  - Name: ${updateSetName}
+  - ID: ${updateSetId}
+  ${artifactSummary}${activitySummary}
+  🔗 **Direct Links:**
+  - Flow Designer: ${flowUrl}
+  - Flow Designer Home: https://${credentials?.instance}/flow-designer.do?sysparm_nostack=true
+  
+  📝 **Flow Components Created:**
+  1. ✅ Trigger configured (${args.trigger_type})
+  2. ✅ Condition logic applied
+  3. ✅ Flow definition structured with ${flowDefinition.activities?.length || 0} activities
+  4. ✅ ${linkedArtifacts.length} artifacts linked and deployed
+  5. ✅ Activation settings configured
+  
+  ${isComposedFlow ? `
+  🧠 **Intelligent Flow Features:**
+  - ✅ Natural language instruction processed
+  - ✅ Artifacts automatically discovered and linked
+  - ✅ Dependencies resolved and deployed
+  - ✅ Error handling configured
+  - ✅ Variables and connections mapped
+  ` : ''}
+  
+  📋 **Next Steps:**
+  1. Test flow execution with sample data
+  2. Monitor flow performance and logs
+  3. Review artifact connections
+  4. Customize error handling if needed
+  
+  💡 **Composed Flow Capabilities:**
+  - Automatic artifact orchestration
+  - Intelligent output-to-input mapping
+  - Multi-artifact dependency resolution
+  - Natural language configuration`;
+  
+        // ENHANCED: Ensure artifact is tracked in Update Set
+        if (result.success && result.data) {
+          await this.ensureUpdateSetTracking({
             sys_id: result.data.sys_id,
-            name: artifact.name,
-            api_name: scriptIncludeData.api_name,
-            type: 'script_include',
-            success: result.success
+            type: usedFallback ? 'Business Rule' : 'Flow',
+            name: args.name,
+            table: usedFallback ? 'sys_script' : 'sys_hub_flow'
+          });
+        }
+  
+        return {
+          content: [
+            {
+              type: 'text',
+              text: successMessage + continuationMessage,
+            },
+          ],
         };
+      } catch (error) {
+        const enhancedError = `🚨 Flow Deployment Failed
+  
+  📍 Error: ${error instanceof Error ? error.message : String(error)}
+  
+  🔧 Troubleshooting Steps:
+  1. Check authentication: snow_auth_diagnostics()
+  2. Validate flow definition: snow_validate_flow_definition()
+  3. Check Update Set: snow_update_set_current()
+  4. Verify flow_designer role permissions
+  
+  💡 Alternative Approaches:
+  • Use snow_create_flow with natural language (recommended)
+  • Test with snow_test_flow_with_mock() first
+  • Use snow_flow_wizard for step-by-step creation
+  • Try Business Rule fallback if flow creation fails
+  
+  📚 Documentation: See CLAUDE.md for Flow Development Guidelines`;
+        throw new Error(enhancedError);
+      }
+    } */
+    /**
+     * Deploy a linked artifact (script include, business rule, etc.) - DEPRECATED
+     */
+    /* private async deployLinkedArtifact(artifact: any): Promise<any> {
+      this.logger.info('Deploying linked artifact', { type: artifact.type, name: artifact.name });
+  
+      switch (artifact.type) {
+        case 'script_include':
+          throw new Error('Script includes via flow deployment are deprecated. Use direct artifact creation instead.');
+        
+        case 'business_rule':
+          return await this.deployBusinessRule(artifact);
+        
+        case 'table':
+          return await this.deployTable(artifact);
+        
+        default:
+          throw new Error(`Unknown artifact type: ${artifact.type}`);
+      }
+    } */
+    /**
+     * Deploy a script include artifact - DEPRECATED
+     */
+    /* private async deployScriptInclude(artifact: any): Promise<any> {
+      const scriptIncludeData = {
+        name: artifact.name,
+        api_name: artifact.api_name || artifact.name,
+        description: artifact.description || `Script include for ${artifact.purpose}`,
+        script: artifact.script || artifact.fallback_script,
+        active: true,
+        access: 'public'
+      };
+  
+      const result = await this.client.createScriptInclude(scriptIncludeData);
+      
+      if (!result.data?.sys_id) {
+        throw new Error(`Script Include deployment failed: No sys_id returned from ServiceNow. Result: ${JSON.stringify(result)}`);
+      }
+      
+      return {
+        originalId: artifact.sys_id,
+        sys_id: result.data.sys_id,
+        name: artifact.name,
+        api_name: scriptIncludeData.api_name,
+        type: 'script_include',
+        success: result.success
+      };
     }
+  
     /**
      * Deploy a business rule artifact
      */
@@ -5539,13 +5580,13 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
                     let result;
                     switch (artifact.type) {
                         case 'flow':
-                            result = await this.deployFlow(artifact.create);
+                            throw new Error('Flow deployment is deprecated. Flows, workflows, and subflows are no longer supported. Use widgets or applications instead.');
                             break;
                         case 'widget':
                             result = await this.deployWidget(artifact.create);
                             break;
                         case 'script_include':
-                            result = await this.deployScriptInclude(artifact.create);
+                            result = await this.client.createScriptInclude(artifact.create);
                             break;
                         case 'business_rule':
                             result = await this.deployBusinessRule(artifact.create);
@@ -5861,12 +5902,7 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
                         };
                     }
                 case 'flow':
-                    const flowResult = await this.deployFlow(config);
-                    return {
-                        success: flowResult.content[0].text.includes('✅'),
-                        sys_id: flowResult.content[0].text.match(/sys_id: ([a-f0-9]+)/)?.[1],
-                        message: 'Flow deployed'
-                    };
+                    throw new Error('Flow deployment is deprecated. Use widgets or applications instead.');
                 case 'script':
                 case 'script_include':
                     const scriptResult = await this.createRecordWithRetry('sys_script_include', config);
@@ -5961,7 +5997,7 @@ Use \`snow_preview_widget\` to see a detailed preview of the widget rendering.`,
     async rollbackArtifact(artifact) {
         const tableMap = {
             'widget': 'sp_widget',
-            'flow': 'sys_hub_flow',
+            // 'flow': 'sys_hub_flow', // REMOVED - flows deprecated
             'script': 'sys_script_include',
             'script_include': 'sys_script_include',
             'business_rule': 'sys_script',
@@ -7596,11 +7632,11 @@ Use individual deployment tools like \`snow_deploy_${args.type}\` with manual co
     getTableForArtifactType(artifactType) {
         const ARTIFACT_TABLES = {
             'widget': 'sp_widget',
-            'flow': 'sys_hub_flow',
+            // 'flow': 'sys_hub_flow', // REMOVED - flows deprecated
             'script': 'sys_script_include',
             'script_include': 'sys_script_include',
             'business_rule': 'sys_script',
-            'workflow': 'wf_workflow',
+            // 'workflow': 'wf_workflow', // REMOVED - workflows deprecated
             'application': 'sys_app',
             'ui_action': 'sys_ui_action',
             'ui_page': 'sys_ui_page',

package/dist/utils/servicenow-client.d.ts

@@ -46,6 +46,7 @@ export interface ServiceNowAPIResponse<T> {
     data?: T;
     error?: string;
     result?: T[];
+    details?: any;
 }
 export declare class ServiceNowClient {
     private client;

package/dist/utils/servicenow-client.js

@@ -668,39 +668,91 @@ class ServiceNowClient {
             }
             // Ensure we have credentials before making the API call
             await this.ensureAuthenticated();
-            const response = await this.client.post(`${this.getBaseUrl()}/api/now/table/sp_widget`, {
+            // Log the request details for debugging
+            const widgetData = {
                 name: widget.name,
-                id: widget.id,
+                id: widget.id || widget.name, // Ensure id is set
                 title: widget.title,
-                description: widget.description,
+                description: widget.description || '',
                 template: widget.template,
-                css: widget.css,
-                client_script: widget.client_script,
-                script: widget.server_script, // Service Portal uses 'script' not 'server_script'
+                css: widget.css || '',
+                client_script: widget.client_script || '',
+                script: widget.server_script || '', // Service Portal uses 'script' not 'server_script'
                 option_schema: widget.option_schema || '[]',
                 demo_data: widget.demo_data || '{}',
-                has_preview: widget.has_preview || false,
-                category: widget.category || 'custom'
-            }, {
+                has_preview: widget.has_preview !== false, // Default to true
+                category: widget.category || 'custom',
+                active: true // Ensure widget is active
+            };
+            this.logger.info('Widget data to be sent:', widgetData);
+            const response = await this.client.post(`${this.getBaseUrl()}/api/now/table/sp_widget`, widgetData, {
                 timeout: this.deploymentTimeout, // Use deployment-specific timeout
                 headers: {
                     'X-Operation-Type': 'deployment' // Mark as deployment operation
                 }
             });
             this.logger.info('✅ Widget created successfully!');
-            this.logger.info(`🆔 Widget ID: ${response.data.result.sys_id}`);
+            // Handle different response structures from ServiceNow
+            const widgetResult = response.data.result || response.data;
+            const sysId = widgetResult.sys_id;
+            if (!sysId) {
+                this.logger.warn('⚠️ Widget created but no sys_id returned. Response:', response.data);
+                throw new Error('Widget creation succeeded but no sys_id was returned');
+            }
+            this.logger.info(`🆔 Widget ID: ${sysId}`);
             // Add post-deployment verification
-            await this.verifyDeployment(response.data.result.sys_id, 'widget');
+            await this.verifyDeployment(sysId, 'widget');
             return {
                 success: true,
-                data: response.data.result
+                data: widgetResult
             };
         }
         catch (error) {
             console.error('❌ Failed to create widget:', error);
+            // Better error handling for axios errors
+            let errorMessage = 'Unknown error';
+            let errorDetails = {};
+            if (error.response) {
+                // The request was made and the server responded with a status code
+                // that falls out of the range of 2xx
+                errorMessage = `HTTP ${error.response.status}: ${error.response.statusText || 'Request failed'}`;
+                errorDetails = {
+                    status: error.response.status,
+                    statusText: error.response.statusText,
+                    data: error.response.data,
+                    headers: error.response.headers
+                };
+                // Extract ServiceNow specific error message if available
+                if (error.response.data?.error?.message) {
+                    errorMessage = `ServiceNow Error: ${error.response.data.error.message}`;
+                }
+                else if (error.response.data?.error) {
+                    errorMessage = `ServiceNow Error: ${JSON.stringify(error.response.data.error)}`;
+                }
+                else if (error.response.status === 401) {
+                    errorMessage = 'Authentication failed: Invalid or expired token. Run: snow-flow auth login';
+                }
+                else if (error.response.status === 403) {
+                    errorMessage = 'Permission denied: User lacks sp_admin role or widget creation permissions';
+                }
+                else if (error.response.status === 404) {
+                    errorMessage = 'API endpoint not found: ServiceNow instance may not have Service Portal installed';
+                }
+            }
+            else if (error.request) {
+                // The request was made but no response was received
+                errorMessage = 'No response from ServiceNow - check network connection and instance URL';
+                errorDetails = { request: error.config?.url };
+            }
+            else {
+                // Something happened in setting up the request that triggered an Error
+                errorMessage = error.message || String(error);
+            }
+            this.logger.error('Widget creation error details:', errorDetails);
             return {
                 success: false,
-                error: error instanceof Error ? error.message : String(error)
+                error: errorMessage,
+                details: errorDetails
             };
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "snow-flow",
-  "version": "3.0.14",
-  "description": "Snow-Flow v3.0.14: WRITE PERMISSIONS FIX! 🔧 Fixed 'this.client.create is not a function' error that was blocking all deployments. Corrected API method calls to use createRecord/deleteRecord. Write permissions diagnostic now works correctly. Plus all features: Zero Mock Data Guarantee, race condition fixes, intelligent reporting, and 100+ MCP tools.",
+  "version": "3.0.16",
+  "description": "Snow-Flow v3.0.16: WIDGET DEPLOYMENT ERROR FIX! 🔧 Fixed 'error: null' issue in widget deployment. Enhanced error reporting for failed POST requests to /api/now/table/sp_widget. Now provides detailed HTTP status codes, ServiceNow-specific error messages, and better debugging information. Widget deployment failures now show exact cause (401 auth, 403 permissions, 404 endpoint, etc).",
   "main": "dist/index.js",
   "type": "commonjs",
   "bin": {