Introduction

Dovetail Agent brings the power of your Clarify system to the web, replacing the legacy Clarify Classic Client.

Dovetail Agent's UI has been updated with a clean new style that incorporates many of the usability features that have become standard in today's popular web applications, allowing new users of the system to reach proficiency more quickly than ever. The application enables a wide range of efficient customer support operations with the following core features:

What's New

Version 11.0.0

Enhancements

Old New Purpose
m l+e Log Email
n l+n Log Note
k l+c Log Commitment
r l+r Log Research
m+r Reply to latest Email
m+a Reply All to latest Email
m+f Forward latest Email

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 11.0.0

  1. Apply Schema Changes

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Import Data Files

    Import these data files found in the $dovetailAgent\source\config\dat directory:

    • canned-responses.dat
    • agent_support_data.dat

  3. Review the new LogEmailReplySettings.IgnoredAddresses application config setting, and set its value properly for your environment. This is to help prevent email loops.

  4. [OPTIONAL] Grant the Quick Close Case and Quick Close Subcase privileges to the desired privilege class(es) using Dovetail Admin.

  5. Merge in your customizations with the baseline 11.0.0 source code

  6. Build / Test / Release / Deploy

Previous Versions

Version 10.0.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 10.0.0

  1. Install Dovetail SDK version 3.4 or higher.

    IMPORTANT CHANGE: Subcase ID Number generation within the Dovetail SDK is now handled by a new stored procedure (fc_next_subcase_seq). This stored procedure needs to be compiled to your database. Refer to the Dovetail SDK documentation for more details.

  2. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  3. [Optional] Setup Dovetail Task Manager

  4. Merge in your customizations with the baseline source code.

  5. Build / Test / Release / Deploy

Version 9.0.2

Bug Fixes

Upgrading to Version 9.0.2

  1. Merge in your customizations with the baseline source code.

  2. Build / Test / Release / Deploy

Version 9.0.1

Enhancements

Bug Fixes

Upgrading to Version 9.0.1

  1. Merge in your customizations with the baseline source code.

  2. Build / Test / Release / Deploy

Version 9.0.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 9.0.0

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Update the resource_key column in the dt_resource table using SQL

    update table_dt_resource set resource_key = SUBSTRING(store_uri,LEN(store_uri) - CHARINDEX('/',REVERSE(store_uri ))+ 2,LEN(store_uri)) where resource_key is null

  1. Install NumberOfTags SQL function

    There is a new SQL function required: NumberOfTags, which returns the number of tags that a user has on a given object. This function is dependent on your specific schema. In order to facilitate different schemas amongst different customers, we have provided a utility for compiling this function.

    First, edit {dovetailAgent}\utilities\sql\InstallSqlTemplates.exe.config file

    1. Set fchoice.dbtype to either MSSQL or Oracle, depending on your database type.
    2. Set fchoice.connectionstring to a valid connection string for your database.

    Second, from a DOS prompt:

    1. DOS> cd {dovetailAgent}\utilities\sql\
    2. DOS> InstallSqlTemplates.exe ..\config\sql\{database}\

This should complete without any errors.

  1. Merge in your customizations with the baseline source code.

  2. Build / Test / Release / Deploy

  3. If using Dovetail Seeker as a Resource Store for images, upgrade Dovetail Seeker (to version 2.4 or higher) and Dovetail Rulemanager (to version 1.6 or higher).

Version 8.0.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Change to webpack for script compilation

Agent has moved from requirejs to webpack for script compilation. While this move was nontrivial, it brought many long-term benefits.

Running in dev mode will compile the project into 1 script

It will no longer rely on requiring all of the scripts on page load (>600 requests) which made for a slow developer loading experience. Instead, webpack compiles all of the scripts into one script and loads that, even in dev mode. Debugging is not hindered, though, as webpack creates a source map so that files can be easily accessed and debugged.

Webpack allows for different dependency styles

RequireJS was great as a dependency manager, but since then better and more straight-forward solutions have come up, such as Commonjs. Webpack allows for code that use either style to co-exist with each other. This means you can choose between either style based on preference and webpack will just work to compile the scripts correctly.

Webpack allows for new technologies

Moving to webpack opens the doors to using the latest and greatest javascript features, namely ES6. It does this by allowing us to pass es6-specific code through a "loader" that translates it down to es5 and then compiles it. Instead of longingly drooling over the new es6 features, you can actually use them!

Webpack allows for removing Bower

We now solely rely on npm to handle javascript dependencies. Adapting your code for this change will be discussed below

Cache Buster

We no longer need to leverage cache busting due to the way resources are loaded now, i.e. directly via the browser instead of asynchronously via Requirejs. Because of this, you won't see any _={cacheBuster} suffixes on the requests in dev mode. There are still suffixes on ajax requests, but that is managed through jquery and only happens on XHRs.

Some important notes about moving to webpack
Change in handling localization

In your templates, you should no longer use the syntax {{$ LOCALIZED_STRING }}, but instead {{i18n "LOCALIZED_STRING"}}. This is because our previous localization strategy ({{$) was provided by a requirejs plugin that we no longer use. It was also not possible to override $ as a handlebars helper. Here's a regex you can use to find all occurrences in your code that need to be updated: {{\$\s+([\w_]+)\s*}}

agentLang, underscore, jquery should no longer be dependencies

Another benefit of webpack is it allows for declaring "global" variables that can be accessed from different modules without explicitly declaring a dependency. agentLang, _, and $ are now "globals" and no longer need to be called out as dependencies. Using these variables in your scripts will just work

Remove all occurrences of hbs! in template includes

Webpack will automatically handle compiling templates correctly (via a handlebars-loader), meaning that template dependencies no longer need the hbs! prefix.

Handlebar helpers should only return a function

If you have created any custom handlebar helpers, be sure to update them so that they just return a function instead of registering the helper with handlebars. See the helper editFor as an example

Localization handling has changed

Webpack will now create a script per localization that has the locale prefix in the name, e.g. en.bundle.js. To enable a localization, make sure a json file with the correct localizations exists and add a line to the languages hash in the webpack.config.js file.

No more Bower

Moving to webpack made removing bower possible, and using 1 package manager instead of 2 seems smart. With that, if any dependencies have been added to bower.json, be sure to move them over to the package.json file under the dependencies hash instead. You will also need to add aliases to those dependencies in the webpack.config.js file if you had added aliases in the requirejs config file for these new dependencies.

New npm scripts

To make the developer setup and experience easier, we have moved the most common dev tasks to npm scripts for the frontend. This means you no longer are required to have gulp installed globally and can run npm scripts instead of gulp tasks to setup the environment. Below is a list of possible npm scripts and a summary of what they do:

If you use LiveReload in your dev flow, this is still supported. To enable watching for webpack, run npm run webpack -- --watch. This is a continually running task that does a first compilation (~20s), and then very quick iterative builds as javascript files change.

Tab Badge Enhancements

The tab component has been updated to allow for richer badges. To make use of these enhancements, adjustments need to be made to both the initial count passed to the tab, and how the badges are updated (usually via a collection reset event).

The count variable can now be one of a number of types.

In addition to these types, the initial count passed in the tab configuration object can be a function that returns any of the above types

When updating complex badges, you will need to use either the reset collection event or manually trigger update:count on the tab's object. Triggering update:count will not do any post-processing of the value as that should already have been done (e.g. collection.trigger('update:count', [1, 'new', { total: 3, type: 'important' }]))). However, the reset event is a little different, so the tab component has added functionality to handle the different possibilities. These include a simple reset that should update the badge based on the collection's length (collection.reset(newItems)), and resets with more complex badges (collection.reset(newItems, [1, 'new', { total: totalResults })).

Supported Node Versions

The Node.js project has experienced a major shift in its management and development speed over the past couple of months. One major change is that they now have an LTS release, code-named "Argon". To better serve our customers, "Argon" will be the version of Node that we will officially support. While other versions both lower and higher may work, these will not be officially supported until we explicitly announce their support. To get the latest LTS release, visit https://nodejs.org/en/ and select the LTS release download link.

Upgrading to Version 8.0.0

  1. Configure rich logs using markdown (email, notes, research) for cases and subcases using the MarkdownSettings.IsRichLoggingEnabled application setting. Requires Dovetail Rulemanager 1.5 or higher for rich HTML outgoing emails.

  2. Merge in your customizations with the baseline source code.

  3. Build / Test / Release / Deploy

Version 7.0.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 7.0.0

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Setup part request searching.

    If using part requests, edit Dovetail Seeker's documentSpecifications.xml file to allow for searching of part request headers and details. Within Seeker's documentSpecifications.xml file, include the part request specifications needed by Dovetail Agent, which are provided in the $dovetailAgent\source\config\seeker.config\part-request-domain-specification.xml file

  3. Import data files.

    • logistics_user_defined_lists.dat
    • agent_logistics_data.dat
    • activity_codes.dat

  4. If using Part Requests (Logistics), grant the Logistics privileges to the desired privilege class(es) using Dovetail Admin.

  5. Merge in your customizations with the baseline source code.

  6. Build / Test / Release / Deploy

Version 6.0.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 6.0.0

  1. Install the .NET Framework 4.5

  2. Merge in your customizations with the baseline 6.0 source code.

  3. Build / Test / Release / Deploy

Version 5.11.0

Enhancements

Changes of Interest to Developers

Upgrading to Version 5.11.0

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Update last modified timestamps for parts and part revisions

Update table_mod_level.x_modify_stmp and table_part_num.x_modify_stmp using the Update Timestamps SQL

  1. Setup part searching.

    If using parts, edit Dovetail Seeker's documentSpecifications.xml file to allow for searching of parts. Within Seeker's documentSpecifications.xml file, include the parts specifications needed by Dovetail Agent, which are provided in the $dovetailAgent\source\config\seeker.config\seeker-part-domain-specification.xml file

  2. Update contact searching.

    Edit Dovetail Seeker's documentSpecifications.xml file to allow for searching of contact email addresses. Refer to the $dovetailAgent\source\config\seeker.config\seeker-contact-domain-specification.xml file for reference Within Seeker's documentSpecifications.xml file:

    • include the email addresses into the contents:

      <contents>
 ...existing paths ...
 <path>e_mail</path>
 <path>contact2e_addr:e_num</path>
</contents>

    • include the email custom field:

       <customField title="email" description="Email Addresses">
   <path>e_mail</path>
   <path>contact2e_addr:e_num</path>
 </customField>

  1. Merge in your customizations with the baseline 5.11 source code.

  2. Build / Test / Release / Deploy

Version 5.10.0

Enhancements

Upgrading to Version 5.10.0

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Install SQL functions

    Dovetail Agent uses user-defined SQL functions for certain operations. The functions are defined in the $dovetailAgent\source\config\sql{database}\toc-queues.sql file. Install these functions to your database.

    MSSQL: sqlcmd -UmyLoginName -PmyPassword -SmyServer -dmyDatabase -i toc-queues.sql

    Oracle: sqlplus myLoginName/myPassword@ora11 @toc-queues.sql

    These should complete without any errors.

  3. Merge in your customizations with the baseline 5.9 source code.

  4. Build / Test / Release / Deploy

Version 5.9.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 5.9

  1. Apply General Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Apply Database-specific Schema Changes.

    The database-specific (mssql/oracle) schema changes to be applied are defined in $dovetailAgent\config\schema\{database}\agent.{database}.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.{database}.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  3. Setup contract searching.

    If using contracts, edit Dovetail Seeker's documentSpecifications.xml file to allow for searching of contracts. Within Seeker's documentSpecifications.xml file, include the contract specifications needed by Dovetail Agent, which are provided in the $dovetailAgent\source\config\seeker.config\seeker-contract-domain-specification.xml file

  4. Merge in your customizations with the baseline 5.9 source code.

  5. Build / Test / Release / Deploy

Version 5.8.0

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 5.8

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Import data files.

    • web_types.dat

  3. Edit Dovetail Seeker's documentSpecifications.xml file.

    Specifically, edit the account specification, changing the idColumnName property from org_id to objid.

    The $agent\config\seeker.config\seeker-account-domain-specification.xml file shows the correct specification.

  4. [Optional] Setup Agent Reporting

  5. Merge in your customizations with the baseline 5.8 source code.

  6. Build / Test / Release / Deploy

Version 5.7

Enhancements

Bug Fixes

Changes of Interest to Developers

Upgrading to Version 5.7

  1. To take advantage of the web.config setting which removes the Server header which identifies that this is an IIS server, install the IIS URL Rewrite on your web server (if its not already installed).

    • Open IIS Manager
    • Click on the Dovetail Agent web application
    • In the middle pane, under IIS, look for URL Rewrite icon
    • If that icon is there, then URL Rewrite is already installed.

  2. Merge in your customizations with the baseline 5.7 source code.

  3. Build / Test / Release / Deploy

Version 5.6

Enhancements

Bug Fixes

Upgrading to Version 5.6

  1. Apply Schema Changes.

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Run upgrade script

    • The upgrade script is located in $dovetailAgent\config\scripts\upgrade\5.6
    • Be sure that the Dovetail SDK is installed on the machine running the upgrade script
    • Edit the fc.env file, defining your database connection information
    • From a DOS prompt: cscript upgrade.js

  3. Import data files.

    • user_impersonation_activity_codes.dat
    • agent_basic_data.dat (for the Impersonate Employee privilege)
    • WorkgroupQuery.dat

  4. Add the canImpersonate custom field to the employee document specification in Dovetail Seeker's documentSpecification file. The custom field specification can be found within the $dovetailAgent\source\config\seeker\seeker-employee-domain-specification.xml file.

  5. Grant the Impersonate Employee privilege to the desired privilege class(es) using Dovetail Admin.

  6. Merge in your customizations with the baseline 5.6 source code.

  7. Build / Test / Release / Deploy

Version 5.5

Enhancements

Bug Fixes

Upgrading to Version 5.5

  1. Merge in your customizations with the baseline 5.5 source code

  2. Build / Test / Release / Deploy

Version 5.4

Enhancements

Upgrading to Version 5.4

  1. Apply Schema Changes

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Import Data Files

    Import these data files found in the $dovetailAgent\source\config\dat directory:

    • agent_support_data.dat
    • commitment-rule-properties.dat
    • commitment-templates.dat

  3. [Optional] Setup Task Manager

  4. Merge in your customizations with the baseline 5.4 source code

  5. Build / Test / Release / Deploy

Version 5.3

Enhancements

Developer Concerns

Upgrading to Version 5.3

  1. Apply Schema Changes

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Merge in your customizations with the baseline 5.3 source code

  3. Build / Test / Release / Deploy

Version 5.2

Enhancements

Upgrading to Version 5.2

  1. Apply Schema Changes

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Merge in your customizations with the baseline 5.2 source code

  3. Build / Test / Release / Deploy

Version 5.1

Enhancements

Bug Fixes

Upgrading to Version 5.1

  1. Apply Schema Changes

    The schema changes to be applied are defined in $dovetailAgent\config\schema\agent.schemascript.xml The easiest way is to simply apply these changes using Dovetail SchemaEditor and the agent.schemascript.xml file - it will add the new schema and skip over any changes that already exist.

  2. Import Data Files

    Import these data files found in the $dovetailAgent\source\config\dat directory:

    • localizations.dat
    • user_defined_lists.dat

  3. Merge in your customizations with the baseline 5.1 source code

  4. Build / Test / Release / Deploy

Version 5.0

Dovetail Agent 5.0 is a completely redesigned user interface and architecture.

On the back end, it uses the FUBU MVC Framework, which is a popular .NET framework for building web applications. It's built on top of the core ASP.NET libraries. The back end is all written in C#. On the front end, is HTML 5, CSS3, and JavaScript. It uses the Backbone JavaScript framework, along with a boatload of other common JavaScript libraries, including Require.js, jQuery, Marionette, Underscore.js, and Moment.js. In short, all leading-edge technologies.

Features

For specific features, view the High-level functional comparison between Clarify and Dovetail applications

Functionality

Functional items of Dovetail Agent worth noting.

Tags

Rather than a workflow item (such as a case or subcase) being in one (and only one) wipbin, Dovetail Agent has the concept of tags. You can tag any workflow item you want with as many tags as you want. These items are easily available from the console and from queries. This allows for more flexibility in how user's organize their work, and allows one to easily get back to any tagged item - such as those items you want to keep an eye on.

Users can manage their tags (rename, delete) from the My Tags page.

Dovetail Agent ships with a script that converts wipbins to tags. Refer to the Convert wipbins to tags section for more details.

Dates

As discussed in Time Zone handling Most dates are displayed in a timeago format, such as 2 days ago or in 11 hours. To view the exact date-time, simply put your mouse over the timeago format, and the exact date-time will be shown.

Time Ago

Avatars

An "avatar" is an image that represents you online—a little picture that appears next to your name when you interact with websites. Throughout the Dovetail Agent application (such as in case history), avatars are used to help identify a user. Dovetail Agent pulls these images from Gravatar based on the email address of the user. A Gravatar is a Globally Recognized Avatar. You upload it and create your profile just once, and then when you participate in any Gravatar-enabled site, your Gravatar image will automatically follow you there.

Avatar

Phone Logs

Since there was very little difference between a Notes Log and a Phone Log, the Phone Log input form has been removed from Dovetail Agent. This simplifies the process for users. Phone logs created from other applications will still be shown as part of the case/subcase history.

Auto-Destination

Auto-destination rules are supported for DISPATCH and ASSIGN operations for cases, subcases, and solutions.

When a user selects the Dispatch workflow operation, auto-destination rules are evaluated.

When a user selects the Assign workflow operation, auto-destination rules are evaluated.

Task Manager

Dovetail Agent supports both Clarify Task Manager and Dovetail Task Manager, although only one can be in use at a given time.

Refer to the Task Manager guide for complete details.

Commitments

Users can create and update commitments for a case or subcase.

There are two ways to create a commitment for a case or subcase:

  1. Choose Commitment from the Log menu, which allows for a Quick Commitment
  2. Click the + icon on the Commitments tab header, which allows for a Full Commitment

Quick Commitment: Select a commitment title from a drop-down list, and a due date.

Full Commitment: Type in a commitment title, due date, reminder, and notes.

Commitment Templates

When a commitment reaches its reminder time, Rulemanager notifies the user using the Warning template. When a commitment expires, Rulemanager notifies the user using the Commitment template. These templates are part of your existing Clarify implementation. Dovetail provides more robust templates in the $dovetailAgent\source\config\dat\commitment-templates.dat file.

My Calendar

Users can access their calendar, which shows commitments (based on the commitment due date) and subcases (based on the due date).

Users can also share their calendar. The Share button on the My Calendar page exposes a public URL for the calendar, which can be given to people they wish to share their calendar data with. Exposes calendar data from 30 days ago to 30 days in the future (Can be configured within application settings). This URL can be imported into a Calendar application such as Microsoft Outlook as an Internet Calendar Subscription.

Impersonation

Dovetail Agent allows a user to impersonate another user. Dovetail calls this Impersonation. Clarify traditionally calls this Switch User.

Impersonation allows a user to essentially login as another user without knowing the other user's password. This is useful for managers to impersonate their employees in order to view their work and commitments, and to re-assign their work when necessary.

Once a user impersonates another user, they can revert the impersonation or log out. Nested impersonations are not allowed - a user cannot impersonate a (third) user while impersonating a user.

Activity Logs are added for both Impersonate and Revert actions, allowing for auditing of these actions.

In order to impersonate another user:

Canned Responses

Canned responses are re-usable text snippets that you can use when logging emails or notes on a case or subcase. Canned responses can save you time if you’re often typing similar responses.

Users can create personal canned resonses, and can also share canned responses to workgroups, or to everyone.

Canned responses can include dynamic properties, such as the Case Title or Status. The list of available properties is the same as the list of business rule properties (excluding properties with a subtype of Alias).

Quick Close

The Quick Close functionality allows a case or subcase to be closed without fronting the Close form (where users select a status, resolution, and enter notes). With Quick Close, the case/subcase is closed without any additional user inputs.

This functionality is controlled by the Quick Close Case and Quick Close Subcase privileges.

Reporting

Dovetail Agent Reporting is an optional reporting module that can be purchased from Dovetail Software. It allows non-technical end users to create and edit reports and dashboards without IT support. For more information, or to obtain this module, contact Dovetail Software.

Broadcasts

A broadcast is used to communicate a message to all users. It will appear in their notification drawer. If a user has the Admin privilege, they can create/edit/delete broadcasts from the Admin page.

Markdown

Markdown is a lightweight and easy-to-use syntax for styling text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like # or *.

If a text area is markdown enabled, it will say Markdown Supported next to it. Clicking on the Markdown Supported link will open a markdown help page.

Markdown support is currently enabled for:

Still have questions?

For more information, or to discuss any of this in more detail, please contact Dovetail Support.

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:

  1. Create a General subcase for setting up the employee's network account and dispatch to the Network queue.
  2. Create an Administrative subcase for ordering business cards and assign to a specific employee.
  3. 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

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

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

Schema

The following tables are used by Dovetail Task Manager:

Requirements

Install / Setup

  1. Apply schema changes using Dovetail SchemaEditor and task-manager.schemascript.xml schema file
  2. Apply database-type-specific schema indexes for task manager using Dovetail SchemaEditor and task-manager.index.{databaseType}.schemascript.xml schema file
  3. Import TaskManager.dat file

  4. 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.

  5. 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]

  6. Dovetail Carrier setup

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

  7. 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.

  8. 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:

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

  1. Validate data in database

    cscript main.wsf  /validate

    If any errors are listed, they must be resolved before preceeding.

  2. Preview converting Clarify Tasks & Properties to Dovetail Tasks & Properties

    cscript main.wsf  /tasks /verbose /preview

  3. Convert Clarify Tasks & Properties to Dovetail Tasks & Properties

    cscript main.wsf  /tasks /verbose

  4. Preview converting Clarify Task Sets to Dovetail Tasks Sets

    cscript main.wsf  /tasksets /verbose /preview

  5. 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.

  1. 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.

  2. 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.

Administrative Concerns

Items that Dovetail/Clarify administrators should be aware of.

Internal Notes

As of Agent 5.0, internal notes are handled differently than previous versions, and differently than the Clarify Client. Traditionally, internal notes are stored in table_notes_log.internal, which is a 255 character field. In Agent 5, internal notes are stored in the same field as regular notes (table_notes_log.description), and the x_is_internal field is set to 1 to indicate that these are internal notes. This removes the 255 character limit of internal notes, and simplifies the application for end users.

However, this can affect SelfService/eSupport/WebSupport style applications, which assume anything in table_notes_log.description is a public note. Because of this change, applications which expose public notes to customers may need to be enhanced to compensate for this new style of internal notes. For more information, or to discuss this in more detail, please contact Dovetail Support.

Time Zone Handling

Any date/timestamps from the database are sent to the client browser in UTC. These timestamps are then converted to the browser's timezone using Javascript. That way all timestamps are presented in the local timezone of the user. When a user enters a date/timestamp, that timestamp is converted to UTC before it is sent to the server. The server then converts it from UTC to the database's timezone The database timezone is determined by the entry in table_time_zone where is_default = 1. All timestamps are stored in the database in that database timezone.

Time Zone of Application User

When logging in as the Application User, this user's timezone will always be UTC, regardless of browser or machine time zone. This is only for the application user.

Requirements

For the most up-to-date platform information, refer to the Dovetail Platform Guide.

Client

The only client requirement is a web browser. Dovetail Agent has been verified to work with the following web browsers:

Server

Operating System

Dovetail Products

Web Server

Clarify Version

Tools

Other Tools

Development

Refer to the Developer Setup page for details on setting up a developer environment.

Install Guide

Review the Requirements

Unzip the agent.zip file

Apply General Schema Changes

The schema changes to be applied are defined in the $dovetailAgent\config\schema directory

Prior to making schema changes, backup the current database.

Use Dovetail SchemaEditor to apply these schema changes.

Apply Database-specific Schema Changes.

The database-specific (mssql/oracle) schema changes to be applied are defined in $dovetailAgent\config\schema\{database}\agent.{database}.schemascript.xml

Use Dovetail SchemaEditor to apply these schema changes.

Install SQL functions

Dovetail Agent uses user-defined SQL functions for certain operations. The NumberOfTags function is dependent on your specific schema. In order to facilitate different schemas amongst different customers, we have provided a utility for compiling this function into your database, along with all the required SQL functions.

First, edit {dovetailAgent}\utilities\sql\InstallSqlTemplates.exe.config file

  1. Set fchoice.dbtype to either MSSQL or Oracle, depending on your database type.
  2. Set fchoice.connectionstring to a valid connection string for your database.

Second, from a DOS prompt:

  DOS> cd {dovetailAgent}\utilities\sql\
  DOS>
  DOS> InstallSqlTemplates.exe ..\..\config\sql\{database}\

This should complete without any errors, as shown here:

  InstallSqlTemplates.exe ..\..\config\sql\mssql
  Found template: ..\..\config\sql\mssql\NumberOfTags.template
  Rendered ..\..\config\sql\mssql\NumberOfTags.template as NumberOfTags.expanded.sql
  Executing SQL: ..\..\config\sql\mssql\NumberOfTags.expanded.sql
  Executing SQL: ..\..\config\sql\mssql\toc-queues.sql

Import Data Files

Import these data files found in the $dovetailAgent\source\config\dat directory:

To import the data files using Dovetail ArchiveManager (DIET) or dataex

Execute the following command:

<importTool> -user_name <user> -password <pass> -db_server <serv> -db_name <db> -imp <file>

where:
<importTool> is the import tool, such as diet.exe or dataex.exe
<user> is the system administrator user
<pass> is the system administrator password
<serv> is the database server name
<db> is the database name
<file> is the name of the file to import. If the <file> is not in the current directory, specify the path to the directory it is in.

Set Up Web Privclasses

Web privclasses allow you to decide which Dovetail Agent operations a specific user (or group of users) may perform. Using Dovetail Admin, you can turn on (or off) virtually any operation in the thin client.

Note: The privileges encompass privileges across multiple Dovetail applications - so not all privileges apply to Dovetail Agent 5.

By default, no operations are initially enabled for any privclasses. You must use Dovetail Admin to grant privileges to users.

To modify the web privclasses:

Update Timestamps

Dovetail Seeker relies on an item's last modified timestamp in order to know when it should be re-indexed. As part of the Dovetail Agent schema, modify timestamp fields have been added to certain entities. These timestamps need to be updated so that Seeker will pick them up to be indexed.

Issue the following SQL using your SQL tool of choice:

Microsoft SQL Server:

update table_employee set x_modify_stmp = getdate()
update table_mod_level set x_modify_stmp = getdate() where x_modify_stmp is null
update table_part_num set x_modify_stmp = getdate()

Oracle:

update table_employee set x_modify_stmp = (select sysdate from dual);
update table_mod_level set x_modify_stmp = (select sysdate from dual) where x_modify_stmp is null;
update table_part_num set x_modify_stmp = (select sysdate from dual);

Dovetail Seeker Configuration

Dovetail Seeker is the search engine that powers the search capabilities of Dovetail Agent. It is a required dependency of Dovetail Agent. Follow the installation instructions provided with Dovetail Seeker.

Within Seeker's documentSpecifications.xml file, be sure to include the specifications needed by Dovetail Agent, which are provided in the $dovetailAgent\source\config\seeker.config\ directory:

From Seeker's baseline documentSpecifications.xml file, the following specifications should be used:

Setup Dovetail Task Manager

[Optional] If using Dovetail Task Manager, follow the Install/Setup Steps

Setup Clarify Task Manager

[Optional] If using Clarify Task Manager:

Setup Agent Reporting

[Optional] If using Dovetail Agent Reporting module

  1. Import data files:

    • agent_basic_data.dat (for the Report privileges)

  2. Grant the Report User and Report Creator privileges to the desired privilege class(es) using Dovetail Admin.

  3. Be sure to set the reporting application configuration settings, which are covered in the next section.

Application Configuration

Edit the $dovetailAgent\app\appSettings.config file, setting the following configuration keys for your environment:

General

Key Default Comments
DovetailDatabaseSettings.Type mssql Your database type. Either mssql or oracle
DovetailDatabaseSettings.
ConnectionString		 Data Source=host.domain.local;Initial Catalog=mobilecl125;
User Id=dovetailapp;Password=password		 Database connection string
DovetailDatabaseSettings.
SessionTimeoutInMinutes		 60 Number of minutes until an inactive session is terminated.
DovetailDatabaseSettings.
ApplicationUsername		 sa A valid Clarify username used by the application
HistorySettings.
MergeCaseHistoryChildSubcases		 false When displaying case history, should subcase entries be included as well
CommitmentSettings.
DefaultDueDateInHours		 24.0 When commitments are created, the default due date will be this many hours in the future
WebsiteSettings.PublicRootUrl http://localhost/agent5/ If you are running your web site in a farm (behind a reverse proxy) Agent5 will need to know the full public URL of your website for when it needs to create public facing URLs (password reset emails)
QuerySettings.
DownloadMaxRowCount		 1000 When downloading query results, the maximum number of rows to be returned.
fchoice.sqlcommandtimeout 30 The timeout (in seconds) for SQL queries executed by the application against the database.
vs:EnableBrowserLink false Disables the Visual Studio Browser Link functionality
SolutionSettings.PublicUrl https://support.dovetailsoftware.com/
selfservice/solutions/show/{{0}}		 The root url for public solutions. This should be your eSupport/WebSupport/SelfService style application where customers can access the public knowledgebase.
WebSecuritySettings.
DisableAntiForgery		 false Disables CSRF protection. Can be useful to disable in certain development/test situations.
LicensingSettings.
TimeoutMinutes		 60 Number of minutes a user must be inactive before their license is released. Remove this value to never release a license.

Enable Features

Key Default Comments
Case.FeatureEnabled true Enable/disable cases in the application
Subcase.FeatureEnabled true Enable/disable subcases in the application
Solution.FeatureEnabled true Enable/disable solutions in the application
PartRequest.FeatureEnabled true Enable/disable part requests in the application
MarkdownSettings.IsRichLoggingEnabled true Enable/disable rich logs using markdown (email, notes, research) for cases and subcases.
DovetailDatabaseSettings.
IsImpersonationEnabled		 false Determines whether impersonation is enabled.
FrontEndSettings.IsGravatarEnabled true Enable/disable use of Gravatar for avatars in the application

Sites

Key Default Comments
SiteSitePartsTab.FeatureEnabled true Enable/disable the site parts tab on the site page
SiteFlashesTab.FeatureEnabled true Enable/disable the flashes tab on the site page
SiteCCTab.FeatureEnabled true Enable/disable the CC tab on the site page
SiteRecentCasesTab.FeatureEnabled true Enable/disable the recent cases tab on the site page
SiteRecentPartRequestsTab.FeatureEnabled true Enable/disable the recent part requests tab on the site page
SiteSupportTab.FeatureEnabled true Enable/disable the support tab on the site page
SiteChildSitesTab.FeatureEnabled true Enable/disable the child sites tab on the site page
SiteCalendarsTab.FeatureEnabled true Enable/disable the calendars tab on the site page
SiteContractsTab.FeatureEnabled true Enable/disable the contracts tab on the site page
SiteConnectionsTab.FeatureEnabled true Enable/disable the connections tab on the site page

Attachment

Key Default Comments
AttachmentSettings.FilePath c:\DovetailCRM\attach Root directory for storage of file attachments
AttachmentSettings.AttachmentMode ModeB Defines how file attachments are saved. Additional Information

Resource Uploads

Agent has support for automatic uploading of image files to an image store. Currently this feature is used when creating and editing solutions, and when logging emails on cases/subcases.

Key Default Comments
ResourceUploadSettings.IsUploadEnabled false Enables support for image uploads. (true or false)
ResourceUploadSettings.ResourceStore Seeker Where images are stored. Seeker or S3.
Amazon S3 Settings

These settings apply when the resource store is set to S3.

Key Default Comments
S3Settings.AWSId Your Amazon Access Key ID
S3Settings.AWSSecret Your Amazon Secret Access Key
S3Settings.Bucket S3 bucket where files will be uploaded
S3Settings.Region us-east-1 When creating a bucket if you select any region beside "US Standard" you will need to configure this setting with the correct region string.

Refer to the Amazon S3 Setup for more details.

Search Settings

Key Default Comments
SearchSettings.SearchServiceUrl http://localhost/seeker URL for Dovetail Seeker
SearchSettings.ProxyUrl http://localhost/seekerproxy URL for Dovetail SeekerProxy
SearchSettings.
ExcludedSearchDomains		 account Comma separated list of search domains that should be excluded from the general search page. Use the domain's Display Name. (Note: case-sensitive)
SearchSettings.MinimumWildcardTermLength 3 The minimum length at which a search term is allowed to be wildcarded.
Wildcarding short terms can result in search errors when too many terms match the wildcarded query.

Subcase

Key Default Comments
SubcaseSettings.
DueDateNumberOfDaysAfterCreation		 7 When subcases are created the due date will be set by adding this value of days to the creation time
SubcaseSettings.PriorWarningInHours 8 When subcases are created, the prior warning will be this many hours
SubcaseSettings.
LogEmailIncludesCaseCCList		 false When logging email to a subcase should the parent case's cclist be used?
SubcaseIdFromCaseHistory
AdditionalInfoExpression		 Number\s+=\s+(?<id>\w+-\w+)" Regular Expression used to parse subcase IDs from act_entry.addnl_info

Sorting

Key Default Comments
SortSettings.CaseIdIsNumeric true Are your case id numbers all numeric? Allows for numeric vs string sorting of cases. Either true or false
SortSettings.SubcaseIdIsNumeric true Are your subcase id numbers all numeric? Allows for numeric vs string sorting of subcases. Either true or false
SortSettings.SolutionIdIsNumeric true Are your solution id numbers all numeric? Allows for numeric vs string sorting of solutions. Either true or false
SortSettings.PartRequestIdIsNumeric true Are your part request id numbers all numeric? Allows for numeric vs string sorting of part requests. Either true or false

Contracts

Key Default Comments
ContractSettings.EntitlementType site The entitlement Type for case contracts (site, contact, or site_part)

Part Requests

Key Default Comments
PartRequestSettings.
PartRequestIdFromAdditionalInfoExpression		 (?<id>\d+-\d+) Allows part request replication history to be linked by id, using regex to find the id

Password

Key Default Comments
PasswordSettings.
MinimumPasswordLengthOn		 false Is there a minimum password length?
PasswordSettings.MinimumPasswordLength 6 Minimum password length
PasswordSettings.
UsernameCantBePasswordOn		 false Disallow the password from containing the username
PasswordSettings.
RequireSpecialCharsOn		 false Require a special character (!@#$%^&*(){}[].-\/) in the password
PasswordSettings.RequireMixedCaseOn false Require upper and lowercase letters in the passsword
PasswordSettings.RequireNumbersOn false Require a number in the password
PasswordSettings.RequireLettersOn false Require a letter in the password

Calendar

Key Default Comments
CalendarSettings.EventLength 15 minutes The timespan a subcase or commitment event takes up on a shared calendar. Can be expressed as "1 hour", "2 hours", "1 minute", 5 minutes", "90 seconds", etc
CalendarSettings.RefreshDuration PT1H Recommended update interval for subscription to the calendar. Defaults to 1 hour. Uses the ISO 8601 Duration format
CalendarSettings.DateRange 30 Number of days before and after today that are listed in shared calendar data

Log Email

Key Default Comments
LogEmailReplySettings.IgnoredAddresses support@company.com Comma-delimited emails that should NOT be auto-injected into the address fields when logging an email (when performing a reply or reply-all)

Task Manager

[Optional] If using Task Manager

Key Default Comments
TaskManagerSettings.TaskManager Dovetail The TaskManager Type for running task sets. When using the Workflow-Run Task Set action on a case, determines which tables are used to retrieve the task sets from. Either Clarify or Dovetail

Reporting

[Optional] If using Dovetail Agent Reporting

Key Default Comments
ExagoSettings.WebApplicationUrl http://localhost/Exago Url to the root of your exago web reports application
ExagoSettings.WebServiceUrl http://localhost/ExagoWebAPI/Api.asmx Url of your exago web service API
ExagoSettings.ConfigXml dovetail.XML What configuration file should the integration use?
ExagoSettings.HomePage DovetailReports Which home page should users be taken to. (Do not add .aspx to the end)
ExagoSettings.ReportUserRole Report User Privilege to determine if a user can run reports
ExagoSettings.ReportCreatorRole Report Creator Privilege to determine if a user can create reports

Web Configuration

Edit the $dovetailAgent\app\web.config file, setting the configuration values for your environment:

HistoryOriginalMessageExpressions section

The HistoryOriginalMessageExpressions section is a collection of strings used to determine when an original message begins within an email log. When building up a case/subcase history, Dovetail Agent will collapse the original message portion of an email log. These strings are used to indicate when an original message begins. There can be many different original message expressions - almost every email client does something different, and different languages obviously use different strings. Dovetail Agent ships with a baseline collection of expressions that are a good place to start. When users observe that an email log isn't collapsing where it should be, investigate the email log body, and add the appropriate expression to this collection.

Note: these are regular expressions (regex) strings, so wildcards and other regex characters can be used.

Example:

  <HistoryOriginalMessageExpressions>
    <add key="1" value="(?i)-+\s*Original Message\s*-+"/>
    <add key="2" value="(?i)On .*,.*wrote:"/>
  </HistoryOriginalMessageExpressions>

Setting the maximum file upload size

By default, the maximum size of a file to be uploaded to the server using the FileUpload control is around 4MB. This value can be increased by modifying the maxRequestLength attribute. In addition, the default maximum length of content in a request supported by IIS is around 28.6 MB. This value can be increased by modifying the maxAllowedContentLength attribute. Additional information regarding these settings.

Rewrite rules

The rewrite section contains rules that rewrite the response before it is sent to the client. The Remove RESPONSE_Server rule will remove the Server header which identifies this is an IIS server. This is for security purposes. This rewrite section and rule is dependent on the IIS URL Rewrite Module

Amazon S3 Setup

When using S3 as a resource store you will need to have an Amazon Web Services (AWS) account which you will use to create AWS credentials having access to the S3 (Simple Storage Service) bucket where your files will be uploaded.

AWS Credentials

Create an AWS account. Use your corporate Amazon login if you have one.

Create new AWS user credentials using the AWS user console

Bucket Creation

Using the S3 web console create the bucket to use as your image store.

For more help use the AWS guide on Creating A Bucket.

DNS propagation

Be aware that the creation of a bucket and the setup of CORS will not work until the new bucket name has propagated through the global DNS. The time DNS propagation takes varies, but there is a way to test to make sure the bucket is primed.

For example if you setup a bucket named bucket.mycompany.tld the AWS bucket URL would look like https://bucket.mycompany.tld.s3.amazonaws.com/.

However if you try and access your bucket URL before the propagation is completed you would be redirected to a different URL, specific to the zone the bucket is in such as https://bucket.mycompany.tld.s3-us-west-2.amazonaws.com/.

This redirection invalidates the CORS handshake and returns an error: XMLHttpRequest cannot load https://bucket.mycompany.tld.s3.amazonaws.com/. The request was redirected to 'https://bucket.mycompany.tld.s3-us-west-2.amazonaws.com/', which is disallowed for cross-origin requests that require preflight.

To test if your bucket is ready navigate to your bucket URL in a web browser. If you are redirected to another domain then bucket isn't ready yet.

Bucket Setup

Ensure that your AWS user has the proper access to the Bucket that was just created, and ensure that Cross Origin Resource Sharing (CORS) is property configured.

Allow user access to the bucket

Add permissions for Authenticated Users to have full access to this bucket.

Adding CORS permissions

Agent needs CORS configured properly to allow background uploads to the image store.

Cross-origin resource sharing (CORS) defines a way for client web applications that are loaded in one domain to interact with resources in a different domain. With CORS support in Amazon S3, you can build rich client-side web applications with Amazon S3 and selectively allow cross-origin access to Amazon S3 resources.

<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <CORSRule>
        <AllowedOrigin>*</AllowedOrigin>
        <AllowedMethod>GET</AllowedMethod>
        <AllowedMethod>POST</AllowedMethod>
        <AllowedHeader>*</AllowedHeader>
    </CORSRule>
</CORSConfiguration>

This is an open <CORSRule/> allowing GET and POST operations from any Origin. If you wish to lock this down to the the exact origin which will be uploading images, refer to the S3 guide on Enabling Cross-Origin Resource Sharing.

Add User Bucket Policy

Grant the required access to your store's bucket.

{
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "s3:ListAllMyBuckets"
         ],
         "Resource":"arn:aws:s3:::*"
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:ListBucket",
            "s3:GetBucketLocation"
         ],
         "Resource":"arn:aws:s3:::my-bucket"
      },
      {
         "Effect":"Allow",
         "Action":[
            "s3:PutObject",
            "s3:GetObject",
            "s3:DeleteObject"
         ],
         "Resource":"arn:aws:s3:::my-bucket/*"
      }
   ]
}

Your user should now have upload and download access to your bucket.

Logging Configuration

Dovetail Agent uses the Log4net logging library. Logging is configured within the $dovetailAgent\app\agent.log4net file. The default logging settings are probably fine to start. The log4net website has more details on specific log4net configuration.

Web Server Configuration

Configure the IIS web server to support Dovetail Agent:

Note: The following assumes IIS version 7.5 on Microsoft Windows 7. Your system may vary slightly.

Open the Internet Information Services Manager

Create a new application pool

Create a web application

Browse to the Dovetail Agent application

Windows Authentication

By default, Dovetail Agent uses the same authentication method as the Clarify Client (loginName/password validated against the database). In addition, Dovetail Agent supports Windows Authentication (Active Directory integration). Windows Authentication is entirely optional - but may be useful in your environment.

How it works

With Windows Authentication, a user is not authenticated using the Clarify login and password against the database. Instead, Windows authenticates the user, and passes the login name to the Agent application. The login name passed to the application includes the domain name, i.e. mydomain\fred.smith

Dovetail Agent needs a way to map the Windows domain and login name to the Clarify login name. It does this using the x_windows_login_name field on table_user, which is how the windows login name is mapped to the Clarify login name.

The SQL is basically this:

SELECT login_name FROM table_empl_user
WHERE  windows_login = 'myDomain\myUserName' AND status = 1

The first login name returned from that query is the Clarify login name, and the user is automatically logged into the application as that login name.

If that query does not return a login name, then the application returns a 404.1 Unauthorized HTTP error.

Windows Authentication Setup

  1. Add Windows Authentication feature

    • Goto Add or Remove Programs
    • Click Turn Windows features on or off
    • Click on the plus icon next Internet Information Services.
    • Click on the plus icon next to World Wide Web Services
    • Click on the plus icon next to Security
    • Select Windows Authorization
    • Click OK

  2. Enable Windows Authentication

    • Open the Internet Information Services Manager
    • In the left pane, click on the Dovetail Agent web application
    • Double-click on the Authentication feature icon (within the IIS category)
    • Click on Windows Authentication from the list
    • Click Enable in the right sidebar

  3. Change the authentication mode from Forms to Windows

    • Edit the $dovetailAgent\app\web.config file

    • Change the authentication mode from Forms:

      <authentication mode="Forms">

      to Windows:

      <authentication mode="Windows">

  4. Populate the table_user.x_windows_login_name column in your database.

Add Database Indexes

The following performance indexes are recommended. Work with your DBA to add these indexes to your database.

Table Column(s) Unique? Comments
fc_login_monitor fcsessionid Yes
dt_search search_terms No
dt_search dt_search2user No
dt_resource store_uri Yes If ResourceUploadSettings.IsUploadEnabled is set to true, then this index will enhance the performance of retrieving details for images.

Application User Permissions

The application user (as configured in the connection string) needs to have permission to change password for other users. This is how the Password Reset functionality is accomplished.

Note: This does not apply if using Windows Authentication.

Microsoft SQL Server

One way to accomplish this is to add the application user to the securityadmin database role.

EXEC master..sp_addsrvrolemember @loginame = N'username', @rolename = N'securityadmin'

(where username is the application user name)

Oracle

One way to accomplish this is to grant the ALTER USER privilege to the application user

grant alter user to username;

(where username is the application user name)

Additional Information

For additional information, refer to the Dovetail Knowledgebase article on this topic.

Implementation Tasks

[Optional] Convert wipbins to tags

The wipbin2tag script creates and adds a tag to every open case, subcase, and solution for either one user or for all users. The tag name will be the name of the wipbin that the case/subcase/solution currently resides in. Refer to the readme.md file found in the $dovetailAgent\config\scripts\wipbin2tag directory for details.

Developer Setup Guide

Install Development Tools

Chocolately is a package manager for windows applications. It is a handy tool for getting common applications installed and keeping them current on your developer machine. We will be using it to install most Agent requirements.

Install Chocolately

From an administrative cmd.exe command prompt execute the following.

@powershell -NoProfile -ExecutionPolicy unrestricted -Command "iex ((new-object net.webclient).DownloadString('https://chocolatey.org/install.ps1'))" && SET PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin

From the same shell now you should be able to run Chocolately install commands.

Add packages required by Agent 5

These packages are required for doing Agent 5 development.

choco install ruby
choco install git

Handy package to have for zip file handling.

choco install 7zip

It is also handy to add browsers you'll be developing with. You should at least update IE to 10 or 11 as Visual Studio 2013 is happier with those versions installed.

choco install ie11
choco install GoogleChrome
choco install Firefox

Install Node.js

Go to https://nodejs.org/ and download the latest LTS (different from "Stable") installer. Run it to install Node.js.

Install Required IIS Features

Windows Authentication

If you plan on using Windows Authentication (Active Directory integration) you'll need to configure IIS for this.

Under World Wide Web Services open Security and select Windows Authorization

Install Dovetail SDK

Download and run the installer for your platform from Dovetail Support.

Install Dovetail Admin

Install Dovetail Seeker

Agent will not work properly without Dovetail's search product Dovetail Seeker as many object pickers are really using search under the hood.

Add MSMQ Support

Install Seeker

It may take a little while for your search index to get created after starting the indexing service.

Install Schema Editor

Install Visual Studio

I installed Visual Studio 2013 With Update 2 from MSDN. I unselected all options but web development. Sit back. This install takes a long time.

Maybe you can get some other install tasks done in the meanwhile.

Using Chocolately to install Visual Studio

Another way to get Visual Studio installed is to use Chocolately. You only need to edit this command line with your Product Key

choco install VisualStudio2013Professional -InstallArguments "/Features:'WebTools SQL' /ProductKey:{ProductKey}"

If you need to find the package name for a different SKU of Visual Studio 2013 try the Chocolately Gallery.

Building Agent from source code

You are done installing a lot of software and now we are ready to work with Agent 5.

Get the source

Setup your development database

You can manually apply schema changes and import data files. If you like.

Because during development these things can change a lot we have provided automation which will apply schema changes and data to your development database. You will need to do this before your application will build or run properly.

This automation uses our products Dovetail SchemaEditor and Archive Manager (Diet) to apply schema changes and import data files. Both applications are licensed products, and require a license file or key to function.

Edit Developer Configuration settings

Default database and typical application settings are sourced from configuration files in the /config directory.

Database settings

Open ./config/app{db}Settings.rb for your desired database platform in your favorite editor.

Notice how the database variables get used to build a connection string. These variables are used in other scripts so be sure to setup all the DATABASE variables do not just edit the DATABASE_CONNECTION.

Database platform and other settings

Open ./config/appSettings.rb and ensure the correct database platform is selected. Also make sure the other settings are as you like.

How are these settings used?

Database and common development centric application settings are controlled with these .rb files. rake setup:* and rake package:* tasks will use these settings to update the application configuration settings.

Diet license

Edit the DIET_LICENSE variable to have the correct ArchiveManager (Diet) license.

If you do not wish to put this license in your source code repository you can alternatively set an environment variable DIET_LICENSE with the correct key.

Other configuration

Please ensure the SEEKER_URL is set to where your Dovetail Seeker web service is installed.

Also ensure that your ATTACHMENT_PATH is correct if you are sharing a development database across users this maybe a UNC windows share.

Seeker Agent specifications

There are a few Seeker document specification XML fragments in the directory config/seeker.config which need to be applied to your Seeker document specification.

We have automation which will do this for you when Seeker is installed locally.

rake setup:switch_seeker

Finally

We are done making sure all the configuration is set. It is time to setup your development database.

rake setup:db

Building Agent from the command line

There are steps to build Agent that need occur outside of Visual Studio. This is handled using Rake.

Build Dependencies

Our source code has a few different package manager dependencies integrated with the build.

These dependencies are are retrieved at build time and are all automated.

Dovetail Nugets

Agent source projects take dependencies on non-public Nugets. These non-public Nugets are released to a private feed to which your organization will receive a unique private URL. You need to update the file ripple.config to use this feed.

Private Feed URL

To obtain your private Nuget feed URL login into our support website. The support home page should have a Nuget Feed entry under Your URLs. If you do not see this entry please create a support case and we will setup a private feed for your organization.

Edit ripple.config

Once you have obtained your private Nuget feed URL you need to edit ripple.config at the root of your source directory. This file contains XML. The first <Feed> element is a placeholder for your private Nuget feed.

Build and test

Invoking Rake by itself will build, and run tests for Agent 5. During your first run it will download all build dependencies mentioned above.

rake

Take it for a spin

Two ways to get the web application running.

Launch!

rake start_web

This will build a production version of the application and configure an IIS web site at http://localhost:8989.

Visual Studio

Double click on the 2012 Visual Studio solution /source/agent.sln. Make sure that the source/Web project is your "StartUp Project". If it is. The Web project will be bold in your Solution Explorer.

Hit Ctrl+F5 to build and launch the site.

To launch from Visual Studio you will need to run rake at least once first.

Frontend Development

When developing in frontend code (javascript, less, handlebars, etc.), you'll need to have npm installed in order to run a watch task that processes the files. npm is automatically installed with node.js. To run the watch task that compiles javascript:

npm run webpack -- --watch

This task must be running while doing javascript development in order to process the files correctly.

For styling, there are custom-styles.less and custom-print-styles.less files that can be used to customize the look of Agent. These are automatically compiled into the stylesheets via gulp less.

Custom Styles

Release

When you want to release Agent you'll need to do a release build. There are two batch files that can be used for this.

The first, and probably more commonly used, is package.bat. This will build the app in release mode and publish the results to the results/release/app directory. You can then point IIS to this directory to run your app or copy the contents elsewhere and host it there.

The second is release.bat. This will also build the app in release mode, but also runs unit tests, copies both the source and docs to results/release, and creates a zip file containing everything in results/release. This can be very helpful for creating snapshots of certain builds that can be backed up.

Logging

Logging is configured in the agent.log4net file. The defaults should be fine. The logging library Log4net is very flexible and has many configuration options

Customization

The Dovetail Agent Developer Training Wiki is a collection of developer training pages we've created to help out Dovetail customers wishing to customize this product. The wiki is a great resource for customizing Dovetail Agent.