From 68dd7ff803ef1037aeb225bb81776b633004f5a8 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 4 Feb 2026 21:37:10 -0500 Subject: [PATCH] docs(10.1-05): add sub-workflow deployment guide - Documents 6 sub-workflows (3 deployed, 3 pending) - Lists all Execute Workflow nodes and target IDs - Provides deployment steps for TODO placeholders - Includes rollback instructions using backup files - Architecture diagram shows workflow relationships - Input/output contracts for new sub-workflows - Testing checklist for post-deployment verification --- DEPLOY-SUBWORKFLOWS.md | 183 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 DEPLOY-SUBWORKFLOWS.md diff --git a/DEPLOY-SUBWORKFLOWS.md b/DEPLOY-SUBWORKFLOWS.md new file mode 100644 index 0000000..0d47c69 --- /dev/null +++ b/DEPLOY-SUBWORKFLOWS.md @@ -0,0 +1,183 @@ +# Sub-workflow Deployment Guide + +## Overview + +Phase 10.1 (Aggressive Workflow Modularization) reduced the main workflow from 192 nodes to 168 nodes by extracting domain-specific functionality into sub-workflows. + +**Final State:** +- Main workflow: 168 nodes (reduced by 24 nodes, -12.5%) +- Total sub-workflows: 6 (3 pre-existing + 3 new) + +## Sub-workflows + +| File | Purpose | Nodes | Status | +|------|---------|-------|--------| +| n8n-update.json | Container update operations | 34 | Deployed (ID: `7AvTzLtKXM2hZTio92_mC`) | +| n8n-actions.json | Container start/stop/restart | 11 | Deployed (ID: `fYSZS5PkH0VSEaT5`) | +| n8n-logs.json | Container log retrieval | 9 | Deployed (ID: `oE7aO2GhbksXDEIw`) | +| n8n-batch-ui.json | Batch selection UI | 16 | **TODO: Deploy** | +| n8n-status.json | Container list/status | 11 | **TODO: Deploy** | +| n8n-confirmation.json | Confirmation dialogs | 16 | **TODO: Deploy** | + +## Deployment Steps + +### Step 1: Deploy n8n-batch-ui.json + +1. In n8n, go to Settings > Import from File +2. Import `n8n-batch-ui.json` +3. Note the assigned workflow ID (e.g., `abc123xyz`) +4. In `n8n-workflow.json`, search for `TODO_DEPLOY_BATCH_UI_WORKFLOW` +5. Replace with the actual workflow ID: + ```json + "value": "abc123xyz" + ``` +6. There is 1 occurrence to replace + +### Step 2: Deploy n8n-status.json + +1. Import `n8n-status.json` to n8n +2. Note the assigned workflow ID +3. In `n8n-workflow.json`, search for `TODO_DEPLOY_STATUS_WORKFLOW` +4. Replace all occurrences with the actual workflow ID +5. There are 4 occurrences to replace: + - Execute Container Status + - Execute Select Status + - Execute Paginate Status + - Execute Batch Cancel Status + +### Step 3: Deploy n8n-confirmation.json + +1. Import `n8n-confirmation.json` to n8n +2. Note the assigned workflow ID +3. In `n8n-workflow.json`, search for `TODO_DEPLOY_CONFIRMATION_WORKFLOW` +4. Replace with the actual workflow ID +5. There is 1 occurrence to replace + +### Step 4: Re-import Main Workflow + +1. Import the updated `n8n-workflow.json` to n8n +2. Activate the workflow + +## Execute Workflow Node Mapping + +| Node Name | Target Sub-workflow | Workflow ID | +|-----------|---------------------|-------------| +| Execute Text Update | n8n-update.json | `7AvTzLtKXM2hZTio92_mC` | +| Execute Callback Update | n8n-update.json | `7AvTzLtKXM2hZTio92_mC` | +| Execute Batch Update | n8n-update.json | `7AvTzLtKXM2hZTio92_mC` | +| Execute Container Action | n8n-actions.json | `fYSZS5PkH0VSEaT5` | +| Execute Inline Action | n8n-actions.json | `fYSZS5PkH0VSEaT5` | +| Execute Batch Action Sub-workflow | n8n-actions.json | `fYSZS5PkH0VSEaT5` | +| Execute Text Logs | n8n-logs.json | `oE7aO2GhbksXDEIw` | +| Execute Inline Logs | n8n-logs.json | `oE7aO2GhbksXDEIw` | +| Execute Batch UI | n8n-batch-ui.json | `TODO_DEPLOY_BATCH_UI_WORKFLOW` | +| Execute Container Status | n8n-status.json | `TODO_DEPLOY_STATUS_WORKFLOW` | +| Execute Select Status | n8n-status.json | `TODO_DEPLOY_STATUS_WORKFLOW` | +| Execute Paginate Status | n8n-status.json | `TODO_DEPLOY_STATUS_WORKFLOW` | +| Execute Batch Cancel Status | n8n-status.json | `TODO_DEPLOY_STATUS_WORKFLOW` | +| Execute Confirmation | n8n-confirmation.json | `TODO_DEPLOY_CONFIRMATION_WORKFLOW` | + +## Rollback + +If issues are encountered, backup files are available: + +```bash +# Restore to before batch UI extraction +cp n8n-workflow.json.backup-batch n8n-workflow.json + +# Restore to before status extraction +cp n8n-workflow.json.backup-status n8n-workflow.json + +# Restore to before confirmation extraction +cp n8n-workflow.json.backup-confirm n8n-workflow.json +``` + +Then re-import the restored `n8n-workflow.json` to n8n. + +## Architecture + +``` +n8n-workflow.json (168 nodes - orchestrator) +├── Telegram Trigger (1) +├── Auth + Error Handling +├── Keyword Routing (switch/if nodes) +│ +├── Update Operations +│ ├── Execute Text Update ──────────┐ +│ ├── Execute Callback Update ──────┼── n8n-update.json (34 nodes) +│ └── Execute Batch Update ─────────┘ +│ +├── Action Operations +│ ├── Execute Container Action ─────┐ +│ ├── Execute Inline Action ────────┼── n8n-actions.json (11 nodes) +│ └── Execute Batch Action ─────────┘ +│ +├── Log Operations +│ ├── Execute Text Logs ────────────┐ +│ └── Execute Inline Logs ──────────┴── n8n-logs.json (9 nodes) +│ +├── Batch UI +│ └── Execute Batch UI ─────────────── n8n-batch-ui.json (16 nodes) +│ ├── Returns: keyboard/confirmation/execute/cancel/limit +│ └── Main routes response based on action +│ +├── Container Status +│ ├── Execute Container Status ─────┐ +│ ├── Execute Select Status ────────┼── n8n-status.json (11 nodes) +│ ├── Execute Paginate Status ──────┤ Returns: list/status/paginate +│ └── Execute Batch Cancel Status ──┘ +│ +└── Confirmation Dialogs + └── Execute Confirmation ─────────── n8n-confirmation.json (16 nodes) + ├── Returns: show_stop/show_update/confirm_*/cancel/expired + └── Calls n8n-actions.json for confirmed stop actions +``` + +## Sub-workflow Input/Output Contracts + +### n8n-batch-ui.json + +**Input:** +- `chatId`, `messageId`, `queryId` +- `callbackData`, `action`, `batchPage` +- `selectedCsv`, `toggleName` + +**Output:** +- `action`: keyboard | confirmation | execute | cancel | limit_reached + +### n8n-status.json + +**Input:** +- `chatId`, `messageId`, `queryId` +- `action`, `containerId`, `containerName` +- `page`, `searchTerm` + +**Output:** +- `action`: list | status | paginate | status_direct + +### n8n-confirmation.json + +**Input:** +- `chatId`, `messageId`, `queryId` +- `action`, `containerId`, `containerName` +- `confirmAction`, `confirmationToken` +- `expired`, `responseMode` + +**Output:** +- `action`: show_stop | show_update | confirm_stop_result | confirm_update | cancel | expired + +## Testing Checklist + +After deployment, verify: + +- [ ] `/list` - Shows container list +- [ ] `/status ` - Shows container details +- [ ] `/stop ` - Shows confirmation dialog +- [ ] Confirm stop - Executes stop action +- [ ] Cancel stop - Returns to status view +- [ ] `/update ` - Shows confirmation dialog +- [ ] Confirm update - Executes update flow +- [ ] `/stop` (no args) - Shows batch selection UI +- [ ] Select multiple containers - Batch selection works +- [ ] Execute batch - All selected containers processed +- [ ] `/logs ` - Shows container logs