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