Custom App to Capture Trade Fair Contacts - Extend...
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.
Have you ever wanted to extend your SAP Marketing Cloud solution with functionality and own apps that are not included in standard? In this blog, you can find steps on how to create a small and lightweight extension app for your SAP Marketing Cloud using the SAP Cloud Platform and integration flows (iFlows) from SAP Cloud Platform Integration.
The example provided in the blog is based on the business case “Capture contact data at a trade fair”: Using the app, employees at the company’s trade fair booth can easily load their visitors’ contact names and additional information such as company data and interaction information to the SAP Marketing Cloud system.
The complete coding of this example is available at github.com/SAP/cloud-marketing-visitor-registration. There you can also find more information on downloading, installing, and setting up the demo scenario. In the blog, you’ll find the steps of building the needed components.
Requirements to the App
The starting point are the following attributes that are needed for the scenario:
Contact with first name, last name, job function, birth date
Company Data with company name and address data of company
Interaction: Day of visit as time stamp, free text for additional visit remarks
Furthermore, the following behavior of the app is required:
If company data cannot be saved, the contact and interaction information shall also not be saved.
If contact cannot be saved, the interaction shall not be saved.
If only interaction information is provided, only the interaction service shall be called.
Send data via app to SAP Marketing Cloud (click to enlarge)
Overview
This sample app was built using the following components:
Frontend: Simple UI5 “one-page” app for data input to be deployed on SAP Cloud Platform
iFlow deployed on SAP Cloud Platform Integration serving as mediator to receive the flat input from the UI app and transform it to suitable payloads for the SAP Marketing Cloud APIs
The components and their communication are visualized as follows:
In the uploading process of the information, the following three SAP Marketing Cloud APIs are involved:
To achieve the calls to the SAP Marketing Cloud system, a SAP Cloud Platform Integration iFlow is used. This iFlow models the process flow of the incoming message, in particular, the transformation and data load to the SAP Marketing Cloud system. In addition, it deals with validation and error handling. The iFlow was chosen as mediator since much integration content is already available for SAP Marketing Cloud on SAP Cloud Platform Integration. For example, the File-Based Data Load IFlows serve as a starting point for integration as they provide also the HTTP input option. This HTTP endpoint can be used to send data to the iFlow from a UI.
The sample app’s iFlow can be imported from the demo repository into your integration tenant as described in the Setup and Configuration document. After having imported the iFlow into a package of your integration tenant, you can check the main components in the Web IDE of SAP Cloud Platform Integration.
The iFlow has two input options, HTTP and SFTP. The SFTP adapter can be used to periodically poll an SFTP server for CSV data files to be sent while the HTTP endpoint is used to push the data. Both input options route the message to the Map and Send process.
The transformation and preparation of the incoming message happens in the Map and Sendlocal integration process:
Map and Send Process (click to enlarge)
The relevant steps are the following:
Message transformation from JSON or flat CSV to a flat XML message according to the metadata information in /xsd/CSV_Input_Data.xsd.
The constraints available are used for validation of the incoming message like timestamp check or string length validation.
Message transformation via XSLT from the flat XML to a structured XML containing the batch payload information for the three used services in the three sub-nodes CompanyPayload, ContactPayload and InteractionPayload.
In groovy script function extractPayloads, the relevant payloads are extracted from the transformation result and stored in message property variables
The sequential calls are triggered through setting the SendEntity message property and calling the Send Data To Marketing local integration process.
Send Data to Marketing Process (click to enlarge)
The Send Data To Marketing local integration process is responsible for the following:
Fetch and set the relevant payload and URL for the OData adapter call depending on the value for message property SendEntity. See groovy script function setPayloadAndUrl.
If no batch payload is available, no OData call is triggered, and the process returns to Map and Send.
If a batch payload is available, the relevant OData service is called via the OData adapter and the result is analyzed.
In case of success, the message flow returns to Map and Send process.
In case of error, the message flow exists with an exception and the processing of the iFlow is stopped.
These two integration processes ensure that the service calls are orchestrated. The header parameter Sap-Cuan-ForceSynchronousProcessing set to true for each service call ensures that the payload is processed synchronously, and the response of the service call is directly returned. Without this parameter set, the processing of the payload happens asynchronously via the staging area, and the direct result is not available.
To also provide a file-based input option of such trade fair contact data, a file input option via SFTP and HTTP adapter is available in addition such as in the File-Based Data Load iFlows.
Testing the iFlow
After having deployed the iFlow successfully on your SAP Cloud Platform Integration tenant (see detailed information on the required parameters in the Setup and Configuration document), you can test the HTTP endpoint with Postman and a suitable JSON payload or a flat CSV payload. Make use of variables in Postman, so you do not need to copy tokens and other information to the post call.
Create different payloads and check the incoming messages in the Import Monitor application of your SAP Marketing Cloud tenant. It can be also useful to use the trace functionality of the iFlow to see the different steps and intermediate payloads in the iFlow.
UI App
To proceed with the import of the sample coding, log on for example to your SAP Cloud Platform free trial account and start the Web IDE from the cockpit. Follow the detailed steps in the Setup and Configuration document. A simple and plain UI5 one-page created from the sample template is used as UI. It was created by following the New -> Project from Template -> SAP UI5 Application path and keeps the default structure of this template app. For more information on the structure, see Folder Structure: Where to Put Your Files.
The app has just one XML view in folder view with corresponding controller VisitorRegistration.controller.js in folder controller. The input fields in the VisitorRegistration.view.xml are bound to the JSON view model Data defined in the AppModel.json (see folder model). Note that the properties in this Data model match exactly the structure CSV_input.xsd of the iFlow.
Sending Data
The user input stored in the Data model is sent to the HTTP endpoint of the iFlow. For more information on calling HTTP endpoints directly from a UI5 app, see Add an External API call to your app. As the HTTP endpoint is CSRF-protected, first a token fetch call is needed before posting the JSON payload to the iFlow. With the obtained token, the JSON object is sent via POST. The logic can be checked in method sendData of the view controller.
Adding Value Help
If you want the app to be able to select available contacts and companies from the SAP Marketing Cloud system, the UI can use the services consumed by the iFlow for posting also for searching. The destination mkt-destination allows the direct connection to the SAP Marketing Cloud system with authentication of a suitable communication user.
To search contacts, the entity set ContactOriginData of the API_MKT_CONTACT_SRV is used and bound to the Email Input field as suggestionItems collection. The following steps have been executed:
Add the API_MKT_CONTACT_SRV as additional model to the app.
Right-click the app folder and choose New OData Service.
Select Service URL and choose the destination mkt-destination to connect.
Enter relative URL of the service endpoint, in this case sap/opu/odata/sap/API_MKT_CONTACT_SRV;v=0002/
Click Next and specify a new model name for this endpoint, in this case API_MKT_CONTACT_SRV.
This named model is subsequently used in the XML view and bound to the suggestionItems of the SearchField control used for the contact email data.
To use the input entered in the search field for filtering the entity set collection, the method onSuggestContact is used to build the necessary filter criteria on selected fields of the ContactOriginData entity.
Same logic is available for the company value help: the service API_MKT_CORPORATE_ACCOUNT was added here as an additional model to the UI app.
The methods that handle the selection of the proposed entities are onSearchContact resp. onSearchCompany. For the contact, several contact-related fields are populated from the ContactOriginData entity to the respective UI fields. In addition, the company information (if available) is retrieved via a separate data call to the corporate account service and populated to the company fields.
Remarks on the Origins of Contact and Company Ids:
When the contact or company is taken from the value help, also the Id together with its OriginId values is put to the data model. When a new contact or company is created, no Id and OriginId values are available. Instead they get generated in the UI controller and filled to the UI model before sending. This logic can be adapted to fit own business needs. For more information on the usage and creation of OriginIDs, see the application help for SAP Marketing Cloud under Defining Origins of Contact IDs.
Deploying the app
The UI app can be deployed directly from the Web IDE to your SAP Cloud Platform account. It can be used directly from there or registered to an SAP Fiori Launchpad.
Summary
This sample app was realized with standard features of the SAP Cloud Platform and SAP Cloud Platform Integration. Most effort was put into the iFlow and the creation of suitable batch payloads for the SAP Marketing Cloud API.
You can use the mentioned components to develop your own extension app. Take the sample app as a starter and adapt where necessary or start from scratch using a similar or different approach. Ideas on enhancing the app can be found in the documentation of the sample repository.
As an alternative to the iFlow, you can also have a Java app deployed as back-end app which transforms the flat JSON object from the UI to the needed message payloads for the involved services. In that case, you don’t need a SAP Cloud Platform Integration tenant.
Hope you found some inspiration and have fun in realizing your project ?. Feel free to comment on this blog in case you have questions or feedback on either the blog or the linked repository with the sources.
