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.