Introducing the SDK Toolkit extension in Dovetail Carrier
Gary Sherman
August 2, 2016

We recently released an updated version of Dovetail Carrier, and this version includes a new SDK Toolkit Extension.

I’m super excited about this new extension – so lets get into the details.

But first, a quick refresher on Dovetail Carrier.

 

What is Dovetail Carrier?

Carrier is a flexible and customizable message handling framework for your Dovetail or Clarify CRM application. It allows the automation of virtually any internal CRM processes associated with communicating with external systems. Carrier uses messaging, a method of communication between software components or applications that enables distributed communication that is loosely coupled, to enable organizations to establish efficient dataflow between their systems.

carrier components including the SDK Toolkit extension

 

Extensions

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.

Baseline Extensions

Carrier ships with the following extensions

  • Email Agent Extension: 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 sub case. Emails about new issues will create cases. This extension is an effective replacement for Clarify EmailClerk and Dovetail’s standalone Email Agent product.
  • Task Manager Extension: Processes messages received from Dovetail Rulemanager. These are typically part of the Dovetail Task Manager process. The Task Manager extension will execute each Task within the given Task Set. This includes dynamic property evaluation and workflow.
  • Communications Extension: 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.
  • SDK Toolkit Extension: A new extension being discussed in this blog post. It allows for executing Dovetail SDK Toolkit methods.

Custom Extensions

You can also write your own custom extensions. We have a number of examples and sample code available that walk you through how to do this:

 

SDK Toolkit Extension

The latest available extension is the SDK Toolkit Extension, which allows for executing methods within the Dovetail SDK Toolkits, without writing any code.

We can now invoke hundreds of available APIs – without writing code. That’s pretty badass!

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

The Toolkits provide convenient business logic wrappers for most of the common tasks performed within Clarify/Dovetail. These include, but are not limited to: Creating cases, solutions, contacts, change requests, and site parts, performing workflow operations like assigning cases and dispatching change requests, and performing logistical operations such as moving and installing parts.

Toolkits

The Toolkits in the SDK are divided into functional areas that map closely to Clarify products. For example, the FChoice.Toolkits.Clarify.Support namespace and, specifically, the Support Toolkit object reflect most or all of the functionality in the ClearSupport product for Clarify.

Toolkit    Namespace
Contracts    FChoice.Toolkits.Clarify.Contracts
DepotRepair    FChoice.Toolkits.Clarify.DepotRepair
FieldOps    FChoice.Toolkits.Clarify.FieldOps
Logistics    FChoice.Toolkits.Clarify.Logistics
Interfaces    FChoice.Toolkits.Clarify.Interfaces
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 an operation or ‘API’.
Again, all of the Toolkits, Methods, and Method Parameters are documented within the Dovetail SDK Documentation.

As an example, here are the methods available within the Support Toolkit:

AcceptCase CloseCase GetCaseTimeAndExpenses LogCaseResearch MoveSubcase
AcceptSubcase CloseSubcase GetSubcaseTimeAndExpenses LogSubcaseCommitment RejectCase
AppendHistoryToCase CreateCase InitialResponse LogSubcaseEmail RejectSubcase
AppendHistoryToSubCase CreateCaseObjid LogCaseCommitment LogSubCaseEmailIn RelateCaseToParentCase
AssignCase CreateSubcase LogCaseEmail LogSubcaseInternalNote ReopenCase
AssignSubcase DispatchCase LogCaseEmailIn LogSubcaseInternalPhone ReopenSubcase
ChangeCaseContact DispatchSubcase LogCaseInternalNote LogSubcaseNote UnrelateCaseFromParentCase
ChangeCaseSite ForwardCase LogCaseInternalPhone LogSubcasePhone UpdateCase
ChangeCaseStatus ForwardSubcase LogCaseNote LogSubcaseResearch UpdateCaseCommitment
ChangeSubcaseStatus FulfillCommitment LogCasePhone MoveCase UpdateSubcase
UpdateSubcaseCommitment YankCase YankSubcase    

 

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. Most of our APIs have two overloads. The first one has just the required parameters as inputs; the bare minimum. The second takes a Setup object as an input, which contains all of the available properties. The SDK docs have more details on Setup objects.

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

 

Example 1

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:

    • public ToolkitResult CloseCase(string caseIDNum)
    • public ToolkitResult CloseCase(CloseCaseSetup setupParam)
    • 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 2

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:

    • public ToolkitResult CloseCase(string caseIDNum)
    • public ToolkitResult CloseCase(CloseCaseSetup setupParam)
    • 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 3

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/Dovetail 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 Carrier.

This allows a business rule to be crafted that will invoke a Dovetail SDK API. 

Usage Examples

  • When the first Log Email or Log Phone is logged for a case by a support agent, then call the InitialResponse API.
  • When a customer logs a note to a case via SelfService, call the ChangeStatus API, setting the status to Customer Responded.
  • If a case has been sitting in a queue for more than 24 hours, call the UpdateCase API, setting the Priority to High.
  • If the case status is Close Pending, and the customer has not responded to the case in 3 days, then call the CloseCase API.

 

Example business rule

Here’s an example of a business rule that will automatically call the ChangeCaseStatus API when a customer logs a note to a case in SelfService.

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


 

Messaging without Rulemanager

In a previous post, I showed how to Publish a message to Dovetail Carrier to invoke a custom action. This published a message into Carrier’s queue using publish.exe.

We can use that with our new message types as well.

For example, here I can call publish.exe, passing in my message, and that will log a note to a case:

image

 

This is great for testing and development purposes.

 

And if you wanted, you could take that code from publish.exe (it’s freely available on Github), and work that into your own application – executable, web service – whatever.

This would allow you to perform actions in Dovetail/Clarify without having to use our SDK, and without needing a database connection.  Distributed systems FTW!

 

Less Moving Parts, Better Performance, and Reliability

In the past, if I wanted to have a business rule invoke an API, I would create the business rule, have that business rule call a BAT file, that BAT file would call script (such as a powershell script), and have that powershell script fire up the SDK, and then invoke the API.

Every time that script was called, it would have to establish a new database connection, log in, perform application initialization (which would cache a bunch of data), perform session initialization (which would also cache a bunch of data), then invoke the API, then shut down. I would also have to deal with separate logging and log files for each script. I also needed to worry about deploying these scripts to my test and production environments.

Now, I simply have the business rule send a message to Carrier. Carrier is already logged in to the database, it already has all of its needed data cached, it already has logging setup and configured. And there aren’t any files that need to be deployed.

So now I have less work to do myself, there are fewer processes running on the server, and my operations execute faster.

Plus, I get the reliability built into messaging. For example, if Carrier is temporarily down, the message won’t be lost. It will remain in the MSMQ queue, and will be picked up when Carrier restarts.

 

Summary

With the SDK Toolkit Extension, we’ve opened up a new avenue for performing custom actions within your system, and doing it without writing or deploying code. I’m super jazzed about these new capabilities!

For a long time, the primary use of Dovetail Carrier was for processing emails. We knew the power of using messaging to extend the capabilities of the system, and we’re excited that we’re finally taking advantage of this power beyond email. The Task Manager extension, SDK Toolkit extension, and custom extension examples really highlight the power of what Carrier can do.

We’re already starting to take advantage of these new Carrier capabilities in our own production environment. I’ll have an additional post or two soon that demonstrates what we’re doing.

I know there’s a lot of information in this post, so if you have any questions, or want to discuss in more detail, feel free to reach out to me – I’m happy to help.

Leave a Comment

International: +1 (512) 610-5400
Toll Free: 1 (800) 684-2055