Introduction

Dovetail Carrier is a flexible and customizable message handling framework for your Dovetail or Clarify CRM application.

Its general purpose message processor and customizable business rule system allow the automation of a virtually any internal CRM processes associated with communicating with external systems.

The Carrier framework is designed to support extensions to its baseline capabilities, for implementing solutions to your organization's business needs.

Extensions shipped by Dovetail have been designed to be customizable and new extensions can be added by customers as needed with no limit on the number of active extensions.

Dovetail Software provides the following extensions for Dovetail Carrier:

Message-based architecture

Benefits of a message-based architecture include:

There are two players in a message-based system. Message Producers and Message Subscribers.

Message Producers put messages into the system.

Message Subscribers perform actions on these messages.

As an example, Dovetail Carrier can listen to an email account, and when a new email is received, it can produce a new message.

Dovetail Carrier contains message processors that subscribe to these messages and do something interesting with them, such as creating a new case or dialogue within the CRM system.

Getting Help

If you need additional help beyond this user guide, you can use any of the following resources:

What's New - Version 3.1.2

Enhancements

Additional Changes

Bug Fixes

Upgrading to Version 3.1.2

What's New in Previous Versions

Previous Versions

Version 3.1.1

Enhancements

Version 3.1.0

Enhancements

Version 3.0.0

Enhancements

Version 2.8.0

Enhancements

Requirement Change

Requires Microsoft .NET version 4.7.x.

Upgrading to Version 2.8.0

Version 2.7.0

Carrier Core

Email Agent Extension

Version 2.6.0

Carrier Installer

When installing Carrier using the MSI, install for all users (as opposed to just the current user). This allows for a user other than the user who installed the app to be able to uninstall the app.

Carrier Core

Email Agent Extension

Version 2.5.0

Carrier Core

Email Agent Extension

Upgrading to Version 2.5.0

Version 2.4.2

Carrier Core

SDK Toolkit Extension

For specific details, refer to the Method Parameter Data Types and Conversions section.

Upgrading to Version 2.4.2

Version 2.4.1

Bug Fixes

Version 2.4.0

Task Manager Extension The Task Manager Extension now includes support for creating action items.

Parent-Child Cases Extension The Parent-Child Cases Extension is a new extension that can be useful when automating workflow processes involving parent-child cases.

Webhooks Extension The Webhooks Extension is a new extension that enables an HTTP request to be invoked.

Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URI configured for the webhook. Users can configure them to cause events on one site to invoke behaviour on another. The action taken may be anything.

This allows for making a web request based on an event within your Clarify/Dovetail system. A business rule can fire based on the event. Dovetail Rulemanager will evaluate the rule, and send a message to Dovetail Carrier. With the Webhooks extension, that message can tell Carrier to make an HTTP request.

Email Agent Extension Incoming emails can now be logged to existing Change Requests and to existing Action Items.

Requirement Change

Requires Microsoft .NET version 4.5.x.

Upgrading to Version 2.4.0

Version 2.3.0

Enhancements

Upgrading to Version 2.3.0

Version 2.2.0

Email Agent Extension

Enhancements

Bug Fixes

Upgrading to Version 2.2.0

If using the Email Agent Extension, additional information about file attachments will be stored in table_doc_path. This requires a database schema change.

Follow the instructions in Update the Clarify Schema to apply the schema changes.

Version 2.1.0

SDK Toolkit Extension

The SDK Toolkit Extension is a new extension that allows for executing methods within the Dovetail SDK Toolkits, without writing any code.

When Carrier receives a message with a type of CallToolkit, the SDK Toolkit Extension will process these message types.

Typically, these messages will originate from Dovetail Rulemanager (such as from a business rule action), although they can also originate from custom applications as well.

Task Manager Extension Changes

Version 2.0.0

Task Manager Extension

Task Manager Extension is a new extension that will process messages received from Dovetail Rulemanager. These are typically part of the Dovetail Task Manager process.

The message will specify a type of Run Task Set, a Task Set Name, and a Case ID. The Task Manager Extension will execute each Task within the given Task Set. This includes dynamic property evaluation and workflow.

In addition to its main out-of-the-box process of creating subcases, Dovetail Task Manager is an enabling technology, meaning that it supports messages flowing into Carrier, where custom functionality can reside. For example, this would enable the Dovetail system to invoke custom code within Carrier, such as calling into another system via a web service.

Task Manager Extension requirements:

Email Agent Extension

Enhancements

Upgrading to Version 2.0.0

Version 1.4.2

Upgrading to Version 1.4.2

If using the Email Agent Extension, the unique message id of incoming emails will be added to the email log. To add this behavior, a custom database column, x_id, needs to be added to the email_log table.

Follow the instructions in Update the Clarify Schema to apply the schema changes.

Version 1.4.1
Version 1.4.0
Version 1.3.4

Upgrading to Version 1.3.4

If using the Email Agent Extension, the subject line of incoming emails can be added to the email log for the target case/subcase. To add this behavior, a custom database column, x_subject, needs to be added to the email_log table.

Follow the instructions in Update the Clarify Schema to apply the schema changes.

Version 1.3.3
Version 1.3.2
Version 1.3.1
Version 1.3.0

Core

Email Agent Extension

<add key="EmailAgentExtensionSettings.EmailAccountUserName" value="account1@company.com,account2@company.com"/>

Carrier-Diagnostics

Version 1.2

Core

Email Agent Extension

Configuration File Changes

Requirement Change

Version 1.1.12

Email Agent Extension

Version 1.1.11
Version 1.1.10
Version 1.1.9
Version 1.1.8

Email Server Connectivity

Version 1.1.7
Version 1.1.6
Version 1.1.5
Version 1.1.4
Version 1.1.3
Version 1.1.2
Version 1.0.8
Version 1.0.7
Version 1.0.6
Version 1.0.5
Version 1.0.4
Version 1.0.3
Version 1.0.2
Version 1.0.1
Version 1.0

Installation

Requirements

This version of Dovetail Carrier requires the following:

Operating System
  • Windows Server 2008 SP2, 2008 R2 SP1, 2012, 2016, 2022
  • Windows 10
Microsoft™ Message Queueing (MSMQ)
  • Installed via 'Turn Windows features on or off'
Microsoft™ .NET Framework 4 Runtime
Clarify™ System Environment
  • Clarify™ 7.0 through 12.5, Amdocs 6 through 7.5
  • Microsoft™ SQL Server™ 2008 and higher
  • Oracle™ Database Server 9, 10g, 11g, 12c, 19c
Scripting EnvironmentThe Communications Extension requires a script to be run by Rulemanager. This script has the following requirements:
  • Dovetail SDK version 3.0 or later
  • Microsoft PowerShell.

Install Dovetail Carrier

Run the installation process by double-clicking the MSI file.

The installation will then proceed through a series of steps or screens which will either provide information about the installation process, or request information necessary to install Dovetail Carrier.

Update the Clarify Schema

When using the EmailAgent Extension:

You can update the Clarify schema with Dovetail SchemaEditor.

Prior to making schema changes, backup the current database.

To make these changes using Dovetail SchemaEditor:
  1. Edit the .SchemaEditor file
    • Set the database connection information.
    • Set the inputFilePath to [InstallDir]\config\schema*carrier.schemascript.xml*
  2. Preview the changes (SchemaEditor.exe -p).
  3. Apply the changes (SchemaEditor.exe -a).

Add Database Indexes

The following indexes will improve the performance of Dovetail Carrier:

Table Column(s) Index Name Unique?
table_act_entry act_entry2email_log ind_act_entry2email_log No

As these are for performance as opposed to enforcing application behavior, they do not need to be schema indexes, i.e. part of your Clarify/Dovetail schema. They can be added to your dbtune.sql script, or whatever script your DBA uses for maintaining performance indexes.

Install License Keys

You should have received a license for Dovetail Carrier either with your distribution or separately. If you have not received a license for Dovetail Carrier, please contact us to obtain one.

The Communications Extension requires a license for the Dovetail Interfaces Toolkit (FCINTER).

The Email Agent Extension requires a license for the Dovetail Interfaces (FCINTER) and Support (FCCS) Toolkits.

The Task Manager Extension requires a license for Dovetail Task Manager and Support (FCCS) Toolkit.

The SDK Toolkit Extension requires a license for whatever SDK Toolkit is invoked.

If you have not received the necessary license keys, please contact Dovetail Software.

To install your Dovetail Carrier license:

  1. Execute the Dovetail Software License Installer which is found in the Dovetail Carrier installation root.

  2. The database connection/login screen will appear (Figure 2). This allows License Installer to connect to your Clarify™ database instance and view current and install new Dovetail Software licenses. Please enter required information (all fields are required except for "DB Name" when the database type is "Oracle") and click "Login". The License Installer will then attempt to connect to the database.

    License Installer Login Screen

    Figure 2: License Installer Login Screen

  3. After successfully connecting to the database and retrieving any existing license information, the license information screen (Figure 3) will be displayed. This will list any existing licenses and some basic information about them. It also allows you to install new licenses by clicking on the "Install New License(s)" button.

    License Installer License Information Screen

    Figure 3: License Installer License Information Screen

  4. To install a new license or licenses, click the "Install New License(s)" button. You will be prompted (see Figure 4) to select an XML license file, or paste a license XML fragment you may have received in an email or other source. Once you have loaded or pasted the XML fragment, click the "Install" button to install the license.

    License Installer Load License Screen

    Figure 4: License Installer Load License Screen

  5. If the installation is successful, the license information screen will appear. The newly installed license(s) should appear in the list of installed license. At this point the License Installer can be closed, or new licenses can be installed as many times as is needed. If the installation is not successful, an error dialog window will appear giving further details about what went wrong.

Configuring Dovetail Carrier

Once the Windows Installer (.msi) installation package has completed, edit the configuration file.

The configuration file for the Windows Service is named DovetailCarrierService.exe.config and is located in the installation directory (typically C:\Program Files\Dovetail Software\Carrier\CarrierService). Review the Service Configuration guide for more details.

Start Dovetail Carrier

After Dovetail Carrier has been installed and configured, the Windows Service can be started. By default, after the service is installed, it is not started.

Start the service

In order for Dovetail Carrier to begin processing, the service must be started. To start the service:

If it fails to start, you will be prompted with a generic error messages from Windows. Consult the Windows Event Viewer to get more information about why Dovetail Carrier failed to start. The log file may also provide more information. The log file will typically be in the logs directory within the installation directory (typically C:\Program Files\Dovetail Software\Carrier\carrierservice\logs).

Running Dovetail Carrier from the command line

Dovetail Carrier can also be run as a command line application. This is useful for testing, but is not recommended for production use.

To start Dovetail Carrier from the command line, open a DOS command prompt, navigate to the carrierservice directory under the Dovetail Carrier installation directory, and type: DovetailCarrierService.exe

Service User Security Requirements

When deploying to production customers will often lock down Windows services to have only the minimum security privileges required. When doing this for Dovetail Carrier you will need to ensure that the identity which the Dovetail Carrier Windows service is running as has the following privileges:

Configuration

There are many configuration options which you will need to visit before you can get Dovetail Carrier running successfully.

There are configuration settings for the Dovetail Carrier service itself which is primarily for setting your Dovetail/Clarify database credentials.

The email configuration settings control what email accounts you can receive email from and how outgoing email is sent.

Logging configuration is handy for keeping a log file of what is happening within the application.

Dovetail Carrier extensions each require their own configuration to link them to the email account they listen to and their many more granular settings.

Service Configuration

The DovetailCarrierService.exe.config file defines the application configuration parameters for the Dovetail Carrier Windows service. You will also need to edit the configuration of any Dovetail Carrier extensions that are in use.

Service Configuration Reference
Attribute Required? Default Description
DovetailCRMSettings.
DatabaseType		 Yes MSSQL Database Type. Valid values: MSSQL, Oracle
DovetailCRMSettings.
DatabaseConnectionString		 Yes Data Source=serverName; Initial Catalog=dovetail;

User Id=myUsername; Password=myPassword;

or:
Integrated Security=SSPI;
Persist Security Info=True;
 Database connection string.

For MSSQL databases:

Data Source=serverName; Initial Catalog=dovetail;
User Id=myUsername; Password=myPassword;

For Oracle databases:

Data Source=OracleConnectionString;User Id=myUsername;Password=myPassword;

Supports connection string parameters: Integrated Security=SSPI; and Persist Security Info=True; to log into the database using current Windows login credentials.
Important: Before Integrated Security can be used a server set up procedure must be followed, see Integrated Security with Dovetail server applications for details.
DovetailCRMSettings.
EmployeeUserName		 Yes sa Login Name of user/employee used when performing actions within the CRM system.
DovetailCRMSettings.
DatabaseType		 Yes MSSQL Database Type. Valid values: MSSQL, Oracle
DovetailCRMSettings.
AttachmentsFilePath		 Yes c:\attach The root path for saving file attachments.
This can be a local path (c:\directory) or a UNC path (\server\directory)
DovetailCRMSettings.
AttachmentMode		 No ModeB Specifies which sub-folder mode Dovetail Mobile Agent should use when saving attachments.

NOTE: The value is NOT case-sensitive (i.e. 'modea' works as well as 'MODEA').

Valid values are:

ModeA: Put all files directly into the path specified by attachPath.

ModeB: Put attachments in subfolders using the CASE ID as a folder prefix.

For example, if the attachPath is set to "c:\attachments", attachments from Case 1792 will be stored in the path:

C:\attachments\001xxx\001792\

This mode groups up to a 1,000 cases in a grouping folder to help organize the attachments.

ModeC: Similar to ModeB but the folder names are slightly different.

For example, if the attachPath is set to "c:\attachments", attachments from Case 1792 will be stored in the path:

C:\attachments\1700\1792\

This mode groups up to 100 cases in a group folder to help organize the attachments.
MessageBusSettings.
MessageQueue		 Yes msmq://localhost/dovetail.carrier The URI of the message queue that Dovetail Carrier will look for messages.
MessageBusSettings.
ConcurrentConsumers		 No 2 * Number of CPUs The number of messages processed concurrently.

NOTE: If using MsGraph to retrieve email, the MsGraph API has some built-in throttling to be aware of, which will influence how you should configure the number of worker threads (concurrent email consumers). Refer to the Dovetail knowledgebase article on Throttling of the MsGraph API with Carrier and Rulemanager for more information.
For MsGraph this value is limited to 4.
DovetailDatabaseSettings.
SessionTimeoutInMinutes		 Yes 60 Number of minutes until an inactive session is terminated.
RegularExpressionSettings.
TimeoutInSeconds		 No 30 Number of seconds a regular expression will execute before timing out. Timed out expressions will throw an exception.

Many extensions use regular expressions to drive how message processing is handled. It is possible that in some rare cases a complex regular expression for certain inputs could runaway. This timeout is a relief value preventing the message consumer from getting stuck evaluating a regular expression.
TaskManagerExtension.
FeatureEnabled		 No True Whether the Task Manager Extension is enabled or not. Note: The Task Manager Extension requires a license for Dovetail Task Manager and Support (FCCS) Toolkit.
Email Service Configuration

Email Service Configuration

Email Account Configuration

Email Account Configuration

Microsoft Graph Account Configuration

MS Graph Account Configuration

Extension Configuration

Please see the configuration reference for any Dovetail Carrier extensions you are using.

Email Service Configuration

Dovetail Carrier has an email service used to send out emails using SMTP which is configured within the DovetailCarrierService.exe.config file. Email can be sent using SMTP or using the Microsoft Graph API.

General

Attribute Required? Default Description
EmailServiceSettings.
EmailStoragePath		 Yes %ALLUSERSPROFILE%\
DovetailCRM\Carrier		 The path where incoming emails are saved while being processed.
EmailServiceSettings.
EmailTemplatePath		 No Current Working Directory '.' Path to the templates used when sending emails from RuleSets. Note: These templates usually end in .spark.

For more information about templates see Email Responses.
EmailServiceSettings.
EmailAccountPollingIntervalInSeconds		 No 60 Delay in seconds between checks of the configured email accounts.
EmailServiceSettings.
SpamStoragePath		 Yes %ALLUSERSPROFILE%\
DovetailCRM\Carrier\Spam		 The path where emails marked as spam get saved. To help control how emails are marked as spam see Stop Words.
EmailServiceSettings.
MailBeeBounceDatabaseFilePath		 Yes BounceDatabase\all.xml Path to support files used to detect bounced emails.
EmailServiceSettings.
AdministrativeNotificationEmailAddress		 Yes n/a Email address to received administrative email notifications.
EmailServiceSettings.
SendAdministrativeNotificationsFromEmailAddress		 Yes n/a Email address used to send administrative email notifications.
EmailServiceSettings.
MaximumEmailRetrievedHistoryEntries		 No 100 Maximum number of entries in retrieved email history. Once reached the oldest entries will be gradually removed to make room for new ones.

SMTP

Attribute Required? Default Description
EmailServiceSettings.
Mode		 No SMTP Specify which mode Carrier uses for sending email. Supported Modes are SMTP, and MsGraph.
EmailServiceSettings.
SmtpHostAddress		 Yes 127.0.0.1 The hostname or IP address of the email server used for sending outgoing emails.
EmailServiceSettings.
SmtpAccountName		 No (empty string) The account name used to login to the SMTP server
EmailServiceSettings.
SmtpAccountPassword		 No (empty string) The password used to login to the SMTP server
EmailServiceSettings.
SmtpPort		 No 25 The port used to connect to the SMTP server
EmailServiceSettings.
SmtpEnableSsl		 No false Specifies if the connection should use TLS/SSL
EmailServiceSettings.
SmtpSslMode		 No StartTls Specifies the type of SSL handshake used to make secure connections. Valid values are : Manual, OnConnect, StartTls, StartTlsIfSupported

Note: This setting only applies when the SmtpEnableSsl setting is true.

MsGraph

Attribute Required? Default Description
EmailServiceSettings.
Mode		 No SMTP Specify which mode Carrier uses for sending email. Supported Modes are SMTP, and MsGraph. If using the MsGraph API, this must be set to MsGraph
EmailServiceSettings.
MsGraphUserName		 Yes, if EmailServiceSettings.Mode is set to MsGraph Username for the email account
EmailServiceSettings.
MsGraphClientId		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application client ID
EmailServiceSettings.
MsGraphClientSecret		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application client secret
EmailServiceSettings.
MsGraphTenantId		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application tenant ID

Email Account Configuration

The DovetailCarrierService.exe.config file defines connection details about the email accounts which Dovetail Carrier will check for email. Both POP3 and IMAP protocols are supported. You may enter more than one email account.

Pop3 Email Accounts

The minimum required information for each POP3 account includes the host, username, and password.

Example of a POP3 account with only the required values:

<pop3Account host="hostname or ip" username="account user name" password="account password"/>

Example of a POP3 account with all values:

<pop3Account 
      host="hostname or ip" 
      port="pop3 service port number" 
      username="account user name" 
      password="account password"
      timeoutinseconds="number of seconds to wait before timing out failed conversations with the email server"
      usesecureconnection="true|false (default is false) should the connection use TLS/SSL"
      authenticationmode="Automatic (default)|ClearText|CramMD5|NTLM|ClearText"
      sslmode="Manual|OnConnect|StartTls (default)|StartTlsIfSupported"
 />
Pop3 Account Configuration Reference
Attribute Required? Default Description
host Yes N/A Hostname or IP address of POP3 email server
username Yes N/A Username for POP3 account
password Yes N/A Password for POP3 account
port No 110 POP3 service port number
timeoutinseconds No 30 Number of seconds to wait before timing out a failed conversation with the email server
usesecureconnection No false Specifies if the connection should use TLS/SSL
authenticationmode No Automatic Specifies the type of authentication used when logging into the POP3 server. Valid values are: Automatic, ClearText, CramMD5, NTLM.
sslmode No StartTls Specifies the type of SSL handshake used to make secure connections. Valid values are : Manual, OnConnect, StartTls, StartTlsIfSupported

Note: This setting only applies when the usesecureconnection setting is true.
IMAP Email Accounts

The minimum required information for each IMAP account includes host, username, and password.

Example of a IMAP account with only the required values:

<imapAccount host="hostname or ip" username="account user name" password="account password"/>

Example of a IMAP account with all values:

<imapAccount 
      host="hostname or ip" 
      port="IMAP service port number" 
      username="account user name" 
      password="account password"
      timeoutinseconds="number of seconds to wait before timing out failed conversations with the email server"
      usesecureconnection="true|false (default is false) should the connection use TLS/SSL"
      authenticationmode="Automatic (default)|ClearText|CramMD5|NTLM|ClearText"
    emailFolder="emailFolderName (default is INBOX)"
      sslmode="Manual|OnConnect|StartTls (default)|StartTlsIfSupported"
 />
IMAP Account Configuration Reference
Attribute Required? Default Description
host Yes N/A Hostname or IP address of IMAP email server
username Yes N/A Username for IMAP account
password Yes N/A Password for IMAP account
port No 143 IMAP service port number
timeoutinseconds No 30 Number of seconds to wait before timing out a failed conversation with the email server
usesecureconnection No false Specifies if the connection should use TLS/SSL
authenticationmode No Automatic Specifies the type of authentication used when logging into the IMAP server. Valid values are: Automatic, ClearText, CramMD5, NTLM.
emailFolder No "INBOX" Email folder from which you wish Dovetail Carrier to pull emails.
sslmode No StartTls Specifies the type of SSL handshake used to make secure connections. Valid values are : Manual, OnConnect, StartTls, StartTlsIfSupported

Note: This setting only applies when the usesecureconnection setting is true.
MsGraph Account Configuration Reference

Example:

<account 
  username="support@company.com" 
  clientId="xxxx665e-xxxx-432e-xxxx-4e09681xxxx" 
  clientSecret="xxxxF7~5r6Rxxxx.xxxx4_~wqAX743xxxx" 
  tenantId="xxxx9085-xxxx-47d1-xxxx-e558e03axxxx" 
/>
Attribute Required? Description
username Yes Username for the email account to be polled
clientId Yes Azure application client ID
clientSecret Yes Azure application client secret
tenantId Yes Azure application tenant ID

MS Graph Account Configuration

Carrier can poll and send email using an Azure application and the Microsoft Graph API.

Polling emails using the Microsoft Graph API

The DovetailCarrierService.exe.config file defines connection details about the email accounts which Dovetail Carrier will check for email. Specifically, the CarrierMsGraphAccounts section defines email accounts that are to be polled using the Microsoft Graph API. You may enter more than one email account.

MS Graph Accounts

The required information for each account includes the username, clientId, clientSecret, and tenantId.

Example :

<account 
  username="support@company.com" 
  clientId="xxxx665e-xxxx-432e-xxxx-4e09681xxxx" 
  clientSecret="xxxxF7~5r6Rxxxx.xxxx4_~wqAX743xxxx" 
  tenantId="xxxx9085-xxxx-47d1-xxxx-e558e03axxxx" 
/>
MS Graph Account Configuration Reference
Attribute Required? Description
username Yes Username for the email account to be polled
clientId Yes Azure application client ID
clientSecret Yes Azure application client secret
tenantId Yes Azure application tenant ID
Azure Application

In order to you the Microsoft Graph API, an Azure application needs to be setup/configured in the Azure Portal. Once the application is setup, the client ID and tenant ID will be made available.

Example :

Azure Application

From that overview page, click on the "Certificates & secrets" section to create a new client secret.

Azure Application API Permissions

Carrier needs the following API permissions in order to read, process, and send email:

Example :

Azure Permissions

Additional Azure Application settings

Additional settings and/or configuration may be desired, such as Conditional Access. This additional azure app configuration is outside the scope of Dovetail Carrier's configuration. Please consult with your Azure administrators for more information.

 

 

Sending emails using the Microsoft Graph API

Azure Application

In order to you the Microsoft Graph API, an Azure application needs to be setup/configured in the Azure Portal. Once the application is setup, the client ID and tenant ID will be made available.

Example:

azure application

From the overview page, click on the "Certificates & secrets" section to create a new client secret.

Azure Application API Permissions

Carrier needs the following API permissions in order to read, process, and send email:

Example:

azure application api permissions

Additional Azure Application settings

Additional settings and/or configuration may be desired, such as Conditional Access. This additional azure app configuration is outside the scope of Dovetail Carrier's configuration. Please consult with your Azure administrators for more information.

Carrier configuration

The DovetailCarrierService.exe.config file defines the configuration parameters necessary to send email. The following settings are specific to using MsGraph:

Parameter Name Required? Default Description
EmailServiceSettings.
Mode		 No SMTP Specify which mode Carrier uses for sending email. Supported Modes are SMTP, and MsGraph. If using the MsGraph API, this must be set to MsGraph
EmailServiceSettings.
MsGraphUserName		 Yes, if EmailServiceSettings.Mode is set to MsGraph Username for the email account
EmailServiceSettings.
MsGraphClientId		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application client ID
EmailServiceSettings.
MsGraphClientSecret		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application client secret
EmailServiceSettings.
MsGraphTenantId		 Yes, if EmailServiceSettings.Mode is set to MsGraph Azure application tenant ID
MsGraphExecutorSettings.
NumberOfRetries		 No 3 Number of retry attempts if a transient exception is detected. If a value greater than 3 is provided the effective value is forced to be equal to 3.
MsGraphExecutorSettings.
RetryDelayMilliseconds		 No 2000 How long to wait between retries in case a transient exception is detected.

The emailAgentExtension.config file also contains configuration parameters that should align with the above settings:

Attribute Required? Description
EmailAgentExtensionSettings.
EmailAccountUserName		 Yes Email Agent will only process messages if the email account matches this value (or one of the values, if using a list of email addresses).

Supports a comma-separated list of values, i.e. "account1@company.com,account2@company.com"

For more information, review the EmailIsFromEmailAgentEmailAccount condition class.
EmailAgentExtensionSettings.
SendResponsesFromEmailAddress		 Yes Email address from which email responses will be sent.

Email Configuration Diagnostics

The most common usage of Dovetail Carrier is to both send and receive emails. Email's received via POP3 and IMAP email accounts are published as Incoming Email Messages into the system's message bus. A potential action as the result of a message being consumed is to send an outgoing email via SMTP to the user who sent an incoming email message or in the case of a failure an administrator who needs to know about an incoming email message which cannot be processed.

Email Configuration Diagnostics

Included with Dovetail Carrier is a command line diagnostics tool which is very helpful for testing your email configuration settings. This tool can be found by opening up a command prompt and going to the following directory:

[InstallDir]\carrierservice\carrier-diagnostics.exe

Running this utility without any arguments will display the available commands

-----------------------------------------------------------------------------------

Available commands:

-----------------------------------------------------------------------------------

accounts -> Test email accounts counfiguration found in email-accounts.config

smtp -> Test smtp server configuration found in emailService.config

smtpsend -> Test sending email via smtp configuration found in emailService.config

-----------------------------------------------------------------------------------
Accounts
[InstallDir]\carrierservice> carrier-diagnostics.exe accounts

The accounts command will go through your email-accounts.config file and connect to each IMAP and POP3 account configured within that file.

Smtp
[InstallDir]\carrierservice> carrier-diagnostics.exe smtp

The smtp command will verify that Dovetail Carrier can connect to the SMTP server configured in your emailService.config file.

SmtpSend
[InstallDir]\carrierservice> carrier-diagnostics.exe smtpsend from@example.com to@example.com

The smtpsend command will send a test email message from the given email address (second argument) to the to address (third argument).

Logging Configuration

Logging Configuration parameters for Dovetail Carrier are specified in the log4net.config file.

Dovetail Carrier uses the same logging framework that is built into the Dovetail SDK. This framework allows developers and administrators a high degree of flexibility to control the quality and detail of the information Dovetail Carrier generates.

Logging capabilities include:

For full details on configuring the logging configuration file, please refer to the Logging section in the Dovetail SDK documentation.

Receiving Emails When Dovetail Carrier Errors Occur

The logging configuration file included with Dovetail Carrier includes a a logging appender configuration named AdministrativeSmtpAppender. If you wish to receive an email when Dovetail Carrier encounters errors you simply need to edit this appenders configuration to point at your SMTP host server and the appropriate email addresses to send the email to and which email address the email will be sent on behalf of.

Please see the log4net SmtpAppender configuration example for more details.

Additional Information

Administrative Email Notifications

Processing incoming emails is a primary function of Dovetail Carrier. When an email cannot be processed it is important for application administrators to know that something went wrong. When for some reason an error is thrown by the processing on an email message.

Email Contents

The administrative email address will be sent an email describing the problem and include detailed errors information and a copy of the offending email message.

The body of the email will include a detailed description of the application exception which caused the email processing to fail.

Attached to the administrative email will be a copy of the email message (saved in the .eml format) which failed to process. Applications which can view the attached .eml include Outlook Express, Windows Live Mail, and Internet Explorer.

Reprocessing Failed Messages

When Dovetail Carrier fails to process a message it moves the message to an error queue. This queue is by default located at msmq://localhost/dovetail.carrier_errors. It is possible to replay the message by moving it back into the main Dovetail Carrier queue (default location - msmq://localhost/dovetail.carrier).

You can move messages between queues with the reprocess-errored-messages.bat batch file. Note you will need to edit the batch file if you have changed queue locations, or are running it from a different machine than the one Dovetail Carrier is installed on. Running this batch file will move all messages from the error queue into the main Dovetail Carrier queue to be reprocessed.

This batch file (and its dependencies) are contained in the following directory:

[InstallDir]\reprocess\

When the batch file executes, the messages should be reprocessed successfully. However, if the problem is still present the messages will again end back up in the error queue.

Dovetail Carrier is a flexible, customizable application and you could potentially have custom behavior which, due to some unforeseen reason, is unable to process a given message. In this case you may need to coordinate with your development team on the best way to handle the problem.

Publish Utility

Dovetail provides a publish.exe utility which will simply take some message content as an input parameter, and publish that message to Carrier. This utility is useful for publishing messages to Carrier, which can be especially helpful when testing. The utility, and the source code for it, are available at the Dovetail Carrier Customizations Examples site.

The following blog posts provide additional details:

Refresh Cache

Dovetail Carrier caches frequently used data, such as schema, lists (application and user-defined), rule properties, etc. When Carrier receives a 'RefreshCache' message, Carrier's internal cache will be reloaded from the database.

Example Message

type=RefreshCache
Message Parameters
Parameter Value
Type RefreshCache

Extensions

Extensions build on top of included core Dovetail Carrier functionality to provide the behavior needed by your organization to react to messages (events) being received. Extensions define everything that Dovetail Carrier does. They define how your business should respond when messages from your organization are received. Extensions can also be responsible for publishing messages into Dovetail Carrier.

All extension source code is shipped with Dovetail Carrier enabling you to change extension behaviors to do exactly what your organization needs. For more information about customization of extension source code please see Creating and Customizing Extensions.

Receiving Email Messages

Dovetail Carrier Core includes support for receiving emails and publishing them as messages. Dovetail Carrier developers can design extensions which subscribe to incoming email messages and perform custom behavior for your business. Included with Dovetail Carrier are two extensions (the Email Agent and extensions), which integrate email functionality with the Dovetail SDK.

Email Agent Extension - Carrier.Extensions.EmailAgent.dll

Email messages received are treated as support case correspondence within your Clarify CRM system. When possible emails are correlated with existing support cases, logging their contents and attachments to the appropriate case or subcase. Emails about new issues will create cases. This extension is an effective replacement for Clarify EmailClerk™ and Dovetail's standalone Email Agent product. This extension is installed by default during Dovetail Carrier installation.

Communications Extension - Carrier.Extensions.Communications.dll

Email messages received are treated as Dialogues and Communications within your Clarify CRM system. This extension is an effective replacement for much of the Amdocs eResponse Manager™ product. This extension is not installed by default.

Parent-Child Cases Extension - Carrier.Extensions.ParentChildCases.dll

The Parent-Child Cases Extension allows for automating workflow processes involving parent-child cases.

SDK Toolkit Extension - Carrier.Extensions.SDK.dll

The SDK Toolkit Extension allows for executing methods within the Dovetail SDK Toolkits, without writing any code.

AutoDest Toolkit Extension - Carrier.Extensions.SDK.dll

The AutoDest Toolkit Extension allows for automatically assigning or dispatching workflow objects based on an auto-destination rules.

Task Manager Extension - Carrier.Extensions.Tasks.dll

This extension will process messages received from Dovetail Rulemanager. These are typically part of the Dovetail Task Manager process.

Webhooks Extension - Carrier.Extensions.Webhooks.dll

Enables an HTTP request to be invoked.

Example Extensions

Dovetail Carrier includes an extension example, which is a complete working example, and includes complete source code.

SLA Extension

An example extension used for SLA calculations. It demonstrates setting of a Next Due Date and Next Action fields on a case.

For more information, refer to the following blog post:

http://clarify.dovetailsoftware.com/gsherman/2016/08/09/sla-calculations-using-dovetail-carrier/

Deploying Customized Carrier Extensions

The surface area of a Dovetail Carrier extension is a simple .Net assembly DLL and its dependencies. The application looks for extensions in the [InstallDir]/carrierservice application directory. Dovetail Carrier ships with the source code for its Email Agent and Communications extensions and other example extensions and support assemblies. This source code includes test projects with NUnit unit tests.

Removing an Extension from use

Simply remove the extension's .Net assembly DLL from the application directory. For example removing Carrier.Extensions.EmailAgent.dll from the [InstallDir]/carrierservice directory would accomplish this.

Deploying an updated extension

Copy the extension and all of its dependent assemblies and configuration files to the [InstallDir]/carrierservice directory and restart the windows service.

Knowing what extensions are being used by Dovetail Carrier

When the application starts up all rule sets found in all extensions found in the application directory are logged.

Defining DefineRuleSetFor named 'Existing Case Support Email'.
 rule:unless condition EmailIsFromEmailAgentEmailAccount  and then exit ruleset.
 rule:unless condition EmailHasCaseId  and then exit ruleset.
 rule:do action LogEmailToCase.
 rule:when condition EmailHasAttachments do action SaveAttachmentsToCase.
 rule:unless condition EmailResponseWasAutomatic do action SendCaseNoteLoggedNotificationToContact.
 rule:do action DeleteEmail.
 error action NotifiyAdministrator will be invoked rule actions or conditions throw an exception.

Email Agent Extension

Email messages received are treated as correspondence within your Clarify CRM system. When possible, emails are correlated with existing workflow items (cases, subcases, change requests, or action items) logging their contents and attachments to the workflow object. Emails about new issues will create cases.

Email Agent extension takes advantage of Carrier's flexibility allowing you to customize how your business responds to email. Taking advantage of our previous experience working with customers to improve our standalone Email Agent application, we have included many optional rules along with the extension source to help you kick start customization of this extension's behavior.

This extension is an effective replacement for Clarify EmailClerk™ and Dovetail's standalone Email Agent product.

Topics

Configuration

The Email Agent extension stores its configuration in a file named emailAgentExtension.config.

Attribute Required? Description
EmailAgentExtensionSettings.
EmailAccountUserName		 Yes Email Agent will only process messages if the email account matches this value (or one of the values, if using a list of email addresses).

Supports a comma-separated list of values, i.e. "account1@company.com,account2@company.com"

For more information, review the EmailIsFromEmailAgentEmailAccount condition class.
EmailAgentExtensionSettings.
SendEmailNotifications		 No Should Email Agent send email notification replies to senders who've created cases or logged notes.

Default value is true.
EmailAgentExtensionSettings.
SendResponsesFromEmailAddress		 Yes Email address from which email responses will be sent.
EmailAgentExtensionSettings.
AdministratorEmailAddress		 Yes Email address which will receive notifications when an error occurs while processing a incoming email message.

Supports a comma-separated list of email addresses, i.e. "admin1@company.com,admin2@company.com".
EmailAgentExtensionSettings.
NewContactDefaultSiteId		 Yes When creating a new case from an email. If the email sender is not already a contact. One can be created. When this happens this value will be used for the new contact's site.
EmailAgentExtensionSettings.
RemoveOriginalMessage		 No Email Agent will attempt to isolate and remove previous email contents. You can control which boundaries are used by editing the emailBoundaryDelimiters.config file.

Default value is true.
EmailAgentExtensionSettings.
CaseIdentifierFormat		 Yes Regular expression describing how Email Agent should locate case identifiers in email subject and bodies.
EmailAgentExtensionSettings.
CaseReplySubjectTemplate		 Yes Spark template used to populate the subject of case email notification responses from Email Agent.
EmailAgentExtensionSettings.
SubcaseIdentifierFormat		 Yes Regular expression describing how Email Agent should locate subcase identifiers in email subject and bodies.
EmailAgentExtensionSettings.
SubcaseReplySubjectTemplate		 Yes Spark template used to populate the subject of subcase email notification responses from Email Agent.
EmailAgentExtensionSettings.
DeleteEmails		 No Should Email Agent delete the email (from the file system) after processing it. Normally this should be set to true. It can be set to false when debugging an issue.

Default value is true.
EmailAgentExtensionSettings.
CreateCases		 No Enable/disable creating new cases. Valid values are true and false.

Default value is true.

If creating cases is disabled, and a new case email is received, then the email will be forwarded to the administrator using the admin_notification_no_case_created.spark template.

For more Dovetail Carrier wide configuration settings look at Service Configuration.

Workflow

Email Agent RuleSets

We have provided out of the box the most typically asked for support email handling behavior. The default behavior is described below.

New Case Support Email

Customer sends an email to the configured Email Agent email account.

Gates

  1. Exit when the email contains a case or subcase or change request or action item identifier.
  2. Exit after marking the email as spam when it contains stop words. Stop words can be configured by editing stopWordPatterns.config.
  3. Exit after deleting the email when the email was from an automatic response. Automatic responses are bounced emails or out of office responses. Detection of out of office responses can be configured by editing outOfOfficePatterns.config.
  4. Notify the administrator and exit if creating cases is disabled

Case Creation

  1. If the email sender is not a contact, a contact is created using the sender's first name, last name and email address. The new contact's initial site is specified via configuration.
  2. Create the case.
  3. Log the contents of the email the case. Email Agent will attempt to isolate the senders email body. Previous email content will removed via email boundary detection. These boundaries are controlled by the emailBoundaryDelimiters.config configuration file.
  4. When the email has attachments save them to the case.
  5. The email sender will be sent a case created notification email. The template for this response email is found in create_case_success.spark.
  6. If the EmailAgentExtensionSettings.DeleteEmails setting is true, delete the email from the server

Existing Case Support Email

Customer sends an email to the configured Email Agent email account.

Gates

  1. Exit unless the email contains a case identifier.

Log Email To Case

  1. Log Email contents of the email to the case. Just like the New Case Support Email RuleSet. Previous email contents are removed.
  2. When the email has attachments save them to the case.
  3. Unless the email response was automatic (Automatic responses are bounced emails or out of office responses), the email sender will be sent a case note logged notification email. The template for this response email is found in case_log_email_success.spark.
  4. If the EmailAgentExtensionSettings.DeleteEmails setting is true, delete the email from the server

Existing Subcase Support Email

Customer sends an email to the configured Email Agent email account.

Gates

  1. Exit unless the email contains a subcase identifier.

Log Email To Subcase

  1. Log Email contents of the email to the subcase. Just like the New Case Support Email RuleSet. Previous email contents are removed.
  2. When the email has attachments save them to the case.
  3. Unless the email response was automatic. The email sender will be sent a case note logged notification email. The template for this response email is found in subcase_log_email_success.spark.
  4. If the EmailAgentExtensionSettings.DeleteEmails setting is true, delete the email from the server

Existing Action Item Email

Customer sends an email to the configured Email Agent email account.

Gates

  1. Exit unless the email contains a action item identifier.

Log Email To Action Item

  1. Log Email contents of the email to the action item.
  2. When the email has attachments save them to the action item
  3. If the EmailAgentExtensionSettings.DeleteEmails setting is true, delete the email from the server

Existing Change Request Email

Customer sends an email to the configured Email Agent email account.

Gates

  1. Exit unless the email contains a change request identifier.

Log Email To Change Request

  1. Log Email contents of the email to the change request.
  2. When the email has attachments save them to the change request
  3. If the EmailAgentExtensionSettings.DeleteEmails setting is true, delete the email from the server

Note: Looking at the extension source you will notice many commented actions and conditions. We have included much of the optional behavior from the original Dovetail Email Agent application which is available in that application via configuration.

Additional Behaviors

We have also include in the source code for the Email Agent extension other commonly used behaviors such as:

Error Handling

Each Email Agent RuleSet is defined to fire an action which will notify the Email Agent administrator if any of the Email Agent RuleSets encounter an error. The original email message is attached to the notification email.

High Level Components

The following is an overview of the different components Dovetail Carrier interacts with when processing Email Agent extension messages.

Carrier Email Overview

CRM Database

Data storage for the CRM system

Email Server

Any email server that supports the POP3, IMAP, and SMTP email protocols. You can use separate servers for inbound and outbound email, and even use several servers for different inbound email channels.

Dovetail Carrier

The message processor.

Out of Office emails - Email Agent Extension workflow

When Dovetail Carrier processes an incoming email message within the Email Agent Extension workflow, if the message is an 'out of office' reply, the email will simply be deleted.

The list of patterns used for determining when an email is an 'out of office' reply are defined in the OutOfOfficePatterns.config file. The patterns in this file can be modified to suit specific business needs.

Stop Words

Emails containing stop words

When Dovetail Carrier processes an incoming email message, if the message contains stop or spam words, the email is simply deleted.

The list of patterns used for determining when an email is spam are defined in the stopWordPatterns.config file. The patterns in this file can be modified to suit specific business needs.

Email Responses

Out of the box the Email Agent extension will send responses back to the email sender as HTML emails informing them about the case they created or the note they logged to an existing case or subcase. Email responses are populated using easily edited template files.

Dovetail's Blog has more extensive information about Customizing Your Response Emails.

Email Templates

Templates are files ending in .spark and can be found in the Dovetail Carrier service directory.

Create Case

When an email is received that does not reference an existing case identifier a new case is created and a email sender receives a response populated by the template create_case_success.spark.

Available types in the rule context: Case and Contact

Log Case Email

Emails received containing a reference to an existing case identifier log that email as a note to the case and the email sender receives a response populated by case_log_email_success.spark.

Available types in the rule context: Case and Contact

Log Subcase Email

Emails received containing a reference to an existing subcase identifier log that email as a note to the case and the email sender receives a response populated by subcase_log_email_success.spark.

Available types in the rule context: Case

Editing Spark Templates

Dovetail Carrier uses the powerful Spark template engine. The included templates give you a taste of a recommended response from Email Agent. You will likely wish to customize their contents.

Available types in the rule context: Subcase

Available Type Properties

Up-to-date details about the types available to the rule context can be found within the extension source code.

  1. Extract the [InstallDir]\developers\extension-source.zip file
  2. Look within the resulting path for this directory \source\Dovetail.SDKIntegration\Models\
  3. Each .cs file defines the available properties on the model type.

SDK Toolkit Extension

The SDK Toolkit Extension allows for executing methods within the Dovetail SDK Toolkits, without writing any code.

When Carrier receives a message with a type of CallToolkit, the SDK Toolkit Extension will process these message types.

Typically, these messages will originate from Dovetail Rulemanager (such as from a business rule action), although they can also originate from custom applications as well.

The message will specify a type of CallToolkit, a Toolkit name, a Method name, and a set of name/value pairs that are the properties and property values of the method.

Example Message

type=CallToolkit 
toolkit=Support 
method=InitialResponse 
caseIDNum=12345
UserName=annie

This example would invoke the InitialResponse method within the Support Toolkit, passing in the values of the CaseIDNum and UserName.

SDK Reference All of the SDK Toolkits, Methods, and Method Parameters are documented within the Dovetail SDK Documentation.

This documentation is available when the Dovetail SDK is installed, and is also available online.

Toolkits

Toolkit Namespace
Contracts FChoice.Toolkits.Clarify.Contracts
DepotRepair FChoice.Toolkits.Clarify.DepotRepair
FieldOps FChoice.Toolkits.Clarify.FieldOps
Interfaces FChoice.Toolkits.Clarify.Interfaces
Logistics FChoice.Toolkits.Clarify.Logistics
Quality FChoice.Toolkits.Clarify.Quality
Sales FChoice.Toolkits.Clarify.Sales
Support FChoice.Toolkits.Clarify.Support

Methods Each Toolkit object has many methods, each intended to encapsulate a Clarify operation or 'API'.

Again, all of the SDK Toolkits, Methods, and Method Parameters are documented within the Dovetail SDK Documentation.

Method Parameters The SDK Toolkit Extension will look at the parameters specified in the message, and try to match those parameters to the method with the same arguments. If there is a match, then the method will be called with those arguments.

If there is not a match, then the SDK Toolkit Extension will use the Setup object for that method.

If an exact argument match is not found, and a Setup object is not found, then an error will be thrown.

Example Given this message:

Type=CallToolkit 
Toolkit=Support 
Method=CloseCase 
CaseIDNum=12345

The message is specifying the CloseCase method on the Support toolkit.

The message is supplying one parameter - CaseIdNum

The Dovetail SDK Support Toolkit has 3 overloads for CloseCase:

  1. public ToolkitResult CloseCase(string caseIDNum)
  2. public ToolkitResult CloseCase(CloseCaseSetup setupParam)
  3. public ToolkitResult CloseCase(CloseCaseSetup setupParam,IDbTransaction transaction)

Since the message is supplying exactly one parameter, then the SDK Toolkit Extension will match to the first CloseCase overload - the one that takes one argument named CaseIDNum.

Example Given this message:

Type=CallToolkit 
Toolkit=Support 
Method=CloseCase 
CaseIDNum=12345
Resolution=Solved

The message is specifying the CloseCase method on the Support toolkit.

The message is supplying two parameters - CaseIdNum and Resolution

The Dovetail SDK Support Toolkit has 3 overloads for CloseCase:

  1. public ToolkitResult CloseCase(string caseIDNum)
  2. public ToolkitResult CloseCase(CloseCaseSetup setupParam)
  3. public ToolkitResult CloseCase(CloseCaseSetup setupParam,IDbTransaction transaction)

Since the message is supplying two parameters, and there is not an overload for the CloseCase method that takes these two parameters, then the CloseCaseSetup object will be used.

The SDK Toolkit Extension will create a CloseCaseSetup object, set the CaseIDNum and Resolution properties on that Setup object, and then pass that Setup object to the CloseCase method (using the 2nd CloseCase overload).

Required Parameters The SDK Toolkit Extension will validate that all of the required method parameters are supplied.

Example Given this message:

Type=CallToolkit 
Toolkit=Support 
Method=CloseCase 
Resolution=Solved

As the CloseCaseSetup constructor requires a CaseIDNum argument, and it has not been supplied in the message, the following error will be thrown:

Missing required parameters: caseIDNum

Additional Fields Many API setup objects have an AdditionalFields property which allows callers to set user defined fields (i.e. 'x_fields') in a customized Clarify environment. It is also possible to use AdditionalFields to override the fields that are set by the API.

To Specify an additional field, simply precede the field name with AdditionalFields.

Example Given this message:

Type=CallToolkit 
Toolkit=Support 
Method=CloseCase 
Resolution=Solved
AdditionalFields.x_done_in_one=1

The SDK Toolkit Extension will create a CloseCaseSetup object, and set the CaseIDNum and Resolution properties on that Setup object.

It will then create an AdditionalFields object, and Append to the AdditionalFields collection, with a field name of x_done_in_one, and a field value of 1.

Finally, it will pass that Setup object to the CloseCase method.

Integration with Rulemanager Dovetail Rulemanager supports a business rule action type of Carrier Message, which will send a message to Dovetail Carrier.

This allows a business rule to be crafted that will invoke a Dovetail SDK API - without any code.

Examples

Example business rule

Attribute Value
Object Type Case
Rule Name/Description When a customer logs a note via SelfService, change the case status to Customer Responded
Start Events Log Note
Cancel Event None
Conditions Logger = SelfService
Action Title Change Status
Create Activity Log Entry? true (checked)
Who to Notify no one (leave empty)
Start Action 0 minutes
From Event Creation
Using Elapsed Time
Repeat Never
Message Type Carrier Message
Message Type=CallToolkit
Toolkit=Support
Method=ChangeCaseStatus
CaseIdNum=[Object ID]
NewStatus=Customer Responded
Notes=Status changed automatically due to action within SelfService
Method Parameter Data Types and Conversions

The SDK Toolkit Extension will automatically perform any necessary data type conversions. Additional details are available in the Method Parameter Data Types and Conversions section.

Method Parameter Data Types and Conversions

The SDK Toolkit Extension will automatically perform any necessary data type conversions.

For example:

caseIDNum=12345

Will be treated as a string, since case ID numbers are strings.

objid=268435457

Will be converted to an integer, as objids are integers

Date Times

CommitmentDate=5/21/2017 15:00:00

Will be converted to a DateTime

A variety of DateTime formats are accepted, including:

Date Time Format
3/9/2007 ShortDate
3/9/2006 4:05 AM ShortDate+ShortTime
5/21/2017 15:00:00 ShortDate+LongTime
2005-03-09 16:05:07Z UniversalSortableDateTime
March 09 2008 4:05:07 PM FullDateTime
Relative Date Times

Dates can also use NOW, or NOW plus or minus an offset.

Examples: DueDate=NOW+2d Converted to a DateTime that is the current date/time + 2 days DueDate=NOW-30m Converted to a DateTime that is the current date/time - 30 minutes

Relative Time Result
NOW the current date/time
NOW+2d the current date/time + 2 days
NOW+30m the current date/time + 30 minutes
NOW-1d the current date/time - 1 day

The Now+ syntax supports days (d), hours (h), and minutes (m).

Time Spans

For parameters that require a timespan (such as the warning time for a commitment), use the hh:mm:dd or d.hh:mm:ss syntax.

Examples: WarningDate=00:30:00 A timespan of 30 minutes WarningDate=2.00:00:00 A timespan of 2 days

AutoDest Toolkit Extension

The AutoDest Toolkit Extension allows for automatically assigning or dispatching workflow objects based on an auto-destination rules.

Typically, these messages will originate from Dovetail Rulemanager (such as from a business rule action), although they can also originate from custom applications as well.

Example Message

type=CallToolkit 
toolkit=AutoDest
method=execute 
ObjectType=case
Operation=DISPATCH
Id=12345

This example would eveluate the DISPATCH auto-destination rule for case 12345, and if a destination queue is found, the case would be dispatched to that queue.

Message Parameters
Parameter Value
Type CallToolkit
Toolkit AutoDest
Method execute
ObjectType A valid object type (Case, Subcase, Solution, Action Item, etc.)
Id The id of the workflow object
Operation A valid Auto-Dest operation

Operations

The following Operations are supported:

Auto-Destination Evaluation

If the auto-destination rule does not return any destinations, then a warning will be logged, and no workflow action (Assign or Dispatch) will occur.

If the auto-destination rule returns multiple destinations, then the first one will be used.

Additional Reference

Refer to the following Dovetail Knowledgebase Article: Auto-Destination Rules: What they are, how they work, and examples.

Webhooks Extension

Webhooks are "user-defined HTTP callbacks". They are usually triggered by some event, such as pushing code to a repository or a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URI configured for the webhook. Users can configure them to cause events on one site to invoke behaviour on another. The action taken may be anything.

This allows for making a web request based on an event within your Clarify/Dovetail system. A business rule can fire based on the event. Dovetail Rulemanager will evaluate the rule, and send a message to Dovetail Carrier. With the webhooks extension, that message can tell Carrier to make an HTTP request.

When Carrier receives a message with a type of InvokeUrl, the Webhooks Extension will process these message types.

Typically, these messages will originate from Dovetail Rulemanager (such as from a business rule action), although they can also originate from custom applications as well.

The message will specify a type of InvokeUrl, a method (POST, GET, PUT, etc.), a contentType, url, and a set of name/value pairs that are passed as parameters to the url.

Example Message
type=InvokeUrl
method=POST
contentType=application/json
url=http://api.webhookinbox.com/i/lIweTgZr/in/
param1=foo
param2=bar
param3="this is something
that has multiple lines in it
even some ""escaped"" quotation marks"

This example would POST a set of JSON formatted data to the given url.

Required Message Parameters
Parameter Value Comments
type InvokeUrl Required
method Typically one of:
  • GET
  • POST
  • PUT
  • DELETE
 The HTTP Request Method
contentType Typically one of:
  • application/json
  • application/x-www-form-urlencoded
 The HTTP Request content type
url The url to be invoked
Request Headers

To specify request headers, use the <HEADER> keyword.

Examples:

Windows Authentication

To specify Windows authentication for the request, simply set the UseWindowsAuth parameter to true

Example Message
type=InvokeUrl
method=POST
contentType=application/json
url=http://api.webhookinbox.com/i/lIweTgZr/in/
param1=foo
param2=bar
useWindowsAuth=true

When this flag is specified, the request will utilize the CredentialCache.DefaultCredentials value which will resolve to the Windows account being used to run the Dovetail Carrier Service.

Optional Message Parameters

Any other name/value pair defined within the message will be treated as parameters to be passed to the url.

If the method is a GET, the name/value pairs will be passed on the querystring.

If the method is POST, they will be included in the request payload.

Logging

The extension will log the details of the received message, the web request, as well as the resulting response.

Example of logs:

INFO Dovetail.Carrier.Core.RuleManager.RuleManagerConsumer -
Carrier message received:
type=InvokeUrl
method=GET
url=http://api.webhookinbox.com/i/lIwesTgZr3w/in/
foo=bar
foo2=bar2
DEBUG Carrier.Extensions.Webhooks.InvokeUrlHandler -
GET http://api.webhookinbox.com/i/lIzsTgZr/in/?foo=bar&foo2=bar2
INFO Carrier.Extensions.Webhooks.InvokeUrlHandler -
Response 200
JSON arrays

When posting JSON data, it's common to include data within arrays, and sometimes even with nested arrays.

The Webhooks Extension supports this, and makes it easy to express this syntax in a simpler fashion.

It is probably best demonstrated with an example.

For example, if a web service may require that the POSTed data be formatted like so:

{
    "channel": "#testing",
    "text": "case notification",
    "username": "testing-bot",
    "attachments": [{
        "fallback": "Case 4106 from Craig Breedlove at American Motors",
        "title": "case title goes here",
        "title_link": "https://myserver/agent/support/cases/4106",
        "color": "warning",
        "pretext": "Case 4106 from Craig Breedlove at American Motors",
        "thumb_url": "https://myserver.com/images/logo.jpg",
        "fields": [{
            "title": "Severity",
            "value": "Medium",
            "short": false
        },
        {
            "title": "Queue",
            "value": "None",
            "short": false
        },
        {
            "title": "Mobile Link",
            "value": "https://myserver.com/mobile/case/4106",
            "short": false
        }]
    }]
}

Rather than building the complex JSON formatting yourself, the Webhooks extension will do it for you,

You can express your parameters in a simpler format, like so:

type=InvokeUrl
url=https://someOtherApplication.com/api/mysecrettoken
method=POST
contentType=application/json
channel=#testing
text=case notification
username=testing-bot
attachments[0].fallback="Case 4106 from Craig Breedlove at American Motors"
attachments[0].title="case title goes here"
attachments[0].title_link="https://myserver/agent/support/cases/4106"
attachments[0].color="warning"
attachments[0].pretext="Case 4106 from Craig Breedlove at American Motors"
attachments[0].thumb_url="https://myserver.com/images/logo.jpg"
attachments[0].fields[0].title=Severity
attachments[0].fields[0].value=Medium
attachments[0].fields[0].short=false
attachments[0].fields[1].title=Queue
attachments[0].fields[1].value=None
attachments[0].fields[1].short=false
attachments[0].fields[2].title=Mobile Link
attachments[0].fields[2].value="https://myserver.com/mobile/case/4106"
attachments[0].fields[2].short=false

Take note of the attachments, attachments[index], and attachments[index].fields[index] syntax used for defining arrays and nested arrays of data.

Task Manager Extension

This extension will process messages received from Dovetail Rulemanager. These are typically part of the Dovetail Task Manager process.

The message will specify a type of Run Task Set, a Task Set Name, and a Case ID. The Task Manager extension will execute each Task within the given Task Set. This includes dynamic property evaluation and workflow.

In addition to its main out-of-the-box process of creating subcases, Dovetail Task Manager is an enabling technology, meaning that it supports messages flowing into Carrier, where custom functionality can reside. For example, this would enable the Dovetail system to invoke custom code within Carrier, such as calling into another system via a web service.

Task Manager Extension requirements:

Tasks and Task Sets are managed within Dovetail Agent (starting with version 10).

Tasks Properties can be resolved based on a rule property. In addition to normal rule properties, Carrier also has support for Function-based Rule Properties.

Process Flow

task manager process flow

Message Parameters
Parameter Value
Type RunTaskSet
TaskSetName The name of the task set to be executed
CaseId The case id number to be used when executing the task set

Example Message

Type=RunTaskSet
TaskSetName=New Employee
CaseId=100

Parent-Child Cases Extension

The Parent-Child Cases Extension allows for automating workflow processes involving parent-child cases.

This extension currently supports one message type, namely CloseChildCases. This allows for automatically closing all the child case of a parent case.

A common use case for this is to have a business rule that fires when a parent case is closed. This rule will send a message to Carrier, and Carrier will close all of the child cases. An internal note will be logged to the parent case with details.

Example Message
type=CloseChildCases
caseID=12345
Status=Closed
Resolution=Auto-Closed
Summary=Automatically closed via Dovetail Carrier extension
Integration with Rulemanager

Dovetail Rulemanager supports a business rule action type of Carrier Message, which will send a message to Dovetail Carrier.

This allows a business rule to be crafted that will close the child cases.

Example business rule
Object TypeCase
Rule Name/DescriptionWhen the parent case is closed, close all the children
Start EventsClose Task
Cancel EventNone
ConditionsNumber Of Child Cases > 0
Action TitleAuto-Close the Children
Create Activity Log Entry?true (checked)
Who to Notifyno one (leave empty)
Start Action0 minutes
FromEvent Creation
UsingElapsed Time
RepeatNever
Message TypeCarrier Message
Message type=CloseChildCases
caseID=[Object ID]
Status=Closed
Resolution=Auto-Closed
Summary=Automatically closed via business rule

Note: The Number Of Child Case rule property (used in the business rule condition) is a custom Function-based Rule Property, freely available at https://dovetailsoftware.github.io/property-extensions/

Note logged to the Parent Case

When this message is handled, an internal note will be logged to the parent case with details of what happened, including which cases wre closed, which are already closed, and which could not e closed (along with the reason why it could not be closed).

Example of note that is logged
Closing all child cases…
Case 4222 - closed
Case 4268 - closed
Case 4267 - already closed
Case 4268 - not closed. This case has open general subcases, therefore it cannot be closed.
---
Closed: 2
Already Closed: 1
Not Closed: 1

Communications Extension

Dialogues and Communications

A Dialogue is a roll-up of all of the back-and-forth communications on a particular topic, such as a customer support request. Each individual exchange is represented as a Communication, which are each part of the same Dialogue.

Communications can occur using different Mediums, such as phone, email, instant message, etc. Within the Medium, there can be multiple Channels. For example, there may be a Support email channel, as well as a Sales email channel. Each Dialogue tracks Communications that are part of the same email thread.

Dovetail Carrier also provides the capabilities for delivery of outgoing Communications.

Topics
Configuration

Configuration for the Communications extension is done through the communicationsExtension.config file in Dovetail Carrier.

Communications Extension Configuration Reference
Attribute Required? Default Description
CommunicationsExtensionSettings.
EmailAccountUserName		 Yes N/A Username of the email account from which the Communications extension should create communications and dialogues.
CommunicationsExtensionSettings.
ChannelDesignation		 Yes N/A Name of Clarify channel defined for incoming email messages.

For more Dovetail Carrier wide configuration settings look at Service Configuration.

Workflow
Basic workflow for dialogues and communications
  1. Customer sends in an email
  2. Dovetail Carrier picks up that email from the email account and pushes it onto the Dovetail Carrier message bus.
  3. Dovetail Carrier picks up the message from the message bus.
  4. If the message does not contain a Dialogue ID number, a new Dialogue is created. Otherwise, the existing Dialogue is used.
  5. A new Communication is created for that Dialogue.
  6. Dovetail Carrier saves any attachments in the email to the file system, and creates them as Attachments within the CRM system.
  7. [OPTIONAL] Rulemanager fires the Route Dialogue rule, which calls the RouteDialogue script, which routes the Dialogue to a Queue.
  8. Agent accepts the Dialogue from the Queue using the Clarify Classic Client.
  9. Agent sends an email reply (new Communication) back to the customer using the Clarify Classic Client.
  10. The Communication delivery status is set to Pending (by the Clarify Classic Client).
  11. Rulemanager fires the Deliver Email Communication rule, which calls the PublishOutgoingCommunication script.
  12. The PublishOutgoingCommunication script pushes a message onto the Dovetail Carrier message bus.
  13. Dovetail Carrier picks up the message from the message bus, sends the outgoing email, and sets the Communication delivery status to Delivered. The message includes the Dialogue ID.
  14. Customer replies to email and the Dialogue ID is retained in email message.
  15. Dovetail Carrier picks up that email from the email account and pushes it onto the Dovetail Carrier message bus.
  16. Dovetail Carrier picks up the message from the message queue, and creates a new Communication for the existing Dialogue.
High Level Components

The following is an overview of the different components typically used (including Dovetail Carrier) as part of end-to-end processing of messages within the CRM system.

Carrier Overview

CRM Database

Data storage for the CRM system

Email Server

Any email server that supports the POP3, IMAP, and SMTP email protocols. You do not need to install any special eResponse You can use separate servers for inbound and outbound email, and even use several servers for different inbound email channels.

Clarify Classic Client

The graphical interface used by agents to work dialogues and communications.

Rulemanager

The engine that processes events (based on business rules) from within the CRM system.

Rulemanager scripts

A set of external scripts used by Rulemanager for performing actions within the CRM system. These scripts may be PowerShell scripts, ClearBasic batch (cbbatch) scripts, javascript or vbscript scripts, or executables. Among other things, these scripts can create messages to be processed by Dovetail Carrier.

Dovetail Carrier

The message processor.

Channels

Communications are related to a Channel. Channels are related to a Medium.

For example, Mediums may be Email, Phone, and Fax.

Within the Email Medium, there may be Channels such as Sales, Support, and General Information.

Each channel has a designation. For email channels, the designation is typically an email address.

When Dovetail Carrier creates a Communication, it must relate it to a Channel.

Dovetail Carrier determines which Channel to use by looking in the database for a Channel (with a Medium of Email) whose Channel designation is equal to the IncomingEmailMessageSettings.InboundCommunication.ChannelDesignation setting within the Service Configuration file.

If the Channel is not found, a new Channel will be created.

Out of Office emails - Communications Extension workflow

When Dovetail Carrier processes an incoming email message within the Communications Extension workflow, if the message is an 'out of office' reply, the email will simply be deleted.

The list of patterns used for determining when an email is an 'out of office' reply are defined in the OutOfOfficePatterns.config file. The patterns in this file can be modified to suit specific business needs.

Bounced emails

When Dovetail Carrier processes an incoming email message, if the message is a bounced email, it creates a new Communication with a delivery status of Bounced.

Stop Words
Emails containing stop words

When Dovetail Carrier processes an incoming email message, if the message contains stop or spam words, the email is simply deleted.

The list of patterns used for determining when an email is spam are defined in the stopWordPatterns.config file. The patterns in this file can be modified to suit specific business needs.

Original Messages

When Dovetail Carrier processes an incoming reply email message containing previous message content, then:

The delimiters for determining the boundary between a current and a previous email message is defined in emailboundarydelimiters.config. The patterns in this file can be modified to suit specific business needs.

Attachment Handling

When processing incoming emails, Dovetail Carrier saves any attachments in the email to the file system, and also creates them as Attachments within the CRM system.

File Storage Location

The base file storage directory is defined by the DovetailCRMSettings.AttachmentsFilePath setting within the Service Configuration file.

This can be either a local path (such as c:\attachments) or a UNC path (\server\attachments).

For each Communication, a directory is created under this path with a directory name that combines the Dialogue ID + an underscore + the number of the Communication within this Dialogue.

For example, if DovetailCRMSettings.AttachmentsFilePath is defined as \fileServer\attachments, assuming a Dialogue ID of 12345, and assuming that this is the 2nd Communication within this Dialogue, then the full path is \fileServer\attachments\12345_2\

TimeStamps

The timestamp used to create a Communication within the CRM system is the timestamp of when the email message was received.

This may be earlier then when the Communication is actually created.

For example, if a customer sends an email at 1:00, its received by the email server at 1:05, and processed by Dovetail Carrier at 1:10, the creation time of the Communication will be 1:05.

Outgoing email not delivered

If an outgoing email Communication is still pending after 8 hours, then Dovetail Rulemanager fires the 2nd action of the Deliver Email Communication rule. This rule calls the EmailDeliveryFailed.bat file. EmailDeliveryFailed.bat sets the delivery status of the Communication to Failed.

EmailDeliveryFailed.bat is included with the Communications Extension as part of the Dovetail Carrier installation.

Refer to the ReadMe.txt file within the EmailDeliveryFailed directory for more details.

Note: The EmailDeliveryFailed.bat file is a wrapper around a PowerShell script. This means that PowerShell is required to be installed on the machine that executes this script ( More details about PowerShell (including download locations) is available at http://microsoft.com/powershell

Message Producers
Outgoing Communication Publisher

OutgoingCommunicationPublisher.exe is a command line application that produces an OutgoingCommunication message onto the message bus.

It takes one parameter, which is the objid of a Communication.

Usage

To use this utility, open a DOS prompt, navigate to the $DovetailCarrier\Outgoing-Communication-Publisher directory, and type:

OutgoingCommunicationPublisher.exe <communicationObjid>

Example:

OutgoingCommunicationPublisher.exe 268435457
Business Rule

A common way to use this utility is through the use of Business Rules. Refer to the Deliver Email Communication Business Rule for specific details.

Customization

Although Dovetail Carrier provides many great features out of the box, it is expected that customers will modify existing Carrier extensions as well as create new ones.

Every Dovetail Carrier extension is provided with source code, so developers can not only customize the existing extensions, but can follow the patterns and examples of the baseline extensions in order to create their own.

Blog Posts

The Dovetail development team has created a series of blog posts that introduce Carrier, provide walkthroughs of example extensions, and guide you through creating your own extensions.

Creating Your First Carrier Extension

Introductory post which takes you through the nuts and bolts of creating your extension project. This post helps you creating the basic outline of a new extension while introducing you the basic concepts you need to know.

Customizing Dovetail Carrier

3 part series which works as a great walk through of the Twitter Agent extension included with the Dovetail Carrier extension source code.

Clock – A Super Simple Carrier Extension

A quick one post introduction to creating a very simple message producing and subscribing extension.

Code Examples
Dovetail Carrier Customizations Examples

The Dovetail Carrier Customizations repository provides examples for working with Dovetail Rule Manager, Carrier, and Task Manager. Examples leverage the Yahoo! Finances API to provide realtime stock quotes. There is also an example of a a simple executable for sending messages to Dovetail Carrier.

Important note: DovetailExtension Attribute

When Carrier is starting up it needs a way to determine which assemblies are extensions. The way to do this is to mark your assembly with the DovetailExtension attribute. Add the assembly attribute to the end of your AssemblyInfo.cs file.

[assembly: DovetailExtension]

If you are creating your own custom extension project, it is important to have this attribute.

Function-based Rule Properties

Function-based Rule Properties are used in a number of places throughout the Dovetail suite, including:

Traditionally, a rule property would traverse a path through the schema, starting from the base object, and ending at a column.

For example, the Contact First Name property for a case would use the path case_reporter2contact:first_name.

However, there are instances where a path cannot be traversed, or where a calculation needs to be made.

For example, you may wish to fire a business rule only if all of the subcases on a case have been closed. So your two business rule conditions would be:

  1. Number of Subcases is greater than zero
  2. Number of Open Subcases is equal to zero

Or, you may wish to fire a business rule if the Number of cases for product X within the last 7 days is greater than 10.

Or you may wish to use a variable (rule property) as part of a canned response that retrieves data from another system using a web service call.

Or you may wish to use a variable (rule property) as part of a task manager property that calculates a value or retrieves data from another system using a web service call.

With these examples, there is not a schema path that can be traversed to provide these values.

You can now write your own custom code for these rule properties. This opens up a whole new avenue for customization.

Dovetail provides an example code project that demonstrates custom Function-based Rule Properties.

This project is freely available at https://dovetailsoftware.github.io/property-extensions/

That link provides more details, working code examples, and steps on how to build and deploy.

Once your code has been written, and the assembly copied into the application directory, then the property can be defined using the Rule Property UI within Dovetail Agent (Agent version 14 or higher).

Edit Rule Property

Copyright © 2023 Dovetail Software, Inc. All rights reserved

Dovetail Software intends the information in this document solely for its licensees and to aid prospective customers in evaluating Dovetail Software products. Any other use is prohibited. Dovetail Software makes a written warranty to its licensees, as is stated in its written license agreement. Dovetail Software makes no warranty to any other party regarding the accuracy or usefulness of the information contained in this document. Dovetail Software reserves the right to modify the content of this document without obligation to notify any party. Dovetail Software is not liable for consequential or incidental damages.

Dovetail Software develops and supplies software and customizations to the following Clarify products: ClearSupport, ClearQuality, ClearHelpDesk, ClearContracts, Policies and Customers, ClearSales, ProductManager, ClearCallCenter, and ClearLogistics.

Many Dovetail Software products use the following Clarify tools: User Interface Editor, ClearBasic Exchange, Data Dictionary Editor, ClearBasic Batch, Data Exchange, Clarify Business Objects, RuleManager, eBusiness Framework, ClearBasic, and Clarify Low-Level API©.

Clarify, its product names, and tools are trademarks of Amdocs, which may include the following: AmdocsCRM, ClearConfigurator, SalesBasic, ClearConfigurator Workshop, Notifier, eSupport, Classification Engine, eOrder Routing Server, eResponse Manager, ClearEnterprise, Email Clerk, Email Manager, Traveler, e.link, Diagnosis Engine, and Flexible Deployment.