2.3 Transaction Types & The Dispatcher vs. Performer Architecture

2.3 Transaction Types & The Dispatcher vs. Performer Architecture

Core Concept: An enterprise automation process is fundamentally defined by how it structures and processes its data. In UiPath REFramework, a Transaction Item represents an atomic unit of business data processed independently from other records. By decoupling the extraction of raw records from their subsequent processing through the Dispatcher (Producer) and Performer (Consumer) architectural patterns, organizations achieve horizontal scalability, robust fault isolation, and automated queue load balancing.

When beginner RPA developers build automations, they frequently bundle data gathering, business calculation, and reporting into a single monolithic script. If the process encounters 1,000 Excel rows and crashes on row 742, restarting the robot re-reads the entire file, risking duplicate transactions and lost work. The Dispatcher-Performer architecture solves this problem by segregating the data ingestion lifecycle from the execution lifecycle using UiPath Orchestrator Queues.

---

1. Transaction Item Types in REFramework

In REFramework, the global variable TransactionItem defines the data contract for each execution cycle. Although the default template specifies UiPath.Core.QueueItem, developers can modify the data type to match specific business requirements:

Supported TransactionItem Data Types in REFramework:
├── UiPath.Core.QueueItem       --> Default enterprise model; backed by Orchestrator Queues
├── System.Data.DataRow         --> Tabular models; processing rows from Excel, SQL, or CSV
├── System.IO.FileInfo / String --> File-based models; batch processing file system documents
├── System.Net.Mail.MailMessage --> Email-driven models; processing inbox messages
└── Newtonsoft.Json.Linq.JToken --> API-driven models; consuming REST endpoints

The QueueItem Model (Default Enterprise Standard)

A QueueItem is a structured record hosted within a UiPath Orchestrator Queue. It provides native enterprise capabilities:

• Persistent Lifecycle States: Tracks items across New, In Progress, Successful, Failed, Abandoned, Retried, and Deleted.
• Orchestrator Auto-Retry: Automatically requeues failed transactions with application exceptions up to a predefined retry limit.
• Postpone and SLA Deadlines: Allows transactions to be deferred until a future timestamp or flagged with strict SLA deadlines.
• SpecificContent Container: A Dictionary<string, object> storing payload data fields (e.g., in_TransactionItem.SpecificContent("InvoiceTotal")).

The DataRow Model (Tabular Processing)

When automations must run offline, without Orchestrator queues, or on standalone Studio/attended robot licenses, the TransactionItem variable is re-typed as System.Data.DataRow. In this architecture:

• All data is extracted into an in-memory System.Data.DataTable variable (typically io_dt_TransactionData).
• in_TransactionNumber serves as the row pointer index.
• The framework processes rows sequentially without native Orchestrator status tracking.

---

2. The Dispatcher (Producer) Architecture

The Dispatcher is an automation workflow whose sole responsibility is to extract raw data from source systems, validate its structure, and push clean transaction items into an Orchestrator Queue.

+-----------------------------------------------------------------------------------+
|                            DISPATCHER ARCHITECTURE                                |
|                                                                                   |
|  [Source Systems]                                                                 |
|  - SQL Database                                                                   |
|  - Legacy ERP Export                                                              |
|  - Email Inbox Attachments                                                        |
|  - REST API Endpoint                                                              |
|           │                                                                       |
|           ▼                                                                       |
|  [Data Extraction & Cleansing]                                                    |
|  - Extract raw dataset into DataTable                                             |
|  - Apply schema validation & business filters                                     |
|  - Remove duplicates & invalid records                                            |
|           │                                                                       |
|           ▼                                                                       |
|  [Queue Ingestion]                                                                |
|  - Add Queue Item (with Reference, Priority, SpecificContent)                     |
|  - OR: Bulk Add Queue Items (for high-volume performance)                         |
|           │                                                                       |
|           ▼                                                                       |
|  [UiPath Orchestrator Queue] (Items stored with status 'New')                     |
+-----------------------------------------------------------------------------------+

Responsibilities of the Dispatcher:

1. Data Gathering: Queries databases, downloads vendor portals, parses shared network drives, or consumes REST APIs.
2. Validation and Pre-Filtering: Filters out corrupt rows, missing mandatory fields, or out-of-scope dates. This ensures that the queue contains only actionable, valid records, adhering to the principle of preventing garbage-in, garbage-out.
3. Queue Population:
   • Add Queue Item Activity: Uploads items individually. Allows assigning individual Reference strings, custom Priority levels (High, Normal, Low), and scheduling dates (Postpone, Deadline).
   • Bulk Add Queue Items Activity: Uploads the rows of a DataTable in one call. Orchestrator accepts at most 15,000 rows per call, so a 50,000-row ledger has to be split into chunks. The CommitType setting (AllOrNothing or ProcessAllIndependently) decides whether one bad row blocks the whole batch.

Critical Queue Properties:

• Reference: A unique business key (e.g., "INV-2026-0982" or "ACCT-" + row("ID").ToString). When Enforce Unique Reference is enabled on the Orchestrator Queue, Orchestrator automatically rejects any attempt to upload an item whose reference already exists, guaranteeing transaction idempotency.
• SpecificContent: Key-value pairs containing the transactional payload. Accessible within the Performer via in_TransactionItem.SpecificContent("KeyName").
• Priority: Directs Orchestrator to allocate High priority items to consumer robots before Normal or Low items.

---

3. The Performer (Consumer) Architecture

The Performer is an independent automation process that dequeues items from the Orchestrator Queue one at a time, executes the required business actions, and commits final transaction statuses.

+-----------------------------------------------------------------------------------+
|                             PERFORMER ARCHITECTURE                                |
|                                                                                   |
|                              [Orchestrator Queue]                                 |
|                               (Pending 'New' Items)                               |
|                                  │       │       │                                |
|               ┌──────────────────┘       │       └──────────────────┐             |
|               ▼                          ▼                          ▼             |
|       +---------------+          +---------------+          +---------------+     |
|       | Robot 01      |          | Robot 02      |          | Robot 03      |     |
|       | (Performer)   |          | (Performer)   |          | (Performer)   |     |
|       +---------------+          +---------------+          +---------------+     |
|       | - Get Item    |          | - Get Item    |          | - Get Item    |     |
|       | - Process     |          | - Process     |          | - Process     |     |
|       | - Set Status  |          | - Set Status  |          | - Set Status  |     |
|       +---------------+          +---------------+          +---------------+     |
|               │                          │                          │             |
|               └──────────────────┬───────┴──────────────────────────┘             |
|                                  ▼                                                |
|                       [Orchestrator Audit Trail]                                  |
|                       - Successful / Failed / Retried                             |
+-----------------------------------------------------------------------------------+

Enterprise Advantages of Decoupled Dispatcher-Performer:

1. Horizontal Elasticity & Concurrency: A single Dispatcher can load 10,000 items into an Orchestrator Queue. Ten unattended robots running the Performer process can concurrently pull from the same queue without file locks or collisions. If workload spikes, administrators simply allocate more robots to the queue.
2. Fault Domain Isolation: If a Performer crashes due to an operating system fault or hardware failure on Robot 02, the remaining robots continue processing uninterrupted. If the workflow catches the error and sets the item to Failed (Application), the queue's Auto Retry can hand a copy to Robot 01. If the robot dies without setting a status, the item stays In Progress and Orchestrator marks it Abandoned after about 24 hours.
3. Independent Lifecycle Scheduling: The Dispatcher can run at 01:00 AM when database servers experience low traffic. The Performers can run throughout the business day, or spin up dynamically in response to Orchestrator Queue Triggers when the queue item count crosses a threshold.

---

4. Architectural Comparison: Dispatcher vs. Performer

---

5. Where the Performer's Data Comes From

The Performer usually consumes queue items, but the same template can process a DataTable, a list of files, or a single linear run. Those adaptations change the TransactionItem type, the logic in GetTransactionData.xaml, and how status is recorded. The last section of this chapter walks through each one.