Dovetail Agent Documentation

Task Manager

Task Manager is an optional module that allows actions to occur automatically when a task set is selected from a case. The most common action is creating a subcase.

For example, when the New Employee Task Set is run:

Create a General subcase for setting up the employee's network account and dispatch to the Network queue.
Create an Administrative subcase for ordering business cards and assign to a specific employee.
Create a General subcase for creating the user's account in the CRM system, and dispatch to a queue based on auto-destination rules.

Dovetail Agent can work with either Clarify Task Manager or Dovetail Task Manager.

Dovetail vs. Clarify

Task evaluation

Clarify: Tasks are evaluated within the Clarify Classic Client itself, or via the Task Manager executable (tskmgr.exe).

Dovetail: Tasks are evaluated within Dovetail Carrier.

Actions

Clarify: Create Subcases, Create Action ItemsDovetail: Create Subcases, Customizable to perform other actions

Applications involved in Task Manager

Clarify: Clarify Classic Client, Rulemanager, Task Manager executable (tskmgr.exe)

Dovetail: Dovetail Agent, Dovetail Carrier, Dovetail Admin, Dovetail Rulemanager

Schema

Clarify and Dovetail use completely different schema for managing tasks, task sets, and task properties.

Clarify: cls_group, cls_factory, stage_task, task_set, cls_factory, cls_opn, cls_ref

Dovetail: dt_task, dt_task_set, dt_property_template, dt_configured_property, prop_name

Clarify Task Manager

Clarify Task Manager is an optional module that allows subcases and action items to be automatically created when a task set is selected from a case.

Clarify Task Manager and the Clarify Classic Client

Within the Clarify Classic Client, this process is started by clicking the Jobs button on a case, and then selecting a Task Set to be executed. The Clarify Client then evaluates the task set and creates the subcases and action items as needed.

Clarify Task Manager and Dovetail Agent

Within Dovetail Agent, this process is started by choosing the Workflow - Run Task Set menu item on a case, and then selecting a Task Set to be executed. User's must have the Task Manager privilege in order to see this menu item. Dovetail Agent itself does not evaluate the task set and create subcases. Instead, Dovetail Agent creates a time bomb, which fires the a business rule. Rulemanager processes this business rule which calls out to Clarify's tskmgr.exe. The Run Clarify Task Set business rule is what makes this happen. Have a look at the business rule to see how it functions.

Administration of Task Sets for Clarify Task Manager

Task Definitions and Task Set Definitions are setup using the Policies and Customers module within the Clarify Classic Client.

Dovetail Task Manager

Dovetail Task Manager is an optional module that allows subcases to be automatically created when a task set is selected from a case. Dovetail Task Manager is also extensible using customization, allowing it to perform other actions, within the Clarify/Dovetail system itself, or even as a mechanism for integrating with other systems.

Process

Within Dovetail Agent, this process is started by choosing the Workflow - Run Task Set menu item on a case, and then selecting a Task Set to be executed.
Dovetail Agent creates a time bomb in the database
Rulemanager pickes up this time bomb, and executes the Run Dovetail Task Set business rule, which sends a message to Dovetail Carrier.
Dovetail Carrier receives the message, which tells it which Task Set to execute
Carrier retrieves the Task Set and related Tasks from the database
For each task in the set:
- Retrieves Task from database
- Resolve each Task Property
- Create subcase (or perform custom action)
- Perform workflow (assign/dispatch/auto-dispatch/etc.)

Migrating from Clarify Task Manager to Dovetail Task Manager

Dovetail Agent ships with a script for converting Clarify Tasks/Task Sets/Properties to Dovetail Tasks/Task Sets/Properties. Details of this script are listed below.

Applications

The following applications are involved in the Task Manager process

Dovetail Agent - setup of tasks, task sets, and task properties; Run Task Set action on cases
Dovetail Admin - setup of business rule which fires when the Run Task Set event fires
Dovetail Rulemanager - evaluates business rule, sends message to Dovetail Carrier
Dovetail Carrier - receives message, evaluates Task Sets and Tasks

Managing Tasks and Task Sets

Tasks and Task Sets are managed within Dovetail Agent. The Tasks privilege is required.

Managing Task Property Templates

Task Property Templates are managed within Dovetail Agent. The Task Property Templates privilege is required.

Important note! It is recommended that managing Task Property Templates should be performed by a System Administrator / Technical Resource on your project. Managing templates requires intimate knowledge of the Clarify schema and the underlying APIs used when Carrier performs actions.

Dovetail Agent Privileges

Task Manager - required to access the Run Task Set action on a case
Tasks - required to manage Tasks and Task Sets
Task Property Templates - required to manager Task Property Templates

Schema

The following tables are used by Dovetail Task Manager:

dt_task - defines the task action
dt_task_set - groups tasks together
dt_property_template - defines a template to be used when configuring properties
dt_configured_property - defiens an instance of a configured property, i.e. what value should this property be set to.
prop_name - business rule properties, defines case properties that can then be set on a subcase

Requirements

Dovetail Agent version 10 or higher
Dovetail Admin version 3.5 or higher
Dovetail Carrier version 2.0 or higher
Dovetail Rulemanager version 2.0 or higher
Dovetail Task Manager license key

Install / Setup

Apply schema changes using Dovetail SchemaEditor and taskmanager.schemascript.xml schema file
Import TaskManager.dat file
Assign Privileges

Assign the privileges to the appropriate privilege classes using Dovetail Admin

Important note! It is recommended that the privilege for managing Task Property Templates should be only be granted to a System Administrator / Technical Resource on your project. Managing templates requires intimate knowledge of the Clarify schema and the underlying APIs used when Carrier performs actions.
Review Business Rule (included in TaskManager.dat)

The important components of the business rule are:
- Object Type: Cases
- Start On Event = Run Task Set
- Action Message Type: Carrier Message
- Message:
```
type=RunTaskSet
caseId=[Object ID]
taskSetName=[Task Set Name]
```
Dovetail Carrier setup

Use Dovetail License Installer (provided with the Dovetail SDK) to install the Dovetail Task Manager license key into your database
Dovetail Rulemanager setup

If Dovetail Carrier is installed on a different machine than Dovetail Rulemanager, then edit the FChoice.RuleManager.WindowsService.exe.config file, setting the value of the Carrier.QueueAddress key with the correct server name/address.
Review auto-destination rules

If your tasks will use the Auto-Assign or Auto-Dispatch workflows, review your existing auto-destination rules and adjust if necessary. Task Manager uses the ASSIGN and DISPATCH operations of auto-destination rules. If an auto-destination rule does not resolve to any queue (for auto-dispatch) or to any user (for auto-assign), then a warning will be logged and the item will not be assigned nor dispatched. If an auto-destination rule resolve to multiple queues (for auto-dispatch) or to multiple users (for auto-assign), then a warning will be logged and the item will be routed to the first item in the list.

Migrating from Clarify Task Manager to Dovetail Task Manager

Business Rules

Inactivate any existing business rules that have an action that calls the Task Manager executable (tskmgr.exe)

Conversion script

Dovetail Agent ships with a script for converting Clarify Tasks/Task Sets/Properties to Dovetail Tasks/Task Sets/Properties.

Conversion Script Requirements/Setup:

Dovetail SDK. Must be installed, as this script uses the SDK via COM.
Dovetail Task Manager schema must be applied to database
Dovetail Task Manager data (from DAT file) must be applied to database
Edit the fc.env file for your environment

The script is executed from a command line:

cscript main.wsf

Note: If cscript throws an error such as: There is no script engine for file extension ".js". Then use the //E option of cscript to specify the script engine to be jscript. Example: cscript //E:jscript main.wsf

Validate, preview, then convert

Validate data in database
```
cscript main.wsf  /validate
```
If any errors are listed, they must be resolved before preceeding.
Preview converting Clarify Tasks & Properties to Dovetail Tasks & Properties
```
cscript main.wsf  /tasks /verbose /preview
```
Convert Clarify Tasks & Properties to Dovetail Tasks & Properties
```
cscript main.wsf  /tasks /verbose
```
Preview converting Clarify Task Sets to Dovetail Tasks Sets
```
cscript main.wsf  /tasksets /verbose /preview
```
Convert Clarify Task Sets to Dovetail Tasks Sets
```
cscript main.wsf  /tasksets /verbose
```

Customizing Dovetail Task Manager

Dovetail Task Manager is extensible using customization, allowing it to perform other actions, within the Clarify/Dovetail system itself, or even as a mechanism for integrating with other systems.

Dovetail provides example code for customizing Task Manager.

Custom action

Out of the box, Task Manager supports one action - Create Subcase. The first example walks through how to add a custom action for a task. Specifically, it will show how to add an action named Get Stock Quote, that will call an external web service to get a stock quote. The quote will be logged as a note to the case.
Custom Message Type

Out of the box, Task Manager fires a business rule with an action of Carrier Message. The business rule action message content specifies type=RunTaskSet Rulemanager turns this into an actual message, and sends it to Carrier. Out of the box, Carrier only knows how to process these messages with a type of RunTaskSet. The second example walks through how to add a custom type, allowing Carrier to perform a custom action, completely independent of Task Manager. Specifically, it will show how to add a type of GetStockQuote, that will call an external web service to get a stock quote.

These examples, including code and documentation, are located on Github.com.