UAT revealed Unraid GraphQL API (7.2.x) only has start/stop mutations.
updateContainer, updateContainers, updateAllContainers exist in API source
but ship in Unraid 7.3+ (unreleased). v1.3 workflows pushed to n8n as
stable rollback. v1.4 work preserved on branch for when 7.3 ships.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds 4 lessons learned from Phase 16 hotfix to prevent repeat issues:
- Connection keys/targets must use node names, not IDs
- Unraid GraphQL nodes must use Header Auth credential
- Node names must be unique
- Use $('Node Name') after GraphQL chains, not $input.item.json
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Incorporates 5 lessons from commit 216f3a4 into the plan:
- Connection keys/targets must use node names, not IDs
- HTTP auth must use Header Auth credential, not manual env vars
- Node names must be unique
- Use $('Node Name') after GraphQL chains, not $input.item.json
- Added validation checklist to verification section
Marks Task 2 as already completed (dead code removal done in hotfix).
Updates node counts from 193 to 181 baseline.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Added IF node to check batch size (threshold: 5 containers)
- Small batches (<=5): use single updateContainers mutation (parallel, fast)
- Large batches (>5): use existing serial Execute Workflow loop
- Build Batch Update Mutation node constructs updateContainers GraphQL query
- Execute Batch Update with 120-second timeout for large image pulls
- Handle Batch Update Response maps results and updates Container ID Registry
- Format and send batch result via Telegram
- Both paths produce consistent result messaging
Workflow pushed to n8n successfully (HTTP 200).
- Migrated Get Container For Action to GraphQL
- Migrated Get Container For Cancel to GraphQL
- Migrated Get All Containers For Update All to GraphQL (with imageId)
- Migrated Fetch Containers For Update All Exec to GraphQL (with imageId)
- Migrated Get Container For Callback Update to GraphQL
- Migrated Fetch Containers For Bitmap Stop to GraphQL
Added 6 GraphQL Response Normalizer nodes and 6 Container ID Registry update nodes.
All nodes use $env.UNRAID_HOST and $env.UNRAID_API_KEY for authentication.
15-second timeout for myunraid.net cloud relay.
Workflow pushed to n8n successfully (HTTP 200).
- Add Build Start/Stop Mutation Code nodes to construct GraphQL queries
- Update Start/Stop Container HTTP nodes to POST to Unraid GraphQL API
- Add GraphQL Error Handler nodes after each mutation (maps ALREADY_IN_STATE to 304)
- Implement restart as sequential stop+start chain (no native restart mutation)
- Add Handle Stop-for-Restart Result node to tolerate 304 on stop step
- Wire: Route Action -> Build Mutation -> HTTP -> Error Handler -> Format Result
- Format Result nodes unchanged (zero-change migration for output formatting)
- Workflow pushed to n8n: HTTP 200
- Replace all 5 Docker API HTTP Request nodes with GraphQL queries
- Add 5 GraphQL Response Normalizer nodes (one per query path)
- Transform Unraid GraphQL responses to Docker API contract format
- Preserve all downstream Code nodes unchanged (bitmap encoding, keyboard building)
- All connection chains validated and working
- Pushed to n8n successfully (HTTP 200)
- Replace 'Get All Containers' Docker API call with GraphQL query
- Add GraphQL Response Normalizer to transform Unraid format to Docker contract
- Add Container ID Registry update on every container lookup
- Update Resolve Container ID to output unraidId (PrefixedID) for mutations
- Wire: Query All Containers -> Normalizer -> Registry Update -> Resolve Container ID
- Added 15-01-SUMMARY.md documenting implementation and deviations
- Updated STATE.md: Phase 15 complete (2/2 plans), 52 total plans, v1.4 at 20%
- Task 1 (Container ID Registry) was pre-existing in baseline
- Task 2 (Token Encoder/Decoder) implemented and pushed to n8n
- All utility nodes standalone, ready for Phase 16 wiring
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Callback Token Encoder: compress 129-char Unraid PrefixedID to 8-char hex token
- SHA-256 hashing with 7-window collision detection (56 chars / 8-char windows)
- Callback Token Decoder: resolve 8-char token back to PrefixedID
- Both use JSON serialization for static data persistence (_callbackTokens)
- Standalone utility nodes at [600,2400] and [1000,2400]
- Not connected - Phase 16 will wire into active flow
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Phases 15-18: Infrastructure Foundation, API Migration, Cleanup, Documentation
23 requirements mapped across 4 phases with 0 gaps.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Unraid GraphQL API foundation — connectivity, authentication, and
container ID format verified for native Unraid API integration.
Phase 14: Unraid API Access (2 plans, 4 tasks)
- Established Unraid GraphQL API connectivity via myunraid.net cloud relay
- Dual credential storage (.env.unraid-api + n8n env vars)
- Container ID format: {server_hash}:{container_hash} (128-char SHA256 pair)
- Complete API contract documented in ARCHITECTURE.md
- "unraid" test command added to Telegram bot
Phases 15-16 dropped (superseded by v1.4 Unraid API Native).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Lucas Berger