qbo.Decision: Workflow Management

The qbo.Decision module represents the workflow management. Workflow is typically modeled in flow chart, where:
  • each shape represents a Step, and
  • each line between shapes represents a Dependency
Steps in a workflow fall into one of five broad categories:
  1. Tasks: require human input, which cause a workflow to pause until completed by a person,
  2. Documents: mail merge data with a document template to produce a document,
  3. If/then steps: used to branch workflow based on data conditions
  4. Polling steps: periodically query the database, waiting for some data conditions to be met
  5. Other steps: call other QBO 3 class methods

Tasks

Tasks typically present a user with a custom form, requiring them to enter data required by later steps in the workflow. 

In the example to the right, the 'Foreclosure Referral Review' step is a task (custom form) that prompts a user to verify that all required data for a foreclosure referral has been entered.

Documents

In the example, the Generate Breach Letter step invokes the qbo.Attachment module's Generate method, producing a PDF document via Microsoft Word's mail merge feature. This is done entirely server-side, and need not involve any human interaction.

If/Then Steps

The 'State Letter Required?' if/then step determine if a State Letter is required given the conditions associated with a particular workflow. If then steps are executed synchronously, and simply evaluate data points in a series of if/then statements to arrive at a 'true' or 'false' condition. Other steps can be made dependent on an if/then step being true, or on and if/then statement being false.

Polling Steps

The 'Wait for Certified Mailing' steps monitors the database for an update to the attachment's OutboundTrackingID column. Polling steps are executed on a schedule, querying the database and evaluating the results against and if/then statement. Once the data conditions are met, the polling step is completed, and the workflow may progress.

Other Steps

The FTP to Mailing Provider step invokes the qbo.Attachment module's Copy method, which can copy documents from the QBO imaging store to any configured FTP site or imaging system. In this case, the mailing provider's FTP site has been configured under the Attachment module in advance, so any document can be copied to their FTP site.

The 'Print Breach Letter' near the end of the workflow is only executed when the 'State Letter Required?' if/then step evaluates to 'true'. If executed, it leverages the qbo.Attachment module's Print interface, capable of having the QBO servers remote-print documents within our client's network.

When invoking various methods, you will be prompted to enter three key Action fields:
  1. ClassName: this is the name of the QBO 3 module the workflow step will be calling (e.g. Loan, Borrower, Contact, Attachment, etc.)
  2. Operation: this is the name of the module's method that the workflow step will be calling (e.g. CopyFile, Edit, Geocode, etc.)
  3. Parameters: the parameter to be passed to the Operation

Decision Processing

Normally, simply saving a Decision will cause the workflow to be 'processed'. Technically, the Decision class includes a Inserted event handler that calls the Decision.Process() method, which in turn will process a workflow.

The Decision.Process() method queries the database to insert eligible steps, and for each step, either processes the step (if the step is defined as synchronous), or queues the step for processing (if the step is asynchronous).  In both cases, ultimately the DecisionStep.Start() method is being called.

For installations that are running QBO 2 and QBO 3 side-by-side, decisions must be processed with either the QBO 2 workflow engine, or the QBO 3 workflow engine; it should not be processed with both. For this reason, QBO 3 includes a DecisionProcessOnInsert application setting, which defaults to true. If true, Decision.Insert() will call Decision.Process() automatically.  If set to false, Decision.Insert() will not call Decision.Process().

Parameter Substitution

QBO 3's Parameter Substitution patterns are used for the parameters. For example, the Attachment/CopyFile method expects two parameters: and ID and a FileObject. When designing the workflow you cannot know in advance the values to be passed, so instead you represent the values as XPath expressions wrapped in curly braces.  For example:
  • Attachment/CopyFile?ID={//AttachmentID[1]}&FileObject=MailingVendorFTPSite
  • Contact/SCRASearch?SSN={//USSSN[1]}
The XPath expressions in the curly braces are evaluated against the Decision's parent Summary statement, which essentially returns all data associated with an object.

If the data containing in the parent object's Summary method is insufficient, a custom query may be used to feed parameters instead. By checking the 'data from a query' checkbox, the UI changes, and you may specify a query to run prior to evaluating the Action to take.

In the example to the right, the query being run is Attachment/Search?InDecisionID={DecisionID}.  The InDecisionID is a useful filter that limits search results to objects created by a Decision. Note that in this case parameter substitution is being used for the custom query! In this case, the parameters available are limited to the columns associated with the Decision table.

If a step uses a Query to feed parameters to an Action, the action is invoked for every row returned by the query. In the example on the right, this means that all attachments created by the workflow would be transmitted to the Mailing Vendor's FTP site.

Date Calcuations

Each workflow step can be dependent on zero or more predecessor steps, and each can be configured with an estimated duration. Normally, the Completion date = the Start Date + the Estimated Duration. 

Each workflow step includes six dates:
  • Estimated Start: the computer-determined start date of a step, determined as the completion date of the last predecessor to be completed
  • Projected Start: a human override of the estimated start
  • Actual Start: the date the step was actually started (DecisionStep/Start was called)
  • Estimated Completion: the computer-determined completion date of a step, based on a 'ReferenceDate'. If no reference date is defined, the start date is used.
  • Projected Completion: a human override of the estimated completion
  • Actual Completion: the date the step was actually completed (DecisionStep/Complete was called)
Note that reference date calculations do not occur until DecisionStep/Start is called. Thus, if you have asynchronous steps, they will initially have an estimated completion date based on the step's start date.  Once the step's Start method has been called, the Estimated Completion date will be recalculated in relation to the reference date. This is because step completion dates are initially calculated in bulk in the data tier, but the reference date calculations rely on XPath expression evaluation done in the application tier.

Changing Templates with Existing Workflows

As workflow template evolve, power users will need to weigh the impact of changing existing workflow templates versus creating entirely new templates. Assume we have a simple workflow comprising the following steps:

 Original Workflow TemplateNew Workflow Template 
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Case Closed
  • Vendor Paid
  • Referred to Vendor
  • Important Step 1
  • Notification Step 3
  • Notification Step 4
  • Case Closed
  • Vendor Paid

In short, we've decided that Unimportant Step 2 no longer needs to be tracked, but we wish to start tracking a Notification Step 4.

Further assume we have existing sample workflows based on this template:
 Workflow 1 (closed)Workflow 2 (recently opened)Workflow 3  (in progress)Workflow 4 (in progress)
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Case Closed
  • Vendor Paid
  • Referred to Vendor
  • Important Step 1
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Case Closed

When adding a new step to a workflow template:
  • if an existing workflow is closed, calling Decision/Process will do nothing, so the new step will not be added to an existing closed workflow
  • if an existing workflow is open, but the new step's dependencies have not been met, the new step will not be added until it's dependencies have been met
  • if an existing workflow is open, and the new step's dependencies have been met, the new step will be added the next time Decision/Process is called
When deleting a step from a workflow template:
  • existing workflows that already have the step completed will retain the step
  • existing workflows that do not yet have the step will never get the step
  • existing workflows that already have the step, but the step is not yet completed, will retain the step, and the step must be manually completed
Thus, deleting Unimportant Step 2 and adding Notification Step 4 will affect the existing sample workflows as follows:

 Workflow 1 (closed)Workflow 2 (recently opened)Workflow 3  (in progress)Workflow 4 (in progress)
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Case Closed
  • Vendor Paid
Unchanged, since it is closed.
  • Referred to Vendor
  • Important Step 1
Unchanged: it will never have the Unimportant Step 2 added, and it will have Notification Step 4 added after Notification Step 3 is complete.
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
Unchanged: Unimportant Step 2 has already been completed, and will be left alone. Notification Step 4 will be added when Notification Step 3 is completed.
  • Referred to Vendor
  • Important Step 1
  • Unimportant Step 2
  • Notification Step 3
  • Notification Step 4
  • Case Closed
Changed: Unimportant Step 2 has already been completed, and will be left alone. Notification Step 4 was added (by calling Decision/Process), and needs to be 'back filled', if appropriate.

In the Workflow 4 example, a business question arises: should Notification Step 4 be "back filled" or not?  Note that the number of workflows affected by this question are limited:
  • Already closed workflows are not affected, so no back fill consideration needs to be made
  • Open workflows that have not yet progressed to the new step have no back fill consideration; the vendor will complete Notification Step 4 in the "normal course of business"
  • Thus, open workflows that have progressed "past" Notification Step 4 are subject to back fill consideration
There are three possible answers to the back fill question:
  • They do not need to be back-filled (don't make the vendor do the work): in this case, update the Notification Step 4 steps to be complete via a query
  • They must all be back-filled (vendor needs to do the work for in-process workflows): in this case, leave the Notification Step 4 alone, and it will appear in Smart Worklists, task lists, etc.
  • The answer depends on the individual workflow: in this case, instruct the vendor to use their "best judgement"
If the changes to the workflow template include many new steps, many deleted steps, or a significant change in dependencies between steps, the back fill question tends toward the "it depends" scenario. In such cases, consider creating a new workflow template and deprecating the old workflow template instead of tasking the vendor (or power user) to try to think through all the "it depends" business scenarios.

Tracking Stalled Steps

In some circumstances, improper configuration can result in 'stalled' decision. A stalled decision is one where:
  • There is one or more pending step(s) where all predecessors have been completed, and
  • There is no queued call to Decision/Process
These steps can be managed by:
  • View all stalled steps: Decision/DecisionStep.ashx/StalledSteps?Output=Xml
  • Requeue all stalled steps: Decision/DecisionStep.ashx/StalledStepsRequeue


Restarting a Decision

A restart can be performed on a decision whereby the user can choose which step they want the decision to restart at.   A new Decision is created and all steps prior to and including the restart step get copied over to the new workflow.  The current Decision gets cancelled and the decision status gets set to “Restart”.  A message is created on the object represented by the Decision.Object/ObjectID indicating a restart has occurred.

Decision/Restart can be performed from the front-end or as a step in the workflow.

Front-end performed from:

  • Decision/Summary page options menu on the summary panel
  • DecisionStep/Search panel options menu

Parameters for performing a restart:

  • ID – DecisionID for the workflow that you are restarting
  • ActualStart – The start date being used for the restart
  • BodyText – The message content that will get added to the Decision.Object/ObjectID showing what was restarted
  • DecisionStepID – (Optional) The DecisionStepID for the step you want to restart your workflow after.  All prior steps will get copied over to the new workflow inclusive of the current step.  If this is not passed in then none of the steps from the previous Decision are copied over to the new Decision.
Example: Decision/Restart? ID={DecisionID}&DecisionStepID={//DecisionStepItem[DecisionStep='StepA']/DecisionStepID}&ActualStart={StartDate}&BodyText=Workflow Step Restart

Comments