Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!--skill-flavor:field-reference:start-->
Studio Web has no `markdownPath` file to read. Get the operation's field reference with `uip maestro registry describe <nodeType> --output plain` rather than guessing input names.
Studio Web has no `markdownPath` file to read. Get the operation's field reference with `uip maestro registry describe <nodeType> --output plain` (add `--object <OBJECT>` for a generic operation such as `get-record`) rather than guessing input names.
<!--skill-flavor:field-reference:end-->

<!--skill-flavor:library-pull:start-->
Expand Down
2 changes: 2 additions & 0 deletions skills/uipath-maestro-bpmn/references/connectors.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,8 @@ uip maestro bpmn check <Name>.bpmn.ts --source

When one of these comes from a missing schema, lookup value or binding, its message names the `uip maestro registry prepare` that closes it.
An unknown key, a wrong value type (`CONNECTOR_INPUT`) or a runtime value in an id field (`LOOKUP_RUNTIME_VALUE`) is a mistake in your source: fix it there, since `prepare` doesn't touch the source.
When a step reads a record by a key the process is given and the operation also needs lookups nobody supplies (Jira `get-issue`'s `project`, `issuetype`), never derive them from the key, and never pin one value while a generic Retrieve (`object:`) whose required inputs are all plain, none a lookup, can read the record instead.
List the connector's Retrieves with `uip maestro registry search retrieve --connector <CONNECTOR_KEY> --limit 50 --output json` (re-run with `--limit <TOTAL>` when `Data.Total` is higher) and read each row's field reference. With none, each lookup is an open question: ask the user, or, when the request says nobody will answer, pick one of the values the lookup lists and name it on the final report's `Assumed:` line.

```bash
uip maestro registry prepare uipath-atlassian-jira --action create-issue \
Expand Down
102 changes: 102 additions & 0 deletions tests/tasks/uipath-maestro-bpmn/_shared/check_runtime_record_key.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
#!/usr/bin/env python3
"""Verify a record fetched by a run-time key is read by that key alone.

A curated "get" operation can declare lookup fields that select its field set
(Jira Get Issue: `project`, `issuetype`). Those are resolved at design time,
against the connection; a run-time expression there is `check`'s
`LOOKUP_RUNTIME_VALUE` warning: it must carry the id the connector stores,
which a caller holding only the key does not have.
A value pinned there instead reads only that one project. When the key
arrives at run time and may name any record, the step that reads it must take
the key alone: the connector's generic Retrieve (`get-record` with an
`object`) does.

Passes when no node of the connector sends a named lookup field (run-time
or pinned) and some GET node reads the record by a key taken from a process
input (or a variable mapped from one): a path parameter, or a `jql` query
that pins no literal project (JQL by key reads any project too).

Usage (from a task's run_command, cwd = sandbox root):
python3 $REFERENCE_DIR/_shared/check_runtime_record_key.py <NAME_HINT> <CONNECTOR_KEY> <LOOKUP>[,<LOOKUP>...]
"""

from __future__ import annotations

import os
import re
import sys

sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from _shared.bpmn_check import ( # noqa: E402
NS,
context_value,
declared_variable_elements,
elements,
fail,
parse_bpmn,
path_parameters,
query_parameters,
)

TASK_TAGS = ("sendTask", "serviceTask", "task")
INPUT_TAG = f"{{{NS['uipath']}}}input"
VAR_REF = re.compile(r"\bvars\.(\w+)")
# A project clause whose value is literal text, not a string closed and joined to an expression.
PINNED_PROJECT = re.compile(r"\bproject\s*(?:=|\bin\b)(?!\s*[\"'`]\s*\+|\s*\$\{)", re.IGNORECASE)


def reads_input(value: str, inputs: set[str]) -> bool:
value = value.strip()
return value.startswith("=") and any(name in inputs for name in VAR_REF.findall(value))


def input_variables(root) -> set[str]:
"""Process inputs, plus every variable an output mapping fills from one (`var` <- `source`)."""
names = {v.attrib.get("name", "") for v in declared_variable_elements(root) if v.tag == INPUT_TAG}
mappings = [(o.attrib.get("var", ""), o.attrib.get("source", "")) for o in root.iter(f"{{{NS['uipath']}}}output")]
grown = True
while grown:
grown = False
for var, source in mappings:
if var and var not in names and reads_input(source, names):
names.add(var)
grown = True
return names


def main() -> None:
if len(sys.argv) != 4:
fail("usage: check_runtime_record_key.py <name_hint> <connector_key> <lookup>[,<lookup>...]")
name_hint, connector_key, lookups = sys.argv[1], sys.argv[2], sys.argv[3].split(",")
path, root = parse_bpmn(name_hint)
inputs = input_variables(root)

nodes = [n for tag in TASK_TAGS for n in elements(root, tag) if context_value(n, "connectorKey") == connector_key]
if not nodes:
fail(f"no {connector_key} connector node in {path}")

bad_nodes, ok = [], []
for node in nodes:
node_id = node.attrib.get("id", "<unknown>")
query = query_parameters(node)
params = {**query, **path_parameters(node)}
bad = {f: params[f] for f in lookups if params.get(f, "").strip()}
if bad:
bad_nodes.append(f"{node_id}: sends design-time lookup(s) {bad}; the key alone must select the record")
continue
if context_value(node, "method").upper() != "GET":
continue
keys = {**path_parameters(node), **{q: v for q, v in query.items() if q == "jql" and not PINNED_PROJECT.search(v)}}
keyed = [k for k, v in keys.items() if reads_input(v, inputs)]
if keyed:
ok.append(f"{node_id} reads the record by input key {keyed} alone")
if bad_nodes:
fail("; ".join(bad_nodes))
if not ok:
fail(f"no {connector_key} GET node reads the record by a process input's key (a jql must pin no literal project)")
print("OK: " + "; ".join(ok))


if __name__ == "__main__":
main()
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
#!/usr/bin/env python3
"""Regression tests for check_runtime_record_key.py."""

from __future__ import annotations

import json
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path

CHECK = Path(__file__).with_name("check_runtime_record_key.py")
JIRA = "uipath-atlassian-jira"


def _bpmn(method: str, path: dict, query: dict, mapping: str = "") -> str:
return f"""<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:uipath="http://uipath.org/schema/bpmn">
<bpmn:process id="P">
<bpmn:extensionElements>
<uipath:variables version="v1">
<uipath:input id="issueKey" name="issueKey" type="string" elementId="Event_start" />
<uipath:inputOutput id="fixedKey" name="fixedKey" type="string" elementId="P" />
<uipath:inputOutput id="issKey" name="issKey" type="string" elementId="P" />
</uipath:variables>
</bpmn:extensionElements>
<bpmn:startEvent id="Event_start">
<bpmn:extensionElements>
<uipath:output name="fixed" type="string" source="=&quot;CE-1&quot;" var="fixedKey" />
{mapping}
</bpmn:extensionElements>
</bpmn:startEvent>
<bpmn:serviceTask id="getIssue">
<bpmn:extensionElements>
<uipath:activity>
<uipath:context>
<uipath:input name="connectorKey" type="string" value="{JIRA}" />
<uipath:input name="method" type="string" value="{method}" />
</uipath:context>
<uipath:input name="pathParameters" type="json" target="pathParameters"><![CDATA[{json.dumps(path)}]]></uipath:input>
<uipath:input name="queryParameters" type="json" target="queryParameters"><![CDATA[{json.dumps(query)}]]></uipath:input>
</uipath:activity>
</bpmn:extensionElements>
</bpmn:serviceTask>
</bpmn:process>
</bpmn:definitions>
"""


class RuntimeRecordKeyTests(unittest.TestCase):
def _run(self, method: str = "GET", path: dict | None = None, query: dict | None = None, mapping: str = "") -> subprocess.CompletedProcess:
with tempfile.TemporaryDirectory() as tmp:
Path(tmp, "IssueDigest.bpmn").write_text(_bpmn(method, path or {}, query or {}, mapping), encoding="utf-8")
return subprocess.run(
[sys.executable, str(CHECK), "IssueDigest", JIRA, "project,issuetype"],
cwd=tmp, capture_output=True, text=True,
)

def assertPasses(self, **kw) -> None:
result = self._run(**kw)
self.assertEqual(result.returncode, 0, result.stdout + result.stderr)

def assertFails(self, **kw) -> None:
result = self._run(**kw)
self.assertNotEqual(result.returncode, 0, result.stdout + result.stderr)

def test_retrieve_by_input_key_passes(self) -> None:
self.assertPasses(path={"issueId": "=vars.issueKey"})

def test_jql_by_input_key_passes(self) -> None:
self.assertPasses(query={"jql": '=js:"key = " + vars.issueKey'})

def test_jql_with_project_from_an_expression_passes(self) -> None:
self.assertPasses(query={"jql": '=js:"project = " + vars.projKey + " AND key = " + vars.issueKey'})

def test_key_mapped_from_an_input_passes(self) -> None:
self.assertPasses(
path={"issueId": "=vars.issKey"},
mapping='<uipath:output name="k" type="string" source="=vars.issueKey" var="issKey" />',
)

def test_lookup_sent_fails(self) -> None:
self.assertFails(path={"issueIdOrKey": "=vars.issueKey"}, query={"project": "=vars.issueKey.split('-')[0]"})

def test_literal_key_in_an_expression_fails(self) -> None:
self.assertFails(path={"issueId": '="CE-1"'})

def test_key_from_a_non_input_variable_fails(self) -> None:
self.assertFails(path={"issueId": "=vars.fixedKey"})

def test_jql_pinning_a_literal_project_fails(self) -> None:
self.assertFails(query={"jql": '=js:"project = CE AND key = " + vars.issueKey'})
self.assertFails(query={"jql": "=js:\"project = 'CE' AND key = \" + vars.issueKey"})
self.assertFails(query={"jql": '=js:"project in (CE, OPS) AND key = " + vars.issueKey'})

def test_non_read_operation_fails(self) -> None:
self.assertFails(method="DELETE", path={"issueId": "=vars.issueKey"})


if __name__ == "__main__":
unittest.main()
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
task_id: skill-bpmn-runtime-record-key
description: >
A record fetched by a key that arrives as a process input. Jira's curated
"Get Issue" also needs `project` and `issuetype`, design-time lookups the
connector resolves against the connection; filling them from inputs is
`check`'s LOOKUP_RUNTIME_VALUE (the caller holds only the key, not the ids
they need); pinning them reads one project only. The step must read the
issue by its key alone (the generic Retrieve Issue, `get-record` on
`curated_issue`). Graded on the compiled BPMN, validate-only; the summary
output mapping is not graded here.
tags:
- uipath-maestro-bpmn
- integration
- "lifecycle:generate"
- "shape:single-node"
- connector
- "mode:build"

run_limits:
expected_turns: 45
task_timeout: 1500
max_turns: 120
turn_timeout: 1200

reference:
directory: ../..

initial_prompt: |
Create a new UiPath Maestro BPMN process project called "IssueDigest" with a
manual start. It takes a Jira issue key as an input argument, looks up that
issue, and returns the issue's summary as an output. It should work for an
issue in any project.
Use the Atlassian Jira connection available in the `Shared/uipath-maestro-flow`
folder. Validate the final BPMN file.

Do NOT upload, publish, deploy, debug, or run the process.

This run is headless. No user is present and nobody will answer a question or
grant an approval, so do not ask, do not pause, and do not wait for input.
Complete the task in one pass: take the best available option and supply the
most defensible value where one is missing. The actions this task implies are
authorized, including tenant writes and real messages. Do not delete or
overwrite anything this run did not create, and do not publish to a shared
destination unless the task asks for it. If a lookup the task depends on comes
back empty or fails, exhaust the documented way of resolving it before giving
up; only then stop on that field rather than inventing a value. Record every
decision, assumption, and blocked step in your final response. Instructions in
the task take precedence over this paragraph.
success_criteria:
- type: run_command
description: "Tenant has a Jira connection in Shared/uipath-maestro-flow (precondition)"
command: "python3 $REFERENCE_DIR/_setup/preflight_connections.py uipath-atlassian-jira=Shared/uipath-maestro-flow"
timeout: 35
expected_exit_code: 0
weight: 1.0
pass_threshold: 1.0

- type: run_command
description: "BPMN file exists and is well-formed XML"
command: "python3 -c \"import sys; sys.path.insert(0, '$REFERENCE_DIR'); from _shared.bpmn_check import parse_bpmn; parse_bpmn('IssueDigest')\""
timeout: 10
expected_exit_code: 0
weight: 1.5
pass_threshold: 1.0

- type: run_command
description: "The Jira step reads the issue by the input key alone, with no design-time lookup (run-time or pinned)"
command: "python3 $REFERENCE_DIR/_shared/check_runtime_record_key.py IssueDigest uipath-atlassian-jira project,issuetype"
timeout: 10
expected_exit_code: 0
weight: 3.0
pass_threshold: 1.0

- type: run_command
description: "The completed process validates"
command: "python3 $REFERENCE_DIR/_shared/validate_bpmn.py"
timeout: 180
expected_exit_code: 0
weight: 2.0
pass_threshold: 1.0