IQueue: Managing Work in the Background

Background

The IQueue interface enables QBO 3 to offload work to background processes. This happens by calling AbstractObject.Queue(), instead of AbstractObject.Invoke(). The queue method will instantiate an IQueue plugin, and pass the operation and parameters to be invoked to some queue.  Example plugins include:
  • MSMQ: Microsoft Message Queue which is a queue based on local disk access
  • SQL Service Broker: the preferred option, this is a queue based on tables in SQL Server
  • Amazon Simple Queuing Service: this is a queue that enables cross-organization communication of queued items
  • CurrentQueue, FutureQueue, FailureQueue (ObjectQueue): these are queues based on the QBO 3 ObjectQueue table that handle non-FIFO (e.g. future-scheduled) items

Using Queuing

Any QBO method signature can be queued for execution as follows:

{ClassName}/Queue/{Operation}?{Parameters}

For example:

Attachment/Queue/Generate?Template=Standard Contract&Object=Organization&ObjectID=1
Message/Queue/Send?ToAddress=info@company.com&Subject=Hello

Queuing specific parameters are also supports:
  • QueuedDate: if a future date and time is specified, the method signature will be routed to the Future queue for deferred execution
    // Queue an email to be delivered @ 9:30 on 1/1/2020
    Message/Queue/Send?ToAddress=info@company.com&Subject=Hello&QueuedDate=1/1/2020 9:30

  • ScheduleName: create a recurring job
    // Create a job to send an email every day at 8am
    Message/Queue/Send?ToAddress=info@company.com&Subject=Reminder&ScheduleName=Daily at 8am

  • QueueName: when specified, the method signature will be routed to the named queue. If not specified, the default queue will be used.
    // Queue an email to the HighPriority queue
    Message/Queue/Send?ToAddress=info@company.com&Subject=Hello&QueueName=HighPriority

  • QueueLabel: when specified, this will override the label of the method signature within the queue infrastructure. This is useful for recurring jobs.
    // Queue an email  with a nice label
    Message/Queue/Send?ToAddress=info@company.com&Subject=Reminder&ScheduleName=Daily at 8am&QueueLabel=Daily Reminder

Managing Queuing

Queuing can be managed from Design > Configuration > Queuing. 

The dashboard includes the following data:
  • Queue: the name of the queue, which also appears in QBO3 UI where power users can choose a queue.
  • Status: displays the status of a queue
  • Uri: resource location of the queue - typically the name of the queue, though for AWS SQS, this would be a longer string.
  • Threads: number of threads allocated to the queue per application servicer. This is how many items may be 'parallel processed' at any one time.
  • Queue Logic: how the queue behaves, such as what to do for errors, how often to retry, etc.
  • Throttling: whether the queue should limit processing per second. This is for third party systems that may not be able to handle enough concurrency under load.
  • Count: number of items current in the queue.
  • Processing: number of items currently being executed by applicaiton servers.
  • Success, Failure and Debug log: what logging sink to write success, failure, or debugging messages to.
The possible statuses for a queue include:
  • Running: the queue is 'on', and the calendar is 'active', so items are eligible for processing.
  • Paused: the queue was paused by a user or multiple consecutive failures, and warrants investigation.
  • Enabled: the queue is 'on', but the calnedar is not 'active', so items are not eligible for processing.
  • Disabled: the queue is 'off'; items are not eligible for processing.
  • Virtual: the queue is managed by QBO or a third party
From the Options menus, you can:
  • Create a new Queue
  • Enable: this turns a queue 'on', allowing it to process items as long as it's calendar is also 'on'.
  • Disable: this turns a queue 'off', and is typically used for troubleshooting or performance management.
  • Purge: this deletes all messages in a queue, typically used for performance management.
  • Clear Log: this removes log entries for a queue.
  • Delete: deletes a queue. This is not allowed of there are items in the queue.
Clicking on the Count or Processing will trigger a display of matching items in the bottom panel(s). Bottom panel options include:
  • Process: pop the selected item(s) from the queue and execute it immediately
  • Process Next Item: pop the next item from the queue and execute it immediately
  • Move: moves the selected items(s) to another queue (e.g. from the Failure queue to a Default queue)
  • Delete Item: deletes selected item(s) from the queue.
  • Delete Next Item: deletes the next item from the queue.
Clicking on one of the Logging links will render a new tab in the bottom panels, display a searchable history of activity for a queue.

Performance Considerations

All QBO 3 systems come pre-configured with a 'DefaultQueue' entry (using Service Broker), and a Current, Future and Failure queue (using ObjectQueue). This is rarely a sufficient setup to manage a production application. New queues can be configured via Design > Configuration > Queuing, and should be created with the following guidelines:
  • To offload queue from a web server to app server(s), use SQL Service Broker
    • this enables multiple machines to monitor a single queue
  • Critical operations (such as deliver of data to clients) should have their own queue
    • this ensures critical operations are not 'stuck' waiting for non-critical operations
  • Long running operations (such as import routines) should have their own queue
    • this ensure long running operations don't interrupt routine operations
  • Operations dependent on a third party (such as interfacing with a servicing system) should have their own queue
    • this enables a queue to be stopped should there be an interface problem, without impacting the flow of other operations
  • High throughput operations (such a DecisionStep/Start) should have their own queue
    • this enables allocation of multiple threads to very common operations, so you can control how much of a machine's resources are dedicated to such things