Part 1: How to use public APIs of SAP Marketing Cloud via Java App on SCP?

[jonathan95]

Introduction

With this blog series, I will provide an introduction on how to interact with public APIs of the Marketing Cloud via a Java Application on SAP Cloud Platform.

In the first part, I will guide you through the installation and setup process, so that you have the sample project up and running. (Please note the prerequisites!) If you are just interested in code snippets and you don´t need an example project, then you can skip part one and continue with part two. In part two, I will explain the main steps, how to use Marketing Cloud APIs from Java Apps on SCP and show you important code snippets.

GitHub Links

Java Project: https://github.wdf.sap.corp/D065128/persistence-service-scp-neo

UI5 App: https://github.wdf.sap.corp/D065128/prototype

Used Marketing Cloud APIs: https://api.sap.com/api/API_MKT_CONTACT_SRV/resource

What you will learn?

• Using Marketing Cloud APIs from Java App


• How to use Apache Olingo as Client Library


• Destinations with technical Communication User

 

Overview

I will show you, how to access public APIs of SAP Marketing Cloud from a Java Application on SAP Cloud Platform. (Neo Environment) I used the public OData API “API_MKT_CONTACT” to create new Contacts. The requests are assembled and send via a Batch request to the Marketing Cloud. To build Batch requests and send them to the Marketing Cloud System I make use of the Apache Olingo Client Java Library.

The prototype consists of two applications which are deployed on SCP separately. In the Frontend, the User interacts with a UI5 App which provides basic functionalities to create, update and delete Contacts.

The Backend is a Java Application which exposes a REST API with CRUD operations. The Java application stores Contacts in a Hana DB, which is bound via Service Binding.

All the created Contacts can be sent via a Batch request to the Marketing Cloud. To enable the data exchange between the application in SCP and the Marketing Cloud System, we use Destinations and a Communication Arrangement. In case your Marketing system is in your on-premise system landscape, you need to install Cloud Connector, which is not part of this blog series.

 

Technologies

 

Backend

• Spring Boot (Configured for SCP Neo Environment, Java Web Runtime)
  
  
  
  • Spring Web
  
  
  • Spring Data (JPA/Hibernate)
  
  
  
  


• Olingo Client Library


• Hana MDC for Cloud deployment, H2 for development (Spring and Maven Profiles combined)

 

Frontend

• Basic UI5 App

 

Architecture

 



 

General Prerequisite

• SAP Cloud Platform Trial Account


• SAP Marketing Cloud tenant

 

Setting Up the Development Environment

 

Setup Prerequisite

• JDK 8


• Eclipse IDE Oxygen (Photon is currently not compatible with SCP Tools)


• SAP Cloud Platform SDK


• SAP Cloud Platform tools for Eclipse


• Git ( + Plugin for Eclipse)


• Maven ( + Plugin for Eclipse)

 

Download Eclipse

⇒ https://www.eclipse.org/downloads/

Install SAP Development Tools for Eclipse

⇒ https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/76137a37711e1014839a8273b0e...

Help → Install New Software



 

 



URL: https://tools.hana.ondemand.com/oxygen

Choose Next and accept the Eclipse and SAP license agreements then choose Finish.

 

Set Up the Runtime Environment

Download SDK for Java Web Tomcat 8

To use the SDK for Java Web Tomcat 8 with Eclipse, please see Set Up the Runtime Environment Procedure for “Java Web Tomcat 8 Runtime”.

 

Set Up SAP JVM in Eclipse IDE

Please, follow the steps described in the link below.

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/7613eaad711e1014839a8273b0e...

Set Up the Console Client (OPTIONAL)

The console client tool is contained in the SDK for Neo environment.

For more information, how to use it, please see the link below.

https://help.sap.com/viewer/65de2977205c403bbc107264b8eccf4b/Cloud/en-US/7613dee4711e1014839a8273b0e...

Once the Development Environment is set up, you can clone the repository from GitHub and open it in Eclipse.

 

Deployment

The Java Project is built with Maven. Maven Profiles combined with Spring Profiles are used for deployment in different environments. The application runs locally on Java Web Tomcat 8 (SAP Cloud Platform Neo Environment SDK) and uses an embedded H2 database. For production, the application is deployed on SAP Cloud Platform Neo Environment and uses Hana DB as Backing Service.

 

Local Deployment

Build WAR file for local deployment with Maven Profile local

mvn -P local clean package

Before deploying the WAR file, please create a Destination for your Marketing Cloud System. You can create the Destination in your JVM in Eclipse. If you change the destination name, please note that you have to adapt the name in the source code as well.

To enable data exchange with your Marketing system in the cloud, set up a Communication Scenario. See the following link for more information.

https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1902.500/en-US/9fa5748d2f9f4199925acace...

For Basic Authentication use your created Communication User.



 

Now you can deploy the WAR file to your Java Web Tomcat 8 Server.



 

You can test the application with the following links. The API documentation gives you an overview of the possible CRUD functionalities.

API URL: http://localhost:8080/persistence-service-scp-neo/contacts

API Docu (Swagger): http://localhost:8080/persistence-service-scp-neo/swagger-ui.html

 

Cloud Deployment

Build WAR file for cloud deployment with Maven Profile cloud

mvn -P cloud clean package

Before deploying the WAR file, please create the Destination for your Marketing Cloud System. You can create the Destination in SCP. If you change the destination name, please note that you have adapt the code as well.

To enable data exchange with your Marketing system in the cloud, set up a Communication Scenario. See the following link for more information.

https://help.sap.com/viewer/0f9408e4921e4ba3bb4a7a1f75f837a7/1902.500/en-US/9fa5748d2f9f4199925acace...

For Basic Authentication use your created Communication User.

 



 

Now You can deploy the WAR file to SCP.



 

Once the application was deployed successfully, don´t start the app.

Click Done and create a Hana MDC database. For more information, how to create a Hana database on SAP Cloud Platform please refer link.

https://help.sap.com/viewer/d4790b2de2f4429db6f3dff54e4d7b3a/Cloud/en-US/eb91609f87b4443dab617d1683c...

After creation, bind the Hana MDC database to the application.

 



 

Now start the application and test it with the following links.

The API documentation gives you an overview of the possible CRUD functionalities.

API URL: https://<app_name><subaccount>.int.sap.hana.ondemand.com/persistence-service/contacts

API Docu (Swagger): https://<app_name><subaccount>.int.sap.hana.ondemand.com/persistence-service/swagger-ui.html

 

UI5 App Deployment

You don’t need the ui5 app to test the application, it is also possible to test the functionality with a rest client like Postman. But it is more fun with a simple application.

To deploy the app please clone the repository.



Before you deploy and run the ui5 app, create the following Destination for your deployed java app on SCP. If you change the destination name, please note that you have to adapt the code as well.

 



 

Now run the app and test the functionality.

 

Conclusion

If you followed all the steps in this blog post, you have the sample project up and running. The running app will help you to understand, what the code is implemented for. Furthermore, you could check the logging of the Java App on SCP. All HTTP requests to your Marketing Cloud System are logged and you can find information about header and body of each batch request. If you are interested in an explanation of important code snippets, which you need, to set up your own project, continue with part two of this blog series.