feat: route DTL calls via script execution for v4 (#ENGCE-61216)

[mrstark14]

Why

Reference fields on 4.0.0 (v4) connector activities are script-backed, not object-backed. The v4 metadata carries reference.scriptRef and has no objectName / path:

"reference": { "scriptRef": "list_usergroups", "lookupValue": "id", "lookupNames": ["id", "name"] }

uip is resources describe uipath-salesforce-slack add_users_to_usergroup --activity-version 4.0.0 --operation POST

The skills only knew one lookup path — uip is resources run list <connector> <reference.objectName> — which cannot resolve these: there is no object to list. The CLI now exposes the design-time lookup (DTL) scripts through the IPE Runtime Proxy (elements_/v4/execute, feat: Add support to execute IPE runtime proxy (#ENGCE-61027)):

uip is resources run script --connection-id <id> --connector-key uipath-salesforce-slack --script-ref list_usergroups

integrationservice-tool/src/commands/resources.ts § run script

Two things an agent cannot infer and would otherwise get wrong:

• maestro flow registry get strips scriptRef. applyOptionalFieldProps copies only objectName/lookupValue/lookupNames/path/childPath (maestro-sdk/src/registry/integration-service-fetcher.ts), so a v4 field surfaces as reference: { lookupValue, lookupNames } with no target. The docs now say: neither objectName nor scriptRef on a 4.0.0 node means script-backed — read scriptRef from describe, never run list a guessed object.
• The response envelope differs from run list. The proxy relays the vendor answer verbatim (ADR-0014): Data.Body is a JSON string decoding to {status, headers, body}, a vendor 4xx/5xx still returns Result: "Success" (read Data.Status), --output-filter cannot reach inside the string, and there is no Data.Pagination.

What

File	Change
uipath-platform/.../reference-resolution.md	New section 4.0.0 Activities — Script References (scriptRef): reference shape, 4-step resolution workflow (describe --activity-version 4.0.0 --operation <METHOD> → run script --script-ref → match lookupNames → write lookupValue), response parsing with a jq example, dotted lookupNames (profile.email), and where scriptRef is/isn't visible. Connection-Scoped and When the Lookup Call Fails now name run script alongside run list so the no-substitution rules apply to both.
uipath-platform/.../resources.md	§ --activity-version: v4 describe example gains --operation <METHOD> (without it the response is an operation summary with no requestFields), plus the scriptRef → run script pointer. New § run script under Execute Operations: syntax, --script-ref xor --inline-script, --connector-key required with --script-ref, envelope caveats.
uipath-maestro-flow/.../connector/impl.md	§ 4.0.0 Activities: delta 5 — reference fields are script-backed, resolve with run script, registry get strips scriptRef. Step 4: callout routing 4.0.0 nodes to run script with parsing rules; zero-match / multi-match / failed-call / connection-scoping rules unchanged.

No frontmatter, Critical Rules, or flavor-marked passages touched; no skill-flavors/ override exists for these files.

Verified

• uip is resources run script … --script-ref list_usergroups against a live Slack connection: Outcome: vendor, Status: 200, Data.Body → {status, headers, body} with 821 user-group rows carrying id/name — matches the documented parsing.
• describe … --activity-version 4.0.0 without --operation returns AvailableOperations: null and no fields; with --operation POST it returns Reference.ScriptRef — hence the added flag.
• node scripts/check-skill-links.mjs — all 6709 links resolve (new anchors included).
• scripts/check-skill-verbs.py flags is resources run script as stale only because assets/uip-catalog-snapshot.json was built from a dev CLI that predates the command; rebuilding the snapshot needs the rpa tool installed for the 1.203.x line (the build refuses otherwise).

🤖 Generated with Claude Code

[github-actions]

Claude finished @mrstark14's task in 3m 5s —— View job

---

PR Review: Route DTL calls via script execution for v4

• Gather context and read review criteria
• Read full diff and changed files
• Perform skill-specific checks
• Post review findings

---

Summary

Documents the uip is resources run script command for resolving 4.0.0 activity reference fields that use scriptRef instead of objectName. Changes span two skills: adds a new authoritative section in uipath-platform (reference-resolution.md, resources.md) and wires in the routing from uipath-maestro-flow (impl.md). Also corrects the 4.0.0 describe command to include the required --operation flag.

Change-by-Change Review

1. skills/uipath-platform/references/integration-service/reference-resolution.md

Severity: OK

New section "4.0.0 Activities — Script References (scriptRef)" (lines 135–197) is well-structured: example JSON, property table, step-by-step CLI workflow, response parsing, and a "Where scriptRef is visible" subsection explaining the registry get vs describe gap. TOC updated (line 11). Existing CRITICAL sections ("Reference IDs Are Connection-Scoped", "When the Lookup Call Fails") updated to mention run script alongside run list — this is correct since the same rules apply. All internal anchors resolve. Clean addition.

2. skills/uipath-platform/references/integration-service/resources.md

Severity: OK

Two clean changes:

• Describe command fix (line 77): Adds --operation <METHOD> to the 4.0.0 describe example, with an explanatory note that without it the response is an operation summary with no requestFields. Correct and important — the old example would have returned incomplete metadata.
• New run script subsection (lines 142–151): Compact, shows the command with proper <PLACEHOLDER> casing, notes the --script-ref / --inline-script mutual exclusivity and the Data.Body-is-a-string caveat, then points to reference-resolution.md for the full workflow. Good pointer discipline.

3. skills/uipath-maestro-flow/references/author/plugins/connector/impl.md

Severity: Low

Two additions:

• Point 5 in § 4.0.0 Activities (line 42): Adds the script-backed reference delta with the full run script command and a link to the authoritative reference-resolution.md section. Follows the pattern of the other four points. The command uses camelCase placeholders (<scriptRef>, <connector-key>) instead of the repo convention <SCRIPT_REF>, <CONNECTOR_KEY> — minor inconsistency with resources.md (line 147) which uses UPPER_SNAKE_CASE. Fix this →
• Step 4 blockquote (line 125): Includes the full command plus parsing instructions (parse Data.Body… rows under .body… match lookupNames → take lookupValue). The parsing detail overlaps with reference-resolution.md's "Reading the response" subsection, but it's compact enough to serve as an in-context shortcut for agents following the step-by-step workflow. Acceptable bridge content given the established pattern in this file.

Cross-skill links from uipath-maestro-flow → uipath-platform are an existing pattern throughout impl.md (lines 36, 61, 107, 117, 131, etc.). All link targets verified to exist.

What's Missing

• Test coverage for run script: No existing tasks in tests/tasks/uipath-maestro-flow/ or tests/tasks/uipath-platform/integration-service/ cover the run script command or scriptRef resolution. This is a new CLI workflow for 4.0.0 activities — a task validating that an agent routes to run script (not run list) when a reference block carries scriptRef would be valuable. (Medium — per review criteria, new capabilities without test tasks.)

Area Ratings

Area	Status	Notes
Frontmatter	OK	No frontmatter changes
E2E Tests	Issue	No test tasks cover the new run script workflow
Skill Body	OK	No SKILL.md changes
References & Assets	OK	New section is authoritative and well-structured; pointer discipline is clean
Repo Hygiene	OK	No secrets, no new skill paths, scoped changes, all links resolve

Issues for Manual Review

• CLI command accuracy: Verify that uip is resources run script --connection-id <id> --connector-key <key> --script-ref <ref> is the correct syntax and that --connector-key is indeed required with --script-ref. This cannot be verified from documentation alone.
• Response envelope shape: The Data.Body is documented as a JSON string decoding to { status, headers, body }. Confirm this matches the actual IPE Runtime Proxy response.
• Data.Status semantics: The claim that a vendor 4xx/5xx still returns Result: "Success" is a subtle footgun — verify this is accurate, since agents will rely on it.

Conclusion

Clean, well-structured documentation addition. The new run script section in reference-resolution.md is thorough, the resources.md update is correctly scoped, and the impl.md additions follow established patterns. One Low finding on placeholder casing inconsistency, and one Medium note on missing test coverage for the new workflow. No blocking issues — the PR is ready to merge.

---

[mukundbayyaram]

We need a skill / reference on how our new scripts look like and conventions so that the scripts agent is building is correct ?

[mukundbayyaram]

Can connectorKey be derived at SDK layer by looking at connection's cached response (assuming we do cache connection response) ? so that command looks a little cleaner ?

[mukundbayyaram]

Should this be part of bash ?

[mukundbayyaram]

This needs to be updated based on feedback in CLI PR ?