REQUEST A DEMO

Carrier – Customizing Your Response Emails

 

Out of the box Dovetail Carrier is very good at receiving emails and allowing you create business functionality which can react to incoming messages. There is a flip side to receiving emails. Sending them. This post will explain how the Email Agent extension uses templates to send email notifications. First we need to explore what information your template will have available to it. We’ll start by setting the stage.

 

Real World Scenario

 

In the Email Agent extension. When an email is received by your company’s support account the New Case Support Email rule set is invoked. This rule set determines that the email is a request for support and a new case is created. The next rule action should send a response email. What should the email tell the user?

 

  • It should inform them of details about the new case they just created.
  • It would also be really nice to send them a hyperlink for viewing this case over at our self service web site.

 

These two things translate into the following bits of information.

 

  • Which email address do we send the message to?
  • The title of the new case.
  • What is the database identifier. We’ll use it to link the customer to their new case on our self service site.

 

The good news is that luckily, and by luckily I mean by design, this information is already available to the send notification action via the RuleContext object.

 

Rule Context

 

The bits of information we need to communicate can be found in the rule context. Let’s take a look at how the information we need gets put into the rule context.

 

The rule context is important. It is the glue that ties all the conditions and actions together letting them communicate with each other by pushing state into the context or by finding state put into the context by previous rule actors.

 

The Omnipresent Message

 

The rule context will always have the current message being processed. In this case the message being processed is an IncomingEmailMessage whose From property contains the sender’s email address.

 

Create Case

 

The case details are pushed into the context by the action which creates the case. How do you know this?  You have the source code. Review the previous actions and conditions to see what objects get pushed into the rule context.

 

public class CreateCase : IAction<IncomingEmailMessage>
{
//...
	public void Execute(IRuleContext<IncomingEmailMessage> context)
	{
		var contact = context.Find<Contact>();

		var title = context.Message.Subject;

		Case caseCreated = _dovetailSdkToolkitAdapter.CreateCase(contact, title);

		_logger.LogInfo("Case {0} created with title {1} for email {2}.", caseCreated.Id, 
title, context.Message.Id);

		context.Push(caseCreated);
	}
}

 

Notice how the create case action pushes a Case object into the rule context. Every condition and action from this point on can Find this case in the rule context.

 

	public class Case
	{
		public string Id { get; set; }
		public string Title { get; set; }
		public bool IsOpen { get; set; }
		public string[] AttachmentFilePaths { get; set; }
	}

 

Present on this Case object are two other bits of information we are looking for, the case identifier, and title.

 

Hopefully spelunking around in the code a bit gives you context and confidence about where your templates will get their information from.

 

Template Engine

 

At this point we could easily create a rule action which builds an email body in code an sends an email. If we do this. What happens if someone wants to change the email’s format? We edit code. Recompile. Redeploy the extension. Yuck. That is a lot to do for such a small change.  This is where a template engine comes in handy.

 

Carrier ships with support for creating email’s using the Spark view engine. In this case the view is an HTML email populated by anything found within the rule context.

 

Create Case Notification Example

 

Here is the create_case_success.spark template used by the Email Agent extension to populate the create case notification email.

 

var caseCreated="Context.Find[[Case]]()"/

html
body
h1Case ${caseCreated.Id} Created/h1
p 
  We have opened a support case (${caseCreated.Id}) based on your email titled ${caseCreated.Title}.
/p
!--
p
  Did you know you can track your case at our support web site? 
  br/
  a href="http://support.yourdomain.com/Cases/Show/${caseCreated.Id}"View Case ${caseCreated.Id}/a
/p
--
/body
/html

 

The only thing provided to the template by Carrier is the rule Context from which the Case is being retrieved. Remember that the CreateCase action (above) pushed the Case object into the rule context.

 

Notice is how we get the Case object out of the rule context. The rule context’s Find method requires a generic argument which has a special syntax in spark.  If you needed get another type of object out the the rule context just replace Case with the object’s type.

 

var caseContact="Context.Find[[Contact]]()"/

 

Notice how the example has the link to the fictitious self service web site commented out. Hopefully you get the idea that customizing this template would not be hard.

 

More .spark files are included with Carrier’s Email Agent extension for other situations like logging a note to a case or subcase.

Administrative Example

 

Here is a more complicated example which pulls a few more interesting bits from the rule context. This template is used, in the unfortunate event of a water landing, by the Email Agent extension to send your administrator exception details.

 

var exception="Context.Find[[Exception]]()"/
var ruleSetName="Context.Find[[RuleSetSettings]]().RuleSetName"/
var message="Context.Message"/
html
  body
    h1Email Agent Error/h1
    p
      Email Agent encountered an error while processing the ruleset strong${ruleSetName}/strong.
      The original email message (id:${Context.Message.Id}) causing this error is attached to this message.

      Note: the original email may not be attached if for some reason it was already deleted by the ruleset.
    /p

    h2Email Body/h2

    ${message.Body}

    h2Exception Details/h2
    pThe following is detailed information about the exception thrown by the ruleset./p
    br/
    pError Message: ${exception.Message}/p

    h3Stack Trace/h3
    pre${exception.StackTrace}/pre

    h3Verbose Output/h3
    pre${exception.ToString()}/pre
  /body
/html

 

This administrative example uses the exception, which is automatically pushed into the rule context by Carrier’s error handling, and the rule set name to give the Carrier administrator exciting details about the problem. The troubled email is sent along with the error notification for potential republishing. For more details check out the source for the NotifiyAdministrator action.

 

Conclusion

 

Hopefully this post gives you confidence, and supplementarily the information, you need to customize Email Agent extension email response templates. If you are interested in creating new rule actions that use the Spark view engine to generate emails please take a look at the source code included with Carrier. In particular the SendContactACaseCreatedNotification class.