Introduction
Intershop Order Management (IOM) has the ability to send emails 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 emails within the IOM. This document is aimed at project developers.
Glossary
| Term | Description |
|---|---|
| Communication partner | A 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 |
| IOM | The abbreviation for Intershop Order Management |
| Transmission | An internal object of IOM that represents the requests and content for an external communication |
References
- Reference - IOM Customer Emails
- Cookbook - IOM Customer Emails
- Guide - IOM Shop Onboarding
- Overview - IOM Shop Onboarding
- Reference - IOM Database Documentation
- Guide - Operate Intershop Order Management 3.X
Sending Emails to Customers
Today, emails are indispensable in contact with customers. In the context of e-commerce, emails enable business owners and systems to interact automatically with customers and provide information about process statuses. Furthermore, emails are legally relevant. Depending on the requirements of the business owner, emails are sent at various times within a business process. Also, design and branding are defined by the business owner. This leads to the need for high flexibility of customer email features of the IOM.
The following diagram shows four selected use cases in which an email could be part of an actor's action.
Preconditions
The IOM requires an existing mail server that processes internal and external emails sent from IOM via the SMTP protocol. Please see Guide - Operate Intershop Order Management 3.X (or later) for more information.
Processes
Overview
IOM has the ability to send emails 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 emails to customers of a shop.
Business Process Customization
The sending of emails to customers is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that uses the email sending process. Using the IOM Business Process Configuration Framework and the IOM Event Framework it is possible to configure the time at which business processes and process tasks send emails to customers. Also, the shop, supplier, and type of email can be configured. For business processes where the sending of a customer email can be useful, see Processes for Email Events.
The following model shows 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. As an example, several points of customization of the business process are marked which show the additional sending of an email after a process task. I.e., an email to confirm an order can be sent after the process Order Capture & Validation or after a fulfillment location was assigned (Order Reservation Process). The process of sending email notifications is provided by the IOM and can be used as seen in the diagram.
Business Process Customization
Process Sending Email Notifications
The following diagram shows the major tasks of the process that sends email notifications to customers. Essentially, it consists of three steps:
- If configured for a partner relation to send emails, a transmission object will be created.
- The method of the transmission will be determined.
- If the transmission method is PUSH, the transmission will be rendered and sent to the customer. For rendering configured templates are used.
Other methods will not end in rendering and sending at this time.
Transmission
A transmission represents the requests and content for external communication. Here an email is represented by an instance of ShopCustomerMailTransmissionDO.
Email Templates
Email templates are used to visually design the message content of emails. Templates consist of the two major components design and content information. Design is used to give emails a pleasant view. This includes a header, a body, and a footer section, to list products and prices in tables or to visualize information on order status and more. Design will be described, e.g., on a basic HTML level using HTML and CSS. The content information itself like the order number, customer addresses, or total sales prices represent the major information. Content information is inserted into templates using variables. Both design and content information, are mixed within the templates and transformed into the final email text by a template engine.
An additional plain text version can be added to the designed HTML. Therefore a separate template can be addressed.
Using a plain text version is optional, but it is recommended to prevent junk-mail classification at several mail clients.
IOM uses the Java-based template engine of The Apache Velocity Project | Velocity Engine.
Template Orchestration
Templates can be organized within a complex folder structure if preferred. For example, different companies/brands can have their own folders. They can be restricted from foreign access.
For example, in the best case, copying a brand's folder will create a new set of templates where just some variables must be changed.
Default Templates
IOM comes with an initial set of customer mail templates that can be used as a blueprint for customization. See var/templates/mails_customers/*.vm to inspect the templates.
The following table lists all initial templates. Each mail requires a template for subject and a template for the message content.
| Exemplary Business Event | Used Template | |
|---|---|---|
| Subject | Message Content | |
| A credit note was created. | creditNoteSubject.vm | creditNoteMessage.vm |
| An order has been shipped. | dispatchSubject.vm | dispatchMessage.vm |
| A download for a non-physical item is available. | immaterialDispatchSubject.vm | immaterialDispatchMessage.vm |
| The invoice for an order was created. | invoiceSubject.vm | invoiceMessage.vm |
| An order has been received initially. | orderSubject.vm | orderMessage.vm |
| Reminder of an open payment. | paymentReminderSubject.vm | paymentReminderMessage.vm |
| Confirmation of an order after a successful assignment of a supplier. | responseSubject.vm | responseMessage.vm |
| Sending of an e-mail on demand that contains a return label. | returnLabelSubject.vm | returnLabelMessage.vm |
| An order was canceled by the customer. | returnSubject_can_rcl.vm | returnMessage_can_rcl.vm |
| An order was canceled by the shop because items are not deliverable. | returnSubject_rcl020mail.vm | returnMessage_rcl020mail.vm |
| A return from the customer has been received. | returnSubject_ret_def_inv.vm | returnMessage_ret_def_inv.vm |
| A return announcement has been created, accepted or rejected. | returnAnnouncementSubject.vm | returnAnnouncementMessage.vm |
For a list of variables that can be used as content information by default see Reference - IOM Customer Emails.
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 email that should be sent, e.g., invoice information in case of an invoice mail or dispatch information in case of a dispatch email. Please see Reference - IOM Customer Emails for more information.
Configuration of Email Sending
Basic Steps
The sending of emails to customers is a process that must be configured. By default, after the initial setup of IOM, there is no configuration that uses the email sending process. The following list shows the major steps of how to configure processes and properties to enable a customized sending of customer emails. The attached diagram is an excerpt of database entities that shows the relations of the configurations. Also, see Cookbook - IOM Customer Emails for a detailed guide including selected solutions and Guide - IOM Shop Onboarding, section Customer Emails.
- In the Event Registry Configuration defines 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 email events only. - The MailEvent Registry Configuration defines which type of email should be sent and which decision bean should be executed, i.e., a dispatch email when a dispatch has been processed.
- In the Mail Transmission Configuration define a set of parameters that are used within the email creation. This includes the sender's email address, the sender's name as well as the template names for the subject, email content, and more. The Mail Template Locations will be referenced here for the selected type of email, i.e.,
dispatchSubject.vm,dispatchMessage.vmanddispatchMessage_plainText.vmfor the processed dispatch. This configuration has to be linked to a Communication Partner exclusively, a shop for example.
If the template is located in a sub-folder it must be configured directly.
Database Relations
The following diagram is an excerpt of database entities that shows the relations of the configurations which are used to enable the sending of e-mails. Also see Configuration of E-mail Sending for more details about configuration and Reference - IOM Database Documentation.
Further Notes
Decision Beans
A decision bean is a filter that reflects whether an action should be processed or not. The major parameter is a business object like an order, a dispatch, or a return. The method(s) of the bean can check simple facts like existing attributes, but also complex facts.
A default decision bean - SendEmailDeciderBean - is available. For implementing a custom decision bean please see Cookbook - IOM Customer Emails.
Execution Bean Keys
The final sending requires a configuration that maps the sender's email address, templates, and more key parameters to a communication partner. Please see Reference - IOM Customer Emails and Cookbook - IOM Customer Emails for more information.