Document Properties
Kbid2C8332
Last Modified22-Jun-2020
Added to KB30-Jun-2017
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
ProductIOM 2.2

Concept - IOM Customer E-mails 2.2

1 Introduction

Intershop Order Management (IOM) has the ability to send e-mails to customers of a shop at various times, e.g., on order creation or the dispatch or return of products. This document describes the basic concepts of how to manage customer e-mails within the IOM. The target audience are partners, consultants and developers of Intershop.

1.1 Glossary

TermDescription
Communication partnerA relation from IOM to an external 3rd-party system with which a defined communication exists. E.g., a shop, supplier or payment provider.
Also named partner in this document.
IOM Business Process Configuration Framework

A framework to extend or modify the default business processes of IOM.

IOM Event Framework

A framework to extend or modify the default business processes of IOM based on events.

IOMThe abbreviation for Intershop Order Management
TransmissionAn internal object of IOM that represents the requests and content for an external communication.

1.2 References

2 Sending E-mails to Customers

E-mails today are indispensable in contact with customers. In the context of e-commerce e-mails enable business owners and systems to interact automatically with customers and deliver information which inform about process statuses, are legally relevant and more. Depending on the requirements of the business owner e-mails are sent at various times within a business process. Also design and branding are defined by the business owner. This leads to the need of a high flexibility of customer e-mails features of the IOM.

The following diagram is showing 4 selected use cases in which an e-mail could be the part of an actors action.

IOM Customer Emails - Overview

3 Preconditions

The IOM requires an existing mail server that processes internal and external emails sent from IOM via the SMTP protocol. Please see Guide - Setup Intershop Order Management 2.2 for more information.

4 Processes

4.1 Overview

IOM has the ability to send e-mails to customers of a shop at various times, e.g., on order creation or the dispatch or return of products and more. Therefore several configurations are required to fulfill the requirements of the business owner like domain, time to send, custom preconditions or design.

The following sections will explain the major concepts and how they are used to send e-mails to customers of a shop.

4.2 Business Process Customization

The sending of e-mails to customers is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that is using the e-mail sending process. Using the IOM Business Process Configuration Framework and the IOM Event Framework it is possible to configure the time at which business process and process task which e-mails should be send to customers. Also the shop, supplier and type of e-mail can be configured. For business processes where the sending of a customer e-mail can be useful see Processes for E-mail Events.

The following model is showing the standard Order Business Process of IOM which controls the complete order capture, validation, approval, routing and submission of an order to the selected fulfillment location. Exemplary several points of customization of the business process are marked which are showing the additional sending of an e-mail after a process task. I.e., an e-mail to confirm an order can be send after the process Order Capture & Validation or after a fulfillment location was assigned (Order Reservation Process). The process of sending e-mail notifications is provided by the IOM and can be used as seen in the diagram.

Business Process Customization

This exemplary customization can be configured in any other business process of the IOM too. Please see Cookbook - IOM Customer E-Mails 2.2 for an exemplary configuration.

OMS BP - 01 - Order Business Process

4.3 Process Sending E-mail Notifications

The following diagram is showing the major tasks of the process that is sending e-mail notifications to customers. It consists essentially of three steps:

  1. If configured for a partner relation to send e-mails a transmission object will be created.
  2. The method of the transmission will be determined.
  3. If transmission method is PUSH the transmission will be rendered and send to the customer. For rendering configured templates will be used.
    Other methods will not end in a rendering and sending at this time.

Transmission

A transmission represents the requests and content for an external communication. Here an e-mail is represented by an instance of ShopCustomerMailTransmissionDO.


OMS BP - Send E-mail Notification Process


5 E-mail Templates

E-mail templates are used to visually design the message content of e-mails. Templates consists of the two major components design and content information. Design is used to give e-mails a pleasant view. This includes a header, a body and a footer section, to list products and prices in tables or to visualize information of order status and more. Design will be described, e.g., on a basic HTML-level using HTML and CSS. The content information itself like order number, customer addresses or total sales prices representing the major information. Content information will be inserted into templates using variables. Both, design and content information, are mixed within the templates and transformed to the final e-mail text by a template engine.

IOM is using the Java-based template engine of The Apache Velocity Project / Velocity Engine 1.7.

5.1 Initial Templates

The IOM comes with an initial set of e-mail templates that can be used as a blueprint for customization. The initial templates are part of a deployment artifact. See bakery.base-app-2.X.X.X.ear\bakery.transform-transform-core-2.X.X.X.jar\deploy\vm\default\*.vm to inspect the templates.

The following table lists all initial templates. For each e-mail a template for subject and a template for the message content is required.

Exemplary Business EventUsed Template
SubjectMessage Content
A credit note was created.creditNoteSubject.vmcreditNoteMessage.vm
An order has been shipped.dispatchSubject.vmdispatchMessage.vm
A download for a non-physical item is available. immaterialDispatchSubject.vmimmaterialDispatchMessage.vm
The invoice for an order was created.invoiceSubject.vminvoiceMessage.vm
An order has been received initially.orderSubject.vmorderMessage.vm
Reminder of an open payment.paymentReminderSubject.vmpaymentReminderMessage.vm
Confirmation of an order after a successfull assignment of a supplier.responseSubject.vmresponseMessage.vm
An order was canceled by the customer because.returnSubject_can_rcl.vmreturnMessage_can_rcl.vm
An order was canceled by the shop because items are not deliverable.returnSubject_rcl020mail.vmreturnMessage_rcl020mail.vm
A return from the customer has been received.returnSubject_ret_def_inv.vmreturnMessage_ret_def_inv.vm

For a list of variables which can be used as content information by default see Reference - IOM Customer E-mails 2.2.

5.2 Custom Templates

Custom templates are hosted in the folder $OMS_HOME\velocity\ of the back-end server. Here a customized version of the blueprint templates or any other e-mail template is hosted.

Also see Guide - Setup Intershop Order Management 2.2 for $OMS_HOME.

5.3 Register Templates

Deprecated from 2.5.0.0


Before using templates the template files must be registered initially in the database. Therefore call the URI http://<host>:<port>/control/InitializeDocumentLayouts of a running back-end server. The call will register all new locations of template files - initial and custom ones. The templates then can be referenced in configurations. Alternatively a redeploy of the artifact bakery.control can be used.

Template update
Because the templates are stored in the database too an update of a template file requires to run the registry again. The content of the template will be updated then in the database and can be used.

5.4 Template Data

To print content information into the templates a predefined object UserMailLO is available. UserMailLO offers a large set of information depending on the type of e-mail that should be send, e.g., invoice information in case of an invoice mail or dispatch information in case of a dispatch e-mail. Please see Reference - IOM Customer E-mails 2.2 section General available Template Data for more information.

6 Configuration of E-mail Sending

6.1 Basic Steps

The sending of e-mails to customers is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that is using the e-mail sending process. The following list is showing the major steps of how to configure processes and properties to enable a customized sending of customer e-mails. The attached diagram is an excerpt of database entities which is showing the relations of the configurations. Also see Cookbook - IOM Customer E-Mails 2.2 for a detailed guide including selected solutions and Customer E-mails (Guide - IOM Shop Onboarding 2.2).

  1. In the Event Registry Configuration define a listener that will act each time the business process event occurs. The event listener has to be of type MailEventManagerBean (MAIL_EVENT_MANAGER_BEAN), which will listen especially for e-mail events only.
  2. The MailEvent Registry Configuration defines which type of e-mail should be send and which decision bean should be executed, i.e., a dispatch e-mail when a dispatch has been processed.
  3. In the Mail Transmission Configuration define a set of parameters that are used within the e-mail creation. This includes the sender's email address, the sender's name as well as the template names for subject, email content and more. The registered Mail Template Locations will be referenced here for the selected type of e-mail, i.e., dispatchSubject.vm and dispatchMessage.vm for the processed dispatch. This configuration has to be linked to a Communication Partner exclusively, a shop for example.

6.2 Database Relations

The following diagram is an excerpt of database entities which shows the relations of the configurations which are used to enable the sending of e-mails. See Configuration of E-mail Sending for more details about configuration. Also see Reference - IOM Database Documentation.

Customer Email Configuration - ERM

7 Further Notes

7.1 Decision Beans

A decision bean is a filter that reflects whether an action should be processes or not. The major parameter is a business object like an order, a dispatch or a return. The methods of the bean can check simple facts like existing e-mail addresses but also complex facts. A default decision bean - SendEmailDeciderBean - is available. For implementing a custom decision bean please see Cookbook - IOM Customer E-Mails 2.2.

7.2 Execution Bean Keys

The final sending requires a configuration that maps sender e-mail address, templates and more key parameters to a communication partner. Please see Execution Bean Keys (Reference - IOM Customer E-mails) and Cookbook - IOM Customer E-Mails 2.2 for more information.

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets