Task API - quandis/qbo3-Documentation GitHub Wiki

The QBO Tasks module encompasses creation, management and completion of tasks. Features include:

• Creation of forms (from simple to very complex) for users to complete
• Management of work lists, including load balancing, automated assignment, and performance tracking
• Auditing work performed

Classes

Class	Description
ImportForm	Used to track an individual task, including values of user-defined fields.
ImportFormTemplate	Template table used to define the behavior of tasks, including the definition of user-defined fields and how to render the GUI for a task.
ImportFormQuestion	Defines the behavior of a user-defined field
SmartWorklistTemplate	Template table used to defined the behavior of worklists and worklist items.
SmartWorklist	A group of related work items
SmartWorklistMember	An instance of a work item

Tasks

A task as a web form (a checklist, perhaps?) that must be completed by one or more users. If a task can be completed by just one person, then the task will have precisely one work items. If a task must be completed by multiple people, there will be a work item for each person that must contribute toward the completion of the task.

Define a task template

/Decision/ImportFormTemplate.ashx/Save?ImportFormTemplate=Task A&AppliesTo=Organization

Not all tasks should be children of all objects. A 'Vendor Review' task may apply to an Organization, while a 'Loan Review' task may apply to a Loan. When defining templates, developers should consider what sort of parent objects a task instance should be bound to.

Add a task

Add a task to Organization where the OrganizationID=27. The response will include the newly created ImportFormID.

/Decision/ImportForm.ashx/Save?Object=Organization&ObjectID=27&Template=Task A

Note: when adding generic objects like tasks, workflow, messages, documents, etc., the method signature follows the pattern Object={ClassName}&ObjectID={Identity}&Template={Template}.

Complete a task

/Decision/ImportForm.ashx/Save?ID=699&ActualCompletion=1/1/2017

Complete a task with user-defined fields

/Decision/ImportForm.ashx/Save?ID=699&ActualCompletion=1/1/2017&FieldA=Foo&FieldB=Bar

Note that any form parameters not recognized by QBO will be automatically saved to the ImportForm.XmlData column as part of an XML fragment.

If you wish to remove MyCustomField from the XmlData, you call:

ImportForm.ashx/Save?ID=12345

This can present a problem if ImportForm/Save is called via an API call where the originating system does not know the existing fields in XmlData. To avoid removing fields accidentally from XmlData, simply pass a MergeXmlData parameters:

ImportForm.ashx/Save?ID=12345&MergeXmlData=1

This will not remove existing XmlData fields just because they're missing from the request.

The reason for this behavior is simple: check boxes! When rendering a check box as an HTML form element, a checked check box is passed over the wire, but an unchecked check box is not. In order for check boxes presented in the UI to behavior properly with XmlData, QBO assumes that the lack of an element in the request data means that it should be removed. This is a good assumption for the majority of Task API calls, which are made from the a UI which renders things like check boxes.

Use of the MergeXmlData allows third parties to control which behavior they want.

Create tasks from spreadsheets

The TaskEngine IImportEngine will create task templates and tasks on demand. For example, importing a spreadsheet using the TaskEngine like this:

Template	Loan	FieldA	DateB
My Sample Task	12345	Here	1/1/2001
My Sample Task	23456	There	2/1/2001
My Sample Task	34567	Everywhere	3/1/2001

Will result in:

• Creation of a template (ImportFormTemplate) named 'My Sample Task'
• Creation of two questions (ImportFormQuestion'):
  • FieldA: string
  • DateB: datetime
• Ensuring 3 loans (12345, 23456, and 34567) exist (they will be created if needed)
• Creation of 3 tasks
• Creation of a SmartWorklistTemplate (also named 'My Sample Task')
• Creation of a SmartWorklist (current worklist of My Sample Task items)
• Creation of 3 SmartWorklistMember rows: 1 for each task created

Querying Tasks with User-Defined Fields

The ImportForm/ExecuteFlat method will transform user-defined fields into traditional columns when generating output. Given as task named 'Quote' with the following user-defined fields:

• QuoteDate
• QuoteAmount

The following call:

api/importform/executeflat?Operation=Search&ImportForm=Quote

will include QuoteDate and QuoteAmount as columns.

The ImportForm rows return may have heterogeneous XmlData: a new column will be output for each distinct node in the xml.

Smart Worklists

Every form you create will automatically have a Smart Worklist created in conjunction with it (though not all Smart Worklists need to be forms-based).

Features include:

• Matrix assignment of Team, Person and Priority enabled you to control load balancing
• Users can be preassigned work, or assigned work as they complete items
• Managers can change priorities, teams or users assigned to item individually or in bulk
• Dashboards show throughput and completion rates by team, individual and worklist

When a form is created (by a user, by a workflow, or by an API call), a work item is queued, with the team, person and priority optionally determined by a Matrix.

Measuring Work

The Worklist dashboard includes a view of tasks by Worklist, Team, or Person, with columns for:

Column	Description
Items	Total number of items assigned to a worklist, team or person.
Queued	Items that are queued to be done, but no one has started working on.
Started	Items that someone has started working on, but not yet completed.
Skipped	Items that someone started working on, but not yet completed, and has been 'delayed' as they work on other items.
Completed	Items that have been completed.
Cancelled	items that have been cancelled.

The worklist detail panel includes filters for:

Filter	Description
All	Show all work items (no filter).
Cancelled	Show cancelled work items.
Completed	Show completed work items.
Pending	Show queued, started and skipped work items (there's still stuff to be done!).

The Performance tab breaks down 'inflows' and 'outflows' for worklists, teams or people over time by measuring:

Field	Description
Starting	Number of pending work items when the time period started.
Queued	Number of work items added during the time period.
Completed	Number of work items completed during time period.
Ending	Number of pending work items when the time period ended.

Assigning Work

QBO clients frequently ask how work items are divided among users, including questions about handing users on vacation, assigning experienced users more work than inexperienced users, and such. Most such questions assume that work items are pre-assigned to individuals. While pre-assigning users is certainly easy to configure with QBO, it is not recommended. Instead, users should be assigned work 'on demand', by clicking on the Worklist > Next Item (SmartWorklistMember.ashx/NextItem) from the main menu. This assigns work to a user only when they indicate they're ready to begin the work, obviating the need to manage vacation schedules, long lunches, or getting stuck working on a particularly complex work item for a long time.

Of course, not all work items should be worked on by all users. Work items may be pre-assigned to Teams (groups of users), and if it is, a user must be a member of the team to be eligible to work on the worklist item. Users may be members of multiple teams, and in fact their team membership can be prioritized. For example, [email protected] may be assigned to:

• Team 'Auditors' with a priority of 1
• Team 'Processors' with a priority of 2

This means that [email protected] will always be routed to work items assigned to the Auditors team until all such work items are done, at which point she becomes eligible to work on items assigned to the 'Processors' team.

The Next Item command will perform several possible functions:

• If the user is already assigned to a worklist item, the highest priority item will be started if necessary, and they will be directed to that item
• Otherwise, a user will be assigned to a worklist item, it will be marked as started, and they will be directed to that item, with the following priority:
  • Team priority
  • Worklist item priority
  • Worklist item sequence,
  • Worklist item due date
  • Worklist item created date

Team, Priority, and even Assigned Person may be defined in a Matrix, so when a worklist item is created, the Matrix output determines the team, priority, and/or person assigned.

Managing Worklists

The Worklist > Manage Worklists dashboard can be used to manage worklists by worklist, person or team. From this dashboard, the following commands may be issued:

• Complete Items: this will mark work items complete, without actually routing a user to the appropriate screens. Access to this method is typically very restricted*.
• Assign Items: used to manually assign a Team or Person to selected work items
• Auto-Assign Items: used to assign items via a Matrix (the matrix is defined from Design > Smart Worklists, when selecting a Smart Worklist Template)
• Re-Queue Items: this unassigns selected items, and NULLs out their Start Date if they've been marked Started. For example, a user has to leave work abruptly.
• Cancel Items: this will mark work items cancelled. Access to this method is typically very restricted*.
• Restart Worklist: over time, worklists become cluttered with completed items. Restart creates a "fresh" worklist as follows:
  • closes the current worklist,
  • creates a new worklist,
  • copies items that have not been completed or cancelled to the new worklist
  • optionally unassigns people (by default, people will be unassigned)
  • optionally unassigns teams (by default, teams will remain the same)
  • calls Auto-Assign for all items in the new worklist
• Cancel Worklist: marks the entire worklist as cancelled, so no work items are eligible when users click on Next Item

Warning: completing or cancelling a worklist item does not complete or cancel the underlying 'work'. For example, completing a worklist item does not complete an underlying task, as doing so may cause problems by:

• bypassing javascript-enforced logic, such as required fields on the task, or
• bypassing requirements for users to add comments when changing the dates of a task Typically, if ones needs to bulk-complete tasks and ignore the risks associated with such a step, one can do so from ImportForm.ashx/Home.

Sticky Assignment

Frequently, multiple work items may be associated with the same parent object. For example, a Loan may have several tasks assigned to it, or a Process may have many tasks assigned to it. In some cases, it may be useful for the same person to work all tasks associated with an object. The Smart Worklist Template "Sticky Assignment" option allows you to specify this. If a worklist is defined as sticky, task-based work items will be assigned as follows:

• If the task is assigned to a person, that person will be assigned to the worklist item
• If the task was created by a workflow, and the workflow has been assigned to a person, that person will be assigned to the worklist item
• If there is another item in the same worklist already assigned, the same assignment will be created for the new task

Query-based Worklists

Task-based worklists are certainly convenience, but do not cover all use cases. Other use cases might include:

• For a 'Loan Modification Audit' requirement, route members of an Auditing team to the Loan summary page, so they may review and annotate with messages
• For a 'Foreclosure Sale Review' requirement, route members of a FC Sale Review team to a Sale Prepared custom form, so they have audit the work already done

Since these uses cases do not have a 1:1 correspondence to tasks, the SmartWorklist/Calculate method will be used to create Smart Worklist Members. The power user must determine the criteria to determine which records are eligible to be included in the Smart Worklist; the Calcualte method will take care of ensure there are no duplicates, and cancelling worklist members if the corresponding record no longer meets the criteria of the worklist.

Power users configure the SmartWorklist/Calculate as follows:

• From Design > Smart Worklists > {Template}, choose Options > Edit, and enter:
  • Object: the name of the object being worked on (e.g. Loan, ImportForm, etc)
  • CalculateMethod: the parameters used to identify which objects to work
  • MemberUrl: relative URL to route the users to

Example: Loan Modification Audit

To route users to a Loan Summary page to audit Loans pending a Loan Modification, we will create a PendingLoanModification filter on the Loan table. From Design > Configuration > Modules > Loan, choose the Filters tab, and add a new filter:

• Name: PendingLoanModification
• Clause:

EXISTS (SELECT 1 FROM LoanModification WHERE LoanModification.LoanID = Loan.LoanID)

Configuration of the Smart Worklist Template would include:

• Object: 'Loan'
• CalculateMethod: SqlFilters=PendingLoanModification
• MemberUrl: Mortgage/Loan.ashx/Summary?ID={SourceObjectID}

Example: Foreclosure Sale Review

We will assume this requirement is a bit more complex, including:

• include only loans with a Sale Prepared form completed in the past 3 days
• limit to Loans with a UPBAmount greater than $350,000
• exclude Loans with 'Goldman', and 'BlackRock' as investors

Since the intention is to audit an existing form, configure a ScoreTemplate to handle the Audit:

• Design > Scores, choose Options > New Template
  • Template: Foreclosure Sale Review
  • AppliesTo: ImportForm

Configuration of the Smart Worklist Template would include:

• Object: ImportForm
• CalculateMethod: ImportForm=Sale Prepared&Loan

This will route users to audit a Sale Prepared custom form.

Naming a Worklist Item

When work items (SmartWorklistMember rows) are created for tasks, they inherit the name of the task. For example, if a task is called Document Approval, the work item will (by default) also be called Document Approval.

Work items may be renamed to include more descriptive information, if required. The Smart Worklist Template's MemberFormat field can data-drive the name of a work item. Assume we have a Document called Acme Service Contract, and under this document is a task called Document Approval. Given this, you may use:

• {Label} => work item is named 'Document Approval'
• {GrandParent} => work item is named 'Acme Service Contract'
• {GrandParent}: {Label} => work item is named 'Acme Service Contract: Document Approval'
• {GrandParent}: Approval => work item is named 'Acme Service Contract: Approval'

One may change the default behavior for all work items from Design > Configuration > Modules > Smart Worklist, Settings tab, SmartWorklistMemberFormat default setting.

Auditing

Any worklist can be audited to verify compliance with your internal policies and procedures.

For example, you may take an existing worklist, and create an auditing rules like:

• have a supervisor team audit 10% of the forms completed as part of Document Review
• have a training team audit 25% of the forms completed by employees who have been on the job for less than 6 months
• have a financial specialist team audit 50% of accounts over M, 25% of account between 50K-M, and 5% of all others

When an auditor drills down into an audit work item, they see the form they are auditing with a floating window asking them to 'score' the work done. These scores are created by power users.

Status Based Routing

A common use case is to submit a task for review and approval. Implied in such a use case is the possibility of rejection, or requiring a submitter to re-work the task to provide amplifying information. Thus, a single form may appear to multiple work lists, for multiple people, as it transitions between statuses.

Implementing this requirement in QBO is best done by:

• Create a series of custom statuses for the task, representing the possible ‘flow’ of the task
  • e.g. Processor Review, Supervisor Review, Manager Review, Rejected, Accepted
• Create a series of state transitions, representing what role is allowed to transition from one status to the next
  • Processor Review => Supervisor Review // submit for approval
  • Processor Review => Rejected // anyone can reject a task
  • Supervisor Review => Processor Review // supervisors can kick a task back to a processors
  • Supervisor Review => Manager Review // supervisors can submit a task for manager approval, but processors cannot
  • Supervisor Review => Rejected // anyone can reject a task
  • Manager Review => Accepted // only managers can accept
  • Manager Review => Rejected // anyone can reject a task
  • Manager Review => Supervisor Review // managers can kick a task back to supervisors
• Adding a call to RenderStatusButtons template
  • This will render ‘save’ buttons labelled for each transition currently allowed, based on the current status and the user’s role

When an Import Form record is updated, QBO will:

• Raise an error if the transition is not allowed (e.g. Process Review => Approved)
• Complete any Smart Worklist Members bound to the task matching the old status
• Insert a new Smart Worklist Member bound to the task matching the new status