Progress Report: Installation of EXM in Sitecore 8 - Part 2

In the first part of this progress report about the Installation of the E-mail Experience Manager (short: EXM) in Sitecore 8 we discussed the initial obstacles that have to be overcome. If you do not want to read the whole post, we will give away this much: It did not work.

In this second part we will discuss the „Why“. And just like the first one, this post is not an instruction but a progress report in real-time. Which means, every step of our way to the solution will (hopefully!) be accordingly documented. Thus dead-ends will have to be exited backwards. That’s just how it is in the reality of IT.

Sitecore Packages

To better understand on which level of an installation things can go wrong it is helpful to look more closely at the structure of a sitecore package.

To begin with, sitecore packages aren’t witchcraft but compressed archives in a zip-format, and thus are easy to open. You can locate files that were uploaded with the sitecore package managers in the folder ‘Data/packages’ of the respective sitecore authority. When you unzip a package it contains an additional archive called ‚paket.zip‘. So far very reasonable.

Upon unzipping this folder you will see the basic structure of a sitecore package:

Graphic 1: Structure of a sitecore package

Especially the subfolders ‘files‘ and ‘items‘ are relevant. In the directory ‚files‘ are, as expected, all files of the module that are copied into the website directory during the installation. Therefore it is a possible cause of error that the user (normally the network service), under which the IIS is running, does not have writing authorizations in all areas. So if anything goes wrong while copying the files, you should review this issue.

The other important area is ‚items‘. Here are all serialized data base entries located. The folder structure complies exactly with the one of the sitecore content trees. This partially explains the very slow speed during installation: Each entry has to get de-serialized, converted into a SQL statement and completed. Little can go wrong during this step: If entries are already existing, you will be asked during the installation via dialog box whether the entry should be kept or overwritten.

So, based on the elements in a package you can review the completeness of an installation. A complete directory delivers the file ‚project‘ into the folder ‚installer‘. This is a XML file, which is created during set up of a package in the package manager.

Since there is no automated mechanism for the de-installation of a package this is the only indicator for a manual removal of all components in a module. 

Cause Study

The first attempt to install the EXM module ended with this window:

Graphic 2: Installation progress... unfortunately none.

This ‚Dialog‘ then stayed visible for several hours. I am patient and know from experience that the installation, even of supposedly small packages, takes longer than a complete backup of the whole data base. But at some point it’s enough.

So I stopped the installation process to find out what was causing the problem. Since all this had taken place a few days ago, I have to re-call the whole scenario in my head by re-reading the first part. Good thing I wrote things down.

Since I am working in a virtual Hyper-V-Environment it is not a problem to go back to the original state of the system, as I had created an according checkpoint prior to starting the installation of the module. But before I do this, I want to see which traces the failed installation has left. Maybe those will already give a hint to the root of the problem. 

EXM Data Base

So first, I check with the SQL-Management-Console if the EXM data base already exists. Negative. So the problem must have had occurred earlier during the installation.

Graphic 3: No EXM data base in the SQL Management Console

Sitecore Tree

The next place to check is the Sitecore CMS Surface, to see if entries have already been written into the Sitecore data base in connection with EXM. For this purpose there are defined locations in the Sitecore Content Tree, in which modules can deposit their data.

In the master data base this is 'sitecore/System/Modules':

Graphic 4: 'Modules' folder in the Sitecore Content Tree

And lo and behold, the installation did indeed leave traces and did not fail completely. In my ‚modules‘ folder I can find a subfolder for EXM. And there it is again, this sitecore-smirk. The folder is called ‚E-mail Campaign Manager‘, which is the old name of the module. Additionally you can already find two different spellings for E-Mail (which is, according to the dictionary, the correct German spelling) on the small screenshot. Even though the module’s language is English and research of the topic „correct spelling email english“ (Google doesn’t need capitalization) shows that even the big shots (Apple, Microsoft, Adobe, etc.) are struggling in this area and use inconsistent spelling. Even within the same company there is, for instance, the spelling ‚email‘ or ‚e-mail‘ – but two different versions of one and the same word within one form? What kind of quality control let this slip?

In this context, as a German client, I remember an installation of the then known ‚E-Mail Campaign Manager‘ module. Here, the administrator had used German as the Sitecore CMS Surface language. But for inexplicable reasons the ECM surface always appeared in English. So the language parameters must not have been passed on correctly from content management to the e-mail module. The information concerning which language should be used, is initially transmitted into Sitecore as an URL parameter and is then saved in a cookie in the client’s browser. This can lead to persistent confusion concerning the used language, which can often only be fixed by deleting the cookie. While in the present case a parameter for the language has been delivered, after consultation with the Sitecore support it turns out that it was the wrong one. That was irritating.

After some doctoring around, the appropriate language was delivered correctly to the ECM module. With the result, that the surface was no longer usable since buttons had disappeared and drop-down menus were empty. The appropriate translations were simply missing. Not that all the words were missing, but the translation was just incomplete.  

So far my excursion to the topic of quality control, but now back to the actual task: How can I get the module to run?

On my search for traces I can also find relevant entries in the core data base, which originated from the EXM installation. 

Graphic 5: Applications in the core data base

In the directory ‚Application‘, available applications are installed, including the ones that belong to Sitecore. For those to be available from the surface, such as the home menu, corresponding entries elsewhere are required. The way to get there is long and in the end, in this concrete case, you will end up at '/sitecore/content/Documents and settings/All users/Start menu/Programs/Email Campaign/Email Campaign Manager'. So there really was a menu item added in the home menu under applications, which I could use to start the Email Campaign Manager, or rather the Email Experience Manager.

Graphic 6: EXM in the home menu

Due to the fact that the old name of the module is still in use everywhere, you can see how thin the Sitecore marketing surface is and how little this regular re-branding really affects the system. Just as a reminder: The EXM module is developed and made available by Sitecore itself, and is not really a niche product.

For the cause study regarding the failed installation this means that at least part of the package could be installed successfully.

So far, so good.

File System

Another level that is affected by the installation of a module, and therefore things can go wrong with as well, is the file system. That is why I am checking if the files contained in the package have been copied. I already found out which ones those should be when unzipping the module. During this process it also appears, that the new files exist. So what the hell went wrong?

It begins to dawn on me that I can eliminate one cause of error completely, and that is the installation of the EXM data base. The reason for this is simple: There is no EXM data base! 

Courage of Desperation?

So there is only one consequence left: I have to push the button to start the Email Experience Manager and see what happens (again: EXM vs. ECM).

Graphic 7: Start button for EXM in the launch pad

Graphic 8: The Sitecore EXM module in action

And my courage is rewarded. Lo and behold, the Email Experience Manager launches.

Only one question remains unanswered: Why did I think that something had gone wrong only because the installation dialog did not end with the words‚ ‚Congratulations! You are now the proud owner of an EXM installation!‘? Perhaps I will have to lower my demands in the future. Talking about future: In another part we will discuss, if the module functions properly and how to work with it.

Conclusion

Orderly and structured troubleshooting is an important instrument when analyzing problems. Here it is helpful to isolate the areas in which things can go wrong and to examine them separately while always questioning your own assumptions.

And sometimes you should just push the button to see what happens.