# Transactional Shape Guide

Content rules for a genome's Transactional Shape section, however the genome is produced. The section's place among the others, its stub and the rules every section follows: [genome-format-guide.md](genome-format-guide.md).

Whether the automation iterates over **units of work** — items that succeed, fail, are retried and are tracked independently of one another — and, when it does, how the work is handled today and how it could be divided at build. UiPath realises per-item work with the **REFramework** (Robotic Enterprise Framework): a state machine that opens the applications once, takes one item at a time, classifies each item's outcome, retries system failures, records every item's status, closes the applications at the end, and reads its settings from a configuration workbook plus Orchestrator assets. An automation can hold several such streams — a **flow** is one kind of item handed from the steps or component that produce it to the steps or component that consume it, independently of any other item (the children an item expands into are levels of that item, not a flow of their own — rule 12); a process genome may have one flow between components 1 and 2, another between 2 and 3, and an independent one between 5 and 6. This section **describes**, per flow: the unit of work and the other viable granularities, how the process produces and consumes items as it is (or as described), where the items and their state live, which coordination the source used, and — for the unit of work and for every alternative unit — which ways of splitting the roles are possible, with what each requires and changes. It **asserts no split, no store, no template and no unit** — those are configuration answers at execution ([transactional-execution-guide.md § Split questions](transactional-execution-guide.md)). The behaviour written in Business Rules, Error Handling and Acceptance Criteria is owed whatever the user chooses.

## Layout

Layout when at least one unit of work exists — one `### Flow N` block per flow, numbered in the order the items first arise, even when there is only one:

```markdown
**Flows:** Flow 1 — {unit}: {producer steps or component} → {consumer steps or component} (Handoffs row {n}); Flow 2 — {unit}: … ; chains: {component x} consumes Flow 1 and produces Flow 2; independent: Flow 3. *(process genome and standalone component; a single flow: "Flow 1 — {unit}: steps {a–b} → steps {c–d}")*

### Flow 1 — {unit of work}: {producer} → {consumer}

**Unit of work:** one {item}; reference {field(s) that identify it and prevent duplicates}; fields as in {Handoffs row N / Interface}; {volume and cadence}; chosen because {items fail, retry and are reported independently at this level; the reference exists; the retry cost is acceptable}.
**Alternative units of work:** one {other item} — fits when {condition}; one {third item} — fits when {condition}. *(every viable granularity, or "none")*

**As-is** — how the process handles the units today:

| Aspect | As-is |
|---|---|
| Produced by | {steps — and, in a process genome, the component — that read the source(s) and create items; how often; one source or several; whether the population is guarded: lock, ledger, "once per date"} |
| Consumed by | {steps / component that take items; one robot or several; how a robot picks its items — any, by parent, by kind; in which order} |
| Item store | {framework work queue, Orchestrator queue, database table, in-memory list, folder}; per-item state kept as {status text, tags, data fields, output} |
| Coordination | {parent items, ledgers, locks, tag joins between item levels} and what each is for — described, not prescribed; "none" when absent |
| Item kinds | {one kind, or several kinds routed inside the consumer, with what differs per kind — payload, work, outcomes} |
| Step groups | once per run: steps {n, m}; per item: steps {p–q}; at the end: steps {r} |

| Outcome | When | Effect |
|---|---|---|
| Success | every per-item step completed | item recorded as done with {result} |
| Business exception | Step {N} rules: {rule names} | no retry; item recorded with the reason; run continues |
| System exception | every other failure — Step {N} handlers: {names} | applications reopened, item retried {n}×, then recorded as failed with the reason; run stops after {m} consecutive |
| Postponed *(only when the source or the description puts items back for later)* | Step {N} rule | {postpone time and limit; past the limit a business exception} |

**Split options** — for the unit of work and for each alternative unit of work, the ways the roles can be divided at build, each named by its letter (rule 3 defines A, B and C) with what it requires and what it changes against as-is in this flow's terms; the number of runners is a deployment setting of each resulting process, never an option; none is asserted:

| Unit of work | Option | Requires | Changes against as-is |
|---|---|---|---|
| {unit} | A | {what this flow needs for the roles to share one job — or "excluded: {the fact that rules it out}"} | {what changes here: projects and schedules, where per-item state is visible, retry granularity, what the end-of-parent work needs} |
| {unit} | B | {…} | {…} |
| {unit} | C | {…; the once-guard this flow's population uses} | {…} |
| {alternative unit} | A | … | {…} |
| {alternative unit} | B | … | {…} |
| {alternative unit} | C | … | {…} |

When the flow's producer and consumer are **different genome components**, B is their as-is, A means the two components' roles in one process and C the two components' roles in one process that keeps the queue between them: the executor materialises one project for both, records it in the completion report, and leaves the Components table unchanged; each Requires cell names what the merge needs (one schedule, one machine and account set for both; under C also the once-guard).

**Evidence:** {facts that bear on the choice, no verdict — several robots run the same process today; the folder source is independent of the export; item kind X needs application Y that kind Z does not; …}
**Configuration:** settings — questions {a, b}; constants — questions {c, d}; assets — every Credential and Text row of Platform Dependencies.
**Traceability:** {what is recorded per item today and where; the upstream reference the item carries when it is produced by the consumer of another flow; screenshot on system exception; run summary}.

### Flow 2 — …
```

Layout in a component genome inside a process — one block per flow the component takes part in, the stub when it takes part in none:

```markdown
### Flow {N} — {unit of work}: {producer} → {consumer}

**Role:** {producer | consumer | consumer of Flow {M} and producer of this flow (chain)} — {one sentence: what this component does with the items}.
{the As-is rows that concern the role (rule 9), the outcomes table and counts for a consumer, its configuration split and traceability}
Split options: per the process genome, Flow {N}.
```

## Rules

1. **One test decides applicability: a unit of work exists — per flow.** Each flow is tested on its own; the section carries one block per flow that passes and the stub only when none does. A unit of work is a discrete item that can succeed, fail, be retried and be tracked independently of the others, and the automation iterates over such items. Sources of items: an Orchestrator queue, a mailbox, a folder of files, the rows of a spreadsheet or table, a work list on a screen, a page of API results, a database work table. **No unit of work:** a run that succeeds or fails as one (a poll, a report, a single posting); one item's work started per item by a caller — the caller owns the lifecycle and is the candidate consumer; an attended automation that waits on its user between items. A trigger that starts one job which then takes items until the source is empty **is** a consumer; a trigger configured to start one job per item is not — say which the source or description implies. **Component types that are never consumers** (they may still be producers): a library, a test-case group, a Flow, BPMN process or Case — as a coordinator or working its items itself, its per-item lifecycle is its own runtime's — an agent, an API workflow, a coded app, a function. Per-item work such a component does itself is written in its Workflow and Error Handling, and the section carries the stub. Volume is never the criterion: fifteen independent items a day is a shape, ten thousand rows written into one file is not. When items nest — a folder of files each holding rows, a mailbox of mails each carrying several documents, a requisition with its lines — the unit of work is the level at which one item fails, retries and is reported on its own, has a natural reference, and whose retry cost is acceptable; the levels above or below it are Alternative units of work (rule 8).
2. **Roles are described, never assigned.** "Produced by" and "Consumed by" name the steps — and, in a process genome, the components — that create and take items today. A producer may be any component type; a consumer is an RPA process (`uipath-rpa`), the only component type the framework builds; the component types rule 1 lists are never consumers. The words `dispatcher` and `performer` are execution vocabulary: they name the projects a chosen split materialises and appear in the Split options table and in the completion report — never in the Components table's Type cell, which reads `RPA process`, and never as a claim about what the rebuild is. A component genome inside a process states its as-is role per flow in one sentence (its `Role:` line) and carries the As-is rows that concern it; a component that consumes one flow and produces the next says so in both blocks.
3. **The item store follows the split.** The As-is row says where items and their state live today; each option needs the store this rule gives it. This rule is the options' one definition: the Split options table names an option by its letter and writes only what this flow requires and changes. **Option A keeps the items in the job**: one job takes its items end-to-end on one runner — the REFramework's direct mode, or a plain loop over an in-process list — and needs no Orchestrator queue. **Options B and C keep them in an Orchestrator queue**, which items need whenever they are shared across jobs — several runners, retries or postponements across runs, another process reading them after the run — with exactly **one queue per unit of work**, which any number of producers and consumers, and any number of runners of each, share. **C keeps both roles in one process**: one entry point and one trigger, every job produces behind a once-guard and then consumes, and every runner runs the same process — the shape of a source that runs one process on several robots and guards its population with a lock or a ledger. **B separates them** into processes with their own triggers, which the roles need when their cadences, machines, credentials or owners differ; a producer entry point with its own trigger is a producer process, so two entry points of one project are B, never C. A source's own coordination stores — a parent queue, a populate ledger, a lock, a tag join — are facts of the Coordination row; they are carried into a build only when the chosen split still needs them and the user keeps them ([transactional-execution-guide.md § Split questions](transactional-execution-guide.md)). One standing case: a source that keeps its work list in a **database the process owns** (hand-out per runner, per-item status written back, operators reading the tables) already has a shared store; the As-is says so, the Requires and Changes cells of B and C can keep that database as the store, and execution offers it beside an Orchestrator queue in the store question rather than imposing a queue.
4. **Outcomes classify the rules and handlers already written; they never restate them.** Three rows always, a fourth only under the condition at the end of this rule: **Success**; **Business exception** — the Business Rules that reject an item (missing or wrong data, a rule the item fails): no retry, the item is recorded with the reason, the run continues; **System exception** — every other failure (application unavailable, element not found, timeout): the applications are closed and reopened, the item is retried the configured number of times, then recorded as failed with the reason, and the run stops after the configured number of consecutive system exceptions. Name rules and handlers by step ("Step 7 rules: duplicate, no open PO"); never copy their text. A source's own per-item results — approved, rejected, skipped, routed to a person — are not outcome rows: the result of a completed item is the Success row, and every result a rule decides (a rejection, a skip, a missing attachment) is a Business exception naming that rule by step. When extracted, this row states the source's own recovery and its two counts, 0 and 1 included, never the framework's defaults ([genome-format-guide.md § Configuration Questions](genome-format-guide.md)): a source that never retries an item and ends the run at its first failure reads "not retried (0×); the run stops after 1". An authored genome asks the counts as Configuration Questions `(constant; default: retried 2×; stop after 3 consecutive)`. A fourth row, **Postponed**, exists only when the source or the description puts an item back for a later attempt without counting it as a failure — the record it targets does not exist yet, a cut-off time has passed. Its When names the rule by step; its Effect states the postpone time and the limit: in a queue store the item returns to the queue with a postpone time and its attempt count untouched, in an in-process store it is written back as pending; past the limit it is a business exception. Postponement never replaces the system-exception retry, and a run that waits between polls is not postponing items.
5. **Once per run, per item, at the end.** Every Workflow step of a consumer belongs to exactly one group, named by step number in the As-is Step groups row: once per run (open and sign in to the applications, read configuration and reference data, read the source when the store is in-process and the source is complete at the start), per item (the business steps), at the end (close the applications, write the summary or report). A step that fits no group is missing from Workflow, not from this section. A producer's steps are never in the consumer's once-per-run group: they are the Produced by row's own steps. In a chain the steps that create the downstream flow's items are **per-item** steps of the upstream flow's consumer, named in both flows' blocks (rule 13).
6. **Configuration: split, do not repeat.** The settings and constants are the ones [genome-format-guide.md § Configuration Questions](genome-format-guide.md) marks; this section names which apply to the flow's consumer and states that the Credential and Text assets in Platform Dependencies are read at start. A value the genome states instead of asking stays where it acts and is not listed. A secret is never a configuration value ([genome-format-guide.md § Platform Dependencies](genome-format-guide.md)).
7. **Traceability: what is recorded per item, and where.** The reference, the outcome and its reason — as the queue item's status, progress and output when the store is a queue; as a write-back column, a result file or a reporting queue when it is not; a screenshot on every system exception; one run summary (items taken, succeeded, business exceptions, failed). These are what a reporting step or a digest reads; a reporting component reads them, never the consumer's log.
8. **Split options and evidence replace any verdict.** Options A, B and C are listed whenever a unit of work exists — once for the unit of work and once for every Alternative unit of work — each with its requirements and its changes against as-is; an option the evidence excludes is still listed, with the reason in its Requires cell ("excluded: several robots work the items and postponements cross days"). Two things are never options: **the number of runners**, a deployment setting of each resulting process (A runs on one runner per job; several runners mean B or C), and **several producers or several consumers**, sub-choices of B the execution asks when the As-is shows several independent sources or several item kinds. A Requires or Changes cell states facts in this automation's terms — projects and schedules to operate, parallelism, retry granularity, where per-item state is visible, what the end-of-parent work needs (rule 11) — and never ranks the options ("recommended", "best", "simplest"); what an option is, and the trade-offs that hold for any automation, are rule 3's and this table's and are not written per flow. The Evidence line carries facts only — robot count, schedules, sources, applications per item kind, whether items survive a run today. The **Alternative units of work** line lists every viable granularity with the condition under which it fits, never a choice. Every unit the line lists gets its own A, B and C rows in Split options — also one whose condition the as-is does not meet today, whose Requires cells then say what would have to change; a parent level's condition never asks that the parent be accepted or rejected as a whole, since its children's outcomes stay recorded per child inside the parent's transaction ([transactional-execution-guide.md § REFramework at build](transactional-execution-guide.md), alternative unit of work); a mode or a project split is never an alternative unit — those are Split options. Derivation table (authoring and extraction):

   | Signal in the source or the description | Split options it enables or excludes |
   |---|---|
   | One job works items end-to-end, nothing else touches them, a rerun is harmless | A viable |
   | Several robots run the same process on the same items; an item must survive a run failure; a postponement or retry crosses runs | A excluded; B and C viable — C while both roles share cadence, machines, credentials and owner |
   | Another process reads the items after the run (a report, an audit, an operator view) | A excluded unless the job writes a per-item record the reader can use; B and C keep the items where the reader finds them |
   | Population and consumption have different natural cadences (an export published once a day, files dropped all day), or need different machines, credentials or owners | B favoured; C excluded |
   | Several independent sources feed the items | B with one producer per source, or A or C reading every source in its producer steps |
   | Item kinds need different applications or machines, or different attempt limits or SLAs | B with one consumer per kind and one queue per kind; otherwise one consumer with a route step |
   | The source guards population with a lock or a ledger | evidence that several identical jobs ran the process, which is C's shape; C keeps a once-guard in its place (a unique reference the queue refuses twice, or the kept ledger); B with one producer job removes the need for it |
   | Work happens once per parent when its children are final (a summary, a report, a close-out per file or mail) | at the child unit: every option names how that work learns its children are final (rule 11); at the parent unit: it is the transaction's last step |

9. **Levels.** The process genome carries the `Flows:` line and one full block per flow: unit of work and alternatives, the As-is across the components the flow joins, outcomes, split options per unit of work, evidence, configuration, traceability. A component genome inside a process carries one block per flow it takes part in (layout above): its `Role:` line, the As-is rows that concern the role (a producer: source, reference rule, what happens to the source item once it is queued; a consumer: its step groups, its outcomes table and counts, its configuration split and traceability), and the line `Split options: per the process genome, Flow N.`; a component in no flow carries the stub with the reason (a library, a coordinator, one item's work started per item by component N). A standalone component genome carries the `Flows:` line and every block in full for its one project. **A flow with one side outside the genome** — items handed to a queue another process works, or taken from one another process fills — keeps its block with the unit of work, the As-is rows of the side this genome holds, its outcomes when this genome is the flow's consumer, and traceability; the line `Split options: none — the consumer is outside this genome: {what takes the items}.` (or `the producer is outside this genome: {what fills the store}`) replaces the Split options table, since execution cannot divide roles it does not build.
10. **Extracted genomes.** A source built on a framework fills the As-is table from the framework's configuration and files (the framework's source guide says which file feeds which row); the framework's plumbing — state transitions, retry counters, status updates, screenshots on exception — is not workflow steps and is listed in the Source Map as a `Framework files` row. A source with a queue producer or consumer, or a per-item loop, and no framework is a candidate when the step that works the items becomes an RPA process: write the unit of work and its alternatives, the As-is, and the Split options for each unit, marking `*[Inferred]*` what the source does not show. A source whose items are worked by a component type rule 1 excludes carries the stub line, nothing more. The As-is is the source's truth — its coordination stores, its item levels, its robot count — exactly as they are.
11. **Several levels of items are one unit of work and one description.** A source whose items expand into children (a record into its line items, a file into its rows, a mail into its attachments, a report into the work list built from it and that list into its rows) has one candidate level per generation, whether the parent is tracked in its own queue or status or only exists as the file or store the children came from — and whatever store (a staging folder, a work list) sits between the generations; rule 1 picks the unit of work and the other level is an Alternative unit of work. The As-is describes both levels as they are — Coordination row: "one parent item per reference, children joined by the parent key, one robot works one parent's children in sequence, the parent is completed when its children are final". Whether a level is folded at build — children produced up front, several robots on one parent's children, the parent's fate derived from its children instead of kept as an item — is an execution decision recorded in the completion report ([execution-guide.md § 3.3](execution-guide.md)), never a claim of this section. What the section does state is the consequence per level, in the Split options rows' Requires and Changes cells: at the child level, how the parent's end-of-parent work learns that its children are final — a parent item on its own queue postponed until they are, a reporting step over the children's records with a guard against sending twice, the consumer that finishes the last child — and what that costs with several runners, under B and C alike; at the parent level, that this work is the transaction's last step, that the children are worked inside the transaction, and what a parent retry redoes (only the unfinished children, when the children's state survives the retry).
12. **Flows come from the handoffs.** Every edge that hands items one by one from producer to consumer is a candidate flow: a queue item between components, a file drop, a database work table, a mailbox, a work-list workbook — the Handoffs row (or its intra-component row, [genome-format-guide.md § Handoffs](genome-format-guide.md)) names it, and the `Flows:` line cites that row. A call made once per item — a start job, an API workflow or agent invoked per item, a subflow — hands no item to a store: the called component does that item's work inside the caller's transaction. It is a step of the caller's flow, never a flow of its own (rule 1). Two edges carrying the same kind of item between the same roles are one flow; items handed on a second time (component 2 → 3 after 1 → 2) are a second flow when the second consumer takes items the first consumer produces, even when the payload is similar. A flow keeps its own unit of work, alternatives, store, outcomes, split options and evidence; two flows never share a queue, since each unit of work has its own (rule 3). Independent flows (5 → 6 beside 1 → 2 → 3) are separate blocks the `Flows:` line lists as independent. **A store between two phases starts a flow of its own only when both tests hold — otherwise the items it holds are a level of the upstream item, and the two phases are producer and consumer steps of one flow (rule 11):** (a) **independence** — a downstream item does not belong to one upstream item whose end-of-parent work waits on it (a summary, a close-out, a status or notification per parent) and is not the upstream item itself carried to its next stage, unless a person decides between the stages (a review, an approval): the upstream item then ends when it is handed to that person, and the decision starts a downstream item of its own, even when it is the same record; (b) **separation** — the two phases differ in run, cadence, robot, account or owner, or another producer or consumer touches the store. A folder or work list that the same job fills and then empties, where each upstream item turns into its own downstream items (a mail into its attachments, a report into its work list, the list into its rows), is one flow with nested levels — never a chain. A second flow inside one component exists only when both tests hold (a drop folder filled all day by one entry point and drained by another on its own schedule).
13. **Chains.** When the consumer of Flow N produces the items of Flow N+1 — items of their own by rule 12's two tests, not the children of the Flow N item — the downstream item carries the upstream reference, so traceability follows an item end-to-end, and who creates it decides the rest. **The automation creates it:** creating it is a per-item step of the upstream item, and its failure is a system exception of the upstream item — retried with it, so the downstream reference must make a second creation a duplicate the store refuses (derive it from the upstream reference); the upstream item succeeds only when its downstream item exists. **A person creates it** (the decision of rule 12, test (a)): the upstream item succeeds when it is handed to that person, and the downstream reference is the upstream reference itself. Each flow's Split options are listed on their own, and each flow's Changes cells state what taking option A or C for two adjacent flows changes (their components' roles in one process; under A the intermediate store gone only when the downstream work can run inside the upstream transaction, under C the intermediate queue kept). Folding a chain into one flow — the downstream work done inside the upstream item — is an Alternative unit of work of the upstream flow, listed with its fit condition when it fits.
