CX Works

A single portal for curated, field-tested and SAP-verified expertise for your SAP C/4HANA suite. Whether it's a new implementation, adding new features, or getting additional value from an existing deployment, get it here, at CX Works.

Integrate SurveyMonkey Surveys with SAP Marketing Cloud (Part 1/2)


Integrate SurveyMonkey surveys with SAP Marketing Cloud


SAP Marketing Cloud provides out of the box functionality to integrate with third-party survey tools.

For our simplified integration scenario, we used SurveyMonkey for generating and maintaining surveys.

Depending on the connectivity options provided by the survey tool you are using, the approach can be different.

The scenario described in this article was built using SAP Marketing Cloud release 1711.

In this article, we will walk through the technical setup on how to integrate SurveyMonkey with SAP Marketing Cloud. Note: The integration flow (iFlow) described in this article does not represent a real customer use case.

This article (Part 1) focuses on the configuration of SurveyMonkey and the setup within SAP Marketing Cloud. The configuration of the SAP Cloud Platform Integration is covered in the next article, Part 2.

Table of Contents

Technical Configuration Overview

The following diagram illustrates the scenarios that will be covered in this article



SurveyMonkey Configuration

1. Create a SurveyMonkey App

Note:  We are using a private app.

  • Review the credentials and select the scope items used in your scenario. This can be changed any time. 

Once we create the app, we can create a new survey. 

  • Go to https://www.surveymonkey.com/ and login with your account.
  • Select My Surveys and create a new survey.
  • Go through the wizard and create a new survey.
  • In the Collect Responses tab, add a new email collector. You can create one from the wizard or through the API.



You’re all set.

  • Create SurveyMonkey app
  • Create a survey
  • Add collectors to the survey


We now have an active survey that is accessible for selected recipients.

Next step, we need to make sure that we are notified when someone completes the survey and provide this information to SAP Marketing Cloud.

To do so, we need to activate a webhook with a callback to receive a notification from SurveyMonkey.

SurveyMonkey provides an API to manage webhooks.

2. Create a SurveyMonkey Webhook

  • Create a new iFlow to create the SurveyMonkey webhook.


We created the following request. Alternatively, you can also use Postman to trigger the webhook creation and validation operations.


POST /v3/webhooks HTTP/1.1
Host: api.surveymonkey.com
Authorization: bearer {access token}
Content-Type: application/json
{
	"name": "{Webhook Name}",
	"event_type": "response_completed",
	"object_type": "survey",
	"object_ids": ["{survey ID}"],
	"subscription_url": "https://{SAP API Management API Proxy URL}"
}


We externalized the parameters to make the iFlow easy to configure for additional campaigns.



You should create an iFlow to create a SurveyMonkey email collector if you have not done so already. Setting up the iFlow is similar to creating the webhook except for the request and the API.

The collector request is needed to retrieve survey information when sending surveys to e-mail recipients.


POST /v3/surveys/131069188/collectors HTTP/1.1
Host: api.surveymonkey.com
Authorization: bearer dbOQpCLSgiGAgu4xPR8K8O6LOe4g-W.U0Od8qNwUkgoBkpAK6RWHMkCCIKsEDAdbl00XbL-zyyH.531r6VudYLYM3ZwrLJqMbbxne1NxzVE.4ifjdUJfvWb-b7BfNwtU
Content-Type: application/json
{
	"type":"email",
	"name": "My Collector"
}


Before sending the webhook creation request, we need to make sure that the subscription URL is available.

Since the notifications are sent without one of the supported authentication methods provided SAP Cloud Platform Integration (SAP CPI), we need to set up a new API to receive the webhook validation request and the notification.

As per the diagram below, we need to create the following:

  • API on SAP API Management (SAP APIM) to receive messages from SurveyMonkey
  • iFlow on SAP Cloud Platform Integration (SAP CPI) as target URL from SAP API Management


3. Create an API on SAP API Management

To create an API, we log onto the SAP API Management API portal.

In this example, we are using an SAP API Management Trial Account on the SAP Cloud Platform Trial.



You can create a trial account for SAP Cloud Platform Integration here: https://account.hanatrial.ondemand.com/

SAP API Management is available in the service tab on your SAP Cloud Platform account.

For additional information, see Free Trial of SAP API Management on HANA Cloud Platform is available now!.

Go to Develop and create a new API.


4. Create an API

API Provider: None
URL: {SAP Cloud Platform Integration HTTP Endpoint}

Name: {API Name}
Title: {API Title}
Description: {API description}
Host Alias: {your APIM account}
API Base URL: {SAP API Management API Proxy URL}
Service Type: REST



  • Go to the Resources tab and define a new resource.
  • Define operations that the API allows.

For this API, we need to at least enable the HEAD and POST on the created resource.



Next, we need to enable notification forwarding to the SAP CPI. Then, send the expected responses back to SurveyMonkey. We accomplish this by creating policies.

First, we create the response for the ping from SurveyMonkey.

When creating a webhook, SurveyMonkey validates the subscription URL by sending a ping to the subscription URL and expects an HTTP 200 response.

Then, we enable the forwarding of the inbound request in SAP APIM to SAP CPI, by simply adding an authorization header.

We do not cover API security measures in this article.

Screenshot above: Sending a 200 response to SurveyMonkey for verified subscription URL.


  • Add a Raise Fault policy to the inbound PreFlow.
  • Make sure the Raise Fault policy is only executed when the correct resource is called and the verb equals HEAD.

For more information, go to Webhooks.


Condition String: (proxy.pathsuffix MatchesPath "/notification" OR proxy.pathsuffix MatchesPath "/notification/**" OR proxy.pathsuffix MatchesPath "/notification(**") AND request.verb = "HEAD"
<!-- can be used to create custom messages in case of an error condition -->
<RaiseFault async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
	<!-- Defines the response message returned to the requesting client -->
	<FaultResponse>
		<Set>
			<!-- Sets or overwrites HTTP headers in the respone message -->
			<Headers/>
			<Payload contentType="text/plain"> </Payload> <StatusCode>200</StatusCode>
			<!-- sets the reason phrase of the response -->
			<ReasonPhrase>Successful</ReasonPhrase>
		</Set>
	</FaultResponse>
	<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</RaiseFault>


  • Enable basic authentication with the created SAP CPI HTTP enpoint. 
  • Then, add an authorization header with the user credentials. This is OK for a test environment but not recommended for a production environment.

For SurveyMonkey webhook documentation, go to Webhooks.


<!-- This policy can be used to create or modify the standard HTTP request and response messages -->
<AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
 <!-- Sets a new value to the existing parameter -->
	<Set>
	    <Headers>
	        <Header name="Authorization">Basic {Base 64 encoded Username:Password}</Header>
	    </Headers>
	</Set>
	<IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
	<AssignTo createNew="false" transport="http" type="request"></AssignTo>
</AssignMessage>


  • Save and deploy the API.

5. Create a Receiver iFlow on SAP Cloud Platform Integration

From the SAP APIM, we are referring to a target endpoint on the SAP CPI. That endpoint is not created yet.

  • Log onto the SAP Cloud Platform Integration and create a new iFlow.

We start with a simple iFlow to receive the inbound message and will refine the iFlow later.

This iFlow will be used to receive SurveyMonkey notification once someone completes the survey.


  • Configure an HTTP sender channel and define an address path.

The HTTP endpoint, created when deploying the iFlow, is constructed in the following format: https:// {CPI Worker Node URL}/http{Address Path}

  • Set authorization to User Role and disable cross-site request forgery (CSRF) Protected. Enabling the CSRF Protection adds the validation of a CSRF token. In this example, we kept this as simple as possible.



After receiving the message, we add a router to route the inbound HEAD request to an end message event. We do this to avoid processing empty messages. This is only mandatory when connecting directly to SAP CPI with a "HEAD" request. In our scenario, we do not send "HEAD" requests directly. To avoid "HEAD" requests, we need to add the following condition: 


Condition Expression: ${header.CamelHttpMethod}  = ‘HEAD’

Then, we add an additional message log script to log the payload. Although this does not have any effect on the functionality of the iFlow , it still needs to be used with care.

SAP CPI limits the use of attachments per day. Writing too many attachments increases the chance of exceeding the size limitation per day.

  • When all the configurations are done, save and deploy the iFlow.
  • Run an initial test to validate if the creation of the webhook works and if a message is received on SAP APIM and SAP CPI.

SurveyMonkey

  • SurveyMonkey Private App
  • SurveyMonkey Survey

SAP API Management

  • API to receive HTTP request from SurveyMonkey

SAP Cloud Platform Integration

  • Webhook creation iFlow
  • Notification iFlow

Your integration scenario is now set up to register a webhook for your created survey on SurveyMonkey and to receive notifications.


Configure SAP Marketing Cloud

SAP Marketing Cloud (MKC) provides functionalities to integrate with third-party survey data.

In this article, we described the basic configuration steps. These configuration steps are also described in the help documentation on SAP MARKETING CLOUD.

Please refer to the official documentation for more detailed information: Integrating SurveySurvey OData API.

  • Launch the Manage Your Solution App. 
  • Then, go to Configure Your Solution and select Manage Integration Content.
  • Add a new Interaction Channel survey with the Communication Medium set to WEB and the Interaction Type set to SURVEY_RESPONSE.

For this article, we decided to use a different approach on publishing the survey.

We will configure the Open Channel to populate the SurveyMonkey contact list and distribute the survey email notifications from SurveyMonkey. We will be collecting the survey responses and importing them to the SAP Marketing Cloud using the survey API.

6. Define Custom Logic

  • Define a custom logic with the mandatory extension.

Business Context: Marketing: Campaign
Definition Description: (1) Open Channel: Define Implementations
Implementation Description: {Custom Logic Name}

  • Define an implementation ID in the default code.


  • Create a new communication system for the SurveyMonkey integration scenario.

System ID: {Define a System ID}
System Name: {Define a System Name}
Host Name: {Host name of the SAP Cloud Platform Worker Node (Runtime)}

  • Define a user for inbound communication used by SAP  CPI t o connect to MKC.
  • Define a user used for outbound communication. The user must exist for the SAP CPI tenant and must be assigned to the ESBMessaging.send role.
  • Create Open Channel Communication Arrangement and use the communication scenario SAP_COM_0049.
  • Select the Communication System created from the previous step.
  • Add the implementation ID defined in the custom logic and select the defined outbound communication user.
  • In Outbound Services, deactivate the pre-processing. 
  • The iFlow is already deployed. Check the connectivity from the Communication Arrangement.

7. Create an Export Definition

  • Go to the Export Definition app and create a new Export Definition.

Definition: {Your Export Definition Name}
Usage: Open Channel
Segmentation Profile: Use the Segmentation profile you want to use for your Export Definition. In our example, we used All Consumers.
Export Profile: File Export

  • Select the field that needs to be exported with the Open Channel.


Now, we need to create a new campaign to trigger an outbound message from SAP Marketing Cloud.

  • Open the Segmentation Modeling app and make sure you’re using the right segmentation profile. 
  • Create a consumer segment that you want to target with your survey.

Note: For product reviews, it would make sense to have consumers reviewing the products they bought in the last couple of weeks. Unfortunately, the system we used for our example, did not have any SAP Commerce Cloud Data integrated.



  • Create a new target group and then perform a quick review. 
  • Release the target group that will be used in the campaign execution. 
  • Make sure your target group is in a released status.



  • Once done reviewing the target group, open the campaigns app and create a new campaign.
  • Create a new Blank Campaign:

Name: {your Campaign Name}
Category: Automated Campaign
Marketing Area: Global (if not configured otherwise)
Target Group: Select the target group we created and released.

  • In the Campaign Automation, select a new action and then select the Open Channel implementation you created.
  • In the Open Channel action, select the created export definition and click done.
  • Review your campaign settings and release the campaign.



The deployed iFlow is pretty basic and is only able to receive and log messages (without further processing). This enables you to review the fields available from SAP Marketing Cloud.

If you didn’t create an i Flow for receiving messages from SAP Marketing Cloud yet, the campaign will throw an error. If this occurs, you can restart the campaign once the i Flow is available.

Every target group member holds the information of the field we selected in the Export Definition.

With this message provided by MKC, we need to transform this message and to form requests that the SurveyMonkey APIs understand.


{
	"d": {
		"Campaign": {
			"CampaignId": "0000000498",
			"Name": "SurveyMonkey 2018 0",
			"MarketingAreaId": "CXXGLOBAL",
			"SegmentationObject": "SAP_CE_CONTACT_ENGAGEMENT",
			"ImplementationId": "ZOC_SURVEYMONKEY_OC"
		},
		"PackageId": 1,
		"ExecutionStartDateTime": "2018-02-23T22:38:51Z",
		"ExecutionRunKey": "8D88691FE6421EE8869D4910DB29995D",
		"CampaignTargetGroupMembers": [{
			"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX",
			"PackageId": 1,
			"ExecutionRunKey": "8D88691FE6421EE8869D4910DB29995D",
			"TargetGroupMemberAttributeData": [{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-SMTP_ADDR",
				"Value": "acbdef@saptrial.com",
				"EdmTypeId": "Edm.String",
				"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-NAME_LAST",
				"Value": "def",
				"EdmTypeId": "Edm.String",
				"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-NAME_FIRST",
				"Value": "abc",
				"EdmTypeId": "Edm.String",
				"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-IC_ID_ORIGIN",
				"Value": "EMAIL,PHONE",
				"EdmTypeId": "Edm.String",
				"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-IC_ID",
				"Value": "abcdef@saptrial.com,+123123",
				"EdmTypeId": "Edm.String",
				"OutboundId": "E5F5000F3212AA7F40BA8C7C838B3XXXXXXXXXX"
			}]
		},
		{
			"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX",
			"PackageId": 1,
			"ExecutionRunKey": "8D88691FE6421EE8869D4910DB29995D",
			"TargetGroupMemberAttributeData": [{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-SMTP_ADDR",
				"Value": "tomtest@saptrial.com",
				"EdmTypeId": "Edm.String",
				"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-NAME_LAST",
				"Value": "test",
				"EdmTypeId": "Edm.String",
				"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-NAME_FIRST",
				"Value": "tom",
				"EdmTypeId": "Edm.String",
				"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-IC_ID_ORIGIN",
				"Value": "EMAIL,PHONE",
				"EdmTypeId": "Edm.String",
				"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX"
			},
			{
				"AttributeId": "DA-SAP_CE_IC_CONTACT-IC_ID",
				"Value": "tomtest@saptrial.com,+123456789",
				"EdmTypeId": "Edm.String",
				"OutboundId": "10D5856A4F25D16A29DE1B84AE8XXXXXXXXXXXX"
			}]
		}]
	}
}


To create a new contact from the SurveyMonkey contact, we need to configure a new Communication Arrangement. We are using the Odata APIs for contacts released with 1708.

  • Create a new Communication Arrangement in the Communication Arrangement app. In our example, our scenario ID is SAP_COM_0207.

To review the API documentation, go to Contacts.



Since we are connecting a new data source, we’ll define a new Contact Origin for SurveyMonkey.

  • Open the Manage Your Solution app on SAP Marketing Cloud and add a new Contact Origin.

Contact Origin: SURVEYMONKEY_ID

We also add two custom fields we can use later in the segmentation.

Campaign ID
YY1_SM_CampaignID_MPS
Business Context: Marketing: Contact
Length: 10
Uis and Reports: Marketing: Contact API
Odata APIs: Marketing Data Import

OutboundID
YY1_OutboundID_MPS
Business Context: Marketing: Contact
Length: 10
Uis and Reports: Marketing: Contact API
Odata APIs: Marketing Data Import


Conclusion

In this article, you learned how to get started with the integration of SurveyMonkey surveys with SAP Marketing Cloud. This article focused on the configuration within SurveyMonkey and the setup of the integration within SAP Marketing Cloud. In Part 2 , you will learn how to configure and set up the iFlow on SAP Cloud Platform Integration.