This blog post of how to connect any text message service provider to SAP Marketing Cloud, consists of 2 chapter:

1. SMS Send Scenario
2. Get Bounces Scenario

This document describes step-by step how to connect a text message service provider of choice to SAP Marketing Cloud.

To connect a custom text message service provider to SAP Marketing Cloud via the newly implemented generic text message adapter, it is necessary to use a middleware that transforms the standardised HTTP output of SAP Marketing Cloud to the custom service provider’s individual API specification. Since SCP is the standard integration tool for SAP Marketing Cloud, is has been used to create an example that illustrates how to setup an integration project to connect the ESP SAP Digital Interconnect.

Within this example, the SCP has been configured to rework HTTP requests from the generic text message adapter of SAP Marketing Cloud to match the specification of SAP Digital Interconnect’s API. At the same time, the SCP processes the response from SAP Digital Interconnect and transforms it to the specific shape required by the generic text message adapter to perform subsequent logic.

This document describes in detail the SCP Integration Flows for sending text messages and retrieving bounces from SAP Digital Interconnect via the generic text message adapter of SAP Marketing Cloud.

Prerequisite:
Communication System and Communication Arrangement Scenario ID SAP_COM_0258 Setting up a Generic SMS Service Provider is maintained.

Details are available in application help Setting up a Generic Text MessageService Provider

Open APP Communication Systems and maintain system id, name, Host Name and User to connect to SAP Cloud Platform system:

Open App Communication Arrangements and maintain Scenario ID SAP_COM_0258 Setting up a Generic SMS Service Provider.

The path for outbound service could be /http/sapmc_sms/ as it is described in section
Configuration of Inbound- and Outbound connections.

Please consider your onwn path.

Maintain Integration Flow on SCP for Text Message Send Scenario

The following steps must be done to transforms the standardised HTTP output of SAP Marketing Cloud to the custom Text Messages Service Provider’s individual API specification:

Transformation Overview

The requests and responses are transformed by the iFlow as follows:

Send Sms Request

Send Sms Response

Integration Flow

General Structure of iFlow:

In the diagram below, the general structure of a send Sms SCP iFlow is displayed. The iFlow acts as translator between the SAP Marketing Cloud System and the connected Sms Service Provider. The SAP Marketing Cloud System sends a HTTPS POST request to the endpoint /hybris_sms/send of the SCP with the parameters as described above. The iFlow transforms the request in a HTTP POST request with the parameters according to the interface definition. The response of the Sms Service Provider is also converted back into the expected format of the SAP Marketing Cloud System. For arising errors, the iFlow contains an exception sub process, that parses the error message and sends it to the SAP Marketing Cloud System in the right format, which is also described in the interface definition.

The following sections explain the different transformation steps of the send Message iFlow in more detail.

Configuration of Inbound- and Outbound connections

The send Message iFlow is connected to the SAP Marketing Cloud System and to the Sms Service Provider via the following two connectors.

Defining the SCP endpoint

The iFlow can be connected to the SAP Marketing Cloud System using a control with type Sender. The endpoint URL of a generic iFlow on SCP is defined by: <SCP Tenant iFlow URL>/<used protocol>/<defined endpoint>

While the <SCP Tenant iFlow URL> is always fixed for a SCP Tenant, the <used protocol> and <defined endpoint> can be configured directly within the iFlow. To perform this configuration, the connector starting from Sender must be double clicked:

In the next window, the Adapter Type can be defined on the right side of the General Tab, while the endpoint settings are made in the Adapter Specific Tab under Request Processing. The configuration for our send mail scenario is shown below:

With this configuration, the complete endpoint URL depending on the used SCP Tenant reads as: <SCP Tenant iFlow URL>/http/hybris_sms/send. After saving and deploying the configuration, a GET request to the specified URL should return with status 200.

Establishing connection to Sms Service Provider

The Sms Service Provider can be connected to the iFlow using a control with type Receiver. Similarly, as above, the connection settings for outgoing calls from SCP to any endpoint can be defined by double clicking the Receiver node:

Here the connection settings can be maintained in the same way as for inbound connections within the tabs General and Adapter Specific. The adapter configuration used in our send message scenario is shown below:

Complete the Address information by your account information.

Redefinition of the input parameters

In the following, the different controls are discussed that are needed for the transformation of the SAP Marketing Cloud to the Sms Service Provider request structure.

Send Sms Start

Control Type: Start Message

This control represents the starting point of the iFlow.

Add root source

Control Type: Content Modifier

Select the control “Add Root Source” and take a look at the properties view. There, the body of the incoming request is encapsulated by a “root”-tag. This is needed because the JSON to XML Converter, which is used later on, requires to have only one root attribute (see Developper’s Guide: Managing Integration Content, Chapter 2.5.3.7.1.1 Conversion Rules for JSON to XML Conversion).

JSON to XML Converter

Control Type: Converter

Note, that we need to convert the json body to xml for the further processing. In the next transformation step, we use a content modifier control, which easily can extract the properties of xml bodies

Extract Properties

Control Type: Content Modifier

This transformation step has two tasks:

1.It creates the properties that are needed for building the request to the Sms Service Provider. The properties are defined as XPath variables that link to the properties of the original input request.

2.It sets the content type of the new request for the Sms Service Provider to html.

Note: It is necessary always to use converters and not to create the body as json object directly. This is, because the values of the properties are still in an xml format and need to be converted back to a json format before they can be used in a json file.

Encode Body

Control Type: Script

In this step, the line breaks are converted to the correct format.

import com.sap.gateway.ip.core.customdev.util.Message;

def Message encodeBody(Message message) {
    String bodyText = new String(message.getProperty("bodyContentPlainText"));
    bodyText = bodyText.replace("\\r", "<CR>").replace("\\n", "<LF>");
    bodyText = bodyText.getBytes("UTF-8").encodeBase64().toString();
    message.setProperty("bodyContentPlainText", bodyText);

    return message;
}

Create Body

Control Type: Content Modifier

The SplitText property is needed, to enable long text messages at SAP Digital Interconnect. The AckReplyAddress is the service address to which SAP Digital Interconnect shall send the bounces. To enable these acknowledgements at SAP Digital interconnect, the AckType needs to be set to MESSAGE and the MobileNotification flag needs to be set.

Reqeust-Reply

Control Type: Service Call

This control is responsible for…

1. sending the send message POST request to the Sms Service Provider via the defined endpoint as described in section Establishing connection to Sms Service Provider and
2. retrieving the answer of the request from the Sms Service Provider.

Set Response

Control Type: Script

import com.sap.gateway.ip.core.customdev.util.Message;

def processSmsResponseMessage(Message message) {

    def body = message.getBody(java.lang.String);
    def messageId = body.split('ORDERID=')[1].split('<br>')[0];
    message.setProperty("messageId", messageId + '');

    return message;
}

In this step, the message id is extracted.

Create Body

Control Type: Content Modifier

The response content type is set to json and new response message body, which will be sent to the SAP Marketing Cloud System later, is created using the abstracted message id.

Note:
SAP Marketing expects, that the messagId is unique, which is send with the answer of text message service provider.

Set Status

Control Type: Script

import com.sap.gateway.ip.core.customdev.util.Message;

def processStatus(Message message) {
    def statusCode = message.getHeaders().get("CamelHttpResponseCode").toInteger();
    if( statusCode == 200){
        message.setHeader("CamelHttpResponseCode", 202);
        message.setHeader("CamelHttpResponseText", 'Accepted'); 
    }

    return message;
}

Because the status code of the SAP Digital Interconnect response is always 200 in the success case, the code and its text needs to be changed to the code 202, which is the expected one of the SAP Marketing Cloud system.

XML to JSON Converter

Control Type: Converter

Send Mail End

Control Type: End Message

This control represents the success end point of the iFlow. The answer of the request will be sent now to the SAP Marketing Cloud System.

The Exception Sub Process

The exception sub process is the same as already documented in ESP Adapter – Exception Subprocess.

Logging

The logging concept is the same as for the Email service provider and can be looked up in ESP Adapter – Logger Controls.

Postman Collection

Headers: Content-Type: application/json

Next Chapter:

2. Get Bounces Scenario