Sending Emails in SAP Hybris

1. Overview

In this article, I will show how to create, configure and send emails in SAP Hybris.

An email in Hybris consists of at least 3 different components :

• Email Template and Email Page.
• Email Process.
• Email Context.

In order to explore all of them we are going to create a simple example, a Hello World Email.

This is a simplified version of how we are going to setup our Hello World Email.

2. Implementation

2.1. Business Process

1. Create an Item type that extends StoreFrontCustomerProcess or StoreFrontProcess, call it HelloWorldEmailProcess.

<itemtype code="HelloWorldEmailProcess" extends="StoreFrontCustomerProcess" 
	jaloclass="com.stackextend.training.core.jalo.process.HelloWorldEmailProcess">

	<attributes>

		<attribute qualifier="firstName" type="java.lang.String">
			<persistence type="property" />
		</attribute>
		
	</attributes>

</itemtype>

2. Create a new xml file, call it helloWorldEmailProcess.xml, it’s  where we are going to define the steps to be executed by the Process Engine.

<!-- .../trainingcore/processes/helloWorldEmailProcess.xml -->

<?xml version="1.0" encoding="utf-8"?>
<process xmlns="http://www.hybris.de/xsd/processdefinition" 
	start="generateHelloWorldEmail" 
	name="helloWorldEmailProcess"
	processClass="com.stackextend.core.model.process.HelloWorldEmailProcessModel" 
	onError="error">

	<action id="generateHelloWorldEmail" bean="generateHelloWorldEmail">
		<transition name="OK" to="sendEmail"/>
		<transition name="NOK" to="error"/>
	</action>

	<action id="sendEmail" bean="sendEmail">
		<transition name="OK" to="removeSentEmail"/>
		<transition name="NOK" to="failed"/>
	</action>

	<action id="removeSentEmail" bean="removeSentEmail">
		<transition name="OK" to="success"/>
		<transition name="NOK" to="error"/>
	</action>
	
	<end id="error" state="ERROR">Something went wrong.</end>
	<end id="failed" state="FAILED">Could not send HelloWorld email.</end>
	<end id="success" state="SUCCEEDED">Sent HelloWorld email.</end>

</process>

3. Register the generateHelloWorldEmail as a bean in Spring :

<bean id="generateHelloWorldEmail" parent="abstractGenerateEmailAction">
	<property name="frontendTemplateName" value="HelloWorldEmailTemplate"/>
</bean>

Note that sendEmail and removeSentEmail beans are already registered in Spring.

4. Register your process as a ProcessDefinitionResource into Spring, to be recognized by Hybris Process Engine.

<bean id="helloWorldEmailProcessDefinitionResource" 
	class="de.hybris.platform.processengine.definition.ProcessDefinitionResource" >
	
	<property name="resource" value="classpath:/traingingcore/processes/helloWorldEmailProcess.xml"/>
	
</bean>

5. Create a new Java class that extends CustomerEmailContext or AbstractEmailContext, call it HelloWorldEmailContext.

An EmailContext is the one that holds the data to be passed to the email template, in our case we will passe to the template a single attribute called firstName.

public class HelloWorldEmailContext extends CustomerEmailContext
{
	private String firstName;

	@Override
	public void init(final StoreFrontCustomerProcessModel processModel, final EmailPageModel emailPageModel)
	{
		super.init(processModel, emailPageModel);
		if (processModel instanceof HelloWorldEmailProcessModel)
		{
			setFirstName(((HelloWorldEmailProcessModel) processModel).getFirstName());
		}
	}

	public String getFirstName() {
		return firstName;
	}

	public void setFirstName(String firstName) {
		this.firstName = firstName;
	}
}

6. Register the HelloWorldEmailContext as a bean in Spring.

<bean id="helloWorldEmailContext" 
	class="com.stackextend.training.facades.process.email.context.HelloWorldEmailContext" 
	parent="customerEmailContext" 
	scope="prototype" >
	
</bean>

2.2. Email Template

The concept of Emails Template in Hybris is similar to Pages Template of the WCMS module, refer to this article for more details.

1. Create 2 Velocity templates, one for the email Subject and the other for the Body.

<%-- .../trainingcore/import/emails/email-helloworld-subject.vm --%>

${ctx.messages.emailSubject}

<%-- .../trainingcore/import/emails/email-helloworld-body.vm --%>

<html>
    <head>
    </head>

    <body bgcolor="#ffffff">

        <h1>Hello ${ctx.firstName}</h1>

        <p>This is a Hello World Email from Hybris</p>

    </body>
</html>

2. The following impex allows you to create RendererTemplates for the Subject and the Body, and attach them to an EmailPageTemplate.

# Content Catalog Version
$contentCV=...

# Path to the Velocity Templates
$emailResource=...

# Package of the Context class
$emailPackageName=...

# Create Template Renderers
INSERT_UPDATE RendererTemplate	;code[unique=true]			;contextClass								;templateScript[lang=en,translator=de.hybris.platform.commerceservices.impex.impl.FileLoaderValueTranslator];rendererType(code)[default='velocity']
								;email-helloworld-body		;$emailPackageName.HelloWorldEmailContext	;$emailResource/email-helloworld-body.vm
								;email-helloworld-subject	;$emailPackageName.HelloWorldEmailContext	;$emailResource/email-helloworld-subject.vm

# Create Email page Template
INSERT_UPDATE EmailPageTemplate	;$contentCV[unique=true];uid[unique=true]		;active	;frontendTemplateName	;subject(code)							;htmlTemplate(code)		;restrictedPageTypes(code)
								;						;HelloWorldEmailTemplate;true	;helloWorldEmail		;email-helloworld-subject				;email-helloworld-body	;EmailPage
			
# Create Email Page			
INSERT_UPDATE EmailPage	;$contentCV[unique=true];uid[unique=true]	;masterTemplate(uid,$contentCV);approvalStatus(code)[default='approved']
						;						;HelloWorldEmail	;HelloWorldEmailTemplate;

2.3. Email Config

Before sending the email make sure to add these properties to your local.properties.

emailservice.send.enabled = true
mail.from = [email protected]
mail.replyto = [email protected]
mail.smtp.server = smtp.gmail.com
mail.smtp.port = 465
mail.smtp.user = [email protected]
mail.smtp.password = password

2.4. Sending Email

Sending a Hello World Email means starting a new instance of the Hello World Process.

// Create a new instance of the process
HelloWorldProcessModel helloWorldProcessModel = (HelloWorldProcessModel) getBusinessProcessService()
	.createProcess("helloWorld-" + System.currentTimeMillis(), "helloWorldEmailProcess");
	
// Fill the process with the appropriate data	
helloWorldProcessModel.setSite(...);
helloWorldProcessModel.setCustomer(...);
helloWorldProcessModel.setLanguage(...);
helloWorldProcessModel.setCurrency(...);
helloWorldProcessModel.setStore(...);

helloWorldProcessModel.setFirstName("Mouad");

// Save the process
getModelService().save(helloWorldProcessModel);

// Then start the process = send the Email
getBusinessProcessService().startProcess(helloWorldProcessModel);

The code snippet above requires modelService and emailService to be injected (Autowired).

3. Conclusion

Creating emails in Hybris is quite tricky because you have to go for a bunch of components, however this separation of responsibilities (process, context, template,…) comes with many more benefits especially for debugging and maintaining.