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 SurveyMonkey surveys with SAP Hybris Marketing - Part 2/2

former_member247020
Active Participant
‎03-20-2018 6:52 PM

Introduction


Welcome to the blog post of the Expert Services Marketing Practice.

We are happy to share our experience with you around Marketing Integration, Analytics, and Business Technology.

  • Part 1

    • Overview

    • SurveyMonkey Configuration

    • SAP Hybris Marketing Configuration

    • SAP API Management - create API



  • Part 2

    • SAP Cloud Platform Integration Configuration

    • Create SAP Hybris Marketing Cloud IFlows

    • Summary




You want to see more? Click here

Background


SAP Hybris Marketing provides out-of-the-box functionality to integrate with 3rd party Survey tools.
For this simplified Integration Scenario, we have used SurveyMonkey for generating and maintaining surveys.

The described approach can be different depending on the connectivity options provided by the Survey tool you are using.

This Scenario is build using SAP Hybris Marketing Cloud with release 1711.

In this Blog Post,
we will walk through the technical setup on how to integrate SurveyMonkey with SAP Hybris Marketing Cloud. This is a concept IFlow and does not represent a real customer use case. This blog post describes the general procedure and approach how to integrate survey data with SAP Hybris Marketing.

The general approach and setup is described.

  • SAP Hybris Marketing Cloud (MKC)

    • Basic Communication Setup only



  • SAP Cloud Platform Integration (CPI)

    • IFlow design and configuration



  • SAP Cloud Platform API Management (APIM)

    • API creation



  • SurveyMonkey

    • Survey creation and management




 

SAP Cloud Platform Integration Configuration - Create the Survey on SAP Hybris Marketing



  • Get Survey Information from SurveyMonkey

  • Create Survey entry on SAP Hybris Marketing


Since we did get a couple of questions on using the HTTP Adapter to create the request message for SAP Hybris Marketing we are going to use the CPI HTTP adapter in this IFlow instead the Odata adapter.
When using the HTTP adapter you need to make sure that the XML message complies with the structure requested by the Odata Service. Further, you need to configure token handling yourself.

Create a new IFlow and configure a Run Once Timer Event to trigger the IFlow when the IFlow gets deployed.

First we need to add the mandatory properties to make the request to retrieve the information of the survey we have created on SurveyMonkey.

Remember, we have configured a private app, hence we only need to define the authorization header and define an additional property, what we can externalize to be available in the IFlow configuration, for the Survey ID. This can be done in a Content Modifier.

Define a Request-Reply Service Call and select the HTTP adapter with following address:
https://api.surveymonkey.com/v3/surveys/${property.SurveyID}/details

Define GET as operation and no Authentication.
When sending the request to SurveyMonkey, the SurveyMonkey API will respond with detailed survey information including the survey metadata but also questions and answers.



To use the graphical mapping we need to transform the JSON response to an XML formatted message.
Create an XML Schema for the source (SurveyMonkey Response) and the target (Hybris Marketing SurveySet) message.
Make sure to set the correct context when working with different message structures.

SAP Message Mapping Context




Value help









Type


RB - Radio Button


BC - Checkbox


DL - Dropdown List


FT - Free TE\ext


MX - Matrix


OE - Open Ended


DG - Demographic


DT - DateTime


 

Sub-type


VT - Vertical


HZ - Horizontal


MU - Menu


SL - Single


RT - Rating


RK - Ranking


ML - Multiple


NU - Numerical


ES - Essay


IN - International


US - Us


Depending to the XML Schema you used in the mapping you might need to transform the message before sending this to SAP Hybris Marketing.

You need to make two calls to SAP Hybris Marketing

  • Get Access Token

  • Create Survey


Configure a HTTP sender channel to SAP Hybris Marketing to retrieve an access token. Make sure to persist the message body before sending the request.
https://{host}:{port}/sap/opu/odata/sap/CUAN_SURVEY_IMPORT_SRV/
Header: x-csrf-token = Fetch
Operation: GET

Add the persisted message payload and configure another HTTP receiver. This time configure  a POST call to SAP Hybris Marketing. Define the Content-Type header as json or xml.
https://{host}:{port}/sap/opu/odata/sap/CUAN_SURVEY_IMPORT_SRV/SurveySet
Operation: POST

Create survey in SAP Hybris Marketing, Message payload example.


https://{host}:{port}/sap/opu/odata/sap/CUAN_SURVEY_IMPORT_SRV/SurveySet
(The shown example is shortened and is only an extract us the actual message payload)



{

  "SurveyId": "1111111111",

  "Provider": "SurveyMonkey",

  "Version": 1,

  "Name": "Market Research - Product Review - USB Rock Pet",

  "NickName": "",

  "AccountId": "1",

  "Category": "market_research",

  "Url": "https://www.surveymonkey.com/summary/abc123",

  "MarketingAreaId": "Global",

  "Language": "en",

  "IsSurveyAnonymous": false,

  "CreatedOn": "2018-02-22T15:02:00",

  "ModifiedOn": "2018-03-01T20:08:00",

  "ValidFrom": "2018-02-22T15:02:00",

  "ValidTo": "2018-12-22T15:02:00",

  "IsMultipleRespAllowed": true,

  "SurveyQuestionSet": [

    {

      "SubType": "VT",

      "Position": 1,

      "Type": "RB",

      "Language": "E",

      "SurveyId": "131069188",

      "Version": 1,

      "IsMandatory": false,

      "Text": "What is your first reaction to the product?",

      "Provider": "SurveyMonkey",

      "QuestionId": "264216339",

      "QuestionAnswerSet": [

        {

          "RowId": "1813880039",

          "RowPosition": 1,

          "RowText": "Very positive"

        },

        {

          "RowId": "1813880040",

          "RowPosition": 2,

          "RowText": "Somewhat positive"

        }

      ]

    },

    {

      "SubType": "VT",

      "Position": 1,

      "Type": "RB",

      "Language": "E",

      "SurveyId": "131069188",

      "Version": 1,

      "IsMandatory": false,

      "Text": "When you think about the product, do you think of it as something you need or dont need?",

      "Provider": "SurveyMonkey",

      "QuestionId": "264216342",

      "QuestionAnswerSet": [

        {

          "RowId": "1813880039",

          "RowPosition": 1,

          "RowText": "Definitely need"

        }

      ]

    }

  ]

}

 

SAP Cloud Platform Integration Configuration - Start the Survey



  • Receive message from SAP Hybris Marketing.

  • Create SurveyMonkey Contact List from SAP Hybris Marketing Target Group

  • Create / Update SAP Hybris Marketing Contact with SurveyMonkey Contact

  • Send E-Mail notification to the Campaign Manager to review and release the survey.


Note:

We took some extra effort to create a Contact List on SurveyMonkey and create a SurveyMonkey Contact in SAP Hybris Marketing Cloud.

You can also add the target group member from MKC directly the survey recipient list and assign the survey responses from the survey to the existing MKC contact with the Email address, assuming the Email address is unique (Email address and full name when Email is shareable).

Create a new IFlow to receive the Message from the SAP Hybris Marketing Open Channel.


Start with a very simple IFlow and test the connectivity between SAP Hybris Marketing and SAP Cloud Platform Integration.
You can test the connectivity from the Communication Arrangement or release a test campaign.
You can Log the Payload using the payload trace or use a GroovyScript to save the message payload and an attachment on the message monitoring.
Currently, the trace is enabled on the CPI WebUI but is displayed in the Eclispe tooling (current build is: 2.37.6).



With the Target Group received from SAP Hybris Marketing we can create a new Contact List for the survey.

Note:
For this scenario we are only considering target groups with less than 5k contacts. Larger target groups are split into different messages. To make sure all contacts are added to the correct contact list the existing contact lists must be polled from SurveyMonkey first and compared with the Campaign ID and Name from SAP Hybris Marketing. This can be implemented using CPI and the SurveyMonkey contact list API.

Request:
POST /v3/contact_lists HTTP/1.1

Host: api.surveymonkey.com

Authorization: bearer {access token}

Content-Type: application/json



{“name”: “USB Rock Pet Prduct Review Contacts”}



Response:

{

“href”: “https://api.surveymonkey.com/v3/contact_lists/101151818“,

“id”: “101151818”,

“name”: “USB Rock Pet Prduct Review Contacts”

}



 

After we created the SurveyMonkey Contact List, we can populate the contact list with the contacts we exported from the SAP Hybris Marketing Target Group.
We retrieve the persisted message we received from SAP Hybris Marketing and transform the message to the request message payload that needs to be send to SurveyMonkey to populate the Contact List.
We used the graphical message mapping since this is the easiest to maintain especially when you need refinements later in the configuration.



We used a small groovy script to extract the created Contact List Id from SurveyMonkey we like to add the contacts before we pull the entry from the data store.

Once you understood the message structure of both, the sender source and target, the mapping is very straightforward. Map the target field based on a condition on the AttributeId.
The c1 custom field is mapped with a script that pulls the campaign id we stored in a property before and returns this as the field value of the target field.

Before sending the Message body to SurveyMonkey we added a script to replace the name of the custom fields (see Note).
In the XML to JSON Converter we kept the default setting for most parts and only enables Suppress JSON Root Element (see the example request to SurveyMonkey).



Note:
We need to transform the message to XML in order to use the graphical Message Mapping. When converting the JSON to XML, XML validation fails because the crated XML message is not well-formatted. This formatting issue is caused by the name definitions of the SurveyMonkey custom fields.



As solution we changed the name of the custom fields in the Target XML Schema file to "c1" and "c2". Before sending the JSON request for bulk loading Contacts, we simply replace "c1" and "c2" to "1" and "2".

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

<root>

   <contacts>

      <element>

         <custom_fields>

            <c1>123</c1>

            <c2>456</c2>

         </custom_fields>

         <email>TomTest@saptrial.com</email>

         <first_name>Tom</first_name>

         <last_name>Test</last_name>

      </element>

   </contacts>

</root>

 

 

Example JSON:
{

	"contacts": [{

		"first_name": "Tom",

		"last_name": "Test",

		"email": "TomTest@saptrial.com",

		"custom_fields": {

			"1": "123",

			"2": "456"

		}

	}]

}

Add Contacts from the Target group to the SurveyMonkey Contact List.

Request:

{

	"contacts": [{

		"first_name": "Tom",

		"last_name": "Test",

		"email": "test@sap.com",

		"custom_fields": {

			"1": "SAP Outbound ID",

			"2": "Campaign ID"

		}

	},

	{

		"first_name": "John",

		"last_name": "Doe",

		"email": "test@surveymonkey.com",

		"custom_fields": {

			"1": "SAP Outbound ID",

			"2": "Campaign ID"

		}

	}]

}

Response:

{

    "succeeded": [

        {

            "status": "active",

            "first_name": "Tom",

            "last_name": "Test",

            "href": "https://api.surveymonkey.com/v3/contacts/123",

            "id": "123",

            "custom_fields": {

                "1": "SAP Outbound ID",

	"2": "Campaign ID"

            },

            "email": "test@sap.com"

        },

        {

            "status": "active",

            "first_name": "John",

            "last_name": "Doe",

            "href": "https://api.surveymonkey.com/v3/contacts/456",

            "id": "456",

            "custom_fields": {

                "1": "SAP Outbound ID",

	"2": "Campaign ID"

            },

            "email": "test@surveymonkey.com"

        }

    ],

    "invalid": [],

    "existing": []

}

 Before creating the Message Mapping, we define the Message Receiver first.

Select Odata as Adapter Type and open the Adapter specific tab.
In the connection details specify the service URL for the Odata Service. The service URL can be found in the Communication Arrangement on yMKT.
Define Authentication against the service.

In the processing details, define POST as operation and click on select. In the Query Editor select the Entity Contact Origin Data and operation POST. Enable Batch Processing and select the fields you like to use for creating the contact.

Click on OK.

The adapter automatically pulls the metadata file and creates an xsd file based on the selected fields. We’re going to use that xsd file in the Message Mapping.



SurveyMonkey provides the contact status and imported contact information in the response. With this response, we can create a contact on SAP Hybris Marketing cloud. In this example, we have created a new Contact Origin for the SurveyMonkey contact data.

Note:
We have decided to create a new contact origin since SurveyMonkey is considered as a new data source.
In our system we configured the Email address as a unique ID.
When the Email address is set to shareable in your system you can provide an additional id with Open Channel and populate this field with.

 



Now, we need to transform the response from surveyMonkey to the target message structure to import the successfully created contact to SAP Hybris Marketing.

Again, we are using the graphical mapping, hence we need to convert the JSON message to XML.
To use the JSON to XML converter, there must be one single root tag. Also the created XML message must be valid to be used in the Message Mapping. To ensure a valid XML message we replace the SurveyMonkey custom fields  “1” and “2” with “c1” and “c2”. Next we add a dummy root tag to the JSON and use the standard JSON to XML converter to convert the message to a valid XML to be used in the Message Mapping.

You could also use a script to transform the message. Using the graphical mapping is a personal preference for two simple reasons: it is a lot easier to explain to someone else and easier to maintain in case you need to make changes.

 


Now, we can send the created message to the receiver, in our case that’s SAP Hybris marketing Cloud, to create the SurveyMonkey Contacts. From there we check if the contacts are received and send a message to the Campaign Manager to review the campaign and further instructions.




We only created a simple E-Mail with simple text.


We can make sure on yMKT that the contacts are merged and have the SurveyMonkey Contact attached to the SurveyMonkey.

Note:
We have used the Email address as the contact ID.


SAP Cloud Platform Integration Configuration - Collect the Survey responses



  • Receive notification from SurveyMonkey with SAP API Management.

  • Create a survey response using the survey API


Test the API
https://api.sap.com/shell/discover/contentpackage/SAPS4HANAMarketingCloud/api/CUAN_SURVEY_IMPORT_SRV

When someone completed the survey, SurveyMonkey sends a notification to the defined webhook subscription URL, in our case SAP API Management. APIM forwards the message to CPI where we convert and transform into a valid SAP Hybris Marketing survey response.
	"event_datetime": "2018-03-01T16:32:39.185600+00:00",

	"resources": {

		"respondent_id": "672792XXXX",

		"recipient_id": "366874XXXX",

		"user_id": "11348XXXX",

		"collector_id": "17055XXXX",

		"survey_id": "13106XXXX"

	},

	"name": "Es Mkt Integration",

	"object_id": "672792XXXX",

	"filter_id": "13106XXXX",

	"event_id": "1000380XXXX",

	"object_type": "response",

	"filter_type": "survey",

	"event_type": "response_completed"

}

From the response we extract the values we need to make the following request to retrieve further information. This can be done with a simple Groovy script.


With the values saved in the exchange properties, we can prepare the request to the SurveyMonkey API.



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

import groovy.json.JsonSlurper;



def Message processData(Message message) {

// Body

    def body = message.getBody(String.class)

    def jsonSlurper = new JsonSlurper()

    def object = jsonSlurper.parseText(body)

    def RespondentId = object.resources.respondent_id

    def SurveyId = object.resources.survey_id



// exchange properties

    message.setProperty("RespondentId",RespondentId)

    message.setProperty("SurveyId",SurveyId)



    return message

}

Create a receiver channel with Adapter type HTTP.


In the Adapter specific tab define the address to the SurveyMonkey API as well as Mothod and Authentication.


https://api.surveymonkey.com/v3/surveys/${property.SurveyId}/responses/${property.RespondentId}




The reply from the SurveyMonkey API must be converted to a valid XML format to be used in the graphical Message Mapping.

Convert the JSON Response to XML similar what was done in the previous IFlow.

Configure the Odata Receiver for importing the survey response and pull the xsd file for the entity /SurveyResponseSet. Enable Batch processing and select the elements applicable for your scenario.

Refer to the documentation below for help on configuring the Survey Odata Service.

With the XML Schema file available for the source and target message, we can add the Message Mapping integration pattern to our IFlow and start mapping the source to the target message.

{

    "total_time": 15,

    "href": "https://api.surveymonkey.com/v3/surveys/131069188/responses/6727925111",

    "custom_variables": {},

    "ip_address": "11.111.111.111",

    "id": "6727925111",

    "logic_path": {},

    "date_modified": "2018-03-01T16:32:38+00:00",

    "response_status": "completed",

    "custom_value": "123",

    "analyze_url": "https://www.surveymonkey.com/analyze/browse/4522325?respondent_id=13",

    "page_path": [],

    "recipient_id": "3668749111",

    "collector_id": "170557111",

    "date_created": "2018-03-01T16:32:23+00:00",

    "survey_id": "131069111",

    "collection_mode": "default",

    "edit_url": "https://www.surveymonkey.com/r/?sm=123345364345",

    "metadata": {

        "contact": {

            "custom4": {

                "type": "string",

                "value": "456"

            },

            "first_name": {

                "type": "string",

                "value": "joey"

            },

            "last_name": {

                "type": "string",

                "value": "hir"

            },

            "email": {

                "type": "string",

                "value": "johannesh@test.com"

            },

            "custom1": {

                "type": "string",

                "value": "123"

            }

        },

        "respondent": {

            "language": {

                "type": "string",

                "value": "en"

            }

        }

    }

}

Create a new Message Mapping and add the XML Schema file created from the SurveyMonkey Response as Source Structue and the XML Schema from the Hybris Marketing from the Odata Service as Target Structure.

Complete the message mapping and test the Message Mapping.
An example to a request received on SAP Hybris Marketing is added below for review.



The survey responses are available in the contact profile and can be used in the segmentation.



Here an example of the generated $batch request and successful response.

Request
--batch

content-type: multipart/mixed; boundary=changeset



--changeset

content-type: application/http

content-transfer-encoding: binary



POST SurveyResponseSet HTTP/1.1

Accept: application/json

Content-Type: application/json



{

  "Provider":"SurveyMonkey",

  "ResponseId":"6728535000",

  "SurveyId":"131069188",

  "Version":1,

  "Id":"johannes.hirling@sap.com",

  "IdOrigin":"EMAIL",

  "IsResponseAnonymous":false,

  "ResponseUrl":"surveymonkey",

  "RespondedOn":"2018-03-08T00:00:00",

  "SurveyResponseSurveyResponseDetailSet":[

    {

      "QuestionId":"264216339",

      "ResponseIdRow":"1813880039"

    },

    {

      "QuestionId":"264216342",

      "ResponseIdRow":"1813880055"

    }

  ]

}



--changeset--

--batch--

 

Response
--DB0EECCC813887570B7F14AF4AAC773E0

Content-Type: multipart/mixed; boundary=DB0EECCC813887570B7F14AF4AAC773E1

Content-Length:      2093



--DB0EECCC813887570B7F14AF4AAC773E1

Content-Type: application/http

Content-Length: 1924

content-transfer-encoding: binary



HTTP/1.1 201 Created

Content-Type: application/json

Content-Length: 1626

location: https://{host}/sap/opu/odata/SAP/CUAN_SURVEY_IMPORT_SRV/SurveyResponseSet(Version=1,Provider='SurveyMonkey',ResponseId='6728111000',SurveyId='1310691111')

dataserviceversion: 2.0



{"d":{"__metadata":{"id":"..................}}}



--DB0EECCC813887570B7F14AF4AAC773E1--



--DB0EECCC813887570B7F14AF4AAC773E0--

 

Summary


The API provides an easy way to integrate 3rd party survey data with SAP Hybris Marketing. That data can be used in the segmentation or to trigger specific campaigns, for example an E-Mail thanking the responded for completing the survey.

The integration scenario and data depends on the survey tool you are using and need to be implemented on an individual basis. SurveyMonkey provides a set of APIs that cover all use cases described in this scenario. Of course, any extension need to be assessed and implemented.

This blog post provides a starting point on using the SAP Hybris Marketing Survey API for integrating your survey tool.

 

You want to see more articles from SAP Services? Click on the banner below.

Your SAP CX Services – Marketing Practice team.

3 Comments
Popular Blog Posts