SAP Commerce Cloud Sales Order Integration with SAP Emarsys Customer Engagement using SAP Cloud Platform Integration

February 20, 2024
Sara Sampaio
Technology Updates

In this article we will describe how you can build an integration between SAP Commerce Cloud and SAP Emarsys Customer Engagement in order to bring sales order data into the application. We’ll focus on a particular customer scenario where this has been implemented successfully in the field, and provide a step by step guide that can be followed in order to achieve similar results in your project.

Table of Contents

- Scenario Overview

- Configuration
  - - SAP Commerce ODATA SALES ORDERS
  - - SAP Cloud Integration
  - - iFlow Design

- Conclusion

Scenario Overview

In this scenario, the client is using SAP Commerce Cloud for two commerce sites, one for Canada and another for the United States of America. All sales information is to be made available to be integrated into the SAP Emarsys Customer Engagement within a single account, located in Canada, using Canadian Dollars as the base currency of the application.

To support the end-to-end process integration, we will use SAP Cloud Integration to pull the sales data to be exported from SAP Commerce Cloud into SAP Emarsys Customer Engagement using the Emarsys API.

In this process we must expose the Sales orders using the OData SAP Commerce Cloud capability, and then using SAP Cloud Integration we can pull the sales data at a defined time frame, and finally import that sales data into SAP Emarsys Customer Engagement. The diagram below depicts a simplified architecture view.

Configuration

SAP Commerce ODATA SALES ORDERS

Pre-requisites:

- SAP Commerce Cloud version 2105 or later

- SAP Emarsys Customer Engagement latest release, with the SAP Commerce plugin installed

To configure SAP Commerce Cloud Sales Order Data to be integrated into SAP Emarsys Customer Engagement you must execute the following steps:

1. Log into SAP Commerce, Back Office – Integration UI Tools

1. You must create a new API model named: EmarsysOrderExt from EmarsysOrder, to allow SAP Cloud Integration to pull SAP Commerce Order Data, with custom attributes, and send it to SAP Emarsys:

1. In our example EmarsysOrderExt must contain an Additional field: entries [OrderEntry] → CadTotalPrice
  1. 1. This is a custom attribute and will be used to calculate the total price in Canadian Dollars.
  1. 1. SAP Emarsys only allows one currency per account, Canadian Dollars in our example, CadTotalPrice was created as Dynamically attribute in SAP Commerce and must be populated using a service to calculate the New CadTotalPrice from TotalPrice by Currency-Rate (Sales Order Date).
  1. 1. if you don’t have any custom attribute to be used in this integration you can use the EmarsysOrder standard provided in the SAP Emarsys customer Engagement integration plugin.
  1. 1. Review all dates from SAP Commerce to be sent to SAP Emarsys. They must follow this specific format: ‘yyyy-MM-dd’
  1. 1. With this new API you will have an API endpoint from SAP Commerce, to be used in SAP Cloud Integration.The following URL example will show the metadata for this exposed object from SAP Commerce
      1. https://<;SAP Commerce Site>/odata2webservices/EmarsysOrderExt/$metadata
        
        You must create a technical user and password in SAP Commerce, to be used in SAP Cloud Integration, with reading privileges for EmarsysOrderExt.
      1. You can use Postman to validate the metadata using the URL, user and password, created in SAP Commerce.

SAP Cloud Integration

SAP Cloud Integration helps you to connect cloud and on-premise applications with other SAP and non-SAP cloud and on-premise applications.

This service has the capability to process messages in real-time scenarios spanning different companies, organizations, or departments within one organization.

Note: SAP Integration Suite combines the integration capabilities Process Integration, API Management, Integration Advisor, and Open Connectors into a cohesive and simplified toolkit for enterprise integrations. To provide a comprehensive integration experience, these services are not available separately, but only as part of the Integration Suite service plan.

To learn more about these different service plans, see the Integration Suite service catalog and SAP Cloud Integration Help Documentation

Integration Package

SAP Cloud Integration allows you to assemble integration contents into packages and publish them, so that integration developers can use these packages in their integration scenarios.

As an integration developer, you can now create integration packages for your specific domain or organization, view different packages published by other integration developers and consume them for your integration purposes, and modify these packages based on your requirements and upload them through the web application.

For more details please visit Packaging Integration Content in SAP Cloud Integration.

Integration Flows

An integration flow allow you to specify how a message is processed on a tenant.

You can use integration flows to specify specific integration patterns like mapping or routing.

A graphical editor allows you, the integration developer, to model the message processing steps and specify in detail what happens to the message during processing.

In detail, you define the following aspects in an integration flow:

- The senders and receivers of the message.

- How the senders and receivers are connected to the tenant (adapters).

- The steps that define the message processing.

For more details, please visit the links below:

- Developing Integration Content with SAP Cloud Integration.

- Elements of an Integration Flow.

Security Artifacts

Required user credentials and parameters are created and stored in the Manage Security Material component on SAP Cloud Platform Integration (SAP CPI).

Please visit the links below to learn more about Security Artifacts:

- Managing Security Material

- Deploying a User Credentials Artifact

- Deploying a Secure Parameter Artifact

Keystore

All keys, key pairs, and certificates for communication with SAP Cloud Platform Integration (SAP CPI) are stored in the SAP CPI Keystore.

To enable a successful SSL Handshake, the Root certificates of the connected systems need to be added to the SAP CPI Keystore.

To learn more, please visit Managing Keystore Entries.

SAP Commerce preparation

You must have administrators privilege in SAP Commerce Cloud in order to create the OData Business Object for sales data to be used by SAP Cloud Integration.

Create a package

You must create a Package in your design space in SAP Cloud Integration:

iFlow Design

The new iFlow “SAP CC Emarsys Replicate Sales Orders”, must be created in the package for the Emarsys integration, using the following design recommendations.

In this section we will provide details regarding each of the fourteen steps in the image below:

iFlow: Sales Order Replication from SAP Commerce to Emarsys

This iFlow is created to pull messages from SAP Commerce Cloud and transforms the inbound message into a well-formatted Emarsys Sales API request.

To avoid the creation of duplicate Sales Order data, the sales order items are only created when certain conditions are true.

Note that in Emarsys, the Sales Data from Commerce is always an insert to the Emarsys Sales Data.

1. Start Timer: iFlow automation, defined in the configuration parameters

1. Retrieve Last Executed Date and define other properties:

Determine Query Run Dates:

1. groovy script to select the next run date, after initial load.

Determine Query Run Dates

def Message processData(Message message) {
   //Properties  
   map = message.getProperties();
   lastModifiedDateValue = map.get("RunFromDate");
   lastRecordProcessedTS = map.get("LastRecordProcessedTS");//This is the prefered date for delta comparison 
   initialStartDateValue = map.get("IntitialRunDate"); //Provide initial load timestamp 
   
   if (lastRecordProcessedTS.length() > 1) {
       message.setProperty("RunFromDate", lastRecordProcessedTS.substring(0,lastRecordProcessedTS.length()));
   } 
  else if (lastModifiedDateValue == null || lastModifiedDateValue.length() < 1) {                              
      message.setProperty("RunFromDate", initialStartDateValue);
   }

   return message;
}

1. Build SCC Sales Orders Query

1. Assign to query property the filter value as per the following sample:
  1. 1. 1. Build SCC Sales Orders Query
        $select=date,user/gyUID,code,currency/isocode,entries/product/code,entries/totalPrice,entries/quantity&$expand=currency,entries,entries/order,entries/product,user,user/type&$filter=date gt datetime'${property.RunFromDate}'
      1. Property RunFromDate, was set up in a previous step.Use:
        
        $select to only extract the fields you like to use in your payload.
        
        $expand in the OData to extract subset data from Commerce Sales Orders.
        
        $filter to define your own query.

1. Save LastExecuted Date
  Using the date-time when the process is running, we must store this data in a global variable, to be used for the next execution, allowing the process just to extract the next delta records from the last execution.

OData Call to SAP Commerce Cloud:
Connection tab

Parameter	Value
Address	https://<servername>.com/odata2webservices/EmarsysOrderExt/
Proxy Type	Internet
Authentication	Basic, used for the sample, you can use other with more security like Client Certificate or OAuth
Credential Name	Name of the Security Artifact, containing the user and password to be used to connect to SAP Commerce
CSRF Protected	Not used for this sample.

1. Processing tab
  
  Parameter Value
  
  Operation Details Query(GET)
  
  Resource Path Orders
  
  Query Options ${property.query}
  
  Content Type Atom

Parameter	Value
Operation Details	Query(GET)
Resource Path	Orders
Query Options	${property.query}
Content Type	Atom

Check Payload Sales Order returned:
Use the following sample script to validate the data returned by the SAP Commerce query:
Check Payload SO

def Message processData(Message message) {
    
    def body_rt = message.getBody(java.lang.String) as String;

    if(body_rt.length() > 12){ 
      //only the label <Orders/> and We defined 12, as the minimum length when no data was returned.
      message.setProperty("Body_To_CSV", "true");
    }
    else {
      message.setProperty("Body_To_CSV", "false");
    }
    message.setProperty("Body_Length_CSV",body_ia.length());

    return message;
}

1. If Sales Orders to send to Emarsys, based on check payload process: Process CSV TO SFTP will be executed.

Mapping from SAP Commerce (XML) to Emarsys required fields: XSLT Valid UID

1. To change the message schema, e.g. when adding new custom Fields, change the xlst schema file in the IFlow resources.

1. Process: XML to CSV Converter and check payload

Use the following XSLT sample: /mapping/XSLTMapping1.xsl
XSLT Valid UID

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:output method="xml" version="1.0" encoding="UTF-8" indent="yes" />
	<xsl:template match="/">
		<!-- template for building message to send to target system -->
		<Orders>
			<Order>
				<xsl:for-each select="Orders/Order">
				<!-- general contact data -->
				<xsl:if test="user/Customer/gyUID = ''">
				<item_orders>
    				<xsl:for-each select="entries/OrderEntry">
    				<item_order>
                				<order>
                					<xsl:value-of select="order/Order/code" />    
                				</order>
                			<item>
                				<xsl:value-of select="product/Product/code" />
                			</item>
                			<customer>
                				<xsl:value-of select="../../user/Customer/gyUID" />            				</customer>
                			<xsl:copy-of select="quantity" />
                			<timestamp>
                				<xsl:value-of select="concat(substring(order/Order/date,1,19),'Z')" />
                			</timestamp>
                			<price>
                				<xsl:value-of select="cadTotalPrice" />            					    	</price>
                			<s_currency>
                				<xsl:value-of select="../../currency/Currency/isocode" />
                			</s_currency>
                			<f_price_original_currency>
                				<xsl:value-of select="totalPrice" />
                			</f_price_original_currency>
                			<s_promo_code>
                			</s_promo_code>
                			<s_customer_Type>
					<xsl:value-of select="../../user/Customer/type/CustomerType/code" />	 
                			</s_customer_Type>
                			<s_customer_Add_Id>
                				<xsl:value-of select="../../user/Customer/uid" /> 						</s_customer_Add_Id>
    				</item_order>
    				</xsl:for-each>
	    		</item_orders>
			</xsl:if>
		</xsl:for-each>
	<!-- end for-each for every contact line in the csv file -->
	</Order>
</Orders>
</xsl:template>
</xsl:stylesheet>

XML to CSV Converter and then Check Payload:

1. We need to convert the XML result from the previous step

Then, we must check the new Payload, using the following script:Check Payload

// We capture the length after the payload was converted.

def Message processData(Message message) {
    
    def body_csv = message.getBody(java.lang.String) as String;

    message.setProperty("Body_Length_CSV3",body_csv.length());

    return message;
}

1. Process Send to Emarsys
  1. 1. Call subprocess: Send to Emarsys

Configure: Emarsys Headers and Body format

Message Header: parameters required to call SAP Emarsys Sales Orders API

Parameter	Value
Accept-Encoding	gzip,deflate,br
Host	Host URL
Cache-Control	no-cache
Connection	keep-alive
Accept	text/plain
Content-type	multipart/form-data; boundary=—-CPI
Authorization	bearer <SAP Emarsys API Sales order token

Message Body

Parameter	Value
Type	Expression
Body	——CPI Content-Disposition: form-data; name=”file”; filename=${property.CSV_file} Content-Type: text/csv Accept: text/plain ${in.body} ——CPI–

Parameter

Value

Type

Expression

Body

——CPI

Content-Disposition: form-data; name=”file”; filename=${property.CSV_file}

Content-Type: text/csv

Accept: text/plain

${in.body}

——CPI–

Send Sales Orders to Emarsys: HTTP Call connection

Parameter	Value
Address	https://<servername>.com/hapi/<merchant ID>/sales-data/api
Query	live=false will be posted as soon is received
Proxy Type	Internet
Method	POST
Authentication	None
Request headers	*(All)
Response Headers	*(All)

1. Exception Subprocess: Send Email
  The capture of any parameter or issue during the execution can be sent by email.

iFlow Configuration

The iFlow must be built to be configured without having to edit the integration itself. Editing the iFlow is only required when the message transformation and processing itself needs to be changed, for example when adding and mapping a new custom field.

To define the iFlow configuration you must assign the external parameters to the properties required then you can open the integration package and select the “Configure” option in the drop-down.

- Timer: You can schedule the frequency to allow the process to run.

- Receiver: Configure the sender adapter for outbound messages.
  - - In multiple sender adapters are configured, you can change the sender adapter in the drop-down list.

- More: All external properties of the iFlow. The default view views. To view externalized properties for a specific step in the message transformation, select the step in the drop dwn list.

1. Timer: This tab allows you to define the automation of the execution
  - - Run Once: execute the iflow only one time immediately
  - - Schedule on Day: Select the date and time you like the iFlow to run
  - - Schedule to Recur: Define the frequency (Daily, Weekly or Monthly) and the range starting hour and ending hour, based in the time zone you select.

Receiver: This tab is to configure the target systems:

SAP Emarsys:

Parameter	Value
Adapter type	HTTP
Address	Automatically created using Emarsys Address parameter
Emarsys Address	Your SAP Emarsys Tenant
Query	live=false; this parameter indicate to Emarsys how to process the new Sales Order
TimeOut (in ms)	Maximun time to wait for Emarsys answer.

SAP Commerce Cloud:

Parameter	Value
Adapter type	HCIOdata
Address	Automatically created using SAP_CC_Address parameter
SAP_CC_Address	Your SAP Commerce Cloud Tenant
Credential Name	Security Artifact created in Sap Cloud Integration to call SAP Commerce Cloud

More: This tab is to configure additional parameters in the iflow:

Parameter	Value
Environment	TEST or PROD
Initial Run Date	<Date> For the initial load date, define when is going to start the process, after this date, the system will use the global variable to load the delta records
Sales Orders Query	to review the query used in the SAP Commerce extraction
Sales orders Top	<Maximum number of Sales Orders to be read per call>

Conclusion

With SAP Cloud Integration Platform, the Sales Orders data from SAP Commerce Cloud can be exported to the SAP Emarsys Customer Engagement. In our scenario where the client is using SAP Commerce Cloud for two commerce sites, one for Canada and another for the United States of America, all sales information was made available to be integrated into the SAP Emarsys Customer Engagement within a single account, located in Canada, using Canadian Dollars as the base currency of the application.

SAP Cloud Integration made it easy to pull the sales data to be exported into SAP Emarsys Customer Engagement using Emarsys API with simple steps that have been explained in this document.

The articles below will help you dive deeper into the solutions:

- SAP Commerce Cloud

- SAP Cloud Integration

SAP Emarsys Integration

Tags: Customer Experience SAP Commerce Cloud SAP Emarsys Customer Engagement

Sara Sampaio

Author Since: March 10, 2022

0 0 votes

Article Rating

0 Comments

Inline Feedbacks

View all comments