API & Architecture

Power users keep QBO’s background work flowing: which queue runs what, when it runs, how failures are handled, and how you know it’s healthy.

Queues

Any operation can be queued: generating documents, sending messages, calling a third-party API, launching workflows. Workflow steps, batch actions, and imports let you pick a queue from a list. The Queue Service on your app servers pops each message and runs the operation.

Setting	Purpose
Threads	How many messages the Queue Service runs at once.
Priority / Dependencies	A queue waits until the queues it depends on are empty, so urgent work jumps ahead.
Throttle interval	Caps throughput, for example one call every three seconds, to respect a vendor’s terms.
Failure strategy	How retries, back-off, and automatic pausing behave (see below).
Calendar	Restricts the queue to business days and hours.
Impersonate type	Runs messages as the queuing user, an inherited user, an admin user, or a specific user.
Success / failure / debug log	Where processing history is written.

Failure strategies are presets for common situations:

Strategy	Behavior
Standard	Default retry behavior.
Database	Fast back-off with a fast pause.
Network	Standard back-off, never pauses. Good for brief connection drops.
Third party	Slow back-off, pauses, and restarts periodically. Good for vendors with maintenance windows.
Cost sensitive	Fast back-off with a small failure threshold, so paid calls stop early.
Advanced	You set retry, pause, and resume intervals yourself.

When a queue hits its failure threshold it pauses itself. Depending on the strategy, it can resume automatically after an interval.

Prioritizing urgent work

Suppose a nightly job queues 100,000 payment postings, and a customer calls at 8:30 with a payment that must go now. Create a Payments – High Priority queue and make Payments depend on it. The Queue Service won’t pop from Payments while the high-priority queue has messages.

Future and failed messages

Messages with a future run date wait in a dedicated future queue, then move to their target queue when due. Messages that exhaust their retries go to a failure queue, where you can review and reprocess them.

Reading queue logs

From the Queuing home page, open a queue’s success or failure log. Each entry shows the message ID, the operation and its Object / ObjectID, queued and executed dates, execution time, execute count (above 1 means retries), and the machine and process that ran it. A process of w3wp instead of the Queue Service means someone ran the message manually from the UI.

Troubleshooting stuck work

Messages that have a Starting or Processing log but no Success or Failure log were started and never finished. Look for these first when app servers show sustained high CPU. Typical causes are large result sets, memory-heavy document or image processing, or unmanaged background threads.

Schedules

Schedules are written in plain English, and QBO parses them:

Pattern	Example
Daily at a time	Daily at 6am or Daily @ 6am
Daily, repeating	Daily repeating 5 minutes between 5am to 10pm
Every few days	Daily every 3 days @ 7am
Weekly	Weekly on Mon, Wed @ 12pm
Weekly, repeating	Weekly on Mon, Wed, Fri repeating 3 hours between 5am to 11pm
Monthly by day	Monthly on day 1 @ 6:00a
Monthly, relative	Monthly on the 2nd Sun every 2 months @ 6am

Any schedule can add starting {date} and ending {date}. To schedule an operation, queue it with a ScheduleName. After each run, QBO re-queues it for the next run date. Schedules with the same text are shared, so add a ScheduleLabel when two jobs need separate schedules.

Calendars

A calendar defines working days, start and end times for each day, the first day of the week, a default time zone, and holidays. Holidays can be fixed dates or calculated each year from a rule or schedule. Queues, schedules, and health checks can each be tied to a calendar, so work runs only during business hours.

Settings

Each module has application settings, such as password policy, API key behavior, or the site name. System defaults are values that can be overridden for a role or an individual user. Examples include a home page’s default dashboard dimension or a default search.

Configuration changes made in the UI are stored as configuration entries in the database. Because each entry records its source file, type, and key, it can be exported as a setup package and promoted from UAT to production.

Custom routes

Routes map URLs to operations. The standard routes are built in. Add your own to alias a module or pre-fill parameters:

Property	Purpose
Name	Routes are evaluated in alphabetical order by name. Names before Default (such as Custom-…) take precedence over the standard routes.
Url	The pattern to match, with {placeholders} and optional :int, :date, or :isodate constraints.
MethodSignature	The operation to run, for example Process/{operation}.
DefaultParameters	Parameters added to every request on this route.
HttpMethods	Limits the route to GET, POST, PUT, PATCH, or DELETE.

For example, QBO ships a documents/{operation} route with MethodSignature="Attachment/{operation}", so /documents/search searches documents. A projects/{operation} route mapped to Process/{operation} would do the same for cases.

Health checks

Health checks run any operation and judge the result: queue counts (for example, the failure queue), report counts (a statement returns expected rows), HTTP and SOAP endpoint checks, or a custom operation.

Property	Purpose
Level	Error, Warning, or Information.
Priority	1 critical and systemic, 2 actionable, 3 support.
Calendar	When the check may run.
Impersonate type	Run as the authenticated user, an inherited user, or a specific user.
Async	Run in the background service and report the cached result (for checks slower than about 100 ms).
Cache interval	Reuse a result for a period.

A monitoring tool calls the health check suite and gets HTTP 200 when every check passes and 417 when any fails, with details in XML or JSON. The suite can also run from a queue on a schedule and email a summary. A lightweight GET /healthcheck returns the installed version for load balancers.

Logs

Log	What it records
Queue log	Every queued message: starting, processing, success, failure, timings, retries.
Rolling log	Application events by category, severity, machine, and user.
Import log	Import file processing.
Security log	Sign-ins, failures, lockouts, impersonation (see Security).

Logs can also be sent to cloud monitoring, such as Amazon CloudWatch or Azure Application Insights. Log entries carry expiration dates so old history can be purged.