Integrate SAP S/4HANA Cloud with SAP Emarsys Customer Engagement (2023)

Station: S4OnPrem

Type: soap

SOAP sender is configured

• Verzeichnis: /sap/bc/srt/scs/sap/businesspartnersuitebulkreplic_OnPrem
• Processing Configuration: Robust
• Permission: user role
• User role: ESBMessaging.send
  The role must be assigned to the communication user used for authentication in the SAP BTP Cockpit.

content modifier

Set properties and headers

Message headers and properties are defined.

Exchange properties:

• emarsysContactList - This is mandatory and defines the list of contacts in Emarsys. All contacts imported through this integration will be added to the defined contact list.
• Security artifact: Required. Emarsys API user credentials must be created as a secure artifact for SAP CPI.
• create_if_not_exists: Required. Values ​​are 1 or 0.
• Contact Key ID: Required. Set the contact key field to be used as the unique contact identifier.
• When using a custom field for Contact ID, the field must first be indexed.
• removeEmpty: Optional. By default, empty values ​​are retained.
• False: Empty values ​​are not removed. Empty values ​​overwrite existing data.
  True - Empty values ​​are removed and do not overwrite existing data.
• administrative email; CPI administrator email is required if email notifications are enabled.
  This is required if error notifications are enabled.
• enableReprocessing - Enables reprocessing of failed contact data.
  This required configuring and deploying both IFlows for reprocessing.
• MailNotification - Email notifications can be enabled but require configuration of a CPI admin email and email template broadcast event in Emarsys.
  Both reprocessing ifflows need to be implemented.
• inboundMessage: keep the inbound message. The received message is used in case of error, so that the same messages can be sent for reprocessing.

wonderful script

log incoming message

• Writes the text of the received message.
• Message logging must be enabled by setting the Enable logging exchange property to true.
• Turn on message logging only when necessary. The message text is stored as an attachment in the message processing log (MPL).
• To test the integration, it is recommended to record the "trace" level. Trace logging level can be turned on for 10 minutes and tracks all message processing including headers and message properties.

XSLT Mapping

Filter address information

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

message mapping

Emarsys contact mapping

router

Validate PA

• Branch 1: contactless/customer
  Default branch, message processing ends
• Rama 2: valid function code
  Expression Type: XML
  condition: boolean(//contacts)
  If there is at least contact after message assignment for further processing. This avoids processing empty messages as not all trading partner short codes are processed.

router

remove empty

• Branch 1: leave blank
  Default branching, keep values ​​empty.
• Branch 2: remove empty
  Expression type: in XML
  Condition: ${property.removeEmpty} = 'yes'

If empty elements are removed, a delta update is sent to Emarsys without overwriting existing values.
If empty values ​​are left, existing values ​​will be overwritten.

XSLT Mapping

remove empty nodes

• Remove empty nodes with no values.

This process step is only performed if the Delete empty branch option is enabled.

wonderful script

Create WSSE Header

• The X-WSSE authentication header is generated.
• Custom script function called: XWSSEHeader
• The "securityArtifact" property is required to run this function.
  The securityArtifact property refers to the name of the security artifact that stores the Emarsys API user credentials

For more information on how to generate the WSSE header, see the Emarsys developer documentation.
https://dev.emarsys.com/docs/emarsys-api/ZG9jOjI0ODk5NzAx-autenticación

common divisor

Divisor-XML

XML to JSON converter

Converts the XML message to a JSON message

wonderful script

remover tmp_

custom function called: replaceTmp

Replaces all tmp_ values ​​for field IDs to match Emarsys field IDs.

wonderful script

registration announcement

See Groovy script "Log incoming message"

content modifier

Remove Header URI

• The SOAP sender stores the request URI path in the CamelHttpUri message header.
• The HTTP Receiver adapter replaces the address defined in the adapter with the header value "CamelHttpUri" if a value is present.
• The CamelHttpUri message header must be removed so as not to overwrite the recipient address.

Request answer

send contact

• HTTP-Senderadapter
• Receiver adapter configuration is static.
• ADDRESS:https://api.emarsys.net/api/v2/contacto/
• Consultor: create_if_not_exists=${property.create_if_not_exists}

wonderful script

validate answer

• Validate Emarsys' answer.
  Emarsys may respond with HTTP success status in the header but indicate an error in the response body.
• custom function called: validResponse

router

• Rama 1: HTTPCodeOK
  Expression type: in XML
• Condition: ${property.responseStatus} = 'OK'
  Rama 2: HTTPCodeNotOK
  Default branch, stop processing.

subprocesso local

error handling

• Error handling logs the error, decides whether messages should be saved for reprocessing, and whether to send an email notification.

subprocesso local

error handling

wonderful script

LogError

• Logs and writes the message body as an attachment to the message processing log
• custom function called: logHTTPError

subprocesso local

error handling

Router 1

• No reprocessing - default path
• Reprocessing: Reprocessing the message
  ${property.enableReprocessing} = 'true' e ${header.message_reprocessing} != 'true'
  enableReprocessing define este IFlow
• message_reprocessing is defined in iflow for reprocessing

subprocesso local

error handling

content modifier

Reset message payload

• Replace the body of the message with the body of the received message.
  ${property.incomingmessage}

subprocesso local

error handling

write data storage

Save the message to edit it again

• The reprocessing message is written to the SAP CPI datastore, where IFlow collects it for reprocessing.
• Datastore name: datastore name

subprocesso local

error handling

router

• No email: default
• Caminho: ${property.MailNotification} = 'true'
  Send an external event to Emarsys to trigger an email notification.

subprocesso local

error handling

wonderful script

definir host tmn

• The script sets the tenant management host from the runtime URL. This URL is used as a personalization attribute in the email to link directly to 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

subprocesso local

error handling

content modifier

define external event

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

The following external event message text is sent to Emarsys.
External event information can be accessed in email personalization.

{

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

"Data": {

"global": {

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

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

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

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

"Caught exception": "${property.CamelExceptionCaught}",

"expectionMessage": "${Exception.Message}",

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

}

}

}

subprocesso local

error handling

content modifier
Remove Header URI

• The CamelHttpUri is removed to avoid replacing the CamelHttpUri HTTP header on the receiver.

subprocesso local

error handling

wonderful script

Create WSSE Header

• The script sets the WSSE authentication header

subprocesso local

error handling

Rezeptor HTTP

• The error notification email is sent via a broadcast event. Streaming events do not require contacting Emarsys and are not tracked.
  ADDRESS:https://api.emarsys.net/api/v2/email/{Eventoid}/output
• The Event ID: Defined in Emarsys by assigning the trigger email and selecting the broadcast event as the email trigger.

time the start

• The startup timer schedules the IFlow to run and is configurable.
• IFlow must be scheduled outside of business hours
• IFlow should not run more than every minute.

data storage selection

Choose Contacts

• Datastore name: Define the name of the datastore from which failed messages will be saved.
• If the message is successfully processed, the entry is removed from the datastore.
• Messages are processed individually

Dissident

split single message

• Data Store Select is configured to collect only one datastore entry for each run.
• The splitter is added to ensure that only one message is processed at a time.
• Processing each datastore entry individually makes it easy to determine which message failed and which succeeded.
• If there are multiple errors, the select operation can be modified to collect multiple messages. If multiple entries are selected, adjustments to the error process may be required.

Filter

• The select operation adds additional elements to the retrieved message. The Filter step filters the selected message to match the original message
  Filterbedingung: //n0:BusinessPartnerSUITEBulkReplicateRequest

content modifier

• Header: message_reprocessing is sent with the value "true" (fixed value).
• This is used in business partner replication to avoid storing the message back in the datastore and creating duplicate entries.
• Exchange property: inboundMessage sets the new inbound message to the second reprocessing IFlow in case the message fails again.

exception process

Reset message text

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

write data storage

Write data Check data storage

• data store name
  Define datastore name for second IFlow for reprocessing

The order is completed and shipped

The order will be canceled

Order is in progress

The item is complete and shipped.

The order is created

article is created

The order is created

the item has been removed

Request is ignored

The item has been canceled

The order is created

the item has been removed

The order is created

The element is created with negative values.

Request is ignored

The article is in progress

article is ignored

article is ignored

Request is ignored

Station: S4OnPrem

Type: soap

• SOAP sender is configured
• Endereço: /SalesOrderBulkReplication_Out_OnPrem
• Processing Configuration: Robust
• Permission: user role
• User role: ESBMessaging.send
  The role must be assigned to the communication user used for authentication in the SAP BTP Cockpit.

content modifier

Set properties and headers

• Message headers and properties are defined.
• Exchange properties:
• File name: required. Defines the file name of the imported sales data
• administrative email; CPI administrator email is required if email notifications are enabled.
• MailNotification - Email notifications can be enabled but require configuration of a CPI admin email and email template broadcast event in Emarsys.

wonderful script

Register input payload

• Writes the text of the received message.
• Message logging must be enabled by setting the Enable logging exchange property to true.
• Turn on message logging only when necessary. The body of the message is stored as an attachment in the message processing log (MPL) and the storage size of attachments is limited in SAP Cloud Integration.
• To test the integration, it is recommended to record the "trace" level. The logging level can be turned on for 10 minutes and tracks all message processing, including headers and message properties.

common divisor

Divisor-XML

• The XML splitter splits the incoming message payload into individual messages so that the message map can validate each sales order business document.
• It is not necessary to process the sales order individually. Customer orders can be processed in batches.
• In this example, the sales order is processed individually. Assigning commercial documents requires that the customer's order DB be edited individually; otherwise, the complex structure of the database can lead to erroneous message transformations.

message mapping

Emarsys contact mapping

XSLT Mapping

delete items

• XSLT mapping removes sales order lines that should not be imported into Emarsys.
• The conditions for importing the customer order are defined in the IFlow description above and implemented in an XSLT script.
• All sales order items with item status "IN PROCESSING" are removed.
• All sales order lines with general status "COMPLETED" and line status "CANCELLED" are removed.
• All sales order lines with general status "CANCELLED" and line status "COMPLETED" are removed.
• Other options are possible to fix this.

To bring together

• The collect step gathers the shared items and combines them into a single message.

router

blank check

• Branch 1: empty
  Default branch, message processing ends
• Branch 2: not empty
  Expression Type: XML
  Condition: boolean(//sales order)
  If at least one sales order exists after assigning the message for further processing.

Filter

• The Collect step filters only the relevant items.
• The Gather step removed the parent nodes added in the previous steps
• XPath Expression: //Order
• Value type: notes

content modifier

add root

• The content modifier adds a root element to the XML.
• The root element is required in the XML for further processing and transformation.

XML to CSV Converter

• Convert XML text to CSV
• Path to source element in XSD: /salesorders/salesorder
• Include field names as headers: checked
• Include parent: disabled
• Include Attribute Values: Disabled

wonderful script

outgoing load log

• See nifty script "Register input payload"

content modifier

Emarsys Sales-API

• Defines the necessary headers and properties.
• Headers are predefined and should not be changed.
• Merchant ID: Required. Merchant ID can be retrieved from Emarsys in Predict data feeds.
• bearerToken - The bearer token that you store in a secure parameter in the CPI so that plain text is not displayed in the interface. The property refers to the name of the security parameter created in SAP CPI.

wonderful script

set permission

• The UDF retrieves the bearer token stored in the security parameter and generates the authorization header.

Rezeptor HTTP

Send sales data

• The HTTP receiver connects to the Emarsys Sales API.
• All values ​​except Merchant ID and Wait Time are preconfigured.
• Merchant ID and Timeout values ​​are managed as an external property.

router

• Rama 1: HTTPCodeOK
• Expression type: in XML
• Condition: ${property.responseStatus} = 'OK'
• Rama 2: HTTPCodeNotOK
  Default branch, stop processing.

wonderful script

logHTTPError

• Logs and writes the message body as an attachment to the message processing log
• custom function called: logHTTPError

subprocesso local

error handling

• Standard error handling: Log the error and decide whether to send an email notification.
• Error handling is the same for trade partner and sales order replication

{

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

"Data": {

"global": {

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

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

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

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

"Caught exception": "${property.CamelExceptionCaught}",

"expectionMessage": "${Exception.Message}",

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

}

}

}

wonderful script

Registry Error

• Stores the message payload as an attachment in the message processing log.

Router 1

• Branch 1: no processing (default)
• Industry 2: Reprocessing
  ${property.enableReprocessing} = 'true' e ${header.message_reprocessing} != 'true'

Message reprocessing branch

• The message body is reset as received and stored in the SAP Cloud Integration data store.
• The datastore write operation is defined to store the failed message.
  Entry visibility must be set to "Global".

router

• Branch 1: email, send email notification
• Branch 2: no email, no email notification
• Conditional expression: ${property.MailNotification} = 'true'

wonderful script

Definir host tmn

• The error message includes a link to the CPI Tenant Monitoring overview.
• In this step, the tenant management node is defined.
• Function called: defineTmnUrl

content modifier

define external event

• The body of the broadcast event request is defined.
• Available customization attributes:
• {{evento.adminEmail}}
  CPI admin email defined in IFlow configuration
• {{event.timestamp}}
  Error timestamp
• {{event.CPIHost}}
• SAP CPI Tenant Management Host
• {{event.CPIPath}}
  SAP CPI endpoint path
• {{event.catchException}}
• Caught exception message
• {{evento.expectionMessage}}
• exception message
• {{event.messageProcessingLogID}}
  SAP CPI MPL ID, used to look up the error message in the message processing log
• Required parameters for email notification should be defined based on relevant use cases.

content modifier

Remove Header URI

• Remove CamelHttpUri header to avoid overwriting target host URL
• Delete: $name=CamelHttpUri

wonderful script
Create WSSE Header

• Create the authentication header
• Function call: XWSSEHeader

request-response

send error message

• Configure Stream Event API Request
• ADDRESS:https://api.emarsys.net/api/v2/email/{{BroadcastEventId}}/broadcast
• Authentication: None (Authentication is defined by "Create WSSE Header" script)
• Request header: X-WSSE (allowed header)
• Response headers: * (allows all response headers)