Overview
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
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:
- Log into SAP Commerce, Back Office – Integration UI Tools
- You must create a new API model named:
EmarsysOrderExtfromEmarsysOrder, to allow SAP Cloud Integration to pull SAP Commerce Order Data, with custom attributes, and send it to SAP Emarsys:
- In our example
EmarsysOrderExtmust contain an Additional field:entries [OrderEntry]→CadTotalPrice
- This is a custom attribute and will be used to calculate the total price in Canadian Dollars.
- if you don’t have any custom attribute to be used in this integration you can use the
EmarsysOrderstandard provided in the SAP Emarsys customer Engagement integration plugin. - Review all dates from SAP Commerce to be sent to SAP Emarsys. They must follow this specific format: ‘yyyy-MM-dd’
- 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
- 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.
- You can use Postman to validate the metadata using the URL, user and password, created in SAP Commerce.
- https://<;SAP Commerce Site>/odata2webservices/EmarsysOrderExt/$metadata
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:
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:
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.
- Start Timer: iFlow automation, defined in the configuration parameters
- Retrieve Last Executed Date and define other properties:
- Determine Query Run Dates:
- 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;
}
- Build SCC Sales Orders Query
- Assign to query property the filter value as per the following sample:
- 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}'
- 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.
- Build SCC Sales Orders Query
- 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.
- Processing tab
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;
}
- 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
- To change the message schema, e.g. when adding new custom Fields, change the xlst schema file in the IFlow resources.
- 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:
- 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;
}
- Process Send to Emarsys
- 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--
- Message Header: parameters required to call SAP Emarsys Sales Orders API
- 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)
- 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.
- 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>
- SAP Emarsys:
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:
Disclaimer: Original version of this article was written in SAP CX Works.
- SAP Managed Tags:
1 Comment
