1 Introduction
SAP Hybris Marketing provides central access for all contact/ customer-related information. This tutorial shows how to enable SAP Hybris Marketing with own data. This includes data upload, segmentation capabilities, etc.
All information are explained with a small example from the travel industry. The company has an SAP ERP system where customer master data and bookings are saved. Information about planes and flight schedules are provided by third party systems. As well, there is an airline system that provides check-in information.
1.1 Contacts
A contact is a natural person that interacts with a company. Contact data are collected and merged from several sources into the master data tables within SAP Hybris Marketing.
The base CDS view for contact master data is
I_MKT_CONTACT. You can have a look at the attributes of the CDS view by opening the app "View Browser" and choosing the CDS View I_MKT_CONTACT.
For each contact that is uploaded, the source system and source key are stored in the database as so called facets:
Field ID_ORIGIN in the table CUAND_CE_IC_FCET is the qualifier for the source system, and field ID contains the key that the contact has in the source system. In case of an SAP ERP system, the customer number would be written into the field ID.
SAP Hybris Marketing is able to distinguish between prospects, contacts and consumers to define the business relationship of a contact to your company. Therefore, the contact in the CDS View I_MKT_CONTACT contains the fields IsContactPerson and IsConsumer. A prospect is a natural person that some time in future can be important in interaction with a company (B2B process) or might generate sales revenue (B2C process). A contact, having set the field IsContactPerson to
‘X’, is a natural person that my company interacts with in a B2B process. A consumer, having set the field IsConsumer, is a natural person that generates sales revenue in a B2C process. A person can be a contact and consumer at the same time.
In addition to the business relationship, there is also the validation status. It indicates the level of trustworthiness of information about a contact. That is to which extent the information about a contact is valid. If a contact clicked an item on your Web site, the validation status is low and the contact is unknown. By default, if a contact filled out a form on your Web site, entering name and address, the contact is self-identified. If a contact clicked on a link in an email that you have sent after the contact has registered on your Web site, the contact is verified, as the email address is validated. If a contact is in your customer database, the contact is a business partner.
1.2 Interactions
Interactions are communication and information exchange of any sort between contact and your company, such as emails, sales documents or posts written in social networks.
The base CDS view for interaction data in SAP Hybris Marketing is
I_MKT_INTERACTION. The base attributes of an interaction are: INTERACTION, INTERACTIONCONTACTORIGIN, INTERACTIONCONTACTID, COMMUNICATIONMEDIUM, INTERACTIONTYPE and INTERACTIONTIMESTAMPUTC. In case of a check-in event the CDS view would return the following values:
2 Data Integration
SAP Hybris Marketing offers OData Services and CSV Uploads for data integration. The OData Services can be used to replicate data with any middleware tool, e.g. SAP Cloud Platform Integration Service, from a source system to the SAP Hybris Marketing system.
Travel Example
The customer master data is stored in table SCUSTOM and the bookings are stored in table SBOOK in the SAP ERP system. The data is exposed via iDocs for replication to external systems. An iFlow in the SAP Cloud Platform Integration Service will be used to map the iDoc data to an OData service interface of SAP Hybris Marketing.
The plane information and flight schedules, which originate in a 3rd party system, will also be replication with SAP Cloud Platform Integration service.
2.1 Integration of Contact Master Data
2.1.1 Prerequisite
Data Model Enhancement of Contact Master Data
SAP Hybris Marketing offers data model extensibility like custom fields, custom business objects and a lot more. You can add custom fields to business contexts in the app "Custom Fields and Logic". For the contact there are two business contexts, the business context "Marketing: Contact" and the business context "Marketing: Contact and Corporate Account".
Enhancement Options for Contact Master Data Upload
During the upload on contacts no matter what import tool is used the Enhancement Option (formally known as Business Add-In)
Update Interaction Contact is always executed. T
his enhancement option is used to enhance an existing contact or to create a new contact based on the data of newly imported contacts. You find available enhancement options also in the app "Custom Fields and Logic" for the respective business context.
Travel Example
The travel company does not only care about where a traveler lives right now but is also interested what nationality the contact has. Therefore the contact master is enhanced with an attribute "Nationality" of type code list:
Custom fields need to be enabled for usage in the application. In order to load the data, the field is enabled for the contact API service. For usage in the contact factsheet, the custom field is enabled for the Marketing Common Service:
As all travelers are business partners to the travel company, they should get the validation status 30. Therefore an enhancement implementation is created:
2.1.1 Import using CSV Upload
Contacts can be uploaded into SAP Hybris Marketing in CSV text format (code page UTF-8) by using the app
Import Data. The upload accepts commas, semicolons and tabulators as separators.
Structure
For the upload, the CSV file consists of the following elements:
- Optional: Comment rows starting with * at the beginning of the CSV file.
- Mandatory: Header row containing the attribute names.
Only the required attributes must be contained in the header row and they can be arranged freely.
Checks During Upload
During the CSV upload, the SAP Hybris Marketing performs the following format checks and conversions:
- Date values: The SAP date format (YYYYMMDD) and the date format specified in the user profile are allowed.
- Integer values: Integer values with or without separators are allowed, for example 1.317.208.
- Timestamp values: The SAP date, SAP date & time (YYYYMMDDhhmmss), or the time stamp long (YYYYMMDDhhmmss,aaaaaaa) values are allowed with or without separators.
- Email values are allowed in the following format: {name}@{domain}
2.1.2 Import using OData Service
Contacts can be imported into SAP Hybris Marketing using the OData service
API_MKT_CONTACT_SRV. The service is part of the communication scenario SAP_COM_0207. You will have to setup a communication arrangement for this scenario to create a communication user with the required authorization.
Structure
The OData service contains an entity type
Contact and an entity type
ContactOriginData. The entity type
Contact represents the contact that is created by SAP Hybris Marketing out of the different contact information from various system uploaded to the system. Therefore only the GET method is available on this entity type. To upload contact data you have to use the entity type
ContactOriginData. The PUT method enables you to directly upload new contact data as well as update existing contact data. The properties ContactOrigin, ContactID and OriginDataLastChgUTCDateTime are required for a successful upload.
Call of OData Service
The following code shows an example how to call the Odata Service with JSON format in order to create and update contacts. As bulk processing increases performance, the $batch implementation is used. The URL called is
https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/
API_MKT_CONTACT_SRV/$batch.
--batch_e0b5-4b67-81dc
content-type: multipart/mixed; boundary=changeset_ba95-fe80-fa44
--changeset_ba95-fe80-fa44
content-type: application/http
PUT ContactOriginData(ContactOrigin='SAP_ERP_BUPA',ContactID='3') HTTP/1.1
Content-Type: application/json
{
"ContactOrigin" : "SAP_ERP_BUPA",
"ContactID" : "3",
"OriginDataLastChgUTCDateTime":"2017-10-20T14:04:00.0000000",
"IsContactPerson" : true,
"FullName" : "Hans Bullinger",
"StreetName" : "Veilchenstraße",
"AddressHouseNumber" : "12",
"ContactPostalCode" : "69119",
"CityName" : "Heidelberg",
"Country" : "DE",
"YY1_Nationality_MPS" : "DE",
"PhoneNumber" : "02099-44591",
"EmailAddress" : "Hansi@Bulli.de"
}
--changeset_ba95-fe80-fa44
content-type: application/http
PUT ContactOriginData(ContactOrigin='SAP_ERP_BUPA',ContactID='4') HTTP/1.1
Content-Type: application/json
{
"ContactOrigin" : "SAP_ERP_BUPA",
"ContactID" : "4",
"OriginDataLastChgUTCDateTime":"2017-10-20T14:00:00.0000000",
"IsContactPerson" : true,
"FullName" : "Staerck",
"StreetName" : "Kaiserstr.",
"AddressHouseNumber" : "55",
"ContactPostalCode" : "69115",
"CityName" : "Heidelberg",
"Country" : "DE",
"YY1_Nationality_MPS" : "DE",
"EmailAddress" : "Farbenblind@gmx.de"
}
--changeset_ba95-fe80-fa44--
--batch_e0b5-4b67-81dc--
Success Message and Error Handling
After a successful data upload, the system returns a 202 HTTP status code for the whole batch request. You need to ensure that the actual HTTP status codes for the individual calls inside the batch return 201. The upload is queued in the SAP Hybris Marketing system and you can check the actual upload status in the app "Import Monitor".
2.2 Integration of Interaction Data
2.1.1 Prerequisite
Data Model Enhancement of Interaction Data
For the interaction the business context "Marketing: Interaction" has to be used to enhance the data model with custom fields.
Enhancement Implementation for Contact Master Data Upload
During the upload on interactions no matter what import tool is used the Enhancement option
Revise Interaction Data Before Import is always executed. T
his enhancement option allows to adapt the complete list of interactions that are to be created, e.g. to assign interactions to a campaign.
Setup of Communication Media, Interaction Types, Interaction Channel
Each interaction needs to be assigned to a communication medium and an interaction type. As on the User Interface the interactions are grouped in interaction channels, the communication media and interaction types need to be assigned to an interaction channel. A communication medium can be nearly any medium used for communication, such as email, phone, a data processing system, or even paper. An interaction type is any interaction that a contact can use or do to interfere with a company. Interaction types could be Web site visits, Web site downloads and Web site registrations. An interaction channel is used to analyze the interactions that a contact has with a company. An example are complaints. They should be grouped together no matter which communication medium was used to file the complaint. The interaction channel appears, for example, in the contact profile. Communication Media, Interaction Types and Interaction Channel are setup as configurations in the app "Manage Your Solution" in the configuration step "Manage Interaction Content".
Travel Example
The travel company is interested in the time when the traveler checked in. Therefore the interaction is enhanced with an attribute "Check In Time". The field is enabled for the usage in the Marketing Interaction API.
For the travel example there is no need to implement an enhancement option.
As communication media SAP has already delivered WEB. This one is used for the check in. As interaction type CHECK_IN is defined. As a check in is done by a contact the direction is inbound. As interaction channel again the SAP delivered WEB entry is reused. The communication media and interaction type are added to this channel.
2.2.1 Import using CSV Upload
Interactions can be uploaded into SAP Hybris Marketing in CSV text format (code page UTF-8) by using the app
Import Data. The upload accepts commas, semicolons and tabulators as separators.
Structure
Only the required attributes must be contained in the header row and they can be arranged freely.
Checks During Upload
During the CSV upload, the SAP Hybris Marketing performs the following format checks and conversions:
- Date values: The SAP date format (YYYYMMDD) and the date format specified in the user profile are allowed.
- Integer values: Integer values with or without separators are allowed, for example 1.317.208.
- Timestamp values: The SAP date, SAP date & time (YYYYMMDDhhmmss), or the time stamp long (YYYYMMDDhhmmss,aaaaaaa) values are allowed with or without separators.
- Email values are allowed in the following format: {name}@{domain}
2.2.2 Import using OData Service
Interactions can be imported into SAP Hybris Marketing using the OData service API_MKT_INTERACTION_SRV. The service is part of the communication scenario SAP_COM_0206. You will have to setup a communication arrangement for this scenario to create a communication user with the required authorization.
Structure
The OData service contains an entity set
Interactions. The POST method enables you to directly upload new interaction data. The properties InteractionContactOrigin, InteractionContactID, CommunicationMedium, InteractionType, InteractionTimeStampUTC, InteractionSourceObjectType and InteractionSourceObject are required for a successful upload.
Call of OData Service
The following code shows an example how to call the Odata Service with JSON format in order to create interactions. As bulk processing increases performance, the $batch implementation is used. The URL called is
https://my<...>-api.s4hana.ondemand.com/sap/opu/odata/sap/
API_MKT_INTERACTION_SRV/$batch.
--batch_e0b5-4b67-81dc
content-type: multipart/mixed; boundary=changeset_ba95-fe80-fa44
--changeset_ba95-fe80-fa44
content-type: application/http
POST Interactions HTTP/1.1
Content-Type: application/json
{
"InteractionContactOrigin" : "AIRLINE_SYSTEM",
"InteractionContactId" : "4711",
"InteractionTimeStampUTC":"2017-10-26T14:36:00.0000000",
"CommunicationMedium" : "WEB",
"InteractionType" : "CHECK_IN",
"InteractionSourceObjectType" : "CHECK_IN_VOUCHER",
"InteractionSourceObject" : "1234567",
"InteractionSourceDataURL" : "https://airlinesystem/check_in",
"SourceSystem" : "AIRLINE_SYSTEM",
"YY1_CheckInTime_MIA" : "PT14H36M"
}
--changeset_ba95-fe80-fa44--
--batch_e0b5-4b67-81dc--
Success Message and Error Handling
After a successful data upload, the system returns a 202 HTTP status code for the whole batch request. You need to ensure that the actual HTTP status codes for the individual calls inside the batch return 201. The upload is queued in the SAP Hybris Marketing system and you can check the actual upload status in the app "Import Monitor".
3 Segmentation
After the contact and interaction data is uploaded into SAP Hybris Marketing, the segmentation can be configured to your needs. SAP Hybris Marketing has delivered several segmentation profiles by default, e.g. All Consumers. This segmentation profile can already be used with the uploaded data:
3.1 Segmentation Enhancements
You can easily add custom fields to SAP delivered segmentation objects by using the app "Marketing Extensibility". In the section Custom Fields you find the option
Assign to Segmentation.
In addition custom business objects as well as own SAP HANA views can be added to the segmentations. You find the documentation under
help.sap.com/marketing -> Extensibility Guide -> Segmentation.
3.2 Segmentation Configuration
With the app "Segmentation Configuration" you can configure the segmentation to your needs.
Travel Example
For the travel example a new attribute group Travellers is created and fields from the Consumer attribute group are moved to that group. Moreover the the segmentation profile name is changed from All Consumers to Travellers. The custom fields Nationality and Check In Time are also added. The outcome on the user interface is the following: