Updated recently
Last updated:
Quick Answer: UiPath REFramework is a free, queue-driven state-machine template that gives you five states — Init, Get Transaction Data, Process, Process Recovery and End Process — with configuration loading, retry logic, logging and exception handling already wired in. Your job is to write business logic in Process.xaml, throw BusinessRuleException for data that cannot be fixed by retrying, and leave everything else as a system exception so the framework recovers and retries it.
When UiPath REFramework Is the Right Answer (and When It Is Not)
REFramework exists for one shape of work: transactional, queue-driven, unattended automation. An invoice batch of 20,000 items. A claims reconciliation. A nightly KYC refresh. If the automation will run unattended, needs an audit trail per item, must retry transient failures, and processes items that arrive in bulk, the framework earns its complexity immediately.
Where it does not earn it: a five-step attended bot that opens an application and pulls a report for one person. Wrapping that in a state machine adds files, configuration and cognitive load for nothing. A plain Sequence is the correct answer, and a surprising number of production UiPath estates have both — REFramework for the heavy performers, simple sequences for the attended helpers. If you are still deciding which platform to commit to before investing in this one, our UiPath vs Blue Prism vs Automation Anywhere comparison covers where each platform’s job volume and pay actually sit.
One more distinction that clears up half the confusion around this template: a REFramework process is a performer. It consumes items from an Orchestrator queue. Something else — usually a small, separate sequence with no framework at all — is the dispatcher that reads the source file and adds those items to the queue. If you find yourself writing file-reading logic inside Process.xaml, you have merged the two roles, and you will feel the pain when the source system’s format changes.
UiPath REFramework: The Five States and What Each One Does
The whole template is a state machine in Main.xaml. Transitions are driven by conditions, mostly on the TransactionItem variable and on exception variables. Here is the flow as it actually executes:
Main.xaml (State Machine)
|
+-- Init ------------------- InitAllSettings.xaml -> load Config.xlsx into Config
| InitAllApplications.xaml -> open + authenticate target apps
| KillAllProcesses.xaml -> clean up stray sessions
|
+-- Get Transaction Data --- GetTransactionData.xaml -> Get Transaction Item from queue
| | (TransactionItem = Nothing)
| | TransactionItem isNot Nothing --> Process |
| | | v
| | v End Process
| | Process
| | (Process.xaml + SetTransactionStatus.xaml)
| | |
| | BusinessRuleException --------+--> mark item, next transaction
| | System exception -------------+--> Process Recovery
| | |
| +<--------------- retries exhausted ----+ (Set Transaction Status = Failed)
|
+-- Process Recovery ------ close/reopen apps, increment RetryNumber,
| Set Transaction Status = Retried, back to Process
|
+-- End Process ----------- CloseAllApplications.xaml, log out, release resources
| State | Workflow | What actually happens | Where it usually breaks |
|---|---|---|---|
| Init | InitAllSettings, InitAllApplications | Config.xlsx is read into the Config dictionary; target applications are opened and authenticated; logging level is applied | App not ready at startup; missing config key; wrong environment |
| Get Transaction Data | GetTransactionData | Pulls the next queue item into TransactionItem. Nothing means the queue is drained and the bot goes to End Process | Typo in OrchestratorQueueName; item stuck from an earlier run; retry exhaustion check |
| Process | Process, SetTransactionStatus | Your business logic runs in a Try/Catch. Success, business exception and system exception are written back to the queue item | Business logic placed outside the try-catch; wrong exception type thrown |
| Process Recovery | Recovery logic | Re-initialises applications, increments RetryNumber, marks the item Retried, and returns to Process if retries remain | Retrying a business exception forever; not closing broken app instances first |
| End Process | CloseAllApplications | Closes applications, logs out, releases licences — on every exit path, including aborts | Skipping cleanup, so the next run starts with a stale window |
Two details that trip people in interviews and in production. First, the counters are framework-level, not queue-level: io_RetryNumber and io_TransactionNumber are passed between states, and RetryNumber is what the retry decision reads against the limit in Config. Second, if a system exception occurs in Init or while the framework is checking its stop signal, there is no transaction context to recover — the workflow ends in a Faulted state, and that is expected behaviour rather than a bug in your code.
Config.xlsx and the Keys You Will Actually Edit
InitAllSettings reads Config.xlsx into a dictionary called Config, and every other state reads from it. The file has Settings, Constants and Queues sheets. In practice you edit four or five rows on a new process:
Config.xlsx (Settings / Constants sheets — the rows you touch first)
OrchestratorQueueName Invoices_Inbound_UAT must match Orchestrator exactly, case-sensitive
OrchestratorQueueFolder Finance/Shared Services modern folder-based tenancy
MaxRetryNumber 3 system exceptions only
RetryIntervalTime 30 seconds between retry attempts
LoggingLevel 3 0 Fatal ... 5 Trace
Environment UAT drives environment-specific constants
# Business rule violation goes INSIDE Process.xaml, inside the try-catch
If Not IsNumeric(txn.SpecificData("InvoiceAmount").ToString) Then
Throw New BusinessRuleException("Invalid amount for reference " & txn.Reference.ToString)
End If
# A broken target application is NOT your business logic's problem — let it bubble
# as a system exception so Process Recovery can retry it
Config versions differ slightly across template generations — you will see NumberOfRetries or RetryIntervalTime spelled differently depending on whether the template came from Academy in 2021 or 2025 — but the pattern does not change: configuration lives in the workbook, never hard-coded in a workflow, because the whole point is that an environment-specific value can be changed without opening Studio.
Business Exceptions vs System Exceptions: The Part Most Developers Get Wrong
This distinction is the single most exam-relevant and production-relevant idea in the framework.
A BusinessRuleException means the data itself is bad. A missing GSTIN. An invoice amount that fails validation. A vendor code that no longer exists in the master. Retrying it three times will fail three times, because nothing technical will change. You throw it deliberately, the framework marks the item as failed with a business exception, and Orchestrator does not retry it by default. The right downstream action is a human: a validation queue in Action Center, an email to the process owner, a row in an exceptions report.
A system exception (a plain .NET exception — InvalidOperationException, a timeout, a selector not found) means something technical went wrong. The application froze. The network dropped. A screen element moved. Here retrying has a real chance of success, so the framework routes the item through Process Recovery, increments RetryNumber, and tries again up to MaxRetryNumber before finally marking it Failed. This classification is also the most monetisable idea in the framework: being able to defend it in a design review is a large part of what separates the top of the UiPath developer salary India 2026 band from the middle of it.
UiPath’s own queue behaviour reinforces this: if a transaction is failed with an application exception and the queue’s Auto Retry option is enabled, Orchestrator retries it; business exceptions are not retried by default, because the underlying data problem needs a human decision. Pick one retry mechanism — either the framework’s RetryNumber or the queue’s Auto Retry — and turn the other off. Running both means a system exception can consume retries twice, and your MaxRetryNumber stops meaning what it says.
Dispatcher and Performer: How It Is Built in Practice
The dispatcher is a small sequence: read the source (Excel, mail, API), build a DataTable, loop the rows, and call Add Queue Item with a unique Reference, the business fields as SpecificContent, a Priority and an optional DeferDate. It does not need REFramework and should not have it. The performer — your REFramework process — pulls those items one at a time and never needs to know where they came from. Orchestrator locks each item to a single robot while it is being processed, which is what makes 40 unattended robots safe to run against one queue. The Blue Prism world solves the same problem with work queues and item locks, as our Blue Prism Control Room and digital workers explainer sets out.
When you are debugging outside Studio, the same queue can be driven straight from the API. This is the pattern interviewers like to see, and it is genuinely useful for loading test data:
# 1. Authenticate against Orchestrator and keep the bearer token
curl -s -X POST "https://orch.example.com/api/Accounts/Authenticate"
-H "Content-Type: application/json"
-d '{"usernameOrEmailAddress":"coe-admin","password":"***","tenant":"AcmeBots"}'
# -> {"result":"<jwt-token>","success":true}
# 2. Add a queue item the REFramework performer will pick up
curl -s -X POST "https://orch.example.com/odata/QueueItems"
-H "Authorization: Bearer <jwt-token>"
-H "Content-Type: application/json"
-d '{"QueueDefinitionId":1024,
"ItemData":"{"InvoiceNo":"INV-4471","InvoiceAmount":"1840.00"}",
"Priority":1}'
ItemData is the serialised SpecificContent — the same dictionary your Process.xaml reads through txn.SpecificData("InvoiceNo"). If the two do not match, you have a mapping bug, and it will show up as a null reference inside Process rather than as an API error.
What Actually Happens at Work: The Exception That Stopped 40 Robots
A Chennai shared-services team ran an accounts-payable performer on 40 unattended robots against a single Orchestrator queue. An upstream extract began shipping rows where a cost-centre field was blank. The mapping code in Get Transaction Data — not in Process, which is where it belonged — hit a null reference while building a lookup dictionary. That is a system exception thrown outside the transaction try-catch, so the framework had nothing to recover: every robot faulted within minutes of pulling its first item.
Queue depth went from 3,000 pending to 62,000 in under nine hours, and the month-end payment run missed its SLA. The recovery involved three separate actions, and all three are worth remembering. Operationally, the team drained the backlog by temporarily raising MaxRetryNumber and running extra robots in the next window — 12 robots cleared 47,000 items in about six hours. Technically, the null check moved inside Process.xaml with an explicit BusinessRuleException, so bad rows now get marked Invalid and land in a daily exceptions report instead of stopping anything. Organisationally, they added a queue-depth alert at 5,000 pending items and a rule that any framework-level code change — Get Transaction Data, Init, anything outside Process — needs a second pair of eyes in review.
The generalisation is the valuable part: a business exception thrown in the wrong state does not fail one transaction, it fails the robot. If you take one idea from this explainer, take that one.
Training Resources
REFramework is the module most candidates claim on their CV and few can defend in a live design discussion. Build it properly with SkilBrill UiPath Training — state machine, dispatcher and performer split, queue design, retries and exception taxonomy, with production-style debugging labs.
FAQ
What is UiPath REFramework?
The Robotic Enterprise Framework is UiPath’s free state-machine template for queue-driven automations. It provides Init, Get Transaction Data, Process, Process Recovery and End Process states with configuration loading, logging, retry handling and transaction status reporting built in, so developers only write business logic.
Should every UiPath project use REFramework?
No. Use it for unattended, transactional, queue-driven work that needs retries and an audit trail. For a simple attended bot or a one-off report pull, a plain Sequence is faster to build and easier to maintain.
What is the difference between BusinessRuleException and SystemException?
BusinessRuleException means the data is wrong and retrying cannot help — the framework marks the item with a business exception and moves on. A SystemException is technical (application froze, selector missing) and routes the item through Process Recovery for retry up to the configured limit.
How does retry work in UiPath REFramework?
Retries are counted per transaction with RetryNumber against the MaxRetryNumber value in Config.xlsx, and only system exceptions trigger them. Turn off the queue’s Auto Retry if the framework is handling retries, or you will double-count failures.
Can UiPath REFramework run without Orchestrator queues?
Yes — the tabular-data variant of the template drives Get Transaction Data from a DataTable instead of a queue, which suits single-robot processes. For anything running on more than one robot, use an Orchestrator queue so items are locked and tracked properly.
