Custom App to Capture Trade Fair Contacts – Extending SAP Marketing Cloud
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.
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:
The communication from the UI app to the service endpoint of the iFlow and the APIs happens using destinations on the SAP Cloud Platform account.
You have access to the following products:
- SAP Marketing Cloud tenant
- SAP Cloud Platform Integration tenant, which you received together with your SAP Marketing Cloud tenant. Check details in the Onboarding Guide.
- SAP Cloud Platform account (trial version is sufficient)
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 Send local integration process:
The relevant steps are the following:
- Message transformation from JSON or flat CSV to a flat XML message according to the metadata information in
- 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
- 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.
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
- 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.
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.
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
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.
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.