ScadaBridge/src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier/README.md

DelmiaNotifier (WWNotifier.exe)

A compact, self-contained Windows console app that DELMIA Apriso shells out to on each recipe / NC-program download to notify the plant that a recipe was placed at a path for a machine.

It is the modern, drop-in replacement for the legacy WWNotifier (see ../../docs/former-api-specs/dnc/Delmia-Integration-API.md, Surface B), repointed from the old Wonderware /notify receiver to the ScadaBridge Inbound API method DelmiaRecipeDownload (as-deployed spec: docs/api-specs/Delmia-Recipe-Download-API.md). The command-line flags, the YES/NO stdout contract, and the exit-code semantics are unchanged, so Delmia's call site and output parsing need no changes — only the executable on disk and its appsettings.json are swapped.

The published assembly name is WWNotifier precisely so it is a literal file-for-file drop-in for Delmia's existing call path.

What it does

Per invocation it POSTs the recipe-download notification to the configured ScadaBridge node(s) and maps the result back to the legacy contract:

DELMIA → WWNotifier.exe → POST {baseUrl}/api/DelmiaRecipeDownload  (X-API-Key: <key>)
                        ← { "Result": true/false, "ResultText": "..." }
        ← stdout: YES | NO\n<reason>   ·   exit: 0 | -1

Command-line flags

Short	Long	Required	→ payload field
-d	--downloadpath	yes	DownloadPath
-m	--machine	yes	MachineCode
-w	--workorder	yes	WorkOrderNumber
-p	--partnumber	yes	PartNumber
-s	--seqop	no	JobStepNumber
-u	--username	no	Username

Each flag takes one value (-m Z28061). A missing required flag → NO + reason, exit -1, no HTTP attempt.

WWNotifier.exe -m Z28061 -d "C:\recipes\job.nc" -w WO12345 -p PN-7788 -s 0100 -u operator1

Output contract (drop-in parity)

• stdout is reserved for the contract Delmia parses:
  • success → YES (exit 0)
  • failure → NO on the first line, then a human-readable reason on the next line (exit -1)
• exit code: 0 on success, -1 on failure. (On POSIX shells -1 surfaces as 255; on Windows %ERRORLEVEL% is -1.)
• All diagnostics (per-URL attempt, status code, which URL answered, exceptions) go to stderr and, if LogPath is set, an appended log file — never to stdout.

Delivery semantics

The notifier retries only when a request is known not to have executed: connection refusal, name-resolution failure, or the server's explicit standby rejection. A connection reset after sending or a response timeout returns OUTCOME_UNKNOWN without replay. Operators must verify an uncertain result before manually retrying. Idempotent method implementations remain useful because callers can deliberately retry, but the notifier does not blindly repeat ambiguous sends.

Configuration — appsettings.json

Placed next to the exe (copied to the output on build/publish):

{
  "ScadaBridge": {
    "BaseUrls": "http://host-a:8085,http://host-b:8085",
    "TimeoutSeconds": 30,
    "LogPath": "logs/delmia-notifier.log",
    "ApiKey": ""
  }
}

• BaseUrls — comma-separated failover list of base URLs only; the app appends /api/DelmiaRecipeDownload. URLs are tried in order after proven DNS/connection refusal or explicit standby rejection. Other HTTP responses are final; ambiguous transport errors return NO + OUTCOME_UNKNOWN without trying another URL.
• TimeoutSeconds — per-attempt HTTP timeout (default 30).
• LogPath — optional diagnostic log file, relative to the exe. Omit to log to stderr only.

Secret — SCADABRIDGE_API_KEY (or ScadaBridge:ApiKey)

The inbound API key is sent as X-API-Key. It is resolved from SCADABRIDGE_API_KEY first (recommended for production — the key never touches disk), falling back to ScadaBridge:ApiKey in appsettings.json when the variable is unset or blank (a blank file value counts as unset too; both values are trimmed). The diagnostic log records which source supplied the key — never the key itself — so a stale environment variable silently shadowing an edited file is visible. If neither is set → NO + API key not configured (SCADABRIDGE_API_KEY or ScadaBridge:ApiKey), exit -1, no HTTP attempt.

Set the variable on the machine/account that DELMIA runs under (e.g. a system/user environment variable, or the service account's environment). If you use the file instead, restrict its ACL to the account DELMIA runs under — the key is stored in plain text there. Fill ApiKey in only on the deployed copy: the repo's appsettings.json is tracked and copied to the build output, so a key pasted there to test locally is one git add away from being committed. It must stay "" in source control.

Building & publishing (Native AOT, win-x64)

The runtime artifact is a self-contained, single-file native exe. Native AOT does not cross-compile from macOS/Linux — publish on Windows with the MSVC build tools (Desktop C++ workload) installed:

# On Windows:
dotnet publish src/ZB.MOM.WW.ScadaBridge.DelmiaNotifier -c Release -r win-x64
# → bin/Release/net10.0/win-x64/publish/WWNotifier.exe  (+ appsettings.json)

Copy WWNotifier.exe and appsettings.json to the Delmia host, set SCADABRIDGE_API_KEY (or fill in ScadaBridge:ApiKey on that copy), and point BaseUrls at the central node(s).

Managed dotnet build / dotnet test run cross-platform and are the development/CI gate; only the final native publish requires Windows.

Manual smoke test

After deploying (or against a reachable test cluster such as wonder-app-vd03):

$env:SCADABRIDGE_API_KEY = "sbk_..."
.\WWNotifier.exe -m Z28061Sim -d "C:\recipes\test.nc" -w WO-TEST -p PN-TEST -s 0100 -u smoketest
# expect: YES  (exit 0)   — or NO + reason (exit -1) with details on stderr / in the log file

This mirrors the earlier curl verification of POST /api/DelmiaRecipeDownload with the X-API-Key header.

Docker rig recipe (no Galaxy needed)

The local rig (docker/) carries an in-memory stand-in for a vd03-style machine, so the whole path — notifier → inbound method → site Call script → simulated DelmiaReceiver handshake — runs on a laptop, including a 2-node central failover. Verified 2026-09-02 (docs/api-specs/Delmia-Recipe-Download-API.md §8):

bash docker/seed-delmia-sim.sh            # SimMachine/DelmiaReceiverSim templates + DelmiaSim01 on site-a, deployed
bash docker/seed-delmia-api.sh            # DelmiaRecipeDownload method + scoped key; prints DELMIA_API_KEY=sbk_... ONCE
export DELMIA_API_KEY=sbk_...
bash docker/sync-inbound-api-keys.sh      # keys are a per-node store: mirror central-a -> central-b (register row 108)
bash docker/verify-delmia-notifier.sh     # runs the managed build from a scratch copy; the key goes in THAT copy's appsettings.json

Case	Setup	Expected
A	active node first in BaseUrls	YES
B	standby first (standby relays to the active)	YES
C	bad key	NO + HTTP 401 (an answer is final — no failover)
D	active docker killed, attempt inside the takeover window	historical baseline: NO + HTTP 503; the updated client retries explicit standby refusals and still fails if no node is active
E	survivor /health/active = 200 (~27 s)	YES (first URL refused → second URL)
F	victim restarted and rejoined as standby	YES (victim relays)
G	DownloadPath ending in .bad	NO + Simulated reject: bad path or missing work order

Safe failover

The notifier advances to the next configured URL after a proven connection refusal/name-resolution failure, or HTTP 503 carrying the server's exact X-ScadaBridge-Standby: 1 pre-execution marker. A generic 503 or business rejection is final. Both centrals may therefore be listed even when their internal standby-forwarding peer lists are absent.

A timeout or other response loss is reported as OUTCOME_UNKNOWN with a failed result and no automatic replay: the first node may already have applied the download. Verify the operation before manually retrying. Configure trusted central endpoints; the standby marker is a server protocol contract, not permission to retry arbitrary HTTP errors.