docs(connector-builder): field names must match the vendor response; add Windows MSYS rule - #2542
docs(connector-builder): field names must match the vendor response; add Windows MSYS rule#2542mukeshkumar-uipath wants to merge 1 commit into
Conversation
…add Windows MSYS rule Two corrections from the ENGCE-59873 dogfooding pass. 1. Primary key vs path token (ENGCE-59873). The skill implied the by-id path token and the primary key were the same thing. They are not: the token names a URL slot and is substituted before the request leaves the platform, while the primary key names a field read back from the vendor response. Document the underlying rule that was missing entirely — a declared field's `name` must be the key the vendor actually returns, resolved as a dot-path against the raw JSON, with no field-level mapping available and no error when it misses. 2. Windows / Git Bash (ENGCE-60368). MSYS rewrites leading-slash arguments before the CLI sees them, so `--vendor-path /latest` is written as a Windows path and `validate` still reports PASS. Added as a Critical Rule with the MSYS_NO_PATHCONV workaround until the CLI-side guard lands. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
PR Review: docs(connector-builder) — field names & MSYS rule
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 61b862a8f8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| **`field.name` must be the key the vendor actually returns.** There is no field-level | ||
| response mapping — no `vendorPath`, `vendorName`, or transformation exists on an SR field, | ||
| and element-service does not project the response through the field list at all (it returns | ||
| the vendor body, minus an optional `rootKey` unwrap). The activity runtime resolves each | ||
| declared field by looking `field.name` up as a **dot-path into the raw vendor JSON** |
There was a problem hiding this comment.
When a postRequest hook reshapes or renames response keys, this rule incorrectly requires field.name to match the raw vendor JSON. The same skill documents that postRequest runs before returning to the caller and can rewrite response_body (references/hooks.md, including the shipped Graph key-deprefixing pattern), so following this guidance would declare the pre-transform key and produce empty outputs after the hook. Describe response fields against the final post-hook/root-unwrapped payload rather than unconditionally against the vendor payload.
Useful? React with 👍 / 👎.
1 participant
What
Two documentation corrections to the
uipath-connector-builderskill, both from the ENGCE-59873 dogfooding pass.1. Primary key vs by-id path token (ENGCE-59873)
The skill implied these were the same thing. They are not. The token names a URL slot and is substituted before the request leaves the platform; the primary key names a field read back from the vendor's response.
This also documents the rule that was missing entirely: a declared field's
namemust be the key the vendor actually returns, resolved as a dot-path against the raw JSON. There is no field-level response mapping on an SR field, and a name the vendor doesn't send binds to an empty activity output with no error anywhere. That silence is what made the reported bug invisible until run time.Includes a worked example (
--vendor-path '/latest/{base_currency}' --primary-key base_code) and the HubSpotget_contact_listshape as the catalogue reference for "path param is not the primary key".2. Windows / Git Bash MSYS path mangling (ENGCE-60368)
MSYS rewrites leading-slash arguments at process spawn, so
--vendor-path /latestreaches the CLI asC:/Program Files/Git/latest, andvalidatestill reports PASS. Added as a Critical Rule with theMSYS_NO_PATHCONV=1/MSYS2_ARG_CONV_EXCL='*'workaround, the list of affected path options, and a note that quoting does not help. Interim guidance until the CLI-side guard in ENGCE-60368 lands.Files
SKILL.md— Critical Rule 4 (token vs key), new Critical Rule 11 (MSYS), new anti-pattern 11, renumberingreferences/standard-resources.md— rewritten by-id section, new field-naming rule under §fieldsreferences/element-json.md— by-id token phrasingreferences/debugging.md— by-id phrasing, plus a new symptom entry for "an output field is always empty at run time"Note
The two changes are independent and land in the same file, so they are one PR but separate concerns. Say the word if you would rather split them.
Code counterpart: UiPath/cli#3535.
🤖 Generated with Claude Code