How do we migrate from Mail Scripts to Message Templates?

Environment:

Mail Scripts, Message Templates

Resolution:

Message Templates provide an easy, flexible way to customize your outgoing Service emails and notifications, as well as personalize the Service messages for your Oracle B2C Service instance. Message Templates also offer patent-pending tracking capabilities, so that you can report on the actions for incident-related responses, such as views and clicks back to Customer Portal. This feature replaces the deprecated Mail Scripts capability, so migration is required before removal of Mail Scripts occurs at a future date.

If you started using the product on/after November 2012 release, Message Templates is enabled by default. Upgrading from releases prior to this version will require migration and a sample list of migration steps is included below. Migration can occur at any point, and should be decoupled from any update. This migration is also one of the keys to entry for the Auto Update Program. If you have not customized your Mail Scripts, this migration should be simple and you are encouraged to try the default templates before making changes that were in play from the legacy configuration. Additionally, you may configure your Message Templates prior to enabling this feature, and convert one interface at a time if preferred. In this way, the messages can be set and reviewed before you send them to customers.

There is a default Message Template already created for every message that was available in Mail Scripts, and new Message Templates have been added to provide more flexibility in your site configuration. This also makes it easier to understand the full list of the messages or notifications that are in use. Unlike Mail Scripts, the Message Templates do not rely on duplicated Message Bases or shared PHP files. Now you configure each message uniquely, adding any text or merge fields to one message at a time.

Suggested Migration Steps

The Update Guide includes steps for migrating to Message Templates (see Notifications and email messages under Common update enhancements).

Reminder: You can first edit, preview/proof, and deploy these new messages prior to enabling them for customers!

In addition to this resource, here are a few additional suggestions for your migration.

1. Add Message Templates permission to your Profile. This permission is within the Administration tab of the Profile Permissions.
2. Add Message Templates to your navigation set (see Customizing notifications and email messages sent by Oracle B2C Service).
3. Open the Message Templates editor to view the list of default messages available. Select an interface from the left navigation, and use the ribbon buttons for Admin Notifications, Admin Emails, Contact Emails, and Print Templates* to see all messages. Start by reviewing the Contact Emails, followed by Print Templates, and then forward messages within Admin Emails - those are typically the most frequently used in the product.
4. View Send and HTML settings for your previous Mail Scripts messages by accessing Site Configuration > Interfaces, and using the ribbon buttons of Admin Notifications, Admin Emails, Contact Emails.
   1. Note which values are unchecked under the Send column. Those messages are not being sent when Mail Scripts are in use. Consider carefully if the same should apply as you move to Message Templates, and if so, uncheck the same Send checkbox(es) in the Message Templates editor, then Save.
   2. Complete the same for the HTML column. If HTML is not selected, then only the Text version of the message is sent. Because of the style changes already applied to the default templates, and the ability to easily re-style the messages to meet your needs, you might consider keeping HTML selected for all Message Templates. If an HTML message cannot be viewed by a receiving email client, the Text version will be shown.
5. Update your Global Template, if desired, with your company logo or any relevant links or other company information. The Global Template is interface-specific, and is essentially a wrapper for your outgoing messages, giving them a consistent style and content. Don't forget to Save and use Deploy Template and Save using the ribbon buttons. If preferred, you can turn off the Global Template on a per-message basis. To view the source of your Mail Scripts message wrapper, please access Site Configuration > File Manager > mail files > cci, and locate the header and footer files - the source differs for HTML and Text, so be sure to view both, as well as the differences between interfaces.
6. Check the following config settings and make sure you update the applicable incident messages in Message Templates if needed:
   • MAIL_DETAILS_ENABLED: This config controls whether or not general incident information is available in your outgoing service message when Mail Scripts were in use. The details included in the default Message Templates are minimal and simple. You can further configure the email experience for your business using Merge Fields or Conditional or Case sections with Merge Fields included. The goal is to only show the customers what they absolutely need to see in the email response. Keep it simple, but add relevant fields as needed.
   • MAIL_SUPPRESS_NULL_CUST_FLDS: This config suppresses null value custom fields from the Mail Scripts. Similar to above, define what is critical for your customers to receive in their email, and add Merge Fields (standard or custom) in order to give them the correct information. If no Default value is listed for a Merge Field, and the value of the field is null (blank), then this field is not shown in the message. Alternately, pairing with Conditional and Case sections provides flexibility to display different fields based on context for each message. For example: Use a conditional section to show the 3 custom fields relating to one special product line that you manage. In this way, these fields are only viewable when they are important.
   • MAIL_INC_THREAD_LEN: This config controls the number of threads to be included in a message sent by Mail Scripts. To change the same value in a Message Template, modify the Incident Thread control properties in the applicable Message Templates to set this value smaller, if desired. By default, this control is used in the Incident messages (Incident Solved/Unresolved/Waiting/Closed, and Rule Email), and can be added to other messages. Change the Limit Threads value in the properties to meet your needs. See Answer ID 5489: Message Templates and MAIL_INC_THREAD_LEN for details. As an added bonus to Message Templates, you can also easily determine WHICH thread types should be included in the outgoing message, and send only those that you specify. Simply check the boxes next to each thread type to include them in your message.
   • MAIL_DEFINED_SUBJECT_ENABLED: This config supports always using one static subject for nearly every incident message sent via Mail Scripts. In Message Templates, starting in November 2013, you can configure your own subject lines for each message in a distinct manner. This provides a much more powerful way to configure your subjects using appropriate merge fields. Further enhancements added in the November 2014 release provide the ability to configure conditional subjects (up to 10 plus a default per message), so that you can change the subjects easily for different cases. For example: A VIP customer gets a personalized subject and response period, while a customer who emails you about an unsupported product gets a subject that says as much, while every other situation gets the standard subject (merge in Incident refno and Subject).
7. There are a number of Message Bases that made up the text in the Mail Scripts messages. Message Templates start with fresh content, so review the messages with fresh eyes to determine if changes are really necessary, according to your current business needs. See the attached file to view the list of Message Bases and their related mail script. You can also do a "KEY" field search on *HTML_MSG and *TXT_MSG to get started. The HTML strings applied when an HTML message was sent, and TXT strings applied to the text version.

As a note, if you have an update in-flight, talk to your Technical Migration Manager about whether or not you have customizations in any of the mail scripts files. These files live in the File Manager > mail files area as read-only in any version on or after November 2012. If no changes exist, proceeding is EASY! :) You need not complete the migration at the same time as your update, but it provides the view you might need to understand if customizations are in play for your Mail Scripts.

Additional Checklist Items

Once you have reviewed your previous setup and applied the suggested changes, add other configuration to the messages to meet your business needs. Be sure to check the following:

1. Save your changes regularly. Changes are not fully committed until the Deploy option is used.
2. Be sure to make frequent use of Preview and Proof capabilities. These allow you to view the messages with live record data, prior to deploying changes.
3. Create the right messages for both HTML and Text versions of each email.
4. Configure messages for all interfaces.
   • NOTE: You can enable Message Templates one interface at a time (see step 6), providing a great way to try the messages to a subset of your customers, in case you have concerns.
5. When the messages are prepared, be sure to deploy, then save your changes. These are not yet live to customers!  There is no harm in deploying during this phase as these aren't in effect until the configuration setting is changed.  The deploy simply promotes your edits into the Live version, which will be used once the config is enabled.
6. Once you have deployed your changes, enable the configuration setting MESSAGE_TEMPLATES_ENABLED. This tells the system to send the Message Templates vs. the Mail Scripts.

   IMPORTANT: Please note, once this functionality is enabled, you are unable to disable the functionality again. Once you enable message templates, the administrator notifications, administrator emails, and contact emails under Site Configuration > Interfaces are disabled, but are still available as read-only, as stated in the online documentation.

7. Enter a value for EGW_DEFAULT_URL in case any links are broken in the future. See Answer 2419: With a Outreach campaign, users go to a blank page after clicking Submit for details.

*Separate Print Templates were added in the November 2013 release. Prior to this release the related Forward message template was also used for Print.