Dovetail Carrier Documentation

Previous Versions

Version 3.1.3

Enhancements

None

Bug Fixes

Issue: Emails that contain a file attachment whose file name contains Unicode or special characters (that are disallowed as filenames in Windows) could lead to broken links in Dovetail Agent, and the attachment file cannot be downloaded. (Special characters are those such as: / \ : * ? < > |).
Fix: These characters are now replaced by an underscore character, and the attachment can be properly accessed within the Dovetail Agent application.
Issue: Emails that contain a file attachment with an unsupported image format (such as HEIC image files) could cause an Out of Memory error. This would happen when trying to determine the image height and width.
Fix: The Out of Memory error will no longer occur in this scenario. If the Windows server does not contain a codec (encoder and decoder) for the given image type, then the file attachment will be saved as normal, but its image_height and image_width (in table_doc_path) will not be calculated.
Issue: Emails with an empty body were not handled properly, and could result in a Carrier error, or the email being discarded.
Fix: Emails with an empty body are now logged properly. The empty email body will be replaced with "This message has no content". This allows the email to be recorded, any email attachments to be saved, and any workflow rules (business rule or auto-destination rules) to be executed.

Upgrading to Version 3.1.3

Stop the Carrier Windows service. Be sure to close the Windows Services application window after doing so.
Backup any Carrier files that you have previously modified (such as .spark files, .config files, or custom extensions)
Un-install the old version of Carrier
Install the new version of Carrier
Merge any of your existing changes with updated files, then copy the merged files back into the carrierservice directory.
The following are files modified in this version that may need to be merged with your customizations:
- DovetailCarrierService.exe.config (new DovetailDatabaseSettings.SessionTimeoutInMinutes setting).
Start the Carrier service

Version 3.1.2

Enhancements

A new Warning message will be logged for every email received from an account which is not specified in EmailAgentExtensionSettings.EmailAccountUserName setting within the emailAgentExtension.config file.
Logging of actions performed for each incoming email has been improved to communicate the email id, actions taken, and condition evaluation results.
The EmailAgentExtensionSettings.AdministratorEmailAddress setting within the emailAgentExtension.config file supports a comma-separated list of email addresses.
MSGraph Email Service has been enhanced to handle throttling scenarios:
- Added transient exception detection functionality with exponential delay methodology for retries.
- Added new MsGraphExecutorSettings keys to control the retry process in response to a transient exception.
New connection string parameters: Integrated Security=SSPI; and Persist Security Info=True; can be used 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.
Required configuration setting: DovetailDatabaseSettings.SessionTimeoutInMinutes key must be used with a value greater than zero.

Additional Changes

If an unexpected exception happens when processing an email, the email will be saved to a new DeadLetters folder, which will be located at {EmailServiceSettings.EmailStoragePath}\DeadLetters. By default, this would be C:\ProgramData\DovetailCRM\Carrier\Email\DeadLetters. When this scenarion happens, an email will also be sent to the administrator email address (EmailServiceSettings.AdministrativeNotificationEmailAddress), alerting the administrator of the problem. This DeadLetters folder is separate folder which can be useful in identifying emails that encountered this unexpected scenario.
A change has been made to avoid log4net StringFormat exception when logging a JSON response from a non-successful URL invocation. If a JSON response is received it will be detected as such and properly formatted for logging.

Bug Fixes

Fixed the DLL version mismatch error for log4net.dll when reprocess-errored-messages.bat is used.
Fixed the StructureMap error for when carrier-diagnostics.exe is used.
Fixed a bug which caused the MessageBusSettings.ConcurrentConsumers setting value being ignored.

Version 3.1.1

Enhancements

Before saving any eml file it's name is to be modified to replace with "_" any character deemed invalid by Windows File System. Any resulting duplicate file name is to be appended with an index.

Version 3.1.0

Enhancements

Added support for Oracle database version 19c.

Version 3.0.0

Enhancements

In addition to POP3 and IMAP, Carrier can now poll email accounts using an Azure application and the Microsoft Graph API. This is useful when using Exchange Online. Refer to the MS Graph Account Configuration section for more details.
In addition to SMTP, Carrier can now send email using an Azure application and the Microsoft Graph API. Refer to the MS Graph Account Configuration section for more details.

Version 2.8.0

Enhancements

The MailBee email support library has been updated to version 12.1.1 to add support for Transport Layer Security (TLS) 1.2.

Requirement Change

Requires Microsoft .NET version 4.7.x.

Upgrading to Version 2.8.0

Confirm that your server has the Microsoft .NET Framework version 4.7.2 or higher
Stop the Carrier Windows service. Be sure to close the Windows Services application window after doing so.
Backup any Carrier files that you have previously modified (such as .spark files, .config files, or custom extensions)
Un-install the old version of Carrier
Install the new version of Carrier
Merge any of your existing changes with updated files, then copy the merged files back into the carrierservice directory.
Start the Carrier service

Version 2.7.0

Carrier Core

During email parsing, the HTML scrubber is no longer removing HTML that is embedded in the email after comments.

Email Agent Extension

Emails that include attachments but have an empty body are now able to be processed normally. Previously no email log was being created.

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

Update to use the latest Dovetail SDK

Email Agent Extension

Fix typo in the admin_notification_no_case_created.spark template (used when creating cases is disabled).

Version 2.5.0

Carrier Core

Add support for a new message type of RefreshCache which will force Carrier to refresh its cache of frequently used data, such as schema, lists (application and user-defined), configuration items, strings, etc.
At application startup, don't log the connection string to the log file.
Bug Fix: Incorrect log entry regarding licenses when a Task Manager license key is not present

Email Agent Extension

Allow for disabling creating cases using a new EmailAgentExtensionSettings.CreateCases setting.
Bug Fix: Out of memory exception when processing an email that has a corrupt (or empty) image file

Upgrading to Version 2.5.0

Stop the Carrier Windows service. Be sure to close the Windows Services application window after doing so.
Backup any Carrier files that you have previously modified (such as .spark files, .config files, or custom extensions)
Un-install the old version of Carrier
Install the new version of Carrier
Merge any of your existing changes with updated files, then copy the merged files back into the carrierservice directory.
The following are files modified in this version that may need to be merged with your customizations:
- DovetailCarrierService.exe.config (assembly binding changes)
- emailAgentExtension.config (new EmailAgentExtensionSettings.CreateCases setting)
Start the Carrier service

Version 2.4.2

Carrier Core

Upgrade to latest Dovetail SDK and dependent assemblies

SDK Toolkit Extension

Allow for durations in DateTime parameters
Add support for TimeSpan parameters

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

Upgrading to Version 2.4.2

Stop the Carrier Windows service. Be sure to close the Windows Services application window after doing so.
Backup any Carrier files that you have previously modified (such as .spark files, .config files, or custom extensions)
Un-install the old version of Carrier
Install the new version of Carrier
Merge any of your existing changes with updated files, then copy the merged files back into the carrierservice directory.
The following are files modified in this version that may need to be merged with your customizations:
- DovetailCarrierService.exe.config (assembly binding changes)
Start the Carrier service

Version 2.4.1

Bug Fixes

Trim white space during message data parsing. Previously, extra spaces around a message parameter or value would be honored, which could lead to messages not being processed as expected.

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

Confirm that your server has the Microsoft .NET Framework version 4.5 or higher
Stop the Carrier Windows service. Be sure to close the Windows Services application window after doing so.
Backup any Carrier files that you have previously modified (such as .spark files, .config files, or custom extensions)
Un-install the old version of Carrier
Install the new version of Carrier
Merge any of your existing changes with updated files, then copy the merged files back into the carrierservice directory.
The following are files modified in this version that may need to be merged with your customizations:
- emailAgentExtension.config
- DovetailCarrierService.exe.config
- Carrier.Extensions.EmailAgent Extension
Start the Carrier service

Version 2.3.0

Enhancements

Add support for Function-based Rule Properties
Business Hour calculations now support holidays

Upgrading to Version 2.3.0

This requires a database schema change. Follow the instructions in Update the Clarify Schema to apply the schema changes.

Version 2.2.0

Email Agent Extension

Enhancements

Store additional attachment information, specifically mime type, file size, and image dimensions.

Bug Fixes

Resolved a System.NullReferenceException error that could occur when performing business hour calculations.

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

Use DovetailCRMSettings.EmployeeUserName setting for subcase creator
Do not execute inactive task sets
The log message for an invalid task set name has been changed from DEBUG to ERROR

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:

Dovetail Rulemanager version 2 or higher
A Dovetail Task Manager license key

Email Agent Extension

Enhancements

A new EmailAgentExtensionSettings.DeleteEmails Configuration setting controls whether Email Agent will delete the email (from the file system) after processing it.
Improve the HTML scrubbing (HTML to plain text conversion) process on incoming emails.

Upgrading to Version 2.0.0

If using the Task Manager Extension, Install Dovetail SDK version 3.4 or higher. As of Dovetail SDK version 3.4, Subcase ID Number generation is handled by a new stored procedure (fc_next_subcase_seq). This stored procedure needs to be compiled to your database. Refer to the Dovetail SDK documentation for more details.

Version 1.4.2

For incoming emails, save the email message id to the email log record.
When adding attachments, relate the attachment record to the email log record.

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

Updated the Dovetail SDK dependency to version 3.3.7.7
Updated Email Agent Extension to use the email subject when logging emails to cases and subcases.

Version 1.4.0

Resolved an issue where a single email message sent to multiple email addresses that are being monitored by Carrier could result in the message being processed multiple times, and in some cases, throw an error when trying to read the .eml file to access attachments within the email.

Version 1.3.4

Added documentation and installation folder for Reprocessing Failed Messages.

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

Updated the Dovetail SDK dependency to version 3.3.5.35
Resolved issue with the DovetailCRMSettings.AttachmentMode setting not being honored.

Version 1.3.2

Fix issue where emails with an empty subject would throw an error.
Fix issue where emails without any recipients would throw an error.

Version 1.3.1

Fix Email Agent Extension to handle incoming emails with an empty To field.

Version 1.3.0

Core

Resolved a log4net assembly binding issue.
Resolved the error "Could not load file or assembly ADODB" when Dovetail SDK was not installed on the same machine as Dovetail Carrier.

Email Agent Extension

Added support for multiple email addresses. Simply use a list of comma-separated email addresses in the EmailAgentExtensionSettings.EmailAccountUserName setting:

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

Carrier-Diagnostics

Updated the help text for carrier-diagnostics.exe to be correct for configuration file changes made as part of version 1.2.

Version 1.2

Core

Infrastructure update to the latest version of the underlying message bus and windows service technologies being used.
Removed the Twitter extension example as it has not been working due to Twitter API changes.
Improved the code responsible for turning HTML emails into plain text.
A number of small logging changes.

Email Agent Extension

Log Email now truncates sender and recipient details if they will not fit into their database fields. The original values are logged as warnings.
Log Email operations now populate the email_log.cc_list field with any CC data from the incoming email.
Log Email operations now populate the email_log.x_subject field (if this field exists) with the subject from the incoming email.
The act_entry record for Log Email and Create Case operations are now related to the contact (if found) who sent in the incoming email.

Configuration File Changes

emailService.config and email-accounts.config files have been removed. The settings from those files are now included in DovetailCarrierService.exe.config.
This simplifies configuration, and also allows for encrypting of sensitive information, such as email account usernames and passwords, as well as database connection information.
For more information on encrypting configuration files: https://support.dovetailsoftware.com/selfservice/solutions/show/619

Requirement Change

Requires Microsoft .NET version 4 (4.0 or 4.5.x)

Version 1.1.12

Fixed an issue related to the scoping of database transactions when consuming messages with rule sets.

Email Agent Extension

Reverted to behavior where Auto Destination happens as a separate message after creating a case. The option is present to do Auto Destination in-line with the create case rule set. The reason we restored this behavior is that in the event of a locking issue with auto destination. This new behavior will allow the case to be created.
Storing email attachments now supports configuring the strategy used for selecting the directory structure when storing the file.

Version 1.1.11

Email Agent Extension's Auto Destination action now happens during creation of new cases. Previously auto destination was evaluated separately as part of its own ruleset.

Version 1.1.10

Added a email configuration settings diagnostic command line tool to assist administrators in verifying configuration settings without having to start up the Dovetail Carrier Windows service.
Fixed a bug which was causing SMTP authentication issues with Exchange 2010 email servers.
The Communications Extension is no longer installed by default.

Version 1.1.9

The previous release was missing a logging support assembly.
Added additional debugging support.

Version 1.1.8

Email Server Connectivity

Email service settings now have a SmtpSslMode configuration setting allowing better control over how secure connections with SMTP servers are negotiated.
Pop3 and IMAP connections using secure connections in Manual mode were not properly starting the secure connection.
Added better logging around email connectivity.

Version 1.1.7

Fixed a bug affecting Oracle users where the Dovetail SDK did not want to initialize properly.
Updated the Dovetail SDK dependency to version 3.2.3. This update contains many bug fixes but notably for Dovetail Carrier it corrects a few database transaction related bugs.
Restored the zipped Dovetail Carrier extension source code which was accidentally excluded.

Version 1.1.6

Added better control of how secure IMAP and POP3 connections are made see email account configuration for more details.
Fixed bug where the email account port configuration was not being used.

Version 1.1.5

Previously only one message consumer was processing incoming messages. The default is now two times the number of processors. This setting is now configurable.
Many Dovetail Carrier extensions use regular expressions to allow for configurable message handling. Regular expression evaluation now has a configurable timeout to avoid rare occurrences where complex regular expressions fail to evaluate in a timely manner.

Version 1.1.4

The name of the Dovetail Carrier windows service is now "DovetailCarrier" (was DovetailCarrierService). This change has been made across all our products with Windows services for consistency. Please be aware that this change may affect service monitors or automation scripts.
Doing a better job managing database connections across RuleSet executions.
The MailBee email support library has been updated to version 6.2.
Log4Net default settings now include thread details in log output.

Version 1.1.3

Carrier will now use Dovetail SDK application settings when they are present.
When converting the contents of HTML email bodies to text we now have better whitespace handling
Detection of bounced emails has been improved.

Version 1.1.2

With this release we are introducing a new extension included with Dovetail Carrier: Email Agent. The Email Agent Extension has similar functionality to the FreeForm mode of our stand alone Dovetail Email Agent application.
Added support for email accounts which use the IMAP email protocol. We have renamed the pop3-account.config file to email-accounts.config to reflect this. Please move the pop3Account configuration elements from your old pop3-account.config into the new configuration file.
Also included in this release with the extension source code are two new examples: a simple Clock example and Twitter Agent.
The Clock example extension is a comprehensive yet simple sample showing how to publish and consume messages.
Twitter Agent demonstrates Email Agent like functionality while using the direct messages within the social networking service Twitter as the medium rather than Email.
Extensions assemblies are now marked with the DovetailExtension attribute. During application startup any assembly having this attribute found in the Dovetail Carrier application directory is configured as an extension.
The email publishing service is no longer started up automatically. Dovetail Carrier is now more intelligent about Message Publishing Services. A Message Publishing Service for a given message type will automatically be started when there are rule sets defined for the message type.
A message published into Carrier having no subscribers will be removed. Previously such a message would forever sit in the message queue.
Dovetail SDK updated to version 2.4.8.

Version 1.0.8

Dovetail SDK updated to version 2.4.6

Version 1.0.7

Fixed a regression that caused line returns to be stripped from HTML emails.

Version 1.0.6

Tracking Ids are now removed from the title of communications created from incoming emails.

Version 1.0.5

Poorly formed HTML content within incoming emails was causing email content to get truncated after unescaped angle brackets. This issue has been corrected for content in <pre> tags.
Additionally Html to Plain text conversion no longer strips line returns from Html content.

Version 1.0.4

Outgoing communications emails were not getting CC and BCC recipients added to the email.

Version 1.0.3

Dovetail Carrier was being too strict when retrieving email communications regarding the type of electronic address medium.

Version 1.0.2

Updated Dovetail SDK to fix activity entry details when creating dialogues.

Version 1.0.1

Updated the version of the Dovetail SDK to correct a bug which prevented dialogues and communications from being updated when they are closed.

Version 1.0

This is the initial release of this product.