procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/procesio/PROCESIO-SEND-EMAIL-CRED-OPTIONALITY.md

@@ -0,0 +1,45 @@
+# PROCESIO `Send Email` — credential optionality (why a "permanently optional email branch" can't ship credential-less)
+
+Live-probed on the `Send Email` action (`c7673492-…`) while building a **zero-credential**
+marketplace template (must import and run with no credentials configured). The question: can
+an email branch be built that runs when an SMTP credential + recipient are present and is
+skipped cleanly when they are not — inside a template that ships with **no** SMTP credential?
+Answer: **no, not via the API.** `Send Email` requires a real, bound SMTP credential just to
+**save**. Evidence (each from `process-create --dry-run`, which runs FE then BE validation):
+
+| Attempt | Result |
+|---|---|
+| `Send Email` with **no** credential bound | **FE blocks**: `REQUIRED` — *"Please make sure that the action is defined/configured properly."* on badge **"Send Email - Select SMTP credentials"**. (BE was empty.) |
+| Credential field bound to a **variable** (`{var:...}`) instead of a literal | FE passes, but **BE blocks**: *"Nullable object must have a value."* |
+| Bind a **mock/dummy** credential GUID | Rejected by policy — a credential that doesn't resolve is a support ticket on import; never do this. |
+| Keep a gated `Decisional` **without** a `Send Email` (both branches → one `Join`) | **BE blocks**: *"Duplicate connection port! SourceId … DestinationId …"* — two ports from one source to the same destination are illegal. |
+
+## Consequences (rules)
+
+- **`Send Email` is only saveable with a real, bound SMTP credential GUID** (a literal
+  credential instance id). Neither empty nor variable-bound satisfies validation.
+- Therefore, in a template that must run with **zero credentials**, the email node **cannot
+  be part of the shipped flow** — and neither can a "placeholder" gated `Decisional`, because
+  a Decisional's two branches must go to **two distinct targets**; with no `Send Email` to be
+  the second target, both would collapse onto the `Join` → "Duplicate connection port".
+- **Ship the flow linear** (no `Send Email`, no decorative `Decisional`/`Join`). Keep the
+  optional recipient **input variable** so the future email step has its trigger. The
+  zero-config run reaches `Stop` and produces its file outputs with no credential in play —
+  outputs never depend on a credential, which is the template standard.
+- This is a genuine **template-standard** finding, not a one-card quirk: any credential-less
+  marketplace template that wants an *optional* notification must add it **post-import**, not
+  ship it dormant.
+
+## Add the gated email branch AFTER import (manual UI recipe, once an SMTP credential exists)
+
+The gated branch *is* valid once there is a credential to bind (case and default then have
+two distinct targets):
+
+1. Create/adopt an **SMTP credential** in the workspace (Credentials → new SMTP).
+2. On the canvas, after the file-producing step, add a **Decisional** "Has Recipient?" with a
+   single case `SubmitterEmail IS_NOT_EMPTY`.
+3. In the **true** branch add **Send Email**: bind the SMTP credential; `To = SubmitterEmail`;
+   set Subject/Body; **Map attachment = [ExcelFile, PdfFile] as a `list<File>`** (a single
+   `File` silently drops the attachment though the run still returns status 50).
+4. Wire **Send Email → Join**; wire the Decisional **default → Join**; **Join → Stop**. Two
+   distinct targets (Send Email vs Join) — no duplicate-port error.

procesio_cli/tools/procesio/PROCESIO-SEND-EMAIL-NOTES.md

@@ -0,0 +1,252 @@
+# PROCESIO "Send Email" action — attachment + dynamic recipient
+
+How a PROCESIO **Send Email** action node sends an email with a **file
+attachment** and a **dynamic (variable) recipient**. Verified against both the
+offline `.procesio` export and the live `GET /api/Actions?getFullAction=true`
+catalog for workspace `3fd85e9d-121e-415b-877f-f488cd685ce3`.
+
+**Reference flow (real, working):**
+`tools/procesio/docs_info/Exports/export_POSF_PROCESIO.procesio` ->
+Flow **"Notification/Process Event with FILE"** -> action
+`ActionName="notify"`, `ActionTemplateName="Send Email"`,
+`TemplateId = c7673492-2912-4975-8cab-747fb9f4085d`, `Category = "cat1"`.
+
+This is a node-building note (how to author the action's `Parameters[]` in a
+flow DTO), complementing the API/auth notes — see
+[PROCESIO-API-NOTES.md](PROCESIO-API-NOTES.md).
+
+---
+
+## 1. "Send Email" is the only send action (SMTP, NOT SendGrid)
+
+The action catalog has four email-related actions:
+
+| Action | Purpose |
+|---|---|
+| **Send Email** | **The ONLY email-send action.** SMTP-based. |
+| Read Mailbox | Read incoming mail |
+| Read Mailbox V2 | Read incoming mail (newer) |
+| Word Mail Merge | Mail-merge a Word template |
+
+There is **no SendGrid action** in PROCESIO — "Send Email" goes out over SMTP.
+Its **first** configuration field is `type="credentials"`, label
+**"Select SMTP credentials"**, with
+`credentialsTemplateId = 20202020-0001-0000-0000-aaaaaaaaaaaa`. The bound
+value is the GUID of a stored SMTP credential (in the example below,
+`2aacf4f1-310c-469f-80ef-394d6ab9582f`).
+
+## 2. Variable-binding pattern (applies to every field)
+
+Every configurable field is one entry in the action's `Parameters[]` array:
+
+```jsonc
+{
+  "TabPropertyId": "<field GUID>",          // which field (see map in section 3)
+  "Variable": [                              // [] when the field is empty/literal
+    { "id": 0, "variableId": "<flow var GUID>", "attribute": null }
+  ],
+  "Value": "<%0%>"                           // PROCESIO placeholder(s) + literal text
+}
+```
+
+- **`Value`** holds PROCESIO placeholders of the form **`<%N%>`**, where `N` is
+  the `id` of the matching entry in `Variable[]`. Placeholders are **mixable
+  with literal text** — e.g. a Subject of `"Notificare mesaj: <%1%>"` injects
+  flow variable `id:1` after the literal prefix.
+- Each `<%N%>` in `Value` must have a `Variable[]` entry whose `id == N`; that
+  entry's `variableId` is the flow variable's GUID. `attribute` is `null` for a
+  whole-variable bind (set it to bind a sub-property of a complex variable).
+- A field that is **empty or purely literal** has **`Variable: []`** and either a
+  literal string `Value` (e.g. From display name `"POSF Notification"`) or
+  `""`/`null`.
+
+## 3. TabPropertyId map — Send Email fields
+
+| TabPropertyId | Field | Type / notes |
+|---|---|---|
+| `f9d5da64-bbc0-4d53-a0ad-6f948cc3ff05` | **Select SMTP credentials** | `credentials` (credentialsTemplateId `20202020-0001-0000-0000-aaaaaaaaaaaa`) |
+| `90d1ec9f-803c-42bc-bd8b-ca11e4ef116c` | **From (Display Name)** | string |
+| `90d1ec9f-803c-42bc-bd8b-ca11e4ef11c6` | **From (Entity)** | string — WARNING: differs from Display Name only in the last 4 chars (`...11c6` vs `...116c`); easy to transpose |
+| `1def19eb-ec69-4a21-a756-4abec8ae3171` | **To** | string (dynamic recipient — see section 5) |
+| `30ba958f-0d83-4259-97b9-d64ce7282d83` | **Cc** | string |
+| `1b6fbfac-183a-481b-9e0d-d4e7cf5543fe` | **Bcc** | string |
+| `9eeaf788-c023-4848-afe7-2454840bd321` | **Subject** | string |
+| `235aa4cf-d20f-4dbb-ad1d-d03e5ff5f13e` | **Body** | code-editor (HTML or plain text) |
+| `5330da65-bd38-4419-88c7-93136bdb6dd9` | **Map attachment** | `file`, `isList=true`, dataTypeId `10c6ac59-3929-49e6-99dc-121212121219` (see section 4) |
+| `3fdba8f7-75b5-4350-9d85-b542f8e5a73d` | **Body is Html** | check-box (`Value: null`/false = plain text; true = HTML) |
+
+## 4. Attachment — bind a File-typed variable
+
+Bind TabPropertyId **`5330da65-bd38-4419-88c7-93136bdb6dd9`** (Map attachment)
+to a **File** flow variable.
+
+- File DataType id = **`10c6ac59-3929-49e6-99dc-121212121219`**.
+- The field is a **list** (`isList=true`), so a **`List<File>`** fits naturally;
+  a **single `File`** variable also works.
+- In the reference flow it is bound to variable **`mailList`** (a `List<File>`,
+  `IsList=True`, DataType `10c6ac59-...121219`).
+- **No inline / base64 content.** Files travel as **PROCESIO File variable
+  references** — you build/obtain a File (e.g. via *Object To File*, *Export To
+  CSV*, a download action) earlier in the flow and pass that variable here. The
+  binding is `Variable:[{id:N, variableId:<file var>, attribute:null}]`,
+  `Value:"<%N%>"`.
+
+## 5. Dynamic recipient — bind a String variable
+
+Bind TabPropertyId **`1def19eb-ec69-4a21-a756-4abec8ae3171`** (To) to a
+**String** flow variable (DataType `0317bfee-b2f5-4bde-bfe8-121212121214`).
+
+- **One recipient:** point the String variable at a single address.
+- **Multiple recipients:** use **one String variable holding comma-joined
+  addresses** (NOT a List). In the reference flow the To field binds variable
+  **`emailsConcatenated`**, which is built upstream by a **For-Each** over the
+  recipient list feeding a **Concatenate** action (`concatEmails` +
+  `concatCrtEmail` in the same flow).
+
+- **Separator: use `;` for a LITERAL list, not `,` (verified live 2026-09-30).** A literal
+  To value `a@example.com,b@example.com` fails AT RUN with `Invalid emails a@example.com,b@example.com` (instance
+  status 40); the same value with `;` sends to both. Validation (FE + BE) passes either way, so
+  only a run catches it. Prefer `;` for variable-built lists too.
+- **SendGrid-backed SMTP credential: From (Entity) must be a verified sender.** Leaving it empty
+  (or using an unverified address) fails at run with `The from address does not match a verified
+  Sender Identity`. Find a working sender by reading an existing Send Email node that uses the
+  same credential (field `90d1ec9f-...11c6`) and reuse its From (Entity).
+
+## 6. Built-in dataTypeIds (for typing flow variables)
+
+| Type | dataTypeId |
+|---|---|
+| String | `0317bfee-b2f5-4bde-bfe8-121212121214` |
+| Text (rich) | `0317bfee-b2f5-4bde-bfe8-121212121221` |
+| Boolean | `0317bfee-b2f5-4bde-bfe8-121212121210` |
+| Integer / Guid | `0317bfee-b2f5-4bde-bfe8-121212121211` |
+| File | `10c6ac59-3929-49e6-99dc-121212121219` |
+
+---
+
+## Reference — verbatim `Parameters[]` from the `notify` action
+
+Taken as-is from the reference flow. Note the byte between `Notificare mesaj:`
+and `<%1%>` in the Subject is **U+00A0 (non-breaking space)**, not a normal
+space — preserved verbatim below.
+
+```json
+[
+  {
+    "TabPropertyId": "f9d5da64-bbc0-4d53-a0ad-6f948cc3ff05",
+    "Variable": [],
+    "Value": "2aacf4f1-310c-469f-80ef-394d6ab9582f"
+  },
+  {
+    "TabPropertyId": "90d1ec9f-803c-42bc-bd8b-ca11e4ef116c",
+    "Variable": [],
+    "Value": "POSF Notification"
+  },
+  {
+    "TabPropertyId": "1def19eb-ec69-4a21-a756-4abec8ae3171",
+    "Variable": [
+      {
+        "id": 0,
+        "variableId": "82957998-8f7f-46d6-819e-e370d9bc913d",
+        "attribute": null
+      }
+    ],
+    "Value": "<%0%>"
+  },
+  {
+    "TabPropertyId": "30ba958f-0d83-4259-97b9-d64ce7282d83",
+    "Variable": [],
+    "Value": ""
+  },
+  {
+    "TabPropertyId": "1b6fbfac-183a-481b-9e0d-d4e7cf5543fe",
+    "Variable": [],
+    "Value": ""
+  },
+  {
+    "TabPropertyId": "9eeaf788-c023-4848-afe7-2454840bd321",
+    "Variable": [
+      {
+        "id": 1,
+        "variableId": "50f8dbbe-ccc6-477b-9492-1544bb011d2d",
+        "attribute": null
+      }
+    ],
+    "Value": "Notificare mesaj: <%1%>"
+  },
+  {
+    "TabPropertyId": "235aa4cf-d20f-4dbb-ad1d-d03e5ff5f13e",
+    "Variable": [],
+    "Value": "Hello,
+
+The message body goes here. Line breaks in a plain-text body are literal \r\n sequences inside the JSON string, not real newlines.
+
+Regards,
+The team"
+  },
+  {
+    "TabPropertyId": "5330da65-bd38-4419-88c7-93136bdb6dd9",
+    "Variable": [
+      {
+        "id": 2,
+        "variableId": "3b45476e-b634-4e05-9fb5-c7ac521615ed",
+        "attribute": null
+      }
+    ],
+    "Value": "<%2%>"
+  },
+  {
+    "TabPropertyId": "3fdba8f7-75b5-4350-9d85-b542f8e5a73d",
+    "Variable": [],
+    "Value": null
+  }
+]
+```
+
+How the example binds each field (resolved against the flow's `Variables[]`):
+
+| TabPropertyId | Field | Binding |
+|---|---|---|
+| `f9d5da64-...ff05` | SMTP credentials | literal credential GUID `2aacf4f1-310c-469f-80ef-394d6ab9582f` |
+| `90d1ec9f-...116c` | From (Display Name) | literal `"POSF Notification"` |
+| `1def19eb-...3171` | **To** | `<%0%>` -> var `emailsConcatenated` (String, comma-joined) |
+| `30ba958f-...2d83` | Cc | empty |
+| `1b6fbfac-...543fe` | Bcc | empty |
+| `9eeaf788-...d321` | Subject | `"Notificare mesaj: <%1%>"` -> var `messageType` (String) |
+| `235aa4cf-...5f13e` | Body | literal multi-line plain-text body |
+| `5330da65-...6dd9` | **Map attachment** | `<%2%>` -> var `mailList` (List<File>) |
+| `3fdba8f7-...a73d` | Body is Html | `null` (unchecked -> plain-text body) |
+
+---
+
+## Corroborating flows (also use Send Email + Map attachment)
+
+Same pattern verified across other production exports under
+`tools/procesio/docs_info/Exports/`:
+
+- **RINGHEL_RINGHEL 1** -> `HR_UC/Add CtrAndAnnex`
+- **RINGHEL_RINGHEL 1** -> `PRC/Generate Contract`
+- **OMS_v2_dev** -> `notification/lateDeliveryNote`
+- **OMS_v2_dev** -> `utilitary/extractFile`
+- **RINGHEL_Demo** -> `Party Invite/Send email to all attendees`
+
+---
+
+## Map attachment requires `list<File>` (verified live 2026-06-25)
+
+The **"Map attachment"** field (`TabPropertyId 5330da65-bd38-4419-88c7-93136bdb6dd9`,
+`type="file"`) is a **LIST of files** at runtime. Binding a **single** `File` variable
+(model `10c6ac59-3929-49e6-99dc-121212121219`, `isList:false`) makes the designer show
+**"Error: data type mismatch"** on the Send Email node and the email sends with **NO
+attachment** — and the run STILL returns **status 50** (the mismatch does not fail the run,
+so a green run is NOT proof the file attached). The designer's "+ Add Variable" tooltip on
+that field literally reads **"Add Variable type=list <File>"**.
+
+**Fix:** the bound variable must be **`isList:true`** (a `list<File>`). So:
+- Declare the process input as `{model: "10c6ac59-…", isList: true}`.
+- When running directly, pass the file DTO **inside a list**: `"briefFile": [ <fileDTO> ]`.
+- A form file-upload control already holds a list, so a form→process attachment binds cleanly.
+
+A **dynamic recipient** is a normal variable bind: `To` Value `<%0%>` + `Variable:[{id:0,
+variableId: <recipientEmail var>}]` — verified delivering live to the entered address, with
+the `list<File>` PDF attached (form → Process 2 brief → Process 3 email, AAT_ use case).

procesio_cli/tools/procesio/PROCESIO-SQL-ACTIONS-NOTES.md

@@ -0,0 +1,284 @@
+# PROCESIO SQL Server actions — PARAMETERIZED (safe) vs INLINE `<%N%>` (WRONG)
+
+**Discovered 2026-07-03** during a review of a chat flow's contact-resolution
+nodes: the reviewer suffixed the existing nodes `[old]`, disabled them, and added
+`[new]` nodes "properly configured using parameters". The whole 2026-07 Networky build authored
+SQL nodes by **string-interpolating flow-variable values into the SQL text** as `N'<%N%>'`. That is
+(a) SQL-injection-prone and (b) the wrong action configuration.
+
+## THE RULE
+Never interpolate a flow-variable value into SQL as `N'<%N%>'`. Use the **`Execute Query`** action
+(NOT `Execute Query V2`) — or **`Execute Command`** for non-query writes — with its **parameter
+binding**: named `@params` in the SQL + a **`Parameters config tab`** (`map-parameters`) collection
+mapping each `@param` to a flow variable. The DB driver passes values as **typed SQL parameters**
+(escaped), so `O'Brien`, quotes, or malicious input can never break or inject the query.
+Literals (`@TopN = 5`) may stay inline. Variable values must be bound, never inlined.
+
+## WRONG (injectable — do NOT author, and convert existing)
+- Template **`Execute Query V2`** (inline-only; substitutes `<%N%>` as raw string into the SQL text).
+- Any `Execute Query` / `Execute Command` node whose SQL contains `N'<%N%>'` / `'<%N%>'` for a value.
+```sql
+-- INJECTABLE: a name like  O'Brien  or  '; DROP ...  breaks/injects it
+EXEC sp_FindContact @ConversationId = N'<%0%>', @Query = N'<%1%>', @TopN = 5
+```
+
+## CORRECT — `Execute Query` template, parameter binding
+```sql
+EXEC sp_FindContact @ConversationId = @conversationId, @Query = @resolveHint, @TopN = 5
+```
+plus a binding: `@conversationId <- flowVar(conversation)`, `@resolveHint <- flowVar(resolveHint)`.
+
+### Exact node DTO (the `Execute Query` template — property ids are stable, reuse them)
+`customData.configuration[0].settings`:
+- `Select Database Server` (type `credentials`) = credential gid (e.g. `45a1dd18-…` = Database).
+- `Execute Query` (type `side-pannel`) = a list of sub-settings:
+  - `{id: 11350a1d-4139-d942-adcb-a2c2c52e5e22, label: "Query", type: "code-editor", language: "sql", value: <SQL with @params>}`
+  - `{id: 73416282-bcfe-4934-9e40-a39f2bb33d2d, label: "Parameters config tab", type: "map-parameters", value: [{id, destination: "<paramName>", source: "<variableId>"}]}`
+  - `{id: 9ce93b2d-5226-4228-a64d-3693c8d3e0e3, label: "Time Out", type: "number", value: "100"}`
+  - `{id: 8aa02e91-1a1e-a44a-b09b-6965d67da04d, label: "Output", type: "any", value: "<output-var-gid>"}`
+
+`parameters[]` (the RUNTIME form the engine executes — must be kept in sync with the settings;
+tabPropertyId == the setting/sub-setting id):
+- `{tabPropertyId: f96ff811-572f-084a-8cac-a74a2c2e365f, value: "<credential-gid>"}`  (Select Database Server)
+- `{tabPropertyId: 11350a1d-…, value: "<SQL text with @params>"}`  (Query)
+- `{tabPropertyId: 73416282-…, value: [ {id:0, source:{value:"<%0%>", variable:[{id:0, variableId:"<gid>", attribute:null}]}, destination:{value:"<paramName>", variable:[]}}, … ] }`  (binding)
+- `{tabPropertyId: 9ce93b2d-…, value: "100"}`  (Time Out)
+- `{tabPropertyId: 8aa02e91-…, value: "<%K%>"}`  (Output binding; setting holds the output-var gid)
+
+Binding semantics: `destination.value` = the SQL parameter NAME (as it appears after `@` in the SQL —
+the action substitutes it with a typed parameter); `source.value` = a positional `<%N%>` whose
+`variable[0].variableId` is the flow variable GUID. So: SQL `@conversationId` ⇄ binding
+`destination:"conversationId"` ⇄ `source:<%0%>` ⇄ variable `conversation`.
+
+Reference DTO captured at `scratchpad/eq_reference.json` (the live `Execute Query [new]` from Resolve Contact).
+
+## `Execute Command` (SQL Server Command — INSERT/UPDATE/DELETE, no result set)
+Same defect when inlined — e.g. `Chat Flow/Extract Info Image` `Execute Command` node:
+`UPDATE messages SET ocr_text = COALESCE(ocr_text,' ') + N'<%0%>' …` (inline, injectable if the value
+is OCR/user text). Fix identically: named `@param` in the SQL + the `Parameters config tab` binding.
+(The Command template exposes the same `Query`/`Parameters config tab`/`Time Out` sub-settings; confirm
+its property ids from a live corrected node before authoring — do not assume they equal the Query ids.)
+
+## Converter / tooling — the `procesio` tool (NOT a Networky script)
+- **`procesio sql-scan --id <process-id>`** — lists every SQL node (Execute Query / Execute Command) with inline-vs-parameterized status. Read-only.
+- **`procesio sql-parameterize --id <process-id> {--node <label|id> | --all} [--dry-run]`** — converts inline `N'<%K%>'` → `@pK`, builds the `Parameters config tab` binding from the node's `<%N%>`→variable map (migrating a deprecated `Execute Query V2` node to `Execute Query`), then PROCESIO-validates and PUTs. NEVER PUTs an invalid flow; `--dry-run` previews.
+- Implementation: `tools/procesio/flowmodel/sqlparam.py` (pure) + `tools/procesio/handlers/sqlactions.py` + `tools/procesio/tests/test_sqlparam.py`.
+- **flowpatch note:** `setscript`/`syncparams` `_to_runtime_form` (GUID→`<%N%>`) is for **CODE (JS) nodes**,
+  NOT SQL. Never use it to (re)author a SQL node's `<%N%>` — that reproduces the injectable inline form.
+
+## Scope in the live build (to convert; audit ongoing)
+- `Execute Query V2` nodes (inline): `Get Last 10 msg` (sp_GetLastMesseges) in Start + clone (GUID inlined — low risk, still convert).
+- `Execute Command` inline: Extract Info Image OCR `UPDATE messages` (OCR text inlined — **user-text, HIGH risk**).
+- `Execute Query` template but inline SQL (my Leak-A edits): `Get info from SalesOMMO` Persist node
+  (`f2503397`, RecordSearchClaim/UpdateSessionContext) + Callback resolver (`11f25dbf`, sp_ClaimSearchResult).
+- **HIGH injection risk = wherever USER TEXT is inlined**: `@Query`/name (sp_FindContact), message_text
+  (sp_MessageAdd/AddMessage), OCR text — prioritize these. GUID/int-only inlines are lower risk.
+- The reviewer already fixed the two contact-resolution nodes (`Execute Query [new]`, `Pending Write [new]`); my
+  `[old]` disabled copies can be deleted.
+
+
+## CRITICAL — the action TYPE is the templateId, NOT the label (learned the hard way, 2026-07-04)
+The designer renders ACTION TYPE from **templateId**, not actionTemplateName. The 2026-07 build put MOST
+SQL nodes on the deprecated **V2 template `a9f851c2-e0ba-4fee-9a06-5445ba000001`** while LABELLING many
+of them "Execute Query". The map-parameters binding (73416282) is a property of the LATEST template
+`76470756-...` ONLY — it does NOT exist on V2. So adding the binding + @params to an a9f851c2 node leaves
+the @params UNBOUND at runtime -> the query errors (a real message creates no user/rows).
+- `procesio sql-parameterize` migrates by **templateId**: any node whose templateId contains `a9f851c2`
+  is swapped to `76470756` (role-based id remap) BEFORE the binding is added. Changing templateId on PUT
+  DOES persist. Keying on the "V2" LABEL alone misses the mislabelled nodes — that bug broke prod once.
+- **PROCESIO `validate` does NOT catch unbound @params** (structure only, not runtime binding). A
+  parameterized SQL change can pass validate and still fail at runtime. ALWAYS runtime-verify (below).
+
+## Runtime verification — the webhook E2E harness (no WhatsApp Web needed)
+Inject a synthetic WhatsApp-Business inbound at Start's webhook, then read the DB:
+`procesio webhook-launch --id db92281a-17b5-451f-b9f4-2a7f6a70f1fc --payload '{"PhoneNumber":"<digits>","FinalMessage":"<text>","MessageId":"wamid.TEST","ImageBase64":"","AudioBase64":""}'`
+The body is the flat WTB DataModel (PhoneNumber / FinalMessage / MessageId / ImageBase64 / AudioBase64),
+passed DIRECTLY (not wrapped in {WTB:...}). Use a fake phone (e.g. 4070000001X) so the Business-API reply
+fails harmlessly. Verify in chatbotAI: a users row + an in message + an out reply = the flow (incl. its SQL
+nodes) works. A REAL launch runs the live LLM + DB + Business-API send and creates real rows (delete test
+rows after). WhatsApp Web itself needs the linked phone ONLINE (else chats stay "Loading…", #main never
+opens; also dismiss the "What'''s new" modal).
+
+## MySQL + Redis engines (PRC-3696, 2026-08)
+
+The DB credential (catalog type "SQL") became multi-engine: `DbClientType` gained
+`MYSQL = 2` (alongside `MSSQL = 1`). A **MySQL** connection is the same DB credential with
+its **server-type** option set to MySQL; the existing `Execute Query` / `Execute Command`
+actions run against it unchanged (they resolve the client by the credential's DbClientType).
+`CustomMySQLClient` was added in BOTH the Web-Api credential-test stack and the
+Process-Execution runtime stack. **Redis** is a STANDALONE credential type
+(`CredentialsType.REDIS = 9`, NOT a `DbClientType`/SQL sub-type) with its own **"Redis
+Connector"** action (19 typed ops; no raw-command execution) — Web-Api #1452 / Action-Core
+#130 / Process-Execution #250. Redis properties: Host/Port(6379)/Username/Password/
+Database(0)/UseTls/ValidateCertificate/ConnectTimeoutSeconds/CommandTimeoutSeconds.
+It shipped but is **not yet activated** (template not seeded in DataBase-Update), so `Redis`
+is not in `/api/Credentials/types` yet; the contract is stable. Security: outbound DB hosts
+are validated by `DbHostBlacklistChecker` (CIDR blacklist) — a private/blacklisted host is
+rejected at connect time. Tool impact: none — credential types are live-resolved from
+`/api/Credentials/types`, so a MySQL/Redis credential is created by setting the template +
+properties (incl. the server-type option). Confirm the exact server-type option name/GUID
+with `procesio list-connection-types` post-launch.
+
+## `Execute Command` is a SECOND family with its own property ids
+
+`sql-parameterize` originally knew only the `Execute Query` family. Command nodes need their own
+ids, and getting this wrong is silent:
+
+| role | Execute Query (`76470756`) | Execute Command (`a1625da6`) |
+|---|---|---|
+| credentials | `f96ff811-572f-084a-8cac-a74a2c2e365f` | `5f75a4fd-d0f5-4ac1-8257-467e50e7292e` |
+| side-pannel | `8add0f17-b2b1-4d5f-962b-c5d400a4e2d4` | `975f25dc-1044-4488-b635-10a2039f8d89` |
+| sql | `11350a1d-4139-d942-adcb-a2c2c52e5e22` (Query) | `824575f6-7652-4bc2-8186-63b32c92cc22` (Command) |
+| **Parameters config tab** | `73416282-bcfe-4934-9e40-a39f2bb33d2d` | `0acb249e-8b21-4bfd-946c-1e65e26baa68` |
+| Time Out | `9ce93b2d-5226-4228-a64d-3693c8d3e0e3` | `2be309c6-9144-4b27-a722-fbc9c89735c2` |
+| Output | `8aa02e91-1a1e-a44a-b09b-6965d67da04d` (any) | `e6ffaa2d-2c32-412d-a9d4-b1038ece9d38` (number) |
+
+**Write the Query bind id onto a Command node and every `@param` is unbound at runtime**, with no
+validation error to show for it: the SQL still executes, the parameter simply arrives NULL, and a
+procedure that reads `OPENJSON(NULL)` inserts nothing and reports success. `sqlparam` now keys the
+family off `templateId` (`family_of` / `bind_pid`) so the right id is always used.
+
+### Deprecated templates, and why the label cannot be trusted
+
+Three templates are inline-only (no map-parameters), so a node on one MUST be migrated before it can
+bind anything: `Execute Query V2` (`a9f851c2-…ba000001`), `Execute Query V1`
+(`574a2ab1-…`), `Execute Command V1` (`c2760ff2-…`). `_migrate_to_current` does a role-based id
+remap from a table of each legacy template's ids, in both the runtime and designer layers, and
+refreshes each remapped setting's label to the current template's wording.
+
+**Always key on `templateId`, never on `actionTemplateName`.** In one live workspace all four
+collectors sat on `Execute Command V1` while two of them were *labelled* "Execute Command". The
+label is cosmetic and drifts; the templateId is what the designer and the engine resolve.
+
+### Migrating raises the Output type bar
+
+`Execute Command V1`'s Output was permissive; the current template types it **number** (rows
+affected, `isRequired`). A legacy node that bound an `Object`/`Json` variable there validates fine on
+V1 and fails migration with `statusCode 142 Data type mismatch … at parameter Output`. Retype that
+variable to number first (`variable-set-type`, safe when it is an internal type-20 variable that
+nothing else reads). The current template also makes **Time Out required** (60..1800) where the
+legacy one had none, so the migration seeds a default rather than leaving a required field empty.
+
+### Proving a parameter is actually bound
+
+A NULL-bound parameter is indistinguishable from "nothing to do" in the logs, so prove the binding
+instead of assuming it. Temporarily prefix the statement with a guard that fails loudly, keeping the
+real statement after it, and run the process:
+
+```sql
+IF @p0 IS NULL OR LEN(@p0) < 1000 RAISERROR('PROBE-PARAM-NOT-BOUND', 16, 1);
+EXEC <the real procedure> @Body = @p0;
+```
+
+A successful run proves the value arrived with real length; the RAISERROR surfaces as a failed
+instance carrying the message. **Run the negative control too**: set the threshold absurdly high and
+confirm the run DOES fail, otherwise a guard that never fires proves nothing. Restore the plain
+statement afterwards. At every point the process is either correct or fails safe, so this is
+usable on a live process when no fresh source data is available to observe an insert.
+
+## `Execute Command` DISCARDS a result set — `sql-convert` moves the node to `Execute Query`
+
+Discovered 2026-08-27. The two SQL families differ in more than their property ids: **`Execute
+Query` carries a RESULT SET into a flow variable; `Execute Command` carries ROWS AFFECTED** (its
+Output property is literally typed `number`). So a stored procedure that ends in `SELECT` — the
+normal way a procedure reports `Success` / `ErrorMessage` / a new id / a token back to its caller
+— returns all of that into a Command node's Output and it is thrown away. There is no error to
+find: the flow is valid, the run finishes green, `flow-lint` is clean, and the output variable
+just holds a count. Everything downstream then treats a refusal and a success identically.
+
+**The tell:** an `Execute Command` node whose SQL is `EXEC <proc>` where the proc's last statement
+is a `SELECT`. Also: an output variable declared `list<Object>` but bound to a Command node — the
+declared shape and the family disagree, and the family wins.
+
+**The fix:** `procesio sql-convert --id <process> --node <label|id> --to query
+[--output-variable <name|id>]`. It is a role-based property-id remap (the same machinery as the
+legacy-template migration) across BOTH the runtime `parameters[]` and the designer `customData`,
+plus three things the remap does not reach and a reader WILL trust: the Output setting's designer
+`type` (`number` -> `any`), the configuration container's label, and `customData.description`.
+The SQL text, credential, timeout and `@param` binding are carried across untouched. `--to command`
+is the exact inverse. A node on a deprecated template is refused rather than half-converted — run
+`sql-parameterize` first, which migrates it onto its family's current template.
+
+**Order matters when both are needed:** parameterize FIRST (it can migrate a legacy template), then
+convert the family. Converting first leaves `sql-parameterize`'s inline detector looking at the new
+family's property id, which is fine, but a legacy node would already have been refused.
+
+### The output variable's data type is a separate axis from the family
+`flow-lint`'s `EXECQUERY_OUTPUT_TYPE` wants an Execute Query Output to be `list<Object>`
+(`...121221`, `isList: true`). `...121220` (Json) also works at RUNTIME — a whole workspace ran on
+it — but the designer renders a "data type mismatch" on every such node. Fix it with
+`variable-set-type --data-type ...121221 --is-list true`; an output/input variable needs
+`--allow-contract-change` because it is the process's public shape.
+
+## Verifying a SQL change: run BOTH paths, and run one through the FORM
+
+`run-process --synchronous` returns `{status, variable, error}` directly, which makes the
+success path easy. The path that actually regresses is the REFUSAL path, because a discarded
+result set looks exactly like a successful one — so assert on a call the procedure must reject
+(a slot outside the offered list, a malformed email) and read the `ErrorMessage` back.
+
+And prove the injection fix while you are there: submit a value containing an apostrophe and a
+statement terminator (`O'Brien Test; DROP TABLE x--`). Under the old inline `N'<%N%>'` form that
+breaks or injects; under parameter binding it is stored verbatim as data. Reading the row back
+afterwards is the assertion.
+
+Finally run one submission through `run-form-with-files`, not just `run-process`: the form and the
+process are assembled separately and nothing asserts they agree. See
+PROCESIO-FORM-SUBMISSION-NOTES.md.
+
+## MySQL is GA - same credential template, `ServerType` discriminator (PRC-3696, 2026-07)
+
+MySQL is a first-class SQL engine now, not a separate credential type. The mechanics an
+API client must know:
+
+- **`DbClientType`**: `MSSQL = 1`, `MYSQL = 2`. This lives on the credential, not the
+  action. The Execute Query / Execute Command action templates are unchanged - the same
+  template runs against either engine and picks the driver from the bound credential.
+- **No separate MySQL credential template.** The existing SQL Server template was
+  UPDATEd in place: renamed to **"SQL"** and given a **`ServerType`** select
+  (`MSSQL` default / `MYSQL`). Choose MySQL by setting that property, not by choosing a
+  different template. `ProtocolType` is now **conditional on `ServerType=MSSQL`**; for
+  MySQL send `ServerType, ServerName, Username, Password` (required) + optional
+  `PortNumber` (default 3306), `DatabaseName`, `Encrypt`, `Pooling`,
+  `TrustServerCertificate`. On MySQL the `Encrypt`/`TrustServerCertificate` flags map to
+  MySqlConnector `SslMode`. Because the tool resolves credential templates live by name,
+  this needs no tool change - you build a "SQL" credential and set `ServerType`.
+- **Parameter binding** is named `@param` (Dapper) via `MapParameters {id, source,
+  destination}` → a dict keyed by `destination.value`, value `source.value`; a duplicate
+  destination errors. MySQL relies on `AllowUserVariables=true` (set server-side). Only
+  the V2 action variants carry a `Parameters` (Map_Parameters) tab; the base
+  Execute Query/Command bind no parameters. Keep using parameters, never inline
+  `<%N%>` for SQL (see the parameterization section above).
+- **DB host blacklist (silent).** Process-Execution enforces a `DbHostBlacklist` (host,
+  `host:port`, IP, or **CIDR**) BEFORE opening a connection; the committed default blocks
+  the private/non-routable ranges (172.16/12, 192.168/16, 127/8, 169.254/16, 100.64/10,
+  0.0.0.0/8 and IPv6 loopback/ULA/link-local), real prod ranges injected per-env. A block
+  is disguised as an ordinary **connect-timeout** - so a SQL/MySQL node that "times out"
+  connecting to an internal host may actually be blacklisted, not slow.
+- **Execute Command injection guard (PRC-5613):** stacked statements in Execute Command
+  are guarded server-side. Author one statement per action; rely on parameters.
+- **Data stores are MySQL-backed, per-workspace users (PRC-5442):** creating/altering a
+  data store provisions a physical MySQL table (why `datastore-create`/`-modify-column`
+  carry a long timeout). Not something the client sends, but explains the latency.
+
+Note reconciliation: an older line in `dto/credential/description.md` called
+"Execute Query V3 / Execute Command V2" the current versions; the live catalog and
+`flowmodel/sqlparam.py` treat the unversioned `Execute Query` / `Execute Command`
+(GUIDs `76470756-…` / `a1625da6-…`) as current, with V2 variants adding Timeout +
+Parameters. Trust the live catalog.
+
+## The `Execute Query` output is `list<Object>`, and `sql-parameterize` saves a failing flow as invalid (measured 2026-10-22)
+
+Declare the variable bound to an `Execute Query` **Output** as `{"type": "object", "isList": true}`
+(`0317bfee-…-121212121221`). A `json` list (`…1220`) is what many older flows use and it runs, and
+`process-create` accepts it, but the designer layer flags it (`flow-lint` EXECQUERY_OUTPUT_TYPE). The
+first `sql-parameterize` on such a flow then runs the designer gate, still PUTs the converted SQL,
+and stamps the flow `isValid: false`. The platform stores that stamp as is, so every launch answers
+`HTTP 400 statusCode 373 "Process needs to be valid in order to be launched."` even though
+`POST /api/Projects/validate` reports it valid. Read `isValid` in the `sql-parameterize` result (and
+run `flow-lint`) before you call the process ready. Fix: retype the variable in the config,
+`process-edit` (desired state, variable ids are kept by name), then `sql-parameterize --all` again.
+
+When parameterizing, keep each `<%N%>` alone on the right of a `DECLARE`
+(`DECLARE @key_in nvarchar(100) = N'<%0%>';`) and do the `COALESCE`/`LEFT`/`NULLIF` work on that SQL
+variable afterwards: the converter turns `N'<%N%>'` into `@pN` wherever it sits.