Blue Prism Pro Developer cheat sheet

Layered model: Process layer (business flow, no application interaction) calls Object layer (application interaction) and Business Object/utility layers; keep page count per layer low and reuse shared objects.

Page-per-action rule: one page performs one reusable action; a page that both navigates and reads data cannot be safely retried or reused, so split it.

Exception blocks belong at the Process layer around the whole work item; Object pages should throw exceptions upward rather than swallow them.

Separate the work item's data into a Collection passed between pages; avoid page-level global data items for anything that must survive a retry.

Design for unattended execution: no user prompts, no MsgBox, no reliance on screen resolution; all decisions must derive from data or application state.

Work queue architecture: control process (get next item, call perform, mark complete) plus a separate performer process; never mix control and performer logic in one page.

Recovery design: every process must be safely re-runnable on the same item; write outputs idempotently or check for existing records before creating.

Naming and versioning: prefix pages by layer (e.g., 'P-', 'BO-', 'U-'), release via a signed package, and keep a single source of truth for shared objects.

Stage order: Start -> (Action/Calculation/Multi-Calculation/Decision/Loop/Read/Write/Block/Note/Anchor/End); a page must reach End on every path or it will hang.

Decision stage evaluates a single boolean expression; both outgoing links carry a label (default 'Yes'/'No'), and every outcome must be handled explicitly.

Loop stage iterates a Collection; use 'Loop - Collection' with a Current Row data item, or 'Loop - Infinite' with an explicit exit condition.

Collection functions: Collection Contains, Count Rows, Filter, Sort, Merge, Remove Duplicates, Get Next Row; row indexing is 1-based in Blue Prism expressions.

Expression syntax uses VBO-style functions: Len(), Left(), Right(), Mid(), InStr(), Replace(), Trim(), Upper(), Lower(), CStr(), CInt(), CDate(), Now(), Today().

Multi-Calculation stage evaluates several expressions in one pass; use it to avoid chaining many single-calculation stages in hot loops.

Block stage groups stages for readability and single-point exception handling; a Block can carry its own Recover and Resume stages.

Data item scope: local to page, or global to process; global items persist across pages and are the primary cause of cross-item state leakage.

Spy modes: Win32 for standard Windows controls, Accessibility for Java/.NET/UI Automation trees, HTML for browser DOM, Region for image/text matching, UIA for modern apps.

Element attributes: match on stable attributes (Window Text, Class, ID, Name, Path) and never on volatile ones (coordinates, dynamic labels, row counts).

Application Modeller: each element has a match type (Wildcard, Exact, Regex); prefer Exact on stable IDs and Wildcard only where the app injects dynamic suffixes.

HTML mode: use CSS/XPath-friendly attributes; handle iframes by spying inside the frame, and wait for document ready rather than fixed sleeps.

Citrix/virtual desktops: use Region mode with image matching plus surface automation (Send Keys, Click Center) because the accessibility tree is not exposed; keep the window maximized and a fixed resolution.

API integration: use the bundled Web Services / HTTP object (or a Utility - HTTP VBO) with GET/POST, headers, and JSON/XML parsing via the built-in JSON/XML functions.

Attach vs Launch: Attach to an already-running application instance where possible; Launch only when the app is not running, and always include a wait-for-create step.

Timeouts: set element-level and application-level timeouts; a missing element should raise a System Exception, not silently return empty.

Exception types: System Exception (unexpected, e.g., app crash, element not found) and Business Exception (expected rule violation, e.g., invalid data); they take different recovery paths.

Recover stage catches the exception into the current page; Resume retries from the failing stage; the exception's Type, Message, and Detail are available as data.

Throw stage raises a deliberate exception; use it to convert a detected business rule violation into a Business Exception.

Preserve stage saves the exception to a data item so the outer block can re-throw or log it after cleanup.

Standard recovery pattern: Block -> Recover -> (cleanup: close app, reset state) -> Resume or re-throw; never leave an application in a half-logged-in state.

Retry limits: cap retries with a counter data item; after N attempts, escalate to a System Exception and mark the item as failed.

Business Exceptions must not be retried; mark the queue item as Exception with the reason and move to the next item.

Logging: write exception Type, Message, Detail, item key, and timestamp to the Blue Prism log or an external log collection before terminating.

Queue item states: New, In Progress, Completed, Exception, Deferred; only New and Deferred items are returned by 'Get Next Item'.

Get Next Item options: filter by tag/priority, set the item to In Progress, and load the item data into a Collection for the performer.

Item key must be unique per queue; duplicate keys are rejected at add time, so use a deterministic key derived from source data.

Deferred items: set a defer-until date/time; the item returns to the queue after that time, useful for rate-limited or scheduled retries.

Attempts counter increments each time an item is fetched; use it to detect poison items and stop infinite retry loops.

Mark Completed only after all downstream writes succeed; marking early causes silent data loss on later failure.

Queue data is stored in the Blue Prism database; large payloads should be stored externally with only a reference key in the item.

Bulk add: use 'Add to Queue' in a loop or the collection-based add; validate the collection schema before adding to avoid partial loads.

Control Room tabs: Processes (run/stop), Queues (view items, change state, retry), Sessions (running instances), Schedules (timed runs), Resources (runtime resources).

Session states: Starting, Running, Stopping, Stopped, Terminated; a session is one running instance of a process on one resource.

Schedule types: once, daily, weekly, monthly, and cron-style; each schedule binds a process, a resource pool, and start parameters.

Resource pools: group runtime resources so a schedule can start on any available member; use pools for load balancing across unattended machines.

Concurrency: a queue can be processed by multiple sessions simultaneously; design the performer to be safe under concurrent access.

Logging levels: set per-process log level (None, Error, Info, Debug) in Control Room; Debug is for troubleshooting only and is verbose.

Stop vs Terminate: Stop requests a graceful shutdown at the next checkpoint; Terminate kills the session immediately and may leave the app in an inconsistent state.

Alerts and dashboards: use Control Room dashboards to monitor queue depth, exception rates, and session health.

Role-based access: users are assigned roles (e.g., Developer, Process Owner, Controller, Administrator); permissions are granted per role, not per user.

Permission categories include Process (view/run/edit), Object, Queue, Schedule, Environment, and System; grant the minimum needed for the job function.

Environment variables hold environment-specific values (URLs, credentials references, file paths); the same release package runs in Dev, Test, and Prod with different variable values.

Credential store: credentials are stored encrypted in the Blue Prism database; processes reference a credential name, never a plaintext password.

Release management: develop in Dev, promote a signed release package to Test, then to Prod; never edit a process directly in Prod.

Audit trail: Blue Prism logs user actions, process changes, and queue state changes; retain logs per the organization's retention policy.

Segregation of duties: the person who develops a process should not be the sole approver for its promotion to Prod.

Change control: every production change requires a documented request, test evidence, and rollback plan before deployment.

Master/worker pattern: one master process splits work into queue items; N worker sessions consume the queue concurrently.

Exception-driven design: treat every external call as fallible; wrap it in a Block/Recover and define the recovery action per call type.

Idempotency: before creating a record, query for an existing match using the item key; skip creation if found.

State machine pattern: model long-running business flows as queue items with a state field, advancing state per run rather than blocking.

Separation of concerns: data extraction, validation, transformation, and submission are separate pages so each can be tested in isolation.

Performance: minimize round-trips to the application; batch reads into collections and process in memory.

Testability: every page should be runnable standalone with sample input data items; use a test harness process to exercise pages.

Documentation: each page carries a description, input/output data items, and a note stage explaining preconditions and side effects.

Dynamic element paths: use wildcards on volatile path segments; if the path is fully dynamic, fall back to Region mode or an API.

Wait stages: prefer 'Wait for element to exist' over fixed delays; fixed sleeps are the main cause of flaky automation.

Read stage: read text, value, or an entire table into a Collection; use 'Read - Table' for grids and verify row count after read.

Write stage: write to an element or a collection; always verify the write by reading back the value.

Action stage: call a page in another object; pass inputs and outputs explicitly via the stage's input/output parameters.

Code stage: use C#/VB.NET for complex parsing; keep code stages small, deterministic, and free of external dependencies.

Web APIs: handle HTTP status codes explicitly (2xx success, 4xx client error -> Business Exception, 5xx server error -> System Exception with retry).

Authentication: use OAuth token flows with token caching; refresh tokens before expiry and store them in a secure data item, not in the log.

Exception hierarchy: System Exceptions bubble up unless caught; Business Exceptions should be caught at the process layer and routed to the queue's Exception state.

Recovery blocks should be small and specific; a single giant Recover that catches everything hides the root cause.

Compensation: when a multi-step transaction fails midway, run compensating actions (delete partial record, reverse submission) before re-throwing.

Circuit breaker: after repeated failures on the same application, stop retrying and raise a System Exception to alert operations.

Screenshot on failure: capture the screen and attach it to the exception log for post-mortem diagnosis.

Retry with backoff: increase the wait between attempts (e.g., 1s, 5s, 30s) to avoid hammering a recovering system.

Exception data: store Type, Message, Detail, Stage, Page, and Timestamp; Detail often contains the stack trace needed for root cause.

Post-incident: review exception logs weekly, classify root causes, and feed fixes back into the process design.

Priority: items carry a priority value; Get Next Item returns highest priority first, then oldest.

Tags: use tags to partition a queue by business unit or batch; filter Get Next Item by tag to isolate workloads.

Queue item data schema: define the collection columns up front; changing the schema after items exist requires migration.

Status transitions: New -> In Progress -> Completed or Exception; Deferred -> In Progress after defer-until; Exception -> In Progress on manual retry.

Monitoring: alert when queue depth exceeds a threshold or when the exception rate exceeds a percentage of items processed.

Archival: completed items are retained for audit; purge or archive per retention policy to keep the queue performant.

Load balancing: multiple sessions on one queue scale horizontally; ensure the performer has no shared mutable state.

Manual intervention: Control Room allows an operator to change item state, reassign, or add a note; log who did what.

Schedule dependencies: chain schedules so a downstream process starts only after the upstream process completes.

Resource pools: assign sessions to pools; a schedule targeting a pool starts on any free member.

Session logs: each session writes a log; use the session log to trace a specific run's stages and exceptions.

Runtime resources: register machines as runtime resources; a resource can run one session at a time unless configured otherwise.

Time zones: schedules run in the server's time zone; document the time zone for distributed teams.

Failure handling: configure the schedule to retry on failure or to alert on failure; a silent failed schedule is a common outage cause.

Maintenance windows: pause schedules during application maintenance to avoid predictable failures.

Capacity planning: track session utilization and queue throughput to size the number of runtime resources.

Environment separation: Dev, Test, UAT, and Prod are separate Blue Prism environments with separate databases.

Release package: a signed package contains processes, objects, and referenced environment variables; import into the target environment and map variables.

Credential management: rotate credentials on a schedule; the process reads the current credential by name, so rotation requires no code change.

Role design: create roles per job function (Developer, Tester, Operator, Administrator) and assign users to the least-privileged role.

Audit: enable audit logging for process edits, permission changes, and queue manual interventions; review quarterly.

Data protection: do not log PII or credentials; mask sensitive fields in exception messages.

Business continuity: document a rollback procedure and keep the previous release package available for redeployment.

Compliance: map controls to the organization's framework (e.g., SOC 2, ISO 27001) and retain evidence of testing and approvals.

Collection filtering: use Filter with an expression on a column; the result is a new collection, leaving the source unchanged.

Collection sorting: Sort by one or more columns ascending/descending; sort before deduplication for deterministic results.

Collection merge: Merge two collections on a key column; specify join type (inner/left/right) and handle null keys.

String building: concatenate with & and use & vbCrLf for line breaks; avoid building huge strings in a loop without a StringBuilder equivalent.

Date handling: use Now() for timestamps, Today() for dates, and FormatDate()/FormatDateTime() for output; store dates as DateTime, not strings.

Numeric handling: CInt rounds, Fix truncates; use Round() explicitly when business rules require a specific rounding mode.

Error-prone expressions: guard division by zero and null collection rows; check Count Rows before indexing.

Page testing: run a page standalone with sample inputs; use a test harness process to exercise pages in isolation.

HTML mode spying: match on id, name, or a stable CSS selector; avoid matching on text that changes with locale.

Iframes: spy inside the frame; the element path includes the frame, and the frame must be loaded before spying.

AJAX: wait for the element to exist after an action; do not assume the DOM is ready immediately after a click.

Citrix: use Region mode with image matching; keep the window at a fixed size and resolution, and use Send Keys for text entry.

Surface automation: image matching is brittle to theme changes; pin the theme and document the dependency.

Web APIs: use the HTTP object with JSON parsing; validate the response schema before reading fields.

Authentication: handle session expiry by re-authenticating and retrying the failed call once.

Element recovery: if an element is not found, re-attach to the application and retry before raising a System Exception.

Business Exception: expected, data-driven, not retried; mark the queue item Exception with a clear reason.

System Exception: unexpected, environment-driven, retried up to a limit; if the limit is exceeded, escalate.

Classification rule: if the same input will always fail, it is a Business Exception; if the same input might succeed on retry, it is a System Exception.

Validation: validate input data before touching the application; fail fast with a Business Exception.

Recovery scope: recover at the narrowest block that can meaningfully clean up; re-throw if cleanup is impossible.

Logging: log Business Exceptions at Info, System Exceptions at Error, with the item key and stage name.

Alerting: System Exceptions that exceed the retry limit should page operations; Business Exceptions should feed a data-quality report.

Testing: inject faults (kill the app, return bad data) to verify each recovery path works.

Queue design: one queue per business process; do not mix unrelated work types in one queue.

Item key: deterministic, unique, and stable across re-runs; derive from source system ID plus a business key.

Payload: keep the item data small; store large documents externally and keep a reference in the item.

Throughput: measure items per hour per session; scale sessions to meet SLA.

Backlog: monitor queue depth; a growing backlog signals under-capacity or a stuck process.

Retry policy: limit attempts to 3-5; after that, route to a manual-review queue.

Reporting: use queue reports for completed, exception, and deferred counts by day.

Data retention: archive completed items after the retention period to keep queries fast.

Session start: a session starts a process on a resource; parameters can be passed at start.

Scheduling: a schedule defines when and where a process runs; it can be recurring or one-off.

Monitoring: watch session state, queue depth, and exception rate on the Control Room dashboard.

Alerts: configure alerts for failed sessions, high queue depth, and high exception rates.

Logs: session logs record each stage's execution; use them for troubleshooting.

Stop semantics: Stop is graceful; Terminate is immediate and may corrupt state.

Resource pools: group resources for load balancing and failover.

Maintenance: pause schedules during application maintenance windows.

User roles: assign the least-privileged role; review access quarterly.

Credentials: store in the credential store; rotate on schedule; never log plaintext.

Environment variables: hold environment-specific values; map on import.

Release: sign packages; promote through Dev, Test, Prod; keep rollback packages.

Audit: log edits, permission changes, and manual queue interventions.

Data protection: mask PII in logs and exception messages.

Change control: require a documented request, test evidence, and approval before Prod deployment.

Compliance: map controls to the organization's framework and retain evidence.

Master/worker: master enqueues work; workers consume concurrently.

Idempotency: check for existing records before creating.

State machine: model long flows as queue items with a state field.

Separation of concerns: extraction, validation, transformation, and submission are separate pages.

Performance: batch reads into collections; process in memory.

Testability: pages runnable standalone with sample inputs.

Documentation: each page carries a description and note stage.

Recovery: every process safely re-runnable on the same item.

Stage order: Start -> stages -> End; every path must reach End.

Decision: single boolean expression; both links labeled.

Loop: iterate a collection with a Current Row item, or infinite with an exit condition.

Collection functions: Contains, Count Rows, Filter, Sort, Merge, Remove Duplicates.

Expression syntax: Len, Left, Right, Mid, InStr, Replace, Trim, CStr, CInt, CDate, Now, Today.

Multi-Calculation: evaluate several expressions in one pass.

Block: group stages for readability and single-point exception handling.

Data item scope: local to page or global to process; global items persist across pages.

Spy modes: Win32, Accessibility, HTML, Region, UIA.

Match on stable attributes; never on coordinates or dynamic labels.

Match types: Wildcard, Exact, Regex; prefer Exact on stable IDs.

HTML: match on id, name, or stable CSS selector.

Citrix: Region mode with image matching; fixed window size and resolution.

Attach vs Launch: Attach to a running instance where possible.

Timeouts: set element-level and application-level timeouts.

Missing element: raise a System Exception, not an empty return.

Exception types: System Exception and Business Exception; different recovery paths.

Recover catches into the current page; Resume retries from the failing stage.

Throw raises a deliberate exception; Preserve saves it for the outer block.

Standard pattern: Block -> Recover -> cleanup -> Resume or re-throw.

Retry limit: cap retries with a counter; escalate after N attempts.

Business Exceptions are not retried; mark the item Exception.

Log Type, Message, Detail, item key, and timestamp before terminating.

Circuit breaker: stop retrying after repeated failures and alert operations.

States: New, In Progress, Completed, Exception, Deferred.

Get Next Item returns New and Deferred items only.

Item key must be unique per queue.

Deferred items return after the defer-until time.

Attempts counter increments on each fetch; use it to detect poison items.

Mark Completed only after all downstream writes succeed.

Queue data is stored in the Blue Prism database.

Bulk add: validate the collection schema before adding.

Session states: Starting, Running, Stopping, Stopped, Terminated.

A session is one running instance of a process on one resource.

Schedule types: once, daily, weekly, monthly, cron-style.

Resource pools: group resources for load balancing.

Concurrency: multiple sessions can process one queue simultaneously.

Log levels: None, Error, Info, Debug; Debug is for troubleshooting only.

Stop is graceful; Terminate is immediate.

Dashboards monitor queue depth, exception rate, and session health.

Roles: Developer, Process Owner, Controller, Administrator.

Permissions granted per role, not per user.

Permission categories: Process, Object, Queue, Schedule, Environment, System.

Environment variables hold environment-specific values.

Credentials stored encrypted; processes reference by name.

Release: Dev -> Test -> Prod; never edit in Prod.

Audit trail logs user actions and process changes.

Segregation of duties: developer is not the sole approver for Prod.

Layers: Process, Object, Business Object/Utility.

Page-per-action: one page performs one reusable action.

Exception blocks at the Process layer around the work item.

Pass work item data as a Collection between pages.

Design for unattended execution: no prompts, no MsgBox.

Control process and performer process are separate.

Recovery: every process safely re-runnable on the same item.

Naming: prefix pages by layer; release via signed package.

Collection functions: Contains, Count Rows, Filter, Sort, Merge, Remove Duplicates, Get Next Row.

Row indexing is 1-based.

Filter returns a new collection; the source is unchanged.

Sort by one or more columns ascending/descending.

Merge on a key column with join type.

Check Count Rows before indexing.

Use Multi-Calculation to avoid chaining single-calculation stages.

Global data items persist across pages; avoid for item data.

Use the HTTP object with GET/POST, headers, and JSON/XML parsing.

Handle status codes: 2xx success, 4xx Business Exception, 5xx System Exception with retry.

Validate the response schema before reading fields.

OAuth: cache tokens, refresh before expiry, store securely.

Attach vs Launch: Attach to a running instance where possible.

Wait for element to exist rather than fixed sleeps.

Code stage: small, deterministic, no external dependencies.

Verify writes by reading back the value.

Business Exception: expected, data-driven, not retried.

System Exception: unexpected, environment-driven, retried up to a limit.

Classification rule: same input always fails -> Business; might succeed on retry -> System.

Validate input before touching the application; fail fast.

Recover at the narrowest block that can clean up.

Log Business at Info, System at Error.

System Exceptions over the retry limit page operations.

Inject faults to verify recovery paths.

One queue per business process.

Item key: deterministic, unique, stable across re-runs.

Keep payload small; store large documents externally.

Measure items per hour per session; scale to meet SLA.

Monitor backlog; growth signals under-capacity or a stuck process.

Retry limit 3-5; then route to manual review.

Queue reports: completed, exception, deferred by day.

Archive completed items after the retention period.

Session start: a session starts a process on a resource with parameters.

Schedule defines when and where a process runs.

Monitor session state, queue depth, exception rate.

Alerts for failed sessions, high queue depth, high exception rate.

Session logs record each stage's execution.

Stop is graceful; Terminate is immediate.

Resource pools for load balancing and failover.

Pause schedules during maintenance windows.