Friday, April 08, 2011

Taking UCommerce emails to the next level and include the order id in the subject, multiple recipients and Google click tracking

One of the things that I've felt has always been a little lacking in uCommerce was their email system, it's a great idea and nicely implemented but it was rather inflexible in earlier version -you couldn't send "other" emails easily etc.

Most of these bug bears have now been resolved however I still feel that even the latest v1.5 release is a few lacking features that we have tended to build into our email systems by default:

• No ability to use place holders e.g. include the uCommerce order id in the subject line or write "Dear John" as a greeting
• It didn't allow you to send to multiple CC or BCC recipients
• There's no click tracking built in

So what does it do?

In our recent project - www.ChalkboardsUK.co.uk, we extended the existing EmailService and "patched" the missing functionality. There's more we can (and will) do with this in the future but for now this should get you started.

By passing in a combination of QueryString and Placeholder parameters, you can send personalised emails to your customer e.g. have a subject line of "Your order with our store #1234" or start your email with "Dear John".

As well as enabling place holders it allows you to send your email to multiple recipients at the same time by simply separating the CC or BCC addresses with a semi-colon.

Finally (and I think this is pretty darn cool), it automatically tags the links within your email with the Google Analytics tracking code! By using the EmailProfile it will enable you to see whether customers are clicking through on links etc within your emails. Pretty cool eh!

The future

We're open to your thoughts on this and ideas for moving it forward but at the moment, we will be adding functionality:

• Pass in a core objects e.g. a purchase order to give them access to any aspect of the data
• Add the ability to format strings
• Repeating regions (though this should really be done within your XSLT) Let me know what you think by leaving a comment, tweeting @timgaunt or emailing me.

Download It

You can download the file right now by clicking here (TheSiteDoctor.UCommerce.EmailService.zip).

How to use it?

The use of this depends on your individual setup, in this post I'm going to assume you've got a separate assembly which you can include this in however I'll post another post soon which wraps this all up into a pipeline. We also use this for the customer "welcome" emails as well so we can send a pretty email welcoming them to the store.

uCommerce changes

Nothing needs to change in the way that you setup your emails in uCommerce. If you would like to send to multiple CC or BCC recipients, simply separate the addresses with a semi-colon (;) as you would in your standard email client:

Umbraco Changes

If you want your content editors to be able to include properties from the order in your email, they'll need to use place holders. At present, the place holders are fairly limited in that there's no repeating regions etc. You can inject anything you want (you'll just need to add the key to dictionary of place holders when constructing the email. The user can then use that value in the email by surrounding the key with square braces e.g. [Order.Total].

An example email:

Hi [Customer.FirstName]

Thank you for your order of £[Order.Total] on [Order.Date]. The details of your purchase are below.

Using it in your code

I would think the most common application for this at the moment will be within your own custom pipelines. If you've already used the UCommerce.Transactions.EmailService then you can retty much just replace the code. If you've not, here's an overview of how you can do it yourself:

// Create an instance of the EmailService
var service = new TheSiteDoctor.uCommerce.Transactions.EmailService();

try
{
    // Get the current catalog's email context
    var profile = SiteContext.Current.CatalogContext.CurrentCatalogSet.EmailProfiles.Single();

    // Setup the QueryString Parameters for the page that's got the various content on -in this instance we're just getting an order confirmation so just pass in the order number
    Dictionary<string, string> qs = new Dictionary<string, string>
        {
            { "orderNumber", purchaseOrder.OrderGuid.ToString() }
        };

    // Add the various bits of information you want to be able to pass to the content
    Dictionary<string, string> ph = new Dictionary<string, string>
        {
            { "Customer.FirstName", customer.FirstName },
            { "Customer.LastName", customer.LastName },
            { "Customer.EmailAddress", customer.EmailAddress },
            { "Order.Number", purchaseOrder.OrderNumber },
            { "Order.Date", purchaseOrder.CompletedDate.Value.ToShortDateString() },
            { "Order.Total", purchaseOrder.OrderTotal.Value.ToString("f2") }
        };

    // Send the email
    service.Send(profile, EmailTypeName, new MailAddress(customer.EmailAddress), qs, ph);
}
catch (Exception ex)
{
    // Something "not good" happened so add any other info that might be of help
    // Add the customer data
    ex.Data.Add("Customer.FirstName", customer.FirstName);
    ex.Data.Add("Customer.LastName", customer.LastName);
    ex.Data.Add("Customer.EmailAddress", customer.EmailAddress);

    if (purchaseOrder != null)
    {
        ex.Data.Add("OrderId", purchaseOrder.OrderId);
        ex.Data.Add("Order.Number", purchaseOrder.OrderNumber);
        ex.Data.Add("BasketId", purchaseOrder.BasketId);
    }

    // Send/log your alert
}

Taking UCommerce emails to the next level and include the order id in the subject, multiple recipients and Google click tracking

Useful Links:            Comments [3]  Trackback

Tags: ASP.Net | C# | The Site Doctor | uCommerce | Umbraco

Friday, April 08, 2011 2:15:00 PM (GMT Daylight Time, UTC+01:00)

Hi Tim,

Great article!

There's one thing I'd like to clarify. When you use the standard EmailService the idea is that you'll pass in a reference to the configured e-mail template, which in turn retrieves the relevant information using standard Umbraco code be it XSLT, Razor, or .NET usercontrols.

When SendEmail is called you specify an orderNumber parameter, which will be passed to the template via a querystring paremter called "orderId". From this point on you can retrieve the order via the .NET API or an XSLT extension and render the mail.

This way you don't have to pass in information to the e-mail other than the reference (orderid, customerid, memberid whatever is relevant to the e-mail) and you keep the e-mail content separate from the service sending the e-mail.

I do agree that uCommerce needs to be able to handle custom subjects and multiple CC/BCC. This is in the dev pipeline (excuse the pun) :)

Søren Spelling Lund

Friday, April 08, 2011 4:04:10 PM (GMT Daylight Time, UTC+01:00)

Hi Søren,

Thanks, as this is something we've discussed offline already I thought I'd ensure everyone is up-to-date.

You're right, that's a fine way of doing it assuming that the end user of UCommerce is technically competent however as many aren’t –but still want to be able to write things such as “Dear FirstName”, doing this in the XSLT is not sufficient.

When configuring the emails in our sites, we allow the users to enter a header/footer message on each of the emails, it’s this bit that we want them to be able to customise, not the order information aspect of it.

The other limitation with your EmailService is that it only caters for orderNumber as the parameter which means you can’t for instance pass in a username and password and send the customer a personalised “welcome to the future of internet sales” email. This just makes it more flexible :)

If I recall correctly though, you’ve sorted the multiple recipients stuff for v2 haven’t you?

Tim

Tim

Wednesday, April 13, 2011 8:06:00 AM (GMT Daylight Time, UTC+01:00)

You can let people edit header and footer using the OOTB setup. Basically you'd you'd add those fields to the doc type supporting the e-mail and let store manager edit that as they would any other content. Of course it would be the same for each e-mail, but I'm assuming that's what you're after :)

You can actually pass in multiple params other than order number if you use the form "WEB-122&customerId=123&firstName=Tim". A bit hacky but it will work so we might formalize that with a dictionary type thing as you've done here :)

As for dynamic subjects and multiple CC and BCC recipient that's in 1.5.1.

Søren Spelling Lund