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)

Execute the following command:

diet.exe -user_name <user> -password <pass> -db_server <serv> -db_name <db> -imp <file>

where:
<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
HistoryPolicySettings.
SmallImageHeight		 72 Image attachments under this height (in pixels) are considered small, and will be classified as verbose items within History. This only applies to image attachments added by Dovetail Carrier.
HistoryPolicySettings.
SmallImageWidth		 72 Images attachments under this width (in pixels) are considered small, and will be classified as verbose items within History. This only applies to image attachments added by Dovetail Carrier.
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.
FilterSettings.
EnableCache		 false Enable caching for parsing the filter configs. For development purposes, setting this to false will make things easier. For production, this should be set to true.

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
ChangeRequest.FeatureEnabled true Enable/disable change requests in the application
ParentChildCases.FeatureEnabled true Enable/disable parent-child cases 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

Contacts

Key Default Comments
IndividualContacts.FeatureEnabled true Enable/disable individual contacts

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.

Case

Key Default Comments
CaseTimeLogsTab.FeatureEnabled true Enable/disable the Time Log tab for cases
CaseExpenseLogsTab.FeatureEnabled true Enable/disable the Expense Log tab for cases
ParentChildCases.FeatureEnabled true Enable/disable parent-child cases in the application

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
SubcaseTimeLogsTab.FeatureEnabled true Enable/disable the Time Log tab for subcases
SubcaseExpenseLogsTab.FeatureEnabled true Enable/disable the Expense Log tab for subcases

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.

[Optional] Remove Unused Permissions

The RemoveUnusedPermissions script will remove unused permissions (web commands) that may exist in your database. This is only applicable to customers who were using an older version of Dovetail Agent or fcClient (versions 3.x or 4.x), who also use Change Requests. Refer to the readme.md file found in the $dovetailAgent\config\scripts\RemoveUnusedPermissions directory for details.