SFlight sample application showing how to extend a...

Former Member · ‎2014 Mar 04

This blog offers you a comprehensive and easy-to-use tutorial for developing a hybrid application on SAP HANA Cloud Platform that integrates with an on-premise ABAP system using JCo and RFC. It is a simple example of how SAP HANA Cloud Platform can be used as extension platform for existing SAP systems running on customer side.

The tutorial below guides you through an application scenario that includes

how to develop a simple cloud application using JCo to call an on-premise ABAP system,
how to use Apache CXF + Spring Framework to define some RESTful services
how to configure and test connectivity of the application on SAP HANA Cloud Platform local runtime
how to setup and configure the SAP HANA Cloud Connector
how to configure and test connectivity of the application on SAP HANA Cloud Platform

List of technologies used:

JCo API and destinations
SAP HANA Cloud Connector
Apache CXF and Spring Framework
SAP UI5
SAP HANA Cloud Platform local runtime for testing

1. Development Scenario Overview

The scenario implements a simple flight booking application based on the well-known SFLIGHT model available as default sample content in ABAP systems [1]. The overall landscape of the sample application is shown in following picture:

The client consists of an HTML UI, based on SAP UI5, and implements the UI following the Model-View-Controller paradigm.

The client interacts with the Web application on SAP HANA Cloud Platform via a set of REST services, to request a list of flights, to get flight details and to book a flight.

The Web application provides these REST services using Apache CXF and the Spring Framework.

The REST services in the application delegate the actual calls to the ABAP system to a JCoFlightProvider class which in turn uses the Java Connector API to call an on-premise ABAP system directly using RFC.

For the on-demand to on-premise connectivity, a SAP HANA Cloud Connector is running in the on-premise landscape. It has the ABAP system and BAPIs configured as accessible resources which are needed by the SFlight application.

In the ABAP system, the sample data of the SFLIGHT model has been created, and the authentication to the SFLIGHT BAPIs is done with a service user in this example.

If you like to see the application running, start it in a browser (Chrome, FireFox, Safari) with following URL: https://sflightdemo.hana.ondemand.com/sflight-web/

2. Setting up the Environment

The sources of the SFlight sample application are available on sap.github.io, as Extension-005 of the personslist git repository which holds a collection of similar HCP sample applications: [0].

In order to run the application in your landscape, an important pre-requisite is to have an ABAP system, version 4.6c or newer, with the SFLIGHT model and licensed named ABAP users available. How to setup the SFLIGHT model in an ABAP system (e.g. how to generate the flight sample data) is described here [1].

2.1 Setting up Local HCP Development Environment

If this pre-requisite is fulfilled, you can set up and run the application in your environment. In this tutorial, only the connectivity specific steps are described in detail, the general steps how to set up the SAP HANA Cloud Platform environment and how to import the SFlight sample project into your Eclipse workspace is just shortly summarized here. A more detailed step-by-step guide for these steps are provided in the ReadMe.txt file that you can find in the root directory of the Extensions-005 branch in the github project [0].

Register for a free developer account on HCP
Install Java 7 JDK
Install Eclipse for Java EE Developers
Install the HCP Eclipse tools
Download the HCP SDK
Set up the HCP runtime environment in Eclipse
Install Egit
Synchronize the cloud-personslist-scenario git repository from [0], and create a local branch for the Extensions-005 branch. This branch contains the sflight-web Maven project.
Import the sflight-web Maven project into your Eclipse workspace.
Run a Maven "clean install" build of the project in Eclipse and make sure the project builds without errors.

You should now have a local HCP development environment set up, and the sflight-web project imported and built successfully in your Eclipse workspace.

2.2 Installing the Cloud Connector and Establishing an SSL Tunnel to Your HCP Account

To make RFC calls from the cloud over SSL, you need to install the SAP HANA Cloud Connector in your on-premise landscape. You can download the cloud connector from https://tools.hana.ondemand.com/#cloud and install it as described here [2].

Once you installed it, you can connect it against your HCP account by following the steps described here [3]. Once this is done, you have established a persistent SSL tunnel from your environment to your HCP account - but don't worry, none of your internal systems are yet accessible from the cloud applications. You have full control over the systems and resources you like to make accessible to your cloud applications, i.e. you need to configure each system and resource in the cloud connector that you like to make accessible to applications of your HCP account. We will do this in a later step of this tutorial.

3. SFlight User Interface

The SFlight application uses SAP UI5 as JavaScript library for its user interface. Following the Model-View-Controller paradigm of SAP UI5, the UI is built of the two files sflight.view.js and sflight.controller.js which you can find under /src/main/webapp/sflight-web in the Eclipse project.

A screenshot of the UI is shown below. On the right hand side, you find the function names within the sflight.view.js file which implement the respective panel.

The single panels interact with the sflight.controller.js file in following ways:

createFlightSearchPanel(...) function: calls the searchFlights(...) function of the controller to retrieve a list of flights from specified departure and arrival airports.
createFlightListPanel(...) function: calls the getFlightDetails(...) function of the controller to retrieve the details of the selected flight.
createFlightDetailsPanel(...) function: calls the bookFlight(...) function of the controller to book the selected flight. It also calls the searchFlights(...) function of the controller again to retrieve an updated flight list.

The UI controller interacts with the SFlight Web application running on the server using REST services. Each of these REST services replies with a JSON response, so that the controller and view are using the sap.ui.model.json.JSONModel to bind the UI to the JSON data. The REST services called in the sflight.controller.js file are following:

GET: /rest/v1/flight.svc/cities
Returns a JSON array of cities in which airports are located.
GET: /rest/v1/flight.svc/flights/{cityFrom}/{cityTo}
Returns a JSON array of flight with departure airport {cityFrom} and arrival airport {cityTo}.
GET: /rest/v1/flight.svc/flight/{carrier}/{connNumber}/{dateOfFlight}
Returns a JSON array with the details of the specified flight.
POST: /rest/v1/flight.svc/booking
Books a flight specified in the response body and returns a JSON object with the booking ID.
xmlhttprequest is used directly to trigger the POST request to the server.

4. Flight REST Services in the Web Application

The Web application is using Apache CXF and the Spring Framework to provide the necessary REST services. In order to use these libraries, following dependencies are define in the pom.xml of the application:

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-rt-frontend-jaxws</artifactId>

<version>${org.apache.cxf.version}</version>

</dependency>

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-rt-transports-http</artifactId>

<version>${org.apache.cxf.version}</version>

</dependency>

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-rt-rs-extension-providers</artifactId>

<version>${org.apache.cxf.version}</version>

</dependency>

<groupId>org.apache.cxf</groupId>

<artifactId>cxf-bundle-jaxrs</artifactId>

<version>${org.apache.cxf.version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-context</artifactId>

<version>${org.springframework.version}</version>

</dependency>

<groupId>org.springframework</groupId>

<artifactId>spring-web</artifactId>

<version>${org.springframework.version}</version>

</dependency>

How to use CXF in combination with Spring is described in more detail here [4]. Shortly summarized, it provides a simple framework to define REST services in POJOs, taking care for all the boilerplate code of receiving and sending HTTP requests for you. It thus allows you to focus on the business logic and makes development of REST services an easy task.

To understand how the REST services of the sample application are implemented, you need to look into the sprintrest-context.xml file located under the /src/main/webapp/WEB-INF folder in the Eclipse project. There, a Spring bean is defined with name flightService.This bean is implemented by the Java class com.sap.cloudlabs.connectivity.sflight.FlightService. Using the CXF and Spring annotations, the FlightService class is a simple POJO which provides the GET and POST service endpoints listed above in section 3. A small code fragment that shows how the definition of the REST service is done is shown below:

@Service("flightService")

@Path("/flight.svc")

@Produces({ "application/json" })

public class FlightService {

@GET

@Path("/flights/{cityFrom}/{cityTo}")

@Produces("application/json")

public String getFlightList(@Context HttpServletRequest req, @PathParam("cityFrom") String cityFrom,

@PathParam("cityTo") String cityTo) {

...

}

5. Fetching Flight Data and Trigger Booking in the ABAP system

The FlightService class delegates all calls to a FlightProvider object which then in turn does the actual call to the backend system. For this, an interface com.sap.cloudlabs.connectivity.sflight.FlightProvider is used that defines the Java methods which shall be performed against the SFlight backend service.

Right now, there is just one implementation of the FlightProvider interface: com.sap.cloudlabs.connectivity.sflight.jco.JCoFlightProvider.
We might add e.g. an ODataFlightProvider in the future to this sample application.

The JCoFlightProvider uses the Java Connector API to make RFC calls directly against an ABAP system. Of course, all the communication is encrypted using the cloud connector and its SSL tunnel. You can use JCo in exactly the same way as you might know it from SAP NetWeaver Java. A tutorial how to work with JCo can be found here [5]. JCo uses RFC destinations which encapsulate the configuration of the ABAP system, and allows the separation of the actual ABAP system configuration from the application coding. The JCoFlightProvider makes use of an RFC destination called dest_sflight. This destination will be configured in section 6.

Note that the JCoFlightProvider class not only fetches data from the ABAP system, but also writes back a flight booking transaction to the ABAP system.The BAPIs called by the application on the ABAP system are:

BAPI_SFLIGHT_GETLIST
BAPI_SFLIGHT_GETDETAIL
BAPI_SBOOK_CREATEFROMDATA
BAPI_TRANSACTION_COMMIT

To provide the result set of the JCo calls in a JSON format, a utility class com.sap.cloudlabs.connectivity.sflight.jco.JCoUtils is used to transform JCo tables and structures into JSON objects. This eases the consumption of the response in the SAP UI5 client.

6. Configuring Destinations

You should have now a good understanding how the application is structured and what the single layers are doing. Next step is to test the application, first on the local test server, and then in the cloud. In order to do this, the RFC destination used by the application needs to be configured.

6.1 Configure Destination in Local Test Server

As first step, deploy the SFlight application on your local HANA Cloud Platform test server:

In Eclipse Project Explorer view select project node sflight-web.
On the selected project node open context menu and choose Run As > Run on Server.
Window Run On Server opens. Make sure that the Manually define new server option is selected.
Select SAP > SAP HANA Cloud local runtime as server type
Choose Finish.

You now need to configure a test user for your local server: Double click SAP > SAP HANA Cloud local runtime in the Servers' view and navigate into the Users tab. Add a test user here and save the changes. This user can be used to log on into the local application.

Afterwards, the RFC destination used by the application needs to be configured:

In the Eclipse Project Explorer, copy the destination dest_sflight.jcoDestination from folder sflight-web/src/main/webapp/destinations into the root directory of your local SAP HANA Cloud Platform test server which you can find in the Eclipse Project Explorer tree under Servers > SAP HANA Cloud Platform local runtime-config.
Adopt the configuration: Open the copied destination dest_sflight.jcoDestination in Eclipse with a text editor and adopt the destination configuration to point to the locally accessible ABAP system you want to use for the sample application. Note that you need to have licensed named ABAP users according to the SAP licensing model for your scenario.
The JCo properties are explained here: https://help.hana.ondemand.com/help/frameset.htm?e184daba118b46679c6968567bacc98e.html

Now, you should be able to test the SFlight application in your browser, using the URL: http://localhost:<port_of_local_server>/sflight-web. The application should successfully call the ABAP system and display data when selecting cities for which flights exist in the ABAP system (e.g. choose Departure = Frankfurt, Arrival = New York).

6.2 Configure Destination in the Cloud

First, publish the SFlight application to your free Developer Account in the cloud:

In Eclipse Project Explorer select sflight-web project node.
Open context menu Run As > Run on Server.
Make sure that 'Manually define a new server' option is selected.
Change default Server's host name 'hana.ondemand.com' to 'hanatrial.ondemand.com'
Choose Next
Enter Application name e.g. sflight (only small letters(a-z) and numbers are allowed)
Then enter your SAP HANA Cloud Platform Developer Account name (<p-user>trial), (SCN) User name (<p-user>) and your password.
Choose Finish.

After about a minute the SFlight application, running on SAP HANA Cloud Platform, is launched with the external Web browser you configured before.

Now, configure the RFC destination for the SFlight application in the cloud:

In Eclipse Server view, open the server UI by double clicking the server.
Navigate into the Connectivity tab.
Click on the Import existing Destination button and browse to the dest_sflight.properties destination located in the sflight-web/src/main/webapp/destinations folder of the Eclipse project.
Adopt the destination configuration to point to your on-premise ABAP system. Note that you need to have licensed named ABAP users according to the SAP licensing model for your scenario.
The JCo properties are explained in detail here: https://help.hana.ondemand.com/help/frameset.htm?e184daba118b46679c6968567bacc98e.html
The properties file is pre-filled with following values:
jco.client.mshost=abap.sflight.host
jco.client.r3name=FLI
These values are relevant for the configuration of the ABAP system in the SAP HANA Cloud Connector, as described in section 7 below. It's recommended to leave these two properties unchanged, so that they fit to the configuration used in the next section.
Save the application. This will deploy the configuration into the cloud.

To run the application in the cloud, one more step is missing: The ABAP system and BAPIs which shall be made accessible to the SFlight application need to be configured in the Cloud Connector.

7. Configure ABAP System and BAPIs in the Cloud Connector

At this stage, you should have installed already a Cloud Connector and established a connection with your free developer account (see section 2.2 above).

Now you need to configure the ABAP system and BAPIs used by the SFlight application in the Cloud Connector. For this, go into the Cloud Connector administrator UI and execute the steps below:

Navigate into the Access Control view of the Cloud Connector. Under Mapping Virtual to Internal System click the Add... button.
Enter and save following values in the Add System Mapping dialog:
      Virutal Host = abap.sflight.host
      Virtual Port = sapmsFLI
      Interal Host = <host name of the ABAP system>
      Interal Port = <port of the ABAP system>
      Protocol = RFC
      Backend Type = ABAP System
Select the newly created entry in the Mapping Virtual to Internal System table.
In the Resources... table at the bottom, add the BAPIs the SFlight application shall get access to.
Enter following 3 entries using the Add... button:
1. Function Name: BAPI_SBOOK
  Naming Policy: Prefix
2. Function Name: BAPI_SFLIGHT
  Naming Policy: Prefix
3. Function Name: BAPI_TRANSACTION_COMMIT
  Naming Policy: Exact Name

Now you should be able to run the SFlight application in the cloud. The application should fetch the data from your on-premise ABAP system and display the data as in the local test case.

8. Summary

The SFlight sample application and this tutorial demonstrate how you can write an application on SAP HANA Cloud Platform that integrates directly with on-premise ABAP systems by using the Cloud Connector and JCo/RFC. Typical use cases for this are scenarios, where existing and potentially already pretty old on-premise ABAP systems should be extended by modern cloud applications, without the need to touch or upgrade the ABAP systems themselves and without the need of additional layers on top of the ABAP systems in order to make their BAPIs externally available. As the data is not stored in the cloud, but fetched by the cloud application, data consistency is not undermined by the cloud scenario. By using the capabilities of the Cloud Connector, it is possible to restrict access only to those parts of the ABAP system which are actually needed by the cloud application. Thus, you can consider this approach a very secure way how to extend an on-premise system in the cloud.

9. References

[0] SAP/cloud-personslist-scenario · GitHub

[1] Flight Data Application: Overview - Demo Example for Integration Technology

[2] SAP HANA Cloud Platform - Installing Cloud Connector 2.x

[3] SAP HANA Cloud Platform - Initial Configuration of Cloud Connector

[4] Apache CXF -- JAXRS Services Configuration

[5] SAP Java Connector

[6] SAP HANA Cloud Code Samples - Extensions of PersonsList Web Application