Introduction

Many years ago (more than I care to count), I was in a role where I managed blended learning programs.  This would include sending out calendar invites to all the participants I was expecting to attend.   In my somewhat bias opinion, they were well written and communicated the necessary information.  Nothing fancy, but easy to read and to the point.  On average, there were 75 people on the “required” list, and maybe 40 or so would show up.  I would then be left to reach out to the absentees, find out why they didn’t attend, and develop a plan to catch up.

One day, I decided to dress the invites up a little by adding a banner image across the top.  The image was of a conference room table and some chairs, one of which was pulled out from the table, turned towards the viewer.  It had a caption … “We’ve saved a seat for you!”.

An interesting thing happened.  Upon sending out this newly dressed up invite, I immediately started getting responses.

“Thank you for saving me a seat, but I have a conflict today, when can I make this up?”

“Thank you for thinking of me, I’ll be OOO that day.”

“Unfortunately, I’ll be on Jury Duty next week”.

Seldom would people proactively tell me that they were unable to attend a class.  Having advance notice meant I could better set the instructors expectation on the number of attendees and certainly saved me a lot of time in follow up work, and was greatly appreciated.  Clearly, the decision to dress up my calendar invites prompted a different (and positive) behavior in our learners.

In this blog, I’ll describe at a high level, how to modify the VCAL entry to support HTML in SuccessFactors LMS. This will allow you to dress up your calendar invites, and hopefully have the same positive experience I did.

Getting down to the details

How do I know what notification to use, if it has options for a VCAL, and what Tokens I can use?

The first stop is SAPs Help Portal.  Specifically the “Template ID to Trigger to Receiver Map” found here.  I’ve always found this a helpful tool to determine what templates there are, when they are triggered, and who gets them.

Once you’ve identified the template you think you’d like to use, you can check if it has a VCAL option by looking the template up under System Administration » Manage Email » Email Notification Templates.  When you’ve opened the template, check the Messages tab.  If there is a Message ID labelled “VCAL”, you’ve got yourself a winner !

NOTE:  We will not be using the WYSIWYG editor in these instructions.  The code we are looking at, and will be setting, is in the VCAL Message field, as seen below.

VCAL Message ID

What syntax Tags are supported?

For a complete list of Syntax Tags that are supported in notifications, first check

System Administration » Manage Email » Email Notification Templates

Search for (and view) the notification that has the VCAL you are modifying.  On the Summary tab, there is a Token Set ID.

For example, the SystemEnrollmentNotification templates, uses the ENROLLMENT token set.

Now that you have the Token set ID, lets take a look at what tokens are available.

System Administration » Manage Email » Email Notification Token Sets

There is a limited amount of Tokens sets, so there is no Search Selector for them.  You may need to expand your list to show all, or page through until you find ENROLLMENT.   View the token set to get a complete list of available tokens.

The Defaults

Lets take a look at the default configuration.

BEGIN:VCALENDAR
METHOD:REQUEST
<LOOP>
BEGIN:VEVENT
UID:<ESCAPEFORVCAL value="<&VCAL_UID>"/>
SEQUENCE:<ESCAPEFORVCAL value="<&VCAL_SEQUENCE>"/>
ORGANIZER:<ESCAPEFORVCAL value="<&VCAL_ORG>"/>
SUMMARY:<ESCAPEFORVCAL value="<&VCAL_SUM>"/>
LOCATION:<&VCAL_LOCN>
DESCRIPTION:<ESCAPEFORVCAL value="<&VCAL_DESC>"/>
DTSTART:<&VCAL_DTSTART>
DTEND:<&VCAL_DTEND>
BEGIN:VALARM
TRIGGER:PT15M
ACTION:DISPLAY
END:VALARM
END:VEVENT
</LOOP>
END:VCALENDAR

This code generates a calendar invite that looks something like this:

Default Calendar Invite

Fairly plain and straight forward. What if I told you, this was possible?

Calendar Invite Generated by LMS

I won’t go through all the line by line code necessary to generate this (that’s not the point of the blog), but I’ll tell you what settings you need to add/change to support adding your own custom HTML.

The Magic you’ve been waiting for

Supporting HTML in the body of the calendar invite requires only two additional lines of code to the VCAL Message.

1. VERSION: 2.0
   Add this line immediately under the first, as seen below.  That’s all there is to the first part. Nothing additional to add to this line.
2. X-ALT-DESC;FMTTYPE=text/html:
   This line can be added anywhere after the first LOOP and before the closing </LOOP> tags.  However, I find adding it before/after to the plain text “Description” field to be a good practice.  Anything after the colon will be processed as HTML.  So start with your opening <html> tag, and start writing your HTML here.  Then, as good practice dictates, close your html with </html>.  You have full access to all the HTML in between, except things like Javascript and linking to External CSS.  Generally, these are unacceptable to most email servers, security, etc.  Certainly, this does not prevent you from creating great emails and calendar invites.  You’ll see in the Tips section, I recommend using in-line CSS for exactly this reason.

HTML code (tables, color, inline css, etc) will not work in the text DESCRIPTION field. The X-ALT-DESC parameter provides a method to add HTML to an event description. Although considered experimental, this field has become the method of choice when including HTML in a description. When using HTML, both fields must be included so that iCalendar readers that do not support the X-ALT-DESC field can still read the text version.

BEGIN:VCALENDAR
VERSION:2.0
METHOD:REQUEST
<LOOP>
BEGIN:VEVENT
UID:<ESCAPEFORVCAL value="<&VCAL_UID>"/>
SEQUENCE:<ESCAPEFORVCAL value="<&VCAL_SEQUENCE>"/>
ORGANIZER:<ESCAPEFORVCAL value="<&VCAL_ORG>"/>
SUMMARY:<ESCAPEFORVCAL value="<&VCAL_SUM>"/>
LOCATION:<&VCAL_LOCN>
X-ALT-DESC;FMTTYPE=text/html:<html><body> ... <h1>This is a header</h1><br/>This is a label in italics:<i>   <label key="notification.Enrollment.MessageText5"/></i><br/>And the SChedule Component tag in bold:<b> <&SCHD-CPNT></b></body></html>
DESCRIPTION:Hello <&STUD-FIRST> <&STUD-LAST>, \n\n You have successfully '<&STUD-ENRL-STATUS>' in this class. You can still put some better verbiage here .. and use \n to indicate a new line.
DTSTART:<&VCAL_DTSTART>
DTEND:<&VCAL_DTEND>
BEGIN:VALARM
TRIGGER:PT15M
ACTION:DISPLAY
END:VALARM
END:VEVENT
</LOOP>
END:VCALENDAR

If you’d like to clean up the plain text version of your calendar invite, then you can certainly do that as well.  You can add syntax tags above and beyond what is there by default, using \n for a new line.  I’ve included a simple example of this in the code box above.

Tips

Before I send you off writing your HTML, I wanted to share a few tips I learned while developing the same invite you saw above.

1. I have found the best way to identify what data comes in what syntax tags, the first thing I did was to put ALL the tags into the body of the email and/or VCAL, then trigger the email.  Then I would know which ones I wanted to use, based on the return value.
2. While it is technically allowable to have your HTML code span multiple lines in your VCAL, I would not recommend this.  There are specific requirements on each line to support this, and its very easy to miss one.  Yes, this will result in a VERY long single line of HTML, but still valid.  Don’t worry, your email client will be able to read this just fine.
3. use inline CSS. This is a good practice not just for VCALs but also when modifying all emails.
4. Store images publicly (not behind something requiring authentication, and reference them using the <img> tag.  There is an alternative method using base64 encoding, however, as I have yet to test that, I’ll save it for another blog.
5. Syntax Tags that might contains multi-line values (meaning could have a hard return in them), like <SCHED_INSTRUCTIONS>, will need to be escaped.
   ie:  <ESCAPEFORVCAL value=”<SCHED_INSTRUCTIONS>”/>

Summary

In summary, we looked at

• Where / How  to find templates
• where to find the tokens that are supported for a given template
• what the default code looks like
• the two lines you need to add to support HTML in your VCAL.
• Tips & Tricks to avoid headaches when you get started.