dohertj2/scadalink-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add dual call modes for external systems: synchronous Call() and cached CachedCall()

Browse Source 
Scripts now choose per invocation whether an external system call is synchronous
(all failures return to script) or cached (transient failures go to store-and-forward).
Mirrors the existing Database.Connection/CachedWrite pattern. Updated ESG, Site
Runtime script API, high-level requirements, and design doc.
This commit is contained in:
Joseph Doherty
2026-03-16 08:00:20 -04:00
parent 5fff1712a8
commit 1ef316f32c
4 changed files with 35 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
Component-ExternalSystemGateway.md
View File

@@ -73,12 +73,29 @@ All external system calls are **HTTP/REST** with **JSON** serialization:
- Response bodies are deserialized from JSON into the method's defined return type.
- Credentials (API key header or Basic Auth header) are attached to every request per the system's authentication configuration.
## External System Call Modes
Scripts choose between two call modes per invocation, mirroring the dual-mode database access pattern:
### Synchronous (Real-time)
- Script calls `ExternalSystem.Call("systemName", "methodName", params)`.
- The HTTP request is executed immediately. The script blocks until the response is received or the timeout elapses.
- **All failures** (transient and permanent) return an error to the calling script. No store-and-forward buffering.
- Use for request/response interactions where the script needs the result (e.g., fetching a recipe, querying inventory).
### Cached (Store-and-Forward)
- Script calls `ExternalSystem.CachedCall("systemName", "methodName", params)`.
- The call is attempted immediately. If it succeeds, the response is discarded (fire-and-forget).
- On **transient failure** (connection refused, timeout, HTTP 5xx), the call is routed to the Store-and-Forward Engine for retry per the system's retry settings. The script does **not** block — the call is buffered and the script continues.
- On **permanent failure** (HTTP 4xx), the error is returned **synchronously** to the calling script. No retry — the request itself is wrong.
- Use for outbound data pushes where deferred delivery is acceptable (e.g., posting production data, sending quality reports).
## Call Timeout & Error Handling
- Each external system definition specifies a **timeout** that applies to all method calls on that system.
- Error classification determines whether the Store-and-Forward Engine retries the call:
- **Transient failures** (connection refused, timeout, HTTP 5xx): The call is routed to the Store-and-Forward Engine for retry per the system's retry settings. The script does **not** block waiting for eventual delivery — the call is buffered and the script continues.
- **Permanent failures** (HTTP 4xx): No retry. The error is returned **synchronously** to the calling script for handling (log, notify, try different parameters, etc.). The failure is logged to Site Event Logging.
- Error classification by HTTP response:
- **Transient failures** (connection refused, timeout, HTTP 5xx): Behavior depends on call mode — `CachedCall` buffers for retry; `Call` returns error to script.
- **Permanent failures** (HTTP 4xx): Always returned to the calling script regardless of call mode. Logged to Site Event Logging.
- This classification ensures the S&F buffer is not polluted with requests that will never succeed.
## Database Connection Management