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
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 

Integrate SAP S/4HANA Cloud with SAP Emarsys Customer Engagement

FernandoRedondo
Product and Topic Expert
Product and Topic Expert
‎08-02-2023 2:10 PM

Overview



Integrate SAP S/4HANA Cloud with SAP Emarsys Customer Engagement

Table of Contents

In this blog post we will describe one possible approach for replicating Contact and Sales Data from SAP S/4HANA to SAP Emarsys Customer Engagement. The described content is built custom and not part of any SAP pre-packaged integration.
The described integration scenarios can be used as a template for building a custom integration with SAP S/4HANA and SAP Emarsys Customer Engagement. SAP Cloud Integration is used for the message transformation for API based data imports to Emarsys.

The following diagram describes the general setup of an exemplary integration between SAP S/4HANA and SAP Emarsys Customer Engagement using SAP Cloud Integration.


 









Note: This blog post does not cover importing product data to Emarsys. Refer to the Emarsys help documentation for uploading product data to Emarsys.

Products/Solutions/Services used:

  • SAP S/4HANA Cloud or On-Premise

  • SAP Cloud Integration (SAP Integration Suite)

  • SAP Emarsys Customer Engagement

  • SFTP Server for Product data (not covered in this blog post)


Integration Overview


In this blog post we focus on the B2C Business Partner/Contact and Sales Order replication.
As now (Q2 2022), SAP Emarsys Customer Engagement does not provide a public API for importing product data.

Before loading data, please familiarize yourself with the available data objects and their corresponding data fields and types.


Business Partner Replication

  • Emarsys documentation – Contact Data fields overview
    https://help.emarsys.com/hc/en-us/articles/115004637605-Overview-Contact-data-fields-Overview

  • Emarsys documentation – Uploading your contact data
    https://help.emarsys.com/hc/en-us/articles/213706389-Uploading-your-contact-data

  • SAP S/4HANA Outbound Service: Business Partner Replication via SOAP Web Service

    • Collecting and sending messages in batches is recommended

    • Only relevant Business Partners a should be replicated to Emarsys



  • Emarsys API: Contact API

  • IFlow: Contact data replication

    • Processes the inbound SOAP Message from SAP S/4HANA

    • Transforms the inbound SOAP Message request into a Emarsys Contact API request

    • Message Processing errors send a notification to the defined tenant administrator via an Emarsys Broadcast event.

    • Failed inbound messages are written to the SAP Cloud Integration data store for reprocessing



  • IFlow: Contact data Reprocessing 1

    • Reprocessed the failed SOAP Message and re-send the failed message to the Contact data replication IFlow.

    • When the message fails again, the entry is deleted from the data store and moved into another data store for a second reprocessing



  • IFlow: Contact data Reprocessing 2

    • Reprocessed the failed SOAP Message and re-send the failed message to the Contact data replication IFlow.

    • When the message fails again, the entry is deleted from the data store and moved into another data store for review.

    • Entries in the for-review data store are not reprocessed again.




Sales Order Replication

  • Emarsys documentation – Preparing your sales data file
    https://help.emarsys.com/hc/en-us/articles/360003070654-Preparing-your-sales-data-file

  • Emarsys documentation – Uploading your sales data
    https://help.emarsys.com/hc/en-us/articles/213706429-Uploading-your-sales-data

  • SAP S/4HANA Outbound Service: Sales Order Replication via SOAP Web Service

    • Collecting and sending messages in batches is recommended

    • Only relevant Sales Orders a should be replicated to SAP Emarsys Customer Engagement.
      Custom filters can be configured on SAP S/4HANA to control the Sales Orders replicated to receiving systems.



  • IFlow: Sales Order data Replication

    • Processes the inbound SOAP Message from SAP S/4HANA

    • Transforms the inbound SOAP Message request into a Emarsys Sales Data API request

    • Message Processing errors send a notification to the defined tenant administrator via an Emarsys Broadcast event




Product Data Replication

SAP S/4HANA Cloud and On-Premise Configuration


A secure connection between SAP S/4HANA and SAP Cloud Integration is established.
Follow the SAP S/4HANA configuration guide for the SAP S/4HANA Integration with SAP Marketing Cloud since the same outbound services are used for this integration.

It is recommended to apply custom filters on SAP S/4HANA to only replicate the relevant data, this is especially important for the Sales Data replication.
Further, you should consider replicating data in batches for better performance.

SAP S/4HANA Integration configuration guides

SAP S4/4HANA Configuration Summary

Summary of configuration steps.

  • Set up Secure Connection between Systems



  • Configuration in SAP Cloud Integration

    • The created endpoint and communication used is to be maintained in SAP S/4HANA



  • Configuration in SAP S4/4HANA



  • To be configured scenarios:





    • Business Partner Replication

      • No End of Purpose (EOP) for Business Partner

      • No Business Partner Relationship



    • Sales Order Replication

    • No Product replication directly from S4HANA. The SOAP WS send partial product catalog updates and not the full catalog as a full extract





  • Initial Data load from SAP S/4HANA

    • Initial Data Load for Business Partners

    • Initial Load for Sales Orders




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 capabilities to process messages in real-time scenarios spanning different companies, organizations, or departments within one organization.



 






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 on different service plans, see Integration Suite service catalog.

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 create integration packages for your specific domain or organization. You can also view different packages published by other integration developers and consume them for your integration purposes. You can modify these packages based on your requirements and upload them through the web application.

Integration Flows


An integration flow allows 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.

Security Artifacts


User Credentials and Secure Parameters


Required user credentials and parameters are created ad stored in the Manage Security Material component on SAP CPI.

Keystore


All keys, key pairs, and certificates for communication with 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.

SAP Emarsys Customer Engagement Value Mapping


You create a value mapping artifact to act as a bi-directional look up table. Value mapping offers the distinct advantage of giving you bi-directional look up capabilities which are used quite often in productive mapping scenarios.

The value mapping can be accessed from the Message Mapping using the mapValue function.

IFlow Configuration


When building custom integration, it is best practice to define externalized parameter for easier configuration. External parameters allow to configure the IFlow without having to edit the IFlow.
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.

More information on defining and configuration of external parameters, refer to the SAP Help documentation.

To configure the IFlow, open the integration package and select the "Configure" option in the drop-down.

  • Sender: Configure the receiver adapter for inbound messages.

  • Receiver: Configure the sender adapter for outbound messages.

    • If 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-down list.


IFlow: Business Partner Replication from SAP S4 HANA to SAP Emarsys Customer Engagement


This IFlow is receiving inbound messages from SAP S/4HANA and transforms the inbound message into a well-formatted Emarsys Contact API request.



 





























































































































Step

Description




Sender: S4OnPrem

Type: SOAP		 SOAP Sender is configured

  • Address: /sap/bc/srt/scs/sap/businesspartnersuitebulkreplic_OnPrem

  • Processing Settings: Robust

  • Authorization: User Role

  • User Role: ESBMessaging.send
    The role needs to be assigned in SAP BTP Cockpit to the communication user that is used for authentication.




Content Modifier

define properties and headers



Message headers and properties are defined.

Exchange Properties:

  • emarsysContactList: This is mandatory and defines the contact list on Emarsys. All Contacts imported through this integration are added to the defined contact list.

  • securityArtifact: Mandatory. Emarsys API User Credentials need to be created as a secure artifact to SAP CPI.

  • create_if_not_exists: Mandatory. Values are 1 or 0.

  • contactKeyID: Mandatory. Define the contact key field to be used as a unique contact identifier.

  • When using a custom field for contact identification, the field needs to be indexed first.

  • removeEmpty: Optional. Per default, empty values are kept.

  • False: empty values are not removed. Empty values overwrite existing data.
    True: empty values are deleted and would not overwrite existing data.

  • adminEmail; The CPI Admin Email is required when Mail notifications are enabled.
    This is required when error notifications are enabled.

  • enableReprocessing: Enable reprocessing for failed contact data.
    This required both reprocessing IFlows to be configured and deployed.

  • MailNotification: Email notifications can be enabled but require configuring an CPI Admin Email and a Broadcast event with Email template in Emarsys.
    Both reprocessing Iflows need to be deployed.

  • inboundMessage: Persists inbound message. The inbound message is used in case of an error so the same messages can be sent for reprocessing.




Groovy Script

Log Inbound Message

  • Logs the inbound message body.

  • Message logs need to be enabled by setting the exchange property “Enable Logging” to value “true”.

  • Only enable the message log if needed. The message body is stored as an attachment in the Message Processing Log (MPL)

  • For testing the integration, it is recommended to log level “trace”. The trace log level can be enabled for 10minutes and traces the complete message processing, including message headers and properties.




XSLT Mapping

Filter Address Info

  • Address information is filtered to only include default address information.




Message Mapping

Emarsys Contact Mapping


  • Message Mapping from SAP S/4HANA On-Prem to SAP Emarsys.

    • The message mapping contains most of the transformation logic of the message body.



  • Input Message Schema: Download the WSDL from SOAMANAGER
    Use BusinessPartnerSUITEBulkReplicateRequest for the Business Partner mapping.

    • IMPORTANT: The WSDL should not be changed manually. Download the most recent WSDL from the SOAP Web Service configuration in SOAMANAGER.



  • Output Message Schema
    Define the Emarsys message Schema.

  • You can use the Emarsys field ID or string ID.

    • IMPORTANT: XML does not allow numeric element names in the XML Schema.
      The Emarsys Contact API requires the field ID or the field Sting ID in the request payload. The option of using the String ID is relatively new (as of Feb 2022) and  caused some issues during data replication (key id field not found and error responses).
      All fields have the prefix tmp_ what is deleted later in the IFlow.





To change the message schema, e.g. when adding new custom Fields, change the schema file in the IFlow resources. The Message Mapping schema is updated with the message schema and the additional field can be mapped.


Use the graphical message mapping to adjust the message transformation logic.
A mapping Excel file can be exported from the Message Mapping.

Emarsys XML Schema example with Emarsys Field ID:

When using the field id of the Emarsys fields, the XML element names can’t be numeric. Add a prefix to all field names and delete the prefix later. The XML format does not allow element definitions such as <1>value</1>.

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="root">

<xs:complexType>

<xs:sequence>

<xs:element type="xs:string" name="contact_list_id"/>

<xs:element type="xs:string" name="key_id"/>

<xs:element name="contacts" maxOccurs="unbounded" minOccurs="0">

<xs:complexType>

<xs:sequence>

<xs:element type="xs:string" name="tmp_1" maxOccurs="1" minOccurs="0"/>

<xs:element type="xs:string" name="tmp_2" maxOccurs="1" minOccurs="0"/>

<xs:element type="xs:string" name="tmp_3" maxOccurs="1" minOccurs="0"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>

Emarsys XML Schema example with Emarsys String Field ID:

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:element name="root">

<xs:complexType>

<xs:sequence>

<xs:element type="xs:byte" name="key_id"/>

<xs:element name="contacts" maxOccurs="unbounded" minOccurs="0">

<xs:complexType>

<xs:sequence>

<xs:element type="xs:string" name="first_name" maxOccurs="1" minOccurs="0"/>

<xs:element type="xs:string" name="last_name" maxOccurs="1" minOccurs="0"/>

<xs:element type="xs:string" name="email" maxOccurs="1" minOccurs="0"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>




Router

BP validate

  • Branch 1: no contact/customer
    Default Branch, Ends message processing

  • Branch 2: validRoleCode
    Expression Type: XML
    Condition: boolean(//contacts)
    When at least contact exist after mapping the message for further processed. This is to avoid processing empty messages since not all Business Partner Role Codes are processed.




Router

Remove Empty

  • Branch 1: keep empty
    Default branch, keeps empty values.

  • Branch 2:  remove empty
    Expression Type: non-XML
    Condition: ${property.removeEmpty} = 'yes'


When empty elements are deleted, a delta update is sent to Emarsys, not overwriting existing values.
When the empty values are kept, existing values are overwritten.




XSLT Mapping

Remove empty nodes

  • Removes empty nodes with no values.


This process step is only executed when the remove empty branch is enabled.




Groovy Script

Create WSSE Header

  • Authentication header X-WSSE is generated.

  • Called custom script function: XWSSEHeader

  • The property “securityArtifact” is required to run this fuction.
    The property “securityArtifact” references the name of the security artifact that stores the Emarsys API User credentials


For more information on ow to generate the WSSE Header, review the Emarsys developer documentation.
https://dev.emarsys.com/docs/emarsys-api/ZG9jOjI0ODk5NzAx-authentication




General Splitter

XML Splitter


The XML Splitter splits the inbound message payload into smaller packages. The package size can be configured in the Grouping parameter of the General Splitter.

The package can also be controlled SAP S4HANA.
XML to JSON Converter Converts the XML Message into a JSON message




Groovy Script

remove tmp_



Called custom function: replaceTmp

Replaces all tmp_ values for the field ids to match the Emarsys field ids.




Groovy Script

Log Outbound Message		 See Groovy Script “Log Inbound Message”




Content Modifier

delete uri header

  • The SOAP sender stores the request uri path in the message header “CamelHttpUri”.

  • The HTTP Receiver adapter replaces the defined address in the adapter with the value of the header “CamelHttpUri” when a values exists.

  • The message header “CamelHttpUri” is to be deleted to not overwrite the receiver address.




Request Reply

Submit Contact





Groovy Script

validate response

  • Validates response from Emarsys.
    Emarsys might respond with the success HTTP status in the header but indicate and error in the response body.

  • Called custom function: validateResponse
Router

  • Branch 1: HTTPCodeOK
    Expression Type: non-XML

  • Condition: ${property.responseStatus} = 'OK'
    Branch 2: HTTPCodeNotOK
    Default branch, ends processing.




Local Sub-process

Error Handling

  • Error handling log the error, decides if messages is stored for reprocessing, and decides if an Email is sent as a notification.




Local Sub-process

Error Handling

Groovy Script

logError

  • Logs and writes message body as Message Processing Log attachment

  • Called custom function: logHTTPError




Local Sub-process

Error Handling

Router 1

  • No reprocessing: default path

  • Reprocessing: Reprocessing messages
    ${property.enableReprocessing} = 'true' and ${header.message_reprocessing} != 'true'
    enableReprocessing is defined in this IFlow

  • message_reprocessing is defined in the Reprocessing Iflow




Local Sub-process

Error Handling

Content Modifier

Reset Message payload

  • Replacing the message body with the inbound message body.
    ${property.inboundMessage}




Local Sub-process

Error Handling

Data Store Write

save Message for reprocessing

  • The message for reprocessing is written to the SAP CPI Data store where it is picked up by the IFlow for reprocessing.

  • Data Store Name: Name of the data store




Local Sub-process

Error Handling

Router

  • No Email: Default

  • Route: ${property.MailNotification} = 'true'
    Sends external event to Emarsys to trigger the Email Notification.




Local Sub-process

Error Handling

Groovy Script

define tmn host

  • The script defines the tenant management host from the runtime URL. This URL is used as a personalization attribute in the email for directly link to the SAP CPI Monitoring.

  • Tenant Management URL
    <tenant name>.<tenant location>.cfapps.us21.hana.ondemand.com

  • Tenant Runtime URL
    <tenant name>.<tenant location>-rt.cfapps.us21.hana.ondemand.com




Local Sub-process

Error Handling

Content Modifier

define external event

  • The external event is defined in the content modifier since the request body is simple and usually does not require modification.


The following external event message body is send to Emarsys.
The information from the external event can be accessed in the email personalization.

{

"email": "${property.adminEmail}",

"data": {

"global": {

"adminEmail": "${property.adminEmail}",

"timestamp": "${property.CamelCreatedTimestamp}",

"CPIHost": "${header.CPITmnHost}",

"CPIPath": "${header.CamelHttpUri}",

"caughtException": "${property.CamelExceptionCaught}",

"expectionMessage": "${exception.message}",

"messageProcessingLogID": "${property.SAP_MessageProcessingLogID}"

}

}

}




Local Sub-process

Error Handling

Content Modifier
delete uri header

  • The CamelHttpUri is deleted to avoid overwriting the HTTP CamelHttpUri header on the receiver.




Local Sub-process

Error Handling

Groovy Script

Create WSSE Header

  • The script defines the WSSE authentication header




Local Sub-process

Error Handling

HTTP Receiver

  • The error notification email is sent via a broadcast event. Broadcast event do not require the contact to exist in Emarsys and are not tracked.
    Address: https://api.emarsys.net/api/v2/email/{EventID}/broadcast

  • The Event ID: Is defined on Emarsys when the Trigger Email is assigned, and Broadcast Event is selected as the Email trigger.

IFlow: Business Partner Replication from SAP S4 HANA to SAP Emarsys Customer Engagement Data Reprocessing


This IFlow reprocesses failed messages of the Business Processing IFlow (IFlow: Business Partner Replication from SAP S4 HANA to SAP Emarsys Customer Engagement). Failed Business Partners are stored on the SAP CPI and reprocessed once a day. A time frame for reprocessing during off-business times is chosen.

Most errors are failed authentication requests when too many requests reach Emarsys at the same time. Resending the same request should resolve this issue.

Every failed message can be reprocessed up to two times before it’s stored for review.










































Step

Description
Start Timer

  • The Start Timer schedules the IFlow execution and can be configured.

  • The IFlow should be scheduled during off-business hours

  • The IFlow should not run more frequently than every minute.




Data Store Select

Select Contacts

  • Data Store Name: Define the data store name from where the failed messages are stored.

  • When the message is processed successfully, the data store entry is deleted.

  • Messages are processed one-by-one




Splitter

Split single message

  • The Data Store Select is configured to only collect one entry from the data store with each run.

  • The splitter is added to ensure that only one message is processed at a time.

  • Processing each data store entry individually makes it easier to define what message failed and succeeded.

  • In case of multiple errors, the select operation can be changed to collect multiple messages. Adjustments in the error process might be required if multiple entries are selected.
Filter

  • The select operation adds additional elements to the called message. The filter step filters the selected message to match the original message
    Filter condition: //n0:BusinessPartnerSUITEBulkReplicateRequest
Content Modifier

  • Header: message_reprocessing is sent with value “true” (fix value).

  • This is used in the Business Partner replication to avoid storing the message again in the data store, creating duplicate entries

  • Exchange Property: inboundMessage sets the new inbound message for the second reprocessing IFlow in case the message fails again.




Exception process

Reset message body

  • This step defines the new message body for the second reprocessing IFlow




Data Store Write

Write to Data Review Data Store

  • Data Store Name
    Define the data store name for the second reprocessing IFlow


IFlow: Business Partner Replication from SAP S4 HANA to SAP Emarsys Customer Engagement Data Reprocessing 2


This IFlow is a copy of the first reprocessing IFlow with the difference being that the Data Store Write operation writes in a data store for data review where the data is not encoded.

IFlow: Sales Order Replication from SAP S4 HANA to SAP Emarsys Customer Engagement


This IFlow is receiving inbound messages from SAP S/4HANA 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.
The conditions related to when a Sales Order is considered as completed can be different depending on the how Sales Orders are processed on SAP S/4HANA.

Note that sales order imports incremental and always add to the existing sales data.
Uploading your sales data: https://help.emarsys.com/hc/en-us/articles/213706429-Uploading-your-sales-data

It is recommended to control the release of Sales Data to Emarsys on SAP S/4HANA defining specific conditions on SAP S/4HANA. Additional conditions can be defined on SAP Cloud Integration if needed.


Data fields for building conditions on SAP Cloud Integration can be on the order header and/or line item level.

  • Order is completed and shipped

  • Order is cancelled

  • Order is in Processing

  • Item is completed and shipped

  • Item is cancelled

  • Item is in processing


This is an example on how to define conditions to be implemented on SAP Cloud Integration.





























Order is completed and shipped

Order is cancelled

Order is in Processing

Item is completed and shipped



Order is created

Item is created



Order is created

Item is removed		 Order is ignored

Item is cancelled



Order is created

Item is removed



Order is created

Item is created with negative values		 Order is ignored

Item is in processing


 Item is ignored Item is ignored Order is ignored






















































































Step

Description




Sender: S4OnPrem

Type: SOAP

  • SOAP Sender is configured

  • Address: /SalesOrderBulkReplication_Out_OnPrem

  • Processing Settings: Robust

  • Authorization: User Role

  • User Role: ESBMessaging.send
    The role needs to be assigned in SAP BTP Cockpit to the communication user that is used for authentication.




Content Modifier

define properties and headers

  • Message headers and properties are defined.

  • Exchange Properties:

  • filename: Mandatory. Defines the filename of the imported sales data

  • adminEmail; The CPI Admin Email is required when Mail notifications are enabled.

  • MailNotification: Email notifications can be enabled but require configuring an CPI Admin Email and A Broadcast event with Email template in Emarsys.




Groovy Script

Log Inbound Payload

  • Logs the inbound message body.

  • Message logs need to be enabled by setting the exchange property “Enable Logging” to value “true”.

  • Only enable the message log if needed. The message body is stored as an attachment in the Message Processing Log (MPL) and the storage size for attachments is limited on SAP Cloud Integration.

  • For testing the integration, it is recommended to log level “trace”. The trace log level can be enabled for 10 minutes and traces the complete message processing, including message headers and properties.




General Splitter

XML Splitter

  • The XML Splitter splits the inbound message payload into single messages, so the message mapping can validate each Sales Order Business Document.

  • It is not required to process the sales order individually. Sales Orders can be processed in batches.

  • In this example, the Sales Order are processed individually. The Mapping for business documents requires the Sales Order BD to be processed individually, otherwise the complex BD structure can lead incorrect message transformations.




Message Mapping

Emarsys Contact Mapping


  • Message Mapping from SAP S/4HANA On-Prem to SAP Emarsys.

  • The message mapping contains most of the transformation logic of the message body.

  • Input Message Schema: The input message schema is defined in the WSDL file downloaded from SOAMANAGER on SAP S/4HANA.

  • IMPORTANT: The WSDL should not be changed manually. Download the most recent WSDL from the SOAP Web Service configuration in SOAMANAGER.

  • Output Message Schema:
    define an XML message schema for Emarsys Sales Orders



To change the message schema, e.g. when adding new custom Fields, change the schema file in the IFlow resources. The Message Mapping schema is updated with the message schema and the additional field can be mapped.


Use the graphical message mapping to adjust the message transformation logic.
A mapping Excel file can be exported from the Message Mapping.

Emarsys Sales Data XML Schema example

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">

<!-- Documentation: https://help.emarsys.com/hc/en-us/articles/360003070654-Preparing-your-sales-data-file#required-fiel...-->

<xs:element name="data">

<xs:complexType>

<xs:sequence>

<xs:element name="salesorders" minOccurs="0" maxOccurs="unbounded">

<xs:complexType>

<xs:sequence>

<xs:element name="salesorder" minOccurs="0" maxOccurs="unbounded">

<xs:complexType>

<xs:sequence>

<xs:element type="xs:string" minOccurs="0" name="item"/>

<xs:element type="xs:string" minOccurs="0" name="price"/>

<xs:element type="xs:string" minOccurs="0" name="order"/>

<xs:element type="xs:string" minOccurs="0" name="timestamp"/>

<xs:element type="xs:string" minOccurs="0" name="customer"/>

<xs:element type="xs:string" minOccurs="0" name="email"/>

<xs:element type="xs:string" minOccurs="0" name="quantity"/>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:sequence>

</xs:complexType>

</xs:element>

</xs:schema>




XSLT Mapping

Remove ítems

  • The XSLT Mapping removes Sales Order items that are not to be imported into Emarsys.

  • The conditions for importing the Sales Order are defined in the IFlow description above and implemented in an XSLT script

  • All Sales Order items with Item Status “INPROCESSING” are removed.

  • All Sales Order items with Overall Status “COMPLETED” and Item Status “CANCELLED” are removed.

  • All Sales Order items with Overall Status “CANCELLED” and Item Status “COMPLETED” are removed.

  • Other options are possible to solve this.
Gather

  • The gather step collects the Split items and combines them into one message.




Router

Check empty

  • Branch 1: empty
    Default Branch, Ends message processing

  • Branch 2: not empty
    Expression Type: XML
    Condition: boolean(//salesorder)
    When at least one sales order exist after mapping the message for further processed.
Filter

  • The Gather step filters for only the relevant items.

  • The Gather step removed the partent nodes added from the previous steps

  • XPath Expression: //salesorder

  • Value Type: Nodelist




Content Modifier

Add root

  • The Content Modifier add a root element to the XML.

  • The root element is required in the XML to further processing and transformation.
XML To CSV Converter

  • Converts the XML body to CSV

  • Path to Source Element in XSD: /salesorders/salesorder

  • Include Field Name as Headers: enabled

  • Include Parent Element: disabled

  • Include Attribute Values: disabled




Groovy Script

Log Outbound Payload

  • See groovy Script “Log Inbound Payload”




Content Modifier

Emarsys Sales API

  • Defines the mandatory headers and properties.

  • Headers are predefined and should not be changed.

  • merchantId: Mandatory. The Merchant ID can be retrieved from Emarsys in the Predict data sources.

  • bearerToken: The bearer token it stores in a secure parameter on CPI to not have the plain text exposed in the frontend. The property refers to the name of the created security parameter on SAP CPI.




Groovy Script

Set Authorization

  • The custom function gets the bearer token stored in the security parameter and generates the authorization header.




HTTP Receiver

Submit Sales Data

  • The HTTP Receiver connects to the Emarsys Sales API.

  • All values except the Merchant ID and Timeout are preconfigured.

  • The Merchant ID and Timeout values are maintained as an externalized property.
Router

  • Branch 1: HTTPCodeOK

  • Expression Type: non-XML

  • Condition: ${property.responseStatus} = 'OK'

  • Branch 2: HTTPCodeNotOK
    Default branch, ends processing.




Groovy Script

logHTTPError

  • Logs and writes message body as Message Processing Log attachment

  • Called custom function: logHTTPError




Local Sub-process

Error Handling

  • Default error handling: log the error and decide if an Email is sent as a notification.

  • The error handing is same for Business Partner and Sales Order replication


IFlow Error Notification


SAP Cloud Integration provides an SMTP adapter for sending Email directly from SAP Cloud Integration Email but does not provide an Email editor or other functionality to easily define and design an email. Since we are already building an integration with SAP Emarsys Customer Engagement, the Triggered Email capabilities of the solution can be leveraged to send Email notifications to a receiver.

For this specific use case using Broadcast Events to trigger an Email might be more suitable that External Events since Broadcast Event emails do not require the contact to be in your contact database and Broadcast Event email streams are not tracked. Broadcast emails are still counted as external event emails for billing purposes.
Once created and activated, you can trigger the sending of error notification from different IFlows using the same process.

In this example we have defined the receiver to receive the error notification in the IFlow. Additional attributes are defined and passed in the request body which can then be used for email personalization on Emarsys. Changes in the Email can be done without having to change the IFlow.

Please review the Emarsys documentation for Triggered Emails for more information.


Triggered Email - End-user guide: https://help.emarsys.com/hc/en-us/articles/360016376278-End-user-guides-Triggered-Email-End-user-gui...


SAP CPI Configuration

  • Enable Email notification by setting the exchange property MailNotification to “true”.

    • We added this so the CPI Admin can decide if error notifications should be enabled or not.



  • Add and Email address for the SAP CPI Admin.

    • In our example we have defined the email notification receiver in the IFlow as an externalized property.
      The receiver could also be passed from the inbound request and defined dynamically on CPI.



  • In the HTTP Receiver channel for the Email Notification, add the Broadcast Event ID generated on Emarsys.


Emarsys Configuration

  • Create a new Triggered Email

  • Select Broadcast Event as a trigger.
    A Broadcast Event ID is provided.

  • Define an Email Template.

  • Activate the triggered email stream


Example Broadcast Event defines on SAP CPI.











{

"email": "${property.adminEmail}",

"data": {

"global": {

"adminEmail": "${property.adminEmail}",

"timestamp": "${property.CamelCreatedTimestamp}",

"CPIHost": "${header.CPITmnHost}",

"CPIPath": "${header.CamelHttpUri}",

"caughtException": "${property.CamelExceptionCaught}",

"expectionMessage": "${exception.message}",

"messageProcessingLogID": "${property.SAP_MessageProcessingLogID}"

}

}

}





























































Step

Description




Groovy Script

Log Error

  • Saves the message payload as attachment to the Message Processing Log.
Router 1

  • Branch 1: no reprocessing (default)

  • Branch 2: Reprocessing
    ${property.enableReprocessing} = 'true' and ${header.message_reprocessing} != 'true'
Message reprocessing branch

  • The message body is reset to the inbound and stored in the SAP Cloud Integration data store.

  • The data store write operation is defined to store the failed message.
    Entry visibility is to be set to “Global”
Router

  • Branch 1: Email, Send Email Notification

  • Branch 2: No Email, No Email Notification

  • Condition expression: ${property.MailNotification} = 'true'




Groovy Script

Define tmn host

  • The error notification includes a link to the CPI tenant’s Monitoring overview.

  • The tenant management node is defined in this step.

  • Called function: defineTmnUrl




Content Modifier

Define external event

  • The broadcast event request body is defined.

  • Available personalization attributes:

  • {{event.adminEmail}}
    Email of the defined CPI Admin in the IFlow configuration

  • {{event.timestamp}}
    Error Timestamp

  • {{event.CPIHost}}

  • SAP CPI Tenant Management Host

  • {{event.CPIPath}}
    SAP CPI Enpoint path

  • {{event.caughtException}}

  • Caught exception message

  • {{event.expectionMessage}}

  • Exception message

  • {{event.messageProcessingLogID }}
    SAP CPI MPL ID, this is used to search the error message in the Message Processing Log

  • The parameters required for the email notification should be defined depending on the relevant use cases.




Content Modifier

delete uri header

  • Deletes CamelHttpUri header to prevent overwriting the target host url

  • Delete: $name=CamelHttpUri
Groovy Script
Create WSSE Header

  • Creates Authentication header

  • Call function: XWSSEHeader




Request-Reply

Send error notification



    • Configure Broadcast Event API request

    • Address: https://api.emarsys.net/api/v2/email/

    • Authentication: none (Authentication is set by the “Create WSSE Header” Script)

    • Request Headers: X-WSSE (allowed header)

    • Response Headers: * (allow all response headers)

 


SAP Emarsys Customer Engagement Configuration


API User


Create an API User on SAP Emarsys Customer Engagement and create a Security Artifact with the Emarsys API User credentials on SAP Cloud Integration. The Security Artifact can be accessed from the IFlow.

On Emarsys, add the required permissions to the API User for the Contact and External Event API.

Sales Data API


The Sales Data API endpoint and token can be retrieved from Emarsys.

Open the Predict Data Sources and go to Manage your Sales Data to find the Sales Data API upload details.




Triggered Email for SAP Cloud Integration Error Notifications


A Triggered Email is created with trigger Broadcast Event.

More information on Triggered Emails can be found in the Emarsys help documentation.






















Step Description
Emarsys Triggered Email Channels > Triggered Emails > Create Mail Stream
Email Settings



Complete the Email settings and select “Broadcast Event” in the Trigger Settings

Note the Broadcast Event ID
Content Creation Define Email Basics and define the Error message email to be send out.

 



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


1 Comment
Popular Blog Posts