Repository navigation
Planner: loops, rethrow-only handlers and passed-down values worded by their result; no application handle across a library call - #4690
Conversation
|
Claude finished @vlad-coteanu-uipath's task in 53s —— View job PR Review: #4690
SummaryThis PR adds three migration rules to Change-by-Change Review1.
|
| Area | Status | Notes |
|---|---|---|
| Frontmatter | OK | Untouched |
| E2E Tests | OK | No new skill; optional coverage noted above |
| Skill Body | OK | SKILL.md untouched |
| References & Assets | OK | Low: option naming, wording on line 38 |
| Repo Hygiene | OK | Two skills touched; changes are related |
Issues for Manual Review
- Check that the Application Card's Open option, set to open only when no instance exists, really covers every source "is it running / is the window open / is the session attached" test. In particular,
ByInstancevs window-level attach may differ when a second instance should be launched on purpose. - Check the Do While rule against sources where the pre-loop step is not quite the same as the body, for example a priming read with different arguments. The current wording ("no step is written twice to run once before the loop") applies only to identical steps; a different priming step should stay as written.
Conclusion
Approve with minor suggestions. The rules are correct and tightly worded, and they close real over-translation patterns. The optional follow-ups are the enum and property names, the "elsewhere" wording, and an anti-pattern entry for the Try/Catch attach.
2900c9f to
ca7a3b4
Compare
…lues worded by their result; no application handle crosses a library call
ca7a3b4 to
7fafa7d
Compare
danmunteanu1
left a comment
There was a problem hiding this comment.
🟡 Commented · 2 blockers · 2 non-blockers
The rethrow rule drops handling a broader catch depends on, and the handle rule contradicts uipath-rpa until #4551 merges.
What
- Genome format: a loop that only computes, selects or tests is written as its result; a catch that only rethrows gets no Error Handling entry; a value passed down only to reach its reader is read by that reader.
- Both copies of the attached-application rule (planner and builder § Interface): no application handle crosses a library call.
Overall findings
- 🔴 Blocker · Merge order. On
main,uipath-rpareferences/library-authoring-guide.mdrule 5 is "Return application handles": a public workflow outputs the window or browser, and downstream workflows take it as an input. Merged alone, this PR has the genome and the builder's reading guide say the opposite, and a library build reads both. Fix: merge with #4551 or after it, and say so under Related PRs.
Outside this PR
- "Run skill smoke tests" is red:
skill-planner-genome-from-sddscored 0.60 (16/17 tasks, under the 95% gate) because the run wrote a process genome where the task expects a component genome. The same task fails with the same checker output on #4692 and #4740, which do not carry this diff.
Behaviour: the same synthetic export was extracted with the base and with this PR merged with #4559 and #4551 (one run per side, same model). On this tree the genome writes the three loops as their results, gives the rethrow-only handler no Error Handling entry, has the submitting step read the machine name itself, and its library passes no browser handle. On the base the loops are per row, the handler is "caught and rethrown unchanged", the machine name is an input of three steps, and a Browser handle argument crosses every library call. The counter-case in the blocker below wasn't in the export.
tl;dr Keep the rethrow-only catch ahead of a broader catch as an entry, and merge with #4551; the other two are wording.
| ### Error Handling | ||
| Same step-associated layout as Business Rules, plus `### Global`. Behavioural wording: "Retries 3× on timeout, then routes the item to the exception queue" — never "RetryScope with NumberOfRetries=3". An entry states the failure, the outcome and the level that handles it; a failure that every UI step shares ("expected element not found: screenshot, stop naming the step") is written once under `### Global`, not repeated per step, and a step entry exists only where that step's handling differs. A Workflow substep's "confirm …" is a post-condition of the action before it, not a separate check (execution builds it as that action's verification). | ||
|
|
||
| **A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does. |
There was a problem hiding this comment.
🔴 Blocker · A rethrow-only catch ahead of a broader catch is handling: it keeps that failure from the broader handler.
Try raises a business-rule exception; Catch BusinessRuleException → Rethrow; Catch Exception → log and retry. Without the first catch the second one catches the failure and retries it; with it, the failure goes to the caller unretried. Run on System.Activities TryCatch: with only the general catch, its handler ran; with a rethrow-only ArgumentException catch ahead of it, the ArgumentException escaped to the caller. Under this rule the genome writes no entry for that catch, and the build retries business-rule failures.
Fix:
| **A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does. | |
| **A handler that only rethrows is no handling.** A catch whose only action is to raise the failure it caught again, unchanged, handles nothing: the failure goes on as if nothing had caught it, and no Error Handling entry describes the catch. A rethrow-only catch ahead of a broader catch of the same block that does handle is the exception: it keeps that failure from the broader handling, and its entry says so ("a business-rule failure is not retried"). A handler that logs, cleans up, retries, changes the failure or chooses between outcomes before it rethrows is an entry, stated by what it does. |
| **Library components** (a project other components consume as a package) carry, instead of the three bullets, one table per public workflow — never one table shared by several, which hides each workflow's types and directions: `Argument | Direction | Type | Description`. The Type is the one the rebuild gives the argument — a flag is a Boolean and a count a number, whatever text the source carried them in — and the description states the default and the value format (what a flag means, how a date is rendered, which side quotes a value), plus the conventions consumers rely on (naming, defaults, what a failed final check does). This table is the contract consumers are authored against before the library packs; every detail it omits becomes a question between two build groups. A workflow over the analyzer's argument cap (20) carries its optional switches and values in one options object — one In argument with its own table (`Field | Type | Default | Description`). | ||
|
|
||
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, an attached application or handle, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application crosses as the application handle the owning skill's public-workflow contract has workflows return and accept. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). | ||
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: a library hands no application handle out for a caller to pass to another call, and each activity gets the application through its own Use Application/Browser card where it uses it. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). |
There was a problem hiding this comment.
🔸 Non-blocker · How a workflow gets its application is uipath-rpa's public-workflow contract, which #4551 words as this line does ("each activity gets the application through its own Use Application/Browser card"). Here it reads as one card per activity. Name the contract, as the base line did, and keep what the genome writes: no handle argument.
Fix: (the builder copy, genome-reading-guide.md:52, changes with it)
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: a library hands no application handle out for a caller to pass to another call, and each activity gets the application through its own Use Application/Browser card where it uses it. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). | |
| **State kept between calls.** A library workflow starts each call from its declared defaults, and a library project holds no global variables or constants, so state the source keeps from one call of its actions to the next — a value one action stores and another reads, its own instance of another component it calls — lives in the consumer and crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field does outlive a call, but as one value for every caller in the job and none inside an isolated invoke, and no Interface shows it, so it holds none of this state. An attached application is no state that crosses a call: the owning skill's public-workflow contract has each workflow open or attach to the application itself, so no argument carries a window or browser handle. The conventions name the holder and the work the source ran on its own — set-up before the first call, a close-down when the run ends, after a failure too — each a public workflow the holder calls at that point. The holder follows the source's instances, as the source guide's § Call Graph Rules state them: an instance per caller is held by each caller — a process in its entry workflow for its whole run, passed to the workflows that call the library, and a calling library in its own Interface, since it holds nothing either; one instance per run is held by the run's entry workflow and passed to every caller, calling libraries included. A stored value no action changes is no state: it is a fact or a Configuration Question (§ Configuration Questions). |
| **Library components** carry one table per public workflow, `Argument | Direction | Type | Description`: the type the rebuild gives the argument, its default and value format, and the conventions consumers rely on. Consumers are written against this table before the library packs. A workflow over the analyzer's argument cap (20) takes its optional switches and values in one options object — one In argument with its own table (`Field | Type | Default | Description`). | ||
|
|
||
| **State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, an attached application, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses as the application handle the owning skill's public-workflow contract has workflows return and accept. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller. | ||
| **State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: a library hands no application handle out, and each activity gets the application through its own Use Application/Browser card where it uses it. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller. |
There was a problem hiding this comment.
🔸 Non-blocker · Same change as the planner copy (genome-format-guide.md:75): the two copies change together.
Fix:
| **State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: a library hands no application handle out, and each activity gets the application through its own Use Application/Browser card where it uses it. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller. | |
| **State kept between calls lives in the consumer.** A library workflow starts each call from its declared defaults and a library project holds no global variables or constants, so state one action stores and another reads (a value, its own instance of another component) crosses each call as an argument: Out from the workflow that produces it, In to each that reads it, In/Out where one changes it. A coded library's static field holds none of it. An attached application crosses no call: the owning skill's public-workflow contract has each workflow open or attach to the application itself, so no argument carries a window or browser handle. An instance per caller is held by each caller; one instance per run is held by the run's entry workflow and passed to every caller. |
|
|
||
| **A source's workaround for its own platform is not behaviour.** A clipboard copy between two ranges, a temporary file written beside the input, a rename around a path the source's script cannot open, a user setting switched to steer a file format: the step states the result the workaround produced, and the Source Map names the workaround — unless a later step reads what it leaves behind, which makes it data. | ||
|
|
||
| **A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step. |
There was a problem hiding this comment.
🔸 Non-blocker · None of the three forms fits a loop that adds each row's amount to a total or counts rows, a common computing loop.
Fix:
| **A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step. | |
| **A loop that only computes, selects or tests is its result.** A loop whose body only sets a field of each row, adds each row's value to a total or count, copies the rows a condition passes into another table, or sets a flag when a row passes is written as what it produces: "{field} of every row is …", "the total of {field} over the rows where …", "the rows of {table} where …", "whether {table} holds a row where …". The loop is a step of its own only when its body acts on an application, a file or a queue, or calls another step. |
Why
Extracted genomes described some source logic by how it works instead of what it does, such as a loop step by step or a catch block that only re-raises. The build then copied those mechanics. Genomes also told libraries to pass the application's window from call to call, which the rebuilt libraries no longer do.
This PR holds the
uipath-plannerchanges. The other skills' changes from the same migrations are in #4559 (uipath-genome) and #4551 (uipath-rpa).How the genome describes source logic (
genome-format-guide.md)A loop that only computes, selects or tests is described by its result. If a loop only fills a field on every row, copies the matching rows into another table, or sets a flag when a row matches, the genome says what it produces:
The build then picks the right activity, such as a filter or a lookup. A loop stays a step only when its body does real work: it acts on an application, a file or a queue, or calls another step.
(§ Workflow)
A catch that only rethrows is not error handling. A handler that catches a failure and immediately raises the same failure, unchanged, does nothing, so the genome writes no Error Handling entry for it; an entry would lead the build to add an empty Try/Catch. A handler that logs, cleans up, retries, changes the failure or decides something before rethrowing is described by what it does.
(§ Error Handling)
A value passed down only to reach the place that uses it is read there. Sources often read the machine name or user name once at the start and pass it through three workflows to the one step that needs it. Such a value is the same wherever it is read, so the genome lets that step read it itself instead of adding an argument to every workflow on the way. A value the caller computes or changes, or one that must stay fixed for the whole run (the run's start time), is passed as an argument.
(§ Interface)
No application handle crosses a library call. An attached application is not state a library passes between calls. Each activity gets the application through its own card where it uses it, and nothing is handed back and forth.
(§ Interface, state kept between calls)
The builder keeps a copy of that last rule (
uipath-genomegenome-reading-guide.md§ Interface). The repo's rules require both copies to change in the same PR, so that oneuipath-genomeline is here, not in #4559.Related PRs
uipath-genome) builds the attach and card changes.uipath-rpa) states the same handle rule for library authors.Checks
skills:testwas not run locally (nonode_moduleson this machine); CI runs it.