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

Previous Versions

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

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

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.

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. Have a look at the Run Task Set business rule to see how it functions.

Setup of Task Manager is detailed within the Install Guide.

Administration of Task Sets

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

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

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:

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 creating/editing solutions.

Still have questions?

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

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

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

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 Task Manager

[Optional] If using 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
DovetailDatabaseSettings.
IsImpersonationEnabled		 false Determines whether impersonation is enabled.
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

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.

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

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

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.

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

F# Tools

Our acceptance tests use a newer version of the F# tools than come with Visual Studio.

Install F# 3.1.1 tools

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.

Do you have a corporate proxy?

You need to configure bower to use your proxy. Bower will be installed during your first rake of the application.

{
    "proxy":"http://proxy.mycompany.com:8080",
    "https-proxy":"http://proxy.mycompany.com:8080"
}

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 gulp installed in order to run a watch task that processes the files. To set this up, run

npm install -g gulp gulp watch

gulp watch must be running while doing frontend development in order to process the files correctly.

Release

When you want to release Agent you'll need to do a release build. This will concatenate, minimize, build, test and setup a web site at http://localhost:8989 with a release ready version of Agent.

release.bat

The release artifacts can be found in the results directory.

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.