ECM Basics

Hey guys, this will be the first in a series of posts about the Sitecore Email Campaign Manager (or ECM).
Since we live in the year 2014, we will be targeting ECM 2.x, which is built in the new SPEAK-interface.
Building newsletters in SPEAK means having access to the Page Editor’s functionality, which offers a whole bunch of new techniques to connect new (or existing) content items to your newsletters.

We did quite a lot ECM implementations over the last year and are pretty confident in giving statements about do’s and don’ts regarding ECM.
We’ve really reached the limits of this module, and went over them at a few occasions. This resulted in not only a deep understanding of the module, but also a list of bugs (which had to be reported to and fixed by Support) and other misconceptions about it.
The module looks pretty simple at first sight, but that’s an opinion you might reconsider later.

The documentation on SDN looks pretty clear and accurate, but lacks a bunch of information regarding architecture of both the module and it’s network.
Simple example: When choosing the SitecoreMTA model (which actually uses Dyn to send bulk emails) which IP-addresses are used, and therefore should be allowed to have out-going packets in the firewall? Good luck finding that information in the documentation.

Questions like the one above have been the reason of close contact with our local Sitecore department, which have helped us out at a lot of occasions. Not only can they provide technical assistance, they are also able to contact the development and/or support teams to retrieve this information more accurately (and importantly a lot FASTER).

Anyway, enough bureaucratic stuff. Let’s get on with the technical stuff!

My first implementation was almost a complete copy of an implementation one of my coworkers made, but even then I had no idea what was going on nor did the documentation made it any clearer what I had to do.
I’m expecting there are other developers who ran into the same problems, so my first ECM blog will be a basic implementation/installation guide.

After you’ve installed the module you’re pretty much left empty handed.
Start of creating a new Manager Root item at the location you want. I would advise not to place a ECM-node as a descendant of a website, but rather next to it. Maybe even place your ECM-nodes in a separate rootfolder.

manager_root

You will end up with something like this:

ecm_node

Now, make sure the path to the ECM-node (including it’s name) does not contain a hyphen (“-“), to escape from a bunch of bugs regarding Sitecore queries made by SPEAK and ECM which do not automatically escape it (it should be escaped by wrapping the itemname in hashtags “#email-manager#”. A few of these bugs have been fixed in the latest version (rev. 140214), but I’ve been through enough trouble to make assumptions about ECM bugfixes in the past. (better safe than sorry).

So we have this ECM node now. Click on it and enter the following fields:

  • Base URL, this one is very important. It’s the URL ECM uses as a prefix for links to images and internal Sitecore links (in content). Be sure to change it when you’re moving from development to production (or you will end up with broken links everywhere).
  • Common Domain, change it to ‘Emailcampaign’
  • From Name, From Address and Reply To, these are not really important because they will be overridden by the fields set on a message but fill them to have a solid fallback.

If you’re using a localMTA (you take care of the email delivery yourself) make sure to change the fields in the Delivery Status Notifications to allow stuff like Bounce Emails to work correctly.
Since we’re in the development fase we will be using a localMTA, after all you should not use a customer’s license in development.
As a partner you probably have a development license including Sitecore.AnyMTA:

anymta

Open your Sitecore.EmailCampaign.config and change the following key to inform Sitecore you will be using a localMTA.

Change the IP address of your mail-server:

Change other SMTP settings if necessary (login credentials).
Alright, so much for the configuration of ECM (easy right?).
If your solution uses any language other than English for your main sites content (like dutch in my case), you will have to do two things.

1. Make sure the SPEAK language uses that language instead of the default English. This is easily done by changing the ‘defaultLanguage’ to your language-code in the web.config.

Make sure this is working correctly by creating a new version of the /sitecore/system/Modules/SPEAK/Email Campaign item in the desired language and change the Title to something like “EMAIL CAMPAIGN MANAGER (DUTCH)” and publish it.
This title will show up in SPEAK. If not, you’ve done something wrong, and the language is still in English.
ecm_app

2. We made SPEAK open up in our desired language, which raises the next problem: The ECM  SPEAK Application has not been translated to any other language than English.
If you open up ECM you will end up with an application which is missing all kinds of labels and other stuff.

Basically this means you will have to translate every descendant of /sitecore/system/Modules/Speak/Email Campaign. There are a few different solutions to this problem:

  1. Translate manually, which is a LOT of work.
  2. Change the SPEAK templates to make Title fields shared (which is not advisable).
  3. Create a script which creates a new version for your language and copies all the values from the English version. This is what we do, it is both safe and quick and you’ll end up with a filled (although English) SPEAK Application which respects the correct language.

One last thing to finish our configuration/installation guide is to make sure we’re not experiencing another bug/problem in ECM.

Open up ECM and take a look at the context switcher.

context_switcher1

Note: This control is only visible if you have more than 1 ECM Node in your Sitecore solution (if the control is not visible you’re not experiencing this problem).

It is possible that a $name context is showing up in the context switcher.

context_switcher2

If this $name item is visible:
For some reason Sitecore thinks that the Email Campaign Root branch item (called $name) is also a ECM Node and selects it to be shown in the context switcher.

This can be easily fixed by removing the item from the multilist in /Sitecore/system/Modules/E-mail Campaign Manager/System/Root List:

context_switcher3

Wrapping up
So much for the installation and configuration of ECM. This isn’t a typical post we would publish on this website, but in my opinion this basic ECM knowledge is pretty hard to get hold off so I’ve created a step-by-step manual anyway.

The remainder of ECM posts in this series will be more interesting, and more related to programming.

Next up will be: Creating different kinds of newsletters.