CRM and CX Blogs by SAP
Stay up-to-date on the latest developments and product news about intelligent customer experience and CRM technologies through blog posts from SAP experts.
cancel
Showing results for 
Search instead for 
Did you mean: 
FernandoRedondo
Product and Topic Expert
Product and Topic Expert
1,465

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:

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

  2. 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:

  3. In our example EmarsysOrderExt must contain an Additional field: entries [OrderEntry] → CadTotalPrice

    1. This is a custom attribute and will be used to calculate the total price in Canadian Dollars.


    2. 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).



    3. 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.

    4. Review all dates from SAP Commerce to be sent to SAP Emarsys. They must follow this specific format: ‘yyyy-MM-dd

    5. 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.




      2. 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:

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.

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

  2. Retrieve Last Executed Date and define other properties:

  3. Determine Query Run Dates:

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


    2. 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;
      }


    3. Build SCC Sales Orders Query

    4. Assign to query property the filter value as per the following sample:



        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}'


        2. Property RunFromDatewas 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.







    5. 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.

    6. 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.


    7. Processing tab

























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



    8. 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;
      }

       

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

    10. 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.

      2. Process: XML to CSV Converter and check payload

      3. 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>

         



    11. XML to CSV Converter and then Check Payload:

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

      2. 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;
        }

         



    12. Process Send to Emarsys

      1. Call subprocess: Send to Emarsys



    13. Configure: Emarsys Headers and Body format

      1. 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


      2. 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--




    14. 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)


    15. 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.



  2. Receiver: This tab is to configure the target systems:

    1. 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.


    2. 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


    3. 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:





Disclaimer: Original version of this article was written in SAP CX Works.
1 Comment