Você está na página 1de 1338

Developer Guide

SAP HANA Cloud Platform


Document Version: 1.85.0 2016-07-20

SAP HANA Cloud Platform

PUBLIC

Content

SAP HANA Cloud Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.1

Product Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Product Prerequisites and Restrictions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.2

Get Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Creating Your First Cloud Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Accounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Java: Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
SAP HANA: Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
HTML5: Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Tutorials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Glossary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

1.3

Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
SDK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Cockpit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Eclipse Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
SAP Web IDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Maven Plugin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Console Client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

1.4

Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Connectivity Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Document Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545
SAP Document Center. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
Feedback Service (Beta). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597
Gamification Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615
Monitoring Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Performance Statistics Service (Beta). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .714
Persistence Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 720
Remote Data Sync Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 871
SAP Translation Hub (Beta). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .894
Git Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928
Business Services with YaaS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 942

1.5

Develop Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 950


Java: Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 951
SAP HANA: Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008
HTML5: Development. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1040
API Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1060

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


Content

1.6

Extend SAP Cloud Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1060


Basic Concepts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1062
Extending SuccessFactors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1070

1.7

Operate Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1095


Java: Application Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1096
SAP HANA: Application Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1164
HTML5: Application Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1171
Configuring Application URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1182
Change Management with CTS+. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1198

1.8

Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
Identity and Access Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
Securing SAP HANA Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Securing Java Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Securing HTML5 Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1323

1.9

Get Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325


Support Information (Eclipse IDE). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1327
Platform Updates and Notifications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1327

1.10

Our Response to Your Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1330

SAP HANA Cloud Platform


Content

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform

Table 1:
Get Started

Get Productive

Account Types [page 12]

Develop

Creating Your First Cloud Application

SAP HANA [page 1008] | Java [page

[page 10]

951] | SAPUI5 | HTML5 [page 1040]

Tutorials [page 76]


Java Samples [page 51]
Glossary [page 78]

Operations
Configure [page 1099] | Update [page
1119] | Log [page 1129] | Debug [page
986] | Monitor [page 1149] ...

Enable Application Providers to Access


Your Account [page 25]

Secure Applications
Authentication [page 1213] | Authoriza
tion [page 1220] | OAuth 2.0 [page 1227]
| Roles [page 1282] | ID Federation [page
1292] ...

What's In

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

What's New

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Product Overview [page 5]


Tools

Release Notes
Our Response to Your Feedback [page
1330]

Cockpit [page 84] | Eclipse [page


86] | Console Client [page 88] | SAP
Web IDE [page 88] | Maven Plugin
[page 88] | Cloud Connector [page
434] ...

Software Development Kit [page 81]


Featured Services
Connectivity [page 267] | Feedback

84]

ID Federation with the Corporate


Identity Provider [page 1292]

871] | Gamification [page 615]

Download the product documentation in

Managing Accounts and Quota


[page 17]

[page 597] | Performance Statistics


[page 714] | Remote Data Sync [page

Notifications in the Cockpit [page

Principal Propagation to OAuth-Pro


tected Applications [page 1318]

Configuring OAuth 2.0 [page 1310]

Managing Database Systems [page


774]

PDF format.

1.1

Product Overview

SAP HANA Cloud Platform is an in-memory cloud platform based on open standards. It provides access to a
feature-rich, easy-to-use development environment in the cloud. The platform includes a comprehensive set of
services for integration, enterprise mobility, collaboration, and analytics.
SAP HANA Cloud Platform enables customers and partners to rapidly build, deploy, and manage cloud-based
enterprise applications that complement and extend your SAP or non-SAP solutions, either on-premise or ondemand.
As a Platform-as-a-Service operated by SAP, our product frees you from any infrastructure and IT costs and
offers state-of-the art quality of service - availability, scalability, multitenancy.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Scenarios

Develop new cloud applications


This scenario is suitable for companies that need to start developing new applications from scratch. You can
create brand new cloud applications and reach your end customers easily, with a low learning curve and small
capital investment in software and hardware.
Develop on-premise extensions
This scenario is suitable for companies that have already invested a lot in on-premise IT infrastructure. You
can create the new extensions to the system on the cloud, and integrate seamlessly with the on-premise
components using Connectivity Service and Cloud Connector.
Develop cloud extensions
At SAP HANA Cloud Platform, you can also develop extensions to other cloud products, such as
SuccessFactors.

Application development
You can use the following programming models to build highly scalable applications:
Java - SAP HANA Cloud Platform is Java EE 6 Web Profile certified. You can develop Java applications just like
for any application server. You can also easily run your existing Java applications on the platform.
SAP HANA - you can use the SAP HANA development tools to create comprehensive analytical models and
build applications with SAP HANA programmatic interfaces and integrated development environment.
HTML5 - you can easily develop and run lightweight HTML5 applications in a cloud environment.
SAPUI5 - use the UI Development Toolkit for HTML5 (SAPUI5) for developing rich user interfaces for modern
Web business applications.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Runtime container for applications


Applications developed on SAP HANA Cloud Platform run in a modular and lightweight runtime container. The
platform provides a secure, scalable runtime environment with reusable platform services.

Services
You can consume a set of services provided by SAP HANA Cloud Platform according to the technology you prefer
and the use cases of your scenarios.

Integration with SAP and non-SAP software


SAP HANA Cloud Platform facilitates secure integration with on-premise systems running software from SAP and
other vendors. Using the platform services, such as the connectivity service, applications can establish secure
connections to on-premise solutions, enabling integration scenarios with your cloud based applications.

In-memory persistence
SAP HANA Cloud Platform includes persistence powered by SAP HANA, taking full advantage of its real-time, inmemory computing technology and built-in analytics.

Secure data
Comprehensive, multilevel security measures have been built into SAP HANA Cloud Platform. This security is
engineered to protect your mission critical business data and assets and to provide the necessary industry
standard compliance certifications.

Free trial
You can start by getting a free SAP HANA Cloud Platform developer license on SAP HANA Cloud Platform
Developer Center that also gives you access to our community and all the free technical resources, tutorials,
blogs, support you need.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Related Information
SAP HANA Cloud Platform
Develop Applications [page 950]
Services [page 264]
Tools [page 81]
Identity and Access Management [page 1205]
Get Support [page 1325]
SAP HANA Cloud Platform Developer Center
openSAP: Introduction to SAP HANA Cloud Platform

1.1.1 Product Prerequisites and Restrictions

General Constraints
SAP HANA Cloud Platform has Java SE 7 Hotspot compatible JVM and supports bytecode compiled in Java
SE 7 Hotspot format.
Upload limit: the size of an application deployed on SAP HANA Cloud Platform can be up to 1.5 GB. If the
application is packaged as a WAR file, the size of the unzipped content is taken into account.
SAP HANA Cloud Platform exposes applications only via HTTPS. For security reasons, applications cannot be
accessed via HTTP.
Language support: you can develop and run applications on the platform, which supports any set of
languages. The documentation and the user intefaces (UI) of the platform itself are only available in English.

SAP HANA Cloud Platform Tools


SAP HANA Cloud Platform Tools for Java and SDK have been tested on Windows 7 (64 bit) with Java
Standard Edition 6 (Java SE 6).
SAP HANA Cloud Platform Tools for Java and SDK run fine in many operating environments with Java SE 6
and Java SE 7 that are supported by Eclipse. However, we do not systematically test all platforms.
SAP HANA Cloud Platform Tools for Java must be installed on Eclipse IDE for Java EE developers.
To be able to deploy your application in a customer account, you have to use SAP HANA Cloud Platform Tools
version 0.24.4.3 or higher.
For JCo-enabled applications, the SDK local runtime needs to be hosted by a 64-bit JVM.
For the specific requirements for the platform development tools, SDK, Cloud connector, SAP JVM, see https://
tools.hana.ondemand.com/#cloud

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Browser Support
For UIs of the platform itself, such as the SAP HANA Cloud Platform Cockpit, the following browsers are
supported on Microsoft Windows PCs and where mentioned below on Mac OS X:
Browser

Versions

Microsoft Internet Explorer

11

Mozilla Firefox

Extended Support Release (ESR) and latest version

Google Chrome

Latest version

Safari

7.0 and upwards (for Mac OS X only)

If you are developing an SAPUI5 application, for the list of supported browsers see Browser and Platform
Matrixes.
For security reasons, SAP HANA Cloud Platform does not support TLS1.0, SSL 3.0 and older, and RC4 based
cipher suites. Make sure your browser supports at least TLS1.1 and modern ciphers (for example, AES).

Services
You can find the restrictions related to each SAP HANA Cloud Platform service in the respective service
documentation:
Connectivity Service [page 267]
Persistence Service [page 720]
Document Service [page 545]

Accounts
For more information about the limitations of each type of account (developer, customer, partner), see Account
Types [page 12]

1.2

Get Started

Table 2:
To learn about

See

The different technologies provided by SAP HANA Cloud Plat


form

Java: Getting Started [page 33]


SAP HANA: Getting Started [page 57]
HTML5: Getting Started [page 66]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

To learn about

See
SAPUI5: Read Me First

How to create a cloud application

Creating Your First Cloud Application [page 10]

What account you need

Accounts [page 11]

The ready-to-use sample scenarios

Tutorials [page 76]

1.2.1 Creating Your First Cloud Application

Build your first application on the platform based on your preference for development technology and language.
You might want to try several of the tutorials in these tables.

Note
The Import option for some technologies means that sample applications are available, which you can import
in your Eclipse IDE.

SAP HANA
Table 3:
Workbench

Hello World!

Eclipse IDE

Creating an SAP HANA XS Application [page 59]


See also: 8 Easy Steps to Develop an XS Application

Java
Table 4:
Eclipse IDE

Hello World!

Import

Samples [page 51]


See also: Granny's Addressbook - a typical Java web app

10

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

HTML5
Table 5:
Web IDE

Hello World Tutorial Using SAP Web IDE (recommended) [page 66]

Eclipse IDE

Hello World! [page 70]


See also: Lightweight HTML5 app

SAPUI5
Table 6:
Workbench

Hello World!

Web IDE

Hello World!

Tool Independent

Hello World!

1.2.2 Accounts
SAP HANA Cloud Platform provides free and paid accounts, a self-service to create accounts, and a member
management feature for setting up teams.

Global Accounts
Accounts are organized in a global account. A global account corresponds to a customer who buys an account for
deploying applications on the cloud platform. The customer data, billing information, and purchased quota (such
as Java quota) are stored in a global account. In the global account, administrators create accounts for
developers, partners and customers and assign the available quota to the accounts. It is possible to reallocate
quota between several accounts in the same global account. New accounts are assigned automatically to the
global account. The global account is the same on all landscapes.

Note
The global account feature is not available in a trial environment. As a user working in a trial environment, you
see your account in which you deploy and run applications.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

11

Developer, Customer, and Partner Accounts


You can use a developer, customer, or a partner account to deploy and run your applications on the cloud
platform.
For more information, see Account Types [page 12].

Related Information
Getting an Account [page 12]
Account Types [page 12]
Managing Accounts and Quota [page 17]
Managing Members [page 23]
Account Member Roles [page 27]
Using Beta Features in Accounts [page 22]

1.2.2.1

Getting an Account

To deploy applications on SAP HANA Cloud Platform, you need an account that corresponds to your role.

Related Information
Account Types [page 12]
Signing Up for a Developer Account [page 15]
Purchasing a Customer Account [page 16]
Joining the Partner Program [page 16]
Cockpit [page 84]

1.2.2.1.1

Account Types

SAP HANA Cloud Platform provides free and paid accounts: developer, customer, and partner accounts. The
account type determines pricing, conditions of use, resources, services available, and landscape host. Each
account is associated with a region, which represents the location of the data center used by that account.
While developer accounts use the trial landscape, which is located in Europe only, customer and partner accounts
use a productive landscape, which is available on a regional basis.
The specific landscape associated with an account is relevant when you deploy applications (landscape host) and
access the SAP HANA Cloud Platform cockpit (cockpit URL).

12

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
You can have several accounts in one or more landscapes. Your accounts are independent of each other, even
if you have accounts of the same name in different regions. The data center assigned to your account is not
directly related to your location. You could be located in the United States, for example, but operate your
account in Europe.
The main features of each account type are described below:
Table 7:

Use case

Developer Account

Customer Account

Partner Account

A developer account enables you

A customer account enables you

A partner account enables you to

to explore the basic SAP HANA

to host productive, business-criti

build applications and to sell them

Cloud Platform functionality for a

cal applications with 24x7 support. to your customers.

non-committal and unlimited pe


riod. Access is open to everyone.

You can purchase a customer ac


count just like any other SAP soft
ware.

Benefits

Free of charge

Support for productive applica

Self-service registration

tions

Unlimited period

A trial tenant database on a

It includes SAP Application


Development licenses to ena
ble you to get started with
scenarios across cloud and
on-premise applications.

shared HANA MDC system

that you can use for 12 hours.

It offers the opportunity to


certify applications and re
ceive SAP partner logo pack

Restriction

age with usage policies.

After 12 hours, it will be

shut down automatically

Partners can advertise and


sell applications via the SAP

to free resources (see Da

Store

tabases and Database


Systems [page 770]).
If you do not use the ten
ant database for 7 days, it
will be automatically de
leted.

Multiple deployed Java appli

Automatic access to SAP

cations
HANA Cloud Portal, SAP Mo
bile Platform, and Gateway as
a Service
Services availa Productive and beta services

Productive and beta services

Productive and beta services

ble

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

13

Developer Account
Limitations

Customer Account

Partner Account

One running Java application

Resources according to your con

Predefined resources according to

1 GB of database storage

tract

your partner package. More can

1 GB of document storage

One user per account

One SAP HANA tenant data

be purchased if there is a need.

base

100MB for all Git repositories

Two configured on-premise


systems with the Cloud con
nector

Cloud connector supported


only for Java and HTML5 ap
plications

No service level agreement


with regards to the availability
of the platform

Registration

For information about how to reg

For more information, see https:// To join the partner program, sign

ister, see Signing Up for a Devel

hcp.sap.com/pricing.html

oper Account [page 15].

Contact us on SAP HANA Cloud


Platform

up at the SAP Application Devel


opment Partner Center

or via an SAP sales

representative.
Landscape

hanatrial.ondemand.com

See Landscape Hosts [page 32]

See Landscape Hosts [page 32]

host

Related Information
Accounts [page 11]
Landscape Hosts [page 32]
Cockpit [page 84]
Managing Accounts and Quota [page 17]
Using Beta Features in Accounts [page 22]
Databases and Database Systems [page 770]

14

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.2.1.2

Signing Up for a Developer Account

A developer account gives you access to the trial landscape for an unlimited period and is free of charge. You can
only have one developer account.

Procedure
1. Go to the SAP HANA Cloud Platform landing page (https://account.hanatrial.ondemand.com).
2. Depending on whether or not you already have a user ID, proceed as follows:
Do you already have a user ID?

Do the following

No.

Youd like to register with the SAP ID service and create a developer account.
1. Click Register.
2. On the registration screen, enter the required data and confirm by clicking
Register.
Youll receive a confirmation e-mail with instructions to activate your ac
count.
3. Click the link in the e-mail to confirm your address and to activate your ac
count.

Yes.

You just want to create a developer account.


1. Click Log On and sign in with your user credentials.
2. Read and accept the SAP HANA Cloud Developer Edition License Agree
ment.

Your developer account is now automatically created. The cockpit opens and shows the dashboard of your
newly created account.

Results
The name of your new developer account contains your user ID and the suffix trial, for example,
p0123456789trial. Note the following points:
Developer accounts are intended for personal exploration, and not for use in a productive environment or for
team development. You can't assign members to the account (you won't see the Members list).
A developer account has only one virtual machine (VM) at its disposal. You can deploy multiple applications,
but you can start only one application at any one time.
Applications will be stopped automatically after a certain period of time for cleanup purposes.
When deploying to the cloud, remember to use the SAP HANA Cloud Platform landscape host
hanatrial.ondemand.com.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

15

Related Information
Cockpit [page 84]
Landscape Hosts [page 32]

1.2.2.1.3

Purchasing a Customer Account

A customer account allows you to host productive, business-critical applications with 24x7 support.
When you want to purchase a customer account, you can select from a set of predefined packages. For more
information, see https://hcp.sap.com/pricing.html . Contact us on SAP HANA Cloud Platform
or via an SAP
sales representative.
In addition, you can upgrade and refine your resources later on. You can also contact your SAP sales
representative and opt for a configuration, tailored to your needs.
After you have purchased your customer account, you will receive an e-mail with a link to the landing page of SAP
HANA Cloud Platform.

Related Information
Signing Up for a Developer Account [page 15]
Joining the Partner Program [page 16]
Account Types [page 12]

1.2.2.1.4

Joining the Partner Program

A partner account enables you to build applications and to sell them to your customers.
To become a partner, you need to fill in an application form and then sign your partner contract. You will be
assigned to an account with the respective resources. To apply for the partner program, visit https://
www.sapappsdevelopmentpartnercenter.com/en/signup/new/ . You will receive a welcome mail with further
information afterwards.
General information about the partner program is available on https://
www.sapappsdevelopmentpartnercenter.com/en/get-started/cloud-applications/

Related Information
Signing Up for a Developer Account [page 15]
Purchasing a Customer Account [page 16]

16

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Account Types [page 12]

1.2.2.2

Managing Accounts and Quota

You can manage accounts and assign the quota available for a global account to the accounts associated with this
global account.
Prerequisites
You have the Administrator role for the account in question to be able to manage the account, its members, and
the quota.
As an administrator you have the rights to perform typical account administration tasks, for example:
Create, edit, and delete accounts
Assign the quota purchased for a global account to individual accounts
Add members to accounts and assign roles to them
Copy attributes including destinations, trust settings, roles, and members from existing accounts to the newly
created account
Enable the use of beta features in the account

Note
You can manage accounts and quota using the cockpit or the console client commands.

Related Information
Accounts [page 11]
Creating Accounts [page 18]
Defining Account Details [page 19]
Deleting Accounts [page 21]
Managing Account Quota [page 21]
Using Beta Features in Accounts [page 22]
Using Multiple Accounts for Staged Application Development [page 1160]
Multitenant Applications [page 990]
create-account [page 110]
delete-account [page 125]
list-accounts [page 187]
set-quota [page 237]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

17

1.2.2.2.1

Creating Accounts

You can create accounts and use a copy function to copy settings from other accounts.

Prerequisites
You have the Administrator role for the account.

Context
The overview of accounts available to you is your starting point for creating accounts in the cockpit.
The new account is added as a new tile in the overview from where you can perform further actions. You are
automatically assigned as a member of the newly created account.

Note
Account creation happens in the background. Some details including the account name and description are
available right away, while the settings you select for copy will only be created in the background with some
delay. There is no notification that the account has been created.
You can enable an account to use beta features made available by SAP for SAP HANA Cloud Platform from timeto-time. This option is available to administrators only and deselected by default for your productive landscape.

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use of
the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by
the use of beta features.

Procedure
1. Log on to the cockpit and go to the overview page of available accounts.
The accounts are displayed as tiles.
2. Choose New Account.
3. Specify a display name.
4. (Optional) Specify a description.
5. (Optional) To enable the use of beta features in the account, select the Enable checkbox.
6. (Optional) To copy settings from an existing account, select the checkbox. The details for the copy function
are displayed. Select an account from the list and select the settings that should be copied to the new
account.

18

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can copy trust settings, destinations, and members.


7. Save your changes.

Next Steps
The newly created account is displayed on the overview page of available accounts.

Related Information
create-account [page 110]
Account Types [page 12]
Defining Account Details [page 19]
Deleting Accounts [page 21]
Managing Account Quota [page 21]
Using Beta Features in Accounts [page 22]

1.2.2.2.2

Defining Account Details

You can view and change the details of the currently selected account.

Prerequisites
You have the Administrator role for the account.

Context
The overview of accounts available to you is your starting point for viewing and changing account details in the
cockpit. Accounts available in a global account are organized in tiles. Each tile shows details about the account
including the number of deployed Java applications, members, and the quota information.
To view or change the details for an account, trigger the intended action directly from the tile, for example by
choosing the pencil icon to edit the account details. To view more details about the account such as its description
and additional attributes like beta and extension, click Show More to expose the backside of the tile.
The account name is a unique identifier of the account on the cloud platform that is automatically generated when
the account is created. You use this account name as a parameter for the console client commands.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

19

You can make changes to the following account details:


Display name: Specify a human-readable name for your Java application and change it later on, if necessary.
This way you can distinguish more easily your accounts in case you have more than one.
Description: Specify a short descriptive text about the Java application, typically stating what it does.
Beta Features: Enable the account to use beta features made available by SAP for SAP HANA Cloud Platform
from time-to-time. This option is available to administrators only and deselected by default for your
productive landscape.

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use
of the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages
caused by the use of beta features.
Default Database: Select a different default database from the list of default databases available for the
account.

Procedure
1. Log on to the cockpit and go to the list of accounts available to you.
The accounts are displayed as tiles.
2. Choose the

(edit) icon on the tile for the account in question.

3. Specify or modify the display name.


4. (Optional) Specify or modify the description.
5. (Optional) To enable the use of beta features in the account, select the checkbox.
6. (Optional) Select a different default database.
7. Save your changes.

Related Information
Creating Accounts [page 18]
Using Beta Features in Accounts [page 22]
Changing the Default Database System [page 810]

20

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.2.2.3

Deleting Accounts

You can delete the currently selected account.

Prerequisites
You have the Administrator role for the account.

Context
You can only delete the accounts you have created yourself and that do not have non-shared database systems,
database schemas, deployed applications, HTML5 applications, or subscriptions. You cannot delete the last
remaining account from the global account in question.
The overview of accounts available to you is your starting point for deleting accounts in the cockpit.

Procedure
1. Log on to the cockpit and go to the list of accounts available to you.
The accounts are displayed as tiles.
2. Choose Delete (trashcan icon) on the tile for the account in question and confirm the operation.

1.2.2.2.4

Managing Account Quota

You can view details about the quota purchased for a global account (such as Java quota) and how it is distributed
between the accounts in this global account. As long as there are free quotas, you can freely distribute them
between the accounts.

Prerequisites
You have the Administrator role for the accounts for which you want to manage the quota.

Context
The overview of accounts available to you is your starting point for viewing quota information in the cockpit. The
overview shows the different quotas in use, how they are distributed between individual accounts, and how many

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

21

free quotas there are for which purchased edition. For example, there are 2 free Java quotas out of 5 that can be
used in the different accounts.
On the Quota Management page in the cockpit, you can view quota information and manage quota for the
currently selected global account. The quota purchased for a global account is available to the applications
deployed in all accounts in this global account. Quotas are sold in different editions. You can free quotas by
removing them from an account.
Use the + and buttons to adjust the quota in the specified limits.
Note the following:
The Edit option on the Quota Management will only be enabled if you have the Administrator role for at least
one account in this global account.
You need the Administrator role for the account in question to be able to change the quota. Otherwise, the +
and buttons are disabled and you can only view how the quota is distributed.
There is a category Other Accounts for which the total quota of all accounts belonging to this category is
displayed, but no details. These are the accounts to which you are not assigned as member and that you
cannot access.
You cannot decrease quota any further if it is still in use. You first need to release some resources before you
can continue (that means, stop some of the applications or processes in that account).
You cannot increase quota any further if you have reached the limit of your purchased quota because you
have distributed all the available quota already.

Procedure
1. Log on to the cockpit and choose Quota Management in the navigation area.
2. Choose Edit.
3. Change the quota as needed and save your changes.

Related Information
Compute Units [page 959]
list-accounts [page 187]
set-quota [page 237]

1.2.2.3

Using Beta Features in Accounts

SAP may offer and a customer may choose to accept access to functionality that is not generally available and is
not validated and quality assured in accordance with SAPs standard processes. Such functionality is defined as a
beta feature.

22

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The aim of the beta features is to enable customers, developers, and partners to test new features on SAP HANA
Cloud Platform. The beta features have the following characteristics:
SAP may require that customers accept additional terms to use beta features.
The beta features are either released on productive landscapes for customer and partner accounts, or on trial
landscapes for developer accounts, or on both landscapes.
You can enable some of the beta features in the SAP HANA Cloud Platform cockpit. In the overview of
(edit) icon on the tile for the account in question and then select
accounts available to you, choose the
the checkbox to enable the use of beta features.
No personal data may be processed by beta functionality in the context of contractual data processing
without additional written agreement.

Caution
You should not use SAP HANA Cloud Platform beta features in productive accounts. Any productive use of the
beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by the
use of beta features.

Related Information
Managing Accounts and Quota
Account Types
Landscape Hosts

1.2.2.4

Managing Members

Use the cockpit to manage users and their roles. You can add and remove users for an account and select and
deselect roles. All members assigned to the selected account can use the functionality provided by SAP HANA
Cloud Platform in the scope of this account and as permitted by their assigned account member roles. These
roles support typical tasks performed by users when interacting with the platform.

Prerequisites
You have the Administrator role for the account.
You have the SAP user IDs of the members that you want to add.

Tip
Users can request user IDs at the SAP Service Marketplace: http://service.sap.com/request-user
SAP Service Marketplace users are automatically registered with the SAP ID service, which controls user
access to SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

23

Context
Note the following:
A user can be assigned to more than one account.
A user can be assigned any number of roles. The role assignment is account-specific.
Roles apply to all operations associated with the account, irrespective of the tool used (Eclipse-based tools,
cockpit, and console client).
Roles determine which panels are visible in the cockpit and which actions users can initiate.
As an administrator, you cannot remove your own administrator role. You can remove any member except
yourself.

Procedure
1. Log on to the cockpit and go to the list of accounts available to you.
The accounts are displayed as tiles.
2. Select an account.
3. Choose Members in the navigation area.
All members currently assigned to the account are displayed in a list.

Note
The name of a member is displayed only after the member visits the account for the first time.
4. Choose Add Members.
5. Enter one or more user IDs.
There is currently no user validation. You can use commas, spaces, semicolons, or line breaks to separate
members.
6. Select the corresponding roles for the new members and save your changes.

Next Steps
You also have the following options:
To select or deselect roles for a member, choose the
roles take effect immediately.

(edit) icon. The changes you make to the member's

You can enter a comment when editing user roles. This provides you with an effective and simple way of
tracking the reasons for account membership and other important data. The comments are visible to all
members.
You can send an e-mail to a member. This option is displayed only after the recipient visits the account for the
first time.
To remove all the roles of a member, choose Delete (trashcan icon). This removes the member from the
account.

24

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To check the member history, choose the History button to view a list of changes to members (for example,
added or removed members, or changed role assignments).
To filter the member list for a specific role, use the filter to show only the members with this role.

Related Information
Cockpit [page 84]
Account Member Roles [page 27]

1.2.2.4.1

Enabling Application Providers to Access Your


Account

If your scenario requires it, you can add application providers as members to your SAP HANA Cloud Platform
customer account and assign them the administrator role so that they can deploy and administer the applications
you have purchased.

Prerequisites
You have a SAP HANA Cloud Platform customer account.
You are an administrator within the account.
Your application provider has sent you the user ID of the user responsible for deploying and managing the
applications you have purchased.

Tip
You can request user IDs at the SAP Service Marketplace: http://service.sap.com/request-user
SAP Service Marketplace users are automatically registered with the SAP ID service, which controls user
access to SAP HANA Cloud Platform.

Context
As an administrator of your SAP HANA Cloud Platform customer account, you can add members to it and make
these members administrators of the account using the SAP HANA Cloud Platform cockpit. For example, if you
have purchased an application from an SAP implementation partner,you may need to enable the SAP
implementation partner to deploy and administer the application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

25

Procedure
1. In your Web browser, open the SAP HANA Cloud Platform cockpit using the URLs given below. Use the
relevant URL for the region with which your customer account is associated:
Europe: https://account.hana.ondemand.com/cockpit
United States: https://account.us1.hana.ondemand.com/cockpit (US East), and https://
account.us2.hana.ondemand.com/cockpit (US West)
Asia-Pacific: https://account.ap1.hana.ondemand.com/cockpit
The cockpit provides integrated access to all accounts you operate on the productive landscape.
2. In the cockpit, select the customer account to which you want to add members.
3. In the navigation area, choose Members.
Make sure that you have selected the relevant global account to be able to select the right account.
All members currently assigned to the account are displayed in a list.
4. In the Members section, choose Add Members.
5. In the Add Members dialog box, enter the user IDs you have received from your application provider and then
select the Administrator checkbox.
To separate the entries, use comma, space, or semicolon. The user IDs are case-insensitive and contain
alphanumeric characters only. Note that currently there is no user validation.

Note
The Developer checkbox is selected by default. Make sure you do not deselect this checkbox.
6. Choose Add Members.
The changes take effect immediately. The users are added to the list of team members and are assigned the
developer and the administrator role. They can now deploy and administer applications in your account.

Note
You cannot remove your own administrator role.
7. Notify your application provider that they now have the necessary permissions to access the account.

Related Information
Managing Members [page 23]
Cockpit [page 84]

26

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.2.5

Account Member Roles

SAP HANA Cloud Platform delivers predefined roles supporting the typical tasks performed by users when
interacting with the platform.

Roles
Table 8:
Role

Description

Administrator

Enables you to manage account members, create new accounts using the self-service op
tion, and move quota between accounts (prerequisite: you are an administrator in each
account).
You can also manage subscriptions, trust, authorizations, and OAuth settings, and restart
SAP HANA services on HANA databases.
In addition, you have all permissions granted by the developer role, except the debug per
mission.

Note
This role also grants permissions to view the Connectivity tab in the SAP HANA Cloud
Platform cockpit.

Cloud Connector Admin

Enables to open secure tunnels via Cloud Connector from on-premise networks to your
cloud accounts.

Note
This role also grants permissions to view the Connectivity tab in the SAP HANA Cloud
Platform cockpit.
Developer

Supports typical development tasks, such as deploying, starting, stopping, and debugging
applications. You can also change loggers and perform monitoring tasks, such as creating
availability checks for your applications and executing MBean operations.

Note
This role is assigned to a newly created user by default.
Support User

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Designed for technical support engineers, this role enables you to read almost all data re
lated to an account, including its metadata, configuration settings, and log files. Note that
to be able to read database content, a database administrator must assign the appropri
ate database permissions to you.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

27

Role

Description

Application User Admin

The account administrator assigns an account member the Application User Admin role.
This role enables you to manage user permissions on application level to access Java,
HTML5 applications, and subscriptions. You can control permissions directly by assigning
users to specific application roles or indirectly by assigning users to groups, which you
then assign to application roles. You can also unassign users from the roles or groups.

Note
The Application User Admin role does not enable you to manage account roles and to
perform actions on account level (for example, stopping or deleting applications).

Related Information
Managing Members [page 23]
Guidelines for Creating Database Users [page 1013]
Working with Git [page 1042]
Managing Roles [page 1282]
Managing Roles and Permissions [page 1177]

1.2.2.6

Managing Subscriptions

Subscriptions represent applications that your account has purchased for use from an application provider. As
the consumer account, you do not own, deploy, or operate these applications yourself. Subscriptions allow you to
configure certain features of the applications and launch them through consumer-specific URLs.

Context
Applications that you use on a subscription basis are referred to as multitenant applications. The subscription
needs two accounts to work. One is the account in which the application is running, that is, the provider account
and the other is the account that will be subscribed to the application, that is, the consumer account. As the
consumer account, you are identifiable to the application provider by a unique tenant ID. The application provider
is responsible for operating and maintaining the applications you use as well as billing you for platform resources
consumed by these applications according to the price model they have defined.

Note
You can subscribe an account to an application that is running in another account only if both accounts
(provider and consumer account) belong to the same landscape.

28

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can list all Java and HTML5 applications to which your account is subscribed using the cockpit (described
below). To list Java subscriptions you can also use the console client. In the cockpit, you can navigate to the
subscription overview, where you can do the following:
Launch the applications through dedicated (consumer-specific) URLs
Switch to the Destinations panel, where you can configure connection parameters to other systems by
creating connectivity destinations (only for subscriptions to Java applications).
Switch to the Roles panel, where you can create custom roles for your subscribed applications and assign
roles (custom or predefined) to individual users and groups.
Display the log files of the subscription (only for subscriptions to HTML5 applications).
Create a new subscription (only for subscriptions to HTML5 applications).
Managing Java Subscriptions [page 29]
Managing HTML5 Subscriptions [page 30]

Related Information
Account Types [page 12]
Landscape Hosts [page 32]
Remote Database Access [page 849]
Cockpit [page 84]
Configuring Destinations from the Cockpit [page 301]
Managing Roles [page 1282]
Subscribing an Account to an Application [page 1162]
subscribe [page 248]
Multitenant Applications [page 990]
list-subscribed-applications [page 209]

1.2.2.6.1

Managing Java Subscriptions

Procedure
1. Open the account in the cockpit and choose Applications Subscriptions
subscriptions to Java applications are listed with the following information:

in the navigation area. The

The account name of the application provider from which the subscription was obtained
The name of the subscribed application
2. To navigate to the subscription overview, click the application name:
To launch an application, click the URL link in the Application URLs panel.
To create connectivity destinations, choose Destinations in the navigation area.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

29

To create or assign roles, choose Roles in the navigation area.

1.2.2.6.2

Managing HTML5 Subscriptions

Procedure
1. Open the account in the cockpit and choose Applications Subscriptions in the navigation area. The
subscriptions to HTML5 applications are listed with the following information:
The account name of the application provider from which the subscription was obtained
The name of the subscribed application
2. To navigate to the subscription overview, click the application name:
To launch an application, click the URL link in the Active Version panel.
To create or assign roles, choose Roles in the navigation area.
3. To create a new subscription, execute the following steps:
1. On the Subscribed HTML5 Applications panel in the Subscriptions section, choose New Subscription.
2. Select the provider account from the dropdown list. (You can select accounts that provided applications
to your account as well as accounts where the current user has the administrator role.)
3. Select the application to which you want to subscribe.
4. Enter a subscription name.

Note
The subscription name must be unique across all subscription names and all HTML5 application
names in the current account.

1.2.2.7

Accessing Services

The cockpit provides an overview of all the platform services that you can access und use for creating or
extending applications. You can see which of the listed services are enabled, view and modify the configuration,
and access the start page (if available) for a service. Services are grouped by service category.

Context
Some of the services are basic services, which are directly provided by the SAP HANA Cloud Platform and are
ready-to-use. In addition, extended services are available. An account administrator must enable these services
and configure the corresponding roles and destinations before account members can access these services.
To view the list of services available to you, you have the following options:

30

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Choose Services in the navigation area for the selected account.


On the overview page for the account, click the links in the Services tile.

Note
Some of the services are exposed only on the trial landscape for developer accounts. That means the services
are not, or not yet, released on the productive landscape for customer and partner accounts.
Some of the services are only exposed if you have purchased a license for them before.

Procedure
1. To display only the services for a specific category, use the filter function.
This makes it easier to find the relevant service in the service overview. You can view all the services in the
overview, or filter the list of services for services in a selected category.
2. To enable a service, choose the tile of the service, and then choose Enable.
This option is available only to account administrators and for the services that need further enablement.
3. To perform administrative tasks, choose the tile for the respective service. The overview page for the service
is displayed.
The overview page shows a description of the service and several links, including links to the documentation
available for the service, the service start page, and configuration options. The availability of the links differs
for each service.
4. On the overview page for the service, you have the following options:
a. To read the documentation available for each service, click the Documentation link.
b. To go to the start page for the service, click the Go to Service link.
This link is available only if the following applies:
The service is enabled.
The service has a start page, on which you can perform administrative tasks.
c. To configure parts of a service, click the link (there could be more than one link) in the configuration
section.
The configuration options are specific to each service. For example, for some services there can be
several links, while for other services there could be none. For details, please read the product
documentation available for each service.
The configuration options for a service may look like in this example for SAP HANA Cloud Portal:
To configure connection parameters to other systems (by creating connectivity destinations), choose
Configure <Configure SAP HANA Cloud Portal>

Destinations .

This option is available only if the service is enabled.


To create custom roles and assign custom or predefined roles to individual users and groups, choose
Configure <Configure SAP HANA Cloud Portal>

Roles .

This option is available only if the service is enabled.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

31

Related Information
Cockpit [page 84]
Services [page 264]
Using Beta Features in Accounts [page 22]

1.2.2.8

Landscape Hosts

Applications can be deployed on the productive landscape hana.ondemand.com or the trial landscape
hanatrial.ondemand.com.
Use the landscapes as follows:
Productive landscape - represents the productive environment; it can be used by customer and partner
accounts only.
Trial landscape - represents the platform for testing the SAP HANA Cloud Platform functionality. To use this
platform, you need a developer account.
The productive landscape is available on a regional basis, where each region represents the location of a data
center:
Europe (the central region): hana.ondemand.com
United States: us1.hana.ondemand.com (US East) and us2.hana.ondemand.com (US West)
Asia-Pacific (Australia): ap1.hana.ondemand.com
When deploying applications, bear in mind that a customer or partner account is associated with a particular data
center and that this is independent of your own location. You could be located in the United States, for example,
but operate your account in Europe (that is, use a data center that is situated in Europe).
To deploy an application on more than one landscape, execute the deploy separately for each landscape host.
The landscape hosts to be used are listed below:
Table 9:
Account Type

Data Center

Landscape Host

IP Ranges

Customer or partner account

Europe

hana.ondemand.com

155.56.128.0/17

United States (US East)

us1.hana.ondemand.com

65.221.12.0/24

United States (US West)

us2.hana.ondemand.com

206.112.73.0/24

Asia-Pacific (Australia)

ap1.hana.ondemand.com

210.80.140.0/24

Europe (all developer ac

hanatrial.ondemand.com

155.56.128.0/17

Developer (trial) account

counts use this location)

Tip
Developer accounts have a suffix trial. For example: P1234567890trial.

32

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Account Types [page 12]

1.2.3 Java: Getting Started


Set up your Java development environment and deploy your first application in the cloud.
Table 10:
Sign Up
You first need to sign up for an SAP HANA Cloud account.
Set Up
Download Eclipse IDE for Java EE Developers, and set up SAP HANA Cloud Tools for Java.
Create or Import
Create a classic Java EE HelloWorld application or import an existing sample application to get started.
Deploy
Deploy your application using the Eclipse IDE.
Monitor
You can view the status and logs of your Java applications.

Samples
A set of sample applications allows you to explore the core functionality of SAP HANA Cloud Platform and shows
how this functionality can be used to develop complex Web applications. See: Samples [page 51]

Tutorials
Tutorials [page 76]

1.2.3.1

Installing Java Tools for Eclipse and SDK

Before developing your application, you need to download and set up the necessary tools, which include Eclipse
IDE for Java EE Developers, SAP HANA Cloud Platform Tools, and SDK.
For more information on the different SDK versions and their corresponding runtime environments, see
Application Runtime Container [page 955]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

33

Features
From the SAP Development Tools for Eclipse page, you can download the following:
SAP HANA Cloud Platform Tools:
SAP HANA Cloud Platform Tools for Java
SAP JVM Profiler
UI development toolkit for HTML5 (Developer Edition)
Documentation for SAP HANA Cloud Platform
SAP HANA Cloud Platform SDK - provides local server runtime, deployment tools, samples and test
applications, APIs, and javadoc.
SAP JVM - the Java runtime used in SAP HANA Cloud Platform. SAP JVM is an important prerequisite for
local profiling with SAP JVM Profiler.
SAP HANA Cloud Connector - provides a tunnel between on-demand applications in SAP HANA Cloud
Platform and existing on-premise systems.

Related Information
Installing the SDK [page 34]
(Optional) Installing SAP JVM [page 35]
Installing Eclipse IDE [page 36]
Installing SAP Development Tools for Eclipse [page 37]
Updating Java Tools for Eclipse and SDK [page 43]

1.2.3.1.1

Installing the SDK

Context
SAP HANA Cloud Platform offers several SDKs for Java development:
Java Web - provides support for some of the standard Java EE APIs (Servlet, JSP, JSTL, EL)
Java Web Tomcat 7 - provides support for some of the standard Java EE APIs (Servlet, JSTL, EL)
Java Web Tomcat 8
Java EE 6 Web Profile - certified to support Java EE 6 Web Profile APIs
For more information on Java profiles, see section Application Runtime Container [page 955].

Procedure
1. Open https://tools.hana.ondemand.com/#cloud

34

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. From the SAP HANA Cloud Platform SDK section, download the relevant ZIP file and save it to your local file
system.
3. Extract the ZIP file to a folder on your computer or network.
Your SDK is ready for use. To use the SDK with Eclipse, see Setting Up SDK Location and Landscape Host in
Eclipse [page 38]. To use the console client, see Using the Console Client [page 89].

Related Information
Application Runtime Container [page 955]
Setting Up SDK Location and Landscape Host in Eclipse [page 38]

1.2.3.1.2

(Optional) Installing SAP JVM

Context
SAP HANA Cloud infrastructure runs on SAP's own implementation of a Java Virtual Machine - SAP Java Virtual
Machine (JVM).
SAP JVM is a fully certified Java Standard Edition Virtual Machine for Java 7. It is derived from Oracles HotSpot
VM and JDK implementation, but enhanced with several supportability features such as the SAP JVM Profiler for
better monitoring, and profiling applications running on the SAP HANA Cloud local runtime. Customer support is
provided directly by SAP for the full maintenance period of SAP applications that use the SAP JVM. For more
information, see Java Virtual Machine [page 953]
Follow the steps below to install an SAP Java Virtual Machine.

Note
This is an optional procedure. You can also run your local server for SAP HANA Cloud Platform on a standard
JDK platform, that is an Oracle JVM. SAP JVM, however, is a prerequisite for local profiling with the SAP JVM
Profiler.

Procedure
1. Open https://tools.hana.ondemand.com/#cloud
2. From the SAP JVM section, download the SAP JVM archive file compatible to your operating system and save
it to your local file system.
3. Extract the archive file.

Note
If you use Windows as your operating system, you need to install the Visual C++ 2010 Runtime prior to using
SAP JVM. The installation package for the Visual C++ 2010 Runtime can be obtained from Microsoft. Download

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

35

and install vcredist_x64.exe from the following site: https://www.microsoft.com/en-us/download/


details.aspx?id=26999 . Even if you already have a different version of Visual C++ Runtime, for example
Visual C++ 2015, you still need to install Visual C++ 2010 Runtime prior to using SAP JVM. See SAP Note
1837221 .

Related Information
Setting Up SAP JVM in Eclipse IDE [page 41]
Updating SAP JVM [page 45]

1.2.3.1.3

Installing Eclipse IDE

Context
Follow the steps below to install a new Eclipse IDE.

Procedure
1. Download Eclipse IDE for Java EE Developers from http://www.eclipse.org/downloads/

Caution
The support for Kepler has entered end of maintenance. We recommend that you use Luna or Mars
releases.
2. Find the ZIP file you have downloaded on your local file system and unpack the archive.
3. Go to the eclipse folder and run the eclipse executable file.
4. Specify a Workspace directory.
5. To open the Eclipse workbench, choose Workbench in the upper right corner.

Note
If the version of your previous Eclipse IDE is 32-bit based and your currently installed Eclipse IDE is 64-bit
based (or the other way round), you need to delete the Eclipse Secure Storage, where Eclipse stores, for
example, credentials for source code repositories and other login information. For more information, see
Eclipse Help: Secure Storage .

36

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.3.1.4

Installing SAP Development Tools for Eclipse

To use SAP HANA Cloud Platform features, you first need to install the relevant toolkit. Follow the procedure
below.

Prerequisites
You have installed an Eclipse IDE. For more information, see Installing Eclipse IDE [page 36].

Caution
The support for Kepler has entered end of maintenance. We recommend that you use Luna or Mars releases.

Procedure
1. Open the Eclipse IDE.
2. Optional: If the Welcome screen is displayed and you want to open the workbench, choose Workbench in the
upper right corner.
3. In the main menu, choose

Window

Preferences .

Note
For some operating systems, the path is

Eclipse

Preferences .

4. Configure your proxy settings (in case you work behind a proxy or a firewall):
1. Go to

General

Network Connections .

2. In the Active Provider dropdown menu, choose Manual.


3. Configure your <HTTP> and <HTTPS> connections.
4. Choose Apply.
5. Choose OK to close the Preferences window.
6. In the main menu, choose

Help

Install New Software .

7. Depending on the Eclipse version you have installed, enter in the Work with field one of the following URLs:
For Eclipse Luna (4.4), add URL: https://tools.hana.ondemand.com/luna
For Eclipse Mars (4.5), add URL: https://tools.hana.ondemand.com/mars
8. Press the ENTER key.
9. Checkbox Contact all update sites during install to find required software is selected by default.
10. Select SAP HANA Cloud Platform Tools to install the whole toolkit. If you do not need the complete package,
expand the node and only select the necessary components.
11. Choose Next.
12. In the Install Details window, review the items to be installed and choose Next.
13. Read and accept the Eclipse and SAP license agreements and choose Finish.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

37

14. After the successful installation, you are prompted to restart the Eclipse IDE. Choose Yes.

Note
If you want to have your SAP HANA Cloud Platform Tools updated regularly and automatically, open the
Preferences window again and choose Install/Update
updates and notify me and choose Apply.

1.2.3.1.5

Automatic Updates . Select Automatically find new

Setting Up SDK Location and Landscape Host in


Eclipse

Prerequisites
You have installed an SDK package. For more information, see Installing the SDK [page 34].

Context
Follow the steps below to set or configure your SDK location and the landscape host on which you want to deploy
your applications.

Procedure
1. Open the Eclipse IDE.
2. Optional: If the Welcome screen is displayed and you want to open the workbench, choose Workbench in the
upper right corner.
3. In the main menu, choose
4. Choose

Server

Window

Preferences .

SAP HANA Cloud Platform .

5. Use the respective landscape host for your account type. For more information, see Landscape Hosts [page
32].
6. For SDK Location, choose the Browse... button to locate the folder within which you have extracted the
downloaded SDK ZIP file.
7. In the Account information pane, enter your account name and e-mail (or user name).

Note
If you have previously entered an account and user name for your landscape host, these names will be
prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.
8. Choose the Validate button to check whether the data on this preference page is valid.

38

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

9. Choose OK.

1.2.3.1.6

Setting Up the Runtime Environment

Prerequisites
You have downloaded an SDK archive and installed it in your Eclipse IDE. For more information, see Setting Up
SDK Location and Landscape Host in Eclipse [page 38].

Context
You need to set up your runtime environment. You can add Java Web, Java Web Tomcat 7, Java Web
Tomcat 8, or Java EE 6 Web Profile, according to the SDK you use. Follow the steps below.

Procedure
Java Web
1. In the Eclipse IDE main menu, choose
2. Choose

Server

Window

Preferences .

Runtime Environments .

3. Choose the Add button.


4. Select

SAP

Java Web .

5. Choose Next.
6. Java Web is set as default name. You can change it if needed.
7. Select radio button Use Java Web SDK from the following location.
8. If you have previously added SDK for Java Web, your SDK location is set by default and shows no errors.
Otherwise, locate your SDK using the Browse button.
9. Choose Finish.
10. Java Web is added as a server runtime environment.
11. In the Preferences window, choose OK.

Java Web Tomcat 7 Runtime


1. In the Eclipse IDE main menu, choose
2. Choose

Server

Window

Preferences .

Runtime Environments .

3. Choose the Add button.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

39

4. Select

SAP

Java Web Tomcat 7 .

5. Choose Next.
6. Java Web Tomcat 7 is set as default name. You can change it if needed.
7. Add your SDK directory:
If you have previously downloaded SDK for Java Web Tomcat 7 from Cloud Tools, choose the Browse
button to locate your SDK folder.
If you have no SDK for Java Web Tomcat 7 locally available or need the latest version, choose the
Download and Install button to download it directly from the Maven Central. You can create a new folder
to keep your workspace well-organised.
8. Choose Finish.
9. Java Web Tomcat 7 is added as a server runtime environment.
10. In the Preferences window, choose OK.

Java Web Tomcat 8 Runtime


1. In the Eclipse IDE main menu, choose
2. Choose

Server

Window

Preferences .

Runtime Environments .

3. Choose the Add button.


4. Select

SAP

Java Web Tomcat 8 .

5. Choose Next.
6. Java Web Tomcat 8 is set as default name. You can change it if needed.
7. Add your SDK directory:
If you have previously downloaded SDK for Java Web Tomcat 8 from Cloud Tools, choose the Browse
button to locate your SDK folder.
If you have no SDK for Java Web Tomcat 8 locally available or need the latest version, choose the
Download and Install button to download it directly from the Maven Central. You can create a new folder
to keep your workspace well-organised.
8. Choose Finish.
9. Java Web Tomcat 8 is added as a server runtime environment.
10. In the Preferences window, choose OK.

Java EE 6 Web Profile


1. In the Eclipse IDE main menu, choose
2. Choose

Server

Window

Preferences .

Runtime Environments .

3. Choose the Add button.


4. Select

SAP

Java EE 6 Web Profile .

5. Choose Next.
6. Java EE 6 Web Profile is set as default name. You can change it if needed.
7. Select radio button Use Java EE 6 Web Profile SDK from the following location.

40

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

8. If you have previously added SDK for Java EE 6 Web Profile, your SDK location is set by default and
shows no errors. Otherwise, locate your SDK using the Browse button.
9. Choose Finish.
10. Java EE 6 Web Profile is added as a server runtime environment.
11. In the Preferences window, choose OK.

Note
When deploying your application on SAP HANA Cloud Platform, you can change your server runtime even
during deployment. If you manually set a server runtime different than the currently loaded, you will need to
republish the application. For more information, see Deploying on the Cloud from Eclipse IDE [page 977].

Related Information
Application Runtime Container [page 955]

1.2.3.1.7

Setting Up SAP JVM in Eclipse IDE

Prerequisites
You have downloaded and installed SAP JVM, version 7.1.011 or higher.

Context
Once you have installed your SAP JVM, you can set it as a default JRE for your local runtime. Follow the steps
below.

Procedure
1. In the Eclipse IDE main menu, choose
2. Choose

Java

Window

Preferences .

Installed JREs .

3. Choose the Add button.


Standard VM is selected as the default JRE type.
4. Choose Next.
5. For the JRE home field, choose the Directory... button and browse to the SAP JVM folder within the folder to
which you previously extracted the archive.
6. Choose Finish.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

41

7. In the Preferences window, choose OK.


8. You can set SAP JVM as default or assign it to a specific SAP HANA Cloud Platform runtime.
To use SAP JVM as default for your Eclipse IDE, follow the steps:
1. Open again the Preferences window.
2. Select sapjvm<n> as default.
3. Choose OK.
To use SAP JVM for launching local servers only, follow the steps:
1. Double-click on the local server you have created (Java Web Server, Java Web Tomcat 7
Server, Java Web Tomcat 8 Server, or Java EE 6 Web Profile Server).
2. Open the Overview tab and choose Open launch configuration.
3. Select the JRE tab.
4. Choose the Alternative JRE option.
5. From the dropdown menu, select the SAP JVM version you have just added.
6. Choose OK.

Related Information
(Optional) Installing SAP JVM [page 35]
Updating SAP JVM [page 45]

1.2.3.1.8

Setting Up the Console Client

Prerequisites
You have downloaded and extracted the SDK. For more information, see Installing the SDK [page 34].

Context
SAP HANA Cloud Platform console client is part of the SDK. You can find it in the tools folder of your SDK
installation. Before using the tool, you need to configure it to work with the platform.

Procedure
1. Open the command prompt.
2. Change the current directory to the <SDK_installation_folder>\tools location, which contains the
neo.bat and neo.sh files. For example:
cd C:\HCP\SDK

42

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

cd tools
3. In case you use a proxy server, specify the proxy settings by using environment variables. You can find sample
proxy settings in the readme.txt file in the \tools folder of your SDK location.
Microsoft Windows

Note
For the new variables to be effective every time you open the console, define them using
Advanced System Settings

Environment Variables

and restart the console.

For the new variables to be valid only for the currently open console, define them in the console
itself.
For example, if your proxy host is proxy and proxy port is 8080, specify the following environment
variables:
set
set
set
set
set

HTTP_PROXY_HOST=proxy
HTTP_PROXY_PORT=8080
HTTPS_PROXY_HOST=proxy
HTTPS_PROXY_PORT=8080
HTTP_NON_PROXY_HOSTS="localhost"

If you need basic proxy authentication, enter your user name and password:
set
set
set
set

HTTP_PROXY_USER=<user_name>
HTTP_PROXY_PASSWORD=<password>
HTTPS_PROXY_USER=<user_name>
HTTPS_PROXY_PASSWORD=<password>

Linux, Mac OS X, or other Unix based OS:


export http_proxy=http://proxy:8080
export https_proxy=https://proxy:8080
export no_proxy="localhost"
If you need basic proxy authentication, enter your user name and password:
export http_proxy=http://user:password@proxy:8080
export https_proxy=https://user:password@proxy:8080
For more information, see the video tutorial

Related Information
Console Client [page 88]

1.2.3.2

Updating Java Tools for Eclipse and SDK

If you have already installed and used the SAP HANA Cloud Platform Tools, SDK and SAP JVM, you only need to
update them.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

43

Follow the steps from the relevant procedures listed below.

Related Information
Updating the SDK [page 44]
Updating SAP Development Tools for Eclipse [page 46]
Updating SAP JVM [page 45]

1.2.3.2.1

Updating the SDK

Context
If you have already installed an SDK package, you only need to update it regularly. To update your SDK, follow the
steps below.

Procedure
1. Download the new SDK version from https://tools.hana.ondemand.com/#cloud
2. Unzip the SDK to a new directory on your local file system. Do not install the new SDK version to a directory
that already contains SDK.
3. Configure the location of the new SDK version in the Eclipse IDE:
HANA Cloud Platform

Window

Preferences

Server

SAP

SDK Location .

Note
If the SDK version is higher and not supported by the version of your SAP HANA Cloud Platform Tools for
Java, a message appears prompting you to update your SAP HANA Cloud Platform Tools for Java. You can
check for updates (recommended) or ignore the message.
4. Go to the Servers tab view.
5. Stop and delete all local servers.
6. Choose Window Preferences Server
For each previously added local runtime:

Runtime Environment .

1. Select the corresponding entry in the table.


2. Choose the Edit button.
3. Locate the new SDK version:
For Java Web: Select option Use Java Web SDK from the following location and then choose the
Browse button and find the folder where you have unpacked the SDK ZIP file.
For Java Web Tomcat 7: Choose the Browse button and find the folder where you have unpacked
the SDK ZIP file or use the Download and Install button to get the latest version.

44

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For Java Web Tomcat 8: Choose the Browse button and find the folder where you have unpacked
the SDK ZIP file or use the Download and Install button to get the latest version.
For Java EE 6 Web Profile: Select option Use Java EE 6 Web Profile SDK from the following
location and then choose the Browse button and find the folder where you have unpacked the SDK
ZIP file.

Note
Again, if the SDK version is higher and not supported by the version of your SAP HANA Cloud Platform
Tools for Java, a message appears prompting you to update your SAP HANA Cloud Platform Tools for
Java. You can check for updates (recommended) or ignore the message.
4. Choose Finish.
7. After editing all local runtimes, choose OK.

Related Information
Installing the SDK [page 34]
Application Runtime Container [page 955]

1.2.3.2.2

Updating SAP JVM

Context
If you have already installed an SAP Java Virtual Machine, you only need to update it. To update your JVM, follow
the steps below.

Procedure
1. Download the new SAP JVM version from https://tools.hana.ondemand.com/#cloud
2. Extract the SAP JVM archive locally on your machine to a new directory.

Note
Do not install the new SAP JVM version to a directory that already contains SAP JVM.
3. In the Eclipse IDE main menu, choose Window
configuration entry of the old SAP JVM version.

Preferences

Java

Installed JREs

and select the JRE

4. Choose the Edit... button.


5. Use the Directory... button to select the directory of the new SAP JVM version.
6. Choose Finish.
7. In the Preferences window, choose OK.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

45

Related Information
(Optional) Installing SAP JVM [page 35]
Setting Up SAP JVM in Eclipse IDE [page 41]

1.2.3.2.3

Updating SAP Development Tools for Eclipse

Context
If you have already installed SAP HANA Cloud Platform Tools, you only need to update them. To do so, follow the
steps below.

Procedure
1. Ensure that the SAP HANA Cloud Platform Tools software site is checked for updates:
1. Find out whether you are using a Kepler, Luna, or Mars release of Eclipse. The name of the release is
shown on the welcome screen when the Eclipse IDE is started.

Caution
The support for Kepler has entered end of maintenance. We recommend that you use Luna or Mars
releases.
2. In the main menu, choose

Window

Preferences

Install/Update

Available Software Sites .

3. Make sure there is an entry https://tools.hana.ondemand.com/kepler, .../luna, or .../mars,


and that the entry is selected.
4. Choose OK to close the Preferences dialog box.
2. Choose

Help

Check for Updates .

3. Choose Finish to start installing the updates.

Note
If you want to have your SAP HANA Cloud Platform Tools updated regularly and automatically, open the
Preferences window again and choose Install/Update
updates and notify me and choose Apply.

Automatic Updates . Select Automatically find new

Related Information
Installing SAP Development Tools for Eclipse [page 37]

46

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.3.3

Creating a HelloWorld Application

This document describes how to create a simple HelloWorld Web application, which you can use for testing on
SAP HANA Cloud Platform.
First, you create a dynamic Web project and then you add a simple HelloWorld servlet to it.
After you have created the Web application, you can test it on the local runtime and then deploy it on the cloud.

Prerequisites
You have installed the SAP HANA Cloud Platform Tools. For more information, see Installing Java Tools for Eclipse
and SDK [page 33].
Make sure you have downloaded the JRE that matches the SDK.
If you work in a proxy environment, set the proxy host and port correctly.

1. Create a Dynamic Web Project


1. Open your Eclipse IDE for Java EE Developers and switch to the Workbench screen.
2. From the Eclipse IDE main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter HelloWorld.


4. In the Target Runtime pane, select the runtime you want to use to deploy the HelloWorld application. In this
tutorial, we use Java Web.
5. In the Configuration pane, use the default configuration.

Note
The application will be provisioned with JRE version matching the Web project Java facet. If the JRE version
is not supported by SAP HANA Cloud Platform, the default JRE for the selected SDK will be used (SDK for
Java Web and for Java EE 6 Web Profile JRE 7).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

47

6. Optional: If you want your context root to be different from "HelloWorld", proceed as follows:
1. Choose the Next button until you reach the Web Module wizard page.
2. Edit the Context root field. If you want to deploy the application in the server's root, just replace the
current string with "/".

48

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

7. Choose Finish.

2. Create a HelloWorld Servlet


1. On the HelloWorld project node, open the context menu and choose
Servlet opens.

New

Servlet

. Window Create

2. Enter hello as Java package and HelloWorldServlet as class name.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

49

3. Choose Next.
4. In the URL mappings field, select /HelloWorldServlet and choose Edit.
5. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

6. Choose Finish to generate the servlet. The Java Editor with the HelloWorldServlet opens.
7. Replace the body content of the doGet() method with the following line:
response.getWriter().println("Hello World!");
8. Save your changes.

Next Steps
Test your HelloWorld application locally and deploy it to SAP HANA Cloud Platform. For more information, see
Deploying and Updating Applications [page 973].

50

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.3.4

Samples

The sample applications allow you to explore the core functionality of SAP HANA Cloud Platform and show how
this functionality can be used to develop more complex Web applications. The samples are included in the SDK or
presented as blogs in the SCN community.

SDK Samples
The samples provided as part of the SAP HANA Cloud Platform SDK introduce important concepts and
application features of the SAP HANA Cloud Platform and show how common development tasks can be
automated using build and test tools.
The samples are located in the <sdk>/samples folder. The table below lists the samples currently available:
Table 11:
Sample

Feature

More Information

hello-world

A simple HelloWorld Web application

Creating a HelloWorld Application [page 47]

explore-ui5

SAPUI5 controls

authentication

HTTP BASIC authentication scheme

User Authentication [page 1213]

connectivity

Consumption of Internet services

Consuming Internet Services (Java Web or Java EE 6


Web Profile) [page 348]

persistence-with-ejb

Container-managed persistence with JPA

Adding Container-Managed Persistence With JPA (Java


EE 6 Web Profile SDK) [page 724]

persistence-with-jpa

Application-managed persistence with


JPA

Adding Application-Managed Persistence With JPA


(Java Web SDK) [page 735]

persistence-with-jdbc

Relational persistence with JDBC

Adding Persistence With JDBC (Java Web SDK) [page


746]

document-store

Document storage in repository

Using the Document Service in a Web Application [page


555]

mail

Sending e-mails

Tutorial: Sending E-Mails [page 414]

websocket

Communication through WebSockets

SAP_Jam_OData_HCP

Accessing data in SAP Jam via OData

Source code for using the SAP Jam API

All samples can be imported as Eclipse or Maven projects. While the focus has been placed on the Eclipse and
Apache Maven tools due to their wide adoption, the principles apply equally to other IDEs and build systems.
For more information about using the samples, see Importing Samples as Eclipse Projects [page 53], Importing
Samples as Maven Projects [page 54], and Building Samples with Maven [page 55].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

51

Community Samples: Paul the Octopus


The Web application "Paul the Octopus" is part of a community blog and shows how the SAP HANA Cloud
Platform services and capabilities can be combined to build more complex Web applications, which can be
deployed on the SAP HANA Cloud Platform.
Features of "Paul the Octopus":
It is intended for anyone who would like to gain hands-on experience with the SAP HANA Cloud Platform.
It involves the following platform services: identity, connectivity, persistence, and document.
Its user interface is developed via SAPUI5 and is based on the Model-View-Controller concept. SAPUI5 is
based on HTML5 and can be used for building applications with sophisticated UI. Other technologies that you
can see in action in "Paul the Octopus" are REST services and job scheduling.
For more information, see the SCN community blog: Get Ready for Your Paul Position

You can get the application source from https://github.com/SAP/cloud-paulpredicts/

Community Samples: SAP Library


The Web application "SAP Library" is presented in a community blog as another example of demonstrating the
usage of several SAP HANA Cloud Platform services in one integrated scenario, closely following the product
documentation. You can import it as a Maven project, play around with your own library, and have a look at how it
is implemented. It allows you to reserve and return books, edit details of existing ones, add new titles, maintain
library users' profiles and so on.
Features of "SAP Library":
The library users authenticate using the identity service. It supports Single Sign-On (SSO).
The books status and features are persisted using the persistence service.
Books details are retrieved using a public Internet Web service, demonstrating usage of the connectivity
service.
The e-mails you will receive when reserving and returning books to the library, are implemented using a Mail
destination.
When you upload your profile image, it is persisted using the document service.
For more information, see the SCN community blog: Welcome to the Library!
You can get the application source from https://github.com/SAP/cloud-sample-library/

Related Information
Importing Samples as Eclipse Projects [page 53]
Importing Samples as Maven Projects [page 54]
Building Samples with Maven [page 55]
Building Java Web Applications with Maven
Working with the "Neo" Maven Plugin

52

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.3.4.1

Importing Samples as Eclipse Projects

To get a sample application up and running, import it as an Eclipse project into your Eclipse IDE and then deploy it
on the local runtime and SAP HANA Cloud Platform.

Prerequisites
You have installed the SAP HANA Cloud Platform Tools and created a SAP HANA Cloud Platform server runtime
environment as described in Installing Java Tools for Eclipse and SDK [page 33].

Procedure
1. From the main menu of the Eclipse IDE, choose
Workspace

File

Import

General

Existing Projects into

and then choose Next.

2. Browse to locate and select the directory containing the project you want to import, for example, <sdk>/
samples/hello-world, and choose OK.
3. Under Projects select the project (or projects) you want to import.
4. Choose Finish to start the import.
The project is imported into your workspace and appears in the Project Explorer view.

Tip
Close the welcome page if it is still shown.

Note
If you have not yet set up a server runtime environment, the following error will be reported: "Faceted
Project Problem: Target runtime SAP HANA Cloud is not defined". To set up the runtime environment,
complete the steps as described in Setting Up SDK Location and Landscape Host in Eclipse [page 38] and
Setting Up the Runtime Environment [page 39].

Next Steps
Run the sample application locally and then in the cloud. For more information, see Deploying Locally from Eclipse
IDE [page 975] and Deploying on the Cloud from Eclipse IDE [page 977].

Note
Some samples are ready to run while others have certain prerequisites, which are described in the respective
readme.txt.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

53

Note
When you import samples as Eclipse projects, the tests provided with the samples are not imported. To be able
to run automated tests, you need to import the samples as Maven projects.

1.2.3.4.2

Importing Samples as Maven Projects

To import the tests provided with the SDK samples, import the samples as Maven projects.

Prerequisites
You have installed the SAP HANA Cloud Platform Tools and created a SAP HANA Cloud Platform server runtime
environment as described in Installing Java Tools for Eclipse and SDK [page 33].

Install the Maven Integration for Eclipse WTP


Procedure
1. From the Eclipse main menu, choose

Help

Eclipse Marketplace .

2. Enter Maven in the Find field and choose Go.


3. Locate the Maven Integration for Eclipse WTP item and choose the Install button.

Note
To configure the Maven settings.xml file, choose

Window

Preferences

Maven

User Settings .

This configuration is required if you need to provide your proxy settings. For more information, see http://
maven.apache.org/settings.html .

Import a Sample Maven Project


Procedure
1. From the Eclipse main menu, choose
Next.

File

Import

Maven

Existing Maven Projects

and then choose

2. Browse to locate and select the directory containing the project you want to import, for example, <sdk>/
samples/hello-world, and choose OK.

54

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Under Projects select the project (or projects) you want to import.
4. Choose Finish to start the import.
The project is imported into your workspace and appears in the Project Explorer view.

Tip
Close the welcome page if it is still shown.
5. If necessary, update the project to remove any errors after the import. To do this, select the project and from
the context menu choose

Maven

Update Project

and then OK.

Next Steps
Run the sample application locally and then in the cloud. For more information, see Deploying Locally from Eclipse
IDE [page 975] and Deploying on the Cloud from Eclipse IDE [page 977].

Note
Some samples are ready to run while others have certain prerequisites, which are described in the respective
readme.txt.

1.2.3.4.3

Building Samples with Maven

All samples provided can be built with Apache Maven. The Maven build shows how a headless build and test can
be completely automated.

Context
The build and test does the following:
Builds a Java Web application based on the SAP HANA Cloud Platform API
Demonstrates how to run rudimentary unit tests (not available in all samples)
Installs, starts, waits for, and stops the local server runtime
Deploys the application to the local server runtime and runs the integration test
Starts, waits for, and stops the cloud server runtime
Deploys the application to the cloud server runtime and runs the integration test

Related Information
Building Samples from the Command Line [page 56]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

55

Building Java Web Applications with Maven


Working with the "Neo" Maven Plugin

1.2.3.4.3.1 Building Samples from the Command Line


You can use the Apache Maven command line tool to run local and cloud integration tests for any of the SDK
samples.

Prerequisites
You have downloaded the Apache Maven command line tool. For more information, see the detailed Maven
documentation at http://maven.apache.org .
You are familiar with the Maven build lifecycle. For more information, see http://maven.apache.org/guides/
introduction/introduction-to-the-lifecycle.html .

Procedure
1. Open the folder of the relevant project, for example, <sdk>/samples/hello-world, and then open the
command prompt.
2. Enter the verify command with the following profile in order to activate the local integration test:
mvn clean verify -P local-integration-tests ...
If you are using a proxy, you need to define additional Maven properties as described below in step 4 (see
proxy details).
3. Press ENTER to start the build process.
All phases of the default lifecycle are executed up to and including the verify phase, with the resulting build
status shown on completion.
4. To activate the cloud integration test, which involves deploying the built Web application on a landscape in the
cloud, enter the following profile with the additional Maven properties given below:
mvn clean verify -P cloud-integration-tests ...
Landscape host
The landscape host (default: hana.ondemand.com) is predefined in the parent pom.xml file (<sdk>/
samples/pom.xml) and can be overwritten, as necessary. If you have a developer account, for example,
and are therefore using the trial landscape, enter the following:
mvn clean verify -P cloud-integration-tests Dsap.cloud.host=hanatrial.ondemand.com ...
Account details

56

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Provide your account, user name, and password:


mvn clean verify -P cloud-integration-tests -Dsap.cloud.account=<account> Dsap.cloud.username=<user name> -Dsap.cloud.password=<password> ...
Proxy details
If you use a proxy for HTTPS Internet access, provide your proxy host (https.proxyHost) and if
necessary your proxy port (https.proxyPort):
mvn clean verify -P cloud-integration-tests -Dhttps.proxyHost=<proxy host> Dhttps.proxyPort=<proxy port> ...

Tip
If your proxy requires authentication, you might want to use the Authenticator class to pass the proxy
user name and password. For more information, see Authenticator . Note that for the sake of
simplicity this feature has not been included in the samples.

Tip
To avoid having to repeatedly enter the Maven properties as described above, you can add them directly to
the pom.xml file, as shown in the example below:
<sap.cloud.username>p0123456789</sap.cloud.username>
You might also want to use environment variables to set the property values dynamically, in particular
when handling sensitive information such as passwords, which should not be stored as plain text:
<sap.cloud.password>${env.SAP_CLOUD_PASSWORD}</sap.cloud.password>

Related Information
Landscape Hosts [page 32]

1.2.4 SAP HANA: Getting Started


Set up your SAP HANA development environment and run your first application in the cloud.
Table 12:
Sign Up
You first need to sign up for an SAP HANA Cloud Platform account.
Set Up
Download Eclipse IDE for Java EE Developers, and set up SAP HANA Tools.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

57

Create
Create a simple HANA XS application and run it in the cloud.
Monitor
Monitor HANA XS applications.

Add Features
Use calculation views and visualize the data with SAPUI5. See: 8 Easy Steps to Develop an XS application on the
SAP HANA Cloud Platform

1.2.4.1

Installing SAP HANA Tools for Eclipse

Before developing your SAP HANA XS application, you need to download and set up the necessary tools.

Prerequisites
You have downloaded and installed a 32-bit or 64-bit version of Eclipse IDE, version Mars or Luna. For more
information, see Installing Eclipse IDE [page 36].

Caution
The support for Kepler has entered end of maintenance.
You have configured your proxy settings (in case you work behind a proxy or a firewall). For more information,
see Installing SAP Development Tools for Eclipse [page 37] step 3.

Procedure
1. Open the Eclipse IDE.
2. In the main menu, choose

Help

Install New Software .

3. Depending on the Eclipse version you have installed, enter one of the following URLs:
For Eclipse Luna (4.4), add URL: https://tools.hana.ondemand.com/luna
For Eclipse Mars (4.5), add URL: https://tools.hana.ondemand.com/mars
4. Select SAP HANA Tools (the whole feature group).

58

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
In case you need to develop with SAPUI5, install also

SAP HANA Cloud Platform Tools

UI development

toolkit for HTML5 (Developer Edition) .


5. Choose Next.
6. On the next wizard page, you get an overview of the features to be installed. Choose Next.
7. Confirm the license agreements.
8. Choose Finish to start the installation.
9. After the successful installation, you will be prompted to restart your Eclipse IDE.

Next Steps
Creating an SAP HANA XS Application [page 59]

1.2.4.2

Creating an SAP HANA XS Application

This tutorial explains how to create a simple SAP HANA XS application that is written in server-side JavaScript
and displays the "Hello World!" message together with a string extracted from a table in the SAP HANA database.

Prerequisites
You have installed the tools as described in Installing SAP HANA Tools for Eclipse [page 58].

Context
In this tutorial, you complete the following steps:
1. Trial SAP HANA database only: Create an SAP HANA development package.
2. Use the Eclipse IDE to access an SAP HANA database.
3. Create a subpackage.
4. Create a repository workspace.
5. Create an XS project.
6. Create the following files:
Application descriptor (.xsapp): Marks the root point in the package hierarchy from which content can
be served. It is a prerequisite to develop and deploy an application on SAP HANA Extended Application
Services (SAP HANA XS).
Application access file (.xsaccess): Determines whether or not package content can be exposed and
specifies the authentication method to be used to grant access.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

59

Application privileges file (.xsprivileges): Defines the privileges required to access an application.
Role (.hdbrole): Contains the defined application privileges.
7. Create the application JavaScript file (file extension XSJS)
8. Grant the user the role required to access the application
9. Open the application from the cockpit.
The following example data is used:
Account: p1234567890trial
User: p1234567890
SAP HANA Cloud Platform landscape: hanatrial.ondemand.com
Replace the above with your own account and user names. If you have a productive SAP HANA database, replace
hanatrial.ondemand.com with the appropriate landscape host, for example, hana.ondemand.com.

(For Trial Landscape Only) 1. Create a SAP HANA Database


This step is required if you use a trial SAP HANA database.

Context
You can create one trial SAP HANA database per account. It is equivalent to a database schema with the database
property HANA XS. Once you have created a trial HANA database, it is listed under
Schemas

Persistence

Databases &

in the cockpit.

Note
This section explains working with trial SAP HANA databases that provide you with a shared database, enabling
you to work with SAP HANA in a managed environment, using schemas instead of tenant databases.
For more information about working with trial SAP HANA databases with multitenant database container
support enabled, see Databases and Database Systems [page 770] and Creating SAP HANA MDC Databases
[page 784].

Procedure
1. Log on to the cockpit on the trial landscape (https://account.hanatrial.ondemand.com/cockpit)
and select an account.
2. Choose Persistence Databases & Schemas in the navigation area.
All databases available in the selected account are listed with their ID, type, version, and related database
system.

60

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tip
To view the details of a database, for example, its state and the number of existing bindings, click the link
for a selected database in the list. This opens the overview of the database, where you can perform further
actions, for example, delete the database.
3. To create a trial database, choose New on the Databases & Schemas page.
The New Database/Schema screen is displayed.
4. Enter the following details:
Schema ID. A schema ID is freely definable but must start with a letter and contain only uppercase and
lowercase letters ('a' - 'z', 'A' - 'Z'), numbers ('0' - '9'), and the special characters '.' and '-'. Note that the
actual schema ID assigned in the database will be different to this version.
Database System: Select a database system (HANA XS (<shared>)).
To create schemas on your productive HANA database systems, you have to use the HANA-specific tools.
5. Save your entries.

2. Connect to an SAP HANA Database


Context
For more information, see the following documents, depending on your use case (productive or trial):
(For the productive landscape) Connecting to SAP HANA Databases via the Eclipse IDE [page 861]
(For the trial landscape) Connecting to SAP HANA Schemas via the Eclipse IDE [page 864]

3. Create a Subpackage
Procedure
1. In the Eclipse IDE, open the SAP HANA Development perspective.
2. In the Systems view, select the Content/p1234567890trial/myhanaxs node.
3. From the context menu, choose

New

Package .

The New Package dialog box appears.


4. In the Name field, p1234567890rial.myhanaxs. is already entered. Add the new package name (for
example, "hello") to the end of the full package path: p1234567890trial.myhanaxs.hello
5. Click in the Description field to automatically copy across the package name.
6. Choose OK to confirm.
The new subpackage hello is added to the package hierarchy below the myhanaxs package.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

61

4. Create a Repository Workspace


Procedure
1. In the Repositories view, choose the Create Repository Workspace button.
2. If your SAP HANA system is not listed in the SAP HANA System list, choose the Add System button and add it
to the list. If you have more than one SAP HANA system, make sure that the applicable system is selected
under SAP HANA System.
3. Enter the workspace name myhanaxs. In this example, the workspace name is the same as the root package
name.
4. In the Workspace Root field, browse to select the folder that will contain the workspace you create in this step.
The tutorial uses C:\HANAXSws.
5. Choose Finish.
The workspace now appears in the Repositories view. A folder has also been added to your local file system:
C:\HANAXSws\myhanaxs. It will contain all your development files.

5. Create an XS Project
Procedure
1. In the Project Explorer view, choose
Project

File

New

Project

SAP HANA

Application Development

XS

and then choose Next.

Note
After installing the SAP HANA tools for SAP HANA Cloud Platform, you may not see the XS Project wizard
in the list of wizards. To fix this:
1. Close the Eclpse IDE.
2. Add a line -clean to the eclipse.ini file, or use -clean at the command line to start Eclipse.
3. Start the Eclipse IDE again. The XS project wizard will now show up.
4. Remove the -clean option again.
2. Enter hello as project name, and choose Next (keeping all default settings).
3. Select the repository workspace you created. As Repository Package, choose Browse and navigate to the
p1234567890trial.myhanaxs.hello package. Choose Next.

Restriction
You cannot use the root repository package here. You need to use the correct subpackage instead (such as
p1234567890trial.myhanaxs.hello). Otherwise, you will get errors during activation.
4. Deselect the default file creation options (XS Application Access (.xsaccess) and XS Application Descriptor
(.xsapp)) and choose Finish.

62

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
Note
If you experience project errors due to unsupported encoding, use one of the following options to fix the
problem:
Quick fix that automatically changes the encoding of individual files to UTF-8
Project settings that change the default encoding of the entire XS project to UTF-8 (
Properties

Resource

Text file encoding

Other

UTF-8

context menu

6. Create the Application Descriptors and Role


Procedure
Application descriptor
a. In the Project Explorer view, select the hello project and choose

File

New

File .

b. Enter the file name .xsapp and choose Finish.


Note that the file name is just a file extension and that the file does not have any content.
Application access file
a. In the Project Explorer view, select the hello project and choose

File

New

File .

b. Enter the file name .xsaccess and choose Finish.


Note that the file name is just a file extension.
c. Copy the following code into the .xsaccess file and save:
{
"exposed" : true,
"default_file": "hello.xsjs"
}
This configuration determines that the application will be exposed in the Internet via HTTPS. Although no
authentication is specified, all SAP HANA XS applications on a trial SAP HANA database use SAML2. For
the productive SAP HANA database, SAML will be enabled in a later step. Application users will then be
authenticated by the SAP ID service.
Application privileges file
a. In the Project Explorer view, select the hello project and choose

File

New

File .

b. Enter the file name .xsprivileges and choose Finish.


Note that the file name is just a file extension.
c. Copy the following code into the .xsprivileges file and save:
{ "privileges" :
[ { "name" : "Basic", "description" : "Basic usage privilege" } ]}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

63

Role
a. In the Project Explorer view, select the hello project and choose

File

New

File .

b. Enter the file name model_access.hdbrole and choose Finish.


c. Copy the following code into the file:
role <package name>::model_access {
application privilege: <package name>::Basic;
}
d. Replace <package name> with the SAP HANA package where the project is shared. For the trial SAP
HANA database, it should look something like this: p1234567890trial.myhanaxs.hello. Then save
the file.

7. Create the JavaScript File


Procedure
1. In the Project Explorer view, select the hello project and choose

File

New

File .

2. Enter the file name hello.xsjs and choose Finish.


3. Copy the following JavaScript code into the file and save:
$.response.contentType = "text/html";
var output = "Hello, " + $.session.getUsername() + " <br><br>";
var conn = $.db.getConnection();
var pstmt = conn.prepareStatement( "SELECT CURRENT_USER FROM DUMMY" );
var rs = pstmt.executeQuery();
if (!rs.next()) {
$.response.setBody( "Failed to retrieve data" );
$.response.status = $.net.http.INTERNAL_SERVER_ERROR;
}
else {
output = output + "This is the response from my SQL. The current user is: "
+ rs.getString(1);
}
rs.close();
pstmt.close();
conn.close();
$.response.setBody(output);
The code does the following:
Opens a connection to the database
Prepares and runs an SQL statement on the system table DUMMY, which returns as a response the
current user.
Adds the results to the response so that it can be displayed in the Web browser
4. To activate the files in the SAP HANA repository, select the files and from the context menu choose

Team

Activate .
The application is now running on the XS engine.

64

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

8. Grant the Role to the User


To enable other users to access your application, you need to grant them the model_access role that you created
in section 6.

Procedure
Trial SAP HANA database
a. In the Systems view, select your system and from the context menu choose SQL Console.
b. In the SQL console, enter the following, replacing <SAP HANA Cloud user> with your user:
call
"HCP"."HCP_GRANT_ROLE_TO_USER"('p1234567890trial.myhanaxs.hello::model_access'
, '<SAP HANA Cloud user>')
c. Execute the procedure. You should see a confirmation that the statement was successfully executed.
Productive SAP HANA database
a. In the Systems view, expand

Security

Users

and then double-click your user ID.

b. On the Granted Roles tab, choose the + (Add) button.


c. Select the model_access role in the list and choose OK. The role is now listed on the Granted Roles tab.
d. Choose Deploy in the upper right corner of screen. A message confirms that your user has been modified.

Note
(Relevant for Trial landscape only) If you refactor existing SAP HANA database views or create new ones
on your Trial account, you need to refactor/recreate them in the "_SYS_BIC" schema instead of your
account-specific schema.

9. Test Your Application


Procedure
Open the cockpit and proceed as described in: Launching SAP HANA XS Applications [page 1009]

Note
The HANA XS application is only visible in the cockpit once you have activated it.
You will be authenticated by SAML and should then see a text similar to the following:
Hello, p1234567890,
This is the response from my SQL. The current user is: p1234567890

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

65

1.2.5 HTML5: Getting Started


Set up your HTML5 development environment and run your first application in the cloud.
Table 13:
Sign Up
You first need to sign up for an SAP HANA Cloud Platform account.
Add Users
Add users who develop and maintain HTML5 applications as account members of your account.
Set Up
To develop HTML5 applications, we recommend that you use the browser-based tool SAP Web IDE, that does not re
quire any set up.
As an alternative you can use the Installing Eclipse IDE [page 36]. Please note that new capabilities for SAPUI5 and
SAP Fiori development will be available only with SAP Web IDE.
Create
Create a simple HTML5 application and run it in the cloud:

Hello World Tutorial Using SAP Web IDE (recommended) [page 66]

Hello World Tutorial Using Eclipse [page 70]

For more information about building applications in SAP Web IDE, see the SAP Web IDE documentation. There,
you will also find information on building your project first and then pushing your app to the cockpit.

Related Information
HTML5: Development [page 1040]
HTML5: Application Operations [page 1171]
Securing HTML5 Applications [page 1323]

1.2.5.1

Hello World Tutorial Using SAP Web IDE


(recommended)

This tutorial illustrates how to build a simple HTML5 application using SAP Web IDE.

Prerequisites
Your company has signed up for an SAP HANA Cloud Platform account.

66

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You are a member of the SAP HANA Cloud Platform account.

Context
During the tutorial, you perform the following tasks:
1. Creating an HTML5 Application [page 67]
2. Creating a Project [page 68]
3. Editing the HTML5 Application [page 69]
4. Deploying Your App to SAP HANA Cloud Platform [page 69]

1.2.5.1.1

Creating an HTML5 Application

You create new applications in the SAP HANA Cloud Platform cockpit.

Context
For each new application a new Git repository is created automatically. To view detailed information on the Git
repository, including the repository URL and the latest commits, choose
in the navigation area and then Versioning.

Applications

HTML5 Applications

Note
To create the HTML5 application in more than one landscape, create the application in each landscape
separately and copy the content to the new Git repository.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose

Applications

HTML5 Applications

in the navigation area.

If you have already created applications using this account, the list of HTML5 applications is displayed.
3. To create a new HTML5 application, choose New Application and enter an application name.

Note
Adhere to the naming convention for application names:
The name must contain no more than 30 characters.
The name must contain only lowercase alphanumeric characters.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

67

The name must start with a letter.


4. Choose Save.
5. Clone the repository to your development environment.
a. To start SAP Web IDE and automatically clone the repository of your app, choose Edit Online (
end of the table row of your application.

) at the

b. On the Clone Repository screen, enter your user and password (SCN user and SCN password), and
choose OK.

Results
You created an application and a corresponding Git repository.

Related Information
Cockpit [page 84]

1.2.5.1.2

Creating a Project

A project is needed to create files and to make them available in the cockpit.

Procedure
1. In SAP Web IDE, choose Development (</>), and then select the project of the application you created in the
cockpit.
2. To create a project and to clone your app to the development environment, right-click the project, and choose
New

Project from Template .

3. Choose the SAPUI5 Application button, and choose Next.


4. In the Project Name field, leave the proposed name for your project, and choose Next.
5. Fill in the following fields, and then choose Next:
Table 14:
Field

Entry

View Type

Select JavaScript.

View Name

Enter HelloWorld (without spaces).

6. Choose Finish.

68

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.5.1.3

Editing the HTML5 Application

SAP Web IDE already created an HTML page for your project. You now adapt this page.

Procedure
1. In SAP Web IDE, expand the project node in the navigation tree and open the HelloWorld.view.js using a
double-click.

2. In the HelloWorld.view.js view, replace Title in the title: "Title" line with the title of your
application Hello World.
3. Save your changes using Save (

).

4. To test your Hello World application, select the index.html file and choose Run (

1.2.5.1.4

).

Deploying Your App to SAP HANA Cloud Platform

With this step you create a new active version of your app that is started on SAP HANA Cloud Platform.

Procedure
1. In SAP Web IDE, select the project node in the navigation tree.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

69

2. To deploy the project, right-click it and choose

Deploy

Deploy to SAP HANA Cloud Platform .

3. On the Login to SAP HANA Cloud Platform screen, enter your password and choose Login.
4. On the Deploy Application to SAP HANA Cloud Platform screen, increment the version number and choose
Deploy.

Note
If you leave the Activate option checked, the new version is activated directly.
5. Confirm the success message with OK.

1.2.5.2

Hello World Tutorial Using Eclipse

This tutorial illustrates how to build a simple HTML5 application.

Prerequisites
You have set up Eclipse, see Installing Eclipse IDE [page 36].
Your company has signed up for an SAP HANA Cloud Platform account.
You are a member of the SAP HANA Cloud Platform account.

Context
During the tutorial, you perform the following tasks:
1. Creating an HTML5 Application [page 71]
2. Cloning a Repository [page 72]
3. Creating a Project and Adding an HTML File [page 72]
4. Pushing a File to the Git Repository [page 73]
5. Testing the Application [page 74]
6. Creating a Version [page 74]
7. Activating a Version [page 75]

Related Information
Blog: Lightweight HTML5 apps and Git on SAP HANA Cloud Platform

70

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.2.5.2.1

Creating an HTML5 Application

You create new applications in the SAP HANA Cloud Platform cockpit.

Context
For each new application a new Git repository is created automatically. To view detailed information on the Git
repository, including the repository URL and the latest commits, choose
in the navigation area and then Versioning.

Applications

HTML5 Applications

Note
To create the HTML5 application in more than one landscape, create the application in each landscape
separately and copy the content to the new Git repository.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose

Applications

HTML5 Applications

in the navigation area.

If you have already created applications using this account, the list of HTML5 applications is displayed.
3. To create a new HTML5 application, choose New Application and enter an application name.

Note
Adhere to the naming convention for application names:
The name must contain no more than 30 characters.
The name must contain only lowercase alphanumeric characters.
The name must start with a letter.
4. Choose Save.
5. Clone the repository to your development environment.
a. To start SAP Web IDE and automatically clone the repository of your app, choose Edit Online (
end of the table row of your application.

) at the

b. On the Clone Repository screen, enter your user and password (SCN user and SCN password), and
choose OK.

Results
You created an application and a corresponding Git repository.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

71

Related Information
Cockpit [page 84]

1.2.5.2.2

Cloning a Repository

You need to clone the Git repository of your application to your development environment.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose the

Applications

HTML5 Applications

in the navigation area.

3. Clone the repository to your development environment:


a. Click your newly created application.
b. Switch to the Versioning tab.
c. Under Source Location, copy the link that points to the Git repository of your application.
d. Start the Eclipse IDE.
e. Open the Git Repositories view in the JavaScript perspective and choose the Clone a Git repository icon.
f. Enter the link that points to the Git repository of your application.
g. Enter your user and password (SCN user and SCN password).
h. Choose Next.

Related Information
EGit/User Guide

1.2.5.2.3

Creating a Project and Adding an HTML File

A project is needed to create files and to make them available in the cockpit.

Procedure
1. Create a project.
a. In the Git repository view, right click on the repository and select Import Projects.

72

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

b. Choose Import as general project.


c. In the Project Name field, ensure that the project name is shown, and choose Next.
d. Enter a name for your project.
e. Choose Finish.
2. Add an HTML file.
a. In the JavaScript or the Resource perspective of Eclipse, start the wizard by right-clicking your project and
choosing

New

File .

b. Enter the following name for your file: index.html.


c. Choose Finish.
d. In your new index.html file, enter, for example, the Hello World code snippet:
<html>
<body>
<h1>Hello World</h1>
</body>
</html>
e. Save your entries.

1.2.5.2.4

Pushing a File to the Git Repository

First you commit your changes and then you publish them to the remote Git repository.

Context
Depending on whether you use Eclipse or SAP Web IDE the procedure to push and commit your changes to the
Git repository varies. Follow the respective steps below.

Procedure
1. Open the Git staging view.
2. Drag all changed files from the Unstaged Changes table to the Staged Changes table.
3. Enter a commit message and choose Commit and Push.

Results
You committed all changes locally and pushed them to the Git repository.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

73

1.2.5.2.5

Testing the Application

You can test your HTML5 application from the cockpit.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose the

Applications

HTML5 Applications

in the navigation area.

3. Select your Hello World application.


4. Choose the Versioning section.
5. To display the Hello World HTML5 application, click the link in the Commit Message column.

Results
If your application is working fine, you can create and activate a version of it.
If you receive an HTTP Status 404 error, check whether your index.html file has been created correctly and
whether you pushed your changes.

Related Information
Creating an HTML5 Application [page 71]
Pushing a File to the Git Repository [page 73]

1.2.5.2.6

Creating a Version

You create a version of your application from one of the commits.

Context
The version is a tag that is attached to the commit.

74

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose the

Applications

HTML5 Applications

in the navigation area.

3. Select your Hello World application.


4. Switch to the Versioning section.
5. In the Available Commits table, select the commit you want to use and choose the Create Version icon.
6. Enter a version name and choose Add.

Results
You can now activate this version to make the application available to the end users.

Related Information
For more information on logging on, see the Logon section in Cockpit [page 84]

1.2.5.2.7

Activating a Version

As end users can only access the active version of an application, you must create and activate a version of your
application.

Context
The administrator can activate a single version of an application to make it available to end users.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose the

Applications

HTML5 Applications

in the navigation area.

3. Select your Hello World application.


4. Switch to the Versioning section.
5. Choose the Versions button.
6. In the Versions table, select your version and choose the Activate this application version icon.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

75

7. Confirm that you want to activate the application.

Results
You can now distribute the URL of your application to the end users.

Related Information
For more information on logging on, see the Logon section in Cockpit [page 84]

1.2.6 Tutorials
Follow the tutorials below to get familiar with the services offered by SAP HANA Cloud Platform.
Table 15:
To learn about

See

How to create a "HelloWorld" Web application

Creating a HelloWorld Application [page 47]

How to create a "HelloWorld" Web application using Java EE 6


Web Profile

Using Java EE 6 Web Profile [page 966]

Connectivity service scenarios

Consuming Internet Services (Java Web or Java EE 6 Web


Profile) [page 348]
Consuming Internet Services (Java Web Tomcat 7) [page
355]
Consuming Back-End Systems (Java Web or Java EE 6 Web
Profile) [page 362]
Consuming Back-End Systems (Java Web Tomcat 7) [page
372]
Tutorial: Invoking ABAP Function Modules in On-Premise
ABAP Systems [page 399]
Tutorial: Sending E-Mails [page 414]

76

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To learn about

See

Persistence service scenarios

Adding Container-Managed Persistence With JPA (Java EE 6


Web Profile SDK) [page 724]
Adding Application-Managed Persistence With JPA (Java Web
SDK) [page 735]
Adding Persistence With JDBC (Java Web SDK) [page 746]
Migrating Web Applications That Use context.xml [page 756]
Creating an SAP HANA Database from the Cockpit [page
757]
Creating an SAP HANA Database Using Console Client [page
763]

Document service scenarios

Creating a Sample Application (Java) [page 555]


Building a Proxy Bridge [page 560]

How to secure your HTTPS connections

Tutorial: Using the Keystore Service for Client Side HTTPS


Connections [page 1251]

How to create an SAP HANA XS application

Creating an SAP HANA XS Application [page 59]

Multitenancy scenarios

Exemplary Provider Application (Servlet) [page 998]


Exemplary Provider Application (JSP) [page 1001]
Creating a Multitenant Connectivity Application [page 1003]

Business Services with YaaS scenarios

Tutorial: Creating a Wishlist Service [page 945]

Cross-Technology Scenarios
In SAP Developer Center, you can find tutorials on how to implement cross-technology scenarios using a
combination of SAP products for mobile, cloud, and on-premise systems.
For more information, see Cross-Technology End-to-End Scenarios

Video Tutorials
Creating a HelloWorld Application
Managing Roles in SAP HANA Cloud
SAP HANA Cloud Platform - Java Development
Using SAP HANA Cloud Platform Console Client
openSAP Course Videos: Introduction to SAP HANA Cloud Platform

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

77

1.2.7 Glossary
SAP HANA Cloud Platform Terminology

A-G
Table 16:
Account [page 11]

A hosted environment provided to a customer organization, representing a named collec


tion of configurations, authorizations, platform resources and applications.

Application

An application running on SAP HANA Cloud Platform, which has a deploy/start/stop/


undeploy lifecycle.

Application process

Each application is started on a dedicated SAP HANA Cloud Platform Runtime. This is
called application process. You can start one or many application processes of your appli
cation at any given time, according to the compute unit quota that you have. Each appli
cation process has a unique process ID that you can use to manage it.

Application runtime container


[page 955]

Java applications developed on SAP HANA Cloud Platform run on a modular and light
weight runtime container, which allows them to consume standard Java EE APIs and plat
form services.

Compute units [page 959]

The virtualized hardware resources used by an SAP HANA Cloud Platform application.

Cockpit [page 84]

SAP HANA Cloud Platform cockpit is the central point of entry to key information about
your accounts and applications, and for managing all activities associated with your ac
count.

Connectivity service [page 267]

Provides a secure, reliable and easy-to-consume access to business systems, running ei


ther on-premise or in the cloud.

Console client [page 88]

SAP HANA Cloud Platform console client enables development, deployment and configu
ration of a Web application outside the Eclipse IDE as well as continuous integration and
automation tasks. The tool is part of the SAP HANA Cloud Platform SDK.

Cloud connector [page 434]

SAP HANA Cloud connector serves as the link between on-demand applications in SAP
HANA Cloud Platform and existing on-premise systems. It combines an easy setup with a
clear configuration of the systems that are exposed to SAP HANA Cloud Platform.

Customer account [page 12]

Allows customers to build applications and host them in a productive environment for
their own purposes. A customer account can be purchased as part of a predefined or tail
ored package.

Database

An organized collection of the data that can be backed up and restored separately. The
database is the technical unit that contains the data where DBMS is a service that enables
users to define, create, query, update and administer the data. SAP HANA Cloud Platform
account administrators can create databases on database management systems in their
account.

See Databases and Database Sys


tems [page 770]

Database management system


(DBMS)
See Databases and Database Sys
tems [page 770]

78

A computer system that enables administrators, developers, and applications to interact


with one or more databases and provides access to the data contained in the database. It
runs on a hardware host (or several hosts for distributed database systems) and has a
version. Examples for DBMSs are SAP HANA and SAP ASE.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Database type

A specific database product, such as the SAP HANA database

See Databases and Database Sys


tems [page 770]
Developer account [page 12]

Offers access to the SAP HANA Cloud Platform trial landscape for evaluation purposes. A
developer account is free of charge and valid for an unlimited period. It allows restricted
use of the platform resources.

Developer Center

SAP HANA Cloud Developer Center


is the place on the SAP Community Network
where you can find information, news, discussions, blogs, and more about SAP HANA
Cloud Platform.

Document service [page 545]

Provides an on-demand repository for applications to manage unstructured content for


an application-specific context using the CMIS protocol.

Global account

Accounts are organized in a global account. A global account corresponds to a customer


who buys an account for deploying applications on the cloud platform. The customer
data, billing information, and purchased resources (such as compute units) are stored in
a global account.

See Accounts [page 11]

I-R
Table 17:
Infrastructure as a Service (IaaS)

A provisioning model in which an organization outsources the equipment used to support


operations, including storage, hardware, servers and networking components.

Identity provider (IdP)

An authorization authority containing all user information and credentials. In SAP HANA
Cloud Platform, user information is provider by identity providers, not stored in SAP
HANA Cloud Platform itself.

Member

Indicates a users assignment to an account. As an account member, a user automatically


has the permissions required to use the SAP HANA Cloud Platform functionality within
the scope of the respective account and as permitted by their account member roles.

Multitenant database container

A self-contained database container in a multiple-container system. A tenant database


container has its own isolated set of database users and its own database catalog. No
data is shared between the tenant databases in a system. Clients can connect to tenant
databases individually.

OAuth [page 1227]

Widely adopted security protocol for protection of resources over the Internet. It is used
by many social network providers and by corporate networks. It allows an application to
request authentication on behalf of users with third-party user accounts, without the user
having to grant its credentials to the application.

Partner account [page 16]

Allows partners to build applications and sell them to their customers. A partner account
is available through a partner program, which provides a package of predefined resources
and the opportunity to certify, advertise, and ultimately sell products.

Persistence service [page 720]

Provides in-memory and relational persistence for applications that are hosted on the
platform.

Platform as a Service

An environment to develop, deploy, run and manage your business applications in the
cloud. The underlying software and hardware infrastructure is provided on demand (as a
service).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

79

Quota [page 17]

An accounts entitlement to an allocated resource, such as CPU, memory, database stor


age, and bandwidth. The resources purchased for an account are available to all applica
tions deployed within that account, within the specified limits.

Runtime for Java [page 953]

The components which create the environment for deploying and running Java applica
tions on SAP HANA Cloud Platform - Java Virtual Machine, Application Runtime Con
tainer and Compute Units.

S-Z
Table 18:
SAP Community Network
(SCN)

SAP's professional social network for SAP customers, partners, employees and experts,
which offers insight and content about SAP solutions and services in a collaborative envi
ronment: http://scn.sap.com. To use SAP HANA Cloud Platform, you have to be regis
tered on SCN.

SAP HANA Cloud Platform [page


5]

SAP HANA Cloud Platform is an in-memory cloud platform that enables customers and
partners to build, deploy, and manage cloud-based enterprise applications that comple
ment and extend SAP or non-SAP solutions, either on-premise or on-demand.

SAP ID service [page 1205]

The default identity provider for SAP HANA Cloud Platform applications. It manages the
user base for SAP Community Network and other SAP Web sites. SAP ID service is also
used for authentication in the cockpit and operations such as deploying, updating, and so
on.

SDK [page 81]

SAP HANA Cloud Platform Software Development Kit is the toolset you need to build and
run SAP HANA Cloud Platform applications. It contains console client for deployment and
configuration editing; binaries for local testing runtime; javadoc.

SAP Cloud Identity service

SAP Cloud Identity service is a cloud solution for identity lifecycle management for SAP
HANA Cloud Platform applications, and optionally for on-premise applications. You can
use SAP Cloud Identity as an identity provider for SAP HANA Cloud Platform applications.

UI development toolkit for HTML5


(SAPUI5)

A framework providing UI controls for developing Web applications.

Security Assertion Markup Lan


guage

A markup language which provides a wide-spread protocol for secure authentication and
SSO. SAML is implemented by SAP ID service.

Service provider

The application interested in getting authentication and authorization information. In


stead of providing this information in itself, it contacts the identity provider.

Single Sign-On

A property of access control of multiple related, but independent software systems,


which enables a user to log in once and have access to all systems.

Software as a Service

A software distribution model in which applications are hosted by a vendor or service pro
vider and made available to customers over the Internet.

SAP Java Virtual Machine [page


35]

SAP's own implementation of a Java Virtual Machine on which the SAP HANA Cloud
Platform infrastructure runs.

Tenant ID [page 995]

Identifier of the consumer account for the current application context. The tenant ID can
be used to distinguish data of different application consumer accounts.

WTP Server Adapter

A tool for deploying and testing Java EE assets on SAP HANA Cloud Platform or for local
testing.

80

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3

Tools

Table 19:
Tool

Description

Cockpit [page 84]

This is the central point for managing all activities associated


with your account and for accessing key information about
your applications.

SAP Web IDE [page 88]

This is a cloud-based meeting space where multiple applica


tion developers can work together from a common Web inter
face connecting to the same shared repository with virtu
ally no setup required. SAP Web IDE allows you to prototype,
develop, package, deploy, and extend SAPUI5 applications.

Maven Plugin [page 88]

It supports you in using Maven to develop Java applications


for SAP HANA Cloud Platform. It allows you to conveniently
call the console client and its commands from the Maven envi
ronment.

SAP HANA Cloud Connector [page 434]

It serves as the link between on-demand applications in SAP


HANA Cloud Platform and existing on-premise systems. You
can control the resources available for the cloud applications
in those systems.

SDK [page 81]

It contains everything you need to work with SAP HANA Cloud


Platform, including a local server runtime and a set of com
mand line tools.

Eclipse Tools [page 86]

This is a Java-based toolkit for Eclipse IDE. It enables you to


develop and deploy applications as well as perform operations
such as logging, managing user roles, creating connectivity
destinations, and so on.

Console Client [page 88]

It enables development, deployment and configuration of an


application outside the Eclipse IDE as well as continuous inte
gration and automation tasks.

1.3.1 SDK
The SDK contains everything you need to work with SAP HANA Cloud Platform, including a local server runtime
and a set of command line tools.

Prerequisites
You have the SDK installed. See Installing the SDK [page 34].
The location of the SDK is the folder you have chosen when you downloaded and unzipped it.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

81

An overview of the structure and content of the SDK is shown in the table below. The folders and files are located
directly below the common root directory in the order given:
Folder/File

Description

api

The platform API containing the SAP and third-party API


JARs required to compile Web applications for SAP HANA
Cloud Platform (for more information about the platform API,
see the "Supported APIs" section further below).

javadoc

Javadoc for the SAP platform APIs (also available as online


documentation via the API Documentation link in the title bar
of the SAP HANA Cloud Platform Documentation Center).
Javadoc for the third-party APIs is cross-referenced from the
online documentation.

repository

The P2 repository from which the local server runtime is


created.

samples

Samples demonstrating how to develop for SAP HANA Cloud


Platform. The samples can be imported as Eclipse or Maven
projects.

server

Initially not present, but created once you install a local


server runtime.

tools

Command line tools required for interacting with the cloud


runtime (for example, to deploy and start applications) and
the local server runtime (for example, to install and start the
local server).

licenses.txt

Licenses of third-party components contained in the SAP


HANA Cloud Platform SDK.

readme.txt

Brief introduction to the SDK, its content, and how to set it


up.

sdk.version

SDK version information for use by other tools interacting


with the SDK.

Local Server Runtime


The cloud server runtime consists of the application server, the platform API, and the cloud implementations of
the provided services (connectivity, persistence, document, and identity). The SDK, on the other hand, contains a
local server runtime that consists of the same application server, the same platform API, but local
implementations of the provided services. These are designed to emulate the cloud server runtime as closely as
possible to support the local development and test process.

Supported APIs
The SDK contains the API for SAP HANA Cloud Platform. All Web applications intended for deployment in the
cloud should be compiled against this platform API. The platform API is used by the SAP HANA Cloud Platform
Tools for Java to set the compile-time classpath.

82

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

All JARs contained in the platform API are considered part of the provided scope and must therefore be used for
compilation. This means that they must not be packaged with the application, since they are provided and wired
at runtime in the SAP HANA Cloud Platform runtime, irrespective of whether you run your application locally for
development and test purposes or centrally in the cloud.
When you develop applications to run on the SAP HANA Cloud Platform, you should be aware of which APIs are
supported and provisioned by the runtime environment of the platform:
Third-party APIs: These include Java EE standard APIs (standards based and backwards compatible as
defined in the Java EE Specification) and other APIs released by third parties.
SAP APIs: The platform APIs provided by the SAP HANA Cloud Platform services.

Related Information
Samples [page 51]
Console Client [page 88]
API Documentation [page 1060]
Supported Java APIs [page 961]
Deploying Locally with the Console Client [page 981]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

83

1.3.2 Cockpit
The cockpit is the central point for managing all activities associated with your cloud-based business applications.
You can use the web-based user interface for deploying, running, and managing your web applications and
connecting them with services on the cloud platform.

Dashboard
The figure below shows an example of the dashboard for the account in question and is followed by an
explanation:

The dashboard provides an overview of the applications available in the different technologies supported by SAP
HANA Cloud Platform (SAP HANA XS, Java, and HTML5), and shows other key information about the account.
The tiles contain links for direct navigation to the relevant information.
The Favorite Applications panel shows all applications that you have added to your favorites, making key
information about them available at a glance. You can manage your favorites directly from the dashboard and
navigate to the application overview for further details and options.

Accounts
The cockpit provides integrated access to all accounts you operate on the productive landscape,
hana.ondemand.com.
Each account is associated with a region, which represents the data center that is used by the account. For more
information about data centers and regions, see Landscape Hosts [page 32].

84

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

A separate cockpit for developer accounts is available on the trial landscape, hanatrial.ondemand.com.

Logon
Log on to the cockpit using the relevant URL for your account type (developer, customer, and partner), and in the
case of customer and partner accounts, the associated region. For example, use https://
account.hana.ondemand.com/cockpit to log on to a customer or partner account located in Europe.

Note
We recommend that you log on with your e-mail address.
When you log on to the cockpit for the first time, you see an overview of all the accounts available in a global
account, together with some details for each account. You can have several global accounts and several accounts
assigned to you in the global account in question. You can select an account in the overview page and drill down to
the account details, from where you can access the applications deployed in this account and related actions.

Accessibility
SAP HANA Cloud Platform provides High Contrast Black (HCB) theme support. You can switch between the
default theme and the high contrast theme using the Settings menu in the cockpit title bar. Once you have saved
your changes, the cockpit starts with the theme of your choice.
The cockpit icons are designed in high-contrast mode.

Navigation
The main screen areas of the cockpit comprise the content area and the navigation area. The navigation area is
composed of the breadcrumb navigation that comes under the header and the navigation entries to the side of the
content area. Use the breadcrumb navigation to access the different applications deployed in your account and
associated activities.
Note the following:
A dropdown menu is available for each of the elements that enables you to switch to other objects by clicking
the triangular selector. For example, use the dropdown menu to switch between different applications in your
account.
The element that is currently selected appears as a hyperlink in the breadcrumb navigation. For example, a
click the link for the application entry launches the application.
You can navigate upwards in the hierarchy or backwards to the previous navigation target using the links in
the breadcrumb navigation.
Each level determines which navigation options are available and the information that is displayed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

85

Browser Support
For more information, see .Product Prerequisites and Restrictions [page 8]

Notifications
Use Notifications to stay informed about different operations and events in the cockpit, for example, to monitor
the progress of copying an account. The (Notification) icon in the header toolbar provides a quick access to the
list of notifications and shows the number of available notifications. The icon is visible only if there are currently
notifications.
Each notification includes a short statement, a date and time, and the relevant account. A notification informs you
about the status of an operation or asks for an action. For example, if copying an account failed, an administrator
of the account can assign the corresponding notification to himself and provide a fix. The other members of this
account will see that the notification is already assigned to someone else.
You have the following options:
Dismiss a notification.
Assign a notification to yourself. It's possible also to unassign yourself from a notification without processing
it further.
Once you have you completed the related action, you can set the status to complete. This dismisses the
corresponding notification for everyone else.
You can access the full list of notifications (also the ones you have dismissed earlier) by choosing Notifications in
the navigation area at the data center level.

Related Information
Account Types [page 12]
Landscape Hosts [page 32]
Managing Accounts and Quota [page 17]
Managing Members [page 23]
Managing Subscriptions [page 28]
Accessing Services [page 30]
Managing Deployed Applications [page 1108]
Managing Roles [page 1282]
ID Federation with the Corporate Identity Provider [page 1292]

1.3.3 Eclipse Tools


SAP HANA Cloud Platform Tools is a Java-based toolkit for Eclipse IDE. It enables you to perform the
following operations in SAP HANA Cloud Platform:

86

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Develop and deploy Web applications


Configure connectivity destinations
View and configure logs and log files
Manage user roles and groups
Profile Web applications locally
Build and adapt Web applications using SAPUI5

Features
You can download SAP HANA Cloud Platform Tools from the SAP Development Tools for Eclipse page. The
toolkit package contains:
SAP JVM Tools
SAP HANA Cloud Platform Tools for Java
Documentation for SAP HANA Cloud Platform
UI development toolkit for HTML5 (Developer Edition)

Support
SAP HANA Cloud Platform Tools come with a wizard for gathering support information in case you need help
with a feature or operation (during deploying/debugging applications, logging, configurations, and so on). For
more information, see Support Information (Eclipse IDE) [page 1327].

Related Information
Installing Java Tools for Eclipse and SDK [page 33]
Updating Java Tools for Eclipse and SDK [page 43]
Configuring Destinations from the Eclipse IDE [page 290]
Deploying on the Cloud from Eclipse IDE [page 977]
Debugging Applications on the Cloud [page 988]
Profiling Applications on the Cloud [page 1145]
Using Logs in the Eclipse IDE [page 1131]
UI development toolkit for HTML5 (SAPUI5)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

87

1.3.4 SAP Web IDE


SAP Web IDE is a fully extensible and customizable experience that accelerates the development life cycle with
interactive code editors, integrated developer assistance, and end-to-end application development life cycle
support. SAP Web IDE was developed by developers for developers.
SAP Web IDE is a next-generation cloud-based meeting space where multiple application developers can work
together from a common Web interface connecting to the same shared repository, with virtually no setup
required. It includes multiple interactive features that allow you to collaborate with your project colleagues and
prototype, develop, package, deploy, and extend SAPUI5 applications.

Related Information
https://help.hana.ondemand.com/webide/frameset.htm

1.3.5 Maven Plugin


SAP offers a Maven plugin that supports you in using Maven to develop Java applications for SAP HANA Cloud
Platform. It allows you to conveniently call the SAP HANA Cloud Platform console client and its commands from
the Maven environment.
Most commands that are supported by the console client are available as goals in the plugin. To use the plugin,
you require a SAP HANA Cloud Platform SDK, which can be automatically downloaded with the plugin. Each
version of the SDK always has a matching Maven plugin version.
For a list of goals and parameters, usage guide, FAQ, and examples, see:
Maven Plugin Documentation

Related Information
Building Java Web Applications with Maven
Working with the "Neo" Maven Plugin

1.3.6 Console Client


SAP HANA Cloud Platform console client enables development, deployment and configuration of an application
outside the Eclipse IDE as well as continuous integration and automation tasks. The tool is part of the SDK. You
can find it in the tools folder of your SDK location.

88

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 20:
To learn more about

See

Downloading and setting up the console client

Setting Up the Console Client [page 42]

Opening the tool and working with the commands and param
eters

Using the Console Client [page 89]

Groups of console client commands

Console Client Commands [page 96]

Ranges and types of exit codes

Exit Codes [page 262]

Machine-readable output of commands

Machine-Readable Command Output [page 93]

Verbose mode of output

Verbose Mode of the Console Commands Output [page 92]

1.3.6.1

Console Client Video Tutorial

Using the Console Client

You execute a console client command by entering neo <command name> with the appropriate parameters. To
list all parameters available for the respective command, execute neo help <command name>.
Opening the Console Client [page 89]
Properties File [page 90]
Command Line [page 90]
Parameter Priority [page 90]
Parameter Values [page 91]
Proxy Settings [page 91]
Output Mode [page 91]
You can define the parameters of the different commands either directly in the command line, or, in a properties
file:
neo <command name> <mandatory parameters> [optional parameters]
neo <command name> <properties file location>

Opening the Console Client


The console client is part of the SAP HANA Cloud Platform SDK. You can find it in the tools folder of your SDK
installation.
To start it, open the command prompt and change the current directory to the <SDK_installation_folder>\tools
location, which contains the neo.bat and neo.sh files.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

89

Command Line
You can deploy the same application as in the example above by executing the following command directly in the
command line:
neo deploy --account <account name> --application <application name> --source
samples/deploy_war/example.war --user <user name or email>

Properties File
Within the tools folder, a file example_war.properties can be found in the samples/deploy_war folder. In
the file, enter your own user and account name:
################################################
# General settings - relevant for all commands #
################################################
# Your account name
account=<your account>
# Application name
application=<your application name>
# User for login to hana.ondemand.com.
user=<email or user name>
# Host of the landscape admin server. Optional. Defaults to hana.ondemand.com.
host=hana.ondemand.com
#################################################################
# Deployment descriptor settings - relevant only for deployment #
#################################################################
# List of file system paths to *.war files and folders containing them
source=samples/deploy_war/example.war

Then execute the deployment with the following line:


neo deploy samples/deploy_war/example_war.properties
Note that you can have more than one properties file. For example, you can have a different properties file for
each application or user in your account.
For more information about using the properties file, watch the video tutorial

Parameter Priority
Argument values specified in the command line override the values specified in the properties file. For example, if
you have specified account=a in the properties file and then enter account=b in the command line, the
operation will take effect in account b.

90

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameter Values
Since the client is executed in a console environment, not all characters can be used in arguments. There are
special characters that should be quoted and escaped.
Consult your console/shell user guide on how to use special characters as command line arguments.
For example, to use argument with value abc&()[]{}^=;!'+,`~123 on Windows 7, you should quote the value
and escape the! character. Therefore you should use "abc&()[]{}^=;^!'+,`~123".
User
You can use your e-mail, SAP ID or user name.
Password
Do not specify your password in the properties file or as a command line argument. Enter a password only when
prompted by SAP HANA Cloud Platform console client.
For example, use:
neo deploy samples/deploy_war/example_war.properties
instead of
neo deploy --password <mypassword > samples/deploy_war/example_war.properties

Restriction
Your password cannot start with the "@" character.

Proxy Settings
If you work in a proxy environment, before you execute commands, you need to configure the proxy.
For more information, see Setting Up the Console Client [page 42]

Output Mode
You can configure the console to print detailed output during command execution.
For more information, see Verbose Mode of the Console Commands Output [page 92]

Related Information
Console Client Commands [page 96]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

91

1.3.6.2

Verbose Mode of the Console Commands Output

The console commands consist of:


Local code - executed inside a local JVM, which is started when the command is started.
Remote code - executed at back end (generally, the REST API that was called by the local code), which is
started in a separate JVM on the cloud.

Note
The trace level for remote code cannot be changed.
For local code execution, a LOG4J library is used. It is easy to be configured and, by default, there is a
configuration file located inside the commands class path, that is .../tools/lib/cmd.
For each command execution, two appenders are defined - one for the session and one for the console. They both
define different files for all messages that are logged by the SAP infrastructure and by apache.http. By default,
the console commands output is written in a number of log files. However, you are allowed to change the
log4j.properties file, and define additional appenders or change the existing ones. If you want, for example,
the full output to be printed in the console (verbose mode), or you want to see details from the execution of
specific libraries (partially verbose mode), you need to adjust the LOG4J configuration file.
For more information on how to configure the LOG4J, see https://logging.apache.org/

To adjust the level of a specific logger, you have to add log4j.logger.<package> = <level> in the code of
the log4j.properties file.
For more information about the different levels, see https://logging.apache.org/log4j/1.2/apidocs/org/apache/
log4j/Level.html
In the file defined for the session, only loggers with level ERROR are logged. If you want, for example, to log debug
information about the apache.http library, you have to change log4j.category.org.apache.http=ERROR,
session to log4j.category.org.apache.http=DEBUG, session.

Example
This example demonstrates how you can change the output of command execution so that it is printed in the
console instead of collecting the information within log files. To do this, open your SDK folder and go to directory /
tools/lib/cmd. Then, open the log4j.properties file and replace its content with the code below.

Tip
We recommend that you save the original content of the log4j.properties file. To switch back to the default
settings, just revert the changes you did in the log4j.properties file.
##########
# Log levels
##########
log4j.rootLogger=INFO, console

92

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

log4j.additivity.rootLogger=false
log4j.category.com.sap = INFO, console
log4j.additivity.com.sap = false
log4j.category.org.apache.http = INFO, console
log4j.additivity.org.apache.http = false
log4j.category.org.apache.http.wire = INFO, console
log4j.additivity.org.apache.http.wire = false
##########
# System out console appender
##########
log4j.appender.console.Threshold=ALL
log4j.appender.console=org.apache.log4j.ConsoleAppender
log4j.appender.console.Target=System.out
log4j.appender.console.layout=org.apache.log4j.PatternLayout
log4j.appender.console.layout.ConversionPattern=%d %-5p [%t] %C: %m%n
log4j.appender.console.filter.1=org.apache.log4j.varia.StringMatchFilter
log4j.appender.console.filter.1.StringToMatch=>> Authorization: Basic
log4j.appender.console.filter.1.AcceptOnMatch=false

Related Information
Machine-Readable Command Output [page 93]
Logging in Applications [page 1129]

1.3.6.3

Machine-Readable Command Output

Context
The console commands can return structured, machine-readable output. When you use the optional --output
parameter in a command, the command returns values and objects in a format that a machine can easily parse.
The currently supported output format is JSON.
Syntax: --output <format>
Accepted format value: json

Cases
If a command supports structured output, it returns machine-readable result values.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

93

If a command does not (yet) support structured output,it returns basic information including the standard
OUT/ERR output.
If the command is invoked without the --output parameter, it works as before.

JSON Output Format


When --output json is specified, the console client prints out a single JSON object containing information
about the command execution and the result, if available.
The JSON object contains the following properties:
Table 21:
Property Name

Type

Description

command

String

The name of the invoked neo command

argLine

String

The exact arguments line as specified by


the calling script

pid

Name

The process ID of the invoked command

exitCode

Name

The process exit code of the invoked


command ( 0 = successful, everything
else = failure)

errorMsg

String

The message provided when the com


mand implementation throws instance
of

com.sap.jpaas.infrastructur
e.console.exception.Command
Exception
commandOutput

String

The command output written to

system.out and captured by the con


sole client framework

commandErrorOutput

String

The command output written to

system.err and captured by the con


sole client framework

result

Object

The result object returned by the com


mand following the new contract for
structured, machine-readable output

Example
Here is a full example of a command ( neo start ) that supports structured output and displays result values:
{

"command": "start",
"argLine": "-a myaccount -b myapplication -h hana.ondemand.com -u myuser -p
******* -y",
"pid": 6523,

94

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"exitCode": 0,
"errorMsg": null,
"commandOutput": "Requesting start for:
application
: myapplication
account
: myaccount
host
: https://hana.ondemand.com
synchronous
: true
SDK version
: 1.48.99
user
: myuser
[Tue Feb 25 18:07:19 CET 2014] Start request performed successfully.
Triggered start of application process.
Status: STARTING
[Tue Feb 25 18:07:19 CET 2014] Waiting for STARTED status..............
[Tue Feb 25 18:07:25 CET 2014] Status STARTING reached for 6161 ms
[Tue Feb 25 18:07:19 CET 2014] Waiting for STARTED
status..................................
[Tue Feb 25 18:08:47 CET 2014] Status STARTED reached for 87838 ms
web: STARTED
URL: https://myapplicationmyaccount.hana.ondemand.com
Access points:
https://myapplicationmyaccount.hana.ondemand.com
Runtime: 1.47 (valid until 20-May-2015)
Application processes
ID
State
Last Change
Runtime
fc735dc
STARTED
25-Feb-2014 18:07:48
1.47.10.2
",
"commandErrorOutput": "",
"result": {
"status": "STARTED",
"url": "https://myapplicationmyaccount.hana.ondemand.com",
"accessPoints": [
"https://myapplicationmyaccount.hana.ondemand.com",
"https://myapplicationmyaccount.hana.ondemand.com/app2"
],
"applicationProcesses": [
{
"id": "fc735dc",
"state": "STARTED",
"lastChange": "2014-02-25T18:07:48Z",
"runtime": "1.47.10.2"
}
]
}
}

Note
The shown command result is only an example and may look different in the real or future implementation. The
output is similar for commands that do not support structured result values but the result property is then null.

Related Information
Exit Codes [page 262]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

95

Viewing the Default Trace [page 1115]

1.3.6.4

Console Client Commands

Table 22:
Group

Commands

Local Server

install-local [page 184]; deploy-local [page 146]; start-local [page 242];


stop-local [page 246]

Deployment

deploy [page 141]; start [page 240]; status [page 238]


stop [page 244]; restart [page 218]; undeploy [page 254]
disable [page 147]; enable [page 158];
list-runtimes [page 202]; list-runtime-versions [page 203];
display-application-properties [page 149]; set-application-property
[page 229]; start maintenance [page 243]; stop maintenance [page
247];
rolling-update [page 224]; hot-update [page 182];
clear-downtime-app [page 108]; set-downtime-app [page 234]

Logging

list-logs [page 201]; get-log [page 162]


list-loggers [page 200]; set-log-level [page 235]

Monitoring

list-availability-check [page 186]; create-availability-check [page 113];


delete-availability-check [page 126]
list-jmx-checks [page 197]; create-jmx-check [page 120]; delete-jmxcheck [page 135]
list-alert-recipients [page 188]; set-alert-recipients [page 227]; clearalert-recipients [page 107]

Keystore

list-keystores [page 199]; upload-keystore [page 259]; download-key


store [page 154]; delete-keystore [page 139];

Connectivity

put-destination [page 211]


get-destination [page 159]
delete-destination [page 131]

96

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Group

Commands

Persistence

list-application-datasources [page 185]; list-dbms [page 191]; list-dbs


[page 192]; list-schemas [page 204]
create-schema [page 123]; bind-schema [page 106]; unbind-schema
[page 253]; delete-schema [page 140]; display-schema-info [page
153]
bind-hana-dbms [page 104]; unbind-hana-dbms [page 252]
list-dbs [page 192]; create-db-ase [page 114]; create-db-user-ase [page
117]; display-db-info [page 152]; set-db-properties-ase [page 232];
bind-db [page 102]; unbind-db [page 250]; delete-db-ase [page 127];
delete-db-user-ase [page 129]
create-db-hana [page 116]; set-db-properties-hana [page 233]; startdb-hana [page 241]; stop-db-hana [page 246]; delete-db-hana [page
128]
grant-schema-access [page 165]; revoke-schema-access [page 223];
list-schema-access-grants [page 205]
open-db-tunnel [page 210]; close-db-tunnel [page 109]
restart-hana [page 220]
grant-db-tunnel-access [page 164]; revoke-db-tunnel-access [page
222]; list-db-tunnel-access-grants [page 194]

Document Service

add-ecm-tenant [page 98]; create-ecm-repository [page 118]; deleteecm-repository [page 132]; display-ecm-repository [page 151]; editecm-repository [page 156]; list-ecm-repositories [page 195]; resetecm-key [page 216]

Account and Quota Management

create-account [page 110]; delete-account [page 125]; list-accounts


[page 187]; set-quota [page 237]

Subscription Management

subscribe [page 248]; unsubscribe [page 255]; list-subscribed-accounts


[page 208]; list-subscribed-applications [page 209]

HANA XS SAML2

delete-hanaxs-certificates [page 134];list-hanaxs-certificates [page


196];reconcile-hanaxs-certificates [page 213];upload-hanaxs-certifi
cates [page 258]

Applicaton Domains

add-custom-domain [page 99]; add-platform-domain [page 101]; listapplication-domains [page 189]; remove-custom-domain [page 214];
remove-platform-domain [page 215]

Custom SSL

create-ssl-host [page 124]; delete-ssl-host [page 138]; list-ssl-hosts


[page 207]; display-csr [page 150]; generate-csr [page 161]; bind-do
main-certificate [page 103]; delete-domain-certificate [page 133]; up
load-domain-certificate [page 256]; list-domain-certificates [page 193];
unbind-domain-certificate [page 251];

System

version [page 261]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

97

Group

Commands

Extensions

hcmcloud-create-connection (Beta) [page 166]; hcmcloud-delete-con


nection (Beta) [page 167]; hcmcloud-disable-application-access (Beta)
[page 169]; hcmcloud-display-application-access-status (Beta) [page
170]; hcmcloud-enable-application-access (Beta) [page 172];
hcmcloud-enable-role-provider (Beta) [page 173]; hcmcloud-get-regis
tered-home-page-tiles (Beta) [page 175]; hcmcloud-import-roles (Beta)
[page 176]; hcmcloud-list-connections (Beta) [page 178]; hcmcloudregister-home-page-tiles (Beta) [page 179]; hcmcloud-unregisterhome-page-tiles (Beta) [page 181]

1.3.6.4.1

add-ecm-tenant

Adds a new tenant to a repository.


neo add-ecm-tenant --account <account_name> --host <landscape_host> --user <email_or_user> --name <repository_name> --key <repository_key> --tenant
<tenant_name> --virus-scan <true/false>

Parameters
Table 23:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID, or user name.

Type: string
-n, --name

Name of the repository

Type: string
-t, --tenant

Tenant alias

Type: string
-k, --key

Key of the repository

Type: string

98

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 24:
Optional

-v, --virus-scan

Can be used to activate the virus scanner and check all incoming documents for viruses.

Default: true
Type: boolean

Recommendation
For repositories that are used by untrusted users and or for unknown content, we rec
ommend that you enable the virus scanner by setting this parameter to true. Enabling
the virus scanner could impair the upload performance.
If a virus is detected, the upload process for the document fails with a virus scanner ex
ception.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example

neo add-ecm-tenant --account sap --host hana.ondemand.com --user


<myemail@example.com> --name DemoRepository --key ecm_012345689 --tenant sap2 -virus-scan true
This example adds the sap2 tenant to the DemoRepository repository.

1.3.6.4.2

add-custom-domain

Use this command to add a custom domain to an application URL. This will route the traffic for the custom domain
to your application on SAP HANA Cloud Platform.
neo add-custom-domain --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --custom-domain <custom_domain>
--application-url <app_url> --ssl-host <ssl_host>

Parameters
To list all parameters available for this command, execute neo help add-custom-domain in the command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

99

Table 25:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-e, --custom-domain

Custom domain for accessing the application

Type: string (hostname such as mydomain.com or shop.mydomain.com corresponding


to the CN/SAN of the certificate)

-i, --application-url

The access point of the application on SAP HANA Cloud Platform default domains
(hana.ondemand.com, etc.)

Type: string (hostname such as myapp.hana.ondemand.com or shop-myten


ant.hana.ondemand.com)

-l, --ssl-host

SSL host as defined with the --name parameter when created, or 'default' if not speci
fied.

Example
neo add-custom-domain --account myacc --user mymail@example.com --host
hana.ondemand.com --custom-domain www.example.com
--application-url myaccountmyapp-subscription.hana.ondemand.com --ssl-host
mysslhostname

Related Information
Add the Custom Domain [page 1190]
list-custom-domain-mappings [page 190]
remove-custom-domain [page 214]
Configuring Custom Domains [page 1186]

100

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.3

add-platform-domain

Adds a platform domain (under hana.ondemand.com) on which the application will be accessed.
neo add-platform-domain --account <account_name> --application <application_name> -user <e-mail_or_user> --host <landscape_host> --platform-domain <platform_domain>

Parameters
To list all parameters available for this command, execute neo help add-platform-domain in the command
line.
Table 26:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-m, --platform-domain

Platform domain under hana.ondemand.com


The chosen platform domain will be parent domain in the absolute application domain.

Acceptable values:

svc.hana.ondemand.com

cert.hana.ondemand.com

Example

neo add-platform-domain --account myacc --application myapp --user myuser -- host


haha.ondemand.com --platform-domain svc.hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

101

Related Information
Platform Domains [page 1196]
remove-platform-domain [page 215]

1.3.6.4.4

bind-db

This command binds a database to a Java application using a data source.


You can only bind an application to a database if the application is deployed.
Database in the same account:
neo bind-db -a <account_name> -b <application_name> -h <landscape_host> -u <email_or_user> -i <database_ID> --db-user <database_user> --db-password
<database_user_password>
Database in another account:
neo bind-db -a <account_name> -b <application_name> -h <landscape_host> -u <email_or_user> --access-token vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1c6uu8b9pt9z
--db-user <database_user> --db-password <database_user_password>

Parameters
Table 27:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

Database ID

Type: string
--access-token

Identifies a database access permission. The access token and database ID parameters
are mutually exclusive.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

102

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required
Use your e-mail, SAP ID, or user name

-u, --user

Type: string
--db-password

Password of the database user used to access the database

--db-user

Name of the database user used to access the database

Table 28:
Optional

-s, --data-source

Data source name


Default: <DEFAULT>

Example
Database in the same account:
neo bind-db -a myaccount -b myapp -h hana.ondemand.com -u mymail@example.com -i
mydb --db-user MYDBUSER --db-password SECRET
Database in another account:
neo bind-db -a myaccount -b myapp -h hana.ondemand.com -u mymail@example.com -access-token 120579jy40i15v1dqv3n3fsw40ug52m6re9fzqxg46l3fah0w0 --db-user
MYDBUSER --db-password SECRET

1.3.6.4.5

bind-domain-certificate

Binds a certificate to an SSL host. The certificate must already be uploaded.


neo bind-domain-certificate --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --ssl-host <ssl_hostname> --certificate <certificate_name>

Parameters
To list all parameters available for this command, execute neo help bind-domain-certificate in the
command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

103

Table 29:
Required
Account name

-a, --account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Use the respective landscape host for your account type.

-h, --host

Type: URL. For acceptable values see Landscape Hosts [page 32]
To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

-p, --password

Type: string
Use your email, SAP ID or user name

-u, --user

Type: string
Name of the certificate that you set to the SSL host

--certificate

The certificate must already be uploaded.

-l, --ssl-host

SSL host as defined with the --name parameter when created, or 'default' if not speci
fied.

Example
neo bind-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --ssl-host mysslhostname --certificate myfirstcert

Related Information
Bind the Certificate to the SSL Host [page 1189]
Configuring Custom Domains [page 1186]

1.3.6.4.6

bind-hana-dbms

This command binds a Java application to a productive SAP HANA database via a data source.
You can only bind an application to a productive SAP HANA database if the application is deployed.
The following commands are available:
Database in the same account:
neo bind-hana-dbms -a <account_name> -b <application_name> -h <landscape_host> u <e-mail_or_user> -i <productive_HANA_database> --db-user <database_user> --dbpassword <database_user_password>

104

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Database in another account:


neo bind-hana-dbms -a <account_name> -b <application_name> -h <landscape_host> u <e-mail_or_user> --access-token
120579jy40i15v1dqv3n3fsw40ug52m6re9fzqxg46l3fah0w0 --db-user <database_user> -db-password <database_user_password>

Parameters
Table 30:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]

Note
The host must be on the productive landscape.

-i, --id

ID of the productive SAP HANA database

Type: string
--access-token

Identifies a database access permission. The access token and database ID parameters
are mutually exclusive.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
--db-password

Password of the database user used to access the productive SAP HANA database

--db-user

Name of the database user used to access the productive SAP HANA database

Table 31:
Optional

-s, --data-source

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Data source name

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

105

Example
Database in the same account:
neo bind-hana-dbms -a myaccount -b myapp -h hana.ondemand.com -u
mymail@example.com -i myhanaxs --db-user MYPRODHANA --db-password SECRET
Database in another account:
neo bind-hana-dbms -a myaccount -b myapp -h hana.ondemand.com -u
mymail@example.com --db-user MYPRODHANA --db-password SECRET --access-token
120579jy40i15v1dqv3n3fsw40ug52m6re9fzqxg46l3fah0w0

Related Information
unbind-hana-dbms [page 252]

1.3.6.4.7

bind-schema

This command binds a schema to a Java application via a data source. If a data source name is not specified, the
schema will be automatically bound to the default data source of the application.
You can only bind a schema to an application if the application is deployed.
neo bind-schema -a <account_name> -b <application_name> -h <landscape_host> -u <email_or_user> -i <schema_ID>

Parameters
Table 32:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

Schema ID

Type: string

106

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

--access-token

Identifies a schema access grant. The access token and schema ID parameters are mutu
ally exclusive.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
Use your e-mail, SAP ID, or user name

-u, --user

Type: string
Table 33:
Optional

-s, --data-source

Data source name


The application will be able to access the schema via the specified data source.

Example

neo bind-schema -a myaccount -b myapp -h hanatrial.ondemand.com -u


mymail@example.com -i myschema -s datasource1

Related Information
Example Scenarios [page 811]
Binding Schemas [page 808]
grant-schema-access [page 165]
unbind-schema [page 253]
bind-hana-dbms [page 104]
unbind-hana-dbms [page 252]

1.3.6.4.8

clear-alert-recipients

Clears alert recipients.


If no emails are specified, it clears all recipients.
neo clear-alert-recipients

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

107

Parameter
Table 34:
Required
Account name

-a, --account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Use your email, SAP ID or user name

-u, --user

Type: string
Table 35:
Optional

-b, --application

Application name for Java applications or productive SAP HANA database system, and
application name in the format <database name>:<application name> for SAP HANA XS
applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Use the respective landscape host for your account type.

-h, --host

Type: URL. For acceptable values see Landscape Hosts [page 32]
Comma separated list of recipient e-mails

-e, --email

Type: string

Example
neo clear-alert-recipients -a myaccount -b demo -u p1234567 --host
hana.ondemand.com

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.9

clear-downtime-app

The command deregisters a previously configured downtime page for an application. After you execute the
command, the default HTTP error will be shown to the user in the event of unplanned downtime.
neo clear-downtime-app --account <account_name> --application <application_name> -host <landscape_host>
--user <e-mail_or_user>

108

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help clear-downtime-app in the command
line.
Table 36:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
neo clear-downtime-app --account myacc --application myapp --user
<mymail@example.com

Related Information
set-downtime-app [page 234]

1.3.6.4.10 close-db-tunnel
This command closes one or all database tunnel sessions that have been opened in a background process using
the open-db-tunnel --background command.
neo close-db-tunnel --session-id <session_ID>
A tunnel opened in a background process is automatically closed when the last session using the tunnel is closed.
The background process terminates after the last tunnel has been closed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

109

Parameters
Table 37:
Required

--all

Closes all tunnel sessions that have been opened in the background

--session-id

Tunnel session to be closed. Cannot be used together with the parameter --all.

Example
neo close-db-tunnel --session-id f4b00f06-df0a-4018-b725-392a93b49bd4

Related Information
open-db-tunnel [page 210]
Automating the Use of Database Tunnels [page 856]

1.3.6.4.11 create-account
Creates a new account with an automatically generated unique ID as account name and the specified display
name and assigns the user as an account owner. The user is authorized against the existing account passed as -account parameter. Optionally, you can clone an existing account configuration to save time and effort.
neo create-account --display-name <account_display_name> --account <account_name> -user <e-mail_or_user> --host <landscape_host> --clone <cloning_options>

Note
If you clone an existing extension account [page 1062], the new account will not be an extension account but a
regular one. The new account will not have the trust and destination settings typical for extension accounts.

Parameters
To list all parameters available for this command, execute neo help create-account in the command line.

110

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 38:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-n, --display-name

Account display name


If you want to create an account whose display name has intervals, use quotes when exe
cuting the command. For example: neo ... --display-name "Display Name with Intervals"

Type: string (up to 255 characters)


-u, --user

Use your email, SAP ID or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
--clone

(Optional) List of settings that will be copied (re-created) from the existing account into
the new account. A comma separated list of values, which are as follows:

trust

members

destinations

all

Each value combination is acceptable, for example, trust,members or all. If speci


fied, all the configurations of the passed type(s) will be cloned to the newly created ac
count.

Tip
We recommend listing explicitly the required cloning options instead of using --

clone all in automated scripts. This will ensure backward compatibility in case the
available cloning options, enveloped by all, change in future releases.

Example
neo create-account --account myaccount --display-name mynewaccount --user myuser -host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

111

Cloning Existing Accounts


You may choose among the following cloning options:
Table 39:
Cloning Option

Description

all

All settings (trust, members and destinations) from the exist


ing account will be copied into the new one.

Caution
The list of cloned configurations might be extended in the
future.

trust

The following trust settings will be re-created in the new ac


count similarly to the relevant settings in the existing account:

Trusted SAP Cloud Identity tenants - the new account will


have trust to the SAP Cloud Identity tenants registered in
the exisitng account. The respective SAP Cloud Identity
tenants, in turn, will automatically register a new service
provider corresponding to the new SAP HANA Cloud Plat
form account.

Note
SAP HANA Cloud Platform will generate a new pair of
key and certificate on behalf of the new account. Re
member to replace them with your proprietary key
and certificate when using the account for productive
purposes.
All other trust settings (for example, trusted on-premise iden
tity providers) from the existing account will not be copied
into the new account.

Note
If you do not have any trusted SAP Cloud Identity tenants
in the existing account, cloning the trust settings will result
in trust with SAP ID Service (as default identity provider) in
the new account.

members

All members with their roles from the existing account will be
copied into the new one.

112

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Cloning Option

Description

destinations

All destinations from the existing account will be created into


the new one. In addition, the relevant certificates and pass
words for the destinations will also be cloned so the destina
tion configurations will be fully functional in the new account.

Example of cloning an existing account to create a new account with the same trust settings and existing
destinations:
neo create-account --account myaccount --display-name mynewaccount --user myuser -host hana.ondemand.com --clone trust,destinations

1.3.6.4.12 create-availability-check
Creates an availability check.
neo create-availability-check

Parameters
Table 40:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-U, --url

Relative application URL

Type: string
Table 41:
Optional

-b, --application

Application name for Java applications or productive SAP HANA database system, and
application name in the format <database name>:<application name> for SAP HANA XS
applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

113

Optional

-W, --warning

Threshold value or range of the response time in seconds.

Default: 50
Type: string
-C , --critical

Threshold value or range of the response time in seconds.

Default: 60
Type: string
-w, --overwrite

Should be used only if there is an existing alert that needs to be updated.

Default: false
Type: boolean

Example
Example for creating an availability check for application demo:
neo create-availability-check -a myaccount -b demo -u p1234567 -U /heartbeat -C 4
-W 6 --host hana.ondemand.com
Example for creating an availability check for myhana application:
neo create-availability-check -a myaccount -b myhanainstance:myhana -u p1234567 U /heartbeat.xsjs -C 4 -W 6 --host hana.ondemand.com

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.13 create-db-ase
This command creates an ASE database with the specified ID and settings on an ASE database system.
neo create-db-ase -a <account_name> -h <landscape_host> -u <e-mail_or_user> -dbsystem <database_system> -i <database_ID> --db-user <dbuser> --db-password
<database_user_password> --db-size <database_size>

114

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 42:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, start


ing with a letter)

-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console cli
ent and not explicitly as a parameter in the properties file or the command
line.

Type: string
-i, --id

ASE database ID

Type: string
--dbsystem

ID of a productive ASE database system

Type: string
--db-user

Name of the user for the ASE database

Type: string (up to 30 characters, starting with a letter)


--db-password

Password of the database user used to access the ASE database (op
tional, queried at the command prompt if omitted)

--db-size

Size of the database in MB

Note
This parameter sets the maximum database size. The minimum data
base size is 24 MB. You receive an error if you enter a database size
that exceeds the quota for this database system.

Example
neo create-db-ase -a myaccount -h hana.ondemand.com -u mymail@example.com -dbsystem mydbsys -i mydb --db-user mydbuser --db-password SECRET --db-size mydbsize

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

115

Related Information
delete-db-ase [page 127]

1.3.6.4.14 create-db-hana
This command creates a SAP HANA database with the specified ID and settings, on a SAP HANA database
system enabled for multitenant database containers.
neo create-db-hana -a <account_name> -h <landscape_host> -u <e-mail_or_user> -dbsystem <database_system> -i <database_ID> --db-password <database_user_password>

Parameters
Table 43:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

HANA database ID

Type: string
--dbsystem

ID of a productive HANA database system

Type: string

Note
To create a tenant database on a trial landscape, use -trial- instead of the ID of a pro
ductive HANA database system.

--db-password

116

Password of the SYSTEM user used to access the HANA database (optional, queried at
the command prompt if omitted)

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 44:
Optional

--dp-server

Enables or disables the data processing server of the HANA database: 'enabled', 'disa
bled' (default).

--script-server

Enables or disables the script server of the HANA database: 'enabled', 'disabled' (default).

--web-access

Enables or disables access to the HANA database from the Internet: 'enabled' (default),
'disabled'

--xsengine-mode

Specifies how the XS engine should run: 'embedded' (default), 'standalone'.

Example
neo create-db-hana -a myaccount -h hana.ondemand.com -u mymail@example.com -dbsystem mydbsys -i mydb --db-password SECRET

1.3.6.4.15 create-db-user-ase
This command creates a user for an ASE database.
neo create-db-user-ase -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID> --db-user <dbuser> --db-password <database_user_password>

Parameters
Table 45:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

117

Required

-i, --id

ASE database ID

Type: string
--db-user

Name of the user for the ASE database

Type: string (up to 30 characters, starting with a letter)


--db-password

Password of the database user used to access the ASE database (optional, queried at the
command prompt if omitted)

Example
neo create-db-user-ase -a myaccount -h hana.ondemand.com -u mymail@example.com -i
mydb --db-user mydbuser --db-password SECRET

1.3.6.4.16 create-ecm-repository
Creates a new repository in the specified account.
neo create-ecm-repository --account <account_name> --host <landscape_host> --user
<e-mail_or_user> --name <repository_name> --key <repository_key> --display
<display_name_of_repository> --description <description_of_repository> --virus-scan
<true/false>

Parameters
Table 46:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID, or user name.

Type: string

118

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-n, --name

Name of the repository

Type: string
-k, --key

Key of the repository

Type: string
Table 47:
Optional

-d, --display-name

Can be used to provide a more readable name of the repository. Equals the --name value
if left blank. You cannot change the display later on.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-e, --description

Description of the repository. You cannot change the description later on.

Type: string
-v, --virus-scan

Can be used to activate the virus scanner and check all incoming documents for viruses.

Default: true
Type: boolean

Recommendation
For repositories that are used by untrusted users and or for unknown content, we rec
ommend that you enable the virus scanner by setting this parameter to true. Enabling
the virus scanner could impair the upload performance.
If a virus is detected, the upload process for the document fails with a virus scanner ex
ception.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo create-ecm-repository --account sap --host hana.ondemand.com --user
<myemail@example.com> --name DemoRepository --key ecm_012345689 --display-name
DemoRep --description "Demo Repository" --virus-scan true
SAP HANA Cloud Platform Console Client
Repository DemoRepository created successfully.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

119

1.3.6.4.17 create-jmx-check
Creates a JMX check.
neo create-jmx-check -a <account_name> -u <e-mail_or_user> -n <JMX_check_name> -O
<MBean_object_name> -A <MBean_object_attribute>

Parameters
Note
The JMX check settings support the JMX specification. For more information, see Java Management
Extensions (JMX) Specification .
Table 48:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name

Name of the JMX check


The name must be up to 99 characters long and must not contain the following symbols:
`~!$%^&*|'"<>?,()=

Type: string
-O, --object-name

Object name of the MBean that you want to call


If it contains quotation marks, they should be escaped with \.

Type: string
-A, --attribute

Name of the attribute inside the class with the specified object name.

Type: string

120

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 49:
Optional

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Note
If the parameter is not used, the JMX check will be on account level for all running ap
plications in the account.

-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Note
If the parameter is not used, the default host is hana.ondemand.com.

-K, --key

Attribute key
It is needed only if the attribute is a composite data structure. This key defines the item in
the composite data structure. For more information about the composite data structure,
see Class CompositeDataSupport

Type: string
-o, --operation

Operation that has to be called on the MBean after checking the attribute value.
It is useful for resetting statistical counters to restart an operation on the same MBean.

Type: string
-U, --unit

Unit of measurement

Type: string
-W, --warning

Warning threshold
The threshold can be a regular expression in case of string values or compliant with the
official nagios threshold/ranges format. For more information about the format in case it
is a number, see the official nagios documentation

-C , --critical

Critical threshold
The threshold can be a regular expression in case of string values or compliant with the
official nagios threshold/ranges format. For more information about the format in case it
is a number, see the official nagios documentation

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

121

Optional

-w, --overwrite

Overwrites an existing check.

Default: false
Type: boolean

Note
When you use this parameter, a new JMX check is not created when the one you spec
ify does not exist.

Example 1: Configuring a JMX Check


For a typical example how to configure a JMX check for your application and subscribe recipients to receive
notification alerts, see Configuring a JMX Check to Monitor Your Application [page 1157].

Example 2: Using Warning and Critical Thresholds


The following example creates a JMX check that returns a warning state of the metric if the value is between 10
and 100 bytes, and returns a critical state if the value is greater than 100 bytes. If the value is less than 10 bytes,
the returned state is OK.
neo create-jmx-check -a myaccount -b demo -u p1234567 -n "JVM Heap Memory Used" -O
java.lang:type=Memory -A HeapMemoryUsage -K used -U B -W 10 -C 100 -h
hana.ondemand.com

Example 3: Using an Operation on an MBean


neo create-jmx-check -a myaccount -b demo -u p1234567 -n "JVM Heap Memory Used" -O
Catalina:type=GlobalRequestProcessor,name="http-bio-8041" -A HeapMemoryUsage o
resetCounters

Related Information
JMX Checks [page 1156]
Monitoring Java Applications [page 1149]

122

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.18 create-schema
This command creates a HANA database or schema with the specified ID on a shared or dedicated database.

Caution
This command is not supported for productive SAP HANA database systems. For more information about how
to create schemas on productive SAP HANA database systems, see Binding SAP HANA Databases to Java
Applications [page 792].
neo create-schema --account <account_name> --host <landscape_host> --id <schema_ID>
--user <e-mail_or_user> --dbtype <database_type>

Parameters
Table 50:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-d, --dbtype

Creates the HANA database or schema on a shared database system. Syntax: 'type:ver
sion'. Version is optional.
Available database types: 'MaxDB', 'HANA', and 'HANAXS' (case-insensitive)
To see which versions are available, execute the list-dbms command.

Type: string
--dbsystem

Creates the schema on a dedicated database system. To see the available dedicated da
tabase systems, execute the list-dbms command.

Type: string

Caution
The list-dbms command lists different database types, including productive SAP
HANA database systems. Do not use the create-schema command for productive
SAP HANA database systems. For more information about how to create schemas on
productive SAP HANA database systems, see Binding SAP HANA Databases to Java
Applications [page 792].

-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

123

Required

-i, --id

HANA database or schema ID


It must start with a letter and can contain lowercase letters ('a' - 'z') and numbers ('0' '9'). For schemas IDs, uppercase letters ('A' - 'Z') and the special characters '.' and '-' are
also allowed.
The ID must be unique within the account.
Note that the actual ID assigned in the database will be different to this version.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example
neo create-schema --account myaccount --host hanatrial.ondemand.com -i myschema -user mymail@example.com --dbtype hana

Related Information
Example Scenarios [page 811]
Managing Schemas [page 804]

1.3.6.4.19 create-ssl-host
Creates an SSL host for configuration of custom domains. This SSL host will be serving your custom domain.
neo create-ssl-host --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --name <ssl_host_name>

Parameters
To list all parameters available for this command, execute neo help create-ssl-host in the command line.

124

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 51:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 52:
Optional

-n, --name

Unique identifier of the SSL host. If not specified, 'default' value is set.

Type: string (alphanumeric symbols allowed)

Example
neo create-ssl-host --account myaccount --user mymail@example.com --host
hana.ondemand.com --name mysslhostname

Related Information
Create an SSL Host [page 1187]
Configuring Custom Domains [page 1186]

1.3.6.4.20 delete-account
Deletes a particular account. Only the user who has created the account is allowed to delete it.

Note
You cannot delete an account if it still has associated non-shared database systems, database schemas,
deployed applications, HTML5 applications, or subscriptions. The persistence service provides a set of console

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

125

client commands for managing schemas which can list the schemas and delete them respectively. For more
information, see Schema Commands [page 821].

neo delete-account --account <account_name> --user <e-mail_or_user> --host


<landscape_host>

Parameters
To list all parameters available for this command, execute neo help delete-account in the command line.
Table 53:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example

neo delete-account --account myaccount --user myuser --host hana.ondemand.com

1.3.6.4.21 delete-availability-check
Deletes an availability check.
neo delete-availability-check

126

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 54:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
Table 55:
Optional

-b, --application

Application name for Java applications or productive SAP HANA database system, and
application name in the format <database name>:<application name> for SAP HANA XS
applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example
neo delete-availability-check -a myaccount -b demo -u p1234567 --host
hana.ondemand.com

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.22 delete-db-ase
This command deletes the ASE database with the specified ID.
neo delete-db-ase -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

127

Parameters
Table 56:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

ASE database ID

Type: string
Table 57:
Optional

--force or -f

Forcefully deletes the ASE database, including all application bindings

--silent

Suppresses the command line confirmation prompt

Example
neo delete-db-ase -a myaccount -h hana.ondemand.com -u mymail@example.com -i mydb

Related Information
create-db-ase [page 114]

1.3.6.4.23 delete-db-hana
This command deletes the SAP HANA database with the specified ID on a SAP HANA database system enabled
for multitenant database container support.
neo delete-db-hana -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID>

128

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 58:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

HANA database ID

Type: string
Table 59:
Optional

--force or -f

Forcefully deletes the HANA database, including all application bindings

--silent

Suppresses the command line confirmation prompt

Example

neo delete-db-hana -a myaccount -h hana.ondemand.com -u mymail@example.com -i mydb

1.3.6.4.24 delete-db-user-ase
This command deletes a user from an ASE database.
neo delete-db-user-ase -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID> --db-user <dbuser>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

129

Parameters
Table 60:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

ASE database ID

Type: string
--db-user

Name of the user for the ASE database

Table 61:
Optional

--silent

Suppresses the command line confirmation prompt

Example
neo delete-db-user-ase -a myaccount -h hana.ondemand.com -u mymail@example.com -i
mydb --db-user mydbuser

Related Information
create-db-user-ase [page 117]

130

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.25 delete-destination
This command deletes destination configuration properties files and JDK files. You can delete them on account,
application or subscribed application level.
neo delete-destination --account <account_name> --user <e-mail_or_user> --name
<destination_file_or_JKS_file> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help delete-destination in the command
line.
Table 62:
Required

-a, --account

Your account. The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

The application for which you delete a destination. Cases:

Use --application <myapp> if the application is running in your account.

Use --application <provider_account>:<provider_app> if the ap


plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
--name

The name of the destination or JKS file to be deleted.

Type: string
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string

Examples
To delete a destination on account level, execute:
neo delete-destination --account myaccount --user p1234567890 --name
myconfiguration.jks --host hanatrial.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

131

To delete a destination on application level, execute:


neo delete-destination --account myaccount --user p1234567890 --application demo
--name weather --host hanatrial.ondemand.com
To delete a destination on subscribed application level, execute:
neo delete-destination --account myaccount --user p1234567890 --application
otheraccount:remotedemo --name weather --host hanatrial.ondemand.com

Related Information
Deleting Destinations [page 288]
Exit Codes [page 262]

1.3.6.4.26 delete-ecm-repository
This command deletes a repository including the data of any tenants in the repository, unless you restrict the
command to a specific tenant.

Caution
Be very careful when using this command. Deleting a repository permanently deletes all data. This data cannot
be recovered.

Parameters
Table 63:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID, or user name.

Type: string
-n, --name

Name of the repository

Type: string

132

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-k, --key

Key of the repository

Type: string
Table 64:
Optional

-t, --tenant

Tenant alias
Deletes the repository for the given tenant only instead of for all tenants. If no tenant
name is provided, the repositories for all tenants are deleted.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo delete-ecm-repository --account sap --host hana.ondemand.com --user
<myemail@example.com> --name DemoRepository --key ecm_012345689
SAP HANA Cloud Platform Console Client
Are you sure you want to permanently delete all data? This operation cannot be
reverted. (yes/no)
yes
Delete command executed successfully.

1.3.6.4.27 delete-domain-certificate
Deletes a certificate.

Note
Cannot be undone. If the certificate is mapped to an SSL host, the certificate will be removed from the SSL host
too.
neo delete-domain-certificate --account <account_name> --user <e-mail_or_user> -host <landscape_host> --name <certificate_name>

Parameters
To list all parameters available for this command, execute neo help delete-domain-certificate in the
command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

133

Table 65:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name

Name of the certificate that you set to the SSL host


The certificate must already be uploaded.

Example
neo delete-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --name myfirstcert

Related Information
Bind the Certificate to the SSL Host [page 1189]
bind-domain-certificate [page 103]

1.3.6.4.28 delete-hanaxs-certificates
This command deletes certificates that contain a specified string in the Subject CN.

Note
After executing this command, a you need to restart the SAP HANA XS services for it to take effect. See
restart-hana [page 220].
neo delete-hanaxs-certificates --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user> --contained-string
<certificate_CN>

134

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help delete-hanaxs-certificates in the
command line.
Table 66:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-cn-string, --containedstring

A part of the certificate CN. All certificates that contain this string shall be deleted.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

Example
To delete all certificates containing John Doe in their Subject DN, execute:
neo delete-hanaxs-certificates --host hana.ondemand.com --account myacc -application myapp --user mymail@example.com --contained-string John Doe

1.3.6.4.29 delete-jmx-check
Deletes the specified JMX check or all JMX checks.
neo delete-jmx-check -a <account_name> -u <e-mail_or_user> -n <JMX_check_name>
or

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

135

neo delete-jmx-check -a <account_name> -u <e-mail_or_user> -A

Parameters
Table 67:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name or -A, all

Name of the JMX check to be deleted or all JMX checks configured for the given account
and application are deleted.

Type: string
Table 68:
Optional

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Note
If the parameter is not used, the default host is hana.ondemand.com.

Example
neo delete-jmx-check -a myaccount -b demo -u p1234567 -n "JVM Heap Memory Used" h hana.ondemand.com

Related Information
JMX Checks [page 1156]
Monitoring Java Applications [page 1149]

136

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.30 delete-resource (Beta)


Deletes a solution resource file from the system repository of a specified extension account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo delete-resource --name <resource_name> --account <account_name> --user <email_or_user> --host <landscape_host> --silent

Parameters
To list all parameters available for this command, execute neo help delete-resource in the command line.
Table 69:
Required

-n, --name

Name of the resource to be deleted

Type: string
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 70:
Optional

-s, --silent

Suppresses the command-line confirmation prompt

Example
To delete a solution resource from the system repository for your extension account, execute:
neo delete-resource --name myresourcename --account myextensionacc --user
mymail@example.com --host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

137

1.3.6.4.31 delete-ssl-host
Deletes an SSL host.
neo delete-ssl-host --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --name <ssl_host_name>

Parameters
To list all parameters available for this command, execute neo help delete-ssl-host in the command line.
Table 71:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name

SSL host as defined with --create-ssl-host

Type: string

Example
neo delete-ssl-host --account myaccount --user mymail@example.com --host
hana.ondemand.com --name mysslhostname

Related Information
create-ssl-host [page 124]
list-ssl-hosts [page 207]

138

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.32 delete-keystore
This command is used to delete a keystore by deleting the keystore file. You can delete keystores on account,
application, and subscription levels.

Parameters
To list all parameters available for this command, execute neo help delete-keystore in the command line.
Table 72:
Required

-a, --account

Consumer account name


The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-n,--name

Name of the keystore to be deleted

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 73:
Optional

-b, --application

Application name

Use --application <consumer_application_name> if the application is


running in your account.

Use --application
<provider_account_name>:<provider_application_name> if the ap
plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Example
On Subscription Level
neo delete-keystore --account <consumer_account_name> --application
<provider_account_name>:<provider_application_name>
--user <e-mail_or_user> --name KeyStore1 --host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

139

On Application Level
neo delete-keystore --account <consumer_account_name> --application
<consumer_application_name>
--user <e-mail_or_user> --name KeyStore1 --host hana.ondemand.com
On Account Level
neo delete-keystore --account <consumer_account_name> --user <e-mail_or_user> -name KeyStore1 --host hana.ondemand.com

Related Information
Keystore Console Commands [page 1248]
Keys and Certificates [page 1246]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

1.3.6.4.33 delete-schema
This command deletes the specified schema, including all data it contains. A schema cannot be deleted if it is still
bound to an application. To enforce the deletion, use the force parameter but bear in mind that this will also delete
all bindings that still exist.
Schema backups are kept for 14 days and may be used to restore mistakenly deleted data (available by special
request only).
neo delete-schema -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<schema_ID>

Parameters
Table 74:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.


Type: URL, for acceptable values see Landscape Hosts [page 32]

-i, --id

HANA database or schema ID

Type: string

140

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 75:
Optional

-f, --force

Forcefully deletes the schema, including all application bindings

Default: off
Type: switch, takes no value
--silent

Suppresses the command line confirmation prompt

Default: off
Type: switch, takes no value

Example

neo delete-schema -a myaccount -h hanatrial.ondemand.com -u mymail@example.com -i


myschema

Related Information
Managing Schemas [page 804]

1.3.6.4.34 deploy
Deploying an application publishes it to SAP HANA Cloud Platform. Use the optional parameters to make some
specific configurations of the deployed application.
neo deploy --host <landscape_host> --account <account_name> --application
<application_name>
--source <file_location> --user <e-mail_or_user>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

141

Parameters
To list all parameters available for this command, execute neo help deploy in the command line.
Table 76:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-s, --source

A comma-separated list of file locations, pointing to WAR files, or folders containing them

Note
The size of an application can be up to 1.5 GB. If the application is packaged as a WAR
file, the size of the unzipped content is taken into account.
If you want to deploy more than one application on one and the same application process,
put all WAR files in the same folder and execute the deployment with this source, or spec
ify them as a comma-separated list.

Type: file location


-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
To deploy an application on more than one landscape, execute the deploy separately for
each landscape host.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 77:
Optional
Command-specific parameters

142

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Optional

--connections

The number of connections used to deploy an application.


Use it to speed up deployment of application archives bigger than 5 MB in slow networks.
Choose the optimal number of connections depending on the overall network speed to
the cloud.

Default: 2
Acceptable values: 1-6
Type: integer
--delta

Deploys only the changes between the provided source and the deployed content. New
content will be added; missing content will be deleted. Recommended for development
use to speed up the deployment.

Acceptable values: None


--ev

Environment variables for configuring the environment in which the application runs.
Sets one environment variable by removing the previously set value; can be used multiple
times in one execution.

Type: --ev <KEY1>=<VALUE1> --ev <KEY2>=<VALUE2> , where a key-value pair speci


fies one environment variable
If you provide a key without any value (--ev <KEY1>=), the ev parameter is ignored.
For a value that contains spaces, use quotation marks.

-j, --java-version

Java Virtual Machine major version number

Default: depends on the SAP HANA Cloud Platform SDK


Type: the version number of the JRE 7.
(beta) You can use JRE 8 with the Java Web Tomcat 7 runtime (neo-java-web version 2.25
or higher) in accounts enabled for beta features.
For more information, see Choosing JRE Version [page 1103]

-m, --minimum-processes

Minimum number of application processes, on which the application can be started

Default: 1
-M, --maximum-processes

Maximum number of application processes, on which the application can be started

Default: 1

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

143

Optional

-V, --vm-arguments

Java Virtual Machine arguments


System properties (-D<name>=<value>) separated with space that will be used when
starting the application process.
Memory settings of your compute units. You can set the following memory parameters: Xms, -Xmx, -XX:PermSize, -XX:MaxPermSize.
We recommend that you use the default memory settings. Change them only if necessary
and note that this may impact the application performance or its ability to start.
For more information, see Configuring VM Arguments [page 1105]

-z, --size

Compute unit size

Acceptable values: lite, pro, prem, prem-plus


Default: the smallest size from the account quotas
For more information, see Compute Units [page 959]

--runtime

Application runtime
Use the parameter if you want to choose an application runtime container different from
the one coming with your SDK. To view all available runtime containers, use list-runtimes
[page 202].
For more information, see Application Runtime Container [page 955].
If you specify --runtime, you also have to specify --runtime-version.

--runtime-version

SAP HANA Cloud Platform runtime version on which the application will be started and
will run on the same version after a restart. Otherwise, by default, the application is
started on the latest minor version (of the same major version) which is backward com
patible and includes the latest corrections (including security patches), enhancements,
and updates. Note that choosing this option does not affect already started application
processes.
You can view the recommended versions by executing the list-runtime-versions com
mand.

Note
If you choose your runtime version, consider its expiration date and plan updating to a
new version regularly.
For more information, see Choosing Application Runtime Version [page 1101]
Tomcat connector attributes

144

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Optional

--compression

Enable or disable gzip response compression

Default: off
Possible values: on (allow compression), off (disable compression), force (forces com
pression for all responses) or an integer (which enables compression and specifies the
compression-min-size value in bytes).
For more information, see Enabling and Configuring Gzip Response Compression [page
1104]

--compressible-mimetype

A comma separated list of MIME types for which compression will be used

Default: text/html, text/xml, text/plain


Condition: applicable if compression is enabled

--compression-min-size

Responses bigger than this value get compressed

Condition: applicable if compression is enabled


--connection-timeout

Defines the number of milliseconds to wait for the request URI line to be presented after
accepting a connection.

Default: 20000
--max-threads

Specifies the maximum number of simultaneous requests that can be handled

Default: 200
--uri-encoding

Specifies the character encoding used to decode the URI bytes on application request

Default: ISO-8859-1
For more information, see the encoding sets supported by Java SE 6

and Java SE 7

Example
Here are examples of some additional configurations. If your application is already started, stop it and start it
again for the changes to take effect.
You can deploy an application on a host different from the default one by specifying the host parameter. For
example, to use the data center located in the United States, execute:
neo deploy --host us1.hana.ondemand.com --account myacc --application myapp -source samples/deploy_war/example.war
--user mymail@example.com
Choose compute unit size
To specify the compute unit size on which you want the application to run, use the --size parameter with one of
the following values:
lite - Lite Edition

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

145

pro - Professional edition


prem - Premium edition
prem-plus - Premium Plus edition
Available sizes depend on your account type and what options you have purchased. For developer accounts, only
the Lite edition is available.
For more information, see Compute Units [page 959].
For example, if you have a productive account and have purchased a package with Premium edition compute
units, then you can run your application on a Premium compute unit size, by executing the following command:
neo deploy --size prem myapp.properties
Set the context root of an application
When deploying an application, name the WAR file with the desired context root.
For example, if you want to deploy your WAR in context root "/hello" then rename your WAR to hello.war.
If you want to deploy it in the "/" context root then rename your WAR to ROOT.war.
Specify character encoding
Using the uri-encoding parameter, you can define the character encoding that will be used to decode the URI
bytes on application request. For example, to use the UTF-8 encoding that can represent every character in the
Unicode character set, execute
neo deploy --uri-encoding UTF-8 myapp.properties

Related Information
Console Client [page 88]
Choosing Application Runtime Version [page 1101]
Choosing JRE Version [page 1103]
Configuring VM Arguments [page 1105]
Enabling and Configuring Gzip Response Compression [page 1104]
Scaling Applications [page 1107]
Updating Application Properties [page 1101]
Deploying and Updating Applications [page 973]
Delta Deployment [page 984]
Managing Accounts and Quota [page 17]

1.3.6.4.35 deploy-local
This command deploys WAR files on a local server instance.
neo deploy-local --source <file_location>

146

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 78:
Required

-s, --source

Source for deployment (comma separated list of WAR files or folders containing one or
more WAR files)

Type: file location


Table 79:
Optional

-l, --location

Local server installation directory

Example

neo deploy-local --source samples/deploy_war/example.war

Related Information
Deploying Locally with the Console Client [page 981]

1.3.6.4.36 disable
This command stops the creation of new connections to an application or application process, but keeps the
already running sessions alive. You can check if an application or application process has been disabled by
executing the status command.
neo disable --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help disable in the command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

147

Table 80:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 81:
Optional

-i, --applicationprocess-id

Unique ID of a single application process. Use it to disable a particular application process


instead of the whole application. As the process ID is unique, you do not need to specify
account and application parameters. You can list the application process ID by using the
<status> command.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

Example
To disable the whole application, execute:
neo disable --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
To disable a single applcation process, first identify the application process you want to disable by executing neo
status:
neo status --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
From the generated list of application process IDs, copy the ID you need and execute neo disable for it:
neo disable --application-process-id e8df21d
mymail@example.com

148

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

--host hana.ondemand.com --user

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Soft Shutdown [page 1126]
start [page 240]
status [page 238]
Exit Codes [page 262]

1.3.6.4.37 display-application-properties
The command displays the set of properties of a deployed application, such as runtime version, minimum and
maximum processes, Java version.
neo display-application-properties --host <landscape_host> --account <account_name>
--application <application_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute the neo help display-application-properties
in the command line.
Table 82:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

149

Example
To list the application properties, execute:
neo display-application-properties --host hana.ondemand.com --account myacc -application myapp --user mymail@example.com

Related Information
deploy [page 141]

1.3.6.4.38 display-csr
Returns the certificate signing request (CSR) of the specified certificate.
neo display-csr --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --name <certificate_name>
--file-name <file-name>

Parameters
To list all parameters available for this command, execute neo help display-csr in the command line.
Table 83:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name

Name of the certificate set to the SSL host


Must already be uploaded

150

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 84:
Optional

-f, --file name

Name of the local file where the CSR is stored

Example
neo display-csr --account myaccount --user mymail@example.com --host
hana.ondemand.com
--name myfirstcert --file-name mycsr

Related Information
generate-csr [page 161]
Configuring Custom Domains [page 1186]

1.3.6.4.39 display-ecm-repository
Returns details and settings of one repository, including tenant details.
neo display-ecm-repository --account <account_name>
<e-mail_or_user> --name <repository_name>

--host <landscape_host> --user

Parameters
Table 85:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID, or user name.

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

151

Required

-n, --name

Name of the repository

Type: string
Table 86:
Optional

-t, --tenant

Tenant alias

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo display-ecm-repository --account acme --host hana.ondemand.com --user
<myemail@example.com> --name ExampleRepository
ExampleRepository
Display name
: Example Repository
Description
: This is an example repository with Virus Scan enabled.
ID
: cdb158efd4212fc00726b035
Application
: Neo CLI
Virus Scan
: on
Tenants
: 1
ExampleTenant
Tenant ID
: 39a9c31a-81a5-4c4e-9bd5-8e60681227ad
Virus Scan
: off
Content
: 1 GB
Metadata
: 258 KB

1.3.6.4.40 display-db-info
This command displays detailed information about the selected database. This includes the assigned database
type, the database version, and a list of bindings with the application and data source names.
neo display-db-info -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID>

152

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 87:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

Database ID

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example
neo display-db-info -a myaccount -h hana.ondemand.com -u mymail@example.com -i mydb

1.3.6.4.41 display-schema-info
This command displays detailed information about the selected schema. This includes the assigned database
type, the database version, and a list of bindings with the application and data source names.
neo display-schema-info -a <account_name> -h <landscape_host> -u <e-mail_or_user> i <schema_ID>

Parameters
Table 88:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

153

Required

-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

Schema ID

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example

neo display-schema-info -a myaccount -h hanatrial.ondemand.com -i myschema -u


mymail@example.com

Related Information
Example Scenarios [page 811]
Managing Schemas [page 804]

1.3.6.4.42 download-keystore
This command is used to download a keystore by downloading the keystore file. You can download keystores on
account, application, and subscription levels.

Parameters
To list all parameters available for this command, execute neo help download-keystore in the command line.

154

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 89:
Required

-a, --account

Consumer account name


The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-n,--name

Name of the keystore to be downloaded

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 90:
Optional

-b, --application

Application name

Use --application <consumer_application_name> if the application is


running in your account.

Use --application
<provider_account_name>:<provider_application_name> if the ap
plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-l,--location

Local directory where the keystore will be saved. If it is not specified, the current directory
is used.

Type: string
-w, --overwrite

Overwrites a file with the same name if such already exists. If you do not explicitly include
the --overwrite argument, you will be notified and asked if you want to overwrite the
file.

Example
On Subscription Level
neo download-keystore --account <consumer_account_name> --application
<provider_account_name>:<provider_application_name>
--user <e-mail_or_user> --location c:\temp --name KeyStore1 --host hana.ondemand.com
On Application Level
neo download-keystore --account <consumer_account_name> --application
<consumer_application_name>
--user <user_ID> --location c:\temp --name KeyStore1 --host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

155

On Account Level
neo download-keystore --account <consumer_account_name> --user <e-mail_or_user>
--location c:\temp --name KeyStore1 --host hana.ondemand.com

Related Information
Keystore Console Commands [page 1248]
Keys and Certificates [page 1246]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

1.3.6.4.43 edit-ecm-repository
Changes the name, key, or virus scan settings of a repository. You cannot change the display name or the
description.
At least one of the --newname, --newkey, or --virus-scan parameters must be provided.
neo edit-ecm-repository --account <account_name> --host <landscape_host> --user <email_or_user> --name <repository_name> --tenant <tenant_name> --virus-scan <true/
false> --key <repository_key>

Note
With this command, you can also change your current repository key to a different one. If you forgot your
current key, request a new one using the reset-ecm-repository command.

Parameters
Table 91:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID, or user name.

Type: string

156

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-k, --key

Key of the repository

Type: string
-n, --name

Name of the repository

Type: string
Table 92:
Optional

-t, --tenant

Tenant alias
Changes the virus scan setting for one tenant.

Caution
If not used, the virus scan setting of the whole repository changes.

Type: string
-o, --newname

New name of the repository

Type: string
-q, --newkey

New repository key

Type: string
-v, --virus-scan

Can be used to activate the virus scanner and check all incoming documents for viruses.

Default: true
Type: boolean

Recommendation
For repositories that are used by untrusted users and or for unknown content, we rec
ommend that you enable the virus scanner by setting this parameter to true. Enabling
the virus scanner could impair the upload performance.
If a virus is detected, the upload process for the document fails with a virus scanner ex
ception.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo edit-ecm-repository --account sap --host hana.ondemand.com --user
<myemail@example.com> --name DemoRepository --tenant sap --virus-scan false --key
ecm_012345689

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

157

SAP HANA Cloud Platform Console Client


edit-ecm-repository executed successfully.

Related Information
reset-ecm-key [page 216]

1.3.6.4.44 enable
This command enables new connection requests to a disabled application or application process. The enable
command cannot be used for an application that is in maintenance mode.
neo enable --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help enable in the command line.
Table 93:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values, see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

158

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 94:
Optional

-i, --applicationprocess-id

Unique ID of a single application process. Use it to enable a particular application process


instead of the whole application. As the process ID is unique, you do not need to specify
account and application parameters. You can list the application process ID by using the
<status> command.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

Example
To enable the whole application, execute:
neo enable --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
To enable a single applcation process, first identify the application process you want to enable by executing neo
status:
neo status --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
From the generated list of application process IDs, copy the ID you need and execute neo enable for it:
neo enable --application-process-id e8df21d
mymail@example.com

--host hana.ondemand.com --user

Related Information
status [page 238]
disable [page 147]
start-maintenance [page 243]

1.3.6.4.45 get-destination
This command downloads (reads) destination configuration properties files and JDK files. You can download
them on account, application or subscribed application level.
neo get-destination --account <account_name> --user <e-mail_or_user> --localpath
<localpath_to_destination_file_or_JKS_file> --host <landscape_host>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

159

Parameters
To list all parameters available for this command, execute neo help get-destination in the command line.
Table 95:
Required

-a, --account

Your account. The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

The application for which you download a destination. Cases:

Use --application <myapp> if the application is running in your account.

Use --application <provider_account>:<provider_app> if the ap


plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
--localpath

The path on your local file system where a destination or a JKS file will be downloaded. If
not set, no files will be downloaded.

Type: string
--name

The name of the destination or JKS file to be downloaded. If not set, the names of all des
tination or JKS files for the service will be listed.

Type: string
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string

Note
If you download a destination configuration file that contains a password field, the
password value will not be visible. Instead, after Password =..., you will only see
an empty space. You will need to learn the password in other ways.

-u, --user

Your email, SAP ID or user name

Type: string

Examples
To read a destination on account level, execute:
neo get-destination --account myaccount --user p1234567890 --name weather -localpath C:\myfiles --host hanatrial.ondemand.com

160

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To read a destination on application level, execute:


neo get-destination --account myaccount -user p1234567890 --application demo -name myconfiguration.jks --localpath C:\SDK\tools\samples\connectivity --host
hanatrial.ondemand.com
To read a destination on subscribed application level, execute:
neo get-destination --account myaccount --user p1234567890 --application
otheraccount:remotedemo --name weather --localpath C:\SDK\tools\samples
\connectivity --host hanatrial.ondemand.com

Related Information
Downloading Destinations [page 286]
Exit Codes [page 262]

1.3.6.4.46 generate-csr
Generates and returns a certificate signing request (CSR).
neo generate-csr --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --name <certificate_name>
--certificate-distinguished-name <type0=value0,type1=value1,type2>

Parameters
To list all parameters available for this command, execute neo help generate-csr in the command line.
Table 96:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

161

Required

-n, --name

Unique identifier of the certificate

Type: string (It can contain alphanumerics, '.', '-' and '_')
-d,--certificatedistinguished-name

Attributes of the CSR

Type: string (formatted as type0=value0,type1=value1,type2=..., characters may be es


caped by \ (backslash), no spaces are skipped)

Allowed attributes:

Country - two-digit code - for example, GB

State - state or province name - for example, Hampshire

Locality city full name - for example Portsmouth

Organization company name

Organizational Unit for example IT Department

Common Name the domain name for which you are requesting the certificate - ex
ample.com

Optional

-s, -subjectalternative-name

A comma-separated list of all domain names to be protected with this certificate, used as
value for the Subject Alternative Name field of the generated certificate.

Type: string

Example
neo generate-csr --account myaccount --user mymail@example.com --host
hana.ondemand.com --name myfirstcert
--certificate-distinguished-name "C=BG,O=MyCompany,CN=www.mycompany.bg" --subjectalternative-name mycompany.com,mycompany.net

Related Information
Configuring Custom Domains [page 1186]

1.3.6.4.47 get-log
This command downloads a particular log file.
neo get-log --account <account_name> --application <application_name> --user <email_or_user> --host <landscape_host> --directory
<local_folder_location_of_the_file> --file <file_name>

162

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help get-log in the command line.
Table 97:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-d, --directory

Local folder location under which the file will be downloaded. If the directory you have
specified does not exist, it will be created.

Type: string
-f, --file

The log file name including its extension.

Type: string
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string
Table 98:
Optional

-w, --overwrite

Overwrites a file with the same name if such already exists. If you do not explicitly include
the --overwrite argument, you will be notified and asked if you want to overwrite the
file.

Default: true
Type: boolean

Example

neo get-log --account myaccount --application demo --user p1234567890 --host


hanatrial.ondemand.com --directory C:\MyDemoApps\log --file jpaas_audit_log.log

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

163

Related Information
Using Logs in the Console Client [page 1134]
Exit Codes [page 262]

1.3.6.4.48 grant-db-tunnel-access
This command generates a token, which allows the members of another account to access a database using a
database tunnel.
neo grant-db-tunnel-access -h <host> -u <user> -a <my account> -i <mydatabase> --toaccount <other account>

Parameters
Table 99:
Required

-i, --id

Database ID

Type: string
--to-account

Account name
The account to be granted database tunnel access, based on the access token

Type: string

Example
neo grant-db-tunnel-access -h hanatrial.ondemand.com -u mymail@example.com -a
myaccount -i mydb --to-account other account

Related Information
Providing Access to Databases for Other Accounts [page 853]
list-db-tunnel-access-grants [page 194]
revoke-db-tunnel-access [page 222]

164

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.49 grant-schema-access
This command gives an application in another account access to a schema based on a one-time access token.
The access token is used to bind the schema to the application.
neo grant-schema-access --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user> --id <schema_ID>

Parameters
Table 100:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name
The application (specified in the format <account>:<application>) to which the schema
can be bound using the created token

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-i, --id

Schema ID

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example
neo grant-schema-access --host hanatrial.ondemand.com --account myaccount -application salescorp:salesapp --user mymail@example.com --id myschema

Related Information
Granting Access to Schemas [page 818]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

165

bind-schema [page 106]


list-schema-access-grants [page 205]
revoke-schema-access [page 223]

1.3.6.4.50 hcmcloud-create-connection (Beta)


This command configures the connectivity of an extension application to a SuccessFactors system associated
with a specified SAP HANA Cloud Platform account. The command creates the required HTTP destination and
registers an OAuth client for the extension application in SuccessFactors. The command is relevant for Java
extension applications.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].

neo hcmcloud-create-connection --application <extension_application> --account


<account_name> --user <e_mail or user> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-create-connection in the
command line.
Table 101:
Required

-b, --application

The name of the extension application for which you are creating the connection. Cases:

Use --application <my_extension_application> if the application is

Use --application

running in your account

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The landscape host for your extension account

Type: URL. For acceptable values, see Landscape Hosts.

166

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
--technical-user-id

ID of the technical user for the connection

Condition: Required for connection type OData with technical user


Type: string
Table 102:
Optional

-w, --overwrite

If a connection with the same name already exists, overwrites it. If you do not explicitly
specify the --overwrite parameter, and a connection with the same name already exists,
the command fails to execute

Example
To configure a connection of type OData with technical user for an extension application in an account located in
the United States (US East) data center, execute:
neo hcmcloud-create-connection --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host us1.hana.ondemand.com -technical-user-id <technical_user_id>

1.3.6.4.51 hcmcloud-delete-connection (Beta)


This command removes the specified connection configured between an extension application and a
SuccessFactors system associated with the specified SAP HANA Cloud Platform account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].

neo hcmcloud-delete-connection --application <extension_application> --account


<account_name> --user <e_mail or user> --host <landscape_host> --name
<destination_name>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

167

Parameters
To list all parameters available for this command, execute neo help hcmcloud-delete-connection in the
command line.
Table 103:
Required

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-n, --name

Name of the connection destination

Accepted values: sap_hcmcloud_core_odata,


sap_hcmcloud_core_odata_technical_user
Type: string
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To delete an OData connection for an extension application running in an extension account in the US East data
center, execute:
neo hcmcloud-delete-connection --application <extension_application> --account
<account_name> --user <e_mail or user> --host us1.hana.ondemand.com --name
sap_hcmcloud_core_odata

168

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.52 hcmcloud-disable-application-access (Beta)


This command removes an extension application from the list of authorized assertion consumer services for the
SuccessFactors system associated with the specified account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].

neo hcmcloud-disable-application-access --application <extension_application> -application-type <extension_application_type> --account <extension_account_name> -user <e-mail_or_user> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-disable-applicationaccess in the command line.
Table 104:
Required

-b, --application

The name of the extension application for which you are deleting the connection. Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
--application-type

The type of the extension application for which you are deleting the connection

Accepted values: java, html5


Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

169

Required

-u, --user

Use your email, SAP ID or user name

Type: string

Example
To remove a Java extension application from the list of authorized assertion consumer services for the
SuccessFactors system associated with an account located in the United States (US East), execute:
neo hcmcloud-disable-application-access --application <my_application> -application-type java --account <my_extension_account> --user
<my_email@example.com> --host us1.hana.ondemand.com
The command removes the entry for the application from the list of the authorized service provider assertion
consumer services for the SuccessFactors system associated with the specified account. If entry for the
extension application does not exist the command will fail.

1.3.6.4.53 hcmcloud-display-application-access-status (Beta)


This command displays the status of an extension application entry in the list of assertion consumer services for
the SuccessFactors system associated with the specified account. The returned results contain the extension
application URL.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].

neo hcmcloud-display-application-access-status --application


<extension_application> --account <extension_account_name> --user <e-mail_or_user>
--host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-display-applicationaccess-status in the command line.

170

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 105:
Required

-b, --application

The name of the extension application for which you are displaying the status in in the list
of assertion consumer services. Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
--application-type

The type of the extension application for which you are creating the connection

Accepted values: java, html5


Type: string
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To display the status of an application entry in the list of authorized assertion consumer services for the
SuccessFactors system associated with an account in the data center located in the United States (US East),
execute:
neo hcmcloud-display-application-access-status --application myapp --account
myextensionacc --user mymail@example.com --host us1.hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

171

1.3.6.4.54 hcmcloud-enable-application-access (Beta)


This command registers an extension application as an authorized assertion consumer service for the
SuccessFactors system associated with the specified account to enable the application to use the
SuccessFactors identity provider (IdP) for authentication.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-enable-application-access --application <extension_application> -account <account_name> --user <e-mail_or_user> --host <landscape_host> -application-type <extension_application_type>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-enable-applicationaccess in the command line.
Table 106:
Required

-b, --application

The name of the extension application for which you are creating the connection. Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
--application-type

The type of the extension application for which you are creating the connection

Accepted values: java, html5


Type: string
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

172

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-u, --user

Use your email, SAP ID or user name

Type: string

Example
To register an extension application as an authorized assertion consumer service for the SuccessFactors system
associated with an account located in the United States (US East) data center, execute:
neo hcmcloud-enable-application-access --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host us1.hana.ondemand.com
--application-type java
The command creates entry for the application in the list of the authorized service provider assertion consumer
services for the SuccessFactors system associated with the specified account. The entry contains the main URL
of the extension application, the service provider audience URL and service provider logout URL. If an entry for the
given extension application already exists, this entry is overwritten.

1.3.6.4.55 hcmcloud-enable-role-provider (Beta)


This command enables the SuccessFactors role provider for the specified Java application.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].

neo hcmcloud-enable-role-provider --application <extension_application> --account


<account_name> --user <e_mail or user> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-enable-role-provider in
the command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

173

Table 107:
Required

-b, --application

The name of the extension application for which you are creating the connection. Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The landscape host for your extension account

Type: URL. For acceptable values, see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To enable the SuccessFactors role provider for your Java application in an extension account located in the United
States (US East) data center, execute:
neo hcmcloud-enable-role-provider --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host us1.hana.ondemand.com

174

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.56 hcmcloud-get-registered-home-page-tiles (Beta)


This command lists the SuccessFactors Employee Central (EC) home page tiles registered in the SuccessFactors
company instance associated with the extension account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-get-registered-home-page-tiles --application <extension_application> -account <account_name> --user <e-mail_or_user> --host <landscape_host> -application-type <extension_application_type>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-get-registered-homepage-tiles in the command line.
Table 108:
Required

-b, --application

The name of the extension application for which you are listing the home page tiles.
Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Note
If you do not specify the application parameter, the command lists all tiles regis
tered in the Successfactors company instance associated with the specified extension
account.

--application-type

The type of the extension application for which you are listing the home page tiles

Accepted values: java, html5


Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Name of the extension account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

175

Required

-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To list the home page tiles registered for a Java extension application running in your account in the US East data
center, execute::
neo hcmcloud-get-registered-home-page-tiles --application <my_application> -account <my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com --application-type <java>
There is no lifecycle dependency between the tiles and the application, so the application may not be started or
may not be deployed anymore.

1.3.6.4.57 hcmcloud-import-roles (Beta)


This command imports SuccessFactors HCM suite roles into the SuccessFactors customer instance linked to an
extension account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-import-roles --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --location <path_to_the_file_with_role_definitions>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-import-roles in the
command line.

176

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 109:
Required

-l, --location

Path to the file containing in which the


SuccessFactors HCM Suite roles are de
fined

Type: string

Note
The file size must not exceed 500 KB.

-a, --account

The SAP HANA Cloud Platform extension


account which is linked to the target Suc
cessFactors system

Type: string (up to 30 characters; lower


case letters and numbers, starting with a
letter)

-h, --host

The respective landscape host for your ac


count type

Type: URL. For acceptable values see


Landscape Hosts

-p, --password

To protect your password, enter it only


when prompted by the console client and
not explicitly as a parameter in the proper
ties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To import the role definitions for an extension application from the system repository for your extension account
into the SuccessFactors customer instance connected to this account, execute:
neo hcmcloud-import-roles --account myextensionacc --user mymail@example.com --host
hana.ondemand.com --location pathtorolefile
If any of the roles that you are importing already exists in the target system, the commands fails to execute.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

177

1.3.6.4.58 hcmcloud-list-connections (Beta)


This command lists the connections configured for the specified extension application.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-list-connections --application <extension_application> --account
<account_name> --user <e_mail or user> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-list-connections in the
command line.
Table 110:
Required

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-n, --name

Name of the connection destination

Accepted values: sap_hcmcloud_core_odata,


sap_hcmcloud_core_odata_technical_user
-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

178

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
To list the connections for an extension application running in an extension account in the US East data center,
execute:
neo hcmcloud-list-connection --application myapp --account myextensionacc
mymail@example.com --us1.host hana.ondemand.com

--user

1.3.6.4.59 hcmcloud-register-home-page-tiles (Beta)


This command registers the SuccessFactors Employee Central (EC) home page tiles in the SuccessFactors
company instance associated with the extension account. The home page tiles must be described in a tile
descriptor file for the extension application in JSON format.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-register-home-page-tiles --application <extension_application> -account <account_name> --user <e-mail_or_user> --host <landscape_host> -application-type <extension_application_type> --location
<path_to_the_tile_descriptor_file>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-register-home-page-tiles
in the command line.
Table 111:
Required

-l, --location

Path to the tile descriptor file

Type: string

Note
The file size must not exceed 100 KB.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

179

Required

-b, --application

The name of the extension application for which you are registering the home page tiles.
Cases:

Use --application <my_extension_application> if the application is


running in your account

Use --application

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
--application-type

The type of the extension application for which you are registering the home page tiles

Default: java
Accepted values: java, html5
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Name of the extension account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To register a home page tile for a Java extension application running in your account in the US East data center,
execute::
neo hcmcloud-register-home-page-tiles --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host us1.hana.ondemand.com
--application-type <java> --location <path_to_tile_descriptor_file>

180

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.60 hcmcloud-unregister-home-page-tiles (Beta)


This command removes the SuccessFactors EC home page tiles registered for the extension application in the
SuccessFactors company instance associated with the specified extension account.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
neo hcmcloud-unregister-home-page-tiles --application <extension_application> -account <account_name> --user <e-mail_or_user> --host <landscape_host> -application-type <extension_application_type>

Parameters
To list all parameters available for this command, execute neo help hcmcloud-unregister-home-pagetiles in the command line.
Table 112:
Required

-b, --application

The name of the extension application for which you are removing the home page tiles.
Cases:

Use --application <my_extension_application> if the application is

Use --application

running in your account

<provider_account>:<extension_application> if the application is


running in another account and your extension account is subscribed to the applica
tion

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Note
You must use the same application name that you have specified when registering the
tiles.

--application-type

The type of the extension application for which you are listing the home page tiles

Default: java
Accepted values: java, html5
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-a, --account

Name of the extension account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

181

Required

-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts.


-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example
To remove the home page tiles registered for a Java extension application running in your account in the US East
data center, execute::
neo hcmcloud-unregister-home-page-tiles --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host us1.hana.ondemand.com
--application-type <java>
There is no lifecycle dependency between the tiles and the application, so the application may not be started or
may not be deployed anymore.

1.3.6.4.61 hot-update
The hot-update command enables a developer to redeploy and update the binaries of an application started on
one process faster than the normal deploy and restart. Use it to apply and activate your changes during
development and not for updating productive applications.
There are three options for hot-update specified with the --strategy parameter:
replace-binaries - redeploys and updates the application binaries
restart-runtime - redeploys and updates the application binaries and restarts the application process
reprovision-runtime - cleans up the file system, reprovisions the runtime and redeploys and updates the
application binaries
neo hot-update --host <landscape_host> --account <account_name> --application
<application_name> --source <file_location> --user <e-mail_or_user> --strategy
<update_strategy>

Limitations:
Works only if there is a single running process of the application.
You cannot change deploy parameters and context path of the application.

182

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help hot-update in the command line.
Table 113:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Your email, SAP ID or user name.

Type: string
-s, --source

A comma-separated list of file locations, pointing to WAR files, or folders containing them.

Type: file location


--strategy

Defines how the update will be performed.

Acceptable values:

replace-binaries

restart-runtime

reprovision-runtime

Table 114:
Optional

--connections

Number of connections used to deploy the content

Default: 2
Acceptable values: 1-6
Type: integer
--delta

Uploads only the changes between the provided source and the deployed content. New
content will be added; missing content will be deleted. Recommended for development
use to speed up the deployment.

Acceptable values: None


-y,--synchronous

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Waits for the operation to complete.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

183

Example
neo hot-update --host us1.hana.ondemand.com --account myacc --application myapp -source samples/deploy_war/example.war --user mymail@example.com --strategy replacebinaries

1.3.6.4.62 install-local
This command installs a server runtime in a local folder, by default <SDK installation folder>/server.
neo install-local

Parameters
Table 115:
Optional

--ajp-port

AJP port opened by server

Default: 8009
--http-non-proxy-hosts

JVM system property http.nonProxyHosts

--http-port

HTTP port opened by server

Default: 8080
--http-proxy-host

JVM system property http.ProxyHost

--http-proxy-port

JVM system property http.ProxyPort

--https-port

HTTPS port opened by server

Default: 8443
--https-proxy-host

JVM system property https.ProxyHost

--https-proxy-port

JVM system property https.ProxyPort

--jmx-port

JMX port opened by server (JVM system property

com.sun.management.jmxremote.port)
Default: 1717
-l, --location

Local server installation directory

Related Information
Deploying Locally with the Console Client [page 981]

184

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.63 list-application-datasources
This command lists all schemas and productive database instances bound to an application.
neo list-application-datasources -a <account_name> -b <application> -h
<landscape_host> -u <e-mail_or_user>

Parameters
Table 116:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letters)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example
neo list-application-datasources -a myaccount -b myapp -h hana.ondemand.com -u
mymail@example.com

Related Information
bind-schema [page 106]
unbind-schema [page 253]
bind-hana-dbms [page 104]
unbind-hana-dbms [page 252]
Example Scenarios [page 811]
Managing Schemas [page 804]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

185

1.3.6.4.64 list-availability-check
Lists the availability checks.
neo list-availability-check

Parameters
Table 117:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
Table 118:
Optional

-b, --application

Application name for Java applications or productive SAP HANA database system, and
application name in the format <database name>:<application name> for SAP HANA XS
applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-R, --recursively

Lists availability checks recursively starting from the specified level. For example, if only
'account' is passed as an argument, it starts from the account level and then lists all
checks configured on application level.

Default: false
Type: boolean

Example
Example for listing availability checks recursively starting on account level and listing the checks configured for
Java and SAP HANA XS applications:
neo list-availability-check -a myaccount -u p1234567 --host hana.ondemand.com -R
Sample output:
SAP HANA Cloud Platform Console Client
Running list-availability-checks with the following parameters:
account
: myaccount
host
: https://hana.ondemand.com
recursively: true
SDK version: 1.2.3

186

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

user
: p1234567
HANA XS Availability Checks
Application availability checks
application : hanaxs:myhana
url
: /myhana.xsjs
warning
: 50 s
critical
: 60 s
technology : HANA XS
Java Availability Checks
Account-level availability check
account
: test
url
: /example
warning
: 50
critical
: 60
Application availability checks
application : demo
url
: /example
warning
: 6
critical
: 4
technology : Java

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.65 list-accounts
Lists all accounts that a customer has. Authorization is performed against the account passed as --account
parameter.
neo list-accounts --account <account_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help list-accounts in the command line.
Table 119:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

187

Required

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example
neo list-accounts --account myaccount --user myuser --host hana.ondemand.com

1.3.6.4.66 list-alert-recipients
Lists alert recipients.
neo list-alert-recipients

Parameters
Table 120:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
Table 121:
Optional

-b, --application

Application name for Java applications or productive SAP HANA instance database name
and application name in the format <instance name>:<application name> for SAP HANA
XS applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

188

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Optional

-R, --recursively

Lists alerts recipients recursively starting from the specified level. For example, if only 'ac
count' is passed as an argument, it starts from the account level and then lists all recipi
ents configured on application level.

Default: false
Type: boolean

Example
neo list-alert-recipients -a myaccount -b demo -u p1234567 -R --host
hana.ondemand.com
Sample output:
SAP HANA Cloud Platform Console Client
Password for your user:
Running list-alert-recipients with the following parameters:
account
: myaccount
host
: https://hana.ondemand.com
recursively : true
user
: p1234567
Account-level alert recipients
Recipients not set on account level for account myaccount
application : demo1
alert_recipients@example.com
application : demo2
alert_recipients@example.org, alert_recipients@example.net

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.67 list-application-domains
Lists all domain names on which an application can be accessed.
neo list-application-domains --account <account_name> --application
<application_name> --user <e-mail_or_user> --host <landscape_host>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

189

Parameters
To list all parameters available for this command, execute neo help list-application-domains in the
command line.
Table 122:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string

Example

neo list-application-domains --account myaccount --application myapplication --user


mymail@example.com --host hana.ondemand.com

Related Information
Add the Custom Domain [page 1190]
add-custom-domain [page 99]
Configuring Custom Domains [page 1186]

1.3.6.4.68 list-custom-domain-mappings
Lists custom domains configured as access points for applications in an account.
neo list-custom-domain-mappings --account <account_name> --user <e-mail_or_user> -host <landscape_host>

190

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help list-custom-domain-mappings in the
command line.
Table 123:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example

neo list-custom-domain-mappings --account myaccount --user mymail@example.com -host hana.ondemand.com

Related Information
Configuring Custom Domains [page 1186]

1.3.6.4.69 list-dbms
This command lists the dedicated and shared database management systems available for the specified account
with the following details: database system (for dedicated databases), database type, and database version.
neo list-dbms -a <account_name> -h <landscape_host> -u <e-mail_or_user>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

191

Parameters
Table 124:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

Example
neo list-dbms -a myaccount -h hanatrial.ondemand.com -u mymail@example.com

Related Information
Example Scenarios [page 811]
Managing Schemas [page 804]

1.3.6.4.70 list-dbs
This command lists all databases for the specified account.
neo list-dbs -a <account_name> -h <landscape_host> -u <e-mail_or_user>

192

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 125:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 126:
Optional

--verbose

Displays additional information about each database: database type and database ver
sion

Default: off
Type: switch, takes no value

Example
neo list-dbs -a myaccount -h hana.ondemand.com -u mymail@example.com

1.3.6.4.71 list-domain-certificates
Use this command to list certificates available for a custom domain.
neo list-domain-certificates --account <account_name> --user <e-mail_or_user> -host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help list-domain-certificates in the
command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

193

Table 127:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example

neo list-domain-certificates --account myaccount --user mymail@example.com --host


hana.ondemand.com

Related Information
upload-domain-certificate [page 256]
delete-domain-certificate [page 133]
Bind the Certificate to the SSL Host [page 1189]

1.3.6.4.72 list-db-tunnel-access-grants
This command lists all current database access permissions for databases in other accounts.
neo list-db-tunnel-access-grants -h <host> -u <user> -a <my account>

Note
The list does not include access permissions that have been revoked.

194

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 128:
Optional
(Optional) Database ID

-i, --id

Lists only the access permissions for the specified database

Type: string

Example
neo list-db-tunnel-access-grants -a myaccount -h hanatrial.ondemand.com -u
mymail@example.com -i mydb
The table below shows the currently active database tunnel access permissions:
Table 129:
Database ID

Granted To

Access Token

myownhana

acmecorp

31t0dpim6rtxa00wx5483vqe7in8i3c1ph
v759w9oqrutf638l

myotherhana

acmetest

vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q4
8yumf1c6uu8b9pt9z

Related Information
revoke-db-tunnel-access [page 222]
grant-db-tunnel-access [page 164]
Providing Access to Databases for Other Accounts [page 853]

1.3.6.4.73 list-ecm-repositories
Returns details and settings of all repositories in the specified account.
Table 130:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

195

Required
Use the respective landscape host for your account type.

-h, --host

Type: URL. For acceptable values see Landscape Hosts [page 32]
Use your email, SAP ID, or user name.

-u, --user

Type: string
Table 131:
Optional
To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

-p, --password

Type: string

Example
neo list-ecm-repositories --account acme --host hana.ondemand.com --user
<myemail@example.com>
ExampleRepository
Display name
Description
ID
Application
Virus Scan

:
:
:
:
:

Example Repository
This is an example repository with Virus Scan enabled.
cdb158efd4212fc00726b035
Neo CLI
on

ExampleRepositoryNoVS
Display name
: Example Repository without Virus Scan
Description
: This is an example repository with Virus Scan disabled.
ID
: cdb158efd4212fc00726b035
Application
: Neo CLI
Virus Scan
: off
Number of Repositories: 2

1.3.6.4.74 list-hanaxs-certificates
This command lists identity provider certificates available to productive HANA instances. Optionally, you can
include a part of the certificate <Subject CN> as filter.
neo list-hanaxs-certificates --host <landscape_host> --account <account_name> -user <e-mail_or_user>

Note
Use this command for SAP HANA version SPS09 or lower SPs only.

196

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help list-hanaxs-certificates in the
command line.
Table 132:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Your email, SAP ID, or SCN user name

Type: string
Table 133:
Optional

-cn-string, --containedstring

A part of the certificate CN. If more than one certificate contain this string, all shall be
listed.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

Example
To list all identity provider certificates that contain <John Smith> in their <Subject CN>, execute:
neo list-hanaxs-certificates --host hana.ondemand.com --account myaccount --user
mymail@example.com --contained-string John Smith

1.3.6.4.75 list-jmx-checks
Lists JMX checks.
neo list-jmx-checks -a <account_name> -u <e-mail_or_user>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

197

Parameters
Table 134:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
Table 135:
Optional

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Note
If the parameter is not used, all JMX checks used for this account will be listed.

-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Note
If the parameter is not used, the default host is hana.ondemand.com.

-R, --recursively

Lists JMX checks recursively, starting from the specified level. For example, if only 'ac
count' is passed as an argument, it starts from the account level and then lists all checks
configured on application level.

Default: false
Type: boolean

Example
neo list-jmx-checks -a myaccount -b demo -u p1234567 -R -h hana.ondemand.com
Sample output:
SAP HANA Cloud Platform Console Client
Password for your user:
Running list-jmx-check with the following parameters:
account
: myaccount
host
: https://hana.ondemand.com
recursively: true
user
: p1234567
Account-level JMX checks
account
: myaccount
check-name
: JVM Heap Memory Used
object-name
: java.lang:type=Memory

198

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

critical
: 60
attribute
: HeapMemoryUsage
attribute key
: used
warning
: 700000000
critical
: 900000000
unit
: B
Application JMX checks
application
check-name
object-name
attribute
attribute key
warning
critical
unit

:
:
:
:
:
:
:
:

demo
JVM Heap Memory Used
java.lang:type=Memory
HeapMemoryUsage
used
600000000
850000000
B

Related Information
JMX Checks [page 1156]
Monitoring Java Applications [page 1149]

1.3.6.4.76 list-keystores
This command is used to list the available keystores. You can list keystores on account, application, and
subscription levels.

Parameters
To list all parameters available for this command, execute neo help list-keystores in the command line.
Table 136:
Required

-a, --account

Consumer account name


The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

199

Table 137:
Optional

-b, --application

Application name

Use --application <consumer_application_name> if the application is


running in your account.

Use --application
<provider_account_name>:<provider_application_name> if the ap
plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Example
On Subscription Level
neo list-keystores --account <consumer_account_name> --application
<provider_account_name>:<provider_application_name>
--user <e-mail_or_user> --host hana.ondemand.com
On Application Level
neo list-keystores --account <consumer_account_name> --application
<consumer_application_name>
--user <e-mail_or_user> --host hana.ondemand.com
On Account Level
neo list-keystores --account <consumer_account_name> --user <e-mail_or_user> --host
hana.ondemand.com

Related Information
Keystore Console Commands [page 1248]
Keys and Certificates [page 1246]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

1.3.6.4.77 list-loggers
This command lists all available loggers with their log levels for your application.
neo list-loggers --account <account_name> --application <application_name> --user
<e-mail_or_user> --host <landscape_host>

200

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help list-loggers in the command line.
Table 138:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string

Example
neo list-loggers --account myaccount --application demo --user p1234567890 --host
hanatrial.ondemand.com

Related Information
Using Logs in the Console Client [page 1134]
Exit Codes [page 262]

1.3.6.4.78 list-logs
This command lists all log files of your application sorted by date in a table format, starting with the latest
modified.
neo list-logs --account <account_name> --application <application_name> --user <email_or_user> --host <landscape_host>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

201

Parameters
To list all parameters available for this command, execute neo help list-logs in the command line.
Table 139:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string

Example
neo list-logs --account myaccount --application demo --user p1234567890 --host
hanatrial.ondemand.com

Related Information
Using Logs in the Console Client [page 1134]
Exit Codes [page 262]

1.3.6.4.79 list-runtimes
The command displays all available application runtime containers.
neo list-runtimes --user <e-mail_or_user> --host <landscape_host>

202

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help list-runtimes in the command line.
Table 140:
Required

-u, --user

Use your email, SAP ID or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example
neo list-runtimes --user myuser --host hana.ondemand.com

Related Information
list-runtime-versions [page 203]
Choosing Application Runtime Version [page 1101]
Understanding the Runtime Information [page 1117]

1.3.6.4.80 list-runtime-versions
The command displays the supported application runtime container versions for your SAP HANA Cloud Platform
SDK. Only recommended versions are shown by default. You can also list supported version for a particular
runtime container.
neo list-runtime-versions --user <e-mail_or_user> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help list-runtime-versions in the
command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

203

Table 141:
Required

-u, --user

Use your email, SAP ID or user name.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
Table 142:
Optional

--all

Lists all supported application runtime container versions. Using a previously released
runtime version is not recommended.

--runtime

Lists supported version only for the specified runtime container.


For more information, see Application Runtime Container [page 955].

Example

neo list-runtime-versions --user myuser --host hana.ondemand.com --runtime neo-javaweb

Related Information
Choosing Application Runtime Version [page 1101]
Understanding the Runtime Information [page 1117]
list-runtimes [page 202]

1.3.6.4.81 list-schemas
This command lists all schemas contained in the specified account.
neo list-schemas -a <account_name> -h <landscape_host> -u <e-mail_or_user>

204

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 143:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 144:
Optional

--verbose

Displays additional information about each schema: database type and database version

Default: off
Type: switch, takes no value

Example
neo list-schemas -a myaccount -h hanatrial.ondemand.com -u mymail@example.com -verbose

Related Information
Example Scenarios [page 811]
Managing Schemas [page 804]

1.3.6.4.82 list-schema-access-grants
This command lists all current schema access grants for a specified account.
neo list-schema-access-grants --host <landscape_host> --account <account_name> -user <e-mail_or_user>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

205

Note that the list does not include grants that have been revoked.

Parameters
Table 145:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 146:
Optional

-i, --id

Schema ID
Lists only the grants for the specified schema

Type: string

Example

neo list-schema-access-grants --host hanatrial.ondemand.com --account myaccount -user mymail@example.com --id myschema

Related Information
Granting Access to Schemas [page 818]
grant-schema-access [page 165]
revoke-schema-access [page 223]

206

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.83 list-ssl-hosts
Lists SSL hosts for a given account.
neo list-ssl-hosts --account <account_name> --user <e-mail_or_user> --host
<landscape_host>

Parameters
To list all parameters available for this command, execute neo help list-ssl-hosts in the command line.
Table 147:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

Example

neo list-ssl-hosts --account myaccount --user mymail@example.com --host


hana.ondemand.com

Related Information
create-ssl-host [page 124]
Create an SSL Host [page 1187]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

207

1.3.6.4.84 list-subscribed-accounts
Lists all accounts subscribed to a given application.
neo list-subscribed-accounts --account <account_name> --application
<application_name> --user <e-mail_or_user> --host <landscape host>

Parameters
To list all parameters available for this command, execute neo help list-subscribed-accounts in the
command line.
Table 148:
Required

-a, --account

Account name
This is the account of the application provider.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name


To be able to execute this command, the specified user must be a member of the provider
account.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo list-subscribed-accounts --account myaccount --application demo --user myuser -host us1.hana.ondemand.com

208

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.85 list-subscribed-applications
Lists all applications to which a given account is subscribed
neo list-subscribed-applications --account <account_name> --user <e-mail_or_user> -host <landscape host>

Parameters
To list all parameters available for this command, execute neo help list-subscribed applications in the
command line.
Table 149:
Required

-a, --account

Account name
This is the account of the applications consumer.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name


To be able to execute this command, the specified user must be a member of the ac
count.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

Example
neo list-subscribed-applications --account consumeraccount --user myuser --host
hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

209

1.3.6.4.86 open-db-tunnel
This command opens a database tunnel to the database system associated with the specified schema or
database.

Note
Make sure that you have installed the required tools correctly.
If you face trouble using this command, please check that your installation is correct.
For more information, see Setting Up the Console Client [page 42] and Using the Console Client [page 89].
The command has two modes:
Default mode: The tunnel remains open until you explicitly close it by pressing ENTER in the command line. It
is closed automatically after 24 hours or if the command window is closed.
neo open-db-tunnel -a <account_name> -h <landscape_host> -u <user> -i <schema_ID>
Background mode: The database tunnel is opened in a separate process. Use the close-db-tunnel
command to close the tunnel once you are done, or it is closed automatically after one hour.
neo open-db-tunnel -a <account_name> -h <landscape_host> -u <user> -i
<schema_ID> --background

Parameters
Table 150:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

ASE database, HANA database or schema ID

Type: string
--access-token

Identifies a database access permission. The access token and database ID parameters
are mutually exclusive.

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string

210

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 151:
Optional

--background

Opens the tunnel session in a background process

Type: switch, takes no value


--output

Prints information about the tunnel in a special output format.

Acceptable values: 'json'


Type: string

Example
neo open-db-tunnel -a myaccount -h hanatrial.ondemand.com -u mymail@example.com -i
myschema

Related Information
Remote Database Access [page 849]
Opening a Database Tunnel [page 851]
Connecting to SAP HANA Databases via the Eclipse IDE [page 861]
Connecting to SAP HANA Schemas via the Eclipse IDE [page 864]
close-db-tunnel [page 109]
Connecting to the Remote SAP ASE Database [page 858]
Automating the Use of Database Tunnels [page 856]
Machine-Readable Command Output [page 93]
Connecting DB Tools to SAP HANA via Service Channels [page 472]

1.3.6.4.87 put-destination
This command uploads destination configuration properties files and JKS files. You can upload them on account,
application or subscribed application level.
neo put-destination --account <account_name> --user <e-mail_or_user> --localpath
<destination_file_or_JKS_file_localpath> --host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help put-destination in the command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

211

Table 152:
Required

-a,

Your account. The account for which you provide username and password.

--account

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

-b,

The application for which you upload a destination. Cases:

--application

Use --application <myapp> if the application is running in your account.

Use --application <provider_account>:<provider_app> if the ap


plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h,

The respective landscape host for your account type.

--host

Type: URL, for acceptable values see Landscape Hosts [page 32]

--localpath

The path to a destination or a JKS file on your local file system.

Type: string
-p,
--password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string

Note
When uploading a destination configuration file that contains a password field, the
password value remains available in the file. However, if you later download this file,
using the get-destination command, the password value will no more be visible.
Instead, after Password =..., you will only see an empty space.

-u,

Your email, SAP ID or user name

--user

Type: string

Examples
To upload a destination on account level, execute:
neo put-destination --account myaccount --user p1234567890 --localpath C:\myfiles
\myconfiguration.jks --host hanatrial.ondemand.com
To upload a destination on application level, execute:
neo put-destination --account myaccount --user p1234567890 --application demo -localpath C:\SDK\tools\samples\connectivity\weather --host hanatrial.ondemand.com
To upload a destination on subscribed application level, execute:
put-destination -h <host> -a <account> -u <user> -b
<provider_account>:<application> --localpath <path to destination file>

212

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Uploading Destinations [page 285]
Exit Codes [page 262]

1.3.6.4.88 reconcile-hanaxs-certificates
This command re-applies all already uploaded certificates to all HANA instances. This command is useful if you
already uploaded certificates to SAP HANA Cloud Platform but uploading failed for some of the HANA instances.

Note
After executing this command, a you need to restart the SAP HANA XS services for it to take effect. See
restart-hana [page 220].

neo reconcile-hanaxs-certificates --host <landscape_host> --account <account_name>


--application <application_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help reconcile-hanaxs-certificates in
the command line.
Table 153:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

213

Required

-u, --user

Your email, SAP ID, or SCN user name

Type: string

Example
neo reconcile-hanaxs-certificates --host hana.ondemand.com --account myaccont -application myapp --user mymail@example.com

1.3.6.4.89 remove-custom-domain
Removes a custom domain as an access point of an application. Use this command if you no longer want an
application to be accessible on the configured custom domain.
neo remove-custom-domain --account <account_name> --user <e-mail_or_user> --host
<landscape_host> --custom-domain <custom_domain> --ssl-host <ssl_host>

Parameters
To list all parameters available for this command, execute neo help remove-custom-domain in the command
line.
Table 154:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-e, --custom-domain

Custom domain for accessing the application

Type: string (Fully qualified domain name - FQDN)

214

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-l, --ssl-host

SSL host as defined with the --name parameter when created, or 'default' if not speci
fied.

Example
neo remove-custom-domain --account myacc --user mymail@example.com --host
hana.ondemand.com --custom-domain www.example.com --ssl-host mysslhostname

Related Information
add-custom-domain [page 99]
Add the Custom Domain [page 1190]
Configuring Custom Domains [page 1186]

1.3.6.4.90 remove-platform-domain
Removes a platform domain (under hana.ondemand.com) as an access point for an application.
neo remove-platform-domain --account <account_name> --application
<application_name> --user <e-mail_or_user> --host <landscape_host> --platformdomain <platform_domain>

Parameters
To list all parameters available for this command, execute neo help remove-platform-domain in the
command line.
Table 155:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

215

Required

-h, --host

Use the respective landscape host for your account type

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-m, platform-domain

Platform domain under hana.ondemand.com

Type: URL

Example
neo remove-platform-domain --account myacc --application myapp --user myuser -host haha.ondemand.com --platform-domain svc.hana.ondemand.com

Related Information
add-platform-domain [page 101]
Platform Domains [page 1196]

1.3.6.4.91 reset-ecm-key
If you have forgotten the repository key, use this command to request a new repository key.
This command only creates a new key that replaces the old one. You cannot use the old key any longer. The
command does not affect any other repository setting, for example, the virus scan definition. If you just want to
change your current repository key, use the edit-ecm-repository command.
neo reset-ecm-key -- name <repository_name> --account <account_name> --host
<landscape_host> --user <e-mail_or_user>

216

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 156:
Required

-a, --account

Account name
Specify an existing account of which you are already a member.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID, or user name.

Type: string
-n, --name

Name of the repository

Type: string

Example
neo reset-ecm-key --name com.foo.MyRepository --account sap --host
hana.ondemand.com --user p1940248318
This example resets the repository key for the com.foo.MyRepository repository and creates a new repository
key, for example fp0TebRs14rwyqq.

Related Information
edit-ecm-repository [page 156]

1.3.6.4.92 reset-log-levels
This command resets all logger levels to their initial state.
neo reset-log-levels --account <account_name> --application <application_name> -user <e-mail_or_user> --host <landscape_host>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

217

Parameters
To list all parameters available for this command, execute neo help reset-log-levels in the command line.
Table 157:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string

Example
neo reset-log-levels --account myaccount --application demo --user p1234567890 -host hanatrial.ondemand.com

Related Information
Using Logs in the Console Client [page 1134]
Exit Codes [page 262]

1.3.6.4.93 restart
Use this command to restart your application or a single application process. The effect of the restart command is
the same as executing the stop command first and when the application is stopped, starting it with the start
command.
neo restart --account <account_name> --application <application_name> --host
<landscape_host> --user <e-mail_or_user>

218

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

neo restart --application-process-id <ID> --user <e-mail_or_user> --host


<landscape_host>

Parameters
To list all parameters available for this command, execute the neo help restart command.
Table 158:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values, see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 159:
Optional

-y, --synchronous

Triggers the process and waits until the application is restarted. The command without
the --synchronous parameter triggers the restarting process and exits immediately
without waiting for the application to start.

Default:off
Type: switch, takes no value
-i, --applicationprocess-id

Unique ID of a single application process. Use it to restart a particular application process


instead of the whole application. As the process ID is unique, you do not need to specify
account and application parameters. You can list the application process ID by using the
<status> command.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

219

Example
To restart the whole application and wait for the operation to finish, execute:
neo restart --account myacc --application myapp --user mymail@example.com --host
hana.ondemand.com --synchronous

Related Information
stop [page 244]
status [page 238]
Exit Codes [page 262]

1.3.6.4.94 restart-hana
Restarts an SAP HANA database or an SAP HANA service.

Note
To use this command, log on with a user with administrative rights for the account.

Note
The restart-hana operation will be executed asynchronously. Temporary downtime is expected for SAP
HANA database or SAP HANA XS Engine, including inability to work with SAP HANA studio, SAP HANA Webbased Development Workbench and Cockpit UIs dependent on SAP HANA XS.
This command has two alternative uses:
For restarting the entire SAP HANA database
neo restart-hana --host <landscape_host> --account <account_name> --user <email_or_user> --id <SAP HANA system identifier> --system
For restarting an SAP HANA service
neo restart-hana --host <landscape_host> --account <account_name> --user <email_or_user> --id <SAP HANA system identifier> --service-name <service_name>
After you trigger the command, you can monitor the command execution in SAP HANA Studio, using
Configuration and Monitoring

Open Administration .

Parameters
To list all parameters available for this command, execute neo help restart-hana in the command line.

220

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 160:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the required productive landscape host.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id

The ID of a productive SAP HANA database system

Note
You can find the SAP HANA database system ID using the list-dbms [page 191] com
mand or in the Databases & Schemas section in the cockpit by navigating to
Persistence

Databases & Schemas

It must start with a letter and can contain uppercase and lowercase letters ('a' - 'z', 'A' 'Z'), numbers ('0' - '9'), and the special characters '.' and '-'.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Your e-mail, SAP ID, or SCN user name

Type: string
--service-name

--system

The SAP HANA service to be restarted. You can choose between the following values:

xsengine - for restarting the SAP HANA XS service

indexserver - for restarting the SAP HANA index server

If available, the entire SAP HANA database system will be restarted.

Example
To restart the SAP HANA database system with ID myhanaid running on the productive landscape, execute:
neo restart-hana --system --id myhanaid --account myaccount --host
hana.ondemand.com --user mymail@example.com
To restart the SAP XS Engine service on SAP HANA database system with ID myhanaid, execute:
neo restart-hana --service-name xsengine --id myhanaid --account myaccount --host
hana.ondemand.com --user mymail@example.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

221

Related Information
SAP HANA Administration Guide

1.3.6.4.95 revoke-db-tunnel-access
This command revokes database access that has been given to another account.
neo revoke-db-tunnel-access -h <host> -u <user> -a <my account> --access-token
<token>

Parameters
Table 161:
Required

-- access-token

Access token that identifies the permission to access the da


tabase

Type: string
--silent

(optional) Suppresses the command line confirmation prompt

Type: boolean
Table 162:
Optional

--output

Confirmation that the permission for opening the database


tunnel from the other account to the database was success
fully revoked

Type: string

Example
neo revoke-db-tunnel-access -h hanatrial.ondemand.com -u mymail@example.com -a
myaccount --access-token 31t0dpim6rtxa00wx5483vqe7in8i3c1phv759w9oqrutf638l

Related Information
grant-db-tunnel-access [page 164]

222

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Providing Access to Databases for Other Accounts [page 853]

1.3.6.4.96 revoke-schema-access
This command revokes the schema access granted to an application in another account.
neo revoke-schema-access --host <SAP HANA Cloud host> --account <account name> -user <e-mail or user name> --access-token <access token>

Parameters
Table 163:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
--access-token

Access token that identifies the grant. Grants can only be revoked by the granting ac
count.

Example
neo revoke-schema-access --host hanatrial.ondemand.com --account myaccount --user
mymail@example.com --access-token vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1c6uu8b9pt9z

Related Information
Revoking Access to Schemas [page 820]
grant-schema-access [page 165]
list-schema-access-grants [page 205]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

223

1.3.6.4.97 rolling-update
The rolling-update command performs update of an application without downtime in one go.

Prerequisites
You have at least one application process that is not in use, see your compute unit quota.
The command can be used with compatible application changes only.
The rolling-update command performs the following steps:
1. Deploys a new version of the application.
2. Starts a new application process.
3. Disables new connection requests for one of the old application processes.
4. Waits for the given timeout.
5. Stops the disabled application process.
6. Repeats steps 2 to 5 for all remaining old application processes.
neo rolling-update --host <landscape_host> --account <account_name> --application
<application_name>
--source <file_location> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help rolling-update in the command line.
Table 164:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-s, --source

A comma-separated list of file locations, pointing to WAR files, or folders containing them
If you want to deploy more than one application on one and the same application process,
put all WAR files in the same folder and execute the deployment with this source, or spec
ify them as a comma-separated list.

Type: file location


-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

224

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 165:
Optional

--compression

Enable or disable gzip response compression

Default: off
Possible values: on (allow compression), off (disable compression), force (forces com
pression for all responses) or an integer (which enables compression and specifies the
compression-min-size value in bytes).
For more information, see Enabling and Configuring Gzip Response Compression [page
1104]

--compressible-mimetype

A comma separated list of MIME types for which compression will be used

Default: text/html, text/xml, text/plain


Condition: applicable if compression is enabled

--compression-min-size

Responses bigger than this value get compressed

Condition: applicable if compression is enabled


--connections

The number of connections used to deploy an application. Use it to speed up deployment


of application archives bigger than 5 MB in slow networks. Choose the optimal number of
connections depending on the overall network speed to the cloud.

Default: 2
Acceptable values: 1-6
Type: integer
--ev

Environment variables for configuring the environment in which the application runs.
Sets one environment variable by removing the previously set value; can be used multiple
times in one execution.

Type: --ev <KEY1>=<VALUE1> --ev <KEY2>=<VALUE2> , where a key-value pair speci


fies one environment variable
If you provide a key without any value (--ev <KEY1>=), the ev parameter is ignored.
For a value that contains spaces, use quotation marks.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

225

Optional

-j, --java-version

JRE version

Default: depends on the SAP HANA Cloud Platform SDK


Type: the version number of the JRE 7.
For more information, see Choosing JRE Version [page 1103]

--timeout

Timeout before stopping the old application processes (in seconds)

Default: 60 seconds
-V, --vm-arguments

System properties (-D<name>=<value>) separated with space that will be used when
starting the application process.
Memory settings of your compute units. You can set the following memory parameters: Xms, -Xmx, -XX:PermSize, -XX:MaxPermSize.
We recommend that you use the default memory settings. Change them only if necessary
and note that this may impact the application performance or its ability to start.
For more information, see Configuring VM Arguments [page 1105]

-z, --size

Compute Unit size:


lite, pro, prem, prem-plus
The compute unit size defines the default memory settings.
For more information, see Compute Units [page 959]

Default: lite
--runtime-version

SAP HANA Cloud Platform runtime version on which the application will be started and
will run on the same version after a restart. Otherwise, by default, the application is
started on the latest minor version (of the same major version) which is backward com
patible and includes the latest corrections (including security patches), enhancements,
and updates. Note that choosing this option does not affect already started application
processes.
You can view the recommended versions by executing the list-runtime-versions com
mand.

Note
If you choose your runtime version, consider its expiration date and plan updating to a
new version regularly.
For more information, see Choosing Application Runtime Version [page 1101]

--uri-encoding

Specifies the character encoding used to decode the URI bytes on application request.

Default: ISO-8859-1
For more information, see the encoding sets supported by Java SE 6

and Java SE 7

226

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
neo rolling-update --host us1.hana.ondemand.com --account myacc --application myapp
--source samples/deploy_war/example.war
--user mymail@example.com --timeout 5

Related Information
deploy [page 141]
Updating Applications with Zero Downtime [page 1121]

1.3.6.4.98 sdk-upgrade
Use this command to upgrade the SDK that you are currently working with.
neo sdk-upgrade
The command checks for a more recent version of the SDK and then upgrades the SDK. There are two possible
cases:
Your SDK version is up to date and no upgrade is needed.
Your SDK version is not up to date and an upgrade process is triggered.
Then an upgrade of the SDK is triggered. The old SDK is backed up in case something goes wrong with the
upgrade.

Note
All files and servers that you add to your SDK will be preserved during upgrade.

Example
neo sdk-upgrade

1.3.6.4.99 set-alert-recipients
Sets alert recipients.
Setting an alert recipient for a Java application or SAP HANA XS application will trigger sending all alerts for
this application to the configured emails.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

227

Setting an alert recipient on account level will send all alerts for all applications in this account to the
configured emails.
neo set-alert-recipients

Parameters
Table 166:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-e, --email

Comma separated list of recipient e-mails


We recommend that you use distribution lists rather than personal email addresses. Keep
in mind that you will remain responsible for handling of personal email addresses with re
spect to data privacy regulations applicable.

Type: string
Table 167:
Optional

-b, --application

Application name for Java applications or productive SAP HANA database system, and
application name in the format <database name>:<application name> for SAP HANA XS
applications

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-w--overwrite

Overwrites existing recipients

Default: false
Type: boolean

Example
neo set-alert-recipients -a myaccount -b demo -u p1234567 -e
alert_recipients@example.com --host hana.ondemand.com

228

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Monitoring Java Applications [page 1149]
Monitoring Database Systems [page 1164]

1.3.6.4.100 set-application-property
Use this command to change the value of a single property of a deployed application without the need to redeploy
it. Execute the command separately for each property that you want to set. For the changes to take effect, restart
the application.
To execute the command successfully, you need to to specify the new value of one property from the optional
parameters table below.
neo set-application-property --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user>
--<property> <new_property_value>

Parameters
To list all parameters available for this command, execute the neo help set-application-property in the
command line.
Table 168:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

229

Table 169:
Optional
Command-specific parameters
Environment variables for configuring the environment in which the application runs.

--ev

Sets the new environment variable without removing the previously set value; can be used
multiple times in one execution.

Type: --ev <KEY1>=<VALUE1> --ev <KEY2>=<VALUE2>, where a key-value pair speci


fies one environment variable.
If you provide a key without any value (--ev <KEY1>=), the environment variable KEY1 will
be deleted.
For a value that contains spaces, use quotation marks.

-j, --java-version

Java Virtual Machine version

Default: depends on the SAP HANA Cloud Platform SDK


Type: the version number of the JRE 7.
(beta) You can use JRE 8 with the Java Web Tomcat 7 runtime (neo-java-web version 2.25
or higher) in accounts enabled for beta features.
For more information, see Choosing JRE Version [page 1103]

-m, --minimum-processes

Minimum number of application processes, on which the application can be started

Default: 1
-M, --maximum-processes

Maximum number of application processes, on which the application can be started

Default: 1
-V, --vm-arguments

Java Virtual Machine arguments


System properties (-D<name>=<value>) separated with space that will be used when
starting the application process.
Memory settings of your compute units. You can set the following memory parameters: Xms, -Xmx, -XX:PermSize, -XX:MaxPermSize.
We recommend that you use the default memory settings. Change them only if necessary
and note that this may impact the application performance or its ability to start.
For more information, see Configuring VM Arguments [page 1105]

-z, --size

Compute unit size

Acceptable values: lite, pro, prem, prem-plus


Default: the smallest size from the account quotas
For more information, see Compute Units [page 959]

230

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Optional

--runtime-version

SAP HANA Cloud Platform runtime version on which the application will be started and
will run on the same version after a restart. Otherwise, by default, the application is
started on the latest minor version (of the same major version) which is backward com
patible and includes the latest corrections (including security patches), enhancements,
and updates. Note that choosing this option does not affect already started application
processes.
You can view the recommended versions by executing the list-runtime-versions com
mand.

Note
If you choose your runtime version, consider its expiration date and plan updating to a
new version regularly.
For more information, see Choosing Application Runtime Version [page 1101]
Tomcat connector attributes

--compression

Enable or disable gzip response compression

Default: off
Possible values: on (allow compression), off (disable compression), force (forces com
pression for all responses) or an integer (which enables compression and specifies the
compression-min-size value in bytes).
For more information, see Enabling and Configuring Gzip Response Compression [page
1104]

--compressible-mimetype

A comma separated list of MIME types for which compression will be used

Default: text/html, text/xml, text/plain


Condition: applicable if compression is enabled

--compression-min-size

Responses bigger than this value get compressed

Condition: applicable if compression is enabled


--connection-timeout

Defines the number of milliseconds to wait for the request URI line to be presented after
accepting a connection.

Default: 20000
--max-threads

Specifies the maximum number of simultaneous requests that can be handled.

Default: 200
--uri-encoding

Specifies the character encoding used to decode the URI bytes on application request.

Default: ISO-8859-1
For more information, see the encoding sets supported by Java SE 6

and Java SE 7

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

231

Example
To change the minimum number of server processes on which you want your deployed application to run,
execute:
neo set-application-property --host hana.ondemand.com --account myacc --application
myapp --user mymail@example.com --minimum-processes 2

Related Information
Updating Application Properties [page 1101]
deploy [page 141]
display-application-properties [page 149]
restart [page 218]
Managing Accounts and Quota [page 17]

1.3.6.4.101 set-db-properties-ase
This command changes the properties for an ASE database.
neo set-db-properties-ase -a <account_name> -h <landscape_host> -u <e-mail_or_user>
-i <database_ID> --db-size <database_size>

Parameters
Table 170:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

232

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-i, --id

ASE database ID

Type: string
--db-size

Size of the database in MB


Specify a size that is greater than the actual size.

Example
neo set-db-properties-ase -a myaccount -h hana.ondemand.com -u mymail@example.com i mydb --db-size dbsize

1.3.6.4.102 set-db-properties-hana
This command changes the properties for a SAP HANA database enabled for multitenant database container
support.
neo set-db-properties-hana -a <account_name> -h <landscape_host> -u <email_or_user> -i <database_ID>

Parameters
Table 171:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

HANA database ID

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

233

Table 172:
Optional

--web-access

Enables or disables access to the HANA database from the Internet: 'enabled' (default),
'disabled'

Example
neo set-db-properties-hana -a myaccount -h hana.ondemand.com -u mymail@example.com i mydb

1.3.6.4.103 set-downtime-app
This command configures a custom downtime page (downtime application) for an application. The downtime
page is shown to the user in the event of unplanned downtime of the original application.
neo set-downtime-app --account <account_name> --application <application_name> -host <landscape_host>
--user <e-mail_or_user> --downtime-application <downtime_application_name>

Parameters
To list all parameters available for this command, execute neo help set-downtime-app in the command line.
Table 173:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

234

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

--downtime-application

Downtime application name


The downtime page application is provided by the customer and hosted in the same ac
count as the application itself.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

Example
neo set-downtime-app --account myacc --application myapp --user mymail@example.com
--downtime-application downtimeapp

Related Information
clear-downtime-app [page 108]
Handling Unplanned Downtime [page 1128]

1.3.6.4.104 set-log-level
This command sets a log level for one or multiple loggers.
neo set-log-level --account <account_name> --application <application_name> --user
<e-mail_or_user> --host <landscape_host> --loggers
<logger_name1>,<logger_name2>,... --level <log_level>

Log Level Mapping


Simple Logging Facade for Java (SLF4J) uses the following log levels:
Level

Description

ALL

This level has the lowest possible rank and is intended to turn
on all logging.

TRACE

This level designates finer-grained informational events than


DEBUG.

DEBUG

This level designates fine-grained informational events that


are most useful to debug an application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

235

Level

Description

INFO

This level designates informational messages that highlight


the progress of the application at coarse-grained level.

WARN

This level designates potentially harmful situations.

ERROR

This level designates error events that might still allow the
application to continue running.

OFF

This level has the highest possible rank and is intended to


turn off logging.

Parameters
To list all parameters available for this command, execute neo help set-log-level in the command line.
Table 174:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-g, --loggers

Single or multiple comma-separated logger names

Type: string
-h, --host

The respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-l, --level

The log level you want to set for the logger(s)

Type: string
-p, --password

Password for the specified user. To protect your password, enter it only when prompted
by the console client and not explicitly as a parameter in the properties file or the com
mand line.

Type: string
-u, --user

Your email, SAP ID or user name

Type: string

236

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
neo set-log-level --account myaccount --application demo --user p1234567890 --host
hanatrial.ondemand.com --loggers com.acme.foo,com.acme.bar --level ERROR

Related Information
Using Logs in the Console Client [page 1134]
Exit Codes [page 262]

1.3.6.4.105 set-quota
Sets compute unit quotas for a given account.

Note
The amount you want to set cannot exceed the amount of quota you have purchased. In case you try to set
bigger amount of quota, you will receive an error message.
neo set-quota --account <account_name> --host <landscape_host> --user <email_or_user> --amount <quota_type>:<integer_amount_of_quota>

Parameters
To list all parameters available for this command, execute neo help set-quota in the command line.
Table 175:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

237

Required

-m, --amount

Compute unit quota type and amount of the quota to be set in the format <type>:
[amount].
In this composite parameter, the <type> part is mandatory and must have one of the fol
lowing values: lite, pro, prem, prem-plus. The amount part is optional and must be an inte
ger value. If omitted, a default value 1 is assigned. Do not insert spaces between the two
parts and their delimiter ":", and use lower case for the <type> part.

Type: string

Example
neo set-quota --account myaccount --user myuser --host hana.ondemand.com --amount
lite:2

1.3.6.4.106 status
You can check the current status of an application or application process. The command lists all application
processes with their IDs, state, last change date sorted chronologically, and runtime information.
When an application process is running but cannot receive new connection requests, it is marked as disabled in its
status description. Additionally, if an application is in planned downtime and a maintenance page has been
configured for it, the corresponding application is listed in the command output.
neo status --account <account_name> --application <application_name> --host
<landscape_host> --user <e-mail_or_user>
neo status --application-process-id <ID> --host <landscape_host> --user <email_or_user>

Parameters
To list all parameters available for this command, execute neo help status in the command line.
Table 176:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id

238

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 177:
Optional

-i, --applicationprocess-id

Unique ID of a single application process. Use it to show the status of a particular applica
tion process instead of the whole application. As the process ID is unique, you do not need
to specify account and application parameters.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)
--show-full-process-id

Shows the full length (40 characters) of the unique application process ID. You may need
to get the full ID when you try to to execute a certain operation on the application process
and the process cannot be identified uniquely with the short version of the ID. In particu
lar, usage of the full length is recommended for tools and batch processing. If this param
eter is not used, the status command lists only the first 7 characters by default.

Default: off
Type: switch, takes no value

Example
You can list all application processes in your application with their IDs:
neo status --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
Then, you can request the status of a particular application process from the list using its ID:
neo status --host hana.ondemand.com --application-process-id e8df21d --user
mymail@example.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

239

Related Information
Console Client [page 88]
start [page 240]
disable [page 147]
start-maintenance [page 243]

1.3.6.4.107 start
Starts a deployed application in order to make it available for customers. In case the application is already started,
the command starts an additional application process if the quota for maximum allowed number of application
processes is not exceeded.
neo start --account <account_name> --application <application_name> --user <email_or_user>
--host <landscape_host>

Parameters
To list all parameters available for this command, execute neo help start in the command line.
Table 178:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

240

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 179:
Optional

-y,--synchronous

Triggers the starting process and waits until the application is started. The command
without the --synchronous parameter triggers the starting process and exits immedi
ately without waiting for the application to start.

Default: off
Type: switch, takes no value

Example
To start the application and wait for the operation to finish, execute:
neo start --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com --synchronous

Related Information
Console Client [page 88]
status [page 238]
Scaling Applications [page 1107]

1.3.6.4.108 start-db-hana
This command starts the specified SAP HANA database on a SAP HANA database system enabled for multitenant
database container support.
neo start-db-hana -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID>

Parameters
Table 180:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

241

Required

-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

HANA database ID

Type: string

Example
neo start-db-hana -a myaccount -h hana.ondemand.com -u mymail@example.com -i mydb

1.3.6.4.109 start-local
This command starts a local server instance.
neo start-local

Parameters
Table 181:
Optional

-l, --location

Local server installation directory

--shutdown-port

Shutdown port opened by server

Default: 8003
--wait-url

Waits for a 2xx response from the specified URL before exiting

--wait-url-timeout

Seconds to wait for a 2xx response from the wait-url before exiting

Default: 180

242

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Deploying Locally with the Console Client [page 981]

1.3.6.4.110 start-maintenance
This command starts the planned downtime of an application, during which it no longer receives requests and a
custom maintenance page for that application is shown to the user. All active connections will still be handled until
the application is stopped.
neo start-maintenance --account <account_name> --application <application_name> -host <landscape_host>
--user <e-mail_or_user> --maintenance-application <maintenance_application_name>

Parameters
To list all parameters available for this command, execute neo help start-maintenance in the command line.
Table 182:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
--maintenanceapplication

Maintenance page application name


The maintenance page application is provided by the customer and hosted in the same
account as the application itself.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
If an application is already in planed downtime, executing the status command for it will show the maintenance
application, to which the traffic is being redirected.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

243

Example
neo start-maintenance --account myacc --application myapp --user
<mymail@example.com --host hana.ondemand.com --maintenance-application maintapp

Related Information
Using Maintenance Mode for Planned Downtimes [page 1123]
stop-maintenance [page 247]
status [page 238]

1.3.6.4.111 stop
Use this command to stop your deployed and started application or application process.
neo stop --account <account_name> --application <application_name> --user <email_or_user> --host <landscape_host>
neo stop --application-process-id <ID> --user <e-mail_or_user> --host
<landscape_host>

Parameters
To list all parameters available for this command, execute neo help stop in the command line.
Table 183:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

244

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
Table 184:
Optional

-y, --synchronous

Triggers the stopping process and waits until the application is stopped. The command
without the --synchronous parameter triggers the stopping process and exits imme
diately without waiting for the application to stop.

Default: off
Type: switch, takes no value
-i, --applicationprocess-id

Unique ID of a single application process. Use it to stop a particular application process


instead of the whole application. As the process ID is unique, you do not need to specify
account and application parameters. You can list the application process ID by using the
<status> command.

Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)

Example
To stop the whole application and wait for the operation to finish, execute:
neo stop --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com --synchronous

Related Information
Console Client [page 88]
status [page 238]
Exit Codes [page 262]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

245

1.3.6.4.112 stop-db-hana
This command stops the specified SAP HANA database on a SAP HANA database system enabled for multitenant
database container support.
neo stop-db-hana -a <account_name> -h <landscape_host> -u <e-mail_or_user> -i
<database_ID>

Parameters
Table 185:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-i, --id

HANA database ID

Type: string

Example

neo stop-db-hana -a myaccount -h hana.ondemand.com -u mymail@example.com -i mydb

1.3.6.4.113 stop-local
This command stops a local server instance.
neo stop-local

246

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
Table 186:
Optional

--shutdown-port

Shutdown port opened by server

Default: 8003

Related Information
Deploying Locally with the Console Client [page 981]

1.3.6.4.114 stop-maintenance
This command stops the planned downtime of an application, starts traffic to it and deregisters the maintenance
application page.
neo stop-maintenance --account <account_name> --application <application_name> -host <landscape_host>
--user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute neo help stop-maintenance in the command line.
Table 187:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
Condition: Do not specify if your host is https://hana.ondemand.com.
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

247

Required

-u, --user

Use your email, SAP ID or user name

Type: string

Example
neo stop-maintenance --account myacc --application myapp --user <mymail@example.com

Related Information
Using Maintenance Mode for Planned Downtimes [page 1123]
start-maintenance [page 243]

1.3.6.4.115 subscribe
Subscribes the account of the consumer to a provider application. Once the command is executed successfully,
the subscription is visible in the "Subscriptions" panel of the cockpit in the consumer account.
neo subscribe --account <account_name> --application <provider_account:application>
--user <e-mail_or_user> --host <landscape_host>

Remember
You must have the Administrator role in the provider and consumer account to execute this command.

Note
You can subscribe an account to an application that is running in another account only if both accounts
(provider and consumer account) belong to the same landscape.

Parameters
To list all parameters available for this command, execute neo help subscribe in the command line.

248

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 188:
Required

-a, --account

Consumer account
This is the account of the consumer that is to be subscribed.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Provider account and application


This parameter must be specified in the format <provider account >:<provider applica
tion>.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name


To be able to execute this command, the specified user must be a member of both the
provider and the consumer accounts and must possess the Administrator role in those
accounts. The command is not available for trial accounts as the same user cannot be a
member of both accounts.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example
neo subscribe --account consumeraccount --application myaccount:myapp --user myuser
--host us1.hana.ondemand.com

Related Information
Managing Subscriptions [page 28]
Subscribing an Account to an Application [page 1162]
unsubscribe [page 255]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

249

1.3.6.4.116 unbind-db
This command unbinds a database from a Java application for a particular data source.
The application retains access to the database until the next application restart. After the restart, the application
will no longer be able to access it.
neo unbind-db -a <account_name> -b <application_name> -h <landscape_host> -u <email_or_user>

Parameters
Table 189:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 190:
Optional

-s, --data-source

Data source name


Default: <DEFAULT>

Example

neo unbind-db -a myaccount -b myapp -h hana.ondemand.com -u mymail@example.com

250

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.117 unbind-domain-certificate
Unbinds a certificate from an SSL host. The certificate will not be deleted from SAP HANA Cloud Platform
storage.
neo unbind-domain-certificate --account <account_name> --user <e-mail_or_user> -host <landscape_host> --ssl-host <ssl_hostname>

Parameters
To list all parameters available for this command, execute neo help unbind-domain-certificate in the
command line.
Table 191:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-l, --ssl-host

SSL host as defined with the --name parameter when created, or 'default' if not speci
fied.

Example
neo unbind-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --ssl-host mysslhostname

Related Information
Bind the Certificate to the SSL Host [page 1189]
Updating an Expired Certificate [page 1194]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

251

1.3.6.4.118 unbind-hana-dbms
This command unbinds a productive SAP HANA database system from a Java application for a particular data
source.
The application retains access to the productive SAP HANA database system until the next application restart.
After the restart, the application will no longer be able to access the database system.
neo unbind-hana-dbms -a <account_name> -b <application_name> -h <landscape_host> -u
<e-mail_or_user>

Parameters
Table 192:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 193:
Optional

-s, --data-source

Data source name

Example

neo unbind-hana-dbms -a myaccount -b myapp -h hana.ondemand.com -u


mymail@example.com

252

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
bind-hana-dbms [page 104]

1.3.6.4.119 unbind-schema
This command unbinds a schema from an application for a particular data source.
The application retains access to the schema until the next application restart. After the restart, the application
will no longer be able to access the schema.
neo unbind-schema -a <account_name> -b <application_name> -h <landscape_host> -u <email_or_user>

Parameters
Table 194:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your e-mail, SAP ID, or user name

Type: string
Table 195:
Optional

-s, --data-source

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Data source name

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

253

Example
neo unbind-schema -a myaccount -b myapp -h hanatrial.ondemand.com -u
mymail@example.com -s datasource1

Related Information
Example Scenarios [page 811]
Managing Schemas [page 804]
bind-schema [page 106]

1.3.6.4.120 undeploy
Undeploying an application removes it from SAP HANA Cloud Platform. To undeploy an application, you have to
stop it first.
neo stop --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>
neo undeploy --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>

Parameters
To list all parameters available for this command, execute the neo help undeploy in the command line.
Table 196:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string

254

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Required

-u, --user

Use your email, SAP ID or user name

Type: string

Example
First stop and then undeploy the application.
neo stop --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com
neo undeploy --host hana.ondemand.com --account myacc --application myapp --user
mymail@example.com

Related Information
Console Client [page 88]
stop [page 244]
Exit Codes [page 262]

1.3.6.4.121 unsubscribe
Removes the subscription to a provider application from a consumer account.
neo unsubscribe --account <account_name> --application
<provider_account:application> --user <e-mail_or_user> --host <landscape_host>

Remember
You must have the Administrator role in the provider and consumer account to execute this command.

Parameters
To list all parameters available for this command, execute neo help unsubscribe in the command line.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

255

Table 197:
Required

-a, --account

Account name
This is the account of the consumer that is to be unsubscribed.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-b, --application

Account name of provider account and application name


This parameter must be specified in the format <account name>:<application>.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user

Use your email, SAP ID or user name


To be able to execute this command, the specified user must be a member of the both the
provider and the consumer accounts.

Type: string
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]

Example
neo unsubscribe --account consumeraccount --application myaccount:myapp --user
myuser --host us1.hana.ondemand.com

Related Information
Managing Subscriptions [page 28]
Providing Multitenant Applications to Tenants for Testing [page 1162]
subscribe [page 248]

1.3.6.4.122 upload-domain-certificate
Uploads an SSL certificate to SAP HANA Cloud Platform. The certificate must be signed using the previously
generated CSR via the generate-csr command.
neo upload-domain-certificate --account <account_name> --user <e-mail_or_user> -host <landscape_host> --name <certificate_name> --location <file_location>

256

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameters
To list all parameters available for this command, execute neo help upload-domain-certificate in the
command line.
Table 198:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string
-n, --name

Name of the certificate that you set to the SSL host


The certificate must already be uploaded.

-l, --location

File name containing certificate data


Note that some CAs issue chained root certificates that contain an intermediate certifi
cate. In such cases, put all certificates in the file for upload starting with the signed SSL
certificate.

Example
neo upload-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --name myfirstcert --location ./certificate.pub

Related Information
generate-csr [page 161]
Configuring Custom Domains [page 1186]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

257

1.3.6.4.123 upload-hanaxs-certificates
This command uploads and applies identity provider certificates to productive HANA instances running on SAP
HANA Cloud Platform.

Note
After executing this command, a you need to restart the SAP HANA XS services for it to take effect. See
restart-hana [page 220].
neo upload-hanaxs-certificates --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user> --localpath
<path_to_certificate>

Parameters
To list all parameters available for this command, execute neo help upload-hanaxs-certificates in the
command line.
Table 199:
Required

-a, --account

Account name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-b, --application

Application name

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
Condition: Not required if using --application-process-id
-h, --host

Use the respective landscape host for your account type.

Type: URL. For acceptable values see Landscape Hosts [page 32]
-p, --password

To protect your password, enter it only when prompted by the console client and not ex
plicitly as a parameter in the properties file or the command line.

Type: string
-u, --user

Your email, SAP ID, or SCN user name

Type: string
-l, --localpath

Path to a X.509 certificate or a directory containing certificates on a loca l file system. If


the local path is a directory, all files in it shall be uploaded. You need to restart the HA NA
instances to activate the certificates.

Default: none
Type: string

258

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
To upload all certificates from the local C:\Certificates folder, execute:
neo upload-hanaxs-certificates --host hana.ondemand.com --account myaccount -application myapp --user mymail@example.com --localpath C:\Certificates

1.3.6.4.124 upload-keystore
This command is used to upload a keystore by uploading the keystore file. You can upload keystores on account,
application, and subscription levels.

Parameters
To list all parameters available for this command, execute neo help upload-keystore in the command line.
Table 200:
Required

-a, --account

Consumer account name


The account for which you provide username and password.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host

Use the respective landscape host for your account type.

Type: URL, for acceptable values see Landscape Hosts [page 32]
-l,--location

Path to a keystore file to be uploaded from the local file system. The file extension deter
mines the keystore type. The following extensions are sup
ported: .jks, .jceks, .p12, .pem. For more information about the keystore formats,
see Features [page 1247]

Type: string
-u, --user

Use your email, SAP ID or user name

Type: string

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

259

Table 201:
Optional

-b, --application

Application name

Use --application <consumer_application_name> if the application is


running in your account.

Use --application
<provider_account_name>:<provider_application_name> if the ap
plication is running in another account.

Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-w, --overwrite

Overwrites a file with the same name if such already exists. If you do not explicitly include
the --overwrite argument, you will be notified and asked if you want to overwrite the
file.

Example
On Subscription Level
neo upload-keystore --account <consumer_account_name> --application
<provider_account_name>:<provider_application_name>
--user <e-mail_or_user> --location C:\Keystores\KeyStore1.jks --host
hana.ondemand.com
On Application Level
neo upload-keystore --account <consumer_account_name> --application
<consumer_application_name>
--user <e-mail_or_user> --location C:\Keystores\KeyStore1.jks --host
hana.ondemand.com
On Account Level
neo upload-keystore --account <consumer_account_name> --user <e-mail_or_user>
--location C:\Keystores\KeyStore1.jks --host hana.ondemand.com

Related Information
Keystore Console Commands [page 1248]
Keys and Certificates [page 1246]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

260

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.3.6.4.125 version
This command is used to list the SDK version and the runtime. It also lists the command versions and the JAR files
in the SDK and checks whether the SDK is up to date.
Use this command to show the SDK version and the runtime. You can use parameters to list the command
versions and the JAR files in the SDK and to check whether the SDK version is up to date.
neo version --commands
neo version --jars
neo version --updates

Parameters
To list all parameters available for this command, execute neo help version in the command line.
Table 202:
Required

-c, --commands

Lists all commands available in the SDK and their versions.

-j, --jars

Lists all JAR files in the SDK and their versions.

-u, --updates

Checks if there are any updates and hot fixes for the SDK and whether the SDK version is
still supported. It also provides the version of the latest available SDK.

Table 203:
Optional

--output <value>

Prints the output in the specified format.

Acceptable values: 'json'


Type: string

Example
To show the SDK version and the runtime, execute:
neo version
To list all available commands and their versions, execute:
neo version -c

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

261

To list all JAR files in the SDK and their versions, execute:
neo version -j
To check whether the SDK is up to date, execute
neo version -u
There are several possible outcomes:
a hot fix is available, you need to update your SDK
your SDK is the latest version available
your SDK is deprecated, you need to update it
your SDK is supported, but it is not the latest version available

Related Information
Machine-Readable Command Output [page 93]

1.3.6.5

Exit Codes

Overview
The exit code is a number that indicates the outcome of a command execution. It shows whether the command
completes successfully or defines an error if something goes wrong during the execution.
When commands are executed as part of automated scripts, the exit codes provide feedback to the scripts, which
allows the script to bypass known errors that can be met during execution. A script can also interact with the user
in order to request additional information required for the script to complete.
All exit codes in SAP HANA Cloud are aligned to the Bash-Scripting Guide. For more information, see Exit Codes
With Special Meanings .

Ranges
The set of exit codes is divided into ranges, based on the error type and the reason.

262

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 204:
Error Type

Start Number

End Number

Count

No error

Common errors

Missing parameters

10

39

30

Parameter validation errors

40

109

70

Authentication and Authoriza 110


tion Errors

126

17

Reserved space for system


errors

127

165

39

Command-specific errors:
frontend

166

209

44

Command-specific errors:
backend

210

254

45

Reserved space for system


errors

255

255

Exit Codes
Exit codes can be defined as general (common for all commands) and command-specific (cover different cases
via different commands).
Table 205:
Code

Meaning

OK

General error

Error during execution of command

Command not found

Misspelled or missing command

Unsupported/Incompatible SDK version

SDK is not compatible with the runtime

Network error

Network problem or missing proxy con


figuration

5-9

Currently not used

Common errors

10

General missing parameter

Missing parameters

11

Missing host name

Missing parameters

12

Missing account name

Missing parameters

13

Missing application name

Missing parameters

14

Missing user name

Missing parameters

15-19

Currently not used

Missing parameters

20-39

Available for use by commands

Missing parameters

40

General parameter is invalid or empty

Validation errors

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Type/Reason

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

263

Code

Meaning

Type/Reason

41

Host name parameter is invalid or empty Validation errors

42

Account name parameter is invalid or


empty

Validation errors

43

Application name parameter is invalid or


empty

Validation errors

44-49

Currently not used

Validation errors

50-109

Available for use by commands

Validation errors

110

Wrong user or password

Authentication and authorization errors

111

General authentication and authoriza


tion error

Authentication and authorization errors

112-114

Currently not used

Authentication and authorization errors

115-126

Available for use by commands

Authentication and authorization errors

127-165

Special exit codes

System-dependent errors

166

General frontend error

Frontend

167 - 209

Available for use by commands

Frontend

210

General backend error

Backend

211 - 254

Available for use by commands

Backend

255

Special exit codes

System-dependent errors

Related Information
Console Client [page 88]

1.4

Services

SAP HANA Cloud Platform provides the following services:


Table 206:
Service

Description

Authorization Management API

The authorization management service REST API provides functionality to manage


roles of your applications and their assignments to users.

Business Services with YaaS [page 942]

You can build business services and Builder modules for YaaS on SAP HANA Cloud
Platform, and then use those services in cloud applications which again can run on
SAP HANA Cloud Platform.

264

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Service

Description

Connectivity Service [page 267]

SAP HANA Cloud Platform connectivity service provides a secure, reliable and
easy-to-consume access to business systems, running either on-premise or in the
cloud. SAP HANA Cloud Platform provides a trusted channel to your business sys
tems while, at the same time, your IT administrator has complete control and audit
ability of what is technically exposed to the on-demand world.

Data Quality Management, microservi

Offers microservices for address cleansing, geocoding, and reverse geocoding. Al

ces for location data (Beta)

lows you to embed address cleansing and enrichment services within any business
process or application so that you can quickly reap the value of complete and accu
rate address data.

Debugging Applications [page 986]

Allows you to inspect a Java application's runtime behavior and state.

Document Service [page 545]

SAP HANA Cloud Platform, document service provides a content repository for un
structured or semi-structured content. Applications access it using the OASIS
standard protocol Content Management Interoperability Services
(CMIS). The applications consume the service using the provided client library.

Feedback Service (Beta) [page 597]

SAP HANA Cloud Platform feedback service provides developers, customers, and
partners with the option to collect end-user feedback for their applications. The
feedback service also delivers detailed text analysis of user sentiment (positive,
negative, or neutral). The feedback service consists of a client API, exposed through
the HTTPS REST protocol, and administration and analysis user interface.
The feedback service is a beta functionality that is available on the SAP HANA
Cloud Platform trial landscape for developer accounts.

Gamification Service [page 615]

The SAP HANA Cloud Platform, gamification service allows the rapid introduction
of gamification concepts into applications. The service includes an online develop
ment and administration environment (gamification workbench) for easy imple
mentation and analysis of gamification concepts. The underlying gamification rule
management provides support for sophisticated gamification concepts, covering
time constraints, complex nested missions and collaborative games. The built-in
analytics module makes it possible to perform advanced analyisis of the player's
behavior to facilitate continuous improvement of game concepts.

Git Service [page 928]

SAP HANA Cloud Platform, Git service allows you to store and version source code
of applications, for example HTML5 and Java applications, in Git repositories.

OData provisioning

OData provisioning is a solution that allows you to consume data from an SAP Busi
ness Suite backend system in SAP HANA Cloud Platform. It establishes a connec
tion between SAP Business Suite data and target clients, platforms, and program
ming framework. OData provisioning exposes business data and business logic as
OData services on SAP HANA Cloud Platform, enabling customers to run user-cen
tric approach on SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

265

Service

Description

Internet of Things (IoT) Services

The Internet of Things Services are designed to facilitate and support the imple
mentation of Internet of Things applications. The services provide interfaces for
registering devices and their specific data types, sending data to a database run
ning on SAP HANA Cloud Platform in a secure and efficient manner, storing the
data in SAP HANA Cloud Platform as well as provide easy access to the data stored.

Keystore Service [page 1246]

Provides a repository for cryptographic keys and certificates to the applications


hosted on SAP HANA Cloud Platform.

Lifecycle REST API

The lifecycle REST API provides functionality for application lifecycle management.

Monitoring Service [page 703]

The monitoring service REST API enables you to fetch the overall monitoring status
and detailed metric values for your Java applications.

OAuth 2.0 Service [page 1310]

After the OAuth-protected application (resource server) is deployed in SAP HANA


Cloud Platform, configure the OAuth authorizations to define the clients authorized
to access the application and other communication information with them.

Performance Statistics Service (Beta)

Performance statistics enable you to monitor the resources used by your applica

[page 714]

tions and to investigate the causes of performance issues.

Persistence Service [page 720]

SAP HANA Cloud Platform persistence service provides in-memory and relational
persistence. All maintenance activities, such as data replication, backup and recov
ery, are handled by the platform.

Profiling Applications [page 1141]

Using SAP JVM Profiler, you can analyze resource-related problems in your Java
application regardless of whether the JVM is running locally or on the cloud.

Remote Data Sync Service [page 871]

SAP HANA Cloud Platform provides a service for synchronizing huge numbers of
remote databases into a consolidated SAP HANA database in the cloud. This serv
ice is based on SAP SQL Anywhere

and its MobiLink

technology.

To get access to MobiLink, you need to request it by creating an IT/IBC ticket to


component BC-NEO-CON.
SAP Cloud Identity Service

SAP Cloud Identity service is a cloud solution for identity lifecycle management. It
provides services for user login, registration, authentication, and access to SAP
HANA Cloud Platform applications.

SAP Forms as a Service by Adobe

SAP Forms as a Service is a solution for generating print and interactive forms us
ing Adobe Document Services running on SAP HANA Cloud Platform.

SAP HANA Cloud Platform Mobile Serv

SAP HANA Cloud Platform is an open, standard-based cloud platform that enables

ices

simplified mobile application development, configuration, and management.

SAP HANA Cloud Portal

SAP HANA Cloud Portal is a cloud-based solution for easy site creation and con
sumption with a superior user experience. Designed primarily for mobile consump
tion, it runs on top of SAP HANA Cloud and is built to operate with SAP HANA, for
in-memory computing.

266

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Service

Description

SAP Jam

Build socially-infused applications on the SAP HANA Cloud Platform with SAP Jam.
SAP Jam delivers secure, social collaboration that extends across SAP's entire
technology landscape - giving you social capabilities where and when you need
them in your business processes.
For more information, refer to our SAP Jam Developer Guide for HANA Cloud Plat
form.
To get support, visit our SAP Jam community

SAP Document Center

SAP Document Center is a solution that protects your content in an easy-to-use na


tive mobile application, giving users anytime, anywhere access to view, edit, and
collaborate on corporate and personal documents.

SAP Translation Hub (Beta) [page 894]

SAP Translation Hub enables customers and partners to satisfy the demands of a
global market by translating the short texts of products into additional languages.

Note
Beta features and services can be tested with the free developer account, which you can request on http://
hanatrial.ondemand.com.

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use of
the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by
the use of beta features.

Related Information
Using Beta Features in Accounts [page 22]
Accessing Services [page 30]

1.4.1 Connectivity Service


Overview
SAP HANA Cloud Platform connectivity service allows SAP HANA Cloud Platform applications to access securely
remote services that run on the Internet or on-premise. This service:
Consists of a Java API that application developers can use to consume remote services.
Allows account-specific configuration of application connections via HTTP and Mail destinations.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

267

Offers a technical connectivity solution, which can be used to establish a secure tunnel from the customer
network to an on-demand application in SAP HANA Cloud Platform. At the same time, the customer IT
department has full control and auditability of what is technically exposed to the on-demand world.
Allows you to make connections to both Java and ABAP on-premise systems.

Table 207:
General Internet
Connectivity

On-Demand to On-Prem
ise Connectivity

Sending and Fetching E-Mail

A company that uses SAP HANA Cloud Platform has been granted an account on the platform to which only
authorized users of the company have access. The company can subscribe applications to its account or deploy
its own applications, and those applications can then be used in this account. The administrator of the cloud
connector can set up a secure tunnel from the customer network to his or her account. The platform ensures that
the tunnel can be only used by the account applications. This means that applications of other accounts have no

268

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

access to the tunnel. The tunnel itself is encrypted via transport layer security so that connection privacy can be
guaranteed.

Features
The connectivity service supports the following protocols relevant for both Java and SAP HANA development:
HTTP Protocol - this protocol enables you to exchange data between your on-demand application and onpremise systems or internet services. For this aim, you can create and configure HTTP destinations to make
the needed Web connections. For on-premise connectivity, you can reach backend systems using the cloud
connector via HTTP.
Mail Protocols - the SMTP protocol allows you to send electronic mail messages from your Web applications
using e-mail providers that are accessible on the Internet, such as Google Mail (Gmail). The IMAP and POP3
allow you to retrieve e-mails from the mailbox of your e-mail account. Applications use the standard
javax.mail API. The e-mail provider and e-mail account are configured using mail destinations.
RFC Protocol - this protocol enables you to invoke ABAP function modules. You can create and configure RFC
destinations as well as make connections to back-end systems using the cloud connector via RFC.

SAP HANA Development


You can create XS destinations for connecting your HANA XS applications to Internet and on-premise services.
For more information, see Consuming the Connectivity Service (HANA XS) [page 421].

Java Development
Use the connectivity service for the following Java scenarios:
Consume a service from the Internet. More information: Consuming Internet Services (Java Web or Java EE 6
Web Profile) [page 348]
Make connections between Web applications and on-premise backend services via HTTP protocol. More
information: Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Make connections between Web applications and on-premise backend services via RFC protocol. More
information: Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]
Establish connections from on-premise systems to SAP HANA Cloud Platform, using the cloud connector.
More information: SAP HANA Cloud Connector [page 434]
Send and fetch e-mails. More information: Sending and Fetching E-Mail [page 408]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

269

Restrictions
For the on-demand to on-premise connectivity scenario, the currently supported protocols are HTTP(S) and
RFC.
Each SAP HANA Cloud Platform account can be connected to one cloud connector only. A single cloud
connector can expose an arbitrary number of back-end systems.
For Internet connections, you are allowed to use any port > 1024. For on-demand to on-premise solutions
there are no port limitations.
You can use destination configuration files with extension .props, .properties, .jks, and .txt, as well as
files with no extension.
If a destination configuration consists of a key store or trust store, it must be stored in JKS files with a
standard .jks extension.
To develop a JCo application, your SDK local runtime needs to be hosted by a 64-bit JVM, on a x86_64
operating system (Microsoft Windows OS, Linux OS, or Mac OS X).
On Windows platforms, you need to install Microsoft Visual C++ 2010 Redistributable Package (x64). To
download this package, go to http://www.microsoft.com/en-us/download/details.aspx?id=14632 .
To check all software and hardware prerequisites for working with cloud connector 2.x, see Prerequisites
[page 437].
You cannot communicate with an e-mail provider via an unencrypted SMTP protocol on port 25.
Fetched e-mail is not scanned for viruses.
Sending e-mail with attachments using javax.activation.DataHandler works with SAP HANA Cloud
Platform SDK for Java EE 6 Web Profile.
Mail destinations can only be configured on application level. That is, configuration on a subscription or
customer account level is not supported.
For SAP HANA Cloud Platform SDK for Java Web and SAP HANA Cloud Platform SDK for Java EE 6 Web
Profile: Applications must use the javax.mail version that is provisioned by the SAP HANA Cloud Platform
runtime (see Connectivity and Destination APIs [page 272]). Applications must not include the javax.mail
library as part of the web archive.

Related Information
Consuming the Connectivity Service (Java) [page 270]
Consuming the Connectivity Service (HANA XS) [page 421]
SAP HANA Cloud Connector [page 434]
Sending and Fetching E-Mail [page 408]
Connectivity Support [page 544]

1.4.1.1

Consuming the Connectivity Service (Java)

In this section, you will learn how to use SAP HANA Cloud Platform connectivity service to connect Web
applications to Internet, make on-demand to on-premise connections to Java and ABAP on-premise systems and
configure destinations to send and fetch e-mail. To do all these tasks, you need to create and configure
destinations, according to the relevant protocol type. For more information, see: Destinations [page 281]

270

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To learn more how to configure a destination from a particular type, see:


HTTP Destinations [page 322]
RFC Destinations [page 384]
Mail Destinations [page 410]

Who can use it?


The following user groups are involved in the end-to-end use of the connectivity service:
Application developers - develop the SAP HANA Cloud Platform application. They create a connectivityenabled application by using the connectivity service API.
Application operators - access SAP HANA Cloud Platform cockpit and are responsible for productive
deployment and operation of an application. They are also responsible for configuring the remote connections
that an application might need.
IT administrators - set up the connectivity to SAP HANA Cloud Platform in the customer's on-premise
network, using the cloud connector.

Scenarios
Making Internet connections between Web applications and external servers via HTTP protocol: Consuming
Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Making connections between Web applications and on-premise backend services via HTTP protocol:
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Making connections between Web applications and on-premise backend services via RFC protocol: Tutorial:
Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]
Sending and fetching e-mail via mail protocols: Sending and Fetching E-Mail [page 408]

Tips
The cloud connector provides light and easy way to establish secure connections from on-premise systems to
SAP HANA Cloud Platform accounts. It supports Microsoft Windows OS, Linux OS and Mac OS X operating
systems. For more information, see SAP HANA Cloud Connector [page 434].

Related Information
Connectivity Service [page 267]
Product Prerequisites and Restrictions [page 8]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

271

SAP Java Connector (Standalone Version)

1.4.1.1.1

Connectivity and Destination APIs

Destinations
Destinations are part of the SAP HANA Cloud Platform connectivity service and are used for the outbound
communication from a cloud application to a remote system. They contain the connection details for the remote
communication of an application, which can be configured for each customer to accommodate the specific
customer back-end systems and authentication requirements. For more information, see Destinations [page
281].
Destinations should be used by application developers when they aim to provide applications that:
Integrate with remote services or back-end systems that need to be configured by customers
Integrate with remote services or back-end systems that are located in a fenced environment (that is, behind
firewalls and not publicly accessible)

Tip
HTTP clients created by destination APIs allow parallel usage of HTTP client instances (via class
ThreadSafeClientConnManager).

Connectivity APIs
Package

Description

org.apache.http

http://hc.apache.org

org.apache.http.client

http://hc.apache.org/httpcomponents-client-ga/httpclient/
apidocs/org/apache/http/client/package-summary.html

org.apache.http.util

http://hc.apache.org/httpcomponents-core-ga/httpcore/
apidocs/org/apache/http/util/package-summary.html

javax.mail

https://javamail.java.net/nonav/docs/api/
The SAP HANA Cloud Platform SDK for Java Web uses
version 1.4.1 of javax.mail, the SDK for Java EE 6 Web
Profile uses version 1.4.5 of javax.mail, and the SDK for
Java Web Tomcat 7 uses version 1.4.7 of javax.mail.

272

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Package

Description

com.sap.core.connectivity.api

You can find the Connectivity service API in directory


<SDK_location>/javadoc/com/sap/core/
connectivity/api>.
You can also access it on the following URL: https://
help.hana.ondemand.com/javadoc/index.html

Destination APIs
JavaMail API [page 409]
DestinationFactory API [page 320]
SAP Java Connector API [page 280]
ConnectivityConfiguration API [page 275]
AuthenticationHeaderProvider API [page 277]
Principal Propagation Using HTTP Proxy [page 338]
HttpDestination API and DestinationFactory [page 273]

Destination Configuration Tasks


Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Console Client [page 283]
Configuring Destinations from the Cockpit [page 301]

1.4.1.1.1.1 HttpDestination API and DestinationFactory


All connectivity API packages are visible by default from all Web applications. Applications can consume the
destinations via a JNDI lookup

Procedure

Retrieving HTTP Destinations Using HttpDestination API


To consume destinations using HttpDestination API, you need to define your destination as a resource in the
web.xml file.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

273

1. An example of a destination resource named myBackend, which is described in the web.xml file, is as follows:
<resource-ref>
<res-ref-name>myBackend</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>
2. In your servlet code, you can look up the destination (a HTTP destination in this example) from the JNDI
registry as following:
import javax.naming.Context;
import javax.naming.InitialContext;
import com.sap.core.connectivity.api.http.HttpDestination;
...
// coding to lookup the destination "myBackend"
Context ctx = new InitialContext();
HttpDestination destination = (HttpDestination) ctx.lookup("java:comp/env/
myBackend");

Note
If you want the lookup name to differ from the destination name, you can specify the lookup name in <resref-name> and the destination name in <mapped-name>, as shown in the following example.
<resource-ref>
<res-ref-name>myLookupName</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
<mapped-name>myBackend</mapped-name>
</resource-ref>
3. With the retrieved HTTP destination, you can then, for example, send a simple GET request to the configured
remote system by using the following code:
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.HttpResponse;
...
// coding to call service "myService" on the system configured in the given
destination
HttpClient createHttpClient = destination.createHttpClient();
HttpGet get = new HttpGet("myService");
HttpResponse resp = createHttpClient.execute(get);

Note
If you want to use <res-ref-name>, which contains "/", the name after the last "/" should be the same as
the destination name. For example, you can use <res-ref-name>connectivity/myBackend</resref-name>. In this case, you should use java:comp/env/connectivity/myBackend as a lookup string.
If you want to get the URL of your configured destination, use the URI getURI() method. This method returns
the URL, defined in the destination configuration, converted to URI.

274

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Retrieving HTTP Destinations Using DestinationFactory


As alternative approach how to retrieve an HTTP destination, DestinationFactory can be used. We
recommend this approach if the used destinations are unknown at implementation time and should be loaded
dynamically at runtime.
1. Define the DestinationFactory as a JNDI resource in the web.xml file:
<resource-ref>
<res-ref-name>connectivity/DestinationFactory</res-ref-name>
<res-type>com.sap.core.connectivity.api.DestinationFactory</res-type>
</resource-ref>
2. In your Java code, you can then look it up and use it in following way:
DestinationFactory destinationFactory = (DestinationFactory)
ctx.lookup(DestinationFactory.JNDI_NAME);
destination = (HttpDestination)
destinationFactory.getDestination(destinationName);

Note
If you have two destinations with the same name, one configured on account level and the other on application
level, the getConfiguration() method will return the destination on account level.
The preference order is: subscription level -> account level -> application level.

Related Information
If you need to also add Maven dependencies, take a look at this blog: Building Java Web Applications with Maven

1.4.1.1.1.2 ConnectivityConfiguration API


All connectivity API packages are visible by default from all Web applications. Applications can consume the
connectivity configuration via a JNDI lookup.

Context
Besides making destination configurations, you can also allow your applications to use their own HTTP clients.
The ConnectivityConfiguration API provides you a direct access to the destination configurations of your
applications. This API also:
Can be used independent of the existing destination API so that applications can bring and use their own
HTTP client

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

275

Consists of both a public REST API and a Java client API.


The ConnectivityConfiguration API is supported by all runtimes, including Java Web Tomcat 7. For more
information about runtimes, see Application Runtime Container [page 955].
To learn how to retrieve destination configurations, follow the procedure below.

Procedure
1. To consume connectivity configuration using JNDI, you need to define ConnectivityConfiguration API
as a resource in the web.xml file. An example of a ConnectivityConfiguration resource named
connectivityConfiguration, which is described in the web.xml file, is as follows:
<resource-ref>
<res-ref-name>connectivityConfiguration</res-ref-name>
<restype>com.sap.core.connectivity.api.configuration.ConnectivityConfiguration</restype>
</resource-ref>
2. In your servlet code, you can look up the ConnectivityConfiguration API from the JNDI registry as
following:
import javax.naming.Context;
import javax.naming.InitialContext;
import com.sap.core.connectivity.api.configuration.ConnectivityConfiguration;
...
// look up the connectivity configuration API "connectivityConfiguration"
Context ctx = new InitialContext();
ConnectivityConfiguration configuration = (ConnectivityConfiguration)
ctx.lookup("java:comp/env/connectivityConfiguration");
3. With the retrieved ConnectivityConfiguration API, you can read all properties of any destination defined
on subscription, application or account level.

Note
If you have two destinations with the same name, one configured on account level and the other on
application level, the getConfiguration() method will return the destination on account level. The
preference order is: subscription level -> account level -> application level.
// get destination configuration for "myDestinationName"
DestinationConfiguration destConfiguration =
configuration.getConfiguration("myDestinationName");
// get the "myDestinationName" authentication property (example)
String value = destConfiguration.getProperty("Authentication");
// get all destination properties
Map<String, String> allDestinationPropeties =
destConfiguration.getAllProperties();
4. If truststore and keystore are defined in the corresponding destination, they can be accessed by using
methods getKeyStore and getTrustStore.
// get destination configuration for "myDestinationName"
DestinationConfiguration destConfiguration =
configuration.getConfiguration("myDestinationName");

276

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

// get the configured keystore


KeyStore keyStore = destConfiguration.getKeyStore();
// get the configured truststore
KeyStore trustStore = destConfiguration.getTrustStore();
// create sslcontext
TrustManagerFactory tmf =
TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustStore);
KeyManagerFactory keyManagerFactory =
KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
String keyStorePassword = "myPassword";
keyManagerFactory.init(keyStore, keyStorePassword.toCharArray());
SSLContext sslcontext = SSLContext.getInstance("TLSv1");
sslcontext.init(keyManagerFactory.getKeyManagers(), tmf.getTrustManagers(),
null);
SSLSocketFactory sslSocketFactory = sslcontext.getSocketFactory();
// get the destination URL
String value = destConfiguration.getProperty("URL");
URL url = new URL(value);
// use the sslcontext for url connection
URLConnection urlConnection = url.openConnection();
((HttpsURLConnection) urlConnection).setSSLSocketFactory(sslSocketFactory);
urlConnection.connect();
InputStream in = urlConnection.getInputStream();
...

1.4.1.1.1.3 AuthenticationHeaderProvider API


All connectivity API packages are visible by default from all Web applications. Applications can consume the
authentication header provider via a JNDI lookup.

Context
The AuthenticationHeaderProvider API allows your Web applications to use their own HTTP clients, as it
also provides them with authentication token generation (application-to-application SSO, on-premise SSO). This
API also:
Provides additional helper methods, which facilitate the task to initialize an HTTP client (for example,
authentication method that helps you set headers for application-to-application SSO).
Consists of both a public REST API and a Java client API.
The AuthenticationHeaderProvider API is supported by all runtimes, including Java Web Tomcat 7. For
more information about runtimes, see Application Runtime Container [page 955].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

277

Procedure

Retrieving Authentication Header Providers


1. To consume the authentication header provider API using JNDI, you need to define
AuthenticationHeaderProvider API as a resource in the web.xml file. An example of a
AuthenticationHeaderProvider resource named myAuthHeaderProvider, which is described in the
web.xml file, is as follows:
<resource-ref>
<res-ref-name>myAuthHeaderProvider</res-ref-name>
<restype>com.sap.core.connectivity.api.authentication.AuthenticationHeaderProvider</
res-type>
</resource-ref>
2. In your servlet code, you can look up the AuthenticationHeaderProvider API from the JNDI registry as
following:
import javax.naming.Context;
import javax.naming.InitialContext;
import com.sap.core.connectivity.api.authentication.AuthenticationHeaderProvider;
...
// look up the connectivity authentication header provider resource called
"myAuthHeaderProvider"
Context ctx = new InitialContext();
AuthenticationHeaderProvider authHeaderProvider = (AuthenticationHeaderProvider)
ctx.lookup("java:comp/env/myAuthHeaderProvider");

Generating Application-to-Application SSO Authentication


The AuthenticationHeaderProvider API can generate authorization header to be used in scenario of
application-to-application communication where the caller needs to propagate its logged in user. Both
applications are deployed on SAP HANA Cloud Platform and consumed within a single account. The header must
be embedded in the request to the target application.

Tip
We recommend that you pack the HTTP client (Apache or other) inside the lib folder of your Web application
archive.
Restrictions:
Principal Propagation must be enabled for the account. For more information, see ID Federation with the
Corporate Identity Provider [page 1292] section "Specifying Custom Local Provider Settings"
Both applications must run on behalf of the same account.

278

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The receiving application must use SAML2 authentication.

Note
In case you work with Java Web Tomcat 7 runtime: Bear in mind that the following code snippet works
properly only when using Apache HTTP client version 4.1.3. If you use other (higher) versions of Apache HTTP
client, you should adapt your code.

// retrieve the authorization header for application-to-application SSO


AuthenticationHeader appToAppSSOHeader =
authHeaderProvider.getAppToAppSSOHeader(url);
// create an HTTP client and add the header to the request
HttpClient httpClient = new DefaultHttpClient();
HttpGet request = new HttpGet(url);
request.addHeader(appToAppSSOHeader.getName(), appToAppSSOHeader.getValue());
// execute the request
HttpResponse response = httpClient.execute(request);

Generating On-Premise SSO Authentication


To learn how to generate on-premise SSO authentication, see Principal Propagation Using HTTP Proxy [page
338].

Generating SAPAssertionSSO Headers


SAP HANA Cloud Platform provides support for applications to use the SAML Bearer assertion flow for
consuming OAuth-protected resources. In this way, applications do not need to deal with some of the
complexities of OAuth and can reuse existing identity providers for user data. Users are authenticated by using
SAML against the configured trusted identity providers. The SAML assertion is then used to request an access
token from an OAuth authorization server. This access token should be injected in all HTTP requests to the
OAuth-protected resources.

Tip
he access tokens are cached by AuthenticationHeaderProvider and are auto-renovated. When a token
is about to expire, a new token is created shortly before the expiration of the old one.
The AuthenticationHeaderProvider API provides the following method for generating such headers:
List<AuthenticationHeader>
getOAuth2SAMLBearerAssertionHeaders(DestinationConfiguration
destinationConfiguration);
For more information, see:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

279

SAP Assertion SSO Authentication [page 326]


SAML Bearer Assertion Authentication [page 329]
https://help.hana.ondemand.com/javadoc/index.html

com.sap.core.connectivity.api.authentication

AuthenticationHeaderProvider

Related Information
HTTP Proxy for On-Premise Connectivity [page 336]

1.4.1.1.1.4 SAP Java Connector API


SAP Java Connector (SAP JCo) is a middleware component that enables you to develop ABAP-compliant
components and applications in Java. SAP JCo supports communication with Application Server ABAP (AS
ABAP) in both directions:
Inbound - Java calls ABAP
Outbound - ABAP calls Java
SAP JCo can be implemented with Desktop applications and Web server applications.
To learn in detail about the SAP JCo API, see SAP Java Connector (Standalone Version).

Note
This documentation contains sections not applicable to SAP HANA Cloud Platform. In particular:
SAP JCo Architecture: CPIC is only used in the last mile from your cloud connector to the backend. From
the cloud to the cloud connector, SSL protected communication is used.
SAP JCo Installation: SAP HANA Cloud Platform already includes all the necessary artifacts.
SAP JCo Customizing and Integration: In SAP HANA Cloud Platform, the integration is already done by the
runtime. You can concentrate on your business application logic.
Server Programming: The programming model of JCo in SAP HANA Cloud Platform does not include
server-side RFC communication.
IDoc Support for External Java Applications: For the time being, there is no IDocLibrary for JCo available in
SAP HANA Cloud Platform.

Related Information
Invoking ABAP Function Modules via RFC Protocol [page 383]

280

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.2

Destinations

Overview
Connectivity destinations are part of SAP HANA Cloud Platform connectivity service and are used for the
outbound communication of a cloud application to a remote system. They contain the connection details for the
remote communication of an application. Connectivity destinations are represented by symbolic names that are
used by on-demand applications to refer to remote connections. The connectivity service resolves the destination
at runtime based on the symbolic name provided. The result is an object that contains customer-specific
configuration details, such as the URL of the remote system or service, the authentication type, and the relative
credentials.
You can use destination files with extension .props, .properties, .jks, and .txt, as well as files with no
extension.
The currently supported destination types are HTTP, Mail and RFC.
HTTP destination [page 322] - provides data communication via HTTP protocol and is used for both Internet
and on-premise connections..
Mail destination [page 410]- specifies an e-mail provider for sending and retrieving e-mails via SMTP, IMAP
and POP3 protocols.
RFC destination [page 384] - makes connections to ABAP on-premise systems via RFC protocol using JCo as
API.

Connectivity Destinations Configuration Level (HTTP and RFC)


Destinations can be simultaneously configured on three levels: application, consumer account and subscription.
This means it is possible to have one and the same destination on more than one configuration level.
Application level - The destination is related to an application and its relevant provider account. It is, though,
independent from the consumer account in which the application is running.
Consumer account level - The destination is related to a particular account.
Subscription level - The destination is related to the triad <Application, Provider Account, Consumer
Account>.
The runtime tries to resolve a destination in the following order: Subscription level Consumer account level
Provider application level.
For more information about the usage of consumer account, provider account and provider application, see
Configuring Destinations from the Console Client [page 283].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

281

Configuring Destinations Using Connectivity Service 2.x


To use the Connectivity service 2.x and the cloud connector 2.x version, the following properties need to be
specified, according to the destination type:
For HTTP destinations, specify property: CloudConnectorVersion = 2
For RFC destinations, specify property: jco.client.cloud_connector_version = 2

Connectivity Destinations Configuration Cache


Destination configuration files and Java keystore (JKS) files are cached at runtime. The cache expiration time
is set to a small time interval (currently around 4 minutes). This means that once you update an existing
destination configuration or a JKS file, the application needs about 4 minutes until the new destination
configuration is applied. To avoid this waiting time, the application can be restarted on the cloud; following the
restart, the new destination configuration takes effect immediately.
When you configure a destination for the first time, it takes effect immediately.
If you change a mail destination, the application needs to be restarted before the new configuration becomes
effective.

How to Configure Destinations


To configure and then use a destination to remotely connect your Java EE or on-demand application, you can use
either of the following methods:
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

Related Information
You can see examples in the SDK package that you previously downloaded from http://
tools.hana.ondemand.com.
Open the SDK location and go to /tools/samples/connectivity. This folder contains a standard
template.properties file, weather destination, and weather.destinations.properties file, which provides all the
necessary properties for uploading the weather destination.

282

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.2.1 Configuring Destinations from the Console Client


As an application operator, you can configure your application using SAP HANA Cloud Platform console client.
You can configure HTTP, Mail or RFC destinations using a standard properties file.
The tasks listed below demonstrate how to upload, download, and delete connectivity destinations. You can
perform these operations for destinations related to your own account, a provider account, your own application
or an application provided by another account.
To use an application from another account, you must be subscribed to this application through your account.

Note
Destination files must be encoded in ISO 8859-1 character encoding.

Prerequisites
You have downloaded and set up the console client. For more information, see Setting Up the Console Client
[page 42].
For specific information about all connectivity restrictions, see Connectivity Service [page 267] section
"Restrictions".

HTTP Destination Properties Files


Name - the name of the destination.
URL - the URL of the remote system or service.
Authentication - the type of authentication against the remote system or service.
The number of mandatory property keys varies depending of the authentication type you choose. For more
information about HTTP destination properties files, HTTP Destinations [page 322].
Key stores and trust stores must be stored in JKS files with a standard .jks extension.
If mandatory fields are missing or data is specified incorrectly, you will be prompted accordingly by the console
client.

Mail Destination Properties Files


Name - the name of the destination.
Type - must be "MAIL" for mail destinations.
mail.* - javax.mail properties for configuring the mail session.
For more information about mail destination properties files, see Mail Destinations [page 410].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

283

If mandatory fields are missing or data is specified incorrectly, you will be prompted accordingly by the console
client.

RFC Destination Properties Files


Name - the name of the destination.
Type - must be "RFC" for RFC destinations.
jco.client* - JCo properties for configuring an RFC connection.
jco.destination* - JCo properties for configuring the behavior of a JCo destination.
All properties except Name and Type must start with "jco.client." or "jco.destination". For more
information about RFC destination properties files, see RFC Destinations [page 384].
If mandatory fields are missing or data is specified incorrectly, you will be prompted accordingly by the console
client.

Tasks
Uploading Destinations [page 285]
Downloading Destinations [page 286]
Deleting Destinations [page 288]

Tutorials with Destinations


Tutorial: Sending E-Mails [page 414]
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]

Related Information
Examples (Console) [page 289]

284

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.2.1.1 Uploading Destinations

Context
The procedure below explains how you can upload destination configuration properties files and certificate files.
You can upload them on account, application or subcribed application level.

Note
Bear in mind that, by default, your destinations are configured on SAP HANA Cloud Platform, that is the
hana.ondemand.com landscape. If you need to specify a particular landscape host, you need to add the --host
parameter, as shown in the examples. Otherwise, you can skip this parameter.

Procedure
1. Open the command prompt.
2. Navigate to the tools folder of the SDK location.
3. Optional: Enter neo help to display all the commands of the console client or neo help <command_name>
to display the help information for a command.
4. Upload a destination.
To upload a destination on account level, use the following command:
neo put-destination --account <account_name> --user <user_name> --localpath
<destination_or_JKS_file_localpath> --host <landscape_host>
To upload a destination on application level, use the following command:
neo put-destination --account <account_name> --user <user_name> --application
<application_name> --localpath <destination_or_JKS_file_localpath> --host
<landscape_host>
To upload a destination for a subscribed application, use the following command:
neo put-destination --account <account_name> --user <user_name> --application
<provider_account>:<provider_application> --localpath
<destination_or_JKS_file_localpath> --host <landscape_host>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

285

Tips
Note
When uploading a destination configuration file that contains a password field, the password value remains
available in the file. However, if you later download this file, using the get-destination command, the
password value will no more be visible. Instead, after Password =..., you will only see an empty space.

Note
The configuration parameters used by SAP HANA Cloud Platform console client can be defined in a properties
file as well, instead of being specified directly in the command (with the exception of the -password
parameter, which must be specified when the command is executed). When you use a properties file, enter the
path to it as the last command line parameter.
Example:
neo put-destination <path_to_properties_file>

Related Information
Examples (Console) [page 289]
put-destination [page 211]

1.4.1.1.2.1.2 Downloading Destinations

Context
The procedure below explains how you can download (read) destination configuration properties files and
certificate files. You can download them on account, application or subcribed application level.
You can read destination files with extension .props, .properties, .jks, and .txt, as well as files with no
extension. Destination files must be encoded in ISO 8859-1 character encoding.

Note
Bear in mind that, by default, your destinations are configured on SAP HANA Cloud Platform, that is the
hana.ondemand.com landscape. If you need to specify a particular landscape host, you need to add the --host
parameter, as shown in the examples. Otherwise, you can skip this parameter.

286

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Open the command prompt.
2. Navigate to the tools folder of the SDK location.
3. Optional: Enter neo help to display all the commands of the console client or neo help <command_name>
to display the help information for a command.
4. Download a destination.
To read a destination on account level, use the following command:
neo get-destination --account <account_name> --user <user_name> --name
<destination_name> --localpath <localpath_to_destination_or_JKS_file> --host
<landscape_host>
To read a destination on application level, use the following command:
neo get-destination --account <account_name> --user <user_name> --application
<application_name> --name <destination_name> --localpath
<localpath_to_destination_or_JKS_file> --host <landscape_host>
To read a destination for a subscribed application, use the following command:
neo get-destination --account <account_name> --user <user_name> --application
<provider_account>:<provider_application> --name <destination_name> -localpath <localpath_to_destination_or_JKS_file> --host <landscape_host>

Tips
Note
If you download a destination configuration file that contains a password field, the password value will not be
visible. Instead, after Password =..., you will only see an empty space. You will need to learn the password in
other ways.

Note
The configuration parameters used by SAP HANA Cloud Platform console client can be defined in a properties
file as well, instead of being specified directly in the command (with the exception of the -password
parameter, which must be specified when the command is executed). When you use a properties file, enter the
path to it as the last command line parameter. A sample weather properties file can be found in directory
<SDK_location>\tools\samples\connectivity.
Example:
neo get-destination <path_to_properties_file>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

287

Related Information
Examples (Console) [page 289]
put-destination [page 211]

1.4.1.1.2.1.3 Deleting Destinations

Context
The procedure below explains how you can delete destination configuration properties files and certificate files.
You can delete them on account, application or subcribed application level.

Note
Bear in mind that, by default, your destinations are configured on SAP HANA Cloud Platform, that is the
hana.ondemand.com landscape. If you need to specify a particular landscape host, you need to add the --host
parameter, as shown in the examples. Otherwise, you can skip this parameter.

Procedure
1. Open the command prompt.
2. Navigate to the tools folder of the SDK location.
3. Optional: Enter neo help to display all the commands of the console client or neo help <command_name>
to display the help information for a command.
4. Delete a destination.
To delete a destination on account level, use the following command:
neo delete-destination --account <account_name> --user <user_name> --name
<destination_name> --host <landscape_host>
To delete a destination on application level, use the following command:
neo delete-destination --account <account_name> --user <user_name> -application <application_name> --name <destination_name> --host
<landscape_host>
To delete a destination from a subscribed application, use the following command:
neo delete-destination --account <account_name> --user <user_name> -application <provider_account>:<provider_application> --name
<destination_name> --host <landscape_host>

288

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tips
Note
The configuration parameters used by SAP HANA Cloud Platform console client can be defined in a properties
file as well, instead of being specified directly in the command (with the exception of the -password
parameter, which must be specified when the command is executed). When you use a properties file, enter the
path to it as the last command line parameter.
Example:
neo delete-destination <path_to_properties_file>

Related Information
Examples (Console) [page 289]
delete-destination [page 131]

1.4.1.1.2.1.4 Examples (Console)

Examples for Uploading Destinations


neo put-destination --account myaccount --user p1234567890 --localpath C:\myfiles
\myconfiguration.jks --host hanatrial.ondemand.com
neo put-destination --account myaccount --user p1234567890 --application demo -localpath C:\SDK\tools\samples\connectivity\weather --host hanatrial.ondemand.com
neo put-destination --account myaccount --user p1234567890 --application
otheraccount:remotedemo --localpath C:\SDK\tools\samples\connectivity\weather -host hanatrial.ondemand.com

Examples for Downloading Destinations


neo get-destination --account myaccount --user p1234567890 --name weather -localpath C:\myfiles --host hanatrial.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

289

neo get-destination --account myaccount -user p1234567890 --application demo --name


myconfiguration.jks --localpath C:\SDK\tools\samples\connectivity --host
hanatrial.ondemand.com
neo get-destination --account myaccount --user p1234567890 --application
otheraccount:remotedemo --name weather --localpath C:\SDK\tools\samples
\connectivity --host hanatrial.ondemand.com

Examples for Deleting Destinations


neo delete-destination --account myaccount --user p1234567890 --name
myconfiguration.jks --host hanatrial.ondemand.com
neo delete-destination --account myaccount --user p1234567890 --application demo -name weather --host hanatrial.ondemand.com
neo delete-destination --account myaccount --user p1234567890 --application
otheraccount:remotedemo --name weather --host hanatrial.ondemand.com

1.4.1.1.2.2 Configuring Destinations from the Eclipse IDE


You can use the Connectivity editor in the Eclipse IDE to configure HTTP, Mail and RFC destinations in order to:
Connect your Web application to the Internet or make it consume an on-premise backend system via
HTTP(S);
Send an e-mail from a simple Web application using an e-mail provider that is accessible on the Internet;
Make your Web application invoke a function module in an on-premise ABAP system via RFC.
You can create, delete and modify destinations to use them for direct connections or export them for further
usage. You can also import destinations from existing files.

Note
Destination files must be encoded in ISO 8859-1 character encoding.

Prerequisites
You have downloaded and set up your Eclipse IDE. For more information, see Installing Java Tools for Eclipse
and SDK [page 33] or Updating Java Tools for Eclipse and SDK [page 43].
You have created a Java EE application. For more information, see Creating a HelloWorld Application [page
47] or Using Java EE 6 Web Profile [page 966].

290

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tasks
Creating and Deleting Destinations Locally [page 291]
Creating and Deleting Destinations on the Cloud [page 292]
Using Destination Certificates (IDE) [page 294]
Importing Destinations (IDE) [page 295]
Exporting Destinations (IDE) [page 296]

Tutorials with Destinations


Tutorial: Sending E-Mails [page 414]
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]

Related Information
Examples (IDE) [page 298]

1.4.1.1.2.2.1 Creating and Deleting Destinations Locally

Context
The procedure below demonstrates how you can create and configure connectivity destinations (HTTP, Mail or
RFC) on a local SAP HANA Cloud Platform server.

Procedure
1. In the context menu of the Servers view, choose

New

Server .

2. Expand the SAP node and, as a server type, choose between:


Java Web Server
Java Web Tomcat 7 Server

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

291

Java Web Tomcat 8 Server


Java EE 6 Web Profile Server
3. Choose Finish.
4. A new server <name> [Stopped]> appears on the Servers view.
Also, a Servers folder is created and appears in the navigation tree of the Eclipse IDE. It contains configurable
folders and files you can use, for example, to change your HTTP or JMX port.
5. On the Servers view, double-click the added server to open its editor.
6. Go to the Connectivity tab view.
a. In the All Destinations section, choose the

button to create a new destination.

b. From the dialog window, enter a name for your destination, select its type and then choose OK.
c. In the URL field, enter the URL of the target service to which the destination should refer.
d. In the Authentication dropdown box, choose the authentication type required by the target service to
authenticate the calls.
If the target service does not require authentication, choose NoAuthentication.
If the target service requires basic authentication, choose BasicAuthentication. You need to enter a
user name and a password.
If the target service requires a client certificate authentication, choose
ClientCertificateAuthentication. See Using Destination Certificates (IDE) [page 294].
e. Optional: In the Properties or Additional Properties section, choose the
destination properties.

button to specify additional

f. Save the editor.


7. When a new destination is created, the changes take effect immediately.
8. To delete a destination, choose the

button.

Related Information
Examples (IDE) [page 298]
Destinations [page 281]

1.4.1.1.2.2.2 Creating and Deleting Destinations on the Cloud

Context
The procedure below demonstrates how you can create and configure connectivity destinations (HTTP, Mail or
RFC) on SAP HANA Cloud Platform.

292

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. In the context menu of the Servers view, choose

New

Server .

2. Choose SAP HANA Cloud Platform as the type of server you want to create, choose Next, and then Finish.
3. A new server <application>.<account> [Stopped]> appears on the Servers view.
4. Double-click the added server to open the server editor.
5. Go to the Connectivity tab view.
a. In the All Destinations section, choose the

button to create a new destination.

b. From the dialog window, enter a name for your destination, select its type and the choose OK.
c. In the URL field, enter the URL of the target service to which the destination should refer.
d. In the Authentication dropdown box, choose the authentication type required by the target service to
authenticate the calls.
If the target service does not require authentication, choose NoAuthentication.
If the target service requires basic authentication, choose BasicAuthentication. You need to enter a
user name and a password.
If the target service requires a client certificate authentication, choose
ClientCertificateAuthentication. See Using Destination Certificates (IDE) [page 294].
If the target service requires your cloud user authentication, choose PrincipalPropagation. You also
need to select Proxy Type: OnPremise and should enter the additional property
CloudConnectorVersion with value 2.
e. In the Proxy Type dropdown box, choose the required type of proxy connection.

Note
This dropdown box allows you to choose the type of your proxy and is only available when deploying on
SAP HANA Cloud Platform. The default value is Internet. In this case, the destination uses the HTTP
proxy for the outbound communication with the Internet. For consumption of an on-premise target
service, choose the OnPremise option so that the proxy to the SSL tunnel is chosen and the tunnel is
established to the connected cloud connector.
f. Optional: In the Properties or Additional Properties section, choose the
destination properties.

button to specify additional

g. Save the editor. This saves the specified destination configuration in SAP HANA Cloud Platform.
6. When new destinations are created, the changes take effect immediately.

Note
Bear in mind that changes are currently cached with a cache expiration of up to 4 minutes, so if you modify
a destination configuration the changes might not take effect immediately. However, if the relevant Web
application is restarted on the cloud, the destination changes will take effect immediately.
7. To delete a destination, choose the

SAP HANA Cloud Platform


SAP HANA Cloud Platform

button.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

293

Related Information
Examples (IDE) [page 298]
Destinations [page 281]

1.4.1.1.2.2.3 Using Destination Certificates (IDE)

Prerequisites
You have opened the Connectivity editor in the Eclipse IDE.

Context
You can maintain keystore certificates in the Connectivity editor. You can upload, add and delete certificates for
your connectivity destinations. Bear in mind that:
You can use JKS, PFX and P12 files for destination keystore, and JKS, CRT, CER, DER files for destination
truststore.
You add certificates in a keystore file and then you upload, add, or delete this keystore.
You can add certificates only for HTTPS destinations. Keystore is available only for
ClientCertificateAuthentication.

Procedure
Uploading Certificates
1. Press the Upload/Delete keystore
editor.

button. You can find it in the All Destinations section in the Conectivity

2. Choose Upload Keystore and select the certificate you want to upload. Choose Open or double-click the
ceritificate.
The certificate file is added.

Note
You can upload a certificate during creation or editing of a destination, by choosing Manage Keystore or by
pressing the Upload/Delete keystore

294

button.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Adding Certificates to Destinations


1. Create a new destination, or open an existing one for editing.
2. In the URL field, enter an HTTPS address.
3. You can use the default JDK truststore or select another one from the truststore dropdown menu. If the menu
is empty, you can upload a certificate on the fly. The password is used for the keystore that will contain your
certificate on the cloud.
4. In the Authentication field, select ClientCertificateAuthentication.
5. In the Keystore name field, select the certificate you just added. Enter the password.

Deleting Certificates

1. Press the Upload/Delete keystore

button.

2. Select the certificate you want to remove and choose Delete Selected
3. Upload another certificate, or close the Manage Keystores window.

Related Information
Creating and Deleting Destinations Locally [page 291]
Creating and Deleting Destinations on the Cloud [page 292]
Importing Destinations (IDE) [page 295]

1.4.1.1.2.2.4 Importing Destinations (IDE)

Prerequisites
You have previously created a connectivity destination (HTTP, Mail or RFC).

Note
The Connectivity editor allows importing destination files with extension .props, .properties, and .txt, as
well as files with no extension. Destination files must be encoded in ISO 8859-1 character encoding.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

295

Procedure
1. On the Servers view, double-click your server to open its editor.
2. Go to the Connectivity tab view.
3. Choose button

(Import destination).

4. Browse to one of the following file types and choose OK.


If the destination does not contain client certificate authentication, it is saved as a single configuration file.
If the destination provides client certificate data, it is saved as an archive, which contains the main
configuration file and a Keystore file.
5. The destination file is imported within the Connectivity editor.

Note
If the properties file contains incorrect properties or values, for example wrong destination type, the editor
only displays the valid ones in the Properties table.

Related Information
Examples (IDE) [page 298]

1.4.1.1.2.2.5 Exporting Destinations (IDE)

Prerequisites
You have imported or created a new destination (HTTP, Mail or RFC) in the Eclipse IDE.

Procedure
1. On the Servers view, double-click your server to open its editor.
2. Go to the Connectivity tab view.
3. From the list of destination names, select the one you want to export.
4. Choose button

(Export destination).

5. Browse to the directory you want to export your destination.


If the destination does not contain client certificate authentication, it is saved as a single configuration file.

296

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If the destination provides client certificate data, it is saved as an archive, which contains the main
configuration file and a Keystore file.

Tip
You can keep the default name of the destination, or rename it to avoid overriding with previous files with
the same name.

Next Steps
After exporting the destination, you can open it to check its content. Bear in mind that all password fields will be
commented (with # symbols), and their values - deleted.
Example:
#Exported connectivity destination
#The following fields with passwords were removed:
#Password
#Tue Apr 21 15:01:02 FET 2015
Type=HTTP
Authentication=BasicAuthentication
Name=mydestination
URL=https://sap.com/index.html
User=p1234567890

Related Information
Examples (IDE) [page 298]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

297

1.4.1.1.2.2.6 Examples (IDE)

Example of HTTP Destination (Internet)

298

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example of HTTP Destination (OnPremise)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

299

Example of Mail Destination

Example of RFC Destination

300

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.2.3 Configuring Destinations from the Cockpit

Use the Destinations editor in SAP HANA Cloud Platform cockpit to configure HTTP, Mail and RFC destinations in
order to:
Connect your Web application to the Internet or make it consume an on-premise back-end system via
HTTP(S)
Send an e-mail from a simple Web application using an e-mail provider that is accessible on the Internet.
Make your Web application invoke a function module in an on-premise ABAP system via RFC.
You can create, delete, clone, modify, import and export destinations.
Use this editor to work with destinations on subscription, account, and application level.

Note
Destination files must be encoded in ISO 8859-1 character encoding.

Prerequisites
1. You have logged into the cockpit from the SAP HANA Cloud Platform landing page, depending on your
account type. For more information, see Landscape Hosts [page 32].
2. Depending on the level you need to make destination configurations from the Destinations editor, make sure
the following is fulfilled:
Subscription level you need to have at least one application subscribed to your account.
Application level you need to have at least one application deployed on your account.
Account level no prerequisites.
For more information, see Accessing the Destinations Editor [page 302].

Tasks
Creating Destinations (Cockpit) [page 303]
Checking the Availability of a Destination (Cockpit) [page 306]
Importing Destinations (Cockpit) [page 311]
Cloning Destinations (Cockpit) [page 308]
Exporting Destinations (Cockpit) [page 312]
Editing and Deleting Destinations (Cockpit) [page 309]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

301

Tutorials with Destinations


Tutorial: Sending E-Mails [page 414]
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]

Related Information
Examples (Cockpit) [page 313]

1.4.1.1.2.3.1 Accessing the Destinations Editor

Prerequisites
You have logged into the cockpit from the SAP HANA Cloud Platform landing page, depending on your account
type. For more information, see Landscape Hosts [page 32].

Procedure
Access on Subscription Level
1. In the cockpit, select your account name from the Account menu in the breadcrumbs.
2. From the left-side navigation, choose
subscribed Java applications (if any).

Applications

Subscriptions

to open the page with your currently

3. Select the application for which you need to create a destination.


4. From the left-side panel, choose Destinations.

Access on Connectivity Level


1. In the cockpit, select your account name from the Account menu in the breadcrumbs.
2. From the left-side navigation, choose

Connectivity

Destinations .

3. The Destinations editor is opened.

302

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Access on Application Level


1. In the cockpit, select your account name from the Account menu in the breadcrumbs.
2. From the left-side navigation, choose Applications
currently deployed Java Web applications (if any).

Java Applications

to open the page with your

3. Select the application for which you need to create a destination.


4. From the left-side panel, choose

Configuration

Destinations .

5. The Destinations editor is opened.

Related Information
Creating Destinations (Cockpit) [page 303]
Importing Destinations (Cockpit) [page 311]
Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.2 Creating Destinations (Cockpit)

Prerequisites
You have logged into the cockpit and opened the Destinations editor.

Context
To learn how to create HTTP, RFC and Mail destinations, follow the steps on the relevant pages:
Creating HTTP Destinations [page 304]
Creating RFC Destinations [page 305]
Creating Mail Destinations [page 306]

Related Information
Destinations [page 281]
Examples (Cockpit) [page 313]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

303

1.4.1.1.2.3.2.1 Creating HTTP Destinations

Prerequisites
You have logged into the cockpit and opened the Destinations editor.

Procedure
1. Choose New Destination.
2. Enter a destination name.
3. From the Type dropdown menu, choose HTTP.
4. The Description field is optional.
5. Specify the destination URL.
6. From the Proxy Type dropdown box, select Internet or OnPremise, depending on the connection you need
to provide for your application.
7. Make sure that Cloud Connector Version is set to 2.
8. From the Authentication dropdown box, select the authentication you need for the connection:
No Authentication - your destination will be provided direct access to the relevant on-premise service.
Basic Authentication - you need to enter user/password credentials.
SAPAssertionSSO - you also need to provide parameters: IssuerSID, IssuerClient, RecipientSID,
RecipientClient and, if needed, Certificate.
AppToAppSSO - no additional parameters except for truststore certificate, if needed.
PrincipalPropagation - you must select ProxyType=OnPremise. Otherwise, the destination cannot
be saved.
ClientCertificateAuthentication - you must select ProxyType=Internet, and your destination
URL must be HTTPS. You also need to provide both keystore and truststore parameters.
OAuth2SAMLBearerAssertion - you must select ProxyType=Internet, and you also need to provide
parameters: audience, clientKey, and tokenServiceURL. For more information, see: SAML Bearer
Assertion Authentication [page 329].

Note
If you set an HTTPS destination, you need to also add truststore. For more information, see Using
Destination Certificates (Cockpit) [page 310].
9. Optional: You can enter additional properties.
a. In the Additional Properties panel, choose New Property.
b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You can
add as many properties as you need.
c. To delete a property, choose the

304

button next to it.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

10. When you are ready, choose the Save button.

Related Information
Examples (Cockpit) [page 313]
HTTP Destinations [page 322]
Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.2.2 Creating RFC Destinations

Prerequisites
You have logged into the cockpit and opened the Destinations editor.

Procedure
1. Choose New Destination.
2. Enter a destination name.
3. From the Type dropdown menu, choose RFC.
4. The Description field is optional.
5. Make sure that Cloud Connector Version is set to 2.
6. Enter credentials for User and Password.
7. Optional: You can enter additional properties.
a. In the Additional Properties panel, choose New Property.
b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You can
add as many properties as you need.
c. To delete a property, choose the

button next to it.

If you add PrincipalPropagation as additional property (jco.destination.auth type), your RFC


destination must not contain user and password information. It can, however, contain repository credentials.
8. When you are ready, choose the Save button.

Related Information
Examples (Cockpit) [page 313]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

305

RFC Destinations [page 384]


Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.2.3 Creating Mail Destinations

Prerequisites
You have logged into the cockpit and opened the Destinations editor.

Procedure
1. Choose New Destination.
2. Enter a destination name.
3. From the Type dropdown menu, choose MAIL.
4. The Description field is optional.
5. Enter credentials for User and Password.
6. Optional: You can enter additional properties.
a. In the Additional Properties panel, choose New Property.
b. Enter a key (name) or choose one from the dropdown menu and specify a value for the property. You can
add as many properties as you need.
c. To delete a property, choose the

button next to it.

7. When you are ready, choose the Save button.

Related Information
Examples (Cockpit) [page 313]
Mail Destinations [page 410]
Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.3 Checking the Availability of a Destination


(Cockpit)

306

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Prerequisites
You have logged into the cockpit and opened the Destinations editor.

Context
You can use the Check Connection button in the Destinations editor of the cockpit to verify if the URL configured
for a HTTP Destination is reachable and if the connection to the specified system is possible.

Note
This check is available with cloud connector version 2.7.1 or higher.
For each destination, the check button is available in the destination detail view and in the destination overview list
(icon Check availability of destination connection in section Actions).

Note
The check does not guarantee that a backend is operational. It only verifies if a connection to the backend is
possible.
This check is supported only for destinations with Proxy Type Internet and OnPremise:
For Internet destinations:
If the check receives a HTTP status code above or equal to 500 from the targeted URL, the check is
considered failed.
Every HTTP status code below 500 is treated as successful.
For OnPremise destinations:
If the targeted backend is reached and returns a HTTP status code below 500 the check is considered
successful.

Error Messages for OnPremise Destinations

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

307

Table 208:
Error Message

Reason

Backend status could not be determined.

The cloud connector version is less

Action

Upgrade the cloud connector to ver

Connect the cloud connector to the


corresponding account.

Check the server status (availabil


ity) of the backend system.

sion 2.7.1 or higher.

than 2.7.1.

The cloud connector is not con


nected to the account.

The backend returns a HTTP status


code above or equal to 500 (server
error).

The SCC is not configured properly.

Check the basic SCC configuration


steps: Initial Configuration [page 459]

The SCC is not configured properly.

Check the basic SCC configuration


steps: Initial Configuration [page 459]

Backend is not reachable from cloud

SCC configuration is ok but the backend

Check the backend (server) availability.

connector.

is not reachable.

Backend is not available in the list of de


fined system mappings in cloud
connector.
Resource is not accessible in cloud
connector or backend is not reachable.

1.4.1.1.2.3.4 Cloning Destinations (Cockpit)

Prerequisites
You have previously created or imported a connectivity destination (HTTP, Mail or RFC ) in the Destinations editor
of the cockpit.

Procedure
1. In the Destinations editor, go to the existing destination which you want to clone.
2. Choose the

icon.

3. The editor automatically creates and opens a new destination that contains all the properties of the selected
one.
4. You can modify some parameters if you need.
5. When you are ready, choose the Save button.

308

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Examples (Cockpit) [page 313]
Exporting Destinations (Cockpit) [page 312]

1.4.1.1.2.3.5 Editing and Deleting Destinations (Cockpit)

Prerequisites
You have previously created or imported a connectivity destination (HTTP, Mail or RFC) in the Destinations editor
of the cockpit.

Procedure
Edit a destination:
1. To edit a created/imported destination, choose the

button.

2. You can edit the main parameters as well as the additional properties of a destination.
3. Choose the Save button. The changes will take effect in up to five minutes.

Tip
For complete consistency, we recommend that you first stop your application, then apply your
destination changes, and then start again the application. Also, bear in mind that these steps will cause
application downtime.
Delete a destination:
To remove an existing destination, choose the

button. The changes will take effect in up to five minutes.

Related Information
Examples (Cockpit) [page 313]
Exporting Destinations (Cockpit) [page 312]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

309

1.4.1.1.2.3.6 Using Destination Certificates (Cockpit)

Prerequisites
You have logged into the cockpit and opened the Destinations editor. For more information, see Accessing the
Destinations Editor [page 302].

Context
This page explains how you can maintain truststore and keystore certificates in the Destinations editor. You can
upload, add and delete certificates for your connectivity destinations. Bear in mind that:
You can only use JKS, PFX and P12 files for destination key store, and JKS, CRT, CER, DER for destination
trust store.
You can add certificates only for HTTPS destinations. Truststore can be used for all authentication types.
Keystore is available only for ClientCertificateAuthentication.

Procedure
Uploading Certificates
1. Choose the Certificates button.
2. Choose Upload Certificate.
3. Browse to the certificate file you need to upload.
The certificate file is added.

Note
You can upload a certificate during creation or editing of a destination, by clicking the Upload and Delete
Certificates link.

Adding Certificates to Destinations


1. Create a new destination, or open an existing one for editing.
2. In the URL field, enter an HTTPS address.
3. You can use the default JDK truststore or select another one from the dropdown menu. If the menu is empty,
you can upload a certificate on the fly. To omit this property, you can set TrustAll=true.

310

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. If you choose Authentication = ClientCertificateAuthentication, you need to also provide a keystore.

Deleting Certificates
1. Choose the Certificates button or click the Upload and Delete Certificates link.
2. Select the certificate you want to remove and choose Delete Selected.
3. Upload another certificate, or close the Certificates window.

Related Information
Creating Destinations (Cockpit) [page 303]
Importing Destinations (Cockpit) [page 311]
Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.7 Importing Destinations (Cockpit)

Prerequisites
You have previously created a connectivity destination (HTTP, Mail or RFC).

Note
The Destinations editor allows importing destination files with extension .props, .properties, .jks,
and .txt, as well as files with no extension. Destination files must be encoded in ISO 8859-1 character
encoding.

Procedure
1. Log into the cockpit and open the Destinations editor.
2. Choose Import from File.
3. Browse to a configuration file that contains destination configuration.
If the configuration file contains valid data, it is displayed in the Destinations editor with no errors. The
Save button is enabled so that you can successfully save the imported destination.
If the configuration file contains invalid properties or values, under the relevant fields in the Destinations
editor are displayed error messages in red which prompt you to correct them accordingly.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

311

Related Information
Examples (Cockpit) [page 313]
Editing and Deleting Destinations (Cockpit) [page 309]

1.4.1.1.2.3.8 Exporting Destinations (Cockpit)

Prerequisites
You have created a connectivity destination (HTTP, Mail or RFC) in the Destinations editor.

Procedure
1. Log into the cockpit and open the Destinations editor.
2. Select a destination and choose the

button.

3. Browse to the location on your local file system where you want to save the new destination.
If the destination does not contain client certificate authentication, it is saved as a single configuration file.
If the destination provides client certificate data, it is saved as an archive, which contains the main
configuration file and a JKS file.

Related Information
Examples (Cockpit) [page 313]
Editing and Deleting Destinations (Cockpit) [page 309]

312

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.2.3.9 Examples (Cockpit)

Example of HTTP Destination (Internet, Client Certificate Authentication)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

313

Example of HTTP Destination (Internet, OAuth2SAMLBearerAssertion)

314

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example of HTTP Destination (On-Premise)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

315

Example of Mail Destination

316

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example of RFC Destination

The following main properties correspond to the relevant additional properties:


User jco.client.user
Password jco.client.passwd
Repository password jco.destination.repository.passwd

Note
For security reasons, do not use these additional properties but use the corresponding main properties' fields.

Related Information
HTTP Destinations [page 322]
RFC Destinations [page 384]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

317

Mail Destinations [page 410]

1.4.1.1.3

Principal Propagation

Overview
The connectivity service provides a secure way of forwarding the identity of an on-demand user to the cloud
connector, and from there to the back end of the relevant on-premise system. This process is called principal
propagation. It uses SAML tokens as the exchange format for the user information. User mapping takes place in
the back end and, in this way, either the token is forwarded directly to the back end or an X.509 certificate is
generated, which is then used in the back end.

Restriction
This authentication is only applicable if you want to connect to your on-premise system via the cloud
connector.

How It Works
Table 209:
Process in Steps

Steps Description
1.

The user authenticates at the Web application front end via the IdP using a
standard SAML Web SSO profile. When the back-end connection is established
by the Web application, the destination service (re)uses the received SAML as
sertion to create the connection to the on-premise system.

2. The cloud connector validates the received SAML assertion for a second time,
extracts the attributes, and uses its STS component to issue a new token (an X.

509 certificate) with the same/similar attributes to assert the identity to the
back end.
3. The cloud connector and the Web application(s) share the same SP identity, that
is, the trust is only set up once in the IdP.

Using the PrincipalPropagation Property in Destinations


You can create and configure connectivity destinations making use of the PrincipalPropagation property in the
Eclipse IDE and in the cockpit. Bear in mind that this property is only available for destination configurations
created on the cloud.

318

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Creating and Deleting Destinations on the Cloud [page 292] (procedure and examples)
Creating Destinations (Cockpit) [page 303] (procedure and examples)

Tasks
Configuring Principal Propagation to an ABAP System for HTTPS [page 488]
Configuring Principal Propagation to an ABAP System for RFC [page 492]
Configuring Subject Pattern for Principal Propagation [page 494]

Related Information
Setting Up Trust [page 480]
Principal Propagation Authentication [page 328]

1.4.1.1.4

Exchanging Data via HTTP Protocol

Consuming Connectivity via HTTP


Call an Internet service using a simple application that queries some information from a public service:
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Consuming Internet Services (Java Web Tomcat 7) [page 355]
Call a service from a fenced customer network using a simple application that consumes an on-premise ping
service:
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Consuming Back-End Systems (Java Web Tomcat 7) [page 372]

Configuring Connectivity via HTTP


Configure an application using destinations:
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Console Client [page 283]
Configuring Destinations from the Cockpit [page 301]
Configure connectivity between a customer system and an on-demand application. You need to install the
cloud connector in your internal network and then configure it to expose an on-premise service. For more
information, see Installing the Cloud Connector [page 436].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

319

Connecting to On-Premise Back-End Services


You can consume on-premise back-end services in two ways via HTTP destinations and via the HTTP Proxy. For
more information, see:
HTTP Destinations [page 322]
HTTP Proxy for On-Premise Connectivity [page 336]

Connecting to a Local Host


To create a loopback connection, you can use the dedicated HTTP port bound to localhost. The port number can
be obtained from the cloud environment variable HC_LOCAL_HTTP_PORT.
For more information, see Using Cloud Environment Variables [page 970] section "List of Environment
Variables".

Note
Note that when deploying locally from the Eclipse IDE or the console client, the HTTP port may differ.

Related Information
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

1.4.1.1.4.1 DestinationFactory API

Overview
By default, all connectivity API packages are visible from all Web applications. In this classical case, applications
can consume the destinations via a JNDI lookup. For more information, see Connectivity and Destination APIs
[page 272].
There are specific cases though, when the destination names are not known in advance and cannot be defined in
the web.xml file. This is relevant to HTTP destinations and you need to use Destination Factory JNDI lookup
(com.sap.core.connectivity.api.DestinationFactory). To do this, follow the procedure below.

320

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Caution
If you use SDK for Java Web, we only recommend that you create a destination before deploying the
application.
If you use SDK for Java EE 6 Web Profile, you must create a destination before deploying the application.
If you use SDK for Java Web Tomcat 7, the DestinationFactory API is not supported. Instead, you can
use ConnectivityConfiguration API [page 275].

Tip
When you know in advance the names of all destinations you need, you should better use destinations.
Otherwise, we recommend using DestinationFactory.

Procedure
To look up the destination factory using JNDI, follow the steps:
1. Define a reference in the web.xml file:
<resource-ref>
<res-ref-name>connectivity/DestinationFactory</res-ref-name>
<res-type>com.sap.core.connectivity.api.DestinationFactory</res-type>
</resource-ref>
2. Use the following code in order to look it up:
import com.sap.core.connectivity.api.DestinationFactory;
import com.sap.core.connectivity.api.http.HttpDestination
...
Context ctx = new InitialContext();
DestinationFactory destinationFactory
=(DestinationFactory)ctx.lookup(DestinationFactory.JNDI_NAME);
HttpDestination destination = (HttpDestination)
destinationFactory.getDestination("myBackend");
3. With the retrieved HTTP destination, you can then, for example, send a simple GET request to the configured
remote system by using the following code:
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.HttpResponse;
...
// coding to call service "myService" on the system configured in the given
destination
HttpClient createHttpClient = destination.createHttpClient();
HttpGet get = new HttpGet("myService");
HttpResponse resp = createHttpClient.execute(get);

Related Information
Connectivity and Destination APIs [page 272]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

321

1.4.1.1.4.2 HTTP Destinations

Overview
The HTTP destinations provide data communication via HTTP protocol and is used for both Internet and onpremise connections.

HTTP Destination Properties


The runtime tries to resolve a destination in the order: Subscription Level Account Level Application Level. By
using the optional "DestinationProvider" property, a destination can be limited to application level only, that
is, the runtime tries to resolve the destination on application level.
Table 210:
Property

Description

DestinationProvider

Restricts destination to application level. If the property is


specified, the destination will be searched on the application
level only. By default, destinations are searched on all configu
ration levels.

Note
If you use Java Web Tomcat 7 runtime container, the DestinationProvider property is not supported.
Instead, you can use AuthenticationHeaderProvider API [page 277].

Example
Name=weather
Type=HTTP
Authentication=NoAuthentication
DestinationProvider=Application

Supported Proxy Types for Connectivity


The proxy types supported by SAP HANA Cloud connectivity service are:
Internet - The application can connect to an external REST or SOAP service on the Internet.
OnPremise - The application can connect to an on-premise back-end system through the cloud connector.
The proxy type used for a destination must be specified by the destination property ProxyType. The property's
default value (if not configured explicitly) is Internet.

322

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Setting Proxy Types for SAP HANA Cloud Local Runtime


If you work in your local development environment behind a proxy server and want to use a service from the
Internet, you need to configure your proxy settings on JVM level. To do this, proceed as follows:
1. On the Servers view, double-click the added server and choose Overview to open the editor.
2. Click the Open Launch Configuration link.
3. Choose the (x)=Arguments tab page.
4. In the VM Arguments box, add the following row:
-Dhttp.proxyHost=yourproxyHost -Dhttp.proxyPort=yourProxyPort Dhttps.proxyHost=yourproxyHost -Dhttps.proxyPort=yourProxyPort
5. Choose OK.
6. Start/restart your SAP HANA Cloud local runtime.
For more information and example, see Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page
348].

Setting Proxy Types for SAP HANA Cloud


When using the Internet proxy type, you do not need to perform any additional configuration steps.
When using the OnPremise proxy type, you configure the setting the standard way through the Connectivity
editor in the Eclipse IDE.
For more information and example, see Consuming Back-End Systems (Java Web or Java EE 6 Web Profile)
[page 362].

Configuring Authentication
When creating an HTTP destination, you can use different authentication types for access control::
Server Certificate Authentication [page 323]
SAP Assertion SSO Authentication [page 326]
Principal Propagation Authentication [page 328]
SAML Bearer Assertion Authentication [page 329]
Application-to-Application SSO Authentication [page 332]
Client Authentication Types for HTTP Destinations [page 334]

1.4.1.1.4.2.1 Server Certificate Authentication

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

323

Context
The server certificate authentication is applicable for all client authentication types, described below.

Properties

Table 211:
Property

Description

TrustStoreLocation

Path to the JKS file which contains trusted certificates (Certificate Authorities) for

1.

When used in local environment

2. When used in cloud environment

authentication against a remote client.


1.

The relative path to the JKS file. The root path is the server's location on the file
system.

2. The name of the JKS file.

Note
The default JDK truststore is appended to the truststore defined in the destina
tion configuration. As a result, the destination simultaneously uses both trust
stores. If the TrustStoreLocation property is not specified, the JDK trust
store is used as a default truststore for the destination.

TrustStorePassword

Password for the JKS trust store file. This property is mandatory in case
TrustStoreLocation is used.

TrustAll

If this property is set to TRUE in the destination, the server certificate will not be
checked for SSL connections. It is intended for test scenarios only, and should not
be used in production (since the SSL server certificate is not checked, the server is
not authenticated). The possible values are TRUE or FALSE; the default value is

FALSE (that is, if the property is not present at all).


In case TrustAll = TRUE, the TrustStoreLocation property is ignored so
you can omit it.
In case <TrustAll> = FALSE, the <TrustStoreLocation> property is manda
tory to be used.

324

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Property

Description

HostnameVerifier

Optional property. It has two values: Strict and BrowserCompatible. This


property specifies how the server hostname matches the names stored inside the
server's X.509 certificate. This verifying process is only applied if TLS or SSL proto
cols are used and is not applied if the TrustAll property is specified. The default
value (used if no value is explicitly specified) is Strict.

Strict HostnameVerifier works in the same way as Oracle Java 1.4,


Oracle Java 5, and Oracle Java 6-rc. It is also similar to Microsoft Internet Ex
plorer 6. This implementation appears to be compliant with RFC 2818 for deal
ing with wildcards. A wildcard such as "*.foo.com" matches only subdomains
at the same level, for example "a.foo.com". It does not match deeper subdo
mains such as "a.b.foo.com".

BrowserCompatible HostnameVerifier works in the same way as


Curl and Mozilla Firefox. The hostname must match either the first common
name (CN) or any of the subject-alts. A wildcard can occur in the CN and in any
of the subject-alts.

The only difference between BrowserCompatible and Strict is that a wild


card (such as ".foo.com") with BrowserCompatible matches all subdomains,
including "a.b.foo.com".
For more information about these Java classes, see Package
org.apache.http.conn.ssl

In case <TrustAll> = TRUE, the <HostnameVerifier> property is ignored so


you can omit it.

Note
You can upload TrustStore JKS files using the same command for uploading destination configuration property
file - you only need to specify the JKS file instead of the destination configuration file.

Note
Connections to remote services which require Java Cryptography Extension (JCE) unlimited strength
jurisdiction policy are not supported.

Configuration
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Console Client [page 283]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

325

Related Information
Client Authentication Types for HTTP Destinations [page 334]

1.4.1.1.4.2.2 SAP Assertion SSO Authentication

Context
By default, all SAP systems accept SAP assertion tickets for user propagation.

Note
The SAP assertion ticket is a special type of logon ticket. For more information, see SAP Logon Tickets and
Logon Using Tickets.
The aim of the SAPAssertionSSO destination is to generate such an assertion ticket in order to propagate the
currently logged-on SAP HANA Cloud Platform user to an SAP back-end system. You can only use this
authentication type if the user IDs on both sides are the same. The following diagram shows the elements of the
configuration process on the SAP HANA Cloud Platform and in the corresponding back-end system:

326

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Configuration Steps
1. Configure the back-end system so that it can accept SAP assertion tickets signed by a trusted x.509 key pair.
For more information, see Configuring a Trust Relationship for SAP Assertion Tickets.
2. Create and configure a SAPAssertionSSO destination by using the properties listed below, and deploy it on
SAP HANA Cloud Platform.
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

Note
Configuring SAPAssertionSSO destinations from the Eclipse IDE is not yet supported.

Properties
The following credentials need to be specified:
Property

Description

Name

Destination name. It must be the same as the destination


name you use for the configuration tools, that is, the console
client and Destinations editor (cockpit).

Type

Destination type. Use HTTP for all HTTP(S) destination.

URL

URL of the protected resource on the called application

Authentication

Authentication type. Use SAPAssertionSSO as a value.

IssuerSID

This system ID should be trusted by the back-end system.

IssuerClient

This client ID should be trusted by the back-end system.

RecipientSID

System ID (SID) of the back-end system

RecipientClient

Client ID of the back-end system

Certificate

A base64 encoded certificate that is trusted by the SAP


system

SigningKey

A base64 encoded signing/private key that is trusted by the


SAP system

SystemUser

Optional property.

If specified, all SAP assertion tickets are generated with


the specified user ID.

If not specified, all SAP assertion tickets are sent on


behalf of the currently logged-on user.

Thus, if the current user needs to be propagated, do not use


this property.

ProxyType

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can use both proxy types Internet and OnPremise.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

327

Example
Name=weather
Type=HTTP
Authentication=SAPAssertionSSO
IssuerSID=JAV
IssuerClient=000
RecipientSID=SAP
RecipientClient=100
Certificate=MIICiDCCAkegAwI...rvHTQ\=\=
SigningKey=MIIBSwIB...RuqNKGA\=

1.4.1.1.4.2.3 Principal Propagation Authentication

Context
The aim of the PrincipalPropagation destination is to forward the identity of an on-demand user to the cloud
connector, and from there to the back-end of the relevant on-premise system. In this way, the on-demand user
will no longer need to provide his/her identity every time he/she makes a connection to an on-premise system via
the same cloud connector.

Configuration Steps
You can create and configure a PrincipalPropagation destination by using the properties listed below, and deploy it
on SAP HANA Cloud Platform. For more information, see:
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Console Client [page 283]

Note
This property is only available for destination configurations created on the cloud.

328

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Properties
The following credentials need to be specified:
Property

Description

Name

Destination name. It must be the same as the destination


name you use in the configuration tools, that is, Connectivity
editor (Eclipse IDE), Destinations editor (cockpit), and the
console client.

Type

Destination type. Use HTTP for all HTTP(S) destinations.

URL

Virtual URL of the protected on-premise application.

Authentication

Authentication type. Use PrincipalPropagation as a


value.

ProxyType

You can only use proxy type OnPremise.

Example
Name=OnPremiseDestination
Type=HTTP
URL= http://virtualhost:80
Authentication=PrincipalPropagation
ProxyType=OnPremise

Related Information
Principal Propagation [page 318]

1.4.1.1.4.2.4 SAML Bearer Assertion Authentication

Context
SAP HANA Cloud Platform provides support for applications to use the SAML Bearer assertion flow for
consuming OAuth-protected resources. In this way, applications do not need to deal with some of the
complexities of OAuth and can reuse existing identity providers for user data. Users are authenticated by using
SAML against the configured trusted identity providers. The SAML assertion is then used to request an access
token from an OAuth authorization server. This access token is automatically injected in all HTTP requests to the
OAuth-protected resources.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

329

Tip
he access tokens are auto-renovated. When a token is about to expire, a new token is created shortly before
the expiration of the old one.

Configuration Steps
You can create and configure an OAuth2SAMLBearerAssertion destination by using the properties listed below,
and deploy it on SAP HANA Cloud Platform. For more information, see:
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

Note
Configuring OAuth2SAMLBearerAssertion destinations from the Eclipse IDE is not yet supported.

Properties
The table below lists the destination properties needed for OAuth2SAMLBearerAssertion authentication type. The
values for these properties should be found in the documentation of the particular provider of OAuth-protected
services. Usually, only a subset of the optional properties are required by a particular service provider.
Table 212:
Property

Description

Required

Name

Destination name. It must be the same as the destination


name you use for the configuration tools, that is, the console
client and Destinations editor (cockpit).

Type

Destination type. Use HTTP as a value for all HTTP(S) desti


nations.
URL of the protected resource on the called application

URL
ProxyType

You can only use proxy type Internet. Authentication type


OAuth2SAMLBearerAssertion is not supported with proxy
type OnPremise.

Authentication

Authentication type. Use OAuth2SAMLBearerAssertion


as a value.

audience

Intended audience for the assertion, which will be verified by


the OAuth authorization server

clientKey

Key that identifies the consumer to the authorization server

tokenServiceURL

URL of the OAuth server

330

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Property

Description

tokenServiceUser

User for basic authentication to OAuth server (if required)

tokenServicePassword

Password for tokenServiceUser (if required)

Additional

SystemUser

User to be used when requesting access token from the


OAuth authorization server. If this property is not specified,
the currently logged-in user will be used.

nameQualifier

Security domain of the user for which access token will be re


quested

companyId

Company identifier

assertionIssuer

Issuer of the SAML assertion

authnContextClassRef

Value of the AuthnContextClassRef tag, which is part of


generated OAuth2SAMLBearerAssertion authentica
tion. For more information, see SAML 2.0 specification

nameIdFormat

Value of the NameIdFormat tag, which is part of generated

OAuth2SAMLBearerAssertion authentication. For


more information, see SAML 2.0 specification

userIdSource

When this property is set, the generated SAML2 assertion


uses the currently logged-in user as a value for the NameId
tag.

Note
When the OAuth authorization server is called, it accepts the trust settings of the destination. For more
information, see Server Certificate Authentication [page 323].

Example
The connectivity destination below provides HTTP access to the OData API of SuccessFactors Jam.
URL=https://demo.sapjam.com/OData/OData.svc
Name=sap_jam_odata
TrustAll=true
ProxyType=Internet
Type=HTTP
Authentication=OAuth2SAMLBearerAssertion
tokenServiceURL=https://demo.sapjam.com/api/v1/auth/token
clientKey=Aa1Bb2Cc3DdEe4F5GHIJ
audience=cubetree.com
nameQualifier=www.successfactors.com

Related Information
Creating HTTP Destinations [page 304]
Examples (Cockpit) [page 313]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

331

1.4.1.1.4.2.5 Application-to-Application SSO Authentication

Context
The AppToAppSSO destinations are used in scenario of application-to-application communication where the
caller needs to propagate its logged in user. Both applications are deployed on SAP HANA Cloud Platform.

Configuration Steps
1. Configure your account to allow principal propagation. For more information, see ID Federation with the
Corporate Identity Provider [page 1292] section "Specifying Custom Local Provider Settings".

Note
This setting is done per account, which means that once set to Enabled all applications within the account
will accept user propagation.
2. Create and configure an AppToAppSSO destination by using the properties listed below, and deploy it on SAP
HANA Cloud Platform. For more information, see:
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

Note
Configuring AppToAppSSO destinations from the Eclipse IDE is not yet supported.

Properties
The following credentials need to be specified:
Table 213:
Property

Description

Name

Destination name. It must be the same as the destination


name you use for the configuration tools, that is, the console
client and Destinations editor (cockpit).

Type

Destination type. Use HTTP as a value for all HTTP(S) desti


nations.

Authentication

Authentication type. Use AppToAppSSO as a value.

URL

URL of the protected resource on the called application

332

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Property

Description

SessionCookieNames

Optional.
The AppToApp authentication module will use it to recognize
the user session which improves the performance of the
HTTP client.

Note
In case that a session cookie name has a variable part you
can specify it as a regular expression.
You can specify more than one session cookie name as
comma separated list:
Example:

JSESSIONID, JTENANTSESSIONID_.*,
CookieName, Cookie*Name, CookieName.*

Note
The spaces after comma are optional.
If several cookies are listed, the session is recognized as soon
as all of them are available in the response from the server.

Note
Recommended value for the target Java app on HCP is:

JTENANTSESSIONID_.*, and for the HANA XS app is:


xsId.*.
saml2_audience

Specifies a local SAML 2.0 provider name of the account


which consumes the target application.

Note
If not specified, both applications must be consumed in the
same account.

Example
#
#Wed Jan 13 12:25:47 UTC 2016
Name=apptapp
URL=https://someurl.com
ProxyType=Internet
Type=HTTP
SessionCookieNames=JTENANTSESSIONID_.*
Authentication=AppToAppSSO

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

333

Related Information
Server Certificate Authentication [page 323]
HTTP Proxy for On-Premise Connectivity [page 336]
AuthenticationHeaderProvider API [page 277]

1.4.1.1.4.2.6 Client Authentication Types for HTTP


Destinations

Context
This section lists the supported client authentication types and the relevant supported properties.

No Authentication
This is used for destinations that refer to a service on the Internet or an on-premise system that does not require
authentication. The relevant property value is:
Table 214:

Authentication=NoAuthentication

Note
When a destination is using HTTPS protocol to connect to a Web resource, the JDK truststore is used as
truststore for the destination.

Basic Authentication
This is used for destinations that refer to a service on the Internet or an on-premise system that requires basic
authentication. The relevant property value is:
Table 215:

Authentication=BasicAuthentication
The following credentials need to be specified:

334

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 216:
Property

Description

User

User name

Password

Password

Preemptive

If this property is not set or is set to TRUE (that is, the default behavior is to use
preemptive sending), the authentication token is sent preemptively. Otherwise, it
relies on the challenge from the server (401 HTTP code). The default value (used if
no value is explicitly specified) is TRUE. For more information about preemptive
ness, see http://tools.ietf.org/html/rfc2617#section-3.3

Note
When a destination is using HTTPS protocol to connect to a Web resource, the JDK truststore is used as
truststore for the destination.

Client Certificate Authentication


This is used for destinations that refer to a service on the Internet. The relevant property value is:
Table 217:

Authentication=ClientCertificateAuthentication
The following credentials need to be specified:
Table 218:
Property

Description

KeyStoreLocation

Path to the JKS file that contains the client certificate(s) for authentication against

1.

When used in local environment

2. When used in cloud environment

a remote server.
1.

The relative path to the JKS file. The root path is the server's location on the file
system.

2. The name of the JKS file.

KeyStorePassword

The password for the key storage. This property is mandatory in case

KeyStoreLocation is used.

Note
You can upload KeyStore JKS files using the same command for uploading destination configuration property
file - you only need to specify the JKS file instead of the destination configuration file.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

335

Configuration
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Console Client [page 283]

Related Information
Server Certificate Authentication [page 323]

1.4.1.1.4.3 HTTP Proxy for On-Premise Connectivity

Overview
Connectivity service provides a standard HTTP Proxy for on-premise connectivity to be accessible by any
application. Proxy host and port are available as the environment variables HC_OP_HTTP_PROXY_HOST and
HC_OP_HTTP_PROXY_PORT.

Note
The HTTP Proxy provides a more flexible way to use on-premise connectivity via standard HTTP clients. It
is not suitable for other protocols, such as RFC or Mail. HTTPS requests will not work as well.
The previous alternative, that is, using on-premise connectivity via existing HTTP Destination API, is still
supported. For more information, see DestinationFactory API [page 320].

Multitenancy Support
By default, all applications are started in multitenant mode. Such applications are responsible to propagate
consumer accounts to the HTTP Proxy, using header SAP-Connectivity-ConsumerAccount. This header is
mandatory during the first request of each HTTP connection. HTTP connections are associated with one
consumer account and cannot be used with another account.. If the SAP-Connectivity-ConsumerAccount
header is sent after the first request, and its value is different than the value in the first request, the Proxy will
return HTTP response code 400.
If an application VM is started for one consumer account, this account is known by the HTTP Proxy and the
application may not send the SAP-Connectivity-ConsumerAccount header.

336

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Using the Proxy on Multi-Tenant VMs


On multitenant VMs, applications are responsible to propagate consumer account via SAP-ConnectivityConsumerAccount header. The following example shows how this can be performed.
// TenantContex instance injection. It is used to get the consumer account name.
@Resource
public TenantContext tenantContext;
...
String proxyHost = System.getenv("HC_OP_HTTP_PROXY_HOST");
int proxyPort = Integer.parseInt(System.getenv("HC_OP_HTTP_PROXY_PORT"));
// set up the on-premise HTTP Proxy
HttpClient httpClient = new DefaultHttpClient();
httpClient.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY, new
HttpHost(proxyHost, proxyPort));
// insert the necessary headers in the request
HttpGet request = new HttpGet("http://virtualhost:1234");
request.addHeader("SAP-Connectivity-ConsumerAccount",
tenantContext.getTenant().getAccount().getId());
// execute the request
HttpResponse response = httpClient.execute(request);

Using the Proxy on Single-Tenant VMs


On single-tenant VMs, the consumer account is known and account propagation via header is not needed. The
following example demonstrates this case.
String proxyHost = System.getenv("HC_OP_HTTP_PROXY_HOST");
int proxyPort = Integer.parseInt(System.getenv("HC_OP_HTTP_PROXY_PORT"));
// create HTTP client and insert the necessary headers in the request
HttpClient httpClient = new DefaultHttpClient();
httpClient.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY, new
HttpHost(proxyHost, proxyPort));
HttpGet request = new HttpGet("http://virtualhost:1234");
// execute the request
HttpResponse response = httpClient.execute(request);

Related Information
Connectivity and Destination APIs [page 272]
Principal Propagation Using HTTP Proxy [page 338]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

337

1.4.1.1.4.3.1 Principal Propagation Using HTTP Proxy

Context
The HTTP Proxy can forward the identity of an on-demand user to the cloud connector, and from there to the
back-end of the relevant on-premise system. In this way, on-demand users will no longer need to provide their
identity every time they make connections to on-premise systems via one and the same cloud connector. To
propagate the logged-in user, an application must use the AuthenticationHeaderProvider API to generate a
header, which then embeds in the HTTP request to the on-premise system.

Restrictions
IDPs used by applications protected by SAML2 have to be denoted as trustworthy for the cloud connector.
Non-SAML2 protected applications have to be denoted themselves as trustworthy for the cloud connector.

Example

String proxyHost = System.getenv("HC_OP_HTTP_PROXY_HOST");


int proxyPort = Integer.parseInt(System.getenv("HC_OP_HTTP_PROXY_PORT"));
String account = System.getenv("HC_ACCOUNT");
// setup the on-premise HTTP proxy
HttpClient httpClient = new DefaultHttpClient();
httpClient.getParams().setParameter(ConnRoutePNames.DEFAULT_PROXY, new
HttpHost(proxyHost, proxyPort));
// look up the connectivity authentication header provider resource called
"authHeaderProvider" (must be defined in web.xml)
Context ctx = new InitialContext();
AuthenticationHeaderProvider authHeaderProvider = (AuthenticationHeaderProvider)
ctx.lookup("java:comp/env/authHeaderProvider");
// get header for principal propagation
AuthenticationHeader principalPropagationHeader =
authHeaderProvider.getPrincipalPropagationHeader();
//insert the necessary headers in the request
HttpGet request = new HttpGet("http://virtualhost:1234");
request.addHeader(principalPropagationHeader.getName(),
principalPropagationHeader.getValue());
request.addHeader("SAP-Connectivity-ConsumerAccount", account);
// execute the request
HttpResponse response = httpClient.execute(request);

338

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
You can also apply dependency injection by using the @Resource annotation.

Related Information
AuthenticationHeaderProvider API [page 277]
HTTP Proxy for On-Premise Connectivity [page 336]

1.4.1.1.4.4 Configuring the Cloud Connector for HTTP

Overview
This section helps you to configure your cloud connector when you are working via the HTTP protocol.

Related Information
Initial Configuration (HTTP) [page 339]
Configuring Access Control (HTTP) [page 341]

1.4.1.1.4.4.1 Initial Configuration (HTTP)

Installation of a System Certificate for Mutual Authentication


In order to setup a mutual authentication between the cloud connector and any back-end system it connects to,
you can import an X.509 client certificate into the cloud connector. The cloud connector will then use the socalled "system certificate" for all HTTPS requests to back-ends that request or require a client certificate. This
means, that the CA, which signed the cloud connector's client certificate, needs to be trusted by all back-end
systems to which the cloud connector is supposed to connect.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

339

This system certificate needs to be provided as PKCS#12 file containing the client certificate, the corresponding
private key and the CA root certificate that signed the client certificate (plus potentially the certificates of any
intermediate CAs, if the certificate chain is longer than 2). Via the file upload dialog, this PKCS#12 file can be
chosen from the file system, and its password also needs to be supplied for the import process.
As of version 2.6.0, there is a second option - starting a Certificate Signing Request procedure, similar to
the UI certificate described in Exchanging UI Certificates [page 456].

340

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If a system certificate has been imported successfully, its distinguished name, the name of the issuer, and the
validity dates are displayed:

If a system certificate is no longer required it can be deleted. To do this, use the respective button and confirm
deletion. If you need the public key for establishing trust with a server, you can simply export the full chain via the
Export button.

Related Information
Configuring Access Control (HTTP) [page 341]

1.4.1.1.4.4.2 Configuring Access Control (HTTP)


Exposing Intranet Systems
To allow your on-demand applications to access a certain back-end system on the intranet, you need to insert an
extra line into the cloud connector access control management.
1. Go to the Access Control tab page.
2. Choose Add. A wizard will open and ask for the required values.
3. Back-end Type: Select the description that best matches the addressed back-end system. This is important
mainly for metering information: tunnel connections to any kind of SAP system are free of charge, while using

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

341

the tunnel for connecting to a non-SAP system costs a fee. Furthermore, it will define, which steps the wizard
will offer and which values are possible.

4. Protocol: This field allows you to decide whether the cloud connector should use HTTP or HTTPS for the
connection to the back-end system. Note that this is completely independent from the setting on cloud side.
Thus, even if the HTTP destination on cloud side specifies "http://" in its URL, you can select HTTPS. This
way, you are ensured that the entire connection from the on-demand application to the actual back-end
system (provided through the SSL tunnel) is SSL-encrypted. The only prerequisite is that the back-end
system supports HTTPS on that port. For more information, see Initial Configuration (HTTP) [page 339].
If you specify HTTPS and there is a "system certificate" imported in the cloud connector, the latter
attempts to use that certificate for performing a client-certificate-based login to the back-end system.
If there is no system certificate imported, the cloud connector opens an HTTPS connection without client
certificate.

5. Internal Host and Internal Port specify the actual host and port under which the target system can be reached
within the intranet. It needs to be an existing network address that can be resolved on the intranet and has
network visibility for the cloud connector without any proxy. cloud connector will try to forward the request to
the network address specified by the internal host and port, so this address needs to be real.

342

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Virtual Host specifies the host name exactly as it is specified as the URL property in the HTTP destination
configuration in SAP HANA Cloud Platform. The virtual host can be a fake name and does not need to exist.
The Virtual Port allows you to distinguish between different entry points of your back-end system, for
example, HTTP/80 and HTTPS/443, and have different sets of access control settings for them. For example,
some non-critical resources may be accessed by HTTP, while some other critical resources are to be called
using HTTPS only. The fields will be pre-populated with the values of the Internal Host and Internal Port. In
case you don't modify them, you will need to provide your internal host and port also in the cloud side
destination configuration or in the URL used for your favorite HTTP client.

7. Principal Type defines what kind of principal is used when configuring a destination on the cloud side using
this system mapping with authentication type Principal Propagation. Regardless of what you choose,
you need to make sure that the general configuration for the principal type has been done to make it work
correctly. For destinations using different authentication types, this setting is ignored. If you choose None as
principal type, it is not possible to use principal propagation to this system.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

343

8. You can enter an optional description at this stage. The respective description will be shown as a rich tooltip
when the mouse hovers over the entries of the virtual host column (table Mapping Virtual to Internal System).

9. The summary shows information about the system to be stored and when saving the host mapping, you can
trigger a ping from the cloud connector to the internal host, using the Check availability of internal host check
box. This allows you to make sure the cloud connector can indeed access the internal system, and allows you
to catch basic things, such as spelling mistakes or firewall problems between the cloud connector and the
internal host. If the ping to the internal host is successful, the cloud connector saves the mapping without any
remark. If it fails, a warning will pop up, that the host is not reachable. Details for the reason are available in
the log files. You can execute such a check at any time later for all selected systems in the Access Control
overview.

10. Optional: You can later edit such a system mapping (via Edit) to make the cloud connector route the requests
for sales-system.cloud:443 to a different back-end system. This can be useful if the system is currently
down and there is a back-up system that can serve these requests in the meantime. However, you cannot edit
the virtual name of this system mapping. If you want to use a different fictional host name in your on-demand
application, you will need to delete the mapping and create a new one.

344

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Limiting the Accessible Services for HTTP(S)


In addition to allowing access to a particular host and port, you also need to specify which URL paths (Resources)
are allowed to be invoked on that host. The cloud connector uses very strict white-lists for its access control, so
only those URLs for which you explicitly granted access are allowed. All other HTTP(S) requests are denied by the
cloud connector.
To define the permitted URLs (Resources) for a particular back-end system, choose the line corresponding to that
back-end system. A dialog appears prompting you to enter the specific URL path that you want to allow to be
invoked.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

345

The cloud connector checks that the path part of the URL (up to but not including a possible question mark (?)
that may denote the start of optional CGI-style query parameters) is exactly as specified in the configuration. If it
is not, the request is denied. If you select option Path and all sub-paths, the cloud connector allows all requests for
which the URL path (not considering any query parameters) begins with the specified string.
The Enabled checkbox allows you to specify, whether that resource shall initially be enabled or disabled. (See the
following section for an explanation of enabled/disabled resources.)

Enabling/Disabling Resources On-the-Fly


In some cases, it is useful for testing purposes to temporarily disable certain resources without having to delete
them from the configuration. This allows you to easily re-provide access to these resources at a later point of time
without having to type in everything once again.
To disable a resource, select it and choose the Disable button:
The traffic light turns red, and from now on, the cloud connector will deny all requests coming in for this
resource.

The traffic light turns red, and from now on, the cloud connector will deny all requests coming in for this
resource. To enable the resource again, select it and choose the Enable button.

346

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

It is also possible to mark multiple lines and then to disable/enable all of them in one go by clicking the
Enable/Disable buttons in the top row.
Examples:
/production/accounting and Path only (sub-paths are excluded) are selected. Only requests of the form
GET /production/accounting or GET /production/accounting?name1=value1&name2=value2...
are allowed. (GET can also be replaced by POST, PUT, DELETE, and so on.)
/production/accounting and Path and all sub-paths are selected. All requests of the form GET /
production/accounting-plus-some-more-stuff-here?name1=value1... are allowed.
/ and Path and all sub-paths are selected. All requests to this server are allowed.

Related Information
Configuring Domain Mappings for Cookies [page 468]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]

1.4.1.1.4.5 Tutorials

Overview
SAP HANA Cloud connectivity service allows a secure, reliable, and easy-to-consume access to remote services
running either on the Internet or in an on-premise network.

Use Cases
The tutorials in this section show how you can make connections to Internet services and on-premise networks:
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

347

1.4.1.1.4.5.1 Consuming Internet Services (Java Web or Java EE


6 Web Profile)
Context
This step-by-step tutorial demonstrates consumption of Internet services using Apache HTTP Client . The
tutorial also shows how a connectivity-enabled Web application can be deployed on a local server and on the
cloud.
The servlet code, the web.xml content, and the destination file (outbound-internet-destination) used in
this tutorial are mapped to the connectivity sample project located in <SDK_location>/samples/
connectivity. You can directly import this sample in your Eclipse IDE. For more information, see Importing
Samples as Eclipse Projects [page 53].
Go through the relevant steps:
1. Create a Dynamic Web Project [page 401]
2. Create a Sample Servlet [page 402]
3. Test the Connectivity-Enabled Web Application Locally [page 352]
4. Deploy the Connectivity-Enabled Web Application on the Cloud [page 353]

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install SDK for Java Web or SDK for Java EE 6 Web Profile.

1. Create a Dynamic Web Project


1. Open the Java EE perspective of the Eclipse IDE.
2. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter ConnectivityHelloWorld .


4. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, we
choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

348

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Create a Sample Servlet


1. From the ConnectivityHelloWorld context menu, choose

New

Servlet .

2. Enter hello as the Java package and ConnectivityServlet as the Class name and choose Next.
3. In the URL mappings field, select /ConnectivityServlet and choose Edit.
4. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

349

5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to

ConnectivityHelloWorld

WebContent

WEB-INF

and open the web.xml file.

7. Choose the Source tab page.


8. Add the following code block to the <web-app> element:
<resource-ref>
<res-ref-name>outbound-internet-destination</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>

Note
The value of the <res-ref-name> element in the web.xml file should match the name of the destination
that you want to be retrieved at runtime. In this case, the destination name is outbound-internetdestination.
9. Replace the entire servlet class with the following one to make use of the destination API. The destination API
is visible by default for cloud applications and must not be added explicitly to the application class path.
package com.sap.cloud.sample.connectivity;
import java.io.IOException;
import java.io.InputStream;
import static java.net.HttpURLConnection.HTTP_OK;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.core.connectivity.api.http.HttpDestination;
/**
* Servlet class making HTTP calls to specified HTTP destinations.
* Destinations are used in the following exemplary connectivity scenarios:<br>
* - Connecting to an outbound Internet resource using HTTP destinations<br>
* - Connecting to an on-premise backend using on-premise HTTP destinations,<br>
*
where the destinations could have no authentication or basic
authentication.<br>
*
* * NOTE: The Connectivity service API is located under
* <code>com.sap.core.connectivity.api</code>. The old API under
* <code>com.sap.core.connectivity.httpdestination.api</code> has been
deprecated.
*/
public class ConnectivityServlet extends HttpServlet {
private static final long serialVersionUID = 1L;

350

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

private static final int COPY_CONTENT_BUFFER_SIZE = 1024;


private static final Logger LOGGER =
LoggerFactory.getLogger(ConnectivityServlet.class);
/** {@inheritDoc} */
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
HttpClient httpClient = null;
String destinationName = request.getParameter("destname");
try {
// Get HTTP destination
Context ctx = new InitialContext();
HttpDestination destination = null;
if (destinationName != null) {
DestinationFactory destinationFactory = (DestinationFactory)
ctx.lookup(DestinationFactory.JNDI_NAME);
destination = (HttpDestination)
destinationFactory.getDestination(destinationName);
} else {
// The default request to the Servlet will use outbound-internetdestination
destinationName = "outbound-internet-destination";
destination = (HttpDestination) ctx.lookup("java:comp/env/" +
destinationName);
}
// Create HTTP client
httpClient = destination.createHttpClient();
// Execute HTTP request
HttpGet httpGet = new HttpGet();
HttpResponse httpResponse = httpClient.execute(httpGet);
// Check response status code
int statusCode = httpResponse.getStatusLine().getStatusCode();
if (statusCode != HTTP_OK) {
throw new ServletException("Expected response status code is 200
but it is " + statusCode + " .");
}
// Copy content from the incoming response to the outgoing response
HttpEntity entity = httpResponse.getEntity();
if (entity != null) {
InputStream instream = entity.getContent();
try {
byte[] buffer = new byte[COPY_CONTENT_BUFFER_SIZE];
int len;
while ((len = instream.read(buffer)) != -1) {
response.getOutputStream().write(buffer, 0, len);
}
} catch (IOException e) {
// In case of an IOException the connection will be released
// back to the connection manager automatically
throw e;
} catch (RuntimeException e) {
// In case of an unexpected exception you may want to abort
// the HTTP request in order to shut down the underlying
// connection immediately.
httpGet.abort();
throw e;
} finally {
// Closing the input stream will trigger connection release
try {
instream.close();
} catch (Exception e) {
// Ignore
}
}
}
} catch (NamingException e) {
// Lookup of destination failed
String errorMessage = "Lookup of destination failed with reason: "

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

351

+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have the destination

"

+ destinationName + " configured.";


LOGGER.error("Lookup of destination failed", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);
} catch (Exception e) {
// Connectivity operation failed
String errorMessage = "Connectivity operation failed with reason: "
+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have an HTTP proxy
configured in your "
+ "local Eclipse environment in case your environment uses "
+ "an HTTP proxy for the outbound Internet "
+ "communication.";
LOGGER.error("Connectivity operation failed", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);
} finally {
// When HttpClient instance is no longer needed, shut down the
connection manager to ensure immediate
// deallocation of all system resources
if (httpClient != null) {
httpClient.getConnectionManager().shutdown();
}
}
}
}

Note
The given servlet can run with different destination scenarios, for which user should specify the destination
name as a requested parameter in the calling URL. In this case, the destination name should be
<applicationURL>/?destname=outbound-internet-destination. Nevertheless, your servlet can
still run even without specifying the destination name for this outbound scenario.
10. Save the Java editor and make sure the project compiles without errors.

3. Test the Connectivity-Enabled Web Application Locally


Caution
If you use SDK for Java Web, we only recommend that you create a destination before deploying the
application.
If you use SDK for Java EE 6 Web Profile, you must create a destination before deploying the application.
1. In the context menu of the Servers view, choose

New

Server .

2. Expand the SAP node, select Java Web Server and choose Finish.
3. A new server Java Web Server [Stopped, Synchronized] appears on the Servers tab page.
Also, a Servers folder is created and appears in the navigation tree of the IDE. It contains configurable folders
and files you can use, for example, to change your HTTP or JMX ports.
4. If you work behind a proxy server, you need to configure your proxy setting as follows:

352

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

In the Servers view, double-click the added server to open the editor.
Click the Open Launch Configuration link.
Choose the (x)=Arguments tab page.
In the VM Arguments box, add the following row:
-Dhttp.proxyHost=<your_proxy_host> -Dhttp.proxyPort=<your_proxy_port> Dhttps.proxyHost=<your_proxy_host> -Dhttps.proxyPort=<your_proxy_port>
Choose OK.
5. Go to the Connectivity tab page of your local server, create a destination with the name outboundinternet-destination, and configure it so it can be consumed by the application at runtime. For more
information, see Configuring Destinations from the Eclipse IDE [page 290].
For the sample destination to work properly, the following properties need to be configured:
Name=outbound-internet-destination
Type=HTTP
URL=http://sap.com/index.html
Authentication=NoAuthentication
6. From the ConnectivityServlet.java editor's context menu, choose

Run As

Run on Server .

7. Make sure that the Choose an existing server option is selected and choose Java Web Server.
8. Choose Finish.
The server is now started, displayed as Java Web Server [Started, Synchronized] in the Servers
view.
Result:
The internal Web browser opens with the expected output of the connectivity-enabled Web application.

4. Deploy the Connectivity-Enabled Web Application on the Cloud


1. In the context menu of the Servers view, choose

New

Server .

2. Choose SAP HANA Cloud Platform as the type of server you want to create and choose Next.
3. For Server's host name, specify the landscape host depending on your account type. For more information,
see Landscape Hosts [page 32].
4. Choose Next.
5. On the New Server wizard page, enter your application and account name. Note that only lowercase Latin
letters and digits are allowed.

Note
The application name should be unique enough to allow your deployed application to be easily identified in
SAP HANA Cloud Platform cockpit.
6. Enter your account name, e-mail or user name, and password.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

353

7. Choose Finish.
8. A new server <application>.<account> [Stopped]> appears in the Servers view.
9. Go to the Connectivity tab page of the server, create a destination with the name outbound-internetdestination, and configure it using the following properties:
Name=outbound-internet-destination
Type=HTTP
URL=http://sap.com/index.html
Authentication=NoAuthentication
ProxyType=Internet
10. From the ConnectivityServlet.java editor's context menu, choose

Run As

11. Make sure that the Choose an existing server option is selected and choose

Run on Server .
<Server_host_name>

<Server_name> .
12. Choose Finish.

354

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Result:
The internal Web browser opens with the URL pointing to SAP HANA Cloud Platform and displaying the expected
output of the connectivity-enabled Web application.

Next Step
You can monitor the state and logs of your Web application deployed on SAP HANA Cloud Platform.
For more information, see Using Logs in the Eclipse IDE [page 1131].

1.4.1.1.4.5.2 Consuming Internet Services (Java Web Tomcat 7)

Context
This step-by-step tutorial demonstrates consumption of Internet services using HttpURLConnection. The
tutorial also shows how a connectivity-enabled Web application can be deployed on a local server and on the
cloud.
The servlet code, the web.xml content, and the destination file (outbound-internet-destination) used in
this tutorial are mapped to the connectivity sample project located in <SDK_location>/samples/
connectivity. You can directly import this sample in your Eclipse IDE. For more information, see Importing
Samples as Eclipse Projects [page 53].
Go through the relevant steps:
1. Create a Dynamic Web Project [page 401]
2. Create a Sample Servlet [page 402]
3. Test the Connectivity-Enabled Web Application Locally [page 360]
4. Deploy the Connectivity-Enabled Web Application on the Cloud [page 360]

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install SDK for Java Web Tomcat 7.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

355

1. Create a Dynamic Web Project


1. Open the Java EE perspective of the Eclipse IDE.
2. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter ConnectivityHelloWorld .


4. In the Target Runtime pane, select Java Web Tomcat 7 as the runtime you want to use to deploy the
application.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

356

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Create a Sample Servlet

1. From the ConnectivityHelloWorld context menu, choose

New

Servlet .

2. Enter hello as the Java package and ConnectivityServlet as the Class name and choose Next.
3. In the URL mappings field, select /ConnectivityServlet and choose Edit.
4. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to

ConnectivityHelloWorld

WebContent

WEB-INF

and open the web.xml file.

7. Choose the Source tab page.


8. To consume connectivity configuration using JNDI, you need to define the ConnectivityConfiguration
API as a resource in the web.xml file. Below is an example of a ConnectivityConfiguration resource,
named connectivityConfiguration.
<resource-ref>
<res-ref-name>connectivityConfiguration</res-ref-name>
<restype>com.sap.core.connectivity.api.configuration.ConnectivityConfiguration</restype>
</resource-ref>
9. Replace the entire servlet class with the following one to make use of the destination API. The destination API
is visible by default for cloud applications and must not be added explicitly to the application class path.
package com.sap.cloud.sample.connectivity;
import
import
import
import
import
import
import

java.io.IOException;
java.io.InputStream;
java.io.OutputStream;
java.net.HttpURLConnection;
java.net.InetSocketAddress;
java.net.Proxy;
java.net.URL;

import
import
import
import
import
import
import

javax.annotation.Resource;
javax.naming.Context;
javax.naming.InitialContext;
javax.servlet.ServletException;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.cloud.account.TenantContext;
import com.sap.core.connectivity.api.configuration.ConnectivityConfiguration;
import com.sap.core.connectivity.api.configuration.DestinationConfiguration;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

357

/**
* Servlet class making http calls to specified http destinations.
* Destinations are used in the following example connectivity scenarios:<br>
* - Connecting to an outbound Internet resource using HTTP destinations<br>
* - Connecting to an on-premise backend using on premise HTTP destinations,<br>
*
where the destinations have no authentication.<br>
*/
public class ConnectivityServlet extends HttpServlet {
@Resource
private TenantContext tenantContext;
private static final long serialVersionUID = 1L;
private static final int COPY_CONTENT_BUFFER_SIZE = 1024;
private static final Logger LOGGER =
LoggerFactory.getLogger(ConnectivityServlet.class);
private static final String ON_PREMISE_PROXY = "OnPremise";
/** {@inheritDoc} */
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
HttpURLConnection urlConnection = null;
String destinationName = request.getParameter("destname");
// The default request to the Servlet will use outbound-internetdestination
if (destinationName == null) {
destinationName = "outbound-internet-destination";
}
try {
// Look up the connectivity configuration API
Context ctx = new InitialContext();
ConnectivityConfiguration configuration =
(ConnectivityConfiguration) ctx.lookup("java:comp/env/
connectivityConfiguration");
// Get destination configuration for "destinationName"
DestinationConfiguration destConfiguration =
configuration.getConfiguration(destinationName);
if (destConfiguration == null) {
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
String.format("Destination %s is not found. Hint: Make
sure to have the destination configured.", destinationName));
return;
}
// Get the destination URL
String value = destConfiguration.getProperty("URL");
URL url = new URL(value);
String proxyType = destConfiguration.getProperty("ProxyType");
Proxy proxy = getProxy(proxyType);
urlConnection = (HttpURLConnection) url.openConnection(proxy);
destinations

// Insert the required header in the request for on-premise


injectHeader(urlConnection, proxyType);

// Copy content from the incoming response to the outgoing response


InputStream instream = urlConnection.getInputStream();
OutputStream outstream = response.getOutputStream();
copyStream(instream, outstream);
} catch (Exception e) {
// Connectivity operation failed
String errorMessage = "Connectivity operation failed with reason: "

358

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have an HTTP proxy
configured in your "
+ "local environment in case your environment uses "
+ "an HTTP proxy for the outbound Internet "
+ "communication.";
LOGGER.error("Connectivity operation failed", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);
}
}
private Proxy getProxy(String proxyType) {
String proxyHost = null;
int proxyPort;
if (ON_PREMISE_PROXY.equals(proxyType)) {
// Get proxy for on-premise destinations
proxyHost = System.getenv("HC_OP_HTTP_PROXY_HOST");
proxyPort = Integer.parseInt(System.getenv("HC_OP_HTTP_PROXY_PORT"));
} else {
// Get proxy for internet destinations
proxyHost = System.getProperty("http.proxyHost");
proxyPort = Integer.parseInt(System.getProperty("http.proxyPort"));
}
return new Proxy(Proxy.Type.HTTP, new InetSocketAddress(proxyHost,
proxyPort));
}
{

private void injectHeader(HttpURLConnection urlConnection, String proxyType)

if (ON_PREMISE_PROXY.equals(proxyType)) {
// Insert header for on-premise connectivity with the consumer
account name
urlConnection.setRequestProperty("SAP-Connectivity-ConsumerAccount",
tenantContext.getAccountName());
}
}
private void copyStream(InputStream inStream, OutputStream outStream) throws
IOException {
byte[] buffer = new byte[COPY_CONTENT_BUFFER_SIZE];
int len;
while ((len = inStream.read(buffer)) != -1) {
outStream.write(buffer, 0, len);
}
}
}

Note
The given servlet can run with different destination scenarios, for which user should specify the destination
name as a requested parameter in the calling URL. In this case, the destination name should be
<applicationURL>/?destname=outbound-internet-destination. Nevertheless, your servlet can
still run even without specifying the destination name for this outbound scenario.
10. Save the Java editor and make sure the project compiles without errors.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

359

3. Test the Connectivity-Enabled Web Application Locally


Note
We recommend but not obligate that you create a destination before deploying the application.
1. In the context menu of the Servers view, choose

New

Server .

2. Expand the SAP node, select Java Web Tomcat 7 Server and choose Finish.
3. A new server Java Web Tomcat 7 Server [Stopped, Synchronized] appears on the Servers tab
page.
Also, a Servers folder is created and appears in the navigation tree of the IDE. It contains configurable folders
and files you can use, for example, to change your HTTP or JMX ports.
4. If you work behind a proxy server, you need to configure your proxy setting as follows:
In the Servers view, double-click the added server to open the editor.
Click the Open Launch Configuration link.
Choose the (x)=Arguments tab page.
In the VM Arguments box, add the following row:
-Dhttp.proxyHost=<your_proxy_host> -Dhttp.proxyPort=<your_proxy_port> Dhttps.proxyHost=<your_proxy_host> -Dhttps.proxyPort=<your_proxy_port>
Choose OK.
5. Go to the Connectivity tab page of your local server, create a destination with the name outboundinternet-destination, and configure it so it can be consumed by the application at runtime. For more
information, see Configuring Destinations from the Eclipse IDE [page 290].
For the sample destination to work properly, the following properties need to be configured:
Name=outbound-internet-destination
Type=HTTP
URL=http://sap.com/index.html
Authentication=NoAuthentication
6. From the ConnectivityServlet.java editor's context menu, choose

Run As

Run on Server .

7. Make sure that the Choose an existing server option is selected and choose Java Web Tomcat 7 Server.
8. Choose Finish.
The server is now started, displayed as Java Web Tomcat 7 Server [Started, Synchronized] in the
Servers view.
Result:
The internal Web browser opens with the expected output of the connectivity-enabled Web application.

4. Deploy the Connectivity-Enabled Web Application on the Cloud


1. In the context menu of the Servers view, choose

New

Server .

2. Choose SAP HANA Cloud Platform as the type of server you want to create and choose Next.
3. For Server's host name, specify the landscape host depending on your account type. For more information,
see Landscape Hosts [page 32].

360

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Choose Next.
5. On the New Server wizard page, enter your application and account name. Note that only lowercase Latin
letters and digits are allowed.

Note
The application name should be unique enough to allow your deployed application to be easily identified in
SAP HANA Cloud Platform cockpit.
6. Enter your account name, e-mail or user name, and password.

7. Choose Finish.
8. A new server <application>.<account> [Stopped]> appears in the Servers view.
9. Go to the Connectivity tab page of the server, create a destination with the name outbound-internetdestination, and configure it using the following properties:
Name=outbound-internet-destination

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

361

Type=HTTP
URL=http://sap.com/index.html
Authentication=NoAuthentication
ProxyType=Internet
10. From the ConnectivityServlet.java editor's context menu, choose

Run As

11. Make sure that the Choose an existing server option is selected and choose

Run on Server .
<Server_host_name>

<Server_name> .
12. Choose Finish.
Result:
The internal Web browser opens with the URL pointing to SAP HANA Cloud Platform and displaying the expected
output of the connectivity-enabled Web application.

Next Step
You can monitor the state and logs of your Web application deployed on SAP HANA Cloud Platform.
For more information, see Using Logs in the Eclipse IDE [page 1131].

1.4.1.1.4.5.3 Consuming Back-End Systems (Java Web or Java


EE 6 Web Profile)
Context
This step-by-step tutorial demonstrates how a sample Web application consumes a back-end system via HTTP(S)
by using SAP HANA Cloud Platform connectivity service. For simplicity, instead of using a real back-end system,
we use a second sample Web application containing BackendServlet, which mimics the back-end system and
can be called via HTTP(S).
The servlet code, the web.xml content, and the destination files (backend-no-auth-destination and
backend-basic-auth-destination) used in this tutorial are mapped to the connectivity sample project
located in <SDK_location>/samples/connectivity. You can directly import this sample in your Eclipse IDE.
For more information, see Importing Samples as Eclipse Projects [page 53].
The tutorial guides you through the following sections:
1. Set Up Application as a Back-End System [page 363]
2. Create a Dynamic Web Project [page 401]
3. Create a Sample Servlet [page 366]
4. Deploy the Application [page 404]
5. Configure the Destination in the Cloud [page 371]

362

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Connectivity User Roles


In the on-demand to on-premise connectivity end-to-end scenario, different user roles are involved. The particular
steps for the relevant roles are described below:
IT Administrator - Sets up and configures the cloud connector. Scenario steps:
1. Downloads the cloud connector from https://tools.hana.ondemand.com/#cloud
2. Installs the connector.
3. Establishes an SSL tunnel from the connector to an SAP HANA Cloud Platform account.
4. Configures the exposed back-end systems and resources.
Application Developer - Develops Web applications using destinations. Scenario steps:
1. Installs the Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
2. Develops a Java EE application using the destination API.
3. Configures connectivity destinations as resources in the web.xml file.
4. Configures connectivity destinations via the SAP HANA Cloud Platform server adapter in Eclipse IDE.
5. Deploys the Java EE application locally and on the cloud.
Account Operator - Deploys Web applications, configures their destinations, and conducts tests. Scenario
steps:
1. Obtains a ready Java EE application WAR file.
2. Deploys the Java EE application to an SAP HANA Cloud Platform account.
3. Uploads the connectivity destination configuration via the console client.
4. Tests the Java EE application on a local server and deploys it again to a SAP HANA Cloud Platform
account.
For more information, see SAP HANA Cloud Connector [page 434].

Prerequisites
You have downloaded and configured the cloud connector. For more information, see SAP HANA Cloud
Connector [page 434].
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install SDK for Java Web or SDK for Java EE 6 Web Profile.

1. Set Up Application as a Back-End System


This tutorial uses a Web application that responds to a request with a ping as a sample back-end system. The
connectivity service supports HTTP and HTTPS as protocols and provides an easy way to consume REST-based
Web services.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

363

To set up the sample application as a back-end system, see Setting Up an Application as a Sample Back-End
System [page 382].

Tip
Instead of the sample back-end system provided in this tutorial, you can use other systems to be consumed
through REST-based Web services.
Once the back-end application is running on your local Tomcat, you need to configure the ping service, provided
by the application, in your installed cloud connector. This is required since the cloud connector only allows access
to white-listed back-end services. To do this, follow the steps below:
1. Open the cloud connector and from the Content navigation (in left), choose Access Control.
2. Under Mapping Virtual To Internal System, choose the Add button and define an entry as shown on the
following screenshot. The Internal Host must be the physical host name of the machine on which the Tomcat
of the back-end application is running.

3. Choose Save. The newly mapped system appears in the table.


4. Click on it. A new table, Resources Accessible On <host>:<port>, opens below.
5. Specify the URL paths /BackendAppHttpBasicAuth and /BackendAppHttpNoAuth as accessible
resources, as shown on the screenshot below. When defining the paths, make sure you have selected the Path
and all sub-paths option.

364

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
In case you use SDK with version equal to or lower than 1.44.0.1 (Java Web) and 2.24.13 (Java EE 6
Web Profile), you should find the WAR files in directory <SDK_location>/tools/samples/
connectivity/onpremise, under the names PingAppHttpNoAuth.war and
PingAppHttpBasicAuth.war. Also, the URL paths should be /PingAppHttpBasicAuth and /
PingAppHttpNoAuth.

2. Create a Dynamic Web Project


1. Open the Java EE perspective of the Eclipse IDE.
2. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter ConnectivityHelloWorld .


4. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, we
choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

365

3. Create a Sample Servlet


1. From the ConnectivityHelloWorld context menu, choose

New

Servlet .

2. Enter hello as the Java package and ConnectivityServlet as the Class name and choose Next.
3. In the URL mappings field, select /ConnectivityServlet and choose Edit.
4. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

366

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to

ConnectivityHelloWorld

WebContent

WEB-INF

and open the web.xml file.

7. Add the following code block to the <web-app> element, respectively:


<resource-ref>
<res-ref-name>outbound-internet-destination</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>
<resource-ref>
<res-ref-name>connectivity/DestinationFactory</res-ref-name>
<res-type>com.sap.core.connectivity.api.DestinationFactory</res-type>
</resource-ref>

Note
Destinations backend-no-auth-destination and backend-basic-auth-destination will be
looked-up via DestinationFactory JNDI lookup. For more information, see DestinationFactory API [page
320].
In case you use destinations as resource reference, the value of the <res-ref-name> element in the
web.xml file should match the name of the destination that you want to be retrieved at runtime. In this
case, the destination name is outbound-internet-destination.
8. Replace the entire servlet class to make use of the destination API. The destination API is visible by default for
cloud applications and must not be added explicitly to the application class path.
package com.sap.cloud.sample.connectivity;
import java.io.IOException;
import java.io.InputStream;
import static java.net.HttpURLConnection.HTTP_OK;
import
import
import
import
import
import
import

javax.naming.Context;
javax.naming.InitialContext;
javax.naming.NamingException;
javax.servlet.ServletException;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;

import
import
import
import
import
import

org.apache.http.HttpEntity;
org.apache.http.HttpResponse;
org.apache.http.client.HttpClient;
org.apache.http.client.methods.HttpGet;
org.slf4j.Logger;
org.slf4j.LoggerFactory;

import com.sap.core.connectivity.api.http.HttpDestination;
import com.sap.core.connectivity.api.DestinationFactory;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

367

/**
* Servlet class making HTTP calls to specified HTTP destinations.
* Destinations are used in the following exemplary connectivity scenarios:<br>
* - Connecting to an outbound Internet resource using HTTP destinations<br>
* - Connecting to an on-premise backend using on-premise HTTP destinations,<br>
*
where the destinations could have no authentication or basic
authentication.<br>
*
* * NOTE: The Connectivity service API is located under
* <code>com.sap.core.connectivity.api</code>. The old API under
* <code>com.sap.core.connectivity.httpdestination.api</code> has been
deprecated.
*/
public class ConnectivityServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final int COPY_CONTENT_BUFFER_SIZE = 1024;
private static final Logger LOGGER =
LoggerFactory.getLogger(ConnectivityServlet.class);
/** {@inheritDoc} */
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
HttpClient httpClient = null;
String destinationName = request.getParameter("destname");
try {
// Get HTTP destination
Context ctx = new InitialContext();
HttpDestination destination = null;
if (destinationName != null) {
DestinationFactory destinationFactory = (DestinationFactory)
ctx.lookup(DestinationFactory.JNDI_NAME);
destination = (HttpDestination)
destinationFactory.getDestination(destinationName);
} else {
// The default request to the Servlet will use outbound-internetdestination
destinationName = "outbound-internet-destination";
destination = (HttpDestination) ctx.lookup("java:comp/env/" +
destinationName);
}
// Create HTTP client
httpClient = destination.createHttpClient();
// Execute HTTP request
HttpGet httpGet = new HttpGet();
HttpResponse httpResponse = httpClient.execute(httpGet);
// Check response status code
int statusCode = httpResponse.getStatusLine().getStatusCode();
if (statusCode != HTTP_OK) {
throw new ServletException("Expected response status code is 200
but it is " + statusCode + " .");
}
// Copy content from the incoming response to the outgoing response
HttpEntity entity = httpResponse.getEntity();
if (entity != null) {
InputStream instream = entity.getContent();
try {
byte[] buffer = new byte[COPY_CONTENT_BUFFER_SIZE];
int len;
while ((len = instream.read(buffer)) != -1) {
response.getOutputStream().write(buffer, 0, len);
}
} catch (IOException e) {
// In case of an IOException the connection will be released

368

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

// back to the connection manager automatically


throw e;
} catch (RuntimeException e) {
// In case of an unexpected exception you may want to abort
// the HTTP request in order to shut down the underlying
// connection immediately.
httpGet.abort();
throw e;
} finally {
// Closing the input stream will trigger connection release
try {
instream.close();
} catch (Exception e) {
// Ignore
}
}

}
} catch (NamingException e) {
// Lookup of destination failed
String errorMessage = "Lookup of destination failed with reason: "
+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have the destination

"

+ destinationName + " configured.";


LOGGER.error("Lookup of destination failed", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);
} catch (Exception e) {
// Connectivity operation failed
String errorMessage = "Connectivity operation failed with reason: "
+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have an HTTP proxy
configured in your "
+ "local Eclipse environment in case your environment uses "
+ "an HTTP proxy for the outbound Internet "
+ "communication.";
LOGGER.error("Connectivity operation failed", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);
} finally {
// When HttpClient instance is no longer needed, shut down the
connection manager to ensure immediate
// deallocation of all system resources
if (httpClient != null) {
httpClient.getConnectionManager().shutdown();
}
}
}
}

Note
The given servlet can be run with different destination scenarios, for which user should specify the
destination name as a requested parameter in the calling URL. In the case of on-premise connection to a
back-end system, the destination name should be either backend-basic-auth-destination or
backend-no-auth-destination, depending on the chosen authentication type scenario. For example:
<application_URL>/?destname=backend-no-auth-destination
9. Save the Java editor and make sure the project compiles without errors.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

369

4. Deploy the Application


Caution
If you use SDK for Java Web, we just recommend that you create a destination before starting the
application.
If you use SDK for Java EE 6 Web Profile, you must create a destination before starting the application.
1. To deploy your Web application locally or on the cloud, follow the steps described in the respective pages:
Deploying Locally from Eclipse IDE [page 975]
Deploying on the Cloud from Eclipse IDE [page 977]
2. Once the application is deployed successfully on a local server and on the cloud, the application issues an
exception saying that destination backend-basic-auth-destination or backend-no-authdestination has not been specified yet:
HTTP Status 500 - Connectivity operation failed with reason: Destination with
name backend-no-auth-destination cannot be found. Make sure it is created and
configured.. See logs for details.
2014 01 10 08:11:01#
+00#ERROR#com.sap.cloud.sample.connectivity.ConnectivityServlet##anonymous#httpbio-8041-exec-1##conngold#testsample#web#null#null#Connectivity operation failed
com.sap.core.connectivity.api.DestinationNotFoundException: Destination with
name backend-no-auth-destination cannot be found. Make sure it is created and
configured.
at
com.sap.core.connectivity.destinations.DestinationFactory.getDestination(Destinat
ionFactory.java:20)
at
com.sap.core.connectivity.cloud.destinations.CloudDestinationFactory.getDestinati
on(CloudDestinationFactory.java:28)
at
com.sap.cloud.sample.connectivity.ConnectivityServlet.doGet(ConnectivityServlet.j
ava:50)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:735)
at javax.servlet.http.HttpServlet.service(HttpServlet.java:848)
at
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilte
rChain.java:305)
at
org.apache.catalina.core.ApplicationFilterChain.doFilter(ApplicationFilterChain.j
ava:210)
at
com.sap.core.communication.server.CertValidatorFilter.doFilter(CertValidatorFilte
r.java:321)
at
org.apache.catalina.core.ApplicationFilterChain.internalDoFilter(ApplicationFilte
rChain.java:243)
...
3. As a next step, you need to configure backend-no-auth-destination or backend-basic-authdestination.
For more information, see DestinationFactory API [page 320].

370

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Configure the Destination in the Cloud


To configure the destination in SAP HANA Cloud Platform, you need to use the virtual host name
(virtualpingbackend) and port (1234) specified in one of the previous steps on the cloud connector's Access
Control tab page.

Note
On-premise destinations support HTTP connections only.
The connection from an application to the cloud connector (through the tunnel) is encrypted on TLS level.
Also, you can choose between using HTTP or HTTPS to hop from the cloud connector to the back end.
1. In the Eclipse IDE, open the Servers view and double-click on <application>.<account> to open the SAP
HANA Cloud Platform editor.
2. Open the Connectivity tab page.
3. In the All Destinations section, choose

to create a new destination with the name backend-no-auth-

destination or backend-basic-auth-destination.
To connect with no authentication, use the following configuration:
Name=backend-no-auth-destination
Type=HTTP
URL=http://virtualpingbackend:1234/BackendAppHttpNoAuth/noauth
Authentication=NoAuthentication
ProxyType=OnPremise
CloudConnectorVersion=2

To connect with basic authentication, use the following configuration:


Name=backend-basic-auth-destination
Type=HTTP
URL=http://virtualpingbackend:1234/BackendAppHttpBasicAuth/basic
Authentication=BasicAuthentication
User=pinguser
Password=pingpassword
ProxyType=OnPremise
CloudConnectorVersion=2

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

371

4. Save the destination.


5. The Connectivity editor automatically saves the configuration in SAP HANA Cloud Platform.
6. Call the URL that references the cloud application again in the Web browser. The application should now
return the ping response.

Next Step
You can monitor the state and logs of your Web application deployed on SAP HANA Cloud Platform.
For more information, see Using Logs in the Eclipse IDE [page 1131].

1.4.1.1.4.5.4 Consuming Back-End Systems (Java Web Tomcat


7)

Context
This step-by-step tutorial demonstrates how a sample Web application consumes a back-end system via HTTP(S)
by using SAP HANA Cloud Platform connectivity service. For simplicity, instead of using a real back-end system,
we use a second sample Web application containing BackendServlet, which mimics the back-end system and
can be called via HTTP(S).

372

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The servlet code, the web.xml content, and the destination file (backend-no-auth-destination) used in this
tutorial are mapped to the connectivity sample project located in <SDK_location>/samples/connectivity.
You can directly import this sample in your Eclipse IDE. For more information, see Importing Samples as Eclipse
Projects [page 53].
The tutorial guides you through the following sections:
1. Set Up Application as a Back-End System [page 374]
2. Create a Dynamic Web Project [page 401]
3. Create a Sample Servlet [page 376]
4. Deploy the Application [page 404]
5. Configure the Destination in the Cloud [page 380]

Connectivity User Roles


In the on-demand to on-premise connectivity end-to-end scenario, different user roles are involved. The particular
steps for the relevant roles are described below:
IT Administrator - Sets up and configures the cloud connector. Scenario steps:
1. Downloads the cloud connector from https://tools.hana.ondemand.com/#cloud
2. Installs the connector.
3. Establishes an SSL tunnel from the connector to an SAP HANA Cloud Platform account.
4. Configures the exposed back-end systems and resources.
Application Developer - Develops Web applications using destinations. Scenario steps:
1. Installs the Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
2. Develops a Java EE application using the destination API.
3. Configures connectivity destinations as resources in the web.xml file.
4. Configures connectivity destinations via the SAP HANA Cloud Platform server adapter in Eclipse IDE.
5. Deploys the Java EE application locally and on the cloud.
Account Operator - Deploys Web applications, configures their destinations, and conducts tests. Scenario
steps:
1. Obtains a ready Java EE application WAR file.
2. Deploys the Java EE application to an SAP HANA Cloud Platform account.
3. Uploads the connectivity destination configuration via the console client.
4. Tests the Java EE application on a local server and deploys it again to a SAP HANA Cloud Platform
account.
For more information, see SAP HANA Cloud Connector [page 434].

Prerequisites
You have downloaded and configured the cloud connector. For more information, see SAP HANA Cloud
Connector [page 434].
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

373

Note
You need to install SDK for Java Web Tomcat 7.

1. Set Up Application as a Back-End System


This tutorial uses a Web application that responds to a request with a ping as a sample back-end system. The
connectivity service supports HTTP and HTTPS as protocols and provides an easy way to consume REST-based
Web services.
To set up the sample application as a back-end system, see Setting Up an Application as a Sample Back-End
System [page 382].

Tip
Instead of the sample back-end system provided in this tutorial, you can use other systems to be consumed
through REST-based Web services.
Once the back-end application is running on your local Tomcat, you need to configure the ping service, provided
by the application, in your installed cloud connector. This is required since the cloud connector only allows access
to white-listed back-end services. To do this, follow the steps below:
1. Open the cloud connector and from the Content navigation (in left), choose Access Control.
2. Under Mapping Virtual To Internal System, choose the Add button and define an entry as shown on the
following screenshot. The Internal Host must be the physical host name of the machine on which the Tomcat
of the back-end application is running.

374

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Choose Save. The newly mapped system appears in the table.


4. Click on it. A new table, Resources Accessible On <host>:<port>, opens below.
5. Specify the URL paths /BackendAppHttpBasicAuth and /BackendAppHttpNoAuth as accessible
resources, as shown on the screenshot below. When defining the paths, make sure you have selected the Path
and all sub-paths option.

2. Create a Dynamic Web Project


1. Open the Java EE perspective of the Eclipse IDE.
2. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter ConnectivityHelloWorld .


4. In the Target Runtime pane, select Java Web Tomcat 7 as the runtime you want to use to deploy the
application.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

375

3. Create a Sample Servlet


1. From the ConnectivityHelloWorld context menu, choose

New

Servlet .

2. Enter hello as the Java package and ConnectivityServlet as the Class name and choose Next.
3. In the URL mappings field, select /ConnectivityServlet and choose Edit.
4. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

376

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to

ConnectivityHelloWorld

WebContent

WEB-INF

and open the web.xml file.

7. To consume connectivity configuration using JNDI, you need to define the ConnectivityConfiguration
API as a resource in the web.xml file. Below is an example of a ConnectivityConfiguration resource,
named connectivityConfiguration.
<resource-ref>
<res-ref-name>connectivityConfiguration</res-ref-name>
<restype>com.sap.core.connectivity.api.configuration.ConnectivityConfiguration</restype>
</resource-ref>

Note
Destination backend-no-auth-destination will be looked-up via ConnectivityConfiguration JNDI
lookup. For more information, see ConnectivityConfiguration API [page 275].
8. Replace the entire servlet class to make use of the configuration API. The configuration API is visible by
default for cloud applications and must not be added explicitly to the application class path.
package com.sap.cloud.sample.connectivity;
import
import
import
import
import
import
import

java.io.IOException;
java.io.InputStream;
java.io.OutputStream;
java.net.HttpURLConnection;
java.net.InetSocketAddress;
java.net.Proxy;
java.net.URL;

import
import
import
import
import
import
import

javax.annotation.Resource;
javax.naming.Context;
javax.naming.InitialContext;
javax.servlet.ServletException;
javax.servlet.http.HttpServlet;
javax.servlet.http.HttpServletRequest;
javax.servlet.http.HttpServletResponse;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.cloud.account.TenantContext;
import com.sap.core.connectivity.api.configuration.ConnectivityConfiguration;
import com.sap.core.connectivity.api.configuration.DestinationConfiguration;
/**
* Servlet class making http calls to specified http destinations.
* Destinations are used in the following example connectivity scenarios:<br>
* - Connecting to an outbound Internet resource using HTTP destinations<br>
* - Connecting to an on-premise backend using on premise HTTP destinations,<br>
*
where the destinations have no authentication.<br>
*/

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

377

public class ConnectivityServlet extends HttpServlet {


@Resource
private TenantContext tenantContext;
private static final long serialVersionUID = 1L;
private static final int COPY_CONTENT_BUFFER_SIZE = 1024;
private static final Logger LOGGER =
LoggerFactory.getLogger(ConnectivityServlet.class);
private static final String ON_PREMISE_PROXY = "OnPremise";
/** {@inheritDoc} */
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
HttpURLConnection urlConnection = null;
String destinationName = request.getParameter("destname");
// The default request to the Servlet will use outbound-internetdestination
if (destinationName == null) {
destinationName = "outbound-internet-destination";
}
try {
// Look up the connectivity configuration API
Context ctx = new InitialContext();
ConnectivityConfiguration configuration =
(ConnectivityConfiguration) ctx.lookup("java:comp/env/
connectivityConfiguration");
// Get destination configuration for "destinationName"
DestinationConfiguration destConfiguration =
configuration.getConfiguration(destinationName);
if (destConfiguration == null) {
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
String.format("Destination %s is not found. Hint: Make
sure to have the destination configured.", destinationName));
return;
}
// Get the destination URL
String value = destConfiguration.getProperty("URL");
URL url = new URL(value);
String proxyType = destConfiguration.getProperty("ProxyType");
Proxy proxy = getProxy(proxyType);
urlConnection = (HttpURLConnection) url.openConnection(proxy);
destinations

// Insert the required header in the request for on-premise


injectHeader(urlConnection, proxyType);

// Copy content from the incoming response to the outgoing response


InputStream instream = urlConnection.getInputStream();
OutputStream outstream = response.getOutputStream();
copyStream(instream, outstream);
} catch (Exception e) {
// Connectivity operation failed
String errorMessage = "Connectivity operation failed with reason: "
+ e.getMessage()
+ ". See "
+ "logs for details. Hint: Make sure to have an HTTP proxy
configured in your "
+ "local environment in case your environment uses "
+ "an HTTP proxy for the outbound Internet "
+ "communication.";

378

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

LOGGER.error("Connectivity operation failed", e);


response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
errorMessage);

private Proxy getProxy(String proxyType) {


String proxyHost = null;
int proxyPort;
if (ON_PREMISE_PROXY.equals(proxyType)) {
// Get proxy for on-premise destinations
proxyHost = System.getenv("HC_OP_HTTP_PROXY_HOST");
proxyPort = Integer.parseInt(System.getenv("HC_OP_HTTP_PROXY_PORT"));
} else {
// Get proxy for internet destinations
proxyHost = System.getProperty("http.proxyHost");
proxyPort = Integer.parseInt(System.getProperty("http.proxyPort"));
}
return new Proxy(Proxy.Type.HTTP, new InetSocketAddress(proxyHost,
proxyPort));
}
{

private void injectHeader(HttpURLConnection urlConnection, String proxyType)

if (ON_PREMISE_PROXY.equals(proxyType)) {
// Insert header for on-premise connectivity with the consumer
account name
urlConnection.setRequestProperty("SAP-Connectivity-ConsumerAccount",
tenantContext.getAccountName());
}
}
private void copyStream(InputStream inStream, OutputStream outStream) throws
IOException {
byte[] buffer = new byte[COPY_CONTENT_BUFFER_SIZE];
int len;
while ((len = inStream.read(buffer)) != -1) {
outStream.write(buffer, 0, len);
}
}
}

Note
The given servlet can be run with different destination scenarios, for which user should specify the
destination name as a requested parameter in the calling URL. In the case of on-premise connection to a
back-end system, the destination names should be backend-no-auth-destination. That is, it will be
accessed at: <application_URL>/?destname=backend-no-auth-destination

Note
When accessing a destination with a specific authentication type, use AuthenticationHeaderProvider API
[page 277] to get authentication headers and then inject them in all requests to this destination.
9. Save the Java editor and make sure the project compiles without errors.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

379

4. Deploy the Application

Note
We only recommend but not obligate that you create the destination before starting the application.
1. To deploy your Web application locally or on the cloud, follow the steps described in the respective pages:
Deploying Locally from Eclipse IDE [page 975]
Deploying on the Cloud from Eclipse IDE [page 977]
2. Once the application is successfully deployed locally or on the cloud, the application issues an exception
saying that the backend-no-auth-destination destination has not been specified yet:
HTTP Status 500 - Destination backend-no-auth-destination is not found. Hint:
Make sure to have the destination configured.
3. As a next step, you need to configure backend-no-auth-destination.
For more information, see ConnectivityConfiguration API [page 275].

5. Configure the Destination in the Cloud


To configure the destination in SAP HANA Cloud Platform, you need to use the virtual host name
(virtualpingbackend) and port (1234) specified in one of the previous steps on the cloud connector's Access
Control tab page.

Note
On-premise destinations support HTTP connections only.
The connection from an application to the cloud connector (through the tunnel) is encrypted on TLS level.
Also, you can choose between using HTTP or HTTPS to hop from the cloud connector to the back end.
1. In the Eclipse IDE, open the Servers view and double-click on <application>.<account> to open the cloud
server editor.
2. Open the Connectivity tab page.
3. In the All Destinations section, choose

to create a new destination with the name backend-no-auth-

destination.
4. Use the following configuration:
Name=backend-no-auth-destination
Type=HTTP
URL=http://virtualpingbackend:1234/BackendAppHttpNoAuth/noauth
Authentication=NoAuthentication
ProxyType=OnPremise
CloudConnectorVersion=2

380

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Save the destination.


6. The Connectivity editor automatically saves the configuration in the cloud.
7. Call the URL that references the cloud application again in the internal Web browser. The application should
now return the ping response.

Next Step
You can monitor the state and logs of your Web application deployed on SAP HANA Cloud Platform.
For more information, see Using Logs in the Eclipse IDE [page 1131].

Related Information
JavaDoc ConnectivityConfiguration
JavaDoc DestinationConfiguration
JavaDoc AuthenticationHeaderProvider
AuthenticationHeaderProvider API [page 277]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

381

1.4.1.1.4.5.5 Setting Up an Application as a Sample Back-End


System
Overview

This section describes how you set up a simple ping Web application that is used as a back-end system.

Prerequisites
You have downloaded SAP HANA Cloud Platform SDK on your local file system.

Procedure

1. Set up a servlet container such as Tomcat

2. Add a user and role for basic authentication by adding the following lines to thetomcat-users.xml file in
directory <TOMCAT_HOME>/conf file:
<role rolename="pingrole"/>
<user name="pinguser" password="pingpassword" roles="pingrole" />
3. From the SDK location, go to /samples/connectivity/onpremise, copy files
BackendAppHttpNoAuth.war and BackendAppHttpBasicAuth.war and paste them into the <TOMCAT_HOME>/
webapps directory.
4. Start Tomcat and access the on-premise applications at the URLs below. Use pinguser / pingpassword as
the credentials.
http://localhost:8080/BackendAppHttpNoAuth/noauth
http://localhost:8080/BackendAppHttpBasicAuth/basic

Note
In case you use SDK with version equal to or lower than, respectively, 1.44.0.1 (Java Web) and 2.24.13
(Java EE 6 Web Profile), you should find the WAR files in directory <SDK_location>/tools/samples/
connectivity/onpremise, under the names PingAppHttpNoAuth.war and PingAppHttpBasicAuth.war.
Also, you should access the applications at the relevant URLs:
http://localhost:8080/PingAppHttpNoAuth/pingnoauth
http://localhost:8080/PingAppHttpBasicAuth/pingbasic

382

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]

1.4.1.1.5

Invoking ABAP Function Modules via RFC Protocol

Installation Prerequisites
To provide connectivity tunnel via RFC destinations, your cloud connector version needs to be at least 1.3.0.
To develop a JCo application, your SDK version needs to be 1.29.18 (SDK Java Web), or 2.11.6 (SDK for
Java EE 6 Web Profile). Also, your SDK local runtime needs to be hosted by a 64-bit JVM.
On Windows platforms, you need to install Microsoft Visual C++ 2010 Redistributable Package (x64). To
download this package, go to http://www.microsoft.com/en-us/download/details.aspx?id=14632 .

Consuming Connectivity via RFC


You can call a service from a fenced customer network using a simple application which consumes a simple onpremise remote-enabled function module.
The invocation of function modules via RFC is offered via the JCo API like the one available in SAP NetWeaver
Application Server Java since version 7.10, and in JCo standalone 3.0. If you are an experienced JCo developer,
you can easily develop a Web application using JCo: you simply consume the APIs like you do in other Java
environments. Restrictions that apply in the cloud environment are mentioned in the Restrictions section below.
To see a sample Web application, see Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems
[page 399].

Configuring Connectivity via RFC


Configuring applications to use RFC destinations.
For more information, see Configuring Destinations from the Console Client [page 283] and RFC Destinations
[page 384].
Configuring connectivity between a back-end system and an on-demand application. You need to install the
cloud connector in your internal network and then configure it to expose a remote-enabled function module in
an on-premise ABAP system.
For more information, see Configuring the Cloud Connector for RFC [page 390].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

383

Restrictions
JCoServer functionality cannot be used within SAP HANA Cloud Platform.
Environment embedding, such as offered by JCo standalone 3.0, is not possible. This is, however, similar to
SAP NetWeaver AS Java.
Currently, a stateful sequence of function module invocations needs to occur in a single HTTP request/
response cycle.
Initially, only a logon with user/password credentials is supported.
The supported set of configuration properties is restricted. For more information, see RFC Destinations [page
384].

Related Information
SAP Java Connector API [page 280]

1.4.1.1.5.1 RFC Destinations


RFC destinations provide the configuration needed for communicating with an on-premise ABAP system via RFC.
The RFC destination data is used by the JCo version that is offered within SAP HANA Cloud Platform to establish
and manage the connection.

RFC Destination Properties


The RFC destination specific configuration in SAP HANA Cloud Platform consists of properties arranged in
groups, as described below. The supported set of properties is a subset of the standard JCo properties in arbitrary
environments. The configuration data is divided into the following groups:
User logon properties [page 385]
Physical connection [page 388]
Special parameters [page 390]
Pooling configuration [page 386]
Repository configuration [page 388]
The minimal configuration contains user logon properties and information identifying the target host. This means
you must provide at least a set of properties containing this information.

Example
Name=SalesSystem
Type=RFC
jco.client.client=000
jco.client.lang=EN
jco.client.user=consultant

384

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

jco.client.passwd=<password>
jco.client.ashost=sales-system.cloud
jco.client.sysnr=42
jco.destination.pool_capacity=5
jco.destination.peak_limit=10

1.4.1.1.5.1.1 User Logon Properties

This group of JCo properties covers different types of user credentials, as well as the ABAP system client and the
logon language. The currently supported logon mechanism uses user/password as the credentials.

Table 219:
Property

Description

jco.client.client

Represents the client to be used in the ABAP system. Valid


format is a three-digit number.

jco.client.lang

Optional property. Represents the logon language. If the prop


erty is not provided, the user's or system's default language is
used. Valid values are two-character ISO language codes or
one-character SAP language codes.

jco.client.user

Represents the user to be used for logging on to the ABAP


system. When working with the Destinations editor in the
cockpit, enter the value of this property in the User field.

jco.client.passwd

Represents the password of the user that shall be used. Note


that passwords in systems of SAP NetWeaver releases lower
than 7.0 are case-insensitive and can be only eight characters
long. For releases 7.0 and higher, passwords are case-sensi
tive with a maximum length of 40.

Note
When working with the Destinations editor in the cockpit,
enter this password in the Password field. Do not enter it as
additional property.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

385

Property

Description

jco.destination.auth_type

Optional property.

If the property is not provided, its default value,


CONFIGURED_USER, is used, which means that user/

To make use of the principal propagation so that the


identity logged on in the cloud application is also logged
on in an on-premise system, this property's value needs
to be set to PrincipalPropagation. In this case,

password or other credentials are directly specified.

jco.client.user and jco.client.passwd may


not be provided in the configuration.

Note
In the case of PrincipalPropagation value, you
should better configure the

jco.destination.repository.user and
jco.destination.repository.passwd proper
ties, since there are special permissions needed (for meta
data lookup in the back end) that not all business applica
tion users might have.

1.4.1.1.5.1.2 Pooling Configuration

Overview
This group of JCo properties covers different settings for the behavior of the destination's connection pool. All
properties are optional.
Table 220:
Property

Description

jco.destination.pool_capacity

Represents the maximum number of idle connec


tions kept open by the destination. A value of 0 has
the effect of no connection pooling, that is, connec
tions will be closed after each request. The default
value is 1.

jco.destination.peak_limit

386

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Represents the maximum number of active connec


tions that can simultaneously be created for a desti
nation.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Property

Description

jco.destination.max_get_client_time

Represents the maximum time in milliseconds to


wait for a free connection in case the maximum num
ber of active connections is already allocated by ap
plications.

jco.destination.expiration_time

Represents the time in milliseconds after which idle


connections that are available in the pool can be
closed.

jco.destination.expiration_check_period

Represents the interval in milliseconds within which


the timeout checker thread checks the idle connec
tions in the pool for expiration.

jco.destination.pool_check_connection

When setting this value to 1, a pooled connection will


be checked for corruption before being used for the
next function module execution. Thus, it is possible
to recognize corrupted connections and avoid excep
tions passed to applications when connectivity is
working in principle (default value is 0).

Note
Turning on this check has performance impact for
stateless communication. This is due to an addi
tional low-level ping to the server, which takes a
certain amount of time for non-corrupted connec
tions depending on latency.

Pooling Details
Each destination is associated with a connection factory and, if the pooling feature is used, with a connection
pool.
Initially, the destination's connection pool is empty, and the JCo runtime does not preallocate any connection.
The first connection will be created when the first function module invocation is performed. The peak_limit
property describes how many connections can be created simultaneously, if applications allocate
connections in different sessions at the same time. A connection is allocated either when a stateless function
call is executed, or when a connection for a stateful call sequence is reserved within a session.
After the <peak_limit> number of connections has been allocated (in <peak_limit> number of sessions),
the next session will wait for at most <max_get_client_time> milliseconds until a different session
releases a connection (either finishes a stateless call or ends a stateful call sequence). In case the waiting
session does not get any connection during the <max_get_client_time> period, the function request will
be aborted with JCoException with the key JCO_ERROR_RESOURCE.
Connections that are no longer used by applications are returned to the destination pool. There are at most
<pool_capacity> number of connections kept open by the pool. Further connections (<peak_limit> <pool_capacity>) will be closed immediately after usage. The pooled connections (open connections in the
pool) are marked as expired if they are not used again during <expiration_time> milliseconds. All expired
connections will be closed by a timeout checker thread which executes the check every
<expiration_check_period> milliseconds.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

387

1.4.1.1.5.1.3 Repository Configuration

This JCo properties group allows you to influence how the repository that dynamically retrieves function module
metadata behaves. All properties below are optional. Alternatively, applications could create their metadata in
their code, using the metadata factory methods within the JCo class, to avoid additional round-trips to the onpremise system.
Table 221:
Property

Description

jco.destination.repository_destination

Specifies which destination should be used for repository


queries. If the destination does not exist, an error occurs when
trying to retrieve the repository. Defaults to itself.

jco.destination.repository.user

Optional property. If this property is set, and the repository


destination is not set, it will be used as the user for repository
queries. This case allows using a different user for repository
lookups, and restricting this user's permissions accordingly.
See also SAP Note 460089

jco.destination.repository.passwd

Represents the password for a repository user. If you use


such a user, this property is mandatory.

Note
When working with the Destinations editor in the cockpit,
enter this password in the field of the main property
Repository password. Do not enter it as additional prop
erty.

1.4.1.1.5.1.4 Target System Configuration

Overview
Two types of configurations exist that can be used alternatively:
Direct connection to an ABAP application server;
Load balancing connection to a group of ABAP application servers via a message server.
Depending on the configuration used, different properties are considered mandatory or optional.

388

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Direct Connection Configuration

Table 222:
Property

Description

jco.client.ashost

Represents the application server host to be used. In the case


of configurations in SAP HANA Cloud, this property needs to
match a virtual host entry in the cloud connector Access
Control configuration. The existence of this property signals
that a direct connection shall be established.

jco.client.sysnr

Represents the so-called "system number" and has two digits.


It identifies the logical port on which the application server is
listening for incoming requests. In the case of configurations
in SAP HANA Cloud, this property needs to match a virtual
port entry in the cloud connector Access Control configura
tion.

Note
The virtual port in the above access control entry needs to
be named sapgw<##>, where <##> is the value of sysnr.

Load Balancing Configuration

Table 223:
Property

Description

jco.client.mshost

Represents the message server host to be used. In the case of


configurations in SAP HANA Cloud, this property needs to
match a virtual host entry in the cloud connector Access
Control configuration. The existence of this property signals
that load balancing shall be used for establishing a connec
tion.

jco.client.group

Optional property. Identifies the group of application servers


that shall be used, the so-called "logon group". If the property
is not specified, the group PUBLIC will be used.

jco.client.r3name

Represents the three-character system ID of the ABAP sys


tem to be addressed. In the case of configurations in SAP
HANA Cloud, this property needs to match a virtual port entry
in the cloud connector Access Control configuration.

Note
The virtual port in the above access control entry needs to
be named sapms<###>, where <###> is the value of
r3name.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

389

Property

Description

jco.client.msserv

Represents the port on which the message server is listening


for incoming requests. This property can be used as an alter
native to jco.client.r3name. One of these two needs to
be present. In the case of configurations in SAP HANA Cloud,
this property needs to match a virtual port entry in the cloud
connector Access Control configuration. You can therefore
avoid lookups in the /etc/services file
(<Install_Drive>\Windows\System32\drivers
\etc\services) on the cloud connector host.

1.4.1.1.5.1.5 Parameters Influencing Communication Behavior


This group of JCo properties allows you to influence the connection to an ABAP system. All properties are
optional.
Table 224:
Property

Description

jco.client.trace

Defines whether protocol traces shall be created. Valid values


are 1 (trace is on) and 0 (trace is off). The default value is 0.

jco.client.codepage

Declares the 4-digit SAP codepage that shall be used when ini
tiating the connection to the backend. The default value is
1100 (comparable to iso-8859-1). It is important to provide
this property if the password that is used contains characters
that cannot be represented in 1100.

jco.client.delta

Enables/disables table parameter delta management. It is en


abled if set to 1, and respectively disabled if set to 0. The de
fault value is 1.

jco.client.cloud_connector_version

The value defines which version of the cloud connector is used


for establishing a connection to the on-premise system.
Choose 1 if using the cloud connector 1.x, and 2 if using the
cloud connector 2.x. The default value is 1.

1.4.1.1.5.2 Configuring the Cloud Connector for RFC

Overview
This section helps you to configure your cloud connector when you are working via the RFC protocol.

390

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Initial Configuration (RFC) [page 391]
Configuring Access Control (RFC) [page 392]
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]

1.4.1.1.5.2.1 Initial Configuration (RFC)

SNC Configuration for Mutual Authentication


To set up a mutual authentication between cloud connector and an ABAP back-end system (connected via RFC),
you can configure SNC for the cloud connector. It will then use the associated PSE for all RFC SNC requests. This
means that the SNC identity, represented by this PSE needs to:
Be trusted by all back-end systems to which the cloud connector is supposed to connect;
Play the role of a trusted external system by adding the SNC name of the cloud connector to the SNCSYSACL
table. You can find more details in the SNC configuration documentation for the release of your ABAP system.

Prerequisites
You have configured your ABAP system(s) for SNC. For detailed information on configuring SNC for an ABAP
system, see also Configuring SNC on AS ABAP. In order to establish trust for Principal Propagation, follow the
steps described in Configuring Principal Propagation to an ABAP System for RFC [page 492].

Configuration Steps
1. Logon to the cloud connector
2. Choose

Settings

SNC

from the menu bar

3. Enter the corresponding values in the fields Library Name, My Name and Quality of Protection (QoP)
4. Press Save and Close.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

391

Example:

Library Name: Provides the location of the SNC library you are using for the cloud connector.

Note
Bear in mind that you must use one and the same security product on both sides of the
communication.
My Name: The SNC name that identifies the cloud connector. It represents a valid scheme for the SNC
implementation that is used.
Quality of Protection (QoP): Determines the level of protection that you require for the connectivity to the
ABAP systems.

Related Information
Configuring Principal Propagation to an ABAP System for RFC [page 492]

1.4.1.1.5.2.2 Configuring Access Control (RFC)

392

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Exposing Intranet Systems


To allow your on-demand applications to access a certain back-end system on the intranet, you need to insert an
extra line within the cloud connector Access Control management.
1. Go to the Access Control tab page.
2. Choose Add.
3. Back-end Type: You need to select the description that best matches the addressed back-end system. In case
of RFC, only ABAP System and SAP Gateway are fitting values, which means usage of RFC is free of charge.

4. Choose Next.
5. Protocol: You need to choose whether the cloud connector should use RFC or RFC with SNC for connecting to
the back-end system. This is completely independent from the settings on cloud side. This way, you are
ensured that the entire connection from the on-demand application to the actual back-end system (provided
through the SSL tunnel) is secured, partly with SSL and partly with SNC. For more information, see Initial
Configuration (RFC) [page 391].

Note
The back end needs to be properly configured to support SNC connections.
SNC configuration has to be provided in the cloud connector.
6. Choose Next.
7. Choose whether you want to configure a load balancing logon or whether to connect to a concrete application
server.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

393

8. Specify the parameters of the back-end system. It needs to be an existing network address that can be
resolved on the intranet and has network visibility for the cloud connector. If this is only possible using a valid
SAProuter, specify the router in the respective field. The cloud connector will try to establish a connection to
this system, so the address has to be real.
When using a load-balancing configuration, the Message Server specifies the message server of the ABAP
system. The system ID is a three-char identifier that is also found in the SAP Logon configuration.
Alternatively, it's possible to directly specify the message server port in the System ID field.

When using direct logon, the Application Server specifies one application server of the ABAP system. The
instance number is a two-digit number that is also found in in the SAP Logon configuration. Alternatively,
it's possible to directly specify the gateway port in the Instance Number field.

394

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

9. Optional: You can virtualize the system information in case you like to hide your internal host names from the
cloud. The virtual information can be a fake name which does not need to exist. The fields will be prepopulated with the values of the configuration provided in Message Server and System ID, or Application
Server and Instance Number.

Virtual Message Server - specifies the host name exactly as specified as the jco.client.mshost
property in the RFC destination configuration in the cloud. The Virtual System ID allows you to distinguish
between different entry points of your back-end system that have different sets of access control
settings. The value needs to be the same like for the jco.client.r3name property in the RFC
destination configuration in the cloud.
Virtual Application Server - it specifies the host name exactly as specified as the jco.client.ashost
property in the RFC destination configuration in the cloud. The Virtual Instance Number allows you to
distinguish between different entry points of your back-end system that have different sets of access
control settings. The value needs to be the same like for the jco.client.sysnr property in the RFC
destination configuration in the cloud.
10. This step will only come up, if you have chosen RFC SNC, not for plain RFC. The <Principal Type> field
defines what kind of principal is used when configuring a destination on the cloud side using this system
mapping with authentication type Principal Propagation. No matter what you choose, you need to make sure
that the general configuration for the <Principal Type> has been done to make it work correctly. For
destinations using different authentication types, this setting is ignored. In case you choose None as
<Principal Type>, it is not possible to apply Principal Propagation to this system.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

395

Note
In the case of RFC, it is not possible to choose between different principal types. The only supported one is
X.509 certificate, which can be applied only when using an SNC-enabled back-end connection.

11. SNC Partner Name: This step will only come up if you have chosen RFC SNC. The SNC partner name needs to
contain the correct SNC identification of the target system.

12. You can enter an optional description at this stage. The respective description will be shown as a rich tooltip
when the mouse hovers over the entries of the virtual host column (table Mapping Virtual to Internal System).

396

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

13. The summary shows information about the system to be stored. When saving the system mapping, you can
trigger a ping from the cloud connector to the internal host, using the Check availability of internal host check
box. This allows you to make sure the cloud connector can indeed access the internal system, and allows you
to catch basic things, such as spelling mistakes or firewall problems between the cloud connector and the
internal host. If the ping to the internal host is successful, the cloud connector saves the mapping without any
remark. If it fails, a warning will pop up, that the host is not reachable. Details for the reason are available in
the log files. You can execute such a check at any time later for all selected systems in the Access Control
overview.

14. Optional: You can later edit a system mapping (choose Edit) to make the cloud connector route the requests
for sales-system.cloud:sapgw42 to a different back-end system. This can be useful if the system is
currently down and there is a back-up system that can serve these requests in the meantime. However, you
cannot edit the virtual name of this system mapping. If you want to use a different fictional host name in your
on-demand application, you need to delete the mapping and create a new one. Here, you can also change the
Principal Type to None in case you don't want to allow principal propagation to a certain system.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

397

Limiting the Accessible Resources for RFC


In addition to allowing access to a particular host and port, you also need to specify which function modules
(Resources) are allowed to be invoked on that host. The cloud connector uses very strict white lists for its access
control, so allowed are only function modules for which you explicitly granted access. All other RFC requests are
denied by the cloud connector.
1. To define the permitted function modules (Resources) for a particular back-end system, choose the row
corresponding to that back-end system. A dialog appears, prompting you to enter the specific function
module name whose invoking you want to allow.

398

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. The cloud connector checks that the function module name of an incoming request is exactly as specified in
the configuration. If it is not, the request is denied.
3. If you select the Prefix option, the cloud connector allows all incoming requests, for which the function module
name begins with the specified string.
4. The Enabled checkbox allows you to specify whether that resource should be initially enabled or disabled.

Related Information
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems [page 399]

1.4.1.1.5.3 Tutorial: Invoking ABAP Function Modules in OnPremise ABAP Systems

Context
This step-by-step tutorial shows how a sample Web application invokes a function module in an on-premise ABAP
system via RFC by using the connectivity service.
The tutorial contains the following sections:
Presenting the user roles
Defining the installation prerequisites

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

399

Developing a sample Web application that uses the connectivity service to consume the simple function
module STFC_CONNECTION.

Connectivity User Roles


Different user roles are involved in the on-demand to on-premise connectivity end-to-end scenario. The particular
steps for the relevant roles are described below:

IT Administrator
This role sets up and configures the cloud connector. Scenario steps:
1. Downloads the cloud connector from https://tools.hana.ondemand.com/#cloud
2. Installs the cloud connector.
3. Establishes an SSL tunnel from the connector to an SAP HANA Cloud Platform account.
4. Configures the exposed back-end systems and resources.

Application Developer
This role develops Web applications using destinations. Scenario steps:
1. Installs the Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
2. Develops a Java EE application using the destination API.
3. Configures connectivity destinations as resources in the web.xml file.
4. Configures connectivity destinations via the SAP HANA Cloud Platform server adapter in Eclipse IDE.
5. Deploys the Java EE application locally and on the cloud.

Account Operator
This role deploys Web applications, configures their destinations, and conducts tests. Scenario steps:
1. Obtains a ready Java EE application WAR file.
2. Deploys the Java EE application in an SAP HANA Cloud Platform account.
3. Uploads the connectivity destination configuration via the console client.
4. Tests the Java EE application on a local server and deploys it again to a SAP HANA Cloud Platform account.

400

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Installation Prerequisites
You have downloaded and set up your Eclipse IDE and SAP HANA Cloud Platform Tools for Java.
You have downloaded the SDK. Its version needs to be at least 1.29.18 (SDK for Java Web), 2.11.6 (SDK for
Java EE 6 Web Profile), or 2.9.1 (SDK for Java Web Tomcat 7), respectively.
Your local runtime needs to be hosted by a 64-bit JVM. On Windows platforms, you need to install Microsoft
Visual C++ 2010 Redistributable Package (x64).
You have downloaded and configured your cloud connector. Its version needs to be at least 1.3.0.
To download the SAP tools, go to https://tools.hana.ondemand.com/#cloud.
To download the Microsoft Visual C++ package, go to http://www.microsoft.com/en-us/download/details.aspx?
id=14632 .
To read the installation documentation, go to Installing Java Tools for Eclipse and SDK [page 33] and Installing the
Cloud Connector [page 436].

Creating a Dynamic Web Project


Procedure
1. In the Eclipse IDE, open the Java EE perspective.
2. From the Eclipse main menu, choose

New

Dynamic Web Project .

3. In the Project name field, enter jco_demo .


4. In the Target Runtime pane, select the runtime you want to use to deploy the HelloWorld application. In this
tutorial, we choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to complete the creation of your project.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

401

Creating a Sample Servlet

Procedure
1. From the jco_demo context menu, choose

New

Servlet .

2. Enter com.sap.demo.jco as the Java package and ConnectivityRFCExample as the Class name and
choose Next.

402

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Choose Finish so that the ConnectivityRFCExample.java servlet is created and opened in the Java editor.
4. Replace the entire servlet class to make use of the JCo API. The JCo API is visible by default for cloud
applications and must not be added explicitly to the application class path.
package com.sap.demo.jco;
import java.io.IOException;
import java.io.PrintWriter;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.conn.jco.AbapException;
import com.sap.conn.jco.JCoDestination;
import com.sap.conn.jco.JCoDestinationManager;
import com.sap.conn.jco.JCoException;
import com.sap.conn.jco.JCoFunction;
import com.sap.conn.jco.JCoParameterList;
import com.sap.conn.jco.JCoRepository;
/**
* Sample application that uses the connectivity service. In particular,
* it makes use of the capability to invoke a function module in an ABAP system
* via RFC
*
* Note: The JCo APIs are available under <code>com.sap.conn.jco</code>.
*/
public class ConnectivityRFCExample extends HttpServlet
{
private static final long serialVersionUID = 1L;
public ConnectivityRFCExample()
{
}
protected void doGet(HttpServletRequest request, HttpServletResponse
response)
throws ServletException, IOException
{
PrintWriter responseWriter = response.getWriter();
try
{
// access the RFC Destination "JCoDemoSystem"
JCoDestination
destination=JCoDestinationManager.getDestination("JCoDemoSystem");
// make an invocation of STFC_CONNECTION in the backend;
JCoRepository repo=destination.getRepository();
JCoFunction stfcConnection=repo.getFunction("STFC_CONNECTION");
JCoParameterList imports=stfcConnection.getImportParameterList();
imports.setValue("REQUTEXT", "SAP HANA Cloud connectivity runs with
JCo");
stfcConnection.execute(destination);
JCoParameterList exports=stfcConnection.getExportParameterList();
String echotext=exports.getString("ECHOTEXT");
String resptext=exports.getString("RESPTEXT");
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter.println("<h1>Executed STFC_CONNECTION in system
JCoDemoSystem</h1>");
responseWriter.println("<p>Export parameter ECHOTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(echotext);
responseWriter.println("<p>Export parameter RESPTEXT of
STFC_CONNECTION:<br>");
responseWriter.println(resptext);
responseWriter.println("</body></html>");
}
catch (AbapException ae)
{
//just for completeness: As this function module does not have an
exception

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

403

always

//in its signature, this exception cannot occur. However,you should

//take care of AbapExceptions


}
catch (JCoException e)
{
response.addHeader("Content-type", "text/html");
responseWriter.println("<html><body>");
responseWriter.println("<h1>Exception occurred while executing
STFC_CONNECTION in system JCoDemoSystem</h1>");
responseWriter.println("<pre>");
e.printStackTrace(responseWriter);
responseWriter.println("</pre>");
responseWriter.println("</body></html>");
}
}
}

5. Save the Java editor and make sure that the project compiles without errors.

Deploying the Application


Procedure
1. To deploy your Web application locally or on the cloud, see the following two procedures, respectively:
Deploying Locally from Eclipse IDE [page 975]
Deploying on the Cloud from Eclipse IDE [page 977]
2. Once the application is successfully deployed on the cloud and you execute it, the application throws an
exception saying that the JCoDemoSystem destination has not been specified yet:
Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem
com.sap.conn.jco.JCoException: (106) JCO_ERROR_RESOURCE: Destination
JCoDemoSystem does not exist
at
com.sap.conn.jco.rt.DefaultDestinationManager.update(DefaultDestinationManager.ja
va:223)
at
com.sap.conn.jco.rt.DefaultDestinationManager.searchDestination(DefaultDestinatio
nManager.java:377)
at
com.sap.conn.jco.rt.DefaultDestinationManager.getDestinationInstance(DefaultDesti
nationManager.java:96)
at
com.sap.conn.jco.JCoDestinationManager.getDestination(JCoDestinationManager.java:
52)
at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:
47)
..... (cut rest of the call stack)
3. As a next step, you need to configure the JCoDemoSystem destination.

404

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Configuring the RFC Destination on the Cloud


To configure the destination on SAP HANA Cloud Platform, you need to use a virtual application server host name
(abapserver.hana.cloud) and a virtual system number (42) that you will expose later in the cloud connector.
Alternatively, you could use a load balancing configuration with a message server host and a system ID.

Procedure
1. Create a properties file with the following settings:
Name=JCoDemoSystem
Type=RFC
jco.client.ashost=abapserver.hana.cloud
jco.client.cloud_connector_version=2
jco.client.sysnr=42
jco.client.user=DEMOUSER
jco.client.passwd=<password>
jco.client.client=000
jco.client.lang=EN
jco.destination.pool_capacity=5
2. Upload this file to your Web application in SAP HANA Cloud Platform. For more information, see Configuring
Destinations from the Console Client [page 283].
3. Call the URL that references the cloud application again in the Web browser. The application should now
return a different exception:
Exception occurred while executing STFC_CONNECTION in system JCoDemoSystem
com.sap.conn.jco.JCoException: (102) JCO_ERROR_COMMUNICATION: Opening connection
to backend failed: Opening connection denied
at
com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.java
:632)
at com.sap.conn.jco.rt.MiddlewareJavaRfc
$JavaRfcClient.connect(MiddlewareJavaRfc.java:1307)
at com.sap.conn.jco.rt.ClientConnection.connect(ClientConnection.java:726)
at com.sap.conn.jco.rt.PoolingFactory.init(PoolingFactory.java:107)
at
com.sap.conn.jco.rt.ConnectionManager.createFactory(ConnectionManager.java:316)
at
com.sap.conn.jco.rt.DefaultConnectionManager.createFactory(DefaultConnectionManag
er.java:46)
at com.sap.conn.jco.rt.ConnectionManager.getFactory(ConnectionManager.java:
290)
at com.sap.conn.jco.rt.ConnectionManager.getClient(ConnectionManager.java:83)
at com.sap.conn.jco.rt.Context.getConnection(Context.java:216)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1306)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1278)
at com.sap.conn.jco.rt.AbapFunction.execute(AbapFunction.java:295)
at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:
55)
..... (cut rest of the call stack)
4. This means the cloud connector denied opening a connection to this system. As a next step, you need to
configure the system in your installed cloud connector.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

405

Configuring the Host Mapping in the Cloud Connector


This is required since the cloud connector only allows access to white-listed back-end systems. To do this, follow
the steps below:

Procedure
1. Optional: In the cloud connector administration UI, you can check under
has been denied:

Monitor

Audit

whether access

OP_ACCESS_DENIED, Denying access to system abapserver.hana.cloud:sapgw42


2. In the cloud connector administration UI, go to the Access Control tab page.
3. Add a new system under the list of defined resources. Under Mapping Virtual To Internal System, choose the
Add button and define the relevant entries.
1. For Back-end Type, select ABAP System.
2. For Protocol, select RFC.
3. Choose option Without load balancing.
4. Enter application server and instance number. The Application Server entry must be the physical host
name of the machine on which the ABAP application server is running. Example:

5. Enter server and instance number for virtual mapping. Example:

406

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Summary (example):

4. Call the URL that references the cloud application again in the Web browser. The application should now
throw a different exception:
com.sap.conn.jco.JCoException: (102) JCO_ERROR_COMMUNICATION: Access denied for
STFC_CONNECTION
at
com.sap.conn.jco.rt.MiddlewareJavaRfc.generateJCoException(MiddlewareJavaRfc.java
:632)
at com.sap.conn.jco.rt.MiddlewareJavaRfc
$JavaRfcClient.execute(MiddlewareJavaRfc.java:1764)
at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java:1110)
at com.sap.conn.jco.rt.ClientConnection.execute(ClientConnection.java:943)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1307)
at com.sap.conn.jco.rt.RfcDestination.execute(RfcDestination.java:1278)
at com.sap.conn.jco.rt.AbapFunction.execute(AbapFunction.java:295)
at com.sap.demo.jco.ConnectivityRFCExample.doGet(ConnectivityRFCExample.java:
55)
..... (cut rest of the call stack)
5. This means the cloud connector denied invoking STFC_CONNECTION in this system. As a final step, you need
to provide access to this function module in your installed cloud connector.

Configuring the Function Module in the Cloud Connector


This is required since the cloud connector only allows access to white-listed resources (which are defined on the
basis of function module names with RFC). To do this, follow the steps below:

Procedure
1. Optional: In the cloud connector administration UI, you can check under
has been denied:

Monitor

Audit

whether access

OP_ACCESS_DENIED, Denying access for user DEMOUSER to resource STFC_CONNECTION


on system abapserver.hana.cloud:sapgw42
2. In the cloud connector administration UI, go to the Access Control tab page.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

407

3. For the specified internal system referring to abapserver.hana.cloud, add a new resource. Select the system in
the table.
4. Add a new function name under the list of exposed resources. Under Resources Accessible On
localappserverhost.compamy.corp:sapgw23, choose the Add button and specify STFC_CONNECTION as the
accessible resource as shown in the screenshot below. Make sure that you have selected the Exact Name
option to only expose this single function module.

5. Call the URL that references the cloud application again in the Web browser. The application should now
return with a message showing the export parameters of the function module after a successful invocation.

Related Information
You can monitor the state and logs of your Web application deployed on SAP HANA Cloud Platform.
For more information, see Using Logs in the Eclipse IDE [page 1131].

1.4.1.1.6

Sending and Fetching E-Mail

The e-mail connectivity functionality allows you to send electronic mail messages from your Web applications
using e-mail providers that are accessible on the Internet, such as Google Mail (Gmail). It also allows you to
retrieve e-mails from the mailbox of your e-mail account.
To send and fetch e-mail, you need to do the following:
Obtain a mail session resource using resource injection or, alternatively, using a JNDI lookup.
Configure the mail session resource by specifying the protocol settings of your mail server as a mail
destination configuration. SMTP is supported for sending e-mail, and POP3 and IMAP for retrieving messages
from a mailbox account.
In your Web application, use the JavaMail API (javax.mail) to create and send a MimeMessage object or
retrieve e-mails from a message store.

408

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Mail Destinations [page 410]
JavaMail API [page 409]
Enabling the Debugging Feature [page 413]
Tutorial: Sending E-Mails [page 414]
Connectivity Service [page 267]

1.4.1.1.6.1 JavaMail API


In your Web application, you use the JavaMail API (javax.mail) to create and send a MimeMessage object or
retrieve e-mails from a message store.

Mail Session
You can obtain a mail session resource using resource injection or a JNDI lookup. The properties of the mail
session are specified by a mail destination configuration. So that the resource is linked to this configuration, the
names of the destination configuration and mail session resource must be the same.
Resource injection
You can directly inject the mail session resource using annotations as shown in the example below. You do not
need to declare the JNDI resource reference in the web.xml deployment descriptor.
@Resource(name = "mail/Session")
private javax.mail.Session mailSession;
JNDI lookup
To obtain a resource of type javax.mail.Session, you declare a JNDI resource reference in the web.xml
deployment descriptor in the WebContent/WEB-INF directory as shown below. Note that the recommended
resource reference name is Session and the recommended subcontext is mail (mail/Session):
<resource-ref>
<res-ref-name>mail/Session</res-ref-name>
<res-type>javax.mail.Session</res-type>
</resource-ref>
An initial JNDI context can be obtained by creating a javax.naming.InitialContext object. You can then
consume the resource by looking up the naming environment through the InitialContext, as follows:
InitialContext ctx = new InitialContext();
Session mailSession = (Session)ctx.lookup("java:comp/env/mail/Session");
Note that according to the Java EE Specification, the prefix java:comp/env should be added to the JNDI
resource name (as specified in the web.xml) to form the lookup name.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

409

Sending E-Mail
With the javax.mail.Session object you have retrieved, you can use the JavaMail API to create a
MimeMessage object with its constituent parts (instances of MimeMultipart and MimeBodyPart). The message
can then be sent using the send method from the Transport class:
Transport transport = mailSession.getTransport();
transport.connect();
MimeMessage mimeMessage = new MimeMessage(mailSession);
...
transport.sendMessage(mimeMessage, mimeMessage.getAllRecipients());
transport.close();

Fetching E-Mail
You can retrieve the e-mails from the inbox folder of your e-mail account using the getFolder method from the
Store class as follows:
Store store = mailSession.getStore();
store.connect();
Folder folder = store.getFolder("INBOX");
folder.open(Folder.READ_ONLY);
Message[] messages = folder.getMessages();
...
folder.close(true);
store.close();
Fetched e-mail is not scanned for viruses. This means that e-mail retrieved from an e-mail provider using IMAP or
POP3 could contain a virus that could potentially be distributed (for example, if e-mail is stored in the database or
forwarded). Basic mitigation steps you could take include the following:
Choose an e-mail provider that scans received e-mail for viruses
Store e-mail in the document service repository before processing it. Make sure that the virus scanner
provided by the document service is enabled.
Generally dont resend e-mail that you have fetched

Related Information
Connectivity and Destination APIs [page 272]

1.4.1.1.6.2 Mail Destinations


A mail destination is used to specify the mail server settings for sending or fetching e-mail, such as the e-mail
provider, e-mail account, and protocol configuration.
The name of the mail destination must match the name used for the mail session resource. You can configure a
mail destination directly in a destination editor or in a mail destination properties file. The mail destination then

410

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

needs to be made available in the cloud. If a mail destination is updated, an application restart is required so that
the new configuration becomes effective.

Mail Destination Properties


The following properties are used to configure the mail destination:
Table 225:
Property

Description

Mandatory

Name

The name of the destination. The mail session that is configured by

Yes

this mail destination is available by injecting the mail session re


source mail/<Name>. The name of the mail session resource
must match the destination name.
The recommended name for a mail destination is Session.

Type

The type of destination. It must be MAIL for mail destinations.

Yes

mail.*

javax.mail properties for configuring the mail session.

Depends on the mail protocol


used.

To send e-emails, you must specify at least

mail.transport.protocol and mail.smtp.host.


To retrieve e-mails, you must specify at least

mail.store.protocol, mail.<protocol>.host, and for


POP3 mail.pop3.port.

mail.password

Password that is used for authentication. The user name for au

Yes, if authentication is used

thentication is specified by mail.user (a standard

(mail.smtp.auth=true and

javax.mail property).

generally for fetching e-mail).

Note the following points:


mail.smtp.port: The SMTP standard ports 465 (SMTPS) and 587 (SMTP+STARTTLS) are open for
outgoing connections on SAP HANA Cloud Platform.
mail.pop3.port: The POP3 standard ports 995 (POP3S) and 110 (POP3+STARTTLS) are open for outgoing
connections (used to fetch e-mail).
mail.imap.port: The IMAP standard ports 993 (IMAPS) and 143 (IMAP +STARTTLS) are open for outgoing
connections (used to fetch e-mail).
mail.<protocol>.host: The mail server of an e-mail provider accessible on the Internet, such as Google
Mail (for example, smtp.gmail.com, imap.gmail.com, and so on).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

411

SMTP and IMAP Example


The destination below has been configured to use Gmail as the e-mail provider, SMTP with STARTTLS (port 587)
for sending e-mail, and IMAP (SSL) for receiving e-mail:
Name=Session
Type=MAIL
mail.user=<gmail account name>
mail.password=<gmail account password>
mail.transport.protocol=smtp
mail.smtp.host=smtp.gmail.com
mail.smtp.auth=true
mail.smtp.starttls.enable=true
mail.smtp.port=587
mail.store.protocol=imaps
mail.imaps.host=imap.gmail.com

SMTPS Example
The destination below uses Gmail and SMTPS (port 465) for sending e-mail:
Name=Session
Type=MAIL
mail.user=<gmail account name>
mail.password=<gmail account password>
mail.transport.protocol=smtps
mail.smtps.host=smtp.gmail.com
mail.smtps.auth=true
mail.smtps.port=465

Related Information
JavaMail API Documentation
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

412

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.6.3 Enabling the Debugging Feature


In order to troubleshoot e-mail delivery and retrieval issues, it is useful to have debug information about the mail
session established between your SAP HANA Cloud Platform application and your e-mail provider.

Context
To include debug information in the standard trace log files written at runtime, you can use the JavaMail
debugging feature and the System.out logger. The System.out logger is preconfigured with the log level INFO.
You require at least INFO or a level with more detailed information.

Procedure
1. To enable the JavaMail debugging feature, add the mail.debug property to the mail destination
configuration as shown below:
mail.debug=true
2. To check the log level for your application, log onto the cockpit.
3. In the content area, choose

Applications

Java Applications .

4. In the application list, select your application to go to the overview.


5. In the content area, choose

Monitoring

Logging .

6. In the Default Trace section in the Log Files panel, choose Configure Loggers.
In the Logger Configuration dialog box, all loggers used since the application was started are listed with the log
levels that are currently applicable. Loggers are not listed if the relevant application code has not been
executed.
7. Enter system.out in the Filter field.
8. If necessary, change the log level for the System.out logger.

Note
You can check the log level of the System.out logger in a similar manner from the Eclipse IDE.

Related Information
Cockpit [page 84]
Using Logs in the Eclipse IDE [page 1131]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

413

1.4.1.1.6.4 Tutorial: Sending E-Mails


This step-by-step tutorial shows how you can send an e-mail from a simple Web application using an e-mail
provider that is accessible on the Internet. As an example, it uses Gmail.
Table 226:
Steps

Sample Application

Prerequisites [page 414]

The application is also available as a sample in the SAP

1. Create a Dynamic Web Project and Servlet [page 414]

HANA Cloud Platform SDK:

2. Extend the Servlet [page 414]

Sample name: mail

3. Test the Application Locally [page 417]

Location: <sdk>/samples folder

4. Test the Application in the Cloud [page 417]

More information: Samples [page 51]

Prerequisites
You have installed the SAP HANA Cloud Platform Tools and created a SAP HANA Cloud server runtime
environment as described in Installing Java Tools for Eclipse and SDK [page 33].

1. Create a Dynamic Web Project and Servlet


To develop applications for the SAP HANA Cloud Platform, you require a dynamic Web project and servlet.
1. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

2. In the Project name field, enter mail.


3. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, you
use Java Web.
4. In the Configuration area, leave the default configuration and choose Finish.
5. To add a servlet to the project you have just created, select the mail node in the Project Explorer view.
6. From the Eclipse main menu, choose

File

New

Servlet .

7. Enter the Java package com.sap.cloud.sample.mail and the class name MailServlet.
8. Choose Finish to generate the servlet.

2. Extend the Servlet


You add code to create a simple Web UI for composing and sending an e-mail message. The code includes the
following methods:
doGet(): Creates an HTML form for entering e-mail details.
doPost(): Uses the mail session resource to create and send a MimeMessage object. It confirms that an email has been sent.

414

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. In the Project Explorer view, expand the mail/Java Resources/src/com.sap.cloud.sample.mail


node.
2. Select MailServlet.java, and from the context menu choose

Open With

Java Editor .

3. In the opened editor, replace the entire servlet class with the following content:
package com.sap.cloud.sample.mail;
import java.io.IOException;
import java.io.PrintWriter;
import javax.annotation.Resource;
import javax.mail.Message.RecipientType;
import javax.mail.MessagingException;
import javax.mail.Session;
import javax.mail.Transport;
import javax.mail.internet.InternetAddress;
import javax.mail.internet.MimeBodyPart;
import javax.mail.internet.MimeMessage;
import javax.mail.internet.MimeMultipart;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* Servlet implementing a mail example which shows how to use the connectivity
service APIs to send e-mail.
* The example provides a simple UI to compose an e-mail message and send it.
The post method uses
* the connectivity service and the javax.mail API to send the e-mail.
*/
public class MailServlet extends HttpServlet {
@Resource(name = "mail/Session")
private Session mailSession;
private static final long serialVersionUID = 1L;
private static final Logger LOGGER =
LoggerFactory.getLogger(MailServlet.class);
/** {@inheritDoc} */
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
// Show input form to user
response.setHeader("Content-Type", "text/html");
PrintWriter writer = response.getWriter();
writer.write("<!DOCTYPE HTML PUBLIC \"-//W3C//DTD HTML 4.01
Transitional//EN\" "
+ "\"http://www.w3.org/TR/html4/loose.dtd\">");
writer.write("<html><head><title>Mail Test</title></head><body>");
writer.write("<form action='' method='post'>");
writer.write("<table style='width: 100%'>");
writer.write("<tr>");
writer.write("<td width='100px'><label>From:</label></td>");
writer.write("<td><input type='text' size='50' value=''
name='fromaddress'></td>");
writer.write("</tr>");
writer.write("<tr>");
writer.write("<td><label>To:</label></td>");
writer.write("<td><input type='text' size='50' value=''
name='toaddress'></td>");
writer.write("</tr>");
writer.write("<tr>");
writer.write("<td><label>Subject:</label></td>");
writer.write("<td><textarea rows='1' cols='100'
name='subjecttext'>Subject</textarea></td>");
writer.write("</tr>");
writer.write("<tr>");
writer.write("<td><label>Mail:</label></td>");

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

415

writer.write("<td><textarea rows='7' cols='100' name='mailtext'>Mail


Text</textarea></td>");
writer.write("</tr>");
writer.write("<tr>");
writer.write("<tr>");
writer.write("<td><input type='submit' value='Send Mail'></td>");
writer.write("</tr>");
writer.write("</table>");
writer.write("</form>");
writer.write("</body></html>");
}
/** {@inheritDoc} */
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse
response) throws ServletException,
IOException {
Transport transport = null;
try {
// Parse form parameters
String from = request.getParameter("fromaddress");
String to = request.getParameter("toaddress");
String subjectText = request.getParameter("subjecttext");
String mailText = request.getParameter("mailtext");
if (from.isEmpty() || to.isEmpty()) {
throw new RuntimeException("Form parameters From and To may not
be empty!");
}
// Construct message from parameters
MimeMessage mimeMessage = new MimeMessage(mailSession);
InternetAddress[] fromAddress = InternetAddress.parse(from);
InternetAddress[] toAddresses = InternetAddress.parse(to);
mimeMessage.setFrom(fromAddress[0]);
mimeMessage.setRecipients(RecipientType.TO, toAddresses);
mimeMessage.setSubject(subjectText, "UTF-8");
MimeMultipart multiPart = new MimeMultipart("alternative");
MimeBodyPart part = new MimeBodyPart();
part.setText(mailText, "utf-8", "plain");
multiPart.addBodyPart(part);
mimeMessage.setContent(multiPart);
// Send mail
transport = mailSession.getTransport();
transport.connect();
transport.sendMessage(mimeMessage, mimeMessage.getAllRecipients());
// Confirm mail sending
response.getWriter().println(
"E-mail was sent (in local scenario stored in '<localserver>/work/mailservice'"
+ " - in cloud scenario using configured mail
session).");
} catch (Exception e) {
LOGGER.error("Mail operation failed", e);
throw new ServletException(e);
} finally {
// Close transport layer
if (transport != null) {
try {
transport.close();
} catch (MessagingException e) {
throw new ServletException(e);
}
}
}
}
}
4. Save the class.

416

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Test the Application Locally


Test your code using the local file system before configuring your mail destination and testing the application in
the cloud.
1. To test your application on the local server, select the servlet and choose

Run

Run As

2. Make sure that the Manually define a new server radio button is selected and select

SAP

Run on Server .
Java Web

Server .
3. Choose Finish. A sender screen appears, allowing you to compose and send an e-mail. The sent e-mail is
stored in the work/mailservice directory contained in the root of your SAP HANA Cloud Platform local
runtime server.

Note
To send the e-mail through a real e-mail server, you can configure a destination as described in the next
section, but using the local server runtime. Remember that once you have configured a destination for local
testing, messages are no longer sent to the local file system.

4. Test the Application in the Cloud


Create a mail destination that contains the SMTP settings of your e-mail provider. The name of the mail
destination must match the name used in the resource reference in the web.xml descriptor.
1. In the Eclipse main menu, choose

File

New

Other

Server

Server .

2. Select the server type SAP HANA Cloud Platform and choose Next.
3. In the SAP HANA Cloud Platform Application dialog box, enter the name of your application, account, user,
and password and choose Finish. The new server is listed in the Servers view.
4. Double-click the server and switch to the Connectivity tab.
5. In the All Destinations section, choose the

New Destination button.

6. In the New Destination dialog box, enter the name Session and type Mail and choose OK.

7. Configure the destination by adding the properties for port 587 (SMTP+STARTTLS) or 465 (SMTPS). To do
this, choose the Add Property button in the Properties section:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

417

To use port 587 (SMTP+STARTTLS), add the following properties:


Table 227:
Property

Value

mail.transport.protocol

smtp

mail.smtp.host

smtp.gmail.com

mail.smtp.auth

true

mail.smtp.starttls.enable

true

mail.smtp.port

587

mail.user

<gmail account name>

mail.password

<gmail account password>

The configured destination for port 587 is shown below:

For port 465 (SMTPS), use the following properties:


Table 228:
Property

Value

mail.transport.protocol

smtps

mail.smtps.host

smtp.gmail.com

mail.smtps.auth

true

mail.smtps.port

465

mail.user

<gmail account name>

mail.password

<gmail account password>

8. Save the destination to upload it to the cloud. The settings take effect when the application is next started.
9. In the Project Explorer view, select MailServlet.java and choose

Run

Run As

Run on Server .

10. Make sure that the Choose an existing server radio button is selected and select the server you have just
defined.
11. Choose Finish to deploy to the cloud. You should now see the sender screen, where you can compose and
send an e-mail

418

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.1.7

Multitenancy in the Connectivity Service

Internet Connectivity
Applications that require connection to a remote service can use the connectivity service to configure HTTP or
RFC endpoints. In a provider-managed application, such an endpoint can either be once defined by the application
provider, or by each application consumer. If the application needs to use the same endpoint, independently from
the current application consumer, the destination that contains the endpoint configuration is uploaded by the
application provider. If the endpoint should be different for each application consumer, the destination shall be
uploaded by each particular application consumer.
Destinations can be simultaneously configured on three levels: application, consumer account and subscription.
This means it is possible to have one and the same destination on more than one configuration level. For more
information, see Destinations [page 281]
Destinations visibility according to the level:
Destination uploaded on account level - it is visible for the whole account
Destination uploaded on subscription level - it is only visible for the dedicated subscription
Destination uploaded on application level - it is visible by all tenants and accounts, regardless their permission
settings
When the application accesses the destination at runtime, the connectivity service tries to first lookup the
requested destination in the consumer account on subscription level. If no destination is available there, it checks
if the destination is available on the account level of the consumer account. If there is still no destination found,
the connectivity service searches on application level of the provider account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

419

Consumer-specific destination:

If an application consumer is not allowed to specify an endpoint for a provider application, the
DestinationProvider=Application property can be set in the HTTP or RFC destination. In this case, the
destination is always read from the provider application.
Provider-specific destination:

420

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

On-Demand to On-Premise Connectivity


This connectivity type is fully applicable when working with Connectivity service 2.x.

Related Information
Multitenant Applications [page 990]
Creating a Multitenant Connectivity Application [page 1003]

1.4.1.2

Consuming the Connectivity Service (HANA XS)

This section is dedicated to SAP HANA Cloud Platform connectivity service in the HANA technology.

Introduction
You can create connectivity destinations for HANA XS applications, configure their security, adding roles and then
test them on a relevant landscape (productive or trial). Depending to your scenario, see:
Connectivity for SAP HANA XS (Productive) [page 424]
Connectivity for SAP HANA XS (Trial) [page 421]

Related Information
SAP HANA Cloud Connector [page 434]

1.4.1.2.1

Connectivity for SAP HANA XS (Trial)

Context
This section represents the usage of the connectivity service when you develop and deploy SAP HANA XS
applications in a trial environment. Currently, you can make XS destinations for consuming HTTP Internet
services only.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

421

The tutorial explains how to create a simple SAP HANA XS application which is written in server-side JavaScript
and makes use of the connectivity service for making Internet connections. In the HTTP example, the package is
named connectivity and the XS application is mapinfo. The output displays information from Google Maps
showing the distance between Frankfurt and Cologne, together with the consumed time if travelling with a car, as
all this information is provided in American English.

Features
In this case, you can develop an XS application in a trial environment at SAP HANA Cloud Platform so that the
application connects to external Internet services or resources.
XS parameter

hanatrial.ondemand.com

useProxy

true

proxyHost

proxy-trial

proxyPort

8080

useSSL

true / false

Note
The useSSL property can be set to true or false depending on the XS application's needs.

1. Initial Steps
To create and assign an XS destination, you need to have a developed HANA XS application.
If you have already created one and have opened a database tunnel, go straight to procedure 2. Create an XS
Destination File on this page.
If you need to create an XS application from scratch, go to page Creating an SAP HANA XS Application [page
59] and execute procedures 1 to 6. Then execute the procedures from this page (2 to 5).

Note
The subpackage in which you will later create your XS destination and XSJS files has to be named connectivity.

2. Create an XS Destination File


1. In the Project Explorer view, select the connectivity folder and choose

File

New

File .

2. Enter the file name google.xshttpdest and choose Finish.


3. Copy and paste the following destination configuration settings:
host = "maps.googleapis.com";

422

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

port = 80;
pathPrefix = "/maps/api/distancematrix/json";
useProxy = true;
proxyHost = "proxy-trial";
proxyPort = 8080;
authType = none;
useSSL = false;
timeout = 30000;
4. Save your changes.
5. Activate the file.

3. Create an XSJS File


1. In the Project Explorer view, select the connectivity folder and choose

File

New

File .

2. Enter the file name google_test.xsjs and choose Finish.


3. Copy and paste the following JavaScript code into the file:
var destination_package = "connectivity.mapinfo";
var destination_name = "google";
try {
var dest = $.net.http.readDestination(destination_package,
destination_name);
var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "?
origins=Frankfurt&destinations=Cologne&mode=driving&language=enUS&sensor=false");
client.request(req, dest);
var response = client.getResponse();
$.response.contentType = "application/json";
$.response.setBody(response.body.asString());
$.response.status = $.net.http.OK;
} catch (e) {
$.response.contentType = "text/plain";
$.response.setBody(e.message);
}
4. Save your changes.
5. Activate the file.

4. Grant a Role to the User


1. In the Systems view, select your system and from the context menu choose SQL Console.
2. In the SQL console, enter the following, replacing <SAP HANA Cloud user> with your user:
call
"HCP"."HCP_GRANT_ROLE_TO_USER"('p1234567890trial.myhanaxs.hello::model_access',
'<SAP HANA Cloud user>')
3. Execute the procedure. You should see a confirmation that the statement was successfully executed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

423

5. Test Your Application


Open the cockpit and proceed as described in Launching SAP HANA XS Applications [page 1009].
You will be authenticated by SAML and should then see a text similar to the following:
Hello, p1234567890,
This is the response from my SQL. The current user is: p1234567890

Related Information
XS Destination Properties [page 432]

1.4.1.2.2

Connectivity for SAP HANA XS (Productive)

Overview
This section represents the usage of the connectivity service in a productive SAP HANA instance. Below are listed
the available scenarios depending on the connectivity and authentication types you use for your development
work.

Connectivity Types
Internet Connectivity
In this case, you can develop an XS application in a productive SAP HANA instance at SAP HANA Cloud Platform
so that the application connects to external Internet services or resources.
XS parameter

hana.ondemand.com

us1.hana.ondemand.com

ap1.hana.ondemand.com

useProxy

true

true

false

proxyHost

proxy

proxy

N/A

proxyPort

8080

8080

N/A

useSSL

true / false

true / false

true / false

424

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
In the outbound scenarion, the useSSL property can be set to true or false depending on the XS
application's needs.
For more information, see Using XS Destinations for Internet Connectivity [page 426]

On-Demand to On-Premise Connectivity


In this case, you can develop an XS application in a productive SAP HANA instance at SAP HANA Cloud Platform
so that the application connects, via a cloud connector tunnel, to on-premise services and resources.
The corresponding XS parameters for all productive landscapes are the same. That is:
XS parameter

hana.ondemand.com

us1.hana.ondemand.com

ap1.hana.ondemand.com

useProxy

true

true

true

proxyHost

localhost

localhost

localhost

proxyPort

20003

20003

20003

useSSL

false

false

false

Note
When XS applications consume the connectivity service to connect to on-premise systems, the useSSL
property must always be set to false.
The communication between the XS application and the proxy listening on localhost is always via HTTP.
Whether the connection to the on-premise back-end should be HTTP or HTTPS is a matter of access control
configuration in the cloud connector. For more information, see Configuring Access Control (HTTP) [page 341].
For more information, see Using XS Destinations for On-Demand to On-Premise Connectivity [page 429]

Authentication Types
No Authenticaion
Internet via HTTP - you can directly connect to an Internet service.
Internet via HTTPS - you need to use SSL certificate to access an Internet service. To meet this requirement,
proceed as follows:
1. As a prerequisite, you need to have previously exported a certificate for the relevant HTTPS site.
2. Then, open a Web browser and start the SAP HANA XS Administration Tool (https://
<schema><account>.<host>sap/hana/xs/admin/).
3. On the XS Applications page, expand the nodes in the application tree to locate your application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

425

4. Select the .xshttpdest file to display details of the HTTP destination and then choose Edit.
5. In the AUTHENTICATION section, leave the None radio button selected..
6. Select the Use SSL checkbox and from the Trust Store field choose your certificate.
7. Save your entries.

Basic Authentication
You need credentials to access an Internet or on-premise service. To meet this requirement, proceed as follows:
1. Open a Web browser and start the SAP HANA XS Administration Tool (https://
<schema><account>.<host>/sap/hana/xs/admin/).
2. On the XS Applications page, expand the nodes in the application tree to locate your application.
3. Select the .xshttpdest file to display details of the HTTP destination and then choose Edit.
4. In the AUTHENTICATION section, choose the Basic radio button.
5. Enter the credentials for the on-premise service.
6. Save your entries.

1.4.1.2.2.1 Using XS Destinations for Internet Connectivity

Context
This tutorial explains how to create a simple SAP HANA XS application, which is written in server-side JavaScript
and makes use of the connectivity service for making Internet connections.
In the HTTP example, the package is named connectivity and the XS application is mapinfo. The output displays
information from Google Maps showing the distance between Frankfurt and Cologne, together with the consumed
time if travelling with a car, as all this information is provided in American English..

Note
You can check another outbound connectivity example (financial services that display the latest stock values)
in SAP HANA Developer Guide section "8.4.1 Tutorial: Using the XSJS Outbound API ".

Prerequisites
You have a productive SAP HANA instance. For more information, see Using a Productive SAP HANA
Database System [page 1010].
You have installed the SAP HANA tools. For more information, see Installing SAP HANA Tools for Eclipse
[page 58].

426

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. Initial Steps
To create and assign an XS destination, you need to have a developed HANA XS application.
If you have already created one and have opened a database tunnel, go straight to procedure 2. Create an XS
Destination File on this page.
If you need to create an XS application from scratch, go to page Creating an SAP HANA XS Application [page
59] and execute procedures 1 to 6. Then execute the procedures from this page (2 to 5).

Note
The subpackage in which you will later create your XS destination and XSJS files has to be named connectivity.

2. Create an XS Destination File


1. In the Project Explorer view, select the connectivity folder and choose

File

New

File .

File

New

File .

2. Enter the file name google.xshttpdest and choose Finish.


3. Copy and paste the following destination configuration settings:
host = "maps.googleapis.com";
port = 80;
pathPrefix = "/maps/api/distancematrix/json";
useProxy = true;
proxyHost = "proxy";
proxyPort = 8080;
authType = none;
useSSL = false;
timeout = 30000;
4. Save your changes.
5. Activate the file.

3. Create an XSJS File


1. In the Project Explorer view, select the connectivity folder and choose
2. Enter the file name google_test.xsjs and choose Finish.
3. Copy and paste the following JavaScript code into the file:
var destination_package = "connectivity.mapinfo";
var destination_name = "google";
try {
var dest = $.net.http.readDestination(destination_package,
destination_name);
var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "?
origins=Frankfurt&destinations=Cologne&mode=driving&language=enUS&sensor=false");
client.request(req, dest);
var response = client.getResponse();

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

427

$.response.contentType = "application/json";
$.response.setBody(response.body.asString());
$.response.status = $.net.http.OK;
} catch (e) {
$.response.contentType = "text/plain";
$.response.setBody(e.message);
}
4. Save your changes.
5. Activate the file.

Note
To consume an Internet service via HTTPS, you need to export your HTTPS service certificate into X.509
format, to import it into a trust store and to assign it to your activated destination. You need to do this in the
SAP HANA XS Administration Tool (https://<schema><account>.<host>/sap/hana/xs/admin/). For more
information, see SAP HANA Developer Guide section "3.6.2 SAP HANA XS Application Authentication".

4. Grant a Role to the User


1. In the Systems view, expand

Security

Users

and then double-click your user ID.

2. On the Granted Roles tab, choose the + (Add) button.


3. Select the model_access role in the list and choose OK. The role is now listed on the Granted Roles tab.
4. Choose Deploy in the upper right corner of screen. A message confirms that your user has been modified.

5. Test Your Application


Open the cockpit and proceed as described in Launching SAP HANA XS Applications [page 1009].
You will be authenticated by SAML and should then see a text similar to the following:
Hello, p1234567890,
This is the response from my SQL. The current user is: p1234567890

Additional Example
You can also see an example for enabling server-side JavaScript applications to use the outbound connectivity
API. For more information, see SAP HANA Developer Guide section "8.4.1 Tutorial: Using the XSJS Outbound
API".

Related Information
XS Destination Properties [page 432]

428

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]

1.4.1.2.2.2 Using XS Destinations for On-Demand to OnPremise Connectivity

Context
This tutorial explains how to create a simple SAP HANA XS application that consumes a sample back-end system
exposed via the cloud connector.
In this example, the XS application consumes an on-premise system with basic authentication on landscape
hana.ondemand.com.

Prerequisites
You have a productive SAP HANA instance. For more information, see Using a Productive SAP HANA
Database System [page 1010].
You have installed the SAP HANA tools. For more information, see Installing SAP HANA Tools for Eclipse
[page 58]. You need them to open a Database Tunnel.
You have cloud connector 2.x installed on an on-premise system. For more information, see Installing the
Cloud Connector [page 436].
A sample back-end system with basic authentication is available on an on-premise host. For more
information, see Setting Up an Application as a Sample Back-End System [page 382].
You have created a tunnel between your account and a cloud connector. For more information, see Initial
Configuration [page 459] section "Establishing Connections to SAP HANA Cloud Platform".
The back-end system is exposed for the SAP HANA XS application via cloud connector configuration using as
settings: virtual_host = virtualpingbackend and virtual_port = 1234. For more information, see
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362].

Note
The last two prerequisites can be achieved by exposing any other available HTTP service in your on-premise
network. In this case, you shall adjust accordingly the pathPrefix value, mentioned below in procedure "2.
Create an XS Destination File".

1. Initial Steps
To create and assign an XS destination, you need to have a developed HANA XS application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

429

If you have already created one and have opened a database tunnel, go straight to procedure 2. Create an XS
Destination File on this page.
If you need to create an XS application from scratch, go to page Creating an SAP HANA XS Application [page
59] and execute procedures 1 to 6. Then execute the procedures from this page (2 to 6).

Note
The subpackage in which you will later create your XS destination and XSJS files has to be named connectivity.

2. Create an XS Destination File


1. In the Project Explorer view, select the connectivity folder and choose

File

New

File .

2. Enter the file name odop.xshttpdest and choose Finish.


3. Copy and paste the following destination configuration settings:
host = "virtualpingbackend";
port = 1234;
useSSL = false;
pathPrefix = "/BackendAppHttpBasicAuth/basic";
useProxy = true;
proxyHost = "localhost";
proxyPort = 20003;
timeout = 3000;

Note
In case you use SDK with a version equal to or lower than 1.44.0.1 (Java Web) and 2.24.13 (Java EE 6
Web Profile) respectively, you should find the on-premise WAR files in directory <SDK_location>/
tools/samples/connectivity/onpremise. Also, the pathPrefix should be /
PingAppHttpBasicAuth/pingbasic.
4. Save your changes.
5. Activate the file.

3. Create an XSJS File


1. In the Project Explorer view, select the connectivity folder and choose

File

New

File .

2. Enter the file name ODOPTest.xsjs and choose Finish.


3. Copy and paste the following JavaScript code into the file:
$.response.contentType = "text/html";
var dest = $.net.http.readDestination("connectivity","odop");
var client = new $.net.http.Client();
var req = new $.web.WebRequest($.net.http.GET, "");
client.request(req, dest);
var response = client.getResponse().body.asString();
$.response.setBody(response);

430

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Save your changes.


5. Activate the file.

Note
You also need to enter your on-premise credentials. You should not enter them in the destination file since they
must not be exposed as plain text.

4. Provide Secured Credentials


1. Open a Web browser and start the SAP HANA XS Administration Tool (https://
<schema><account>.<host>/sap/hana/xs/admin/).
2. On the XS Applications page, expand the nodes in the application tree to locate your application.
3. Select the odop.xshttpdest file to display the HTTP destination details and then choose Edit.
4. In section AUTHENTICATION, choose the Basic radio button.
5. Enter your on-premise credentials (user and password).
6. Save your entries.

Note
If you later need to make another configuration change to your XS destination, you need to enter your
password again since it is no longer remembered by the editor.

5. Grant a Role to the User


1. In the Systems view, expand

Security

Users

and then double-click your user ID.

2. On the Granted Roles tab, choose the + (Add) button.


3. Select the model_access role in the list and choose OK. The role is now listed on the Granted Roles tab.
4. Choose Deploy in the upper right corner of screen. A message confirms that your user has been modified.

6. Test Your Application


Open the cockpit and proceed as described in Launching SAP HANA XS Applications [page 1009].
You will be authenticated by SAML and should then see a text similar to the following:
Hello, p1234567890,
This is the response from my SQL. The current user is: p1234567890

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

431

Principal Propagation to on-premise systems


Principal Propagation scenario is available for HANA XS applications. It is used for propagating the currently
logged in user to an on-premise backend system using the cloud connector and connectivity service. To configure
the scenario make sure to:
1.Create an XS destination with the parameter authType=SamlAssertionPropagation.
2.Open the cloud connector and mark your HANA instance as trusted in the Principal Propagation tab. The HANA
instance name is displayed in the cockpit under
see Setting Up Trust [page 480].

Persistence

Databases & Schemas . For more information,

Related Information
XS Destination Properties [page 432]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]

1.4.1.2.2.3 XS Destination Properties


XS Property

Description

Value

host

It enables you to specify the host name


of the HTTP destination providing the
service or data you want your SAP
HANA XS application to access.

URL (string)

port

It enables you to specify the port


number to use for connections to the
HTTP destination hosting the service or
data you want your SAP HANA XS
application to access.

For Internet connection: 80, 443

For on-demand to on-premise


connection: 1080

For service-to-service connection:

8443

pathPrefix

It enables you to specify a text element


to add to the start of the URL used for
connections to the service specified in
the HTTP destination configuration.

useProxy

It enables you to specify whether a


proxy server must be used to resolve
the host name specified in the HTTP
destination configuration file.

Depends on the authentication type and

the landscape on which you deploy your


SAP HANA XS application.

432

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

"..."; (string)

For hana.ondemand.com:

Internet: true

On-premise: true

Service-to-service: true

For us1.hana.ondemand.com:

Internet: true

On-premise: true

Service-to-service: false

SAP HANA Cloud Platform


SAP HANA Cloud Platform

XS Property

Description

Value

For ap1.hana.ondemand.com:

proxyHost

Depending on the authentication type


and the landscape on which you deploy
your SAP HANA XS application.

proxyPort

Depending on the authentication type


and the landscape on which you deploy
your SAP HANA XS application.

On-premise: true

Service-to-service: false

For hana.ondemand.com:

Internet: proxy

On-premise: localhost

Service-to-service: proxy

For us1.hana.ondemand.com:

Internet: proxy

On-premise: localhost

Service-to-service: N/A

For ap1.hana.ondemand.com:

Internet: N/A

On-premise: localhost

Service-to-service: N/A

For hana.ondemand.com:

Internet: 8080

On-premise: 20003

Service-to-service: 8080

For us1.hana.ondemand.com:

Internet: false

Internet: 8080

On-premise: 20003

Service-to-service: N/A

For ap1.hana.ondemand.com:

Internet: N/A

On-premise: 20003

Service-to-service: N/A

authType

It enables you to specify the


authentication method that must be
used for connection requests for the
service located at the HTTP destination
specified in the configuration.

none, basic, AssertionTicket,


SAML Assertion Propagation

useSSL

It is of type Boolean and enables you to


specify whether the outbound
connection between SAP HANA XS and
the HTTP destination is secured with
the Secure Sockets Layer (SSL)
protocol (HTTPS).

true, false

timeout

It enables you to specify for how long (in -1 (default)


milliseconds) an application tries to
connect to the remote host specified in In the connectivity tutorials: 3000
the HTTP destination configuration.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

433

Related Information
SAP HANA Developer Guide section "3.7.3 HTTP Destination Configuration Syntax"

1.4.1.3

SAP HANA Cloud Connector

Caution
The cloud connector must not be used with products other than SAP HANA Cloud Platform.

Context
The cloud connector serves as the link between on-demand applications in SAP HANA Cloud Platform and
existing on-premise systems. It combines an easy setup with a clear configuration of the systems that are
exposed to SAP HANA Cloud Platform. In addition, you can control the resources available for the cloud
applications in those systems. Thus, you can benefit from your existing assets without exposing the whole internal
landscape.
The cloud connector runs as on-premise agent in a secured network and acts as a reverse invoke proxy between
the on-premise network and SAP HANA Cloud Platform. Due to its reverse invoke support, you don't need to
configure the on-premise firewall to allow external access from the cloud to internal systems. The cloud connector
provides fine-grained control over:
On-premise systems and resources that shall be accessible by cloud applications;
Cloud applications that shall make use of the cloud connector.
You can use the cloud connector in business critical enterprise scenarios. The tool takes care to automatically reestablish broken connections, provides audit logging of the inbound traffic and configuration changes, and can be
run in a high-availability setup.
In the Scenarios section below, follow the steps according to the protocol you need to use (HTTP or RFC).

Advantages
Compared to the approach of opening ports in the firewall and using reverse proxies in the DMZ to establish
access to on-premise systems, the cloud connector has the following advantages:
The firewall of the on-premise network does not have to open an inbound port to establish connectivity from
SAP HANA Cloud Platform to an on-premise system. In the case of allowed outbound connections, no
modifications are required.
The cloud connector supports additional protocols, apart from HTTP. For example, the RFC protocol supports
native access to ABAP systems by invoking function modules.

434

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The cloud connector can be used to connect on-premise database, or BI tools to SAP HANA databases in the
cloud. That means, it also supports the opposite connection direction (from the on-premise system to the
cloud).
The cloud connector allows propagating identity of cloud users to on-premise systems in a secure way.
The cloud connector is easy to install and configure, that is, it comes with a low TCO and fits well to cloud
scenarios. SAP provides standard support for it.

Scenarios
Note
Depending on the type of installation setup, the cloud connector can also be installed in an environment
managed by SAP or a 3rd party provider. In this case, special procedures may apply for configuration. If so,
they are mentioned in the corresponding configuration steps.

Connecting Cloud Applications to On-Premise Systems


Table 229:
1.

Install the cloud connector. [page 436]

2. Set up mutual authentication between the cloud connector and a back-end


system:
Initial Configuration [page 459]
Initial Configuration (HTTP) [page 339]
Initial Configuration (RFC) [page 391]
3. Allow your Web application to access a back-end system on the intranet:
Configuring Access Control (HTTP) [page 341]
Configuring Access Control (RFC) [page 392]
4. Connect your Web application to an on-premise system:
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile)
[page 362]
Tutorial: Invoking ABAP Function Modules in On-Premise ABAP Systems
[page 399]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

435

Connecting On-Premise Database Tools to SAP HANA Databases


Table 230:
1.

Install the cloud connector. [page 436]

2. Configure service channels to access HANA databases on SAP HANA


Cloud Platform. [page 470]
3. Connect on-premise database or BI tools to a HANA database on SAP
HANA Cloud Platform. [page 472]

What's new?
You can follow the release notes
connector.

of SAP HANA Cloud Platform to stay informed about updates of the cloud

Related Information
Upgrading the Cloud Connector [page 458]
Cloud Connector Operator's Guide [page 524]

1.4.1.3.1

Installing the Cloud Connector

Choose one of the procedures listed below to install cloud connector 2.x depending on your preferable operating
system.
On Microsoft Windows and Linux, two installation modes are available: Developer version and Productive
version. On Mac OS X, only the Developer version is available.
Developer version - it can be easily installed by just extracting a compressed archive into an empty
directory. It does not require administrator or root privileges for the installation. Restrictions:
It cannot be run in the background as a Windows Service or Linux daemon (with automatic start
capabilities at boot time).
It does not support an automatic upgrade procedure. So, if you want to update a Developer installation,
you will have to delete the current installation, extract the new version, and then re-do the configuration.

436

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Productive version - it requires administrator or root permissions for the installation and can be set up to
run as a Windows Service or Linux daemon in the background. It can also be easily upgraded, retaining all the
configuration and customizing.

Prerequisites
There is a list of prerequisites you need to fulfill to successfully install the cloud connector 2.x. For more
information, see Prerequisites [page 437].

Tasks
Installation on Microsoft Windows OS [page 440]
Installation on Linux OS [page 443]
Installation on Mac OS X [page 445]

Related Information
Recommendations for Secure Setup [page 446]
Recommended: Replacing the Default SSL Certificate [page 452]
Uninstalling the Cloud Connector [page 523]

1.4.1.3.1.1 Prerequisites
The listed prerequisites below need to be fulfilled for successful installation of the cloud connector 2.x.

Connectivity Restrictions
For general information about SAP HANA Cloud Platform restrictions, see Product Prerequisites and Restrictions
[page 8].
For specific information about all connectivity restrictions, see Connectivity Service [page 267] section
"Restrictions".

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

437

Hardware
Hardware prerequisites, physical or virtual machine:
Memory: mininum 1 GB RAM, 4 GB recommended
Hard disk space: minimum 1 GB, recommended 20 GB
CPU: minimum single core 3 GHz, dual core 2 GHz recommended, x86-64 architecture compatible

Software
You have downloaded the cloud connector installation archive from SAP Development Tools for Eclipse.
A JDK 7 needs to be installed. Due to problems with expired root CA certificates contained in older patch
levels of JDK 7, we recommend that you install the most recent patch level. An up-to-date SAP JVM can be
downloaded from the SAP Development Tools for Eclipse page as well.

Caution
Do not use Apache Portable Runtime (APR)
on the system on which you use the cloud connector. If you
cannot avoid this restriction and want to use APR at your own risk, you need to manually adopt the defaultserver.xml configuration file in directory <scc_installation_folder>/config_master/
org.eclipse.gemini.web.tomcat. To do so, follow the documentation of the HTTPS port configuration
for APR.

Supported JDKs
Table 231:
JDK

Version

Cloud Connector Version

SAP JVM 64-bit (recommended)

2.x

2.7.2 and higher

2.x

2.7.2 and higher

Oracle JDK 64-bit

438

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Network
You need to have Internet connection at least to the following hosts (depending on the data center), to which you
can connect your cloud connector:
Table 232:
Data Center (Landscape host)

Hosts

IP Addresses

Europe

connectivitynotification.hana.onde
mand.com

155.56.210.83

connectivitycertsigning.hana.onde
mand.com

155.56.210.43

(hana.ondemand.com)

connectivitytunnel.hana.ondemand.com 155.56.210.84
United States East
(us1.hana.ondemand.com)

United States West


(us2.hana.ondemand.com)

Asia-Pacific (Australia)
(ap1.hana.ondemand.com)

Trial (Europe only)


(hanatrial.ondemand.com)

connectivitynotification.us1.hana.onde
mand.com

65.221.12.40

connectivitycertsigning.us1.hana.onde
mand.com

65.221.12.241

connectivitytunnel.us1.hana.onde
mand.com

65.221.12.41

connectivitynotification.us2.hana.onde
mand.com

64.95.110.215

connectivitycertsigning.us2.hana.onde
mand.com

64.95.110.211

connectivitytunnel.us2.hana.onde
mand.com

64.95.110.214

connectivitynotification.ap1.hana.onde
mand.com

210.80.140.247

connectivitycertsigning.ap1.hana.onde
mand.com

210.80.140.227

connectivitytunnel.ap1.hana.onde
mand.com

210.80.140.246

connectivitynotification.hanatrial.onde
mand.com

155.56.219.26

connectivitycertsigning.hanatrial.onde
mand.com

155.56.219.22

connectivitytunnel.hanatrial.onde
mand.com

155.56.219.27

Product Availability Matrix

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

439

Table 233:
Operating System Version

Architecture

Cloud Connector Version

Windows 7, Windows Server 2008 R2

x86_64

2.x

SUSE Linux Enterprise Server 11, Redhat

x86_64

2.x

Mac OS X 10.7 (Lion), Mac OS X 10.8


(Mountain Lion)

x86_64

2.x

Windows 8.1, Windows Server 2012,


Windows Server 2012 R2

x86_64

2.5.1 and higher

SUSE Linux Enterprise Server 12, Redhat x86_64


Enterprise Linux 7

2.5.1 and higher

Mac OS X 10.9 (Mavericks), Mac OS X


10.10 (Yosemite)

x86_64

2.5.1 and higher

Windows 10

x86_64

2.7.2 and higher

Enterprise Linux 6

Related Information
Installation on Microsoft Windows OS [page 440]
Installation on Linux OS [page 443]
Installation on Mac OS X [page 445]
Recommendations for Secure Setup [page 446]

1.4.1.3.1.2 Installation on Microsoft Windows OS

Prerequisites
You have either of the following 64-bit operating systems: Windows 7, Windows 8.1, Windows Server 2008 R2,
Windows Server 2012, or Windows Server 2012 R2
You have downloaded either the ZIP archive for the developer's use case on Windows, or the MSI installer for
productive usage from the SAP Development Tools for Eclipse page.
You need to install Microsoft Visual Studio C++ 2010 runtime libraries. For more information, see Microsoft
Visual Studio C++ 2010 Redistributable Package (x64)

Note
Even if you have a more recent version of the Microsoft Visual C++ runtime libraries, you still need to install
the Microsoft Visual Studio C++ 2010 libraries.

440

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Java 7 needs to be installed. In case you want to use SAP JVM, you can download it from the SAP
Development Tools for Eclipse page.
Environment variable <JAVA_HOME> needs to be set to the Java installation directory, so that the bin
subfolder can be found. Alternatively, when using the ZIP file, you can add the relevant bin directory to the
<PATH> variable.

Context
You can choose between a simple ZIP installer of the cloud connector and the MSI-based installer. The installer is
the generally recommended means that can be used for both developer and productive scenarios. It takes care,
for example, to register the cloud connector as a Windows service and this way to automatically start it after
machine reboot.

Tip
If you are a developer, you might want to use the ZIP installer as you can run the cloud connector after a simple
unzip (archive extraction). You might want to use it also if you cannot perform a true installation due to lack of
permissions, or if you need to use multiple versions of the cloud connector simultaneously on the same
machine.

Procedure
Developer Scenario
1. Extract the <sapcc-<version>-windows-x64.zip> ZIP file to an arbitrary directory on your local file
system.
2. Set the environment variable JAVA_HOME to the installation directory of the JDK you want to use to run the
cloud connector. (Alternatively, you can add the bin subdirectory of the JDK installation directory to the
PATH environment variable.)
3. Change to the cloud connector installation directory and start it via the go.bat batch file.
4. Continue with the Next Steps section.

Note
Cloud connector 2.x is not started as a service in the Developer's use case, and hence will not automatically
start after a reboot of your system. Also, the Developer version does not support the automatic upgrade
procedure.

Productive Scenario

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

441

1. Start the <sapcc-<version>-windows-x64.msi> installer by double-clicking it.


2. The installer informs you that you are now guided through the installation process. Choose Next>.
3. Navigate to the desired installation directory for your cloud connector and choose Next>. When doing the
installation in the context of an upgrade, make sure that you choose the previous installation directory again.
4. You can choose the port on which the administration UI is reachable. Either leave the default 8443 or choose a
different port if needed. Then choose Next>.
5. Select the JDK to be used for running the cloud connector. The installer will display a list of all JDKs of version
7 that are installed on your machine. If the needed JDK is not listed in the drop-down box (for example, if it's
an SAP JVM that is not registered in the Windows Registry upon installation), you can browse to its
installation directory and select it. We recommend that you use an up-to-date Java 7 installation to run the
cloud connector.
6. On this step, decide whether the cloud connector should be started immediately after finishing the setup. If
you do not want this now, remove the check from the checkbox. Then choose Next>.
7. After all installation options have been fulfilled, if you really want to install, press again the Next> button.
8. In up to a few seconds, the installation has been done. To finish the installer, choose the Close button.
9. Continue with the Next Steps section.

Note
Cloud connector 2.x is started as a Windows Service in the Productive use case. Hence, installation requires
administration permissions. After installation, the service should be administrated under
Administrative Tools

Control Panel

Services . The service name is Cloud Connector 2.0. Make sure that the service is

executed with a user that has limited privileges. Typically, privileges allowed for service users are defined by
your company policy. Afterwards, you should adjust the folder and file permissions to be manageable by only
this user and system administrators.

Next Steps

1. In a browser, enter: https://<hostname>:8443, where <hostname> is the host name of the machine on
which you have installed the cloud connector.
If you access the cloud connector locally from the same machine, you can just enter localhost.
2. Continue with initial configuration of the cloud connector 2.x. It works in the same way as for version 1.x.
For more information, see Initial Configuration [page 459].

Related Information
(Optional) Installing SAP JVM [page 35]
Recommendations for Secure Setup [page 446]
Recommended: Replacing the Default SSL Certificate [page 452]

442

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.3.1.3 Installation on Linux OS

Prerequisites
You have either of the following 64-bit operating systems: SUSE Linux Enterprise Server 11 or 12, or Redhat
Enterprise Linux 6 or 7
You have downloaded either the tar.gz archive for the Developer's use case on Linux or the RPM contained
in the ZIP for Linux for productive usage, from the SAP Development Tools for Eclipse page.
Java 7 needs to be installed. In case you want to use SAP JVM, you can download it from the SAP
Development Tools for Eclipse page as well. When installing it via the RPM package, the cloud connector will
detect it and use it for its runtime.
When using the tar.gz archive, the environment variable <JAVA_HOME> needs to be set to the Java
installation directory, so that the bin subdirectory can be found. Alternatively, you can add the Java
installation's bin subdirectory to the <PATH> variable.

Context
You can choose between a simple TGZ installer of the cloud connector and the RPM-based installer. The installer
is the generally recommended means that can be used for both developer and productive scenarios. It takes care,
for example, of registering the cloud connector as a daemon service and this way to automatically start it after
machine reboot.

Tip
If you are a developer, you might want to use the TGZ installer as you can run the cloud connector after a
simple "tar -xzof" execution. You might want to use it also if you cannot perform a true installation due to
lack of operating system permissions, or if you need to use multiple versions of the cloud connector
simultaneously on the same machine.

Developer Scenario
1. Extract the tar.gz file to an arbitrary directory on your local file system using the following command:
tar -xzof sapcc-<version>-linux-x64.tar.gz
Note that by using parameter "o", the extracted files will be assigned to the user ID and the group ID of the
user that has unpacked the archive. This is the default behavior for users other than root.
2. Change to this directory and start the cloud connector via the go.sh script.
3. Continue with the Next Steps section.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

443

Note
In this case, cloud connector 2.x is not started as a daemon, and hence will not automatically start after a
reboot of your system. Also, the Developer version does not support the automatic upgrade procedure.

Productive Scenario
1. Extract the <sapcc-<version>-linux-x64.zip> archive to an arbitrary directory.
2. Change to this directory and install the extracted RPM using the following command. Note that this step
requires you to be root.
rpm -i com.sap.scc-ui-<version>.rpm
3. Continue with the Next Steps section.
In the productive case, cloud connector 2.x is started as daemon. If you need to manage the daemon process,
execute:
service scc_daemon stop|restart|start|status

Caution
When adjusting the cloud connector installation (for example, restoring a backup), make sure that the RPM
package management is synchronized with such changes. In the case when you simply replace files which do
not fit to the information stored in the package management, lifecycle operations (such as upgrade or
uninstallation) might later fail with errors. Or even worse - the cloud connector could get into unrecoverable
state.
Example: After a file system restore, the system files represent cloud connector 2.3.0 but the RPM package
management "believes" version 2.4.3 is installed. In this case, commands like rpm -U and rpm -e will not work
as expected. Furthermore, avoid the usage of the --force parameter as it may lead to unpredictable state
with two versions being installed concurrently, which is not supported.

Next Steps
1. In a browser, enter: https://<hostname>:8443, where <hostname> is the host name of the machine on
which you have installed the cloud connector.
If you access the cloud connector locally from the same machine, you can just enter localhost.
2. Continue with initial configuration of the cloud connector 2.x. It works in the same way as for version 1.x.
For more information, see Initial Configuration [page 459].

444

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Recommendations for Secure Setup [page 446]
Recommended: Replacing the Default SSL Certificate [page 452]

1.4.1.3.1.4 Installation on Mac OS X

Prerequisites

Note
Mac OS X is not supported for productive scenarios. The developer version described below must not be used
as productive version.
You have either of the following 64-bit operating systems: Mac OS X 10.7 (Lion), Mac OS X 10.8 (Mountain
Lion), Mac OS X 10.9 (Mavericks), or Mac OS X 10.10 (Yosemite)
You have downloaded the tar.gz archive for the developer use case on Mac OS X from the SAP
Development Tools for Eclipse page.
Java 7 needs to be installed. In case you want to use SAP JVM, you can download it from the SAP
Development Tools for Eclipse as well.
Environment variable <JAVA_HOME> needs to be set to the Java installation directory so that the bin
subfolder can be found. Alternatively, you can add the Java installation's bin subdirectory to the <PATH>
variable.

Procedure
1. Extract the tar.gz file to an arbitrary directory on your local file system using the following command:
tar -xzof sapcc-<version>-macosx-x64.tar.gz
2. Change to this directory and start cloud connector 2.x via the go.sh script.
3. Continue with the Next Steps section.

Note
Cloud connector 2.x is not started as a daemon, and hence will not automatically start after a reboot of
your system. Also, the Mac OS X version of cloud connector 2.x does not support the automatic upgrade
procedure.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

445

Next Steps
1. In a browser, enter: https://<hostname>:8443, where <hostname> is the host name of the machine on
which you have installed the cloud connector.
If you access the cloud connector locally from the same machine, you can just enter localhost.
2. Continue with initial configuration of the cloud connector 2.x. It works in the same way as for version 1.x.
For more information, see Initial Configuration [page 459].

Related Information
Recommendations for Secure Setup [page 446]
Recommended: Replacing the Default SSL Certificate [page 452]

1.4.1.3.1.5 Recommendations for Secure Setup


Overview
The following guideline should be applied by customers who use SAP HCP connectivity service and the cloud
connector to guarantee the highest level of security. To assist the administrator with this task the current security
status is shown in the top left corner as a button with an icon. Details can be viewed by pressing that button.

The General Security Status addresses security topics that are account-independent.
Press any of the colored buttons to navigate to the UI area that deals with that particular topic.
Navigation is not possible for the last item in the list, namely the Service User.
The service user is specific to the Windows Operating System (see Installation on Microsoft Windows OS
[page 440] for details) and is only visible when running the cloud connector on Windows. It cannot be
addressed through the UI. If the service user was set up properly, check the check box.

446

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The Account-Specific Security Status lists security-related information for each and every account. Both the
account-specific and the general security status are aggregated to obtain a summary of the security status that
can then be displayed as the icon of the button mentioned above.

Note
The security status is purely of an informational nature and merely serves as a reminder to address security
issues or as confirmation that your installation complies with all recommended security settings.

Password Policy for the Cloud Connector Administration UI


Once installed, the cloud connector provides an initial user name and password and forces the user
(Administrator) to change the password upon initial login. The password should be changed from the initial
password to a specific one immediately after installation.
The connector itself does not check the strength of the password. The cloud connector administrator must select
a strong password that cannot be guessed easily.

Note
To enforce your company's password policy, we recommend that you configure the Administration UI to use an
LDAP server for authorizing access to the UI.

Restricting OS Level Access to Machines with Cloud Connector Installation


The cloud connector is a security critical component that handles the external access to systems of an isolated
network, comparable to a reverse proxy. We therefore recommend to restrict the access to the operating system
on which the cloud connector is installed to the minimal set of users who shall administrate the cloud connector.
This will minimize the risk of unauthorized people getting access to credentials, such as certificates stored in the
secure storage of the cloud connector.
Following the same arguments, we recommend that you use the machine to operate the cloud connector only and
no other systems.

Cloud Connector Administrator Privileges


To log on to the cloud connector administration UI, the "Administrator" user of the connector must not have an
OS user for the machine on which the connector is running. This allows the OS administrator to be distinguished
from the cloud connector administrator. To make an initial connection between the connector and a particular
SAP HANA Cloud account, an SAP HANA Cloud user with the needed permissions for the related account is
required. We recommend that you separate these roles/duties (that means, you have separate users for cloud
connector administrator and SAP HANA Cloud).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

447

Note
We recommend that only a small number of users be granted access to the machine as root.

Using Hard-Drive Encryption for Machines with Cloud Connector Installations


This ensures that the cloud connector configuration data cannot be read by unauthorized users, even if they
obtain access to the hard drive.

Accessing the Cloud Connector Administration UI


The cloud connector administration UI can be remotely accessed via HTTPS. The connector uses a standard X.
509 self-signed certificate as SSL server certificate. The certificate can be exchanged by a customer-specific
certificate that is trusted by the customer. For more information, see Recommended: Replacing the Default SSL
Certificate [page 452].
We recommend that you limit the access to the administration UI to localhost. Thus, you can restrict the access to
a browser that is running on the same server as the cloud connector.

Note
Since browsers usually do not resolve localhost to the host name while the certificate usually is created under
the host name, you might get a certificate warning. In this case, just skip the warning message.
Proceed as follows:
1. Open the default-server.xml file of the Web container provided as part of the cloud connector:
Microsoft Windows OS: <install_dir>\config_master\org.eclipse.gemini.web.tomcat
\default-server.xml
Linux OS/Mac OS X: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/
default-server.xml
2. Modify the SSL Connector configuration in the <Host> section, which makes the Web container listen to the
localhost only (that is, IP address 127.0.0.1):
<Connector port="8443" address="127.0.0.1" protocol="HTTP/1.1" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
keystoreFile="config/ks.store" keystorePass="${jks.password}"
truststoreFile="config/ks.store" truststorePass="${jks.password}"
keyPass="${jks.password}" keyAlias="tomcat"
clientAuth="want" sslProtocol="TLS"
sslEnabledProtocols="TLSv1,TLSv1.1,TLSv1.2"
ciphers="TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_RSA
_WITH_AES_128_CBC_SHA,TLS_DHE_RSA_WITH_AES_128_CBC_SHA256,TLS_DHE_DSS_WITH_AES_12
8_CBC_SHA,TLS_DHE_DSS_WITH_AES_128_CBC_SHA256"
compression="on" compressionMinSize="1024"
noCompressionUserAgents="gozilla,traviata,*MSIE 6.*"
compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/
css,text/json,application/x-javascript,application/javascript,application/json"
/>

448

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Caution
With regards to ciphers and sslEnabledProtocols, make sure that these parameters work correctly
with the JCE you are using with your Java Virtual Machine. If they don't, you will not be able to use the High
Availability setup, or the UI administration port may not start at all. If you need to modify the ciphers we
recommend to use the respective section of the settings UI (see Selecting Encryption Ciphers below).

Supported Protocols for On-Demand to On-Premise Connectivity


Currently, HTTP, HTTPS and RFC are supported as the protocols between SAP HANA Cloud Platform and onpremise systems when the cloud connector and the connectivity service are used. The whole route from the
application virtual machine in the cloud to the cloud connector is always SSL-encrypted.
The route from the connector to the back-end system can be SSL-encrypted or SNC-encrypted.
For more information, see Configuring Access Control (HTTP) [page 341] and Configuring Access Control (RFC)
[page 392].

Switching On Audit Log on Operating System Level


We recommend that you turn on the audit log on operating system level to monitor the file operations.

Switching On Audit Log on Cloud Connector Level


The cloud connector audit log must remain switched on during the time it is used with productive systems (set it
to audit level "ALL"; the default one is "SECURITY"). The administrators responsible for a running cloud connector
are obliged to ensure that the audit log files are properly archived and do not get lost, in order to conform to the
local regulations. Additionally, audit logging should be switched on in the connected back-end systems.
Cloud connector administrators should not be authorized to modify files on operating system (OS) level, and OS
administrators should not have access to the cloud connector administration UI.

Selecting Encryption Ciphers


By default, all available encryption ciphers are supported for HTTPS connections to the administration UI.
However, some of them may not conform to your security standards and hence should be excluded. To do so,
open the Settings dialog (top right on the cloud connector administration UI) and then choose Cipher Suites from
the left panel of that dialog.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

449

By default, all available ciphers are marked as selected. Unselect those that do not meet your security
requirements and press Save.

Note
We recommend to revert to the default (all ciphers selected) whenever you plan to switch to another JVM. As
the set of supported ciphers may differ, there is a chance that the selected ciphers may not be supported by
the new JVM. In that case the cloud connector will not start anymore, and you need to fix the issue manually
adapting the file default-server.xml (cp. attribute ciphers, see Accessing the cloud connector Administrator UI
above). After a successful switch, the list of eligible ciphers can be adjusted again.

Related Information
Connectivity via Reverse Proxy [page 451]

450

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.3.1.5.1 Connectivity via Reverse Proxy

Overview
This section outlines an alternative approach for technical connectivity between the cloud and on-premise, using a
reverse proxy. It also discusses the pros and cons of this method compared to when you use the cloud connector.

Features
An alternative approach compared to the SSL VPN solution that is provided by the cloud connector is to expose
on-premise services and applications via a reverse proxy to the Internet. For this method, there is typically a
reverse proxy setup in the "demilitarized zone" (DMZ) subnetwork of a customer, which:
Acts as a mediator between SAP HANA Cloud Platform and the on-premise services;
Provides the services of an Application Delivery Controller (ADC) in order, for example, to encrypt, filter,
route, or introspect the inbound traffic.
The figure below shows the minimal overall network topology of this approach. For more information, see
Technical Connectivity Guide .
On-premise services accessible via a reverse proxy are then callable from SAP HANA Cloud Platform like other
HTTP services available on the Internet. When you use destinations to call those services, make sure that the
configuration of the ProxyType parameter is set to Internet.

Advantages
Depending on your scenario, you can benefit from the reverse proxy. An example is the required network
infrastructure (such as a reverse proxy and ADC services): since it already exists in your network landscape, you
can reuse it to connect to SAP HANA Cloud Platform. In this case, there would be no need to set up and operate
new components on your (customer) side.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

451

Disadvantages
The reverse proxy approach does not prevent the exposed services from being generally accessible via the
Internet, which makes them vulnerable to attacks from anywhere in the world. Denial-of-Service attacks in
particular are possible and difficult to protect against. Therefore, protection against potential attacks requires
the highest security standards to be implemented in the DMZ and reverse proxy. For the productive
deployment of a hybrid cloud/on-premise application, this approach usually requires intense involvement of
the customer's IT department and a longer period of implementation.
If the reverse proxy is set to allow filtering or restriction of accepted source IP addresses, you can only set one
single IP address to be used for all SAP HANA Cloud Platform outbound communications.
Although it filters any callers that are not running on the cloud, the reverse proxy does not exclusively restrict
the access to cloud applications belonging to the related customer. Basically, any application running on the
cloud would pass this filter.
SAP-proprietary RFC protocol is not supported, so that a cloud application cannot directly call an on-premise
ABAP system without having application proxies on top of ABAP.

Note
These demerits do not exist when using the cloud connector. As it establishes the SSL VPN tunnel to SAP
HANA Cloud Platform via a reverse invoke approach, there is no need to configure the DMZ or external firewall
of a customer network for inbound traffic. Attacks from the Internet are not possible. With its simple setup and
fine-grained access control of exposed systems and resources, the cloud connector allows a high level of
security and fast productive implementation of hybrid applications. It also supports multiple application
protocols such as HTTP and RFC.

1.4.1.3.1.6 Recommended: Replacing the Default SSL


Certificate

Overview
By default, the cloud connector comes with a self-signed default certificate that is used to encrypt the
communication between the browser-based user interface and the cloud connector itself. For security reasons,
however, you should replace this certificate with your own certificate so that the browser accepts the certificate
without security warnings.
Up to version 2.5.2, for this purpose, you need to know the password of the cloud connector's Java keystore. This
password is generated during installation and then kept into encrypted secure storage area.

Note
The procedure described above, which requires the manual execution of command line commands is only
needed for versions below 2.6. As of version 2.6.0, you can easily replace the default certificate within the
Settings dialog. For more information, see Exchanging UI Certificates [page 456].

452

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Caution
The cloud connector's keystore may contain a certificate used in the High Availability setup. This certificate has
alias "ha". Be careful - any changes on it or removal would lead to disruption of communication between the
shadow and the master instance, and as a consequence - to a failed procedure. Therefore, we recommend that
you replace the keystore on both the master and shadow server before establishing the connection between
the two instances.

Procedure
You can read the password by executing the following command:
on Microsoft Windows OS:
java -cp <scc_install_dir>\plugins\com.sap.scc.rt*.jar Djava.library.path=<scc_install_dir>\auditor com.sap.scc.jni.SecStoreAccess path <scc_install_dir>\scc_config -p
on Linux OS:
java -cp /opt/sap/scc/plugins/com.sap.scc.rt*.jar Djava.library.path=/opt/sap/scc/auditor com.sap.scc.jni.SecStoreAccess path /opt/sap/scc/scc_config -p
In the next procedure, we will use the standard Java keytool tool to delete/generate/import certificates from/for/
into the cloud connector's keystore. Memorize the keystore password shown by the above command, as you will
need it for these operations.
Also make sure that you change into the directory /opt/sap/scc/config before executing the commands
described in the following.

Note
For a detailed description of the keytool tool, see http://docs.oracle.com/javase/7/docs/technotes/tools/
solaris/keytool.html .

Related Information
Exchanging UI Certificates [page 456]
Using a Self-Signed Certificate [page 454]
Using Certificates Signed by Trusted Certificate Authority [page 454]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

453

1.4.1.3.1.6.1 Using a Self-Signed Certificate

Context
If you want to use a simple, self-signed certificate, follow the procedure below.

Note
The parameter values in the following section are simply examples.
The Server configuration delivered by SAP uses the same password for key store (option \-storepass) and
key (option \-keypass) under alias tomcat.

Procedure
1. Remove the current default certificate:
keytool -delete -alias tomcat -keystore ks.store -storepass <password>
2. Generate a certificate:
keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>, O=<YourCompany>"
3. Self-sign it - you will be prompted for the keypass password defined in step 2:
keytool -selfcert -v -alias tomcat -storepass <password> -keystore ks.store

1.4.1.3.1.6.2 Using Certificates Signed by Trusted Certificate


Authority

Overview
Before starting the procedure, bear in mind that
The parameter values in the following section are simply examples.
We recommend that you use a signed certificate by a trusted CA, because it is more secure than a self-signed
certificate.
For your convenience, you can set the generated password as environment variable, like in the command
below, and then use $PASS as a password:

454

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

export PASS=`<the release-dependent command as given in the parent page>`


Keytool supports delete and changealias commands. If the cloud connector SSL Certificate is changed on
a running instance, we recommend that you prepare a new certificate under a temporary alias. Once
everything is ready, you change the alias.

Procedure
If you have a signed certificate produced by a trusted certificate authority (CA), go directly to step 3.
1. Generate your key pair if you start fresh:
keytool -genkey -v -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -dname "CN=SCC, OU=<YourCompany>, O=<YourCompany>"
Alternatively, you may reuse an existing key store.
2. Create a local Certificate Signing Request (CSR):
keytool -certreq -keyalg RSA -alias tomcat -keypass <password> -keystore
ks.store -storepass <password> -file <csr-file-name>
You now have a file called <csr-file-name> that you can submit to the Certificate Authority. In return, you
get a certificate.
3. Import the certificate chain that you obtained from your trusted CA:
keytool -import -alias root -keystore ks.store -storepass <password> trustcacerts -file <filename_of_the_certificate_chain>
4. Import your new certificate:
keytool -import -alias tomcat -keystore ks.store -storepass <password> -file
<your_certificate_filename>
The password is created at installation time and stored in the secure storage. Thus, only applications with access
can read the password. You can read password using Java:
jar -xf /opt/sap/scc/dropins/scc/plugins/com.sap.scc.tomcat.utils*.jar lib/
libsapsecstore4j.so
java -cp /opt/sap/scc/dropins/scc/plugins/com.sap.scc.tomcat.utils*.jar Djava.library.path=./lib/ com.sap.mw.scc.util.SecStoreAccess -show
You might need to adapt the configuration if you want to use another key storage file or change the current
configuration (HTTPS port, authentication type, SSL protocol, and so on). You can find the SSL configuration in
the Connector section of the file, respectively :
Microsoft Windows OS: <install_dir>\config_master\org.eclipse.gemini.web.tomcat
\default-server.xml
Linux OS: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default-server.xml

Note
We recommend that you do not modify the configuration unless you have expertise in this area.
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

455

maxThreads="150" scheme="https" secure="true"


keystoreFile="config/ks.store" keystorePass="${jks.password}" keyPass="$
{jks.password}" keyAlias="tomcat"
truststoreFile="config/ks.store" truststorePass="${jks.password}"
clientAuth="want" sslProtocol="TLS"
compression="on" compressionMinSize="1024"
noCompressionUserAgents="gozilla,traviata,*MSIE 6.*"
compressableMimeType="text/html,text/xml,text/plain,text/javascript,text/
css,text/json,application/x-javascript,application/javascript,application/json"/>

Related Information
For more information about configuring SSL, see http://tomcat.apache.org/tomcat-7.0-doc/sslhowto.html#SSL_and_Tomcat .

1.4.1.3.1.6.3 Exchanging UI Certificates


By default, the cloud connector comes with a self-signed default certificate, which is used to encrypt the
communication between the browser-based user interface and the cloud connector itself. For security reasons,
however, you should replace this certificate with your own one so that the browser accepts the certificate without
security warnings.

Procedure
Master Instance
1. Open the Settings dialog.
2. Choose UI Certificate to start a Certificate Signing Request procedure.
3. In the CSR field, specify a subject fitting to your host name.
4. Press the Generate button.

456

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. You are prompted to save the signing request in a file. The content of the file is the signing request in PEM
format.
The signing request needs to be provided to a Certificate Authority (CA) - either one within your company or
another one you trust. The CA will sign the request and the returned response should be stored in a file.
6. To import the signing response, choose Browse to locate it and then press the Import button.
7. You'll see the major certificate details in a dialog.
8. Restart the cloud connector to activate the new certificate.

Shadow Instance
The same operation is possible on the shadow instance in a high availability setup. In that case, you need to:
1. Navigate to the Administration section.
2. Expand the UI Certificate panel.
3. Proceed the same way as on the master.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

457

1.4.1.3.2

Upgrading the Cloud Connector

Choose one of the procedures listed below to upgrade your cloud connector depending on your operating system.
If you follow these steps, the previous settings and configurations will be automatically preserved.

Note
Upgrade is supported only for productive versions.

Avoid connectivity downtime


If you have a single-machine cloud connector installation, a short downtime is unavoidable during the upgrade
process. However, if you have set up a master and a shadow instance, you can perform the upgrade without
downtime by executing the following procedure:
1. Shut down the shadow instance.
2. Perform the upgrade on the shadow instance. (Follow the relevant procedure below.)
3. Start the shadow instance again and connect to the master instance.
4. Perform a Switch Roles operation by pressing the corresponding button in the master administration UI. The
master instance has now changed into a shadow instance.
5. Shut down the new shadow instance and perform the upgrade procedure on it as well.
6. Start the new shadow instance again, connect it to the new master, and then perform again the Switch Roles
operation.
Result: Both instances have now been upgraded without connectivity downtime and without configuration loss.
For more information, see Installing a Failover Instance for High Availability [page 507].

458

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Microsoft Windows OS
1. Uninstall the cloud connector as described on page Uninstalling the Cloud Connector [page 523].
2. Install again the cloud connector within the same directory. For more information, see Installation on
Microsoft Windows OS [page 440].
3. Before accessing the administration UI again, make sure to clear your browser cache in order to avoid
unpredictable behavior due to the upgraded UI.

Linux OS
1. To upgrade the cloud connector, execute:
rpm -U com.sap.scc-ui-<version>.rpm
2. Before accessing the administration UI again, make sure to clear your browser cache in order to avoid
unpredictable behavior due to the upgraded UI.

1.4.1.3.3

Initial Configuration

Context
Once the cloud connector has been installed and the cloud connector daemon has been started, you can log on
and perform the necessary customization to make your cloud connector operational. To do this, follow the
procedure below.
Go through the following steps:
Log in [page 460]
Change your password [page 461]
Set up parameters and HTTPS proxy [page 461]
Establish connections to SAP HANA Cloud Platform [page 465]

Prerequisites
We strongly recommend that you read and follow the steps described in Recommendations for Secure Setup
[page 446]. For operating the cloud connector securely, see also Guidelines for Secure Operation of cloud
connector [page 538].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

459

Log in to the Cloud Connector


To administer the cloud connector, you need a Web browser. To check the list of supported browsers, go to
Product Prerequisites and Restrictions [page 8] section "Browser Support".
1. In a Web browser, enter: https://<hostname>:<port>
<hostname> refers to the machine on which the cloud connector has been installed. If installed on your
machine, you can enter localhost.
<port> is the cloud connector port specified during installation (default port is 8443).
2. The following login screen is displayed:

3. For User Name / Password enter Administrator / manage (case sensitive).


4. Choose between master and shadow installation. Use Master if you are installing a single cloud connector
instance or a main instance from a pair of cloud connector instances. For more information, see Installing a
Failover Instance for High Availability [page 507].

460

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Change your Password


1. When you first log in, you must change the password before you continue forwards, regardless of the
installation type you have chosen.

2. You can configure again the password for the Administrator user from the Settings menu:

Set up Connection Parameters and HTTPS Proxy


Window Set Up Initial Configuration is displayed.
If your internal landscape is protected by a firewall that blocks any outgoing TCP traffic, you need to specify an
HTTPS proxy that the cloud connector can use to connect to SAP HANA Cloud Platform. Normally, you would

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

461

need to use the same proxy settings as those being used by your standard Web browser. The cloud connector
needs this proxy for two operations:
Downloading the correct connection configuration corresponding to your account ID in SAP HANA Cloud
Platform.
Establishing the SSL tunnel connection from the cloud connector to your SAP HANA Cloud Platform account.

Note
In case you want to skip the initial configuration, you can click the
icon in the upper right corner. You might
need this in case of connectivity issues described in your logs. You can add accounts later as described in page
Managing Accounts [page 474].
When you first log on, the cloud connector collects the following required information:
1. For Landscape Host, specify the SAP HANA Cloud Platform landscape that should be used. You can choose
the one you need from the dropdown list. For more information, see Landscape Hosts [page 32].
2. For Account Name, Account User and Password, enter the values you obtained when you registered your
account on SAP HANA Cloud Platform or add a new Account User [page 23] with role Cloud Connector
Admin from the Members tab in the SAP HANA Cloud cockpit and use the new user and password..

Note
If the cloud connector is installed in an environment that is operated by SAP, SAP will provide a user that
you should add as new member in your SAP HANA Cloud Platform account. In this case, please assign the
Cloud Connector Admin role (see Account Member Roles [page 27]) to the user provided by SAP. Once
the cloud connector connection is established, this user is not needed any more since it serves for initial
connection setup only. You may revoke the corresponding role assignment then and remove the user from
the Members list.
3. Optional: You can define a Display Name, which allows you to easily recognize a specific account in the UI
compared to the technical Account Name.
4. Optional: You can define a Location ID, which identifies the location of this cloud connector for a specific
account. Currently, this is only documentary but in future, it might also be used for routing purposes.
5. Enter proxy host and port. You need to specify a proxy server that supports SSL communication (a standard
HTTP proxy will not suffice).
6. Optionally: You can provide a Description (free-text) for this cloud connector instance. It helps you identify the
particular cloud connector you use.
7. When you finish with the settings, choose Apply.

462

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The cloud connector starts a handshake with SAP HANA Cloud Platform and attempts to establish a secure SSL
tunnel to the server hosting account in which your on-demand applications are running. However, no requests are
yet allowed to pass from the cloud side to any of your internal back-end systems. To allow your on-demand
applications to access specific internal back-end systems, proceed with the access configuration described in the
next section.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

463

Note
The internal network must allow access to the port. Specific configuration for opening the respective port(s)
depends on the firewall software used.
The default ports are 80 for HTTP and 443 for HTTPS. For RFC communication, you need to open a gateway
port (default: 33+<instance number> and an arbitrary message server port. For a connection to a HANA
Database (on SAP HANA Cloud Platform) via JDBC, you need to open an arbitrary outbound port in your
network. Mail (SMTP) communication is not supported.
If you later need to change your proxy settings (for example, because the company firewall rules have
changed), choose the Settings menu in the upper right corner. Some proxy servers require credentials for
authentication. In this case, you need to provide the relevant user/password information.

If you later want to change the description for your cloud connector, in the upper right corner choose Settings,
open the Connector Info section and edit the description.

464

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Establish Connections to SAP HANA Cloud Platform


Once the initial setup has been completed successfully, the tunnel to the cloud endpoint is open (even though no
requests are allowed to pass until you have completed the Access Control setup). However, you can manually
close (and reopen) the connection to SAP HANA Cloud Platform by opening the Connector State page and
choosing the Disconnect button (or the Connect button to reconnect to SAP HANA Cloud Platform). The yellow
state icon and the text indicate that there is still no resource exposed that could be used from a cloud application.
This requires additional configuration, which is mentioned in the Related Information section.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

465

The green icons next to Landscape Host and HTTPS Proxy indicate that they both are valid and work properly. In
case of a timeout or a connectivity issue, the icon is respectively yellow (warning) or red (error), and a tooltip
displays the cause of the problem. The Account User is the user that has originally established the tunnel. During a
normal operation, this user is no longer needed but some certificates, exchanged during establishing a connection
to an account, are used instead.

Note
Once connected, you can monitor the cloud connector also in the Connectivity section of the HCP cockpit.
There, you can track attributes like version, description and high availability set up. Every cloud connector
configured for your account will automatically appear in the Connectivity section.

Related Information
Managing Accounts [page 474]
Using LDAP for Authentication [page 477]
Configuring the Cloud Connector for HTTP [page 339]
Configuring the Cloud Connector for RFC [page 390]
Account Member Roles [page 27]

1.4.1.3.4

Configuring Access Control

When adding new accounts, it is possible for you to copy the complete access control settings from another
account on the same cloud connector. In case you skip this operation, you can do it later by using the import/
export mechanism provided by the cloud connector.

466

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Exporting Access Control Settings


1. In your cloud connector, go to the Access Control page.
2. When ready, choose the Export button above to store the current settings in a ZIP file.
3. The file can be imported later into a different cloud connector.

Importing Access Control Settings


On the screenshot below, there are two locations from which you can import access control settings:
From a file, which has been previously exported from a cloud connector
From a different account on the same cloud connector

In addition, there are two checkboxes that influence the behavior of the import:
Overwrite Existing System Mappings: When this checkbox is selected, all previously existing system mappings
will be removed. Otherwise, the imported ones will be merged into the list of existing ones. Even then, if the
same virtual host-port combination exists already, it will be overridden by the imported one. By default,
imported system mappings are merged into the existing ones.
Include Resources: When this checkbox is selected (default), the resources that belong to the imported
systems will also be imported. Otherwise, only the list of system mappings will be imported - without any
exposed resource.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

467

Related Information
Configuring Access Control (HTTP) [page 341]
Configuring Access Control (RFC) [page 392]
Configuring Domain Mappings for Cookies [page 468]

1.4.1.3.5

Configuring Domain Mappings for Cookies

Context
Some HTTP servers return cookies which contain a "domain" attribute. On further requests, HTTP clients should
send these cookies to machines whose hostnames lie in the specified domain.
For example, if the client receives a cookie like the following:
Set-Cookie: cookie-field=some-value; domain=mycompany.corp; path=...; ...
it will return that the cookie in follow-up requests to all hosts like ecc60.mycompany.corp,
crm40.mycompany.corp, and so on, if the other attributes like "path" and "attribute" require it.
However, in the setup with the cloud connector between a client and a Web server, this may lead to potential
problems. For example, assume that you have defined a virtual host sales-system.cloud and mapped it to the
internal host name ecc60.mycompany.corp. Then, the client "thinks" it is sending an HTTP request to the host
name sales-system.cloud, while the Web server, unaware of the above host name mapping, sets a cookie for the
domain mycompany.corp. The client does not know this domain name and thus, for the next request to that Web
server, it will not attach the cookie, even though it should.
To resolve this problem, follow the steps below.

Procedure
1. Select Cookie Domains.
2. Choose Add.
3. Enter cloud as the virtual domain, and your company name as the internal domain.
4. Choose Save.

468

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

This way, the cloud connector will check the Web server's response for "Set-Cookie" headers, and if it finds
one with an attribute domain=intranet.corp, it will replace it with domain=sales.cloud before returning
the HTTP response to the client. Then, the client recognizes the domain name, and for the next request
against www1.sales.cloud it will attach the cookie, which will then successfully arrive at the server on
machine1.intranet.corp.

Note
Some Web servers use a syntax such as "domain=.intranet.corp" (RFC 2109), even though the newer
RFC 6265 recommends using the notation without a dot.

Note
Also bear in mind that the value of the domain attribute may be a simple host name. In this case, no extra
domain mapping is necessary on the cloud connector. If the server sets a cookie with
"domain=machine1.intranet.corp", the cloud connector will automatically reverse the mapping
machine1.intranet.corp to www1.sales.cloud and replace the cookie domain accordingly.

Related Information
Configuring Access Control [page 466]

1.4.1.3.6

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Using Service Channels

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

469

Context
With service channels, the cloud connector allows secure and reliable access from an external network to certain
services on SAP HANA Cloud Platform, which are not exposed for direct access from the Internet. The cloud
connector takes care that the connection is always available and communication is secured.
The database tunnel is a first service channel, which allows accessing HANA databases running in the cloud with
database clients (for example, clients using ODBC/JDBC drivers). You can use the database tunnel to connect
database tools, analytical tools, BI tools, or replication tools to your HANA database in your SAP HANA Cloud
Platform account.
Follow the next steps to establish a database tunnel to a HANA instance of your account.

Next Steps
Configuring Service Channels [page 470]
Connecting DB Tools to SAP HANA via Service Channels [page 472]

1.4.1.3.6.1 Configuring Service Channels

Context
You can establish a connection to a service in the cloud that is not directly exposed to external access. You can do
this in the Services Channels section of the cloud connector.
The database tunnel is a service channel which allows accessing SAP HANA databases running on the cloud via
ODBC/JDBC. You can use the database tunnel to connect database tools, analytical tools, BI tools, or replication
tools to your HANA database in your SAP HANA Cloud Platform account.

Note
The following procedure requires a productive HANA instance. It cannot be performed using a trial instance.
Follow the steps below to establish a database tunnel to a HANA instance of your account.

Procedure
1. In the cloud connector, go to the Service Channels page.
2. Choose Add.

470

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. In the Add Service Channel page, select one of the support channel types. Currently, only the HANA Database
type is supported.
4. Choose Next. The HANA Database page opens.

5. Specify the HANA instance name. It must match one of the names shown under
& Schemas

Persistence

Databases

in the cockpit.

6. Choose the local instance number. This is a double-digit number which computes the local port used to
access the HANA instance in the cloud. The local port is derived from the local instance number as
3<instance number>15. For example, if the instance number is 22, then the local port will be 32215.

Note
The local port should not match the HANA port used in the cloud they are mapped transparently by the
cloud connector.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

471

7. Leave the Enabled option selected to establish the tunnel immediately after clicking Save, or deselect it if the
tunnel should not yet be established.
8. When you are ready, choose Save.

Next Steps
Once you have established a database tunnel, you can connect on-premise database or BI tools to the selected
HANA database in the cloud by using <Cloud_connector_host>:<local_HANA_port> in the JDBC/ODBC
connect strings.
For more information, see Connecting DB Tools to SAP HANA via Service Channels [page 472]

1.4.1.3.7

Connecting DB Tools to SAP HANA via Service


Channels

Context
This section describes how you can connect database, BI, or replication tools running in on-premise network to a
HANA database on SAP HANA Cloud Platform using service channels of the cloud connector. You can also use the
high availability support of the cloud connector to achieve a highly available database connection. The picture
below shows the landscape in such a scenario.

472

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Follow the steps below to set up failover support, configure a service channel and connect on-premise DB tools via
JDBC or ODBC to the SAP HANA database.

Note
For more information on using SAP HANA instances, see Using a Productive SAP HANA Database System
[page 1010]
For the connection string via ODBC you need a corresponding database user and password (see step 4 below).
See also: Guidelines for Creating Database Users [page 1013]
Find detailed information on Configuring Clients for Failover here: SAP HANA Administration Guide.

Procedure
1. To establish a highly available connection to one or multiple SAP HANA instances in the cloud, we recommend
that you make use of the failover support of the cloud connector. For this aim, set up a master and a shadow
instance. For more information, see Installing a Failover Instance for High Availability [page 507].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

473

2. In the master instance, configure a service channel to the SAP HANA database of the SAP HANA Cloud
Platform account to which you want to connect. Let's assume that the chosen port of the service channel is
30015. For more information, see Configuring Service Channels [page 470].
3. You can now connect on-premise DB tools via JDBC to the SAP HANA database by using the following
connection string:
jdbc:sap://<cloud-connector-master-host>:30015;<cloud-connector-shadow-host>:
30015[/?<options>]
The SAP HANA JDBC driver supports failover out of the box. All you need is to configure the shadow instance
of the cloud connector as a failover server in the JDBC connection string. The different options supported in
the JDBC connection string are described in page: Connect to SAP HANA via JDBC
4. You can also connect on-premise DB tools via ODBC to the SAP HANA database. The connection string is as
follows:
"DRIVER=HDBODBC32;UID=<user>;PWD=<password>;SERVERNODE=<cloud-connector-masterhost>:30015;<cloud-connector-shadow-host>:30015;"

1.4.1.3.8

Managing Accounts

Context
Effective version 2.2, it is possible to connect to several accounts within a single cloud connector installation.
Those accounts can use the cloud connector concurrently with different configurations. By selecting an account
from the drop-down box, all tab entries will show the configuration, audit and state specific to this account. In case
of audit and traces, cross account info is merged with the account specific parts in the UI.

Note
We recommend that you group only accounts of the same quality in a single installation:
Productive accounts should reside on a cloud connector that is used for productive accounts only.
Test and development accounts could be merged, depending on the group of people that are supposed to
deal with those accounts. However, the mostly preferred logical setup is to have separate development and
test installations.

Account Dashboard
In the account dashboard, you can check the state of all account connections managed by this cloud connector at
a glance.

474

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

In the screenshot above, the demo account (technical name a1b2e3f4) is already connected, but has no active
resources exposed. The esworkplace account (technical name km12tbd45) is currently disconnected.
In addition, the dashboard allows you to do mass disconnect and connect operations for the accounts by selecting
the accounts and pressing the respective button. In case you try to connect in such an operation an already
connected account, this account will be skipped in this operation.
In case you want to have an additional account to be connected with your on-premise landscape, just press the
Add button and a dialog appears, which is similar to the Initial Configuration operation when establishing the first
connection.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

475

Procedure
1. The Landscape Host field specifies the SAP HANA Cloud Platform landscape that should be used. You can
choose the one you need from the dropdown list. For more information, see Cockpit [page 84] section
"Logon".
2. For Account Name and User Name (user/password), enter the values you obtained when you registered your
account on SAP HANA Cloud Platform or add a new Account User [page 23] with role Cloud Connector
Admin from the Members tab in the SAP HANA Cloud cockpit and use the new user and password.

Note
If the cloud connector is installed in an environment that is operated by SAP, SAP will provide a user that
you should add as new member in your SAP HANA Cloud Platform account. In this case, please assign the
Cloud Connector Admin role (see Account Member Roles [page 27]) to the user provided by SAP. Once
the cloud connector connection is established, this user is not needed any more since it serves for initial
connection setup only. You may revoke the corresponding role assignment then and remove the user from
the Members list.
3. Optional: You can define a Display Name, which allows you to easily recognize a specific account in the UI
compared to the technical Account Name.
4. Optional: You can define a Location ID, which identifies the location of this cloud connector for a specific
account. Currently, this is only documentary but in the future, it might also be used for routing purposes.
5. If you want to import the access control settings from another account on this cloud connector, select the
Import Access Control From Account checkbox and choose the desired account from the dropdown box.
6. Once all the settings have been completed, choose OK.

Note
Since you are allowed to have one and the same account name connected to different landscapes, you can
distinguish the two names by their tooltips in the Account dropdown box.

Next Steps
To modify an existing account, press the Edit button and then change the Display Name and/or the Location
ID. The latter can be modified only if the account is currently not connected.

476

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can also delete an account from the list of connections. After confirming that you really want to delete it,
the account will be disconnected and all configurations will be removed from the installation.

Related Information
Account Member Roles [page 27]

1.4.1.3.9

Using LDAP for Authentication

Overview
After installation, the cloud connector uses file-based user management. Initially there is one Administrator user
with the password manage, which needs to be changed on the first logon. As an alternative to this file-based user
management, the cloud connector also supports LDAP-based user management. If you have an LDAP server in
your landscape, you can configure the cloud connector to use the users available on that LDAP server. All users
that are in a group named admin or sccadmin will have the necessary authorization for administrating the cloud
connector. This group membership is checked by the cloud connector.

Setting LDAP Authentication


1. To change the configuration, log on to the cloud connector and choose Settings in the menu.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

477

2. Go to the Authentication panel and select LDAP.

3. If you want to save intermediate adoptions of the LDAP configuration, press the Save button.
4. Usually, the LDAP server lists users in an LDAP node and user groups in another node. In this case, you can
use the following template for LDAP configuration. The template can be copied into the configuration text
area by choosing the rightmost button immediately below the text area. The template looks like this:
userPattern="uid={0},ou=people,dc=mycompany,dc=com"
roleBase="ou=groups,dc=mycompany,dc=com"
roleName="cn"
roleSearch="(uniqueMember={0})"
5. Change the ou and dc fields in userPattern and roleBase, according to the configuration on your LDAP
server, or use some other LDAP query.
6. Provide the LDAP server's host and port (port 389 is used by default) in the Host field. If you want to use the
secure protocol variant LDAPS based on TLS, select the Secure checkbox to do so.
7. Provide a failover LDAP server's host and port (port 389 is used by default) in the Alternate Host field. If you
want to use the secure protocol variant LDAPS based on TLS, select the Secure checkbox to do so.
8. Optional: You can provide a service user and its password in the fields User Name and Password.
9. Optionally, you can override the role to check for permissions in User Role. If not provided, cloud connector
will check permissions for the default role sccadmin. After finishing the configuration, choose Activate.
Immediately after activating the LDAP configuration, a restart of the local server is enforced which invalidates
the current browser session. You need to refresh the browser and to perform a new logon to the cloud
connector, this time with the credentials configured at the LDAP server. If you want to use the secure protocol
variant LDAPS based on TLS, select the Secure checkbox to do so.
10. To switch back to file-based user management, choose the Password option.

478

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For more information about how to set up LDAP authentication, see tomcat.apache.org/tomcat-7.0-doc/realmhowto.html .

Note
When using LDAP together with a high availability setup with master and shadow, the configuration option
userPattern cannot be used. Instead a working combination of userSearch, userSubtree and userBase
needs to be used.

Note
If an LDAP configuration is wrong, you will probably not be able to logon to the cloud connector again. In this
case, you need to adjust the cloud connector configuration to use the file-based user store again without the
administration UI. For more information, see the next section.
The same operation is possible on the shadow instance in a high availability setup. There you need to navigate to
the Administration section and expand the Authentication panel to proceed in the same way as on the master.

Switching Cloud Connector Back to File-Based User Store without


Administation UI
In case your LDAP settings do not work as expected, you can use the useFileUserStore tool, provided with cloud
connector version 2.8.0 and higher, to revert back to the file based user store:
1. Change to the installation directory of the cloud connector. To adjust the userstore, execute the following
command:
Microsoft Windows: useFileUserStore
Linux, Mac OS: ./useFileUserStore.sh
2. The tool will inform you about the successful modification of the user store.
3. To activate the file based user store, you need to restart the cloud connector.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

479

For older versions you need to manually edit the configuration files as described below.
Depending on your operating system, the configuration file is located at:
Microsoft Windows OS: <install_dir>\config_master\org.eclipse.gemini.web.tomcat
\default-server.xml
Linux OS: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/default-server.xml
Mac OS X: /opt/sap/scc/config_master/org.eclipse.gemini.web.tomcat/defaultserver.xml
1. To revert to file-based user management, replace the Realm section with the following:
<Realm className="org.apache.catalina.realm.LockOutRealm">
<Realm className="org.apache.catalina.realm.CombinedRealm">
<Realm
X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetrieve
r" className="org.apache.catalina.realm.UserDatabaseRealm" digest="SHA-256"
resourceName="UserDatabase"/>
<Realm
X509UsernameRetrieverClassName="com.sap.scc.tomcat.utils.SccX509SubjectDnRetrieve
r" className="org.apache.catalina.realm.UserDatabaseRealm" digest="SHA-1"
resourceName="UserDatabase"/>
</Realm>
</Realm>
2. To restart the cloud connector service, proceed as described below depending on your operating system:
Microsoft Windows OS: Open the Windows Services console and restart the cloud connector service.
Linux OS: Execute command: service scc_daemon restart
Mac OS X: Not applicable because no daemon exists; it is only a "developer version".

1.4.1.3.10 Setting Up Trust

Content
Configure trust in the cloud connector [page 480]
Configure on-premise for principal propagation [page 482]
Trust cloud applications in the cloud connector [page 482]
Trust Store [page 483]
Tasks [page 484]

Configure Trust in the Cloud Connector


The purpose of the trust configuration is the support of principal propagation: Forwarding the logged on identity in
the cloud to the internal system, which means logging on with a user that matches this identity without the need

480

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

of providing the password. By default, your cloud connector is not trusting any entity that is issuing tokens for
principal propagation. Therefore, the list of trusted identity providers is empty in the beginning. If you decide to
make use of the principal propagation feature, you need to establish trust to at least one identiy provider.
Currently, SAML2 identity providers are supported. Trust to one or more SAML2 IDPs can be configured per
account. After you've configured trust in the cockpit for your account, for example, to your own company's
identity provider(s), you can synchronize this list to your cloud connector.
Starting with cloud connector 2.4, you can also trust HANA instances and Java applications to act like identity
providers.

By pressing the Synchronize button, the list of existing identity providers will be stored locally in your cloud
connector.
When selecting the entry, you can see the following details about it, in case the trusted entity reflects a SAML2
identity provider:
Name: the name associated with the identity provider
State: denotes whether the entry shall be trusted for principal propagation
Description: descriptive information about this entry
Certificate: The certificate associated with the entry. The cloud connector runtime will use this certificate
for verifying that the assertion used for principal propagation has been issued by a trusted entity.
For each of the entries you can decide, whether to trust it for the principal propagation use case by (de)selecting
the State checkbox for the respective entry. This will be stored locally.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

481

Configure On-Premise for Principal Propagation


The following procedure helps you to set up principal propagation from SAP HANA Cloud Platform to your internal
system that shall be used in a hybrid scenario.

Note
As a prerequisite for principal propagation for RFC, the following cloud application runtime versions are
required:
for Java Web: 1.51.8 or higher
for Java EE 6 Web Profile: 2.31.11 or higher
1. Set up trust to an entity, which is issuing an assertion for the logged on user. This is described in the section
above.
2. Set up the system identity for the cloud connector.
In the case of HTTPS communication, you need to import a system certificate into your cloud connector.
In the case of RFC communication, you need to import SNC PSE into your cloud connector.
3. Configure the target system in a way that it trusts the cloud connector. There are two levels of trust:
1. First, you need to allow the cloud connector to identify itself with its system certificate (for the HTTPS
case), or with the SNC PSE (for the RFC case).
2. Then, you need to allow this identity to propagate the user accordingly:
In the case of HTTPS, the cloud connector will forward the true identity in a short-living X.509
certificate in an HTTP header named SSL_CLIENT_CERT. The system needs to use this certificate for
logging on the real user. The SSL handshake, however, is performed through the system certificate.
In the case of RFC, the cloud connector will forward the true identity as part of the RFC protocol.
4. Configure the user mapping in the target system. The X.509 certificate contains information about the cloud
user in its subject. Use this information in order to map the identity to the appropriate user in this system.
This is independent from the communication protocol.

Note
If you have the following scenario: Application1->AppToAppSS0->Application2->Principal Propagation->On
premise Backend System you have to mark Application2 as trusted by the cloud connector in the Trust
Configurations tab.

Trust Cloud Applications in the Cloud Connector


By default, all applications within an account are allowed to use the cloud connector associated with the account
they run in. However, this behavior might not be desired. For some applications this is acceptable, as they need to
interact with on-premise resources. Others, for which it is not transparent whether they try to receive some onpremise data, might turn out to be malicious. For such cases, the application whitelist is useful.

482

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

As long as there is no entry in this list, all applications will be allowed to use the cloud connector. If one or more
entries appear in the whitelist, then only these applications will be allowed to connect to the exposed systems in
the cloud connector.
To add one or more applications, press the Add button. Enter a comma-separated list in the dialog's input
field and then press the Save button.
To edit an existing entry, press Edit. Press Save after editing the value.
To remove an application from the list, select the entry and choose Delete. To delete all entries, choose Delete
All.

Note
In order to allow subscribed applications, you need to add it to the whitelist in the format
<providerAccount>:<applicationName>.

Trust Store
By default, the cloud connector trusts every on-premise system when connecting to it via HTTPS. As this may be
an undesirable behavior from a security perspective, you can configure a trust store that acts as a whitelist of
trusted on-premise systems, represented by their respective public keys. You can configure the trust store by
opening the settings dialog (top right on administration UI) and then selecting Trust Store from the left panel:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

483

An empty trust store does not impose any restrictions on the trusted on-premise systems. This behavior ensures
downward compatibility so that the cloud connector behaves as it did before introducing the configurable trust
store. While an empty trust store acts like a blacklist, it transforms into a whitelist as soon as you add the first
public key.

Note
You hve to provide the public keys in .der or .cer format.

Tasks
To learn more about the different types of configuring and supporting principal propagation for a particular AS
ABAP, see:
Configuring a CA Certificate for Principal Propagation [page 485]
Configuring Principal Propagation to an ABAP System for HTTPS [page 488]
Configuring Principal Propagation to an ABAP System for RFC [page 492]
Configuring Subject Pattern for Principal Propagation [page 494]
Configuring a Secure Login Server for the Cloud Connector [page 496]

484

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Principal Propagation [page 318]

1.4.1.3.10.1 Configuring a CA Certificate for Principal


Propagation

Supported CA Mechanisms
You can enable support for Principal Propagation with X.509 certificates in two ways:
Using a Local CA in the cloud connector. Prior to version 2.7.0, this was the only option and the system
certificate was acting both as client certificate and CA certificate in the context of Principal Propagation.
Using a Secure Login Server and delegate the CA functionality to it.
The cloud connector will then use the configured CA approach for issuing short-living certificates for logging on
the same identity in the back-end that is logged on in the cloud. For establishing trust with the back-end, the
respective configuration steps are independent from the approach chosen for the CA.

Installing a local CA Certificate


In order to issue short-living certificates used for principal propagation to a back-end system, you can import an
X.509 client certificate into the cloud connector. This CA certificate needs to be provided as PKCS#12 file
containing the (intermediate) certificate, the corresponding private key and the CA root certificate that signed the
intermediate certificate (plus potentially the certificates of any intermediate CAs, if the certificate chain is longer
than 2). Via the file upload dialog, this PKCS#12 file can be chosen from the file system, and its password also
needs to be supplied for the import process. As a second option, you can start a Certificate Signing Request
procedure like for the UI certificate - described in Exchanging UI Certificates [page 456].

Note
The CA certificate should have the KeyUsage attribute keyCertSign. Many systems verify that the issuer of a
certificate has this attribute and deny a client certificate, if it is not the case. When using the Certificate Signing
Request procedure, the attribute will be requested for the CA certificate.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

485

If a CA certificate has been imported successfully, its distinguished name, the name of the issuer, and the validity
dates are displayed:

486

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If a CA certificate is no longer required, you can delete it. To do this, use the respective button and confirm
deletion.

Configuration of a CA Hosted by a Secure Login Server


If you like to delegate the CA functionality to a Secure Login Server, choose the CA via Secure Login Server option
and configure the Secure Login Server as follows, after having configured the Secure Login server as described in
Configuring a Secure Login Server for the Cloud Connector [page 496].

The fields need to be filled in in the order on the screen:


<Host Name>: The host, on which your Secure Login Server (SLS) is installed.
<Authentication Port>: The port, over which the cloud connector is requesting the short-living
certificates from SLS.

Note
For this privileged port a client certificate authentication is required, for which the cloud connector system
certificate will be used.
<Profile>: The Secure Login Server Profile that will allow to issue certificates as needed for Principal
Propagation with the cloud connector. You can choose the profile in the dialog below that pops up when
clicking on the selection menu icon next to the field.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

487

After the profiles have been fetched successfully, press the Apply button to choose the selected profile for
your configuration.
<Profiles Port>: The profiles port needs to be provided only when your Secure Login Server is configured
to not allow to fetch profiles via the privileged authentication port. If this is the case, you can provide here the
port that is configured for that functionality.
Press the Save button to store the configuration.

Related Information
Configuring a Secure Login Server for the Cloud Connector [page 496]
Initial Configuration (HTTP) [page 339]
Initial Configuration (RFC) [page 391]

1.4.1.3.10.2 Configuring Principal Propagation to an ABAP


System for HTTPS

Context
In this page, the abstract description for principal propagation configuration is mapped to a concrete step-by-step
instruction for an ABAP application server configuration of the use case.
Exemplary data for the scenario:
System certificate was issued by: CN=MyCompany CA, O=Trust Community, C=DE
It has subject: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE.
An example for a short-living certificate has the subject CN=P1234567890, where P1234567890 is the
platform user

488

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. Configuring ABAP Systems to Trust Cloud Connector's System Certificate


You have the following two parts:
The ABAP system trusts the cloud connector's system certificate:
1. Open the Trust Manager (transaction code: STRUST).
2. Double-click on the SSL-Server Standard folder in the menu tree on the left.
3. In the displayed screen, click on the Import certificate button.
4. In the dialog window, choose the certificate file representing the public key of the issuer of the system
certificate, for example, in DER format. Typically, this is a CA certificate. In case you decide to use a selfsigned system certificate, it is the system certificate itself.
5. Afterwards, the details of this certificate are shown in the section above. Mapped to the exemplary certificate,
you would see CN=MyCompany CA, O=Trust Community, C=DE as subject.
6. If you are sure you are importing the correct certificate, you can integrate the certificate into the certificate
list by choosing the Add to Certificate List button.
7. In the end, the CA certificate (CN=MyCompany CA, O=Trust Community, C=DE) is part of the certificate list.
The ICM trusts the system certificate for principal propagation:
1. Open the Profile Editor (transaction code: RZ10).
2. Select the profile you like to edit, for example, the DEFAULT profile.
3. Select the radio button for Extended maintenance and choose the Change button.
4. Create the following two parameters:
icm/HTTPS/trust_client_with_issuer: this is the issuer of the system certificate (exemplary data:
CN=MyCompany CA, O=Trust Community, C=DE)
icm/HTTPS/trust_client_with_subject: this is the subject of the system certificate (exemplary
data: CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE)

Note
In case you have applied SAP Note 2052899
to your system, you can alternatively provide an additional
parameter for icm/trusted_reverse_proxy_<x>
For example: icm/trusted_reverse_proxy_2 = SUBJECT="CN=SCC, OU=HCP Scenarios, O=Trust
Community, C=DE", ISSUER="CN=MyCompany CA, O=Trust Community, C=DE"
5. Save the profile.
6. Open the ICM Monitor (transaction code: SMICM) and restart the ICM. To do so, choose
ICM

Exit Hard

Administration

Global .

7. Verify that the two profile parameters have been taken over by ICM as desired. To do so, choose
Parameters

Display

Goto

Note
In case you have a Web dispatcher installed in front of the ABAP system, trust needs to be added in its
configuration files with the same parameters as for the ICM. In addition, the system certificate of the cloud
connector needs to be added to the trust list of the Web dispatcher Server PSE.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

489

2. Mapping Short-Living Certificates to Corresponding Users


You can do this manually in the system as described below or make use of an Identity Management Solution for a
more comfortable approach. For example, for large numbers of users the rule-based certificate mapping is a good
way to save time and effort. For more information, see Rule-based Mapping of Certificates [page 490].
1. Open Assignment of External ID to Users (transaction code: EXTID_DN).
2. Switch to edit mode.
3. Create a new entry. Specify the subject of the certificate as External ID. Mapped to the exemplary data,
this is CN=P1234567890. In the User field, provide the appropriate ABAP user, for example JOHNSMITH.
4. Activate the mapping by checking Activate.
5. Save the mapping.
6. Repeat the previous steps for all users that shall be supported for the scenario.

3. Providing Logon Data


Optional procedure. Execute these steps in case your scenario requires basic authentication support for some of
the ICF services.
1. Go to Maintain Services (transaction code: SICF).
2. Enter a Service Name.
3. Double click on the service and go to the Logon Data tab.
4. Switch to Alternative Logon Procedure and make sure that Basic Authentication Logon Procedure is before
Logon Through SSL Certificate.

Related Information
Rule-based Mapping of Certificates [page 490]
Configuring Subject Pattern for Principal Propagation [page 494]
Setting Up Trust [page 480]

1.4.1.3.10.2.1 Rule-based Mapping of Certificates


To perform rule-based mapping of certificates in the ABAP server, proceed as follows:
1. Enter a dynamic parameter using transaction RZ11.
1. Enter the parameter, login/certificate_mapping_rulebased,
2. Click the button Change Value.
3. Enter the new value as "1".

490

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Save the value.

Note
If dynamic parameters are disabled, enter the value using transaction RZ10 and re-start the whole ABAP
system.
2. Configure rule-based mapping
1. Create a sample certificate with the cloud connector. Login to the cloud connector, goto Tab, Settings,
select Principal Propagation and enter a sample CN Name to save/download the sample certificate to the
Downloads folder of your browser.
2. Import the sample certificate using transaction CERTRULE and click on Import certificate.

Note
To access transaction CERTRULE, you need the corresponding authorizations (see: Assigning
Authorization Objects for Rule-based Mapping [page 491]).
3. Click on the button Rule to create explicit rule mappings.
4. Click on Save to save the changes.

Note
Once you save the changes and return to transcation CERTRULE, the sample certificate which you
imported in Step 2b will not be saved. This is just a sample editor view to see the sample certificates
and mappings.

Related Information
Rule-Based Certificate Mapping

1.4.1.3.10.2.1.1 Assigning Authorization Objects for Rule-based


Mapping
Assign authorizations to access transaction CERTRULE.
To access transaction CERTRULE, you need the following authorizations:
CC control center: System administration (S_RZL_ADM)
Activity 03 grants display authorizations.
Activity 01 grants change authorizations.
User Master Maintenance: User Groups (S_USER_GRP)
Activity 03 grants display authorizations.
Activity 02 grants change authorizations.
Class: enter the names of user groups for which the administrator can maintain explicit mappings.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

491

To assign these authorization objects, proceed as follows:


1. Create a Single Role with transaction PFCG.
2. Goto tab Authorizations, choose Change Authorization data and press the Manually button to add the
authorization objects S_RZL_ADM and S_USER_GRP.
3. Choose Generate to generate the profile and save the changes.
4. In the User tab, enter the user who should execute the transaction CERTRULE.
5. Choose User comparison to match the newly generated profiles to the users.

1.4.1.3.10.3 Configuring Principal Propagation to an ABAP


System for RFC

Context
In this page you will find a detailed step-by-step scenario on how to configure the cloud connector and an AS
ABAP so that it accepts user principals propagated from a SAP HANA Cloud Platform account.
Exemplary data for the scenario:
A system PSE has been generated and installed on the host where the cloud connector is running.
For more information, see the SNC User's Guide: https://service.sap.com/security
section
"Infrastructure Security".
The system's SNC name is: p:CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE
The ABAP system's PSE name is: p:CN=SID, O=Trust Community, C=DE
The ABAP system's PSE and the cloud connector's system PSE need to be signed by the same CA for mutual
authentication.
An example for a short-living certificate has the subject CN=P1234567, where P1234567 is the platform user.

1. Configuring the ABAP System to Trust the Cloud Connector's System PSE
1. Open the SNC Access Control List for Systems (transaction code: SNC0).
2. Think of a nice "system ID" for your cloud connector and enter it together with its SNC name: p:CN=SCC,
OU=HCP Scenarios, O=Trust Community, C=DE
3. Save the entry and then choose the Details button.
4. In the next screen, activate the check boxes for Entry for RFC activated and Entry for certificate activated.
5. Save your settings.

492

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Mapping Short-Living Certificates to Corresponding Users


You can do this manually in the system as described below or make use of an Identity Management Solution for a
more comfortable approach. For example, for large numbers of users the rule-based certificate mapping is a good
way to save time and effort. For more information, see Rule-Based Certificate Mapping.
1. Open Assignment of External ID to Users (transaction code: EXTID_DN).
2. Switch to edit mode.
3. Create a new entry. Specify the subject of the certificate as External ID. Mapped to the exemplary data,
this is CN=P1234567. In the User field, provide the appropriate ABAP user, for example JOHNDOE.
4. Save the mapping.
5. Repeat the previous steps for all users that shall be supported for the scenario.

3. Configuring the Cloud Connector


We assume that:
The necessary security product for the SNC flavor, used by your ABAP backend systems, is already installed
on the cloud connector host
The cloud connector's system PSE is opened for the operating system user under which the SCC process is
running. If this is the case, two more steps need to be performed in the cloud connector UI:.
Set up the cloud connector to use the given system PSE
1. Open the Settings dialog and go to the SNC section.
2. Provide the fully qualified name of the SNC library (the security product's shared library implementing the
GSS API), the SNC name of the above system PSE, and the desired quality of protection.
For more information, see Initial Configuration (RFC) [page 391].

Note
The example in Initial Configuration (RFC) [page 391] shows the library location if you use the SAP Secure
Login Client as your SNC security product. In this case (as well as for some other security products), SNC
My Name is optional, because the security product automatically uses the PSE associated with the current
operating system user under which the process is running, so you can leave that field empty. (Otherwise, in
this example it should be filled with p:CN=SCC, OU=HCP Scenarios, O=Trust Community, C=DE.)
We recommend that you use the third shown option for Quality of Protection, if your security solution
supports it, as it provides the best protection.
3. Choose Save and Close.
Create an RFC hostname mapping corresponding to the RFC destination with principal propagation on cloud
side
1. In the Access Control section of the cloud connector, create a hostname mapping corresponding to the cloudside RFC destination. For more information, see Configuring Access Control (RFC) [page 392].
2. Make sure that you choose RFC SNC as Protocol and ABAP System as Back-end Type. In the SNC Partner
Name field, enter the ABAP system's SNC name, for example p:CN=SID, O=Trust Community, C=DE in
this example.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

493

3. Save your mapping.

1.4.1.3.10.4 Configuring Subject Pattern for Principal


Propagation

How to configure a principal propagation subject?


Using the principal propagation, a secure way is provided to forward the on-demand identity to the cloud
connector and from there to the back end. The pattern identifying the user for the subject of the generated shortliving X.509 certificate, as well as its validity period, can be defined as shown in the picture below.

Subject Pattern
There are two ways to define the subject's distinguished name (DN), for which the certificate will be issued:
Adding/editing the subject pattern field directly with free text.
Using the help of the selection menu, that is, the

494

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

icon.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Thus, you can assign a value for each parameter (either directly as a free text or as a variable selected from the
menu of this field). Those selectable parameters are:
${name}
${mail}
${display_name}
The values for these variables will be provided by the Certificate Authority, which also provides the values
for the subject's DN.
By the help of this menu, you can define the distinguished name of the subject as its subject pattern. By
default, the following attributes are provided:
CN: (common name) the name of the certificate owner
EMAIL: (email address) - the email address of the certificate owner
L: (locality) the locality of the certificate owner
O: (organization) the organization/company to which the certificate owner belongs
OU: (name of organizational unit) the organizational unit to which the certificate owner belongs
ST: (state of residence) the state of residence of the certificate issuer
C: (country of residence) the country of the certificate owner
By pressing button Create Sample Certificate you can create a sample certificate that looks like one of the shortliving certificates created at runtime. It can be used for generating user mapping rules in the target system, for
example, via transaction CERTRULE in an ABAP system. If your subject pattern contains variable fields, a small
wizard will allow you to provide meaningful values for each of them and eventually you can save the sample
certificate in DER format.

Expired Session Tolerance Time (h)


This is the time, provided in hours, that defines how long the application can use a principal issued for a user after
the token provided from cloud side has been expired.

Certificate Validity Period (min)


This is the time, provided in minutes, that defines how long the certificate generated for principal propagation can
be used to authenticate against the back end. Reuse of a previously generated certificate increases the
performance.

Related Information
Server Certificate Authentication [page 323]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

495

1.4.1.3.10.5 Configuring a Secure Login Server for the Cloud


Connector
Configuration steps for Java SLS support.
The cloud connector is able to use on-the-fly generated X.509 user certificates to log in to on-premise systems if
the external user session is authenticated (for example by means of SAML). If you do not want to use the built-in
certification authority (CA) functionality of the cloud connector (for example because of security considerations),
you can connect SAP SSO 2.0 Secure Login Server (SLS).
SLS is a Java application running on AS JAVA 7.20 or higher, which provides interfaces for certificate enrollment.
The protocol is using the formats:
HTTPS
REST
JSON and
PKCS#10/PKCS#7

Note
Any enrollment requires a successful user or client authentication, which can be a single, multiple or even a
multi factor authentication.
The following schemes are supported:
LDAP/ADS
RADIUS
SAP SSO OTP
ABAP RFC
Kerberos/SPNego and
X.509 TLS Client Authentication
SLS allows you to define arbitrary enrollment profiles, each with a unique profile UID in its URL, and with a
configurable authentication and certificate generation.

Requirements
For the purpose of user certification, SLS has to provide a profile with the following properties:
Cloud connector client authentication by its X.509 service certificate
Cloud connector service certificate and SLS may live in different PKIs
Cloud connector hands over the full users certificate subject name
SLS provides all required features with SAP SSO 2.0 SP06:
TLS Client Authentication-based enrollment with SecureLoginModuleUserDelegationWithSSL (available
since SP04)
multi PKI support is implemented by all standard components of AS JAVA, AS ABAP, HANA, by importing
trusted Root CA certificates

496

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SLS allows to configure PKCS10:SUBJECT in a profiles certificate configuration (SP06)

Implementation
INSTALLATION
Follow the standard installation procedures for SLS. This includes the initial setup of a PKI (public key
infrastructure).

Note
SLS allows you to set up one or more own PKIs with Root CA, User CA etc. You can also import CAs as
PKCS#12 file or use a hardware security module (HSM) as "External User CA".

Note
You should only use HTTPS connections for any communication with SLS. AS JAVA / ICM supports TLS, and
the default configuration comes with a self-signed sever certificate. You may use SLS to replace this certificate
by a PKI certificate.

CONFIGURATION
SSL Ports
1. Open the NetWeaver Administrator, choose

Configuration

SSL

and define a new port with Client

Authentication Mode = REQUIRED.

Note
You may also define another port with Client Authentication Mode = Do not request if you did
not do so yet.
2. Import the Root CA of the PKI that issued your cloud connector service certificate.
3. Save and restart the Internet Communication Manager (ICM).
Authentication Policy
1. Open the NetWeaver Administrator (NWA, https://<host:port>/nwa).
2. Go to the top level menu and choose

Configuration

Authentication and Single Sign-On

3. In the Policy Configuration table, switch to Type = Custom.


4. Press Add to create a new policy, e.g. with name SecureLoginCloudConnector.
5. Open Edit mode.
6. In Details of authentication configuration choose Authentication Stack
SecureLoginModuleUserDelegationWithSSL.

Login Modules

and add

7. In <Rule1.subjectName> and <Rule1.issuerName>, enter the respective certificate names of your cloud
connector service certificate.
8. In Details of authentication configuration choose Properties and add the property UserNameMapping with
value VirtualUser.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

497

9. Save the policy.


Client Authentication Profile
1. Open the SLS Administration Console (SLAC, https://host:port/slac).
2. Go to the top level menu and choose

Profile Management

Authentication Profiles

3. Create a new profile with Client Type = Secure Login Client, for example with name Cloud
Connector User Certificates.
4. Choose

User Authentication

Use Policy Configuration

and select from the drop down list Policy

Configuration Name = SecureLoginCloudConnector.


5. Edit all required fields in the wizard according to your requirements.
6. Save your entries.
7. Select the new profile and open Edit mode.
8. Choose

Certificate Configuration

Certificate Name and Alternative Names

and set Appendix Subject

Name = (PKCS10:SUBJECT).
9. Keep all other fields in Certificate Name and Alternative Names empty.
10. In page Enrollment Configuration, make sure that the <Enrollment URL> has the correct value, otherwise
edit and fix it:
1. full DNS name
2. port with TLS Client Authentication (see port number in NWA SSL Configuration).
11. Save your entries.
User Profile Group
1. Open the SLS Administration Console (SLAC, https://host:port/slac).
2. Go to the top level menu and choose

Profile Management

User Profile Groups .

3. Create a new profile group, make sure that the <Policy URL> has the correct value, otherwise edit and fix it:
1. full DNS name
2. port without TLS Client Authentication (see port number in NWA SSL Configuration).
4. In tab Profiles, add the profile Cloud Connector User Certificates.
5. Save your entries.
Root CA Certificate
1. Open SLS Administration Console (SLAC, https://host:port/slac).
2. Go to the top level menu and choose Certificate Management.
3. Select the Root CA certificate you are using in your profile.
4. Choose

Export entry

X.509 Certificate

and download the certificate file.

SAP Cloud Connector


Follow the standard installation procedure of the cloud connector and configure SLS support:
1. Enter the Policy URL pointing to the SLS User Profile Group.
2. Select the profile, e.g. Cloud Connector User Certificates.
3. Import the Root CA certificate of SLS into the cloud connectors trust store.
On-Premise Target Systems
Follow the standard configuration procedure for cloud connector support, and configure SLS support:

498

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. Import the Root CA certificate of SLS into the systems trust store
AS ABAP: transaction STRUST
AS Java:

NWA

Configuration

SSL

2. (...)

1.4.1.3.11 Configuring User Store in the Cloud Connector

Prerequisites
You have configured your cloud application to use an on-premise user provider and to consume users from
LDAP via the cloud connector. To do this, execute the following command:
neo deploy --host <landscape host> --account <account name> --application
<application name> --source <path to WAR file> --user <e-mail or user name> --vmarguments "-Dcom.sap.cloud.security.um.user_provider_name=onpremise Dcom.sap.cloud.security.um.destination_name=onpremiseumconnector"
You have created a connectivity destination (with the parameters below), to configure the on-premise user
provider:
Name=onpremiseumconnector
Type=HTTP
URL= http://scc.scim:80/scim/v1
Authentication=NoAuthentication
CloudConnectorVersion=2
ProxyType=OnPremise

Context
You can configure applications running on SAP HANA Cloud Platform to use your corporate LDAP server as a user
store. This way, SAP HANA Cloud Platform does not need to keep the whole user database but requests the
necessary information from the LDAP server. For that purpose, Java applications running on SAP HANA Cloud
Platform can use the on-premise system to check credentials, search for users, and retrieve their details. In
addition to the user information, the cloud application may request information about the groups of which a
specific user is a member.
One way for a cloud Java application to define user authorizations is by checking the user membership to specific
groups in the on-premise user store. For that purpose, the Java application uses the roles for the groups defined
in SAP HANA Cloud Platform. For more information, see Managing Roles [page 1282].
The corporate LDAP server that is used in the current configuration is configured in the cloud connector.

Note
The configuration steps below are only applicable for Microsoft Active Directory.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

499

Procedure
1. In the cloud connector menu, choose Settings.
2. From the left panel, select Cloud User Store.

3. Select Secure if you want to connect to the LDAP system via SSL.
4. In the Hosts field, you can manage the hosts (and ports) of your LDAP server(s).
Choose the Add button to add as many hosts (and ports) as you need.
Choose Edit to edit the selected host.
Choose Delete to delete the selected hosts.
5. For User Name and Password, enter the credentials of the service user that will be used to contact the LDAP
system.
6. In User Path, specify the LDAP subtree that contains the users.
7. In Group Path, specify the LDAP subtree that contains the groups.
8. Choose Apply.

Related Information
Using an SAP System as an On-Premise User Store [page 1305]

500

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.3.12 Configuring Kerberos in the Cloud Connector

Context
The cloud connector allows you to propagate users authenticated in SAP HANA Cloud Platform via Kerberos
against back-end systems. It uses the Service For User and Constrained Delegation protocol extension of
Kerberos.
We use Key Distribution Center (KDC) to exchange messages in order to retrieve Kerberos tokens for a certain
user and a back-end system.
For more information, see Kerberos Protocol Extensions: Service for User and Constrained Delegation Protocol
Table 234:
1.

An SAP HANA Cloud Platform application calls a back-end system via the cloud
connector.

2. The cloud connector calls the KDC to obtain a Kerberos token for the user
propagated from the cloud connector.
3. The obtained Kerberos token is sent as a credential to the back-end system.

Procedure
1. In the cloud connector menu, choose Settings.
2. From the left panel, select Kerberos.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

501

3. In the Realm Name field, enter the name of your Kerberos realm.
4. In the KDC Hosts field, enter the host name of your KDC in format <host>:<port>. The port is optional. If
you do not specify a port, the default one, 88, will be used.
5. Select an encryption key algorithm from the dropdown menu.

Note
Currently, only rc4-hmac is supported.
6. Upload a keytab file that contains the secret keys of your service user. The keytab file should contain the rc4hmac key for your user.
7. In the User Name field, enter the name of the service user to be used for communication with the KDC. This
service user should be allowed to request Kerberos tokens for other users for the back-end systems that you
are going to access.
8. Choose Save.

Example
You have a back-end system protected with SPNego authentication in your corporate network. You want to call
it from a cloud application while preserving the identity of a cloud-authenticated user.
For this purpose, you need to define the following:
A connectivity destination in SAP HANA Cloud Platform, with ProxyType = OnPremise
A system mapping made in the cloud connector. (Go to
select Kerberos.)

Access Control

Add , and for Principal Type,

Kerberos configuration in the cloud connector, where the service user is allowed to delegate calls for your
back-end host service. See the Procedure section above.

502

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Result:
When these configurations are provided, if you call a back-end system, the cloud connector will obtain an
SPNego token from your KDC for the cloud-authenticated user. This token will be sent along with the request to
the back end, so that it can authenticate the user and the identity to be preserved.

Related Information
Kerberos Configuration
Setting Up Trust [page 480]

1.4.1.3.13 Securing the Activation of Traffic Traces

Context
The cloud connector provides the possibility to trace all network traffic going through it (HTTP/RFC requests and
responses) for support purposes. This traffic data may contain business critical information or security sensitive
data, such as usernames, passwords, address data, credit card numbers, and so on. Thus, by activating the
corresponding trace level, a cloud connector administrator could see business data that he/she is not supposed
to see. If you want to prevent this behavior from occurring, you need to implement the following four-eyes
principle. This principle is supported by the cloud connector release 1.3.2 and higher.
Once the four-eyes principle is applied, activating a trace level that dumps traffic data will require two separate
users:
An operating system user on the machine where the cloud connector is installed;
An Administrator user of the cloud connector user interface.
By assigning these two users to two different persons, it can be ensured that both persons are needed to activate
a traffic dump (that is, when a certain problem needs to be troubleshot) but neither of them can do this on their
own.

Four-Eyes Principle for Microsoft Windows OS

1. Go to directory <scc_install_dir>\scc_config and create a file with name writeHexDump. The owner
of this file needs to be different from the operating system user that runs the cloud connector process.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

503

Note
Usually, this is the user which is specified in the Log On tab in the properties of the cloud connector service
(in the Windows Services console). Note that the Local System user should not be used in this case. You
shall better have a dedicated OS user for the cloud connector service.
Only the owner of the file and no other user shall have write permission for the file.
The OS user that runs the cloud connector process needs read-only permissions for this file.
Initially, the file should contain a line like allowed=false.
In the security properties of the file scc_config.ini (same directory), make sure that only the OS user
that runs the cloud connector process has write/modify permissions for this file. The best way to achieve
this is by just removing all other users from the list.
2. Once this file is located there, the cloud connector will refuse any attempt at activating the Payload Trace flag.
3. In order to activate the payload trace, first the owner of the writeHexDump file mentioned above needs to
change the file content from allowed=false to allowed=true. Then, the Administrator user can activate
the payload trace from the cloud connector administration screens.

Four-Eyes Principle for Linux OS/Mac OS X


1. Go to directory /usr/local/vl/base/cfg (cloud connector 1.3.2) or /opt/sap/scc/scc_config (cloud
connector 2.x) and create a file with name writeHexDump. The owner of this file needs to be different from
the scctunnel user (that is, the operating system user under which the cloud connector processes run) and
not a member of the operating system user group sccgroup.
Only the owner of the file and no other user shall have write permission for the file.
The scctunnel user needs read-only permissions for this file.
Initially, the file should contain a line like allowed=false.
2. Once this file is located there, the cloud connector will refuse any attempt at setting the trace level higher than
Runtime (cloud connector 1.3.2) or at activating the Payload Trace flag (cloud connector 2.x).
3. In order to set a higher trace level, which includes traffic Hex-dumps (cloud connector 1.3.2), or to activate the
payload trace (cloud connector 2.x), first the owner of the file mentioned above needs to change the file
content from allowed=false to allowed=true. Then, the Administrator user can activate one of the higher
trace levels (cloud connector 1.3.2) or the payload trace (cloud connector 2.x) from the cloud connector
administration screens.

1.4.1.3.14 Audit Logging in the Cloud Connector

504

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Starting with version 2.2, the cloud connector is providing an auditor tool. It allows you to verify the integrity of the
available audit log files.

Audit Logs in the Cloud Connector


From Content Audit , you can specify which kind of audit events the cloud connector should log at runtime.
Currently, you can choose between three different Audit Levels:
Security: Default value. The cloud connector writes an audit entry for each request that was blocked
("Access Denied"). It also writes audit entries, whenever an administrator changes one of the critical
configuration settings, such as exposed backend systems, allowed resources, and so on.
All: The cloud connector writes one audit entry for each received request, regardless of whether it was
allowed to pass or not ("Access Allowed" and "Access Denied"). It also writes audit entries relevant to the
Security mode.
Off: No audit entries are written.

Note
We recommend that you switch to All only in case of legal requirements or company policies for which not
only security-relevant events shall be logged.

Audit entries for configuration changes are written for the following different categories:
BackendMapping: Something changed in the virtual to internal system mappings.
AllowedResource: For one of the virtual systems, something changed in the accessible resources.
DomainMapping: Something changed in the domain mappings.
ServiceChannelConfiguration: The configuration of a service channel was changed.
SCCPassword: The cloud connector administration password was changed.
LDAPConfiguration: Something changed in the LDAP settings.
SNCSettings: The cloud connector's SNC settings were changed.
Configuration: The settings for the connection to SAP HANA Cloud were changed.
ProxySettings: The proxy settings were changed.
SystemCertificate: The system certificate was changed.
Account: The account configuration was changed.
PrincipalPropagationConfiguration: The principal propagation settings were changed.
TrustSynchronization: The trust configuration for principal propagation was synchronized.
IdentityProviderTrust: The trust configuration for a specific identity provider was changed.
KerberosConfiguration: The Kerberos configuration was changed.
ApplicationTrust: The trust configuration to applications was changed.
AuditLogLevel: The audit log level was changed.
PayloadTrace: Payload trace (traffic data) was activated/deactivated.
CPICTrace: The CPIC trace level was changed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

505

In the Audit Viewer section, you can first define filter criteria and then display the selected audit entries.
In the Audit Type field, you can select whether you want to view the audit entries for:
only requests that were denied;
only requests that were allowed;
cloud connector changes;
all of the above.
In the Pattern field, you can specify a certain string that the detail text of each selected audit entry must
contain. The detail text contains information about the user name, requested resource/URL, and the virtual
<host>:<port>. Wildcards are currently not supported in this field. This feature can help you:
Filter the audit log for all requests that a particular HTTP user has made during a certain time frame
Identify all users who attempted to request a particular URL
Identify all requests to a particular back-end system
Find out whether someone has changed a certain SAP HANA Cloud connnector configuration. For
example, a search for string "BackendMapping" will return all add-, delete- or modify- operations on
the Mapping Virtual To Internal System page.
The Time Range settings specify the time frame for which you want to display the audit events.
These three filter criteria are combined with a logical AND so that all audit entries that match these criteria are
displayed. If you have modified one of the criteria, choose the Refresh button to display the updated selection of
audit events that match the new criteria.

Note
In order to ensure separation of concerns, we recommend that the operating system administrator and the
SAP HANA Cloud Platform administrator are different persons. Thus, a single person cannot change audit log
level and delete all existing audit logs. Additionally, we recommend to turn on the audit log on operating system
level for file operations.

The

Check button checks all files that are filtered by the specified date range.

Verifying the Integrity of Audit Logs


To check the integrity of the audit logs, go to <scc_installation>/auditor. This directory contains an
executable go script file (respectively, go.cmd on Microsoft Windows OS and go.sh on other OS).
if you start the go file without specifying parameters from <scc_installation>/auditor, it will start the
verification of all available audit logs for the current cloud connector installation.
The tool is built as a Java Application and hence requires Java runtime for execution. The best way is to specify
JAVA_HOME:
For Microsoft Windows OS, set JAVA_HOME=<path-to-java-installation>
For Linux OS and Mac OS X, export: JAVA_HOME=<path-to-java-installation>
Alternatively, include the Java bin directory into the PATH variable so that Java can be executed.

506

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
In the following example, the Audit Viewer displays all audit entries on level Security, with denied access, for the
time frame between May 28, 00:00:00 and May 28, 23:59:59:

1.4.1.3.15 Installing a Failover Instance for High Availability


The cloud connector allows installation of a redundant instance, which monitors the main instance.

Context
In the case when the main instance goes down, the redundant one takes over its role. The main instance of the
cloud connector is called master and the redundant instance - shadow. The shadow has to be installed and
connected to its master. During the setup of high availability, the master pushes the whole configuration to the
shadow. Later on, during a normal operation, the master also pushes configuration updates to the shadow,
whenever the configuration is changed. Thus, the shadow instance is kept synchronized with the master instance.
The shadow pings the master regularly, and if the master is not reachable for a while, the shadow tries to take over
the master role and to establish the tunnel to SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

507

Procedure
Preparing the Master Instance for High Availability
1. Open the cloud connector UI and go to the master instance.
2. Go to the Settings tab and choose High Availability.
3. Select checkbox High Availability Through Shadow System Enabled.

If this flag is not activated, no shadow instance can connect itself to this cloud connector. Additionally, when
providing a concrete Shadow Host, you can ensure that only from this host a shadow instance can be
connected.

Note
By pressing the Reset button, all high availability settings will be reset to their initial state. As a result high
availability will be disabled and the shadow host will be cleared. Resetting will only work if no shadow is
connected.

Installing and Setting Up a Shadow Instance


The shadow instance must be installed in the same network segment as the master instance. Communication
between master and shadow via proxy is not supported. The same distribution package is used for master and
shadow instance.

508

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
If you plan to use LDAP for the user authentication on both master and shadow, make sure you configure it
before establishing the connection from shadow to master.
1. On first start-up of a cloud connector instance, a UI wizard asks you whether the current instance should be
master or shadow.

2. Choose Shadow and provide connection data for the master instance. On first connect, you will be forced to
log on to the master instance. The user and password of the master instance are required. Later on, the
master and shadow instances exchange RSA certificates, which will be used for mutual authentication.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

509

Note
If you decide to attach the shadow instance to a different master, choose the Reset button. All your high
availability settings will be removed, that is, reset to their initial state. This will only work if the shadow is
currently not connected.
3. On successful connect, the master instance pushes the whole configuration and some information about
itself to the shadow instance. This information can be viewed in the UI of the shadow instance, but cannot be
modified.

4. The UI on the master instance shows information about the connected shadow instance. Choose the High
Availability icon under Account Dashboard:

510

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. As of version 2.6.0, in this High Availability view on the master, at the bottom there is an Alert Messages
panel displaying alerts in case configuration changes had not been pushed successfully before. This could
happen if a temporary network failure occurs just at the time a configuration change is done. Thus, an
administrator can recognize whether there is an inconsistency in the configuration data between master and
shadow that could cause trouble if the shadow needs to take over. Typically, the master recognizes this
situation and tries to push the configuration change at a later time automatically. If this is successful, all
failure alerts will be removed and replaced by a warning alert showing that there had been trouble before.
In case it does not recover automatically, disconnect/connect the shadow, which will trigger a complete
configuration transfer.

Related Information
Initial Configuration [page 459]
Master and Shadow Administration [page 512]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

511

1.4.1.3.15.1 Master and Shadow Administration

Administration of Shadow Instances


There is few administration required (if possible) on the shadow instance. All configuration of tunnel connections,
host mappings, access rules, and so on, must be maintained on the master instance. They can be replicated over
to the shadow instance only for display reasons. You may want to modify the check interval (time between
checks of whether the master is still alive) and the takeover delay (time the shadow waits to see whether the
master would come back online, before taking over the master role itself).
Keep in mind:
The log level on master and shadow instances can be different.
Configuration for check interval and takeover delay is maintained on the shadow instance only, and will be
transferred to the master for display.
Audit logs are written on the master instance only and will not be transferred to the shadow. That means, if
the shadow has become master for a while, during which the original master was down, the audit log is
potentially distributed over both master and shadow instances.
If you want to drop all configuration on the shadow that is related to the master, choose the Reset button, but only
if the shadow is not connected to the master.

Failover Process
The shadow instance checks regularly if the master instance is still alive. Once the check fails, the shadow
instance tries to re-establish the connection to the master instance for a time period specified by the takeover
delay parameter.
If during this time, no connection was possible, the shadow tries to take over the master role. At this point, it is
still possible for the master to be alive and the trouble to be caused by a network issue between the shadow
and master. In any case, the shadow instance then tries to establish a tunnel to the given SAP HANA Cloud
Platform account. If the original master is still alive (and consequently its tunnel to the cloud account is still
active), this attempt will be denied and the shadow will remain in "shadow status", periodically pinging the
master and trying to connect to the cloud, while the master is not yet reachable.
Otherwise, the cloud side allows the tunnel to be opened and the shadow instance therefore knows that the
master is indeed down, and takes over its role. Starting this moment, the shadow instance displays the UI of a
master instance and allows the usual operations of a master instance, e.g. starting/stopping tunnels,
modifying the configuration, etc.
When the former master instance is started again, it first checks whether in the meantime the registered shadow
instance has taken over the master role. In such a case, the master registers itself as a shadow instance on the
former shadow (now master) instance. Thus, the two cloud connector installations, in fact, have switched their
roles.

512

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
Only one shadow instance is supported. Any further shadow instances attempting to connect will be declined
by the master instance.
The master considers a shadow as lost, if no check/ping is received from that shadow instance during a time
interval of three times the check period. Only after this period, another shadow system can register itself.

Note
On the master, it is possible to trigger a failover process by choosing the Switch Roles button. If the shadow is
up, this works as described before, but even if the shadow can not be reached, a role switch of the master can
be enforced. Only enforce the switch if you are absolutely sure that this is right.

Related Information
Installing a Failover Instance for High Availability [page 507]

1.4.1.3.16 Changing the UI Port

Context
By default, the cloud connector uses port 8443 for its administration UI. In case this port is blocked by another
process, or if you just want to change it after the installation (on Windows, you can choose a different port during
installation), you can use the changeport tool, provided with cloud connector version 2.6.0 and higher.

Procedure
1. Change to the installation directory of the cloud connector. To adjust the port, execute the following
command:
Microsoft Windows OS:
changeport <desired_port>
Linux OS, Mac OS X:
./changeport.sh <desired_port>
2. The tool will inform you about the successful modification of the port.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

513

3. To activate the new port, you need to restart the cloud connector.

1.4.1.3.17 Troubleshooting
Overview
This page provides you with details on how to monitor the state of your open tunnel connections in the cloud
connector. You can also view different types of logs and traces that can help you troubleshoot connection
problems.
To find a solution for a particular problem or an error you have encountered, you can refer to the cloud connector
troubleshooting pages. For more information, see Connectivity Support [page 544].

Monitoring
It is possible to view the list of all currently connected applications. To do that, choose the account you are
interested in, go to the Connector State tab and check the Connections section.

The information available covers:


Application name: The name of the application, as also shown in the cockpit, for your account
Connections: The number of currently existing connections to the application
Connected Since: The earliest start time of a connection to this application
Peer Labels: The name of the application processes, as also shown for this application in the cockpit, for your
account.

Logs
On the Logs tab page, you can find some log files that can help you troubleshoot problems with the internal
operation of the cloud connector. These logs are intended primarily for SAP Support. They cover both internal
cloud connector operations and details about the communication between the local and the remote (SAP HANA
Cloud Platform) tunnel endpoint.

514

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Log and Trace Settings


If you encounter problems during your business process, which seem to be caused by some trouble in the
communication between your cloud application and the on-premise system, you can go to the Logs tab page and
activate payload tracing there, by checking the option Payload Trace.

Note
Use payload and CPIC tracing on Level 3 carefully and only when requested to do so for support reasons. In
particular, the trace may write sensitive information (such as payload data of HTTP/RFC requests and
responses) to the trace files, and thus, present a potential security risk. For this reason the cloud connector
(effective version 2.2) supports an implementation of a "four-eyes principle" for activating the trace levels that
dump the network traffic into a trace file. When this four-eyes principle is in place, two users are required for
the activation of a trace level that would record traffic data.
For more information about setting this extra security measure, see Securing the Activation of Traffic Traces
[page 503].
When the payload trace is activated for an account, all the HTTP and RFC traffic crossing the tunnel for that
account going through this cloud connector, is traced in files with names traffic_trace_<account
id>_on_<landscapehost>.trc.
CPIC Trace Level allows you to set the level between 0 and 3 and provides traces for the CPIC-based RFC
communication with ABAP systems.
Log Level adjusts the levels for Java loggers directly related to cloud connector functionality.
In case All Loggers is marked as well, the changes to the log level will affect all Java loggers available in the
runtime (which is very rarely needed). You only need to change the level when requested by SAP Support.

Log and Trace Files


In this section, you can view all existing trace files and delete the ones that are no longer needed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

515

To prevent your browser from being overloaded when files of several megabytes or even gigabytes are loaded
simultaneously, the cloud connector loads only one page into memory and you can display the trace file one page
at a time. Use the paginator buttons to scroll forward/backward by one page (angle bracket), or jump to the
beginning or the end of the file (angle bracket plus vertical bar).
Via the Download/Download All buttons you can create a ZIP archive containing one particular trace file or all
trace files and download it to your local file system for convenient analysis of larger trace files.

Note
Trace files currently in use by the cloud connector cannot be deleted from the UI. Linux OS allows them to be
deleted from the command line, but we recommend that you do not use this option to avoid inconsistencies in
the internal trace management of the cloud connector.
Once a problem has been identified, you can turn off the trace again from this page.
On this screen, you can use the Refresh button to update the displayed information. (This option is also available
on all other screens.) For example, you can use this button because more trace files might have been written since
you last updated the display.

516

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Get Support [page 1325]

1.4.1.3.18 Monitoring

Monitoring in the Cockpit


The cockpit provides a Connectivity view. Here an administrator can check the status of the cloud connector
attached in the current account, if any. The view provides information about the cloud connector ID, version, used
Java runtime, high availability setup, and some more details. Access is granted to administrators, developers and
support users.

Monitoring in the Cloud Connector


The cloud connector offers various views for monitoring its activities and state. Choose one of the sub-menus of
Monitoring:

Performance Overview
All requests that went through the cloud connector to the respective back-ends as specified through access
control take a certain amount of time. You can check the duration of requests in a bar chart. The bar chart either
shows the duration statistics for all virtual hosts or for a selected virtual host. The requests are not shown
individually, but are clustered (assigned to buckets). Each of these buckets represents a time range.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

517

For example, the first bucket contains all requests that took 10ms or less, the second one the requests that took
longer than 10ms, but not longer than 20ms. The last bucket contains all requests that took longer than 5000ms.
The collection of duration statistics starts as soon as the cloud connector is operational. At any point you may
delete all of these statistical records using the button Delete All. After that, the collection of duration statistics will
start from scratch.

Note
Deleting means that the list of most recent requests as well as top time consumers (see below) will be cleared.

Most Recent Requests


A table shows recorded requests starting with the most recent requests:

The number of displayed requests is limited to 50. You can either view all requests or just the ones destined for a
certain virtual host, which you can select from a drop-down box. For all requests listed in the table you can view
the details by selecting the respective table row:

518

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

A horizontal stacked bar chart breaks down the duration of the request into 5 parts as per legend. The numbers
shown on the chart sections are milliseconds.

Note
Parts with a duration of less than 1ms are not shown at all.
In the example shown above the selected request took 25ms, to which the cloud connector contributed 1ms.
Opening a connection took 5ms. Processing at the back-end side consumed 7ms. Latency effects accounted for
the remaining 12ms, while there was no SSO handling necessary and hence it took no time at all.

Top Time Consumers


This view is in major parts identical to Most Recent Requests. However, requests are not shown in order of
appearance, but rather sorted by their duration (in descending order). Furthermore, you can delete top time
consumers, which has no effect on most recent requests nor the performance overview.

Back-end Connections
This section shows a tabular overview of all active and idle connections, aggregated for each virtual host. By
selecting a row (i.e. a virtual host) you can view the details of all active connections as well as a graphical summary

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

519

of all idle connections. The graphical summary is an accumulative view of connections based on the time the
connections have been idle.
The maximum idle time is displayed on the rightmost side of the horizontal axis. For any point t on that axis
(representing a time value ranging between 0ms and the maximal idle time) the ordinate is the number of
connections that have been idle for not more than t. You can click inside the graph area to view the respective
abscissa t and ordinate.

Hardware Metrics
You can check the current state of critical system resources through pie charts. Furthermore, the history of CPU
and memory usage (recorded in intervals of fifteen seconds) is displayed graphically.
The history graphs allow you to:
view the usage at a certain point in time by clicking inside the main graph area, and
zoom in on a certain excerpt of the historic data through standard click, drag and release of the left mouse
button.
The entire historic data is always visible in the smaller bottom area right below the main graph.
In case you have zoomed in, an excerpt window in the bottom area shows you where you are in the main area with
respect to the entire data. You can:
drag that window (press left mouse button when inside the window and keep it pressed down while dragging)
or
position it somewhere else by clicking anywhere inside the bottom area. You can also
undo zooming, using the button located in the top right corner of the respective graph area.

Monitoring APIs
As a user of the cloud connector, you might want to integrate some monitoring information in the monitoring tool
you use. In future, the cloud connector will offer more APIs for that purpose. Find below the APIs currently
available.

Health Check (version 2.6.0)


With the health check API, it is possible to recognize that the cloud connector is up and running. The purpose of
this health check is only to verify that the Cloud connector is not down. It does not check any internal state, nor
tunnel connection states. Thus, it is a quick check, which you can often execute.
Table 235:
URL

Expected Return Code

https://<scc_host>:<scc_port>/exposed?

200

action=ping

520

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Monitoring Java Applications [page 1149]

1.4.1.3.19 Alerting
You can configure the cloud connector to send out Emails whenever critical situations occur that may prevent it
from operating flawlessly in the near or not so distant future. Choose Alerting from the top left navigation area to
set up and tailor alerting to your needs:

Email Configuration
In this section you can specify the list of Email addresses to which alerts should be sent (Send To).

Note
You can assign Email addresses in compliance with RFC 2822. For instance, both john.doe@company.com and
John Doe <j.doe@company.com> are valid Email addresses.
Optionally, you can enter the sender's Email address (Sent From).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

521

Specification of the mail server (SMTP Server) is mandatory.


The SMTP port may be specified if necessary. For details, contact your Email administrator or provider.
The same goes for User and Password.
Press Save to change the current Email configuration.

Observation Configuration
In this section you can configure the surveillance of pivotal resources and components of the cloud connector:
Emails will be sent out as soon as any of the chosen components or resources is deemed to malfunction, or is
considered to be in a critical state.
High Availability deals with issues that can occur in the context of an active high availability set up, meaning a
shadow system is connected. Whenever a communication problem is detected in this context an alert is
produced.
Tunnel Health and Service Channels Health refer to the state of the respective connections. Whenever such a
connection is lost, an alert is triggered.
An excessively high CPU load over an extended period of time adversely affects performance and may be an
indicator of serious issues that jeopardize the operability of the cloud connector. The CPU load is monitored
and an alert is triggered whenever the CPU load exceeds and continues to exceed a given threshold
percentage (default is 90%) for more than a given period of time (default is 60 seconds).
The cloud connector does not require nor consume large amounts of Disk space. However, running out of disk
space remains an undesirable circumstance that you should avoid.

Note
We recommend to send out an alert if the disk space falls below a critical value (default is 10 megabytes).
To configure the components to be monitored, proceed as follows:
1. Check the components or resources that you want to keep under surveillance. The selected components and
resources will be examined every 30 seconds by default.
2. If you wish to change the Health Check Interval enter the number of seconds of your choice into the respective
field at the bottom.
3. Press Save to change the current configuration.

Alert Messages
The cloud connector does not only send out alert messages via Email, it also lists them in this section. However,
the cloud connector does not dispatch the same alert repeatedly. Instead, an informational alert is generated,
sent out and listed, as soon as the respective and previously reported issue has been resolved (i.e., cannot be
detected anymore).
You can remove alerts using Delete or Delete All.

522

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
This is particularly sensible in the case of informational alerts and alerts that have obviously been resolved.
Deleting alerts that pertain to issues that still occur is futile as they will reappear.

1.4.1.3.20 Uninstalling the Cloud Connector

Context
If you have installed a productive version of the cloud connector 2.x, follow the steps below according to your
operating system.

Note
For uninstalling a developer version, proceed as described in section Developer Versions.

Microsoft Windows OS
1. Go to Windows Software administration.
2. Search for SAP HANA cloud connector 2.x.
3. Double-click on the entry and confirm the successful uninstallation dialog.
4. Confirm again for User account control that it is OK to uninstall.
5. When doing the uninstallation in the context of an upgrade, make sure to retain the configuration files.

Linux OS
To uninstall cloud connector 2.x, execute:
rpm -e com.sap.scc-ui

Caution
Bear in mind that this command will also remove the configuration files.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

523

Mac OS X
There is no productive version for Mac OS X, only a developer version (see below).

Developer Versions
If you have installed a developer version (zip archive) of the cloud connector, just remove the directory in which
you have originally extracted the cloud connector archive.

Note
This procedure is relevant for Microsoft Windows OS, Linux OS and Mac OS X developer versions.

Related Information
Installing the Cloud Connector [page 436]

1.4.1.3.21 Cloud Connector Operator's Guide


Table 236:
To learn about

See

The general big picture

Introduction [page 525]

All the system requirements

System Requirements [page 527]

The available network zones

Network Zones [page 529]

How to install a cloud connector on Microsoft Windows OS

Cloud Connector on Microsoft Windows [page 530]

How to install a cloud connector on Linux OS

Cloud Connector on Linux [page 531]

How to create a shadow instance for the cloud connector

High Availability Setup of the Cloud Connector [page 532]

How to administer the cloud connector

Cloud Connector Administration [page 532]

How to securely operate the cloud connector

Guidelines for Secure Operation of Cloud Connector [page


538]

How to monitor the cloud connector

Monitoring [page 540]

How to handle issues with the cloud connector

Supportability [page 540]

The releases and maintenance

Release and Maintenance Strategy [page 541]

Hybrid scenarios with the cloud connector

Process Guidelines for Hybrid Scenarios [page 541]

524

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.3.21.1 Introduction
The cloud connector is an on-premise agent that runs in the customer network and takes care of securely
connecting cloud applications, running on SAP HANA Cloud Platform, with services and systems of the customer
network. It is used to implement hybrid scenarios, in which cloud applications require point-to-point integration
with existing services or applications in the customer network. The following diagram shows a high-level picture of
the landscape:

This document provides a guide for IT administrators how to setup, configure, securely operate and protect the
cloud connector, version 2.x, in productive scenarios.

Sections
This Operators guide is structured as follows:
System requirements for the cloud connector
This section provides an overview on the minimal and recommended system requirements needed to install
and run the cloud connector.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

525

Installation, upgrade, and uninstallation of the cloud connector (on Windows or Linux operating systems)
This section describes the lifecycle management operations of the cloud connector, i.e. how to install,
upgrade and uninstall it, as well as how to start the cloud connector process after installation.
High Availability
This section provides information on how to install a shadow instance, which needs to be reachable in case
the master instance of the cloud connector goes down.
Administration and configuration of the cloud connector
This section provides an overview on how to administrate and configure the cloud connector and how to
securely operate it. For example: how to configure on-premise resources which shall be accessible to the
related cloud account; how to configure trust between the cloud connector and an on-premise system; how to
configure named administrator users for the cloud connector administration; and so on.
Guidelines for secure operation of the cloud connector
This section summarizes briefly all guidelines and recommendations for a secure setup of the cloud
connector as they are relevant for productive scenarios. It also provides references to the single sections of
this operators guide where the related topics are described in more detail.
Monitoring
This section provides an overview on how to monitor the cloud connector-based connectivity to the cloud,
and describes high-availability features of the cloud connector.
Supportability
This section provides an overview on supportability in case of issues with the cloud connector.
Maintenance and release strategy
This section describes the maintenance and release strategy of the cloud connector, how new patches or new
versions are released, and where to find information about new releases.
Process guidelines for hybrid scenarios
This section provides process guidelines which help to manage and operate hybrid scenarios.

Target Audience
System administrators, IT administrators, cloud account administrators

Additional Information
This document focuses on the operation aspects of the cloud connector. It does not cover a general overview of
the SAP HANA Cloud Platform and its connectivity service; neither does it address development related
questions, such as how to implement connectivity-enabled applications.
For additional information on specific topics, see the following online resources:
Table 237:
Resource

Link

SAP HANA Cloud Platform documentation

https://help.hana.ondemand.com/

SAP HANA Cloud Platform connectivity service documenta


tion

https://help.hana.ondemand.com/help/frameset.htm?
e54cc8fbbb571014beb5caaf6aa31280.html

526

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Resource

Link

SAP HANA cloud connector documentation

https://help.hana.ondemand.com/help/frameset.htm?
e6c7616abb5710148cfcf3e75d96d596.html

SAP HANA Cloud Platform Release Notes

http://scn.sap.com/docs/DOC-28833

SAP Community Network

http://scn.sap.com/community/developer-center/cloudplatform

SAP security

https://service.sap.com/security

SAP security guides, network security

https://service.sap.com/securityguide

SAP HANA Cloud Platform openSAP course

https://open.sap.com/course/hanacloud1
Videos of openSAP course "Introduction to SAP HANA Cloud
Platform"

Registration for free SAP HANA Cloud Platform account

https://account.hanatrial.ondemand.com/

1.4.1.3.21.2 System Requirements


This section describes the hard- and software requirements needed to install and run the cloud connector.

Hardware Requirements

Table 238:
Minimum

Recommended

CPU

Single core 3 GHz, x86-64 architecture


compatible

Dual core 2 GHz, x86-64 architecture


compatible

Memory (RAM)

1 GB

4 GB

Free disk space

1 GB

20 GB

Software Requirements

Table 239:
Operating System

Architecture

Windows 7, Windows 8.1, Windows 10, Windows Server 2008


R2, Windows Server 2012, Windows Server 2012 R2

x86_64

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

527

Operating System

Architecture

SUSE Linux Enterprise Server 11, SUSE Linux Enterprise


Server 12, Redhat Enterprise Linux 6, Redhat Enterprise Linux
7

x86_64

Note
An up-to-date list with detailed cloud connector version information is available from Prerequisites [page 437]
section.

Supported Browsers
The browsers that can be used for the cloud connector Administration UI are the ones supported by SAP UI5.
Currently, these are the following:
Microsoft Internet Explorer 9 or higher
Mozilla Firefox 10 and latest version
Safari 5.1 and higher
Google Chrome (latest versions)
An up-to-date list of the supported SAP UI5 browsers can be found here: Browsers for Platforms

Cloud Connector Software Download


The cloud connector can be downloaded from the Cloud Tools page.

Free Disk Space


Installation size
To download and install a new cloud connector server, a minimum of free disk space is required as following:
Size of downloaded cloud connector installation file (ZIP, TAR, MSI files): 50 MB
Newly installed cloud connector server: 70 MB
Total: 120 MB as a minimum

Additional disk space for log and configuration files


The cloud connector writes configuration files, audit log files and trace files at runtime. The recommendation is to
accommodate between 1 and 20 GB of disk space for those files.

528

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Trace and log files are written to <scc_dir>/log/ within the cloud connector root directory. The
ljs_trace.log file contains traces in general, communication payload traces are stored in
traffic_trace_*.trc. They are used for support cases to analyze potential issues. The default trace level is
set to Information, where the amount of written data is in the range of few KB each day. You can turn off these
traces to save disk space. However, it is not recommended to turn off this trace completely, but to leave it with the
default settings to allow root cause analysis in case an issue occurs. If the trace level is increased to All, the
amount of data can easily reach the range of several GB per day. We recommend that you only use trace level All
for analyzing a particular issue. Payload trace, however, should be turned off normally and only in case of certain
issues turned on for supporting analysis by SAP support.

Note
From operations perspective, we recommend that you back up or delete written trace files regularly in order to
clean up the used disk space.
Audit log files are written to /log/audit/<account-name>/audit-log_<account-name>_<date>.csv
within the cloud connector root directory. By default, only security related events are written within the audit log.
The cloud connector administrator can change the audit log level using the administration UI, as described in:
Audit Logging in the Cloud Connector [page 504]
To be compliant with the regulatory requirements of your organization and the regional laws, the audit log files
must be persisted for a certain period of time for traceability purposes. Therefore, it is recommended to back up
the audit log files regularly from the cloud connector file system and to keep the backup for a certain period of
time, fitting to those rules.

1.4.1.3.21.3 Network Zones


Usually, a customer network is divided into multiple network zones or sub-networks according to the security level
of the contained components. There is, for instance, the DMZ that contains and exposes the external-facing
services of an organization to an untrusted network, usually the Internet, and there is one or multiple other
network zones which contain the components and services provided in the companys intranet.
Generally, customers have the choice in which network zone the cloud connector should be set-up in their
network. Technical prerequisites for the cloud connector to work properly are:
cloud connector must have internet access to the SAP HANA Cloud Platform landscape host, either directly
or via HTTPS proxy.
cloud connector must have direct access to the internal systems it shall provide access to. That means, there
must be transparent connectivity between the cloud connector and the internal system.
Depending on the needs of the project, the cloud connector can be either set-up in the DMZ and operated
centrally by the IT department or set-up in the intranet and operated by the line-of-business.

Note
The internal network must allow access to the port. Specific configuration for opening the respective port(s)
depends on the firewall software used.
The default ports are 80 for HTTP and 443 for HTTPS. For RFC communication, you need to open a gateway
port (default: 33+<instance number> and an arbitrary message server port. For a connection to a HANA

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

529

Database (on SAP HANA Cloud Platform) via JDBC, you need to open an arbitrary outbound port in your
network. Mail (SMTP) communication is not supported.

1.4.1.3.21.4 Cloud Connector on Microsoft Windows


Currently, the cloud connector supports the following Microsoft Windows OS versions: MS Windows 7 64-bit
and MS Windows Server 2008 R2 64-bit. This section describes how to install, upgrade, uninstall and start/
stop the cloud connector process on MS Windows operating systems.

Installation
Detailed documentation on how to install the cloud connector on Microsoft Windows can be found here:
Installation on Microsoft Windows OS [page 440]

Note
The Windows MSI installer must be used for productive scenarios, as only then the cloud connector gets
registered as a MS Windows service (SAP HANA Cloud Connector 2.0). Your company policy defines the
privileges to be allowed for service users. Then, adjust the folder/file permissions to be manageable by only a
limited-privileged user and system administrators.

Upgrade
Detailed documentation on how to upgrade the cloud connector on Microsoft Windows can be found here:
Upgrading the Cloud Connector [page 458]

Starting the Cloud Connector


After the installation, the cloud connector is registered as a Windows service which is configured to be started
automatically. With this configuration, the cloud connector process will be started automatically after a reboot of
the system. You can start and stop the service via shortcuts created on the desktop ("Start Cloud Connector
2.0" and "Stop Cloud Connector 2.0"), or by using the Windows Services manager and look for the
service SAP HANA cloud connector 2.0.
Once started, the cloud connector administration UI can be accessed at https://localhost:<port>, where the
default port is 8443 (this port could have been modified during the installation).

530

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Uninstallation
Detailed documentation on how to uninstall the cloud connector on Microsoft Windows can be found here:
Uninstalling the Cloud Connector [page 523]

1.4.1.3.21.5 Cloud Connector on Linux


Currently, the cloud connector supports the following Linux OS versions: SUSE Linux Enterprise Server 11
64-bit and Redhat Enterprise Linux 6 64-bit. This section describes how to install, upgrade, uninstall
and start/stop the cloud connector process on Linux operating systems.

Installation
Detailed documentation on how to install the cloud connector on Linux can be found here: Installation on Linux OS
[page 443]

Note
For productive scenarios, the cloud connector Linux RPM installer must be used, as only then the cloud
connector will be registered as a daemon process.

Upgrade
Detailed documentation on how to upgrade the cloud connector on Linux can be found here: Upgrading the Cloud
Connector [page 458]

Starting the Cloud Connector


After installing the cloud connector via RPM manager, the cloud connector process is started automatically and
registered as a daemon process, which takes care of restarting the cloud connector automatically after a reboot
of the system.
To start/stop/restart the process explicitly, you can open a command shell and use the following commands,
which require root permissions:
service scc_daemon stop|restart|start|status

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

531

Uninstallation
Detailed documentation on how to uninstall the cloud connector on Linux can be found here: Uninstalling the
Cloud Connector [page 523]

1.4.1.3.21.6 High Availability Setup of the Cloud Connector

Context
The cloud connector can be operated in a high availability mode, in which a master and a shadow instance are
installed. The main instance of the cloud connector is called master and the redundant instance - shadow. In the
case, when the master instance goes down, the shadow takes over its role and continues to serve the connectivity
with SAP HANA Cloud platform. For the shadow instance, a second cloud connector has to be installed, then
configured as a shadow, and connected to its master. The master instance pushes its whole configuration to the
shadow whenever the configuration of the master is changed. Thus, the shadow instance is kept synchronized
with the master. The shadow pings the master regularly, and if the master is not reachable for a while, the failover
happens and the shadow takes over the role of the master.

Activities
To learn how to install a failover (shadow) instance, see: Installing a Failover Instance for High Availability
[page 507]
To learn how to administer master and shadow instances, see: Master and Shadow Administration [page 512]

1.4.1.3.21.7 Cloud Connector Administration

Operating System Access and Configuration


As the cloud connector is a security critical component enabling external access to systems of an isolated
network, similar to a reverse proxy in a DMZ, we recommend that you restrict the access to the operating system
on which the cloud connector is installed to the minimal set of users who shall administrate the system. This will
minimize the risk of unauthorized people accessing the cloud connector system and trying to modify or damage a
running cloud connector instance.

532

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

We also recommend that you use hard-drive encryption for the cloud connector system. This ensures that the
cloud connector configuration data cannot be read by unauthorized users, even if they obtain access to the hard
drive.
To learn all tips and tricks for secure setup, see Recommendations for Secure Setup [page 446]

Configuring a Trusted Certificate for the Administration UI


After a new installation, the cloud connector provides a self-signed X.509 certificate used for the SSL
communication between the cloud connector Administration UI running in a Web browser and the cloud
connector process itself. For security reasons, this certificate should be replaced for productive scenarios with a
certificate trusted by your organization.
To learn in detail how to do this, read this page: Recommended: Replacing the Default SSL Certificate [page 452]

Basic Configuration
The basic configuration steps for the cloud connector consist of:
Changing the initial password for the built-in Administrator user
Connecting the cloud connector against a cloud account
Detailed documentation of these two steps can be found here: Initial Configuration [page 459]
You are forced to change the initial password to a specific one immediately after installation. The cloud connector
itself does not check the strength of the password, thus the cloud connector administrators should voluntarily
choose a strong password that cannot be guessed easily.

Related Information
Connecting and Disconnecting a Cloud Account [page 533]
Configuring Accessible Resources [page 534]
Configuring Trust between Cloud Connector and On-Premise Systems [page 536]
Configuring Named Cloud Connector Administrator Users [page 536]
Using the Audit Log [page 537]
Authenticating Users for On-Premise Systems [page 537]

1.4.1.3.21.7.1 Connecting and Disconnecting a Cloud Account


The major principle for the connectivity established by the cloud connector is that the cloud connector
administrator should have full control over the connection to the cloud, i.e. they should be able to decide if and

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

533

when the cloud connector need to be connected to the cloud at all, to which accounts it shall be connected, and
which on-premise systems and resources shall be accessible to applications of the connected account.
Using the administration UI, the cloud connector administrator can connect and disconnect the cloud connector
to the configured cloud account. Once disconnected, there is no communication possible neither between the
cloud account and the cloud connector nor to the internal systems. The connection state can be verified and
changed by the cloud connector administrator on the Account Dashboard tab of the UI as shown in the following
screen shot:

Note
Bear in mind that once the cloud connector is freshly installed and connected to a cloud account, still none of
the systems available in the customer network will be accessible to the applications of the related cloud
account. The systems and resources that shall be made accessible must be configured explicitly in the cloud
connector one by one. For more information, see Configuring Trust between Cloud Connector and On-Premise
Systems [page 536]
Effective cloud connector version 2.2.0, a single cloud connector instance can be connected to multiple
accounts in the cloud. This is useful especially for customers who need multiple accounts to structure their
development or to stage their cloud landscape into development, test, and production. These customers have the
option to use a single cloud connector instance for multiple accounts of theirs. Nevertheless, it is recommended
to not use accounts running productive scenarios and accounts used for development or test purposes within the
same cloud connector. A cloud account can be added to or deleted from a cloud connector viaAccount
Dashboard, using the Add and Delete buttons (see screenshot above).
A detailed description on how to add, delete, connect or disconnect accounts can be also found here: Managing
Accounts [page 474]

1.4.1.3.21.7.2 Configuring Accessible Resources


After a new cloud connector installation in a network, no systems or resources of the network have been exposed
to the cloud yet. The cloud connector administrator must configure each system and resource that shall be used

534

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

by applications of the connected cloud account in the Access Control view of the cloud connector, as shown in the
following screenshot:

Thereby, any type of system that can be called via one of the supported protocols (currently: HTTP and RFC), i.e.
both SAP and non-SAP systems are supported. As an example, a convenient way to access an ABAP system in a
cloud application is to do this via SAP NetWeaver Gateway, as it allows consumption of ABAP content via HTTP
and open standards.
Detailed documentation on how HTTP resources are configured can be found here: Configuring Access
Control (HTTP) [page 341]
Detailed documentation on how RFC resources are configured can be found here: Configuring Access Control
(RFC) [page 392]
We recommend that you narrow the access only to those backend services and resources that are explicitly
needed by the cloud applications. Instead of configuring, for example, a system and granting access to all its
resources, we recommend that you only grant access to the concrete resources which are needed by the cloud
application. For example, define access to an HTTP service by specifying the service URL root path and allowing
access to all its sub-paths.
When configuring an on-premise system, it is possible to define a virtual host and port for the specified system, as
shown in the screenshot below. The virtual host name and port represent the fully-qualified domain name of the
related system in the cloud. We recommend that you use the virtual host name/port mapping in order to prevent
from leaking information about the physical machine name and port of an on-premise system and thus of your
internal network infrastructure getting published to the cloud.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

535

1.4.1.3.21.7.3 Configuring Trust between Cloud Connector and


On-Premise Systems
For secure communication between the cloud connector and the used on-premise systems, it is recommended to
use encrypted protocols, like HTTPS and RFC over SNC, and to set up a trust relationship between the cloud
connector and the on-premise systems by exchanging certificates.
When using HTTPS as protocol, a trust relationship can be set-up by configuring the so-called system certificate
in the cloud connector. A system certificate is an X.509 certificate which represents the identity of the cloud
connector instance and is used as a client certificate in the HTTPS communication between the cloud connector
and the on-premise system. The used on-premise system should be configured to validate the system certificate
of the cloud connector to ensure that only calls from trusted cloud connectors are accepted.
A detailed documentation on how to use and configure the system certificate for a cloud connector can be found
here: Initial Configuration (HTTP) [page 339]
Analogously, SNC can be configured for secure RFC communication to an ABAP backend, as described here:
Initial Configuration (RFC) [page 391]

1.4.1.3.21.7.4 Configuring Named Cloud Connector


Administrator Users
We recommend that you configure LDAP-based user management for the cloud connector Administration UI so
that only named administrator users can log on to the administration UI. This is important to guarantee
traceability of the cloud connector configuration changes via the cloud connector audit log. With the default and

536

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

built-in Administrator user, it is not possible to identify the physical person who has done a possibly securitysensitive configuration change in the cloud connector.
If you have an LDAP server in your landscape, you can configure the cloud connector to authenticate cloud
connector administrator users against the LDAP server. Valid administrator users must belong to the user group
named admin or sccadmin. Documentation on how to configure an LDAP server can be found here: Using LDAP
for Authentication [page 477]
Once an LDAP has been configured for the authentication of the cloud connector, the default Administrator
user will be inactive and cannot be used anymore for logging on to the cloud connector.

1.4.1.3.21.7.5 Using the Audit Log


Audit logging is a critical element of an organizations risk management strategy. The cloud connector provides
audit logging for the complete record of access between cloud and cloud connector, as well as of configuration
changes done in the cloud connector. The written audit log files are digitally signed by the cloud connector so that
their integrity can be checked by the cloud connector auditor tool, as described here: Audit Logging in the Cloud
Connector [page 504]
The audit log data of the cloud connector can be used to alert cloud connector administrators to unusual or
suspicious network and system behavior. Additionally, the audit log data can provide auditors with information
required to validate security policy enforcement and proper segregation of duties. IT staff can use the audit log
data for root-cause analysis following a security incident.

Note
We recommend that you switch on audit logging of the cloud connector permanently in productive scenarios.
Normally, you should better set it to Security (the default configuration value).
In case of legal requirements or company policies, we recommend that you set it to All. In this way, the
audit log files can be used to detect attacks of, for example, a malicious cloud application that tries to
access on-premise services without permission, or in a forensic analysis of a security incident.

It is further recommended to copy the audit log files of the cloud connector regularly to an external persistent
storage according to your local regulations. The audit log files can be found in the cloud connector root directory
under the following location: /log/audit/<account-name>/audit-log_<timestamp>.csv.

1.4.1.3.21.7.6 Authenticating Users for On-Premise Systems


Currently, the cloud connector supports basic authentication and principal propagation as user authentication
types towards internal systems. The destination configuration of the used cloud application defines which of these
types is used for the actual communication to an on-premise system through the cloud connector. For more
information, see: Destinations [page 281]
In case basic authentication is used, the on-premise system must be configured to accept basic authentication
and to provide one or multiple service users. There are no additional steps which are needed in the cloud
connector for this authentication type.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

537

In case principal propagation is used, the cloud connector administrator has to explicitly configure trust to those
cloud entities from which user tokens are accepted as valid. This can be done in the Trust view of the cloud
connector and is described in more detail here: Setting Up Trust [page 480]

1.4.1.3.21.8 Guidelines for Secure Operation of Cloud


Connector
The following table summarizes the guidelines and recommendations for a secure setup and operation of the
cloud connector in a productive scenario.
#

Activity

Recommendation

Restrict OS level access to


the cloud connector

Restrict the access to the


cloud connector operating
system to the users who
should administrate the cloud
connector.

Use hard drive encryption for


the cloud connector
operating system

Use hard drive encryption to


avoid unauthorized access to
the cloud connector
configuration data and
credentials in case hard disk
gets stolen.

Change password of built-in


Administrator user
immediately after installation
and choose a strong
password

Cloud connector
administrator should change
the initial password manage

Authenticate with named


users to the cloud connector
Administrator UI

Configure an LDAP system in


the cloud connector and work
with named administrator
users to have better
traceability.

Change default X.509


certificate of cloud connector
Administration UI

The self-signed certificate


provided by the cloud
connector after a new
installation shall be changed
to an own certificate to
increase the security of the
SSL communication between
the cloud connector
administration UI and the
cloud connector server itself
and to avoid security
warnings of the browser
when connecting to the
administration UI.

538

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

to a strong password that


cannot be easily guessed.
Optionally, you can also
adjust the user name.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Activity

Recommendation

Use HTTPS and System


Certificate, or RFC via SNC
for communication from
cloud connector to backend

For communication between


cloud connector and the
backend systems, as well as
to authenticate a cloud
connector against the
backend systems, we
recommend that you use
HTTPS and a system
certificate, or RFC over SNC.

Use host name mapping of


exposed backend systems

When configuring the access


to an internal system in the
Access Control configuration
of the cloud connector, we
recommend that you use the
virtual host name mapping in
order to not expose physical
host names of systems of the
on-premise network to the
cloud.

Narrow access to backend


systems to required services

When configuring the access


to an internal system in the
Access Control view of the
cloud connector, we
recommend that you restrict
the system access to those
resources which are required
by the cloud applications. Do
not expose the complete
system just to save some
configuration work.

Switch on audit logging in


cloud connector to All

To recognize attempts of
attackers to get unauthorized
access to the cloud
connector, and to have full
traceability of the
communication and the
configuration changes, we
recommend that you switch
on the audit log to All.

10

Copy and persist audit log


files of cloud connector
regularly

The cloud connector audit log


files shall be copied regularly
from the cloud connector
machine to an external
persistent storage and kept
for a certain period of time
according to the regulatory
requirements.

11

Clean up cloud connector


traces regularly and set
default trace level to
Information

Cloud connector trace files


should be deleted regularly in
order to clean up disk space.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

539

Activity

Recommendation

Unless for error analysis, the


trace level of the cloud
connector should not be set
to a level higher than
Information in the regular
operation. Traces created for
analysis of an issue with trace
level All should be deleted
immediately after the issue
has been resolved.

1.4.1.3.21.9 Monitoring
To verify that a cloud connector is up and running, the simplest way is to try to access its administration UI. If the
UI can be opened in a Web browser, the cloud connector process is running.
On Microsoft Windows operating systems, the cloud connector process is registered as a Windows service,
which is configured to start automatically after a new cloud connector installation. In case the machine gets
rebooted, the cloud connector process should then be auto-restarted immediately. You can check the state
with the following command:
sc query "SAP HANA cloud connector 2.0"
The line state shows the state of the service.
On Linux operating systems, the cloud connector is registered as a daemon process and gets restarted
automatically each time the cloud connector process is down, like after a reboot of the whole system. The
daemon state can be checked with:
service cloud connector_daemon status
To verify if a cloud connector is connected to a certain cloud account, log on to the cloud connector
Administration UI and go to the Accounts Dashboard, where the connection state of the connected accounts are
visible, as described in section Connecting and Disconnecting a Cloud Account [page 533].

1.4.1.3.21.10 Supportability
In case of issues with the cloud connector, SAP customers and partners can create OSS tickets under the
component BC-MID-SCC.
The general SAP SLAs in regards of OSS processing time also apply for SAP HANA Cloud Platform and the cloud
connector. To avoid unnecessary answer/response cycles in the support case, we recommend that you download
the logs of the corresponding cloud connector, using the Download button on the Logs view, and to attach the
respective log file(s) to the OSS ticket directly when creating it.
In case the issue is easily reproducible, re-execute it at log level All before creating the archive.

540

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.1.3.21.11 Release and Maintenance Strategy


As for all components of SAP HANA Cloud Platform, new releases of the cloud connector are available on the
Cloud Tools page. As SAP HANA Cloud Platform releases in a bi-weekly cycle, new releases of the cloud connector
could occur every other week, although the actual releases will be more seldom (new releases are shipped when
new features or important bug fixes shall be delivered).
Cloud connector versions follow the <major>.<minor>.<micro> versioning schema. Within a major version, the
cloud connector will stay fully compatible. Within a minor version, the cloud connector will stay with the same
feature set, and higher minor versions usually support additional features compared to lower minor versions.
Micro versions are increased to release patches of a <master>.<minor> version in order to deliver bug fixes.
For each supported major version of the cloud connector, only one <major>.<minor>.<micro> version will be
provided and supported on the Cloud Tools page. This means that users have to upgrade their existing cloud
connectors in order to get a patch for a bug or to make use of new features.
New versions of the cloud connector are announced in the Release Notes
of SAP HANA Cloud Platform. We
recommend that cloud connector administrators check regularly the release notes for cloud connector updates.
New versions of the cloud connector can be applied by using the cloud connector upgrade capabilities. For more
information, see Upgrading the Cloud Connector [page 458].

Note
We recommend that you apply an upgrade first in the cloud connector test landscape to validate that the
running applications are working, and then continue with the productive landscape.
When updates are applied on the cloud, operations continuity of existing cloud connectors and its connections are
assured by the platform, i.e. users do not have to perform manual actions in the cloud connector when the cloud
side gets updated.

1.4.1.3.21.12 Process Guidelines for Hybrid Scenarios


The following chapter provides process guidelines that help you to manage productive hybrid scenarios, in which
applications running on SAP HANA Cloud Platform require access to on-premise systems.

Document Landscape of Hybrid Solution


To have an overview of the cloud and on-premise landscape relevant for your hybrid scenario, we recommend
that you document the used cloud accounts, their connected cloud connectors and the used on-premise backend
systems in landscape overview diagrams. Document the account names, the purpose of the accounts (dev, test,
prod), information of the cloud connector machines (host, domains), the URLs of the cloud connectors in the
landscape overview document, and possibly more details.
An example of landscape overview documentation could look like this:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

541

Document Administrator Roles


It is recommended to document which users have administrator access to the cloud accounts, to the cloud
connector operating system, and to the cloud connector Administration UI.
An example of such administrator role documentation could look like following sample table:
Table 240:
Resource

john@acme.com

Cloud Account (CA)


Dev1

CA Dev2

marry@acme.com

pete@acme.com

greg@acme.com

CA Test
CA Prod
cloud connector Dev1 + X
Dev2

X
X

cloud connector Test

cloud connector Prod


cloud connector Dev1 +
Dev2 file system
cloud connector Test
file system

X
X

X
X

cloud connector Prod


file system

542

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Document Communication Channels


It is recommended to create and document separate email distribution lists for both the cloud account
administrators and the cloud connector administrators.
An example of the documented communication channels could look like this:
Table 241:
Landscape

Distribution List

Cloud Account Administrators

DL ACME HCP Account Admins

Cloud Connector Administrators

DL ACME Cloud Connector Admins

Define Project and Development Guidelines


It is recommended to define and document mandatory project and development guidelines for your SAP HANA
Cloud Platform projects. An example of such a guideline could look like the following:
For every SAP HANA Cloud Platform project of your organization, the following requirements are mandatory:
Usage of Maven, Nexus, Git-&-Gerrit for the application development
Alignment with accountable manager in projects (name: Flora Miller)
Alignment with accountable security officer in projects (name: Pete Johnson)
For externally developed source code a hand over to your organization is required
Fulfill the connection restrictions in a 3 system landscape, i.e. usage of staged landscape for dev, test and
prod, and e.g. dev landscape only connects to dev systems, etc.
Productive accounts do not use the same cloud connector like a dev or test account

Define Process of How to Set a Cloud Application Live


It is recommended to define and document the process of how to set a cloud application live and how to configure
needed connectivity for such an application.
For example, the following processes could be seen as relevant and shall be defined and document in more detail:
1. Transferring application to production: This process defines the steps which are necessary for transferring an
application to the productive status on the SAP HANA Cloud Platform.
2. Application Connectivity: This process defines the steps which are necessary to add a connectivity
destination to a deployed application for connections to other resources in the test or productive landscape.
3. Cloud Connector Connectivity: This process defines the steps which are necessary to add an on-premise
resource to the cloud connector in the test or productive landscapes to make it available for the connected
cloud accounts.
4. On-premise System Connectivity: This process defines the steps which are necessary to setup a trust
relationship between an on-premise system and the cloud connector and to configure user authentication and
authorization in the on-premise system in the test or productive landscapes.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

543

5. Application Authorization: This process defines the steps which are necessary to request and assign an
authorization which is available inside the SAP HANA Cloud application to a user in the test or productive
landscapes.
6. Administrator Permissions: This process defines the steps which are necessary to request and assign the
administrator permissions in a cloud account to a user in the test or productive landscape.

1.4.1.4

Connectivity Support

What is this?
This section contains troubleshooting information related to SAP HANA Cloud Platform connectivity service and
the cloud connector. It provides solutions to general connectivity issues as well as to specific on-demand to onpremise cases.
Locate the problem or error you have encountered and follow the steps recommended in the solution.

SAP Support Information


If you cannot find a solution to your issue, use the following template to provide specific, issue-relevant
information. This helps SAP Support to resolve your problem case.
The Java EE code that throws an error (if any)
A screenshot of the error message displayed for the failed operation or the error message from the
HttpResponse body
Access credentials for your on-demand or on-premise location
You can submit this information by creating a customer ticket in the SAP CSS system. Use the following
components:
BC-NEO-CON - for general connectivity issues
BC-MID-SCC - for connectivity issues related to installing and configuring the cloud connector, configuring
tunnels, connections, and so on.
In case you experience a more serious issue that cannot be resolved with traces and logs only, access to the cloud
connector is needed by support. In such a situation, follow the instructions of the notes below:
For providing access to the Administration UI via a browser is described, check 592085

For providing SSH access to the operating system of the Linux machine, on which the connector is installed,
check 1275351 .

Related Information
Get Support [page 1325]
Cloud Connector Operator's Guide [page 524]

544

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2 Document Service


The SAP HANA Cloud Platform, document service provides an on-demand content repository for unstructured or
semi-structured content.

Overview
Applications access it using the OASIS standard protocol Content Management Interoperability Services (CMIS).
Java applications running on SAP HANA Cloud Platform can easily consume the document service using the
provided client library. A JavaScript client library is currently being developed. Since the document service is
exposed using a standard protocol, it can also be consumed by any other technology that supports the CMIS
protocol.

Features
The document service is an implementation of the CMIS standard and is the primary interface to a reliable and
safe store for content on SAP HANA Cloud Platform.
Features of the document service include:
The storage and retrieval of files, which the file system often handles on traditional platforms
The organization of files in a hierarchical folder structure
The association of metadata with the content and the ability to read and write metadata
A query interface based on this metadata using a query language similar to SQL
Managing access control (access control lists)
Versioning of content
A powerful Java API (Apache Chemistry OpenCMIS)
Streaming support to also handle large files efficiently
Files are always encrypted (AES-128) before they are stored in the document service.
A virus scanner can be activated to scan files for viruses during file uploads (write accesses). For performance
reasons, read-only file accesses are not scanned
Access from applications running internally on SAP HANA Cloud Platform or externally
The following figure illustrates the document service's architecture:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

545

The CMIS standard defines:


A domain model and service bindings that can be used by applications to work with a content management
repository
An abstraction layer for controlling diverse document management systems and repositories using Web
protocols
CMIS provides a common data model covering typed files and folders with generic properties that can be set or
read. There is a set of services for adding and retrieving documents (called objects). CMIS defines an access
control system, a checkout and version control facility, and the ability to define generic relations. CMIS defines the
following protocol bindings, which use WSDL with Simple Object Access Protocol (SOAP) or Representational
State Transfer (REST):
The Atom Publishing (AtomPub) Protocol
The JavaScript Object Notation (JSON) format
The consumption of CMIS-enabled document repositories is easy using the Apache Chemistry libraries. Apache
Chemistry provides libraries for several platforms to consume CMIS using Java, PHP, .Net, or Python. The
subproject OpenCMIS, which includes the CMIS Java implementation, also includes tools around CMIS, like the
CMIS Workbench, which is a desktop client for CMIS repositories for developers.

546

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Since the SAP HANA Cloud Platform, document service API includes the OpenCMIS Java library, applications can
be built on SAP HANA Cloud Platform that are independent of a specific content repository.

Restrictions
The SOAP (Web services) binding is not supported.
The following features, which are defined in the OASIS CMIS standard, are supported with restrictions:
Versioning: Only major versions are supported
Versioning: No support for check-in comments
Query: Only metadata searches, no joins and no type aliases
The following CMIS features are not yet supported:
Multifiling
Policies
Relationships
Change logs
There is a limit for the properties of a document:
For searchable properties, a maximum of 100 values with a maximum of 5,000 characters is allowed.
For non-searchable properties, a maximum of 1,000 values with a maximum of 50,000 characters is allowed.

Related Information
Consuming the Document Service
Consuming the Document Service (Java) [page 548]
Consuming the Document Service (HTML5 Applications) [page 591]
Managing the Document Service
Managing Repositories in the Cockpit [page 592]
Managing a Repository with Console Client Commands [page 595]
General Information on CMIS
OASIS Page on CMIS
Apache Chemistry Page
OASIS Page with link to CMIS-v1.1pdf

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

547

1.4.2.1

Consuming the Document Service (Java)

Use the SAP HANA Cloud Platform, document service to store unstructured or semi-structured data in the
context of your SAP HANA Cloud Platform application.

Introduction
Many applications need to store and retrieve unstructured content. Traditionally, a file system is used for this
purpose. In a cloud environment, however, the usage of file systems is restricted. File systems are tied to
individual virtual machines, but a Web application often runs distributed across several instances in a cluster. File
systems also have limited capacity.
The document service offers persistent storage for content and provides additional functionality. It also provides a
standardized interface for content using the OASIS CMIS standard.

Related Information
Basic Concepts (Java) [page 548]
Handling CMIS Metadata [page 564]
Creating a Sample Application (Java) [page 555]

1.4.2.1.1

Basic Concepts (Java)

The following sections describe the basic concepts of the SAP HANA Cloud Platform, document service.
Client API (Java) [page 548]
Documents and Folders (Java) [page 551]
Deployment Options [page 552]
Data Isolation (Java) [page 553]
In the coding and the coding samples, ecm is used to refer to the document service. Therefore, for example, the
document service API is called ecm.api.

1.4.2.1.1.1 Client API (Java)


The SAP HANA Cloud Platform, document service is exposed using the OASIS standard protocol Content
Management Interoperability Service (CMIS).
The CMIS standard defines the protocol level (SOAP, AtomPub, and JSON based protocols). The SAP HANA
Cloud Platform provides a document service client API on top of this protocol for easier consumption. This API is
the Open Source library OpenCMIS provided by the Apache Chemistry Project.

548

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Apache Chemistry Project
ecm.api

1.4.2.1.1.2 Repositories (Java)


To manage documents in the SAP HANA Cloud Platform, document service, you need to connect an application to
a repository of the document service.
A repository is the document store for your application. It has a unique name with which it can later be accessed,
and it is secured using a key provided by the application. Only applications that provide this key are allowed to
connect to this repository.
You can manage repositories in several ways:
In the cockpit, see Managing Repositories in the Cockpit [page 592].
Programmatically using the createRepository(repositoryOptions) method of the EcmService, see
Managing a Repository Programmatically (Java) [page 549].
Using console client commands, see Managing a Repository with Console Client Commands [page 595].

Note
As a repository has a certain storage footprint in the back end, the total amount of repositories for each
account is limited to 100. When you create repositories, for example, for testing, make sure that these
repositories are deleted after a test is finished to avoid reaching the limit. Should your use case require more
than 100 repositories per account, please create a support ticket.

Note
Due to the tenant isolation in SAP HANA Cloud Platform, the document service cockpit cannot access or view
repostories you create in SAP Document Center or vice versa.

1.4.2.1.1.2.1 Managing a Repository Programmatically (Java)


You can manage a repository using the application's program. In this way, you can create, edit, delete, and
connect the repository.

Related Information
Creating a Repository Programmatically (Java) [page 550]
Connecting to a Repository (Java) [page 550]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

549

1.4.2.1.1.2.1.1 Creating a Repository Programmatically (Java)


You can create a repository with the createRepository(repositoryOptions) method of the EcmService
(document service).

Procedure
Use the createRepository(repositoryOptions) method and define the properties of the repository.
The following code snippet shows how to create a repository where uploaded files are scanned for viruses:
RepositoryOptions options = new RepositoryOptions();
options.setUniqueName("myrepository");
options.setRepositoryKey("1234567890");
options.setVirusScannerEnabled(true);
EcmService.createRepository(options);

Related Information
Alternative Ways to Create Repositories
create-ecm-repository [page 118]
Creating a Repository (Cockpit) [page 592]
Connecting Your Repository to an Application
Creating a Sample Application (Java) [page 555]

1.4.2.1.1.2.1.2 Connecting to a Repository (Java)


Your application must be connected to the repository you created.

Context
There are many ways to connect to a repository. For more information, see the API Documentation [page 1060]
and Reuse OpenCmis Session Objects in Performance Tips (Java) [page 587].

Procedure
To connect to an existing repository, use the connect(uniqueName, key) method.

550

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Once you are connected to the repository, you get an OpenCMIS session object to manage documents and
folders in the connected repository.

1.4.2.1.1.3 Documents and Folders (Java)


Probably the most common use case is to create documents and folders in a repository. Every repository in CMIS
has a root folder. Once you have received a Session, you can create the root folder using the following syntax:
// get the root folder of the repository
Folder root = openCmisSession.getRootFolder();
Once you have a root folder, you can create other folders or documents. In the CMIS domain model, all CMIS
objects are typed. Therefore, you have to provide type information for each object you create. The types carry the
metadata for an object. The metadata is passed in a property map. Some properties are mandatory, others are
optional. You have to provide at least an object type and a name. For properties defined in the standard,
OpenCMIS has predefined constants in the PropertyIds class.
To create a document in the root folder, enter the following syntax:
Map<String, String> newFolderProps = new HashMap<String, String>();
newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
newFolderProps.put(PropertyIds.NAME, "MyFirstFolder");
root.createFolder(newFolderProps);
To create a document with content, provide a map of properties. In addition, create a ContentStream object
carrying a Java InputStream plus some additional information for the content, like Content-Type and file
name.
Map<String, String> properties = new HashMap<String, String>();
properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
properties.put(PropertyIds.NAME, "HelloWorld.txt");
byte[] helloContent = "Hello World!".getBytes( "UTF-8");
InputStream stream = new ByteArrayInputStream(helloContent);
ObjectFactory factory = openCmisSession.getObjectFactory();
ContentStream contentStream = factory.createContentStream("HelloWorld.txt",
helloContent. length, "text/plain; charset=UTF-8", stream);
To create the document, enter the following syntax:
Document myDocument = root.createDocument(properties, contentStream,
VersioningState.NONE);
Get the ID for later retrieval of the document:
String id = myDocument.getId();

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

551

Getting Children
To get the children of a folder, you can use the following code:
Folder root = openCmisSession.getRootFolder();
ItemIterable<CmisObject> children = root.getChildren();
for (CmisObject o : children) {
System.out.print("Name: " + o.getName());
if (o instanceof Folder) {
System.out.println(", type: Folder, createdBy: " + o.getCreatedBy());
}
else {
Document doc = (Document) o;
System.out.println.println(", type: Document, createdBy: " +
o.getCreatedBy() +
" filesize: "+ doc.getContentStreamLength() + " bytes");
}
}

Retrieving a Document
To retrieve a document, you can use the following code:
Document document = (Document) openCmisSession.getObject(id);
Property<String> p = document.getProperty(PropertyIds.NAME);
System.out.println("Name: " + p.getValue());
// or use System.out.println("Name: " + document.getName());
To get the content, use the following code:
InputStream stream = document.getContentStream().getStream();
You can also retrieve a document using its path with the getObjectByPath() method.

Tip
We recommend that you retrieve objects by ID and not by path. IDs are kept stable even if the object is moved.
Retrieving objects by IDs is also faster than retrieving objects by paths.

1.4.2.1.1.4 Deployment Options


Before your application can use the document service, the application must be able to access and consume the
service.
There are several ways in which your application can access the document service:
Any application deployed on SAP HANA Cloud Platform as a Java Web application can consume the
document service.
During the development phase, you can also use the document service in the SAP HANA Cloud Platform local
runtime.

552

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

As a prerequisite for local development, you need an installation of the MongoDB on your machine. See
Creating a Sample Application (Java) [page 555].
You can also use the document service from an application running outside SAP HANA Cloud Platform.
This requires a special application running on SAP HANA Cloud Platform acting as a bridge between the
external application and the document service. This application is called a "proxy bridge". For more
information, see Building a Proxy Bridge [page 560].

Related Information
http://chemistry.apache.org/

1.4.2.1.1.5 Data Isolation (Java)

User Management
The service treats user names as opaque strings that are defined by the application. All actions in the document
service are executed in the context of this named user or the currently logged-on user. That is, the service sets the
cmis:createdBy and cmis:lastModifiedBy properties to the provided user name. The service also uses this
user name to evaluate access control lists (ACLs). For more information, see the CMIS specification. The
document service is not connected to a user management system and, therefore, does not perform any user
authentication.

Repository Naming and Data Isolation


Repositories are identified either by their unique name or by their ID. The unique name is a human-readable name
that should be constructed with Java package-name semantics, for example, com.foo.MySpecialRepository,
to avoid naming conflicts. Repositories in the document service are secured by a key provided by the application.
When a repository is created, a key must be supplied. Any further attempts to connect to this repository only
succeed if the key provided by the connecting application matches the key that was used to create the repository.
Therefore, this key must be stored in a secure manner, for example, using the Java KeyStore. It is, however, up to
the application to decide whether to share this key with other applications from the same account to implement
data-sharing scenarios.
Multiple applications can access the same repository. However, applications can only connect to the same
repository using the unique name assigned to this repository if they are deployed within the same account as the
application that created the repository. In contrast, applications that are deployed in a different account cannot
access this repository. A consequence of having repositories isolated within an account is that data cannot be
shared across different accounts.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

553

Example of Account Isolation


Repository ABC is created when Application1 is deployed in Account1. Application2 is located in the same Account1
as Application1; therefore, Application2 can also access the same repository using its unique name ABC.
Application3 is deployed in Account2. Application3 calls a repository that has the same unique name ABC as the
other repository that belongs to Account1. However, Application3 cannot access the ABC repository that belongs
to Account1 using the identical unique name, because the repositories are isolated within the account. Therefore,
Application3 in Account2 connects to another ABC repository that belongs to Account2. In summary, a repository
can only be accessed by applications that are deployed in the same account as the application that created the
repository.

Multitenancy
The document service supports multitenancy and isolates data between tenants. Each application consuming the
document service creates a repository and provides a unique name and a secret key. The document service
creates the repository internally in the context of the tenant using the application. While the repository name
uniquely identifies the repository, an internal ID is created for the application for each tenant. This ID identifies the
storage area containing all the data for the tenant in this repository. An application that uses the document
service in this way has multitenancy support. No additional logic is required at the application level.

Tip
One document service session is always bound to one tenant and to one user. If you create the session only
once, then store it statically, and finally reuse it for all subsequent requests, you end up in the tenant where you
first created the document service session. That is: You do not use multitenancy.
We recommend that you create one document service session per tenant and cache these sessions for future
reuse. Make sure that you do not mix up the tenants on your side.
If you expect a high load for a specific tenant, we recommend that you create a pool of sessions for that tenant.
A session is always bound to a particular server of the document service and this will not scale. If you use a
session pool, the different sessions are bound to different document service servers and you will get a much
better performance and scaling.

Related Information
Content Management Interoperability Services (CMIS) Version 1.1
Multitenant Applications [page 990]

554

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2.1.2

Creating a Sample Application (Java)

Prerequisites
You have downloaded and configured the SAP Eclipse platform. For more information, see Installing Java
Tools for Eclipse and SDK [page 33].
You have created a HelloWorld Web application as described in Creating a HelloWorld Application [page 47].
You have downloaded the SDK used for local development.
You have installed MongoDB as described in Local Development Setup [page 559].

Context
This tutorial describes how you extend the HelloWorld Web application so that it uses the SAP HANA Cloud
Platform, document service for managing unstructured content in your application. You test and run the Web
application on your local server and the SAP HANA Cloud Platform.

Note
For historic reasons, ecm is used to refer to the document service in the coding and the coding samples.

Procedure
1. Connect the HelloWorld Web application to the document service.
The document service client library is used to connect to the document service. The library connects to the
local or central document service and returns an authenticated OpenCMIS session. If you are running your
application locally in the Eclipse IDE, the document service client library connects to a local document service
of the SAP HANA Cloud Platform SDK that is connected to your local MongoDB. If your application is
deployed on SAP HANA Cloud Platform, the document service client library connects to the document service
that belongs to the corresponding system landscape.
2. If your application needs authenticated users and these users should be automatically propagated to the
document service, configure your Web application to enable user authentication.
a. Expand the HelloWorld/WebContent/WEB-INF node.
b. Select the web.xml file and choose Open from the context menu.
c. Enable authentication for your application.
For more information about authentication, see Enabling Authentication.
3. Connect to the document service and create a folder and a document.
a. Expand the HelloWorld/Java Resources/src/hello node.
b. Select the HelloWorldServlet.java file and, choose Open from the context menu.
c. Add the following code to the HelloWorldServlet.java.
package hello;
import java.io.ByteArrayInputStream;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

555

import java.io.IOException;
import java.io.InputStream;
import java.util.HashMap;
import java.util.Map;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.chemistry.opencmis.client.api.CmisObject;
import org.apache.chemistry.opencmis.client.api.Document;
import org.apache.chemistry.opencmis.client.api.Folder;
import org.apache.chemistry.opencmis.client.api.ItemIterable;
import org.apache.chemistry.opencmis.client.api.Session;
import org.apache.chemistry.opencmis.commons.PropertyIds;
import org.apache.chemistry.opencmis.commons.data.ContentStream;
import org.apache.chemistry.opencmis.commons.enums.VersioningState;
import
org.apache.chemistry.opencmis.commons.exceptions.CmisNameConstraintViolationEx
ception;
import
org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
import com.sap.ecm.api.RepositoryOptions;
import com.sap.ecm.api.RepositoryOptions.Visibility;
import com.sap.ecm.api.EcmService;
import javax.naming.InitialContext;
/**
* Servlet implementation class HelloWorldServlet
*/
public class HelloWorldServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* @see HttpServlet#HttpServlet()
*/
public HelloWorldServlet() {
super();
}
/**
* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
*
response)
*/
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException,
IOException {
response.getWriter().println("<html><body>");
try {
// Use a unique name with package semantics e.g. com.foo.MyRepository
String uniqueName = "com.foo.MyRepository";
// Use a secret key only known to your application (min. 10 chars)
String secretKey = "my_super_secret_key_123";
Session openCmisSession = null;
InitialContext ctx = new InitialContext();
String lookupName = "java:comp/env/" + "EcmService";
EcmService ecmSvc = (EcmService) ctx.lookup(lookupName);
try {
// connect to my repository
openCmisSession = ecmSvc.connect(uniqueName, secretKey);
}
catch (CmisObjectNotFoundException e) {
// repository does not exist, so try to create it
RepositoryOptions options = new RepositoryOptions();
options.setUniqueName(uniqueName);
options.setRepositoryKey(secretKey);
options.setVisibility(Visibility.PROTECTED);
ecmSvc.createRepository(options);
// should be created now, so connect to it
openCmisSession = ecmSvc.connect(uniqueName, secretKey);
}
response.getWriter().println(

556

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"<h3>You are now connected to the Repository with Id "


+ openCmisSession.getRepositoryInfo().getId()
+ "</h3>");
// access the root folder of the repository
Folder root = openCmisSession.getRootFolder();
// create a new folder
Map<String, String> newFolderProps = new HashMap<String, String>();
newFolderProps.put(PropertyIds.OBJECT_TYPE_ID, "cmis:folder");
newFolderProps.put(PropertyIds.NAME, "SapHANANeo");
try {
root.createFolder(newFolderProps);
} catch (CmisNameConstraintViolationException e) {
// Folder exists already, nothing to do
}
// create a new file in the root folder
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
properties.put(PropertyIds.NAME, "HelloWorld.txt");
byte[] helloContent = "Hello World!".getBytes("UTF-8");
InputStream stream = new ByteArrayInputStream(helloContent);
ContentStream contentStream = openCmisSession.getObjectFactory()
.createContentStream("HelloWorld.txt",
helloContent.length, "text/plain;
charset=UTF-8", stream);
try {
root.createDocument(properties, contentStream, VersioningState.NONE);
} catch (CmisNameConstraintViolationException e) {
// Document exists already, nothing to do
}
// Display the root folder's children objects
ItemIterable<CmisObject> children = root.getChildren();
response.getWriter().println("The root folder of the repository with id
" + root.getId()
+ " contains the following objects:<ul>");
for (CmisObject o : children) {
response.getWriter().print("<li>" + o.getName());
if (o instanceof Folder) {
response.getWriter().println(" createdBy: " + o.getCreatedBy() + "</
li>");
} else {
Document doc = (Document) o;
response.getWriter().println(" createdBy: " + o.getCreatedBy() + "
filesize: "
+ doc.getContentStreamLength() + " bytes"
+ "</li>");
}
}
response.getWriter().println("</ul>");
} catch (Exception e) {
throw new ServletException(e);
} finally {
response.getWriter().println("</body></html>");
}
}
/**
* @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse
*
response)
*/
protected void doPost(HttpServletRequest request,
HttpServletResponse response) throws
ServletException, IOException {
// TODO Auto-generated method stub
}
}
For more information about using the OpenCMIS API, see the Apache Chemistry documentation.
During execution, this servlet executes the following steps:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

557

1. It connects to a repository. If the repository does not yet exist, the servlet creates the repository.
2. It creates a subfolder.
3. It creates a document.
4. It displays the children of the root folder.
4. Add the resource reference description to the web.xml file.

Note
The document service is consumed by defining a resource in your web.xml file and by using JNDI lookup to
retrieve an instance of the com.sap.ecm.api.EcmService class. For more information, see Example
Application. Once you have established a connection to the document service, you can use one of the
connect() methods to get a CMIS session
(org.apache.chemistry.opencmis.client.api.Session). A few examples of how to use the
OpenCMIS Client API from the Apache Chemistry project are described below. For more information, see
the Apache Chemistry page.
a. In the Project Explorer view, expand the HelloWorld/WebContent/WEB-INF node.
b. Select the web.xml file and choose

Open With

Text Editor

from the context menu.

c. Insert the following content after the <servlet-mapping> elements.


<resource-ref>
<res-ref-name>EcmService</res-ref-name>
<res-type>com.sap.ecm.api.EcmService</res-type>
</resource-ref>
5. Test the Web application locally or in the SAP HANA Cloud Platform. For testing, proceed as described in
Deploying Locally from Eclipse IDE or Deploying on the Cloud From Eclipse IDE linked below.

Related Information
Enabling Authentication [page 1213]
http://chemistry.apache.org/java/opencmis.html
http://chemistry.apache.org/
http://chemistry.apache.org/java/developing/guide.html
http://chemistry.apache.org/java/0.13.0/maven/apidocs/
http://chemistry.apache.org/java/examples/index.html
Deploying Locally from Eclipse IDE [page 975]
Deploying on the Cloud from Eclipse IDE [page 977]

558

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2.1.3

Local Development Setup

To use the document service in a Web application, download the SDK and install the MongoDB database.

Context
To install the MongoDB database, execute the following steps:

Procedure
1. Download the MongoDB database from http://www.mongodb.org/downloads

2. Unpack the file to a local directory (for example, c:\mongodb).


3. Create an empty directory (for example, c:\mongodb_data).
4. To start the MongoDB server, execute the following steps:
a. Open a command prompt.
b. Switch to the MongoDB bin directory (for example, c:\mongodb\bin).
c. Enter the following command: mongod --dbpath C:\mongodb_data
5. In your Web browser, navigate to http://localhost:27017.
If your setup is correct, you see a text message starting with "You are trying to access MongoDB on
the native driver port. "

Related Information
Creating a Sample Application (Java) [page 555]

1.4.2.1.4

Access from External Applications

Overview
The services on SAP HANA Cloud Platform can be consumed by applications that are deployed on SAP HANA
Cloud Platform but not from external applications. There are cases, however, where applications want to access
content in the cloud but cannot be deployed in the cloud.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

559

The figure below describes a mechanism with which this scenario can be supported and is followed by an
explanation:

This can be addressed by deploying an application on SAP HANA Cloud Platform that accepts incoming requests
from the Internet and forwards them to the document service. We refer to this type of application as a proxy
bridge. The proxy bridge is deployed on SAP HANA Cloud Platform and runs in an account using the common SAP
HANA Cloud Platform patterns. The proxy bridge is responsible for user authentication. The resources consumed
in the document service are billed to the SAP HANA Cloud Platform account that deployed this application.

Related Information
Building a Proxy Bridge [page 560]

1.4.2.1.4.1 Building a Proxy Bridge

Context
All the standard mechanisms of the document service apply. The SAP HANA Cloud Platform SDK provides a base
class (a Java servlet) that provides the proxy functionality out-of-the-box. This can easily be extended to
customize its behavior. The proxy bridge performs a 1:1 mapping from source CMIS calls to target CMIS calls.
CMIS bindings can be enabled or disabled. Further modifications of the incoming requests, such as allowing only
certain operations or modifying parameters, are not supported. The Apache OpenCMIS project contains a bridge
module that supports advanced scenarios of this type.

560

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The proxy bridge allows you to use standard CMIS clients to connect to the document service of SAP HANA Cloud
Platform. An example is the Apache Chemistry Workbench, which can be useful for development and testing.

Caution
Note that the proxy bridge opens your repository to the public Internet and should always be secured
appropriately.

Note
For historic reasons, ecm is used to refer to the document service in the coding and the coding samples.

Procedure
1. Create an SAP HANA Cloud Platform application as described in Using Java EE 6 Web Profile, which is linked
below.
2. Create a web.xml file and a servlet class.
3. Derive your servlet from the class com.sap.ecm.api.AbstractCmisProxyServlet.
4. Add a servlet mapping to your web.xml file using a URL pattern that contains a wildcard. See the following
example.

Example
<servlet>
<servlet-name>cmisproxy</servlet-name>
<servlet-class>my.app.CMISProxyServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>cmisproxy</servlet-name>
<url-pattern>/cmis/*</url-pattern>
</servlet-mapping>
You can use prefixes other than /cmis and you can add more servlets in accordance with your needs. The
URL pattern for your servlet derived from the class AbstractCmisProxyServlet must contain a /* suffix.
5. Override the two abstract methods provided by the AbstractCmisProxyServlet class:
getRepositoryUniqueName() and getRepositoryKey().
These methods return a string containing the unique name and the secret key of the repository to be
accessed. You can override a third method getDestinationName(), which also returns a string. If this
method is overridden, it should return the name of a destination deployed for this application to connect to
the service. This is useful if a service user is used, for example. Ensure that you have then deployed this
destination on the virtual machine.
6. Optionally, you can override the getServletConfig() method. To do so, call the superclass.
Do not override the following methods:
service()
doGet()

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

561

doPost()
and so on
7. Optionally, you can restrict the proxy bridge to restrict the exposed bindings by overriding one or more of the
following methods:
supportAtomPubBinding()
supportBrowserBinding()
At least one of the methods must return true.
8. Add the following code snippet to your web.xml and assign the role EcmDeveloper to the users in your
account who require external access to the repository.
<security-constraint>
<web-resource-collection>
<web-resource-name>Proxy</web-resource-name>
<url-pattern>/cmis/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>EcmDeveloper</role-name>
</auth-constraint>
</security-constraint>
In some cases it might be useful to grant public access for reading content but not for modifying, creating or
deleting it. For example, a Web content management application might embed pictures into a public Web site
but store them in the document service. For a scenario of this type, override the method readOnlyMode() so
that it returns true. This means that only read requests are forwarded to the repository and all other requests
are rejected. The read-only mode only works with the JSON binding. The other bindings are disabled in this
case.

Note
If you need finer control or dynamic permissions you can override the requireAuthentication() and
authenticate() methods in the AbstractCmisProxyServlet.
9. Optionally, you can override two more methods to customize timeout values for reading and connecting:
getConnectTimeout() and getReadTimeout().
It should only be necessary to use these methods if frequent timeout errors occur.
The following code is an example of a proxy servlet.
package my.app;
import com.sap.ecm.api.AbstractCmisProxyServlet;
public class CMISProxyServlet extends AbstractCmisProxyServlet {
@Override
protected String getRepositoryUniqueName() {
return "MySampleRepository";
}
@Override
//For productive applications, use a secure location to store the secret key.
protected String getRepositoryKey() {
return "abcdef0123456789";
}
}
10. To access the proxy brigde from an external application you need the correct URL.

562

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The URL is composed of the following elements:


The URL of your deployed application (displayed in the cockpit)
The name of your Web application
The path configured in web.xml in the servlet mapping of the proxy bridge (in the example below: /cmis)
An extension for the CMIS binding type (/atom for AtomPub or /json for browser binding)

Example
Your proxy bridge application is deployed as cmisproxy.war on the landscape. The cockpit shows the
following URL for your app: https://cmisproxysap.hana.ondemand.com/cmisproxy and the
web.xml is as shown above. Then the URLs is as follows:
CMIS 1.1:
AtomPub: https://cmisproxysap.hana.ondemand.com/cmisproxy/cmis/1.1/atom
Browser: https://cmisproxysap.hana.ondemand.com/cmisproxy/cmis/json
CMIS 1.0:
AtomPub: https://cmisproxysap.hana.ondemand.com/cmisproxy/cmis/atom
Browser: (not available)
These URLs can be passed to the CMIS Workbench from Apache Chemistry, for example.
The workbench requires basic authentication. Please add the following code to your web.xml:

Sample Code
<login-config>
<auth-method>BASIC</auth-method>
</login-config>

Related Information
Using Java EE 6 Web Profile [page 966]

1.4.2.1.5

Advanced Concepts

The following sections describe the advanced concepts of the SAP HANA Cloud Platform, document service.
Handling CMIS Metadata [page 564]
ACLs in the Document Service [page 581]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

563

1.4.2.1.5.1 Handling CMIS Metadata


One benefit of Content Management Interoperability Services (CMIS) as compared to a file system is the
extended handling of metadata.
You can use metadata to structure content and make it easier to find documents in a repository, even if it contains
millions of documents. In the CMIS domain model, metadata is structured using types. A type contains the set of
allowed or required properties, for example, an Invoice type that has the InvoiceNo and CustomerNo
properties.

The CMIS Type System


A type is described in a type definition and contains a list of property definitions. CMIS has a set of predefined
types and predefined properties. Custom-specific types and additional custom properties can extend the
predefined types. When a type is created, it is derived from a parent type and extends the set of the parent
properties. In this way, a hierarchy of types is built. The base types do not have parents. Base types are defined in
the CMIS specification. The most important base types are cmis:document and cmis:folder.
Predefined properties contain metadata that is usually available in the existing repositories. These are, for
example, cmis:name, cmis:createdBy, cmis:modifiedBy, cmis:createdAt, and cmis:modifiedAt. They
contain the name of the author, the creation date, and the date of the last modification. Some properties are typespecific, for example, a folder has a parent folder and a document has a property for content length.
Each property has a data format (String, Integer, Date, Decimal, ID, and so on) and can define additional
constraints, such as:
Required (must have a value)
Read-only (cannot be updated)
Value range (minimum value, maximum value)
Value list (value must be one of a fixed list of values)
A property is either single-valued or multi-valued.
Each object stored in a CMIS repository has a type and a set of properties. Types and properties provide the
mechanism used to find objects with CMIS queries.

Related Information
http://chemistry.apache.org/
http://chemistry.apache.org/java/developing/guide.html
http://chemistry.apache.org/java/0.9.0/maven/apidocs/
http://chemistry.apache.org/java/examples/index.html
http://docs.oasis-open.org/cmis/CMIS/v1.1
http://docs.oracle.com/javase/6/docs/api/java/security/KeyStore.html

564

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2.1.5.1.1 Metadata in the Document Service


The document store on SAP HANA Cloud Platform supports the cmis:document and cmis:folder types. It also
has a built-in subtype for versioned documents. The types can be investigated using the Apache CMIS workbench.
In addition to the standard CMIS properties, the document service of SAP HANA Cloud Platform supports
additional SAP properties. The most important ones are:
sap:owner (the owner of a document)
sap:owner is used for ACLs (access control).
sap:tags
sap:tags is a multi-valued attribute used for tagging the content.

Related Information
http://chemistry.apache.org/java/download.html
http://docs.oasis-open.org/cmis/CMIS/v1.1

1.4.2.1.5.1.2 Creating Metadata


You can pass metadata when documents are created.

Context
The CMIS client API uses a map to pass properties. The key of the map is the property ID and the value is the
actual value to be passed. The cmis:name and cmis:objectTypeId properties are mandatory.

Procedure
1. Use a name that is unique within the folder and a type ID that is a valid type from the repository.
2. Run the sample code.
// properties
Map<String, Object> properties = new HashMap<String, Object>();
properties.put(PropertyIds.OBJECT_TYPE_ID, "cmis:document");
properties.put(PropertyIds.NAME, "Document-1");
// content
byte[] content = "Hello World!".getBytes();
InputStream stream = new ByteArrayInputStream(content);
ContentStream contentStream = new ContentStreamImpl(name,
BigInteger.valueOf(content.length), "text/plain", stream);
// create a document

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

565

Folder root = session.getRootFolder();


Document newDoc = folder.createDocument(properties, contentStream,
VersioningState.NONE

Results
You can inspect the document in the CMIS workbench. You can see that various other properties have been set by
the system, such as the ID, the creation date, and the creating user.

1.4.2.1.5.1.3 Updating Properties

Context
This procedure focuses on the use of the sap:tags property to mark the document. This is a multi-value
attribute, so you can assign more than one tag to it.

Procedure
1. To assign the Hello and Tutorial tags to the document, use the following code:
List<String> tags = Arrays.asList("Hello", "Tutorial");
Map<String, Object> properties = new HashMap<String, Object>();
properties.put("sap:tags", tags);
doc.updateProperties(properties);
2. To display the property, refresh the document in the CMIS workbench.
The following property is displayed:
Table 242:

566

Name

ID

Type

Value

sap:tags

sap:tags

string

Hello Tutorial

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2.1.5.1.4 Querying Properties


This section gives a very brief introduction to querying. The OpenCMIS Client API is a Java client-side library with
many capabilities, for example, paging results. For more information, consult the OpenCMIS Javadoc and the
examples on the Apache Chemistry Web site.

Context
The following procedure focuses on a use case where you have created a second folder and some more
documents. The repository then looks like this:

The Hello Document and Hi Document documents have the tags Hello and Tutorial, the Loren Ipsum
document has no tags.

Procedure
1. Use the CMIS query to search documents in the system based on their properties.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

567

Note
The CMIS query language CMISSQL is similar to SQL.

SELECT cmis:name, cmis:objectId, cmis:createdBy, sap:owner FROM cmis:document


WHERE cmis:createdBy='john'
This query returns the following result set:
Table 243:
cmis:createdBy

cmis:name

sap:owner

cmis:objectId

john

Lorem Ipsum Document

john

<ID>

john

Hi Document

john

<ID>

john

Hello Document

john

<ID>

2. Query all documents with the tag Hello.


SELECT cmis:name, cmis:objectId, cmis:createdBy, sap:tags, sap:owner FROM
cmis:document WHERE ANY sap:tags IN ('Hello')

Note
In this case, the workbench displays only the first value of multi-valued properties.
Table 244:
cmis:createdBy

cmis:name

sap:owner

sap:tags

cmis:objectId

john

Hello Document

john

Hello

<ID>

Tutorial
john

Hi Document

john

Hello

<ID>

Tutorial

3. Execute the query with the following code:


String query = "SELECT cmis:name, cmis:objectId, cmis:createdBy, " +
"sap:tags, sap:owner FROM cmis:document WHERE ANY sap:tags " +
"IN ('Hello')";
ItemIterable<QueryResult> results = session.query(query, false););
System.out.println("Name | Object-Id | Author | Tags");
System.out.println("---------------------------------");
for (QueryResult result : results) {
String name = result.getPropertyValueByQueryName("cmis:name");
String id =result.getPropertyValueByQueryName("cmis:objectId");
String author =
result.getPropertyValueByQueryName("cmis:objectId");
List<String> tags =
result.getPropertyMultivalueByQueryName("sap:tags");
System.out.println(name + " | " + id + " | " + author + " | "
+ tags);
}

568

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

This query produces the following output:


Name | Object-Id | Author | Tags --------------------------------- Hello-Document |
7L8S0XYG9dh7O1gGgkiA9gWl3gSIzYkYpYds6vnxA-M | john | [Hello, Tutorial] Hi-Document
| 3ovtYi1sqWyUmXW3-zGg30OT-e2U12qiD_o-kf595YA | john | [Hello, Tutorial]

Related Information
http://chemistry.apache.org/java/0.13.0/maven/apidocs/
http://chemistry.apache.org/java/examples/index.html

1.4.2.1.5.1.5 Type Mutability


For the SAP HANA Cloud Platform, document service, you can create new object types or you can remove those
new object types again in accordance with the CMIS standard.

Context
In CMIS, every object, for example a document or a folder, has an object type. The object type defines the basic
settings of an object of that type. For example, the cmis:document object type defines that objects of that type
are searchable.
Furthermore, the object type defines the properties that can be set for an object of that type, for example, an
object of type cmis:document has a mandatory cmis:name property that must be a string. Therefore, every
object of type cmis:document needs a name. Otherwise, the object is not valid and the repository rejects it.
In CMIS, types are organized hierarchically. The most important (predefined) base types are:
cmis:document for all file-like objects
cmis:folder for folder-like objects
cmis:secondary for secondary types
CMIS allows you to define additional types provided that each type is a descendant of one of the predefined base
types. In this type hierarchy, a type inherits all property definitions of its parent type. CMIS 1.1 allows type
hierarchy modifications (see the OASIS page) by providing methods for the creation, the modification, and the
removal of object types. Currently, the document service only supports the creation and removal of types. This
allows a developer to define new types as subtypes of existing types. The new types might possess other
properties in addition to all of the automatically inherited property definitions of the parent type. Creating objects
of that type allows you to assign values for these new properties to the object. Remember to also set the values
for the inherited properties as appropriate.
The following example shows how to create a new document type that possesses one additional property for
storing the summary of a document. The developer must implement the MyDocumentTypeDefinition and
MyStringPropertyDefinition classes. Example implementations for these classes as well as for the

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

569

interfaces (FolderTypeDefinition, SecondaryTypeDefinition, PropertyBooleanDefinition,


PropertyDecimalDefinition, and so on) are described in the following topics.

Example
import java.util.HashMap;
import java.util.Map;
import org.apache.chemistry.opencmis.client.api.ObjectType;
import org.apache.chemistry.opencmis.client.api.Session;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.enums.BaseTypeId;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.ContentStreamAllowed;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
import
org.apache.chemistry.opencmis.commons.exceptions.CmisObjectNotFoundException;
import org.apache.chemistry.opencmis.commons.exceptions.CmisRuntimeException;
// specify type attributes
String idAndQueryName = "test:docWithSummary";
String description = "Doc with Summary";
String displayName = "Document with Summary";
String localName = "some local name";
String localNamespace = "some local name space";
String parentTypeId = BaseTypeId.CMIS_DOCUMENT.value();
Boolean isCreatable = true;
Boolean includedInSupertypeQuery = true;
Boolean queryable = true;
ContentStreamAllowed contentStreamAllowed = ContentStreamAllowed.ALLOWED;
Boolean versionable = false;
// specify property definitions
Map<String, PropertyDefinition<?>> propertyDefinitions
= new HashMap<String, PropertyDefinition<?>>();
MyStringPropertyDefinition summaryPropertyDefinitions
= createSummaryPropertyDefinitions();
propertyDefinitions.put(summaryPropertyDefinitions.getId(),
summaryPropertyDefinitions);
// build object type
MyDocumentTypeDefinition docTypeDefinition
= new MyDocumentTypeDefinition(idAndQueryName, description, displayName,
localName, localNamespace, parentTypeId, isCreatable,
includedInSupertypeQuery, queryable, contentStreamAllowed,
versionable, propertyDefinitions);
// add type to repository
ecmSession.createType(docTypeDefinition);
// create document of new type
ecmSession.clear();
Map<String, String> newDocProps = new HashMap<String, String>();
newDocProps.put(PropertyIds.OBJECT_TYPE_ID, docTypeDefinition.getId());
newDocProps.put(PropertyIds.NAME, "testDocWithNewType");
newDocProps.put("test:summary", "This is a document with a summary property");
Folder root = ecmSession.getRootFolder();
root.createDocument(newDocProps, null, null);
private static MyStringPropertyDefinition createSummaryPropertyDefinitions() {
String idAndQueryName = "test:summary";
Cardinality cardinality = Cardinality.SINGLE;
String description = "this is a summary";
String displayName = "Summary";
String localName = "some local name";
String localNameSpace = "some local name space";
Updatability updatability = Updatability.READWRITE;
Boolean orderable = false;
Boolean queryable = false;
MyStringPropertyDefinition summaryPropDef
= new MyStringPropertyDefinition(idAndQueryName,

570

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

cardinality, description, displayName, localName, localNameSpace,


updatability, orderable, queryable);
return summaryPropDef;

Restrictions for Creating New Object Types


You can only create types with a cmis:document, cmis:folder, or cmis:secondary base type.
The ID and the query name must be identical and meet the following rules:
They must match the regular Java expression "[a-zA-Z][a-zA-Z0-9_:]*".
Their names must not start with cmis:, sap, or s: in any combination of uppercase and lowercase
letters, for example, cMis: is also not allowed.

Restrictions for Property Definitions of New Object Types


The ID and the query name must be identical and meet the following rules:
They must match the regular Java expression "[a-zA-Z][a-zA-Z0-9_:]*".
Their names must not start with cmis:, sap, or s: in any combination of uppercase and lowercase
letters, for example, cMis: is also not allowed.
If the base type of the new object type is cmis:secondary, no other type definition may already contain a
property definition with the same ID or query name.
If the base type of the new object type is not cmis:secondary and another type definition already contains a
property definition with the same ID or query name, this property definition must be identical to the one of the
new type.
You cannot specify default values or choices.

Deleting New Object Types


To delete a new object type, you can use the following code snippet: ecmSession.deleteType(typeId);
You can only delete an object type if it is no longer used by any documents or folders in the repository.

Updating Object Types


Updating an object type is not supported.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

571

Related Information
OASIS page

1.4.2.1.5.1.5.1 Implementation Examples for Type and Property


Definition Classes
Example
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import org.apache.chemistry.opencmis.commons.data.CmisExtensionElement;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.definitions.TypeDefinition;
import org.apache.chemistry.opencmis.commons.definitions.TypeMutability;
import org.apache.chemistry.opencmis.commons.enums.BaseTypeId;
public abstract class MyTypeDefinition implements TypeDefinition {
private String description = null;
private String displayName = null;
private String idAndQueryName = null;
private String localName = null;
private String localNamespace = null;
private String parentTypeId = null;
private Boolean isCreatable = null;
private Boolean includedInSupertypeQuery = null;
private Boolean queryable = null;
private Map<String, PropertyDefinition<?>> propertyDefinitions
= new HashMap<String, PropertyDefinition<?>>();
public MyTypeDefinition(String idAndQueryName, String description,
String displayName, String localName, String localNamespace,
String parentTypeId, Boolean isCreatable,
Boolean includedInSupertypeQuery, Boolean queryable,
Map<String, PropertyDefinition<?>> propertyDefinitions) {
this.description = description;
this.displayName = displayName;
this.idAndQueryName = idAndQueryName;
this.localName = localName;
this.localNamespace = localNamespace;
this.parentTypeId = parentTypeId;
this.isCreatable = isCreatable;
this.includedInSupertypeQuery = includedInSupertypeQuery;
this.queryable = queryable;
if (propertyDefinitions != null) {
this.propertyDefinitions = propertyDefinitions;
}
}
@Override
abstract public BaseTypeId getBaseTypeId();
@Override
public String getDescription() {
return description;
}
@Override
public String getDisplayName() {
return displayName;
}
@Override
public String getId() {

572

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

return idAndQueryName;
}
@Override
public String getLocalName() {
return localName;
}
@Override
public String getLocalNamespace() {
return localNamespace;
}
@Override
public String getParentTypeId() {
return parentTypeId;
}
@Override
public Map<String, PropertyDefinition<?>> getPropertyDefinitions() {
return propertyDefinitions;
}
@Override
public String getQueryName() {
return idAndQueryName;
}
@Override
public Boolean isCreatable() {
return isCreatable;
}
@Override
public Boolean isIncludedInSupertypeQuery() {
return includedInSupertypeQuery;
}
@Override
public Boolean isQueryable() {
return queryable;
}
// methods with static content
@Override
public TypeMutability getTypeMutability() {
return new MyTypeMutability();
}
@Override
public Boolean isControllableAcl() {
return true;
}
@Override
public Boolean isControllablePolicy() {
return false;
}
@Override
public Boolean isFileable() {
return true;
}
@Override
public Boolean isFulltextIndexed() {
return false;
}
@Override
public List<CmisExtensionElement> getExtensions() {
return null;
}
@Override
public void setExtensions(List<CmisExtensionElement> extension) {
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

573

1.4.2.1.5.1.5.1.1 MyTypeMutability Class


import java.util.List;
import org.apache.chemistry.opencmis.commons.data.CmisExtensionElement;
import org.apache.chemistry.opencmis.commons.definitions.TypeMutability;
public class MyTypeMutability implements TypeMutability {
@Override
public List<CmisExtensionElement> getExtensions() {
return null;
}
@Override
public void setExtensions(List<CmisExtensionElement> arg0) {
}
@Override
public Boolean canCreate() {
return true;
}
@Override
public Boolean canDelete() {
return true;
}
@Override
public Boolean canUpdate() {
return false;
}
}

1.4.2.1.5.1.5.1.2 MyDocumentTypeDefinition Class


import java.util.Map;
import org.apache.chemistry.opencmis.commons.definitions.DocumentTypeDefinition;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.enums.BaseTypeId;
import org.apache.chemistry.opencmis.commons.enums.ContentStreamAllowed;
public class MyDocumentTypeDefinition extends MyTypeDefinition implements
DocumentTypeDefinition {
private ContentStreamAllowed contentStreamAllowed = null;
private Boolean versionable = null;
public MyDocumentTypeDefinition(String idAndQueryName, String description,
String displayName, String localName, String localNamespace,
String parentTypeId, Boolean isCreatable,
Boolean includedInSupertypeQuery, Boolean queryable,
ContentStreamAllowed contentStreamAllowed, Boolean versionable,
Map<String, PropertyDefinition<?>> propertyDefinitions) {
super(idAndQueryName, description, displayName, localName, localNamespace,
parentTypeId, isCreatable, includedInSupertypeQuery, queryable,
propertyDefinitions);
this.contentStreamAllowed = contentStreamAllowed;
this.versionable = versionable;
}
@Override
public BaseTypeId getBaseTypeId() {
return BaseTypeId.CMIS_DOCUMENT;
}
@Override
public ContentStreamAllowed getContentStreamAllowed() {
return contentStreamAllowed;
}
@Override

574

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

public Boolean isVersionable() {


return versionable;
}

1.4.2.1.5.1.5.1.3 MyFolderTypeDefinition Class


import java.util.Map;
import org.apache.chemistry.opencmis.commons.definitions.FolderTypeDefinition;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.enums.BaseTypeId;
public class MyFolderTypeDefinition extends MyTypeDefinition implements
FolderTypeDefinition {
public MyFolderTypeDefinition(String idAndQueryName, String description,
String displayName, String localName, String localNamespace,
String parentTypeId, Boolean isCreatable,
Boolean includedInSupertypeQuery, Boolean queryable,
Map<String, PropertyDefinition<?>> propertyDefinitions) {
super(idAndQueryName, description, displayName, localName, localNamespace,
parentTypeId, isCreatable, includedInSupertypeQuery, queryable,
propertyDefinitions);
}
@Override
public BaseTypeId getBaseTypeId() {
return BaseTypeId.CMIS_FOLDER;
}
}

1.4.2.1.5.1.5.1.4 MySecondaryTypeDefinition Class


import java.util.Map;
import org.apache.chemistry.opencmis.commons.definitions.FolderTypeDefinition;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.enums.BaseTypeId;
public class MySecondaryTypeDefinition extends MyTypeDefinition implements
FolderTypeDefinition {
public MySecondaryTypeDefinition(String idAndQueryName, String description,
String displayName, String localName, String localNamespace,
String parentTypeId, Boolean isCreatable,
Boolean includedInSupertypeQuery, Boolean queryable,
Map<String, PropertyDefinition<?>> propertyDefinitions) {
super(idAndQueryName, description, displayName, localName, localNamespace,
parentTypeId, isCreatable, includedInSupertypeQuery, queryable,
propertyDefinitions);
}
@Override
public BaseTypeId getBaseTypeId() {
return BaseTypeId.CMIS_SECONDARY;
}
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

575

1.4.2.1.5.1.5.1.5 MyPropertyDefinition Class


import java.util.List;
import org.apache.chemistry.opencmis.commons.data.CmisExtensionElement;
import org.apache.chemistry.opencmis.commons.definitions.Choice;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
abstract public class MyPropertyDefinition<T> implements PropertyDefinition<T> {
private String idAndQueryName = null;
private Cardinality cardinality = null;
private String description = null;
private String displayName = null;
private String localName = null;
private String localNameSpace = null;
private Updatability updatability = null;
private Boolean orderable = null;
private Boolean queryable = null;
public MyPropertyDefinition(String idAndQueryName, Cardinality cardinality,
String description, String displayName, String localName,
String localNameSpace, Updatability updatability,
Boolean orderable, Boolean queryable) {
super();
this.idAndQueryName = idAndQueryName;
this.cardinality = cardinality;
this.description = description;
this.displayName = displayName;
this.localName = localName;
this.localNameSpace = localNameSpace;
this.updatability = updatability;
this.orderable = orderable;
this.queryable = queryable;
}
@Override
public String getId() {
return idAndQueryName;
}
@Override
public Cardinality getCardinality() {
return cardinality;
}
@Override
public String getDescription() {
return description;
}
@Override
public String getDisplayName() {
return displayName;
}
@Override
public String getLocalName() {
return localName;
}
@Override
public String getLocalNamespace() {
return localNameSpace;
}
@Override
abstract public PropertyType getPropertyType();
@Override
public String getQueryName() {
return idAndQueryName;
}
@Override
public Updatability getUpdatability() {

576

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

return updatability;
}
@Override
public Boolean isOrderable() {
return orderable;
}
@Override
public Boolean isQueryable() {
return queryable;
}
// methods with static content
@Override
public List<Choice<T>> getChoices() {
return null;
}
@Override
public List<T> getDefaultValue() {
return null;
}
@Override
public Boolean isInherited() {
return false;
}
@Override
public Boolean isOpenChoice() {
return true;
}
@Override
public Boolean isRequired() {
return false;
}
@Override
public List<CmisExtensionElement> getExtensions() {
return null;
}
@Override
public void setExtensions(List<CmisExtensionElement> arg0) {
}

1.4.2.1.5.1.5.1.6 MyBooleanPropertyDefinition Class


import org.apache.chemistry.opencmis.commons.definitions.PropertyBooleanDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyBooleanPropertyDefinition extends MyPropertyDefinition<Boolean>
implements PropertyBooleanDefinition {
public MyBooleanPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {

super(idAndQueryName, cardinality, description, displayName,


localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.BOOLEAN;
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

577

1.4.2.1.5.1.5.1.7 MyDateTimePropertyDefinition Class


import java.util.GregorianCalendar;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDateTimeDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.DateTimeResolution;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyDateTimePropertyDefinition extends
MyPropertyDefinition<GregorianCalendar> implements PropertyDateTimeDefinition {
public MyDateTimePropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.DATETIME;
}
@Override
public DateTimeResolution getDateTimeResolution() {
return DateTimeResolution.TIME;
}
}

1.4.2.1.5.1.5.1.8 MyDecimalPropertyDefinition Class


import java.math.BigDecimal;
import org.apache.chemistry.opencmis.commons.definitions.PropertyDecimalDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.DecimalPrecision;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyDecimalPropertyDefinition extends MyPropertyDefinition<BigDecimal>
implements
PropertyDecimalDefinition {
public MyDecimalPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.DECIMAL;
}
@Override
public BigDecimal getMaxValue() {
return null;
}
@Override
public BigDecimal getMinValue() {
return null;
}
@Override
public DecimalPrecision getPrecision() {

578

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

return DecimalPrecision.BITS64;

1.4.2.1.5.1.5.1.9 MyHtmlPropertyDefinition Class


import org.apache.chemistry.opencmis.commons.definitions.PropertyHtmlDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyHtmlPropertyDefinition extends MyPropertyDefinition<String>
implements PropertyHtmlDefinition {
public MyHtmlPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.HTML;
}
}

1.4.2.1.5.1.5.1.10 MyIdPropertyDefinition Class


import org.apache.chemistry.opencmis.commons.definitions.PropertyIdDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyIdPropertyDefinition extends MyPropertyDefinition<String> implements
PropertyIdDefinition {
public MyIdPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.ID;
}
}

1.4.2.1.5.1.5.1.11 MyIntegerPropertyDefinition Class


import java.math.BigInteger;
import org.apache.chemistry.opencmis.commons.definitions.PropertyIntegerDefinition;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

579

import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyIntegerPropertyDefinition extends MyPropertyDefinition<BigInteger>
implements PropertyIntegerDefinition {
public MyIntegerPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.INTEGER;
}
@Override
public BigInteger getMaxValue() {
return null;
}
@Override
public BigInteger getMinValue() {
return null;
}
}

1.4.2.1.5.1.5.1.12 MyStringPropertyDefinition Class


import java.math.BigInteger;
import org.apache.chemistry.opencmis.commons.definitions.PropertyStringDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;
import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyStringPropertyDefinition extends MyPropertyDefinition<String>
implements PropertyStringDefinition {
public MyStringPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.STRING;
}
@Override
public BigInteger getMaxLength() {
return null;
}
}

1.4.2.1.5.1.5.1.13 MyUriPropertyDefinition Class


import org.apache.chemistry.opencmis.commons.definitions.PropertyUriDefinition;
import org.apache.chemistry.opencmis.commons.enums.Cardinality;

580

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

import org.apache.chemistry.opencmis.commons.enums.PropertyType;
import org.apache.chemistry.opencmis.commons.enums.Updatability;
public class MyUriPropertyDefinition extends MyPropertyDefinition<String> implements
PropertyUriDefinition {
public MyUriPropertyDefinition(String idAndQueryName,
Cardinality cardinality, String description, String displayName,
String localName, String localNameSpace,
Updatability updatability, Boolean orderable, Boolean queryable) {
super(idAndQueryName, cardinality, description, displayName,
localName, localNameSpace, updatability, orderable, queryable);
}
@Override
public PropertyType getPropertyType() {
return PropertyType.URI;
}
}

1.4.2.1.5.2 ACLs in the Document Service


The document service supports ACLs (Access Control Lists) consisting of ACEs (Access Control Entries) to
control the access to documents and folders as described in the CMIS standard.
The document service supports the following permissions:
cmis:read
Allows fetching an object (folder or document).
Allows reading the ACL, properties and the content of an object.
sap:file
Includes all privileges of cmis:read.
Allows the creation of objects in a folder and to move an object.
cmis:write
Includes all privileges of sap:file.
Allows modifying the properties and the content of an object.
Allows checking out of a versionable document.
sap:delete
Includes all privileges of cmis:write.
Allows the deletion of an object.
Allows checking in and canceling check out of a private working copy.
cmis:all
Includes all privileges of sap:delete.
Allows modifying the ACL of an object.
For a repository the initial settings for the root folder are:
The ACL contains one ACE for the {sap:builtin}everyone principal with the cmis:all permission. With
these settings, all principals have full control over the root folder.
The owner property is set to {sap:builtin}admin (ownership is described below).
Initially, without specific ACL settings, all documents and folders possess an ACL with one ACE for the built-in
principal {sap:builtin}everyone with the cmis:all permission that grants all users unrestricted access.
ACLs or ACEs are not inherited but explicitly stored at the particular objects. An empty ACL means that no
principal has permission, except the owner of the object. The owner concept is described below in more detail.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

581

Example
The example assumes that every user has full access to the folder. In the following, the access to a folder is
restricted in such a way that User1 has full access and User2 has only read access.
Session session = ..;
Folder folder = ..;
String userIdOfUser1 = ..;
String userIdOfUser2 = ..;
// list of ACEs which should be added
List<Ace> addAcl = new ArrayList<Ace>();
// build and add ACE for user U1
List<String> permissionsUser1 = new ArrayList<String>();
permissionsUser1.add("cmis:all");
Ace aceUser1 = session.getObjectFactory().createAce(userIdOfUser1,
permissionsUser1);
addAcl.add(aceUser1);
// build and add ACE for user U2
List<String> permissionsUser2 = new ArrayList<String>();
permissionsUser2.add("cmis:read");
Ace aceUser2 = session.getObjectFactory().createAce(userIdOfUser2,
permissionsUser1);
addAcl.add(aceUser2);
// list of ACEs which should be removed
List<Ace> removeAcl = new ArrayList<Ace>();
// build and add ACE for user {sap:builtin}everyone
List<String> permissionsEveryone = new ArrayList<String>();
permissionsEveryone.add("cmis:all");
Ace aceEveryone = session.getObjectFactory().createAce(
"{sap:builtin}everyone", permissionsEveryone);
removeAcl.add(aceEveryone);
// add and remove the ACEs at the folder
folder.applyAcl(addAcl, removeAcl, AclPropagation.OBJECTONLY);

1.4.2.1.5.2.1 Detailed Method Description


The following methods for modifying ACLs (Access Control Lists) in the CMIS client library are available:
applyAcl(List<Ace> addAcl, List<Ace> removeAcl, AclPropagation propagation)
First removes the ACEs (Access Control Entries) in removeAcl from the current ACL and adds the ACEs from
addAcl afterward.
setAcl(List<Ace> acl)
Sets the ACL on the specified one.
addAcl( List<Ace> acl, AclPropagation propagation )
Same as applyAcl with addAcl = acl and removeAcl = null
remove(List<Ace> acl, AclPropagation propagation)
Same as applyAcl with addAcl = null and removeAcl = acl
To modify the ACL of the current object only, set the propagation parameter to OBJECTONLY. To modify the
ACL of the current object as well as of the ACLs of all of the object's descendants, set the propagation
parameter to PROPAGATE. You can apply PROPAGATE only to folders. It works as follows: The ACEs that are added
and removed at the root folder of the operation are computed and then applyAcl is called with these ACE sets
for each descendant.

582

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For one principal at most one ACE is stored in an object ACL. Assigning a more powerful permission to a principal
replaces the inferior permission with the more powerful one. cmis:all is, for example, more powerful than
sap:delete. If, for example, the current permission for a principal is cmis:read and the permission
cmis:write is added this results in an ACL with one ACE for the principal containing the permission
cmis:write. Adding an inferior permission has no effect.
Removing a permission for a principal from an object results in no ACE entry for the principal in that ACL. This is
independent of the current settings in the ACL with respect to this principal.
In methods with parameters for adding and removing ACEs, first the specified ACEs are removed and then the
new ones are added.

1.4.2.1.5.2.2 Owner Concept


Every folder and document has the sap:owner property. When an object is created the currently connected user
automatically becomes the owner of the object. The owner of an object always has full access even without any
specific ACEs granting him permission.
The owner property could be changed using the updateProperties method with the following restrictions:
The new value of the owner property must be identical with the currently connected user.
The currently connected user has cmis:all privilege.

1.4.2.1.5.2.3 User for Connecting to the Document Service


An application has the following options to connect to the document service:
The application can use a connect method without explicitly providing a parameter containing a user. Then
the current user is forwarded to the document service. The user's right to access particular documents and
folders is determined using the user ID and the attached ACLs.
The application can provide a user ID explicitly using a parameter of the connect method. Then this ID is used
for checking the access rights.

Note
Note that the document service is not connected to any Identity Provider or Identity Management System and
considers the provided ID as an opaque string. This is also true for the user or principal strings provided in the
ACEs when setting ACLs at objects.
The application is responsible for providing the correct user ID but it can also submit a technical user ID that
does not belong to any physical user, for example, to implement some kind of service user concept.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

583

1.4.2.1.5.2.4 Connecting While Providing Additional Principals


Besides providing a user, some connect methods have an additional parameter to provide the IDs of additional
principals to the document service.
If additional principals are provided, the user not only has his or her own permissions to access objects but in
addition gets the access rights of these principles. If, for example, the user him or herself has no right to access a
specific document but one of the additionally provided principals is allowed to read the content, then the user can
also access the content in the context of this connection.
With this concept an application could also use roles (or even groups) in the ACLs by setting ACEs indicating
these roles or groups. Then the roles of the current user can be evaluated during his connection calls and he is
granted access rights according to his role (or group) membership.
It is very important to keep in mind that the additional principals are also opaque strings for the document service.
This leaves it up to the application to decide what kind of information it sends as additional principals, including
identifiers only known by the application itself. On the other hand, the application must ensure that there is no
user with an ID similar to the additional principals, which the application uses in its ACLs because such a user
might unintentionally get too many access rights.

Example
This example shows how to assign write and read permissions for two kinds of users: Authors and readers.
Authors should have write access to documents and readers should only have read access to the documents.
The application defines two roles, one for authors called author-role and one for readers called readerrole.
For more information about securing applications and using roles, see Securing Applications.
To set up permissions for authors and readers as described in our example, set the appropriate ACEs at the
documents. The following code snippet shows how to set these permissions for a single document:
Session session = ..;
Document document = ..;
String authorRole = "author-role";
String readerRole = "reader-role";
// list of ACEs which should be added
List<Ace> addAcl = new ArrayList<Ace>();
// build and add ACE for user authors
List<String> permissionsAuthor = new ArrayList<String>();
permissionsAuthor.add("cmis:write");
Ace aceAuthor = session.getObjectFactory().createAce(authorRole,
permissionsAuthor);
addAcl.add(aceAuthor);
// build and add ACE for user U2
List<String> permissionsReader = new ArrayList<String>();
permissionsReader.add("cmis:read");
Ace aceReader = session.getObjectFactory().createAce(readerRole,
permissionsReader);
addAcl.add(aceReader);
// we remove all ACEs currently set
List<Ace> removeAcl = document.getAcl().getAces();
// add and remove the ACEs at the folder
document.applyAcl(addAcl, removeAcl, AclPropagation.OBJECTONLY);

584

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The next code snippet shows how the author and reader roles are automatically determined for the users and
propagated to the document service to provide the users the access rights they need.
import
import
import

String
String

com.sap.security.um.service.UserManagementAccessor;
com.sap.security.um.user.User;
com.sap.security.um.user.UserProvider;
authorRole = "author-role";
readerRole = "reader-role";

// fetch current user and its roles


UserProvider userProvider = UserManagementAccessor.getUserProvider();
User currentUser = userProvider.getCurrentUser();
Set<String> roles = currentUser.getRoles();
// add author or reader role
List<String> additionalPrincipals = new ArrayList<String>();
if (roles != null && roles.contains(authorRole)){
additionalPrincipals.add(authorRole);
}
else if (roles != null && roles.contains(readerRole)){
additionalPrincipals.add(readerRole);
}
// connect with additional role
String uniqueRepositoryName = ..;
String key = ..;
null,

Session session = EcmFactory.connectForUser(uniqueRepositoryName, key,


currentUser.getName(), null, additionalPrincipals);

As long as the user's session is active, his or her permission to access the documents is determined by the
user's role assignment. That is, authors can change documents and readers are only allowed to read them.

Related Information
Securing Java Applications [page 1211]

1.4.2.1.5.2.5 Predefined Users


There are some predefined users for the document service.
The following predefined users exist:
The {sap:builtin}admin user who always has full access to all objects no matter which ACLs are set.

Note
Note that the document service considers user IDs only as opaque strings. Therefore, the application must
prevent that a normal user connects to the document service using this administration user ID.
The {sap: builtin}everyone user applies to all users. Therefore, granting a permission to this user using
an ACE grants this permission to all users.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

585

1.4.2.1.5.2.6 Special Rules for ACL Settings


There are some document service specific rules with respect to ACLs.

Object Creation
When creating an object the connected user becomes the owner of the new object. The ACL of the parent folder is
copied to the new object and modified according to the addAcl and removeAcl parameter settings of the
create method.

Access by Path
A user is allowed to fetch an object using the path if the user has at least the cmis:read permission for the
object. In this case, the ACLs of the ancestor folders of the object are not relevant.

Versioning
All documents of a version series, except the private working copy (PWC), share the same ACL and owner.
It is only allowed to modify the ACL on the last version of a version series and only if it is not checked out.
Principals are allowed to check out a document if they have the cmis:write permission for it. They become
the owner of the PWC and the ACL of the PWC initially contains only one ACE with their principal name and
the cmis:all permission.
The ACL and the owner of a PWC can be changed independently of the other objects of the version series the
PWC belongs to. Only the owner of the PWC and users with the sap:delete permission are allowed to check
in or to cancel a checkout.
Only principals having the cmis:all permission for the version series are allowed to add or remove ACEs
when checking in a PWC.

Operations with Special Behavior


getChildren
Returns all children the principal is allowed to see. If the principal has no read permission for the current
folder, a NodeNotFoundException is thrown.
getDecendants
Returns only those descendants of a folder F, which the principal is allowed to see. Only those descendants
are returned for which all folders on the path from F to the descendant are accessible to the principal. If the
principal has no read permission for the current folder F, a NodeNotFoundException is thrown.
getFolderTree

586

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Similar to getDecendants.
getFolderParent
If the principal has no read permission for the current folder, a NodeNotFoundException is thrown. If the
principal has no read permission for the parent folder, a PermissionDeniedException is thrown.
getObjectParents
Returns a list with the parents the principal is allowed to see. Only one parent is returned because the
document service does not support multi-filing. If the principal has no read permission for the current object,
a NodeNotFoundException is thrown.
move
This method is allowed if the principal has the sap:file permission for the source folder, target folder, and
the object to move.

1.4.2.1.6

Performance Tips (Java)

In many ways the document service behaves like a relational database, where each document and folder is one
entry.
Therefore, most of the performance tips for databases also apply to the document service, for example:
Use selective queries and do not fetch too many objects.
Do not filter objects in the application if this is possible in the document service.
Try to reduce the amount of information you request for the objects, for example, only request the ACLs or
the allowed actions if you really need them. Furthermore, try to reduce the set of properties that you query to
just those that your application really depends on.
To help you improve the performance of your application that uses the document service, we provide the
following tips.

Note
These are only recommendations, and may not be suitable in every case. There may be situations where you
cannot and should not apply them.

Keep the Number of Repositories Small


Documents and folders are stored in the document service in different repositories. Creating a large number of
repositories entails significant CPU usage and requires a considerable amount of storage, even if no documents
are stored.

Recommendation
We recommend that you keep the total number of repositories to a minimum. Avoid, for example, creating a
separate repository for each user, especially if the users do not have large amounts of data to store. In such a
situation, create just one repository instead and store the user data in several separate folders.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

587

As a rule of thumb, if an application uses more than 10 repositories and if the amount of data in these repositories
is small, consider using folders instead of repositories. If each repository contains a large set of data (more than
100 GB), using many repositories is not a problem.

Prevent getChildren Calls on Large Folders


If folders contain many children, performance might be impaired when you navigate to one of these folders using
a getChildren call. If you navigate to a folder to analyze its data, for example, using the CMIS Workbench, this
analysis becomes complicated. In contrast, fetching a child in a folder with many children by using its object ID or
its path is not a problem.
It is difficult to define what qualifies as a "large" folder. If you send only one getChildren call per hour, then a
thousand or more children would be totally acceptable, but if you send many calls per second, then even 100
children might impair performance. In any case, the load caused by calling this method increases linearly with the
number of children.
Instead of having one folder with many children, you might consider subdividing the children into different
subfolders or even a subfolder hierarchy. Another alternative to using the getChildren call option is to use the
query method with the IN_FOLDER predicate together with additional restrictions to limit the number of matching
results.

Do Not Use Large Skip Counts


Several CMIS methods have a skip count parameter, for example, the getChildren or the query method. Using
large skip counts produces a significant load because a huge number of matching result objects is found and
skipped before the final result set can be collected. To prevent the need for large skip counts, try to reduce the
number of matching results by subdividing the children into different subfolders or by using a more selective
query.

Avoid Using a Sort Criterion (for example, getChildren, query)


Only use a sort criterion if you really need it, because it might reduce performance significantly (see also Paging
with maxItems and skipCount (for example, for getChildren, query) in the Frequently Asked Questions.

Do Not Request All Properties of an Object


In the operational context (see the OperationalContext.java class), you can define the properties that are to
be returned together with the selected objects. Do not query all properties because this might be time consuming
and it increases the amount of data transferred over the network. In particular, requesting the cmis:path
property can be inefficient because it has to be computed for each call. The general rule is to reduce the amount

588

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

of data you fetch from the document service; this also applies to other information you might request together
with the objects, such as the ACLs or allowed actions.

Access Using the Object ID Rather Than the Path


It is much faster to access an object using its ID than using its path.

Prevent Use of getFolderTree, getDescendants, and IN_TREE on Large


Hierarchies
Using the getFolderTree or getDescendants method on large hierarchies is very inefficient. The same is true
for the folder predicate IN_TREE that you can use in the statement of the query method. All these methods are
slow for large hierarchies even if the final result set is small.
The reason for the performance problems with these methods is that all the descendant folders of the start folder
have to be loaded from the database into the server where the document service is running. This results in many
calls to the database and many objects are transferred over the network. Finally, a very complex query with all the
IDs of the folders in the hierarchy has to be created and sent to the database to get the final result.
For the query method, the size of the searchable folder hierarchy is already restricted to a maximum of 1000. For
larger hierarchies an exception is thrown. Be aware that even a hierarchy of 1000 folders is quite large and results
in a heavy load on the system as well as bad performance for the request.

Reuse OpenCmis Session Objects


When applications use the document service they fetch a session object using one of the connect methods.
Creating a session is quite an expensive operation, which should be reused and shared if possible. A session
object is thread safe and allows parallel method calls.
Usually, a session is bound to a user. To reduce the number of sessions that are created, fetch the session only for
the first request of the user and store it in the user's HTTP session. Then the session can be reused in subsequent
requests of this user.
If an application uses a service user to connect the session to the document service, we recommend that you
store this session in a central place and reuse it for all subsequent requests.
When you share a session object, observe the following tips:
A session object has an internal cache, for example, for already fetched objects. To make sure that you fetch
the latest version of specific objects, clear the cache from time to time.
If a session is used for a very long time, problems might occur that result in exceptions (for example, network
connection problems). A possible solution is to replace the failing session with a new one. However, do not
replace a session if an ObjectNotFound exception is thrown because you tried to fetch a non-existent
document or folder. This also applies to similar situations where the exception is part of the normal method
behavior.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

589

Do not use a single session object for a large number of requests because due to session stickiness all these
requests are send to the same server. Rather use a pool of about 50 to 100 session objects to distribute the
requests over different servers on which the document service is running.

Multitenancy
One document service session is always bound to one tenant and to one user. If you create the session only once,
then store it statically, and finally reuse it for all subsequent requests, you end up in the tenant where you first
created the document service session. That is: You do not use multitenancy.
We recommend that you create one document service session per tenant and cache these sessions for future
reuse. Make sure that you do not mix up the tenants on your side.
If you expect a high load for a specific tenant, we recommend that you create a pool of sessions for that tenant. A
session is always bound to a particular server of the document service and this will not scale. If you use a session
pool, the different sessions are bound to different document service servers and you will get a much better
performance and scaling.

Search Hints
You can indicate hints for queries. The general syntax is:
hint:<hintname>[,<hintname>]*:<cmis query>
The following hints are currently available:
ignoreOwner: Usually, documents are returned for which the current user is the owner OR is present in an
ACE. The ignoreOwner setting returns only documents for which the current user has an ACE; ownership is
ignored in this case. This improves the speed of the query because the owner check is omitted. This is useful if
the owner is present in an ACE anyway.
noPath: Does not return the path property even if it is requested. This improves the speed of queries on
folders, because paths do not have to be computed internally.

Sample Code
hint:ignoreOwner,noPath:SELECT * FROM cmis:folder
hint:ignoreOwner:SELECT * FROM cmis:document

Related Information
Apache Chemistry OperationContext Class
Frequently Asked Questions (Java) [page 591]

590

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.2.1.7

Frequently Asked Questions (Java)

Answers to frequently asked questions on the document service.

How often does a backup occur?


The document service executes several backups a day to prevent file loss due to disasters. Backups are kept for
14 days and then deleted. Backups are not needed for simple hard disk crashes, since all storage hardware is
based on redundant hard disks.

How to do Paging with maxItems and skipCount (for example, for


getChildren, query)
If you implement paging using maxItems and skipCount, be aware that the different calls might be send to
different database servers each returning the result objects in a possibly different order. To get a consistent result
for these calls, add a unique sort criterion so that each server returns the objects using the same order. Be aware
that using a sort criterion might reduce the processing speed significantly. Therefore, only use a sort criterion if
really needed.

1.4.2.2

Consuming the Document Service (HTML5


Applications)

You can connect to the document service by treating it as an external service and the document service treats
your HTML5 application as an external app that requests access.

Procedure
To enable external access to your document service repositories, deploy a small proxy application that is available
out-of-the-box. For more information about its usage and deployment, see Access from External Applications
[page 559].

Related Information
Consuming the Document Service (Java) [page 548]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

591

1.4.2.3

Managing Repositories in the Cockpit

In the cockpit, you can create, edit, and delete a document service repository for your accounts. In addition, you
can monitor the number and size of the tenant repositories of your document service repository.

Note
Due to the tenant isolation in SAP HANA Cloud Platform, the document service cockpit cannot access or view
repostories you create in SAP Document Center or vice versa.

Related Information
Creating a Repository (Cockpit) [page 592]
Editing a Repository (Cockpit) [page 593]
Deleting a Repository (Cockpit) [page 594]
Viewing Content and Metadata Size of Tenant Repositories (Cockpit) [page 594]

1.4.2.3.1

Creating a Repository (Cockpit)

In the cockpit, you can create document service repositories for your accounts.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose the

Repositories

Document Repositories

in the navigation area.

3. To create a new repository, choose New Repository, and enter the following data.
Table 245:

592

Field

Entry

Name

Mandatory. Enter a unique name consisting of digits, letters, or special characters. The name is
restricted to 100 characters.

Display Name

Optional. Enter a display name that is shown instead of the name in the repository list of the ac
count. The name is restricted to 200 characters. You cannot change this name later on.

Description

Optional. Enter a descriptive text for the repository. The name is restricted to 500 characters.
You cannot change the description later on.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Field

Entry

Virus Scan Status

Select this checkbox to activate the virus scan.


When you create a repository, you can activate a virus scanner for write accesses. The virus
scanner scans files during uploads. If it finds a virus, write access is denied and an error message
is displayed. Note that the time for uploading a file is prolonged by the time needed to scan the
file for viruses.

Repository Key

Enter a repository key consisting of at least 10 characters but without special characters. This
key is used to access the repository meta data.
You cannot recover this key. Therefore, you must be sure to remember it.
You can, however, create a new key using the console client command reset-ecm-key [page
216].

Key Confirmation

Reenter the repository key.

4. Choose Save.

Related Information
Alternative Ways to Create Repositories
Creating a Repository Programmatically (Java) [page 550]
create-ecm-repository [page 118]
Connecting Your Repository to an Application
Creating a Sample Application (Java) [page 555]

1.4.2.3.2

Editing a Repository (Cockpit)

In the cockpit, you can change the name, key, or virus scan settings of the repository. You cannot change the
display name or the description.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. In the Repositories Document Repositories in the navigation area, select the repository for which you
want to change the name or the virus scan setting.
3. Choose Edit, and change the repository name or the virus scan setting.
4. Enter the repository key.
5. To change the repository key itself, choose the Change Repository Key button and fill in the key fields that
appear.
6. Choose Save.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

593

1.4.2.3.3

Deleting a Repository (Cockpit)

In the cockpit, you can delete a repository including the data of any tenants in the repository.

Context

Caution
Be very careful when using this command. Deleting a repository permanently deletes all data. This data cannot
be recovered.
If you simply forgot the repository key, you can request a new repository key and avoid deleting the repository.
For more information, see reset-ecm-key [page 216].

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. In the Repositories
to delete.

Document Repositories

in the navigation area, select the repository, which you want

3. Choose Delete.
4. On the dialog that appears, enter the repository key.
5. Choose Delete.

1.4.2.3.4

Viewing Content and Metadata Size of Tenant


Repositories (Cockpit)

In the cockpit, you can monitor the number and size of the tenant repositories of your document service
repository.

Context
If an application runs in several different tenant contexts, a tenant repository is created for each tenant context.
The tenant repository is created automatically when the application connects to the document service and the
respective tenant repository did not exist before.

594

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. In the

Repositories

Document Repositories

in the navigation area, click on the name of your repository.

3. Choose Tenant Repositories in the navigation area.

Related Information
Tenant Context API [page 995]

1.4.2.4

Managing a Repository with Console Client


Commands

You can create and manage repositories for the document service with client commands.
The following set of console client commands for managing repositories is available:

Related Information
Console Client Commands [page 96]
add-ecm-tenant [page 98]
create-ecm-repository [page 118]
delete-ecm-repository [page 132]
display-ecm-repository [page 151]
edit-ecm-repository [page 156]
list-ecm-repositories [page 195]
reset-ecm-key [page 216]

1.4.3 SAP Document Center


Use SAP Document Center to access and share business content stored in your existing document management
systems, by connecting them to your cloud application.
SAP Document Center helps you provide a seamless user experience to your business users by integrating file
access into the SAP Fiori Launchpad, SAP Jam, and SAP Business Suite applications. Using the native mobile
apps, your employees can access business content everywhere, online or offline - so they can focus on business
anytime, anywhere.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

595

SAP Document Center empowers your employees to share files securely with business partners, ensuring
compliance with business policies and external regulations for data privacy and data protection.
SAP Document Center helps you innovate. Integrate file sharing capabilities into your existing applications.
Expose tailored business content through the ABAP connector implementation. Leverage state-of-the-art
document management capabilities to integrate into your own apps (HTML5, iOS, Android, Windows Mobile, ).
Or use the SAP HANA Cloud Platform document service to build completely new content-rich applications.
SAP Document Center provides a ready-to-use solution for sharing content based on the SAP HANA Cloud
Platform, as well as an extension platform to integrate custom repositories and custom clients. In addition, it can
be integrated as a tile into the SAP Fiori launchpad. This way, SAP Document Center enables access to existing
on-premise business content, for example, documents that are stored in Microsoft SharePoint or SAP Business
Suite. Users can share content to collaborate with their business partners in a compliant way. Moreover, business
document templates and standards are available company-wide.
On top of the ready-to-use solution, you can use SAP Document Center to integrate a sharing functionality into
your existing applications, implement your own clients for advanced scenarios, and extend ABAP connectivity to
support your business processes.

Related Information
SAP Mobile Documents Cloud Edition - Integration How-To Guides
SAP Mobile Documents 1.0 - Cloud Version

596

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.4 Feedback Service (Beta)


The SAP HANA Cloud Platform feedback service (feedback service) provides developers, customers, and
partners with the option to collect end user feedback for their applications. In addition, the feedback service
provides predefined analytics on the collected feedback data - feedback rating distribution and detailed text
analysis of user sentiment (positive, negative, or neutral).

Note
The feedback service is a beta functionality that is available on the SAP HANA Cloud Platform trial landscape
for developer accounts.
To use the feedback service, you must enable it from the SAP HANA Cloud Platform cockpit for your account. For
more information, see Accessing Services in the Related Information section.
The feedback service has three components:
Feedback service client API that collects feedback data
Administration - the feedback service user interface (UI) for administering feedback collection and feedback
quota
Analysis - the feedback service UI for analyzing and exporting collected feedback data
The Analysis UI leverages the SAP HANA analytics and text analysis capabilities. Feedback data is stored in the
SAP HANA DB.
To be able to operate in Administration and Analysis, you need the following roles assigned to your user:
FeedbackAdministrator
FeedbackAnalyst
As an account owner, the roles are automatically assigned to your user once you have enabled the feedback
service. If you want to allow other SAP ID users to access the Analysis and Administration UIs, you need to assign
the roles manually. For more information about assigning the required roles, see Consuming the Feedback
Service [page 598].
In the Administration UI, the administrator adds the applications for which feedback is to be collected. As a result,
the developer can use the client API to consume the feedback service.
Once the feedback service is consumed by the application and feedback data is collected, the feedback analyst
can explore feedback text analysis in the Analysis UI. As a result, a developer can use end user feedback to
improve the performance and appearance of the specific application.

Architecture
The feedback service is operated by SAP HANA Cloud Platform and leverages the in-memory technology of the
SAP HANA DB.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

597

Related Information
Consuming the Feedback Service [page 598]
Getting Feedback for Applications [page 609]
Accessing Services [page 30]

1.4.4.1

Consuming the Feedback Service

Note
The feedback service is a beta functionality that is available on the SAP HANA Cloud Platform trial landscape
for developer accounts.
In this section, you will learn how to enable your application to use the SAP HANA Cloud Platform feedback
service to collect feedback. To do so, you need to:
1. Have a SAP HANA Cloud Platform developer account.
You can request a free trial developer account on https://account.hanatrial.ondemand.com/.
2. Enable the feedback service for your account. To do so, proceed as follows:
1. In the SAP HANA Cloud Platform cockpit, choose Services in the navigation.
2. Choose Feedback Service (BETA) Enable .
For more information about enabling services, see Accessing Services in the Related Information section.

598

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Have the required roles assigned to the users who should have access to the Analysis and the Administration
UIs.
Account owners have the required roles assigned to their user by default. As an account administrator, you
can assign the roles to other SAP ID users. To do so, proceed as follows:
1. In the SAP HANA Cloud Platform cockpit, choose

Services

Feedback Service (BETA) .

2. Under Service Configuration, choose Configure feedback Roles


FeedbackAdministrator and FeedbackAnalyst roles to your user.
When assigning the roles, make sure you use the following settings:

and assign the

Account: usageanalytics
Application: feedback

Note
For the role assignments to take effect once you have made them, you either use a new browser
session or log out from the cockpit and log on to it again.
4. Add the application for which feedback is to be collected in the Administration UI of the feedback service.
For more information about accessing the Administration and Analysis UIs of the feedback service, adding
applications, and analyzing feedback, see Getting Feedback for Applications [page 609].
5. Modify your application code to use the feedback service client API for collecting your application users'
feedback.
Your application can consume the feedback service either via a browser or via web application backend.

Related Information
Feedback Service Client API [page 599]
Consuming the Feedback Service Via a Browser [page 603]
Consuming the Feedback Service Via Web Application Backend [page 605]
Getting Feedback for Applications [page 609]
Managing Roles [page 1282]
Accessing Services [page 30]

1.4.4.1.1

Feedback Service Client API

The SAP HANA Cloud Platform feedback service is exposed through a client API that you can use to enable users
to send feedback for your application. You do this by adding code to your application that uses the feedback
service client API.
In this section you will learn:
How to call the feedback service
What are the service parameters
What is the service response
What error responses could be returned

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

599

You can also look at two tutorials about:


How to consume the service via a browser
How to consume the service via a web application backend
For more information about the tutorials, see the Related Links section.

Request
Your application can consume the feedback service through the service's REST API. The messages exchanged
between the client (your application) and the feedback service are JSON-encoded. You call the feedback service
by issuing an HTTP POST request to the unique application feedback URL that contains your application ID:
https://feedback-account_name.hanatrial.ondemand.com/api/v2/apps/application_id/posts
The application feedback URL is automatically generated after you have registered your application in the
Administration UI of the feedback service. For more information about how to obtain the application feedback
URL, see Feedback Service Administration in the Related Links section.
You need to set the Content-Type HTTP header of the request to application/json. In the request body, you
supply a feedback resource in JSON format. The resource may have the following attributes:
Table 246: Feedback Service Client API Attributes
Attribute

Type

Dimension

Description

texts

collection

texts.tX

string

ratings

collection

Rating values

ratings.rX

object

The rating for rating question


X. X is in the range [1 - 5]

ratings.rX.value

integer

context

object

context.page

string

2038

The page for which feedback


is sent

context.view

string

64

The page view for which feed


back is sent

context.lang

string

The ISO code of the language


used for the feedback text.
The code is a lower-case, twoletter code as defined by
ISO-639-1. The default value
is

Feedback text values


2000

[1-5]

The value for feedback ques


tion X. X is in the range [1 - 5]

The value for rating question


X
Feedback context

en
- English.

600

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Attribute

Type

Dimension

Description

context.attrX

string

64

Additional context specifica


tion. X is the range [1-5].

To collect feedback data, you need to provide values for at least one rating or one free text attribute. You can
additionally pass values for:
Up to 5 rating attributes
Up to 5 free text attributes
Up to 8 context attributes

Caution
According to the data privacy terms defined in the Terms of Use for SAP HANA Cloud Developer Edition, no
personal data must be collected, processed, stored or transmitted using your developer account on the trial
landscape. Therefore, you must not use the context attributes of the feedback service client API to collect
personal data such as user ID, user name, and so on.

Response
Upon successful request, the feedback service returns an HTTP response with code 200-OK and an empty body.

Error Handling
In case of errors, the feedback service returns an HTTP response with an appropriate error code. Whenever there
is any additional information describing the error, it is contained in the response body as an Error object. For
example:
{

error: {
code: 30,
message: "quota exceeded"
}

The value of error.code identifies the cause, and the value of error.message describes the cause. The string in
error.message is not intended to be presented to your application users and therefore not translated. The error
message's purpose is to assist the development of your application.
The table below lists the most common errors that the service can return. In addition to this list, a call to the
feedback service may also result in a response with another HTTP response code. In this case the HTTP response
code itself should be enough to describe the issue.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

601

Table 247: Error Codes


Error Cause

HTTP Status Code

Content Type

error.code

error.message

Feedback quota ex
ceeded

403

application/json

30

quota exceeded

Invalid request. All pa


rameter values are
valid, but the combina
tion of them is not.

400

application/json

40

<error
description>

Invalid parameter value 400

application/json

41

invalid value for param


eter <param_name>

Invalid JSON or empty


body

400

application/json

42

<error
description>

Incorrect service URL

404

Incorrect or misisng
Content-Type header

415

Incorrect HTTP method 405


- for example, calling
the feedback service
with method GET

Feedback service error

Examples:

the request does


not contain neither
text, neither rating

a parameter is
missing

500

Example
A sample request to the feedback service may look like this:
URL: https://feedback-<account_name>.hanatrial.ondemand.com/api/v2/apps/
<application_id>/posts
HTTP method: POST
Content-Type: application/json
Request body:
{

602

"texts":{
"t1": "Very helpful",
"t2": "Well done",
"t3": "Not usable at all",
"t4": "I don't like it",
"t5": "OK"
},
"ratings":{
"r1": {"value":5},
"r2": {"value":2},
"r3": {"value":5},
"r4": {"value":3},
"r5": {"value":1}

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

},
"context":{
"page": "/b2b/orders",
"view": "payment",
"lang": "en",
"attr1": "1.3.15",
"attr4": "mobile"
}

Related Information
Consuming the Feedback Service Via a Browser [page 603]
Consuming the Feedback Service Via Web Application Backend [page 605]
Feedback Service Administration [page 610]

1.4.4.1.2

Consuming the Feedback Service Via a Browser

This tutorial guides you how to use the SAP HANA Cloud Platform feedback service directly via a web browser.

Prerequisites
Have a SAP HANA Cloud Platform developer account.
You have installed the SAP HANA Cloud Platform Tools and created a SAP HANA Cloud server runtime
environment.
For more information, see the Related Links section.

Procedure
1. Create a dynamic web project:
a. From the Eclipse main menu, navigate to

File

New

Dynamic Web Project .

b. In the Project name field, enter feedback-app. Make sure that SAP HANA Cloud is selected as the target
runtime.
c. Leave the default values for the other project settings and choose Finish.
2. Add an HTML file to the web project:
a. In the Project Explorer view, select the feedback-app node.
b. From the Eclipse main menu, navigate to

File

New

HTML File .

c. Enter as file name index.html.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

603

d. To generate the file, choose Finish.


e. Replace the source code with the following content:
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
<title>Feedback Application</title>
<script src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js"
id="sap-ui-bootstrap"
data-sap-ui-libs="sap.m, sap.ui.commons"
data-sap-ui-theme="sap_bluecrystal">
</script>
<script>
var app = new sap.m.App({initialPage:"page1"});
var t1 = new sap.m.Text({text: "Please share your feedback"});
var t2 = new sap.m.Text({text: "Do you like it"});
var ind1 = new sap.m.RatingIndicator({maxValue : 5, value : 4});
var t3 = new sap.m.Text({text: "Some free comments:"});
var textArea = new sap.m.TextArea({rows : 2, cols: 40});
var sendBtn = new sap.m.Button({
text : "Send",
press : function() {
var data = {
"texts": {t1: textArea.getValue()},
"ratings": {r1: {value: ind1.getValue()}},
"context": {page: "page1"}
};
$.ajax({
url: "https://feedback<account_name>.hanatrial.ondemand.com/api/v2/apps/<your_application_id>/
posts",
type: "POST",
contentType: "application/json",
data: JSON.stringify(data)
}).done(function() {
jQuery.sap.require("sap.m.MessageToast");
sap.m.MessageToast.show("Thank you. Your feedback was
accepted.");
}).fail(function() {
jQuery.sap.require("sap.m.MessageToast");
sap.m.MessageToast.show("Something went wrong plese try
again later.");
});
}
});
var vbox = new sap.m.VBox({
fitContainer: true,
displayInline: false,
items: [t1, t2, ind1, t3, textArea, sendBtn]
});
var page1 = new sap.m.Page("page1", {
title: "Feedback Application",
content : vbox
});
app.addPage(page1);
app.placeAt("content");
</script>
</head>
<body class="sapUiBody">
<div id="content"></div>
</body>
</html>

604

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
<Account_name> is the unique identifier of the account over the cloud that is automatically generated
when the account is created. For more information about the account parameters, see Managing
Accounts and Quota in the Related Information section.
3. Adjust the service URL in the source code so that it points to the application feedback URL generated for your
application.
4. Test the application on SAP HANA Cloud Platform local runtime:
a. Deploy the application on your SAP HANA Cloud Platform local runtime.
b. Open the application in your web browser: http://<host>:<port>/feedback-app/. Send sample
feedback.
5. Test the application on the SAP HANA Cloud Platform:
a. Deploy the application on the SAP HANA Cloud Platform.
b. Start the application and open it in your web browser.

Related Information
Installing Java Tools for Eclipse and SDK [page 33]
Consuming the Feedback Service [page 598]
Feedback Service Administration [page 610]
Managing Accounts and Quota [page 17]

1.4.4.1.3

Consuming the Feedback Service Via Web


Application Backend

This tutorial guides you how to use the SAP HANA Cloud Platform feedback service from the Java code in a simple
Java EE Web application.

Prerequisites
Have a SAP HANA Cloud Platform developer account.
You have installed the SAP HANA Cloud Platform Tools and created a SAP HANA Cloud server runtime
environment. For more information, see Installing Java Tools for Eclipse and SDK [page 33].
To be able to operate in the Administration and Analysis UIs of the feedback service so that you can test the
feedback for your application, you need to assign the following roles to your user:
FeedbackAdministrator
FeedbackAnalyst
For more information, see: Getting Feedback for Applications [page 609].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

605

Procedure
1. Create a dynamic web project:
a. From the Eclipse main menu, navigate to

File

New

Dynamic Web Project .

b. In the Project name field, enter feedback-app. Make sure that SAP HANA Cloud is selected as the target
runtime.
c. Leave the default values for the other project settings and choose Finish.
2. Add a servlet to the web project:
a. In the Project Explorer view, select the feedback-app node.
b. From the Eclipse main menu, navigate to

File

New

Servlet .

c. Enter the Java package hello and the class name FeedbackServlet.
d. To generate the servlet, choose Finish.
e. Replace the source code with the following content:
FeedbackServlet.java
package hello;
import java.io.IOException;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.conn.ClientConnectionManager;
import org.apache.http.entity.StringEntity;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.core.connectivity.api.DestinationException;
import com.sap.core.connectivity.api.http.HttpDestination;
/**
* Servlet implementation class FeedbackServlet
*/
public class FeedbackServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final Logger LOGGER =
LoggerFactory.getLogger(FeedbackServlet.class);
public FeedbackServlet() {
super();
}
protected void doPost(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
HttpClient httpClient = null;
try {
Context ctx = new InitialContext();
HttpDestination destination = (HttpDestination)
ctx.lookup("java:comp/env/FeedbackService");
httpClient = destination.createHttpClient();
HttpPost post = new HttpPost();
String text = request.getParameter("text");
String rating = request.getParameter("rating");
String page = request.getParameter("page");
String body = "{\"texts\":{\"t1\": \"" + text + "\"}, \"ratings\":
{\"r1\": {\"value\": " + rating + "}}, \"context\": {\"page\": \"" + page +
"\", \"lang\": \"en\", \"attr1\": \"mobile\"}}";
//Use the proper content type

606

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"UTF-8"));

post.setEntity(new StringEntity(body, "application/json",

HttpResponse httpResponse = httpClient.execute(post);


int responceCode = httpResponse.getStatusLine().getStatusCode();
if (responceCode != HttpServletResponse.SC_OK) {
LOGGER.error("Feedback Service call failed with HTTP responce
code " + responceCode + ". Error: " +
httpResponse.getStatusLine().getReasonPhrase());
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR, "Something
went wrong please try again later.");
} else {
response.getWriter().print("Your feedback was accepted. Thank
You!");
}
} catch (NamingException e) {
LOGGER.error("Cannot lookup the feedback service destination", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
"Cannot lookup the feedback service destination");
} catch (DestinationException e) {
LOGGER.error("Cannot create HttpClient", e);
response.sendError(HttpServletResponse.SC_INTERNAL_SERVER_ERROR,
"Something went wrong please try again later.");
} finally {
if (httpClient != null) {
ClientConnectionManager connectionManager =
httpClient.getConnectionManager();
if (connectionManager != null) {
connectionManager.shutdown();
}
}
}
}
}

3. Add an HTML file to the web project:


a. In the Project Explorer view, select the feedback-app node.
b. From the Eclipse main menu, navigate to

File

New

HTML File .

c. Enter as file name index.html.


d. To generate the file, choose Finish.
e. Replace the source code with the following content:
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/>
<title>Feedback Application</title>
<script src="https://sapui5.hana.ondemand.com/resources/sap-ui-core.js"
id="sap-ui-bootstrap"
data-sap-ui-libs="sap.m, sap.ui.commons"
data-sap-ui-theme="sap_bluecrystal">
</script>
<script>
var app = new sap.m.App({initialPage:"page1"});
var t1 = new sap.m.Text({text: "Please share your feedback"});
var t2 = new sap.m.Text({text: "Do you like it"});
var ind1 = new sap.m.RatingIndicator({maxValue : 5, value : 4});
var t3 = new sap.m.Text({text: "Some free comments:"});
var textArea = new sap.m.TextArea({rows : 2, cols: 40});
var sendBtn = new sap.m.Button({
text : "Send",
press : function() {
var data = {
"text": textArea.getValue(),

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

607

"rating": ind1.getValue(),
"page": "page1"

accepted.");

};
$.ajax({
url: "FeedbackServlet",
type: "POST",
data: data
}).done(function() {
jQuery.sap.require("sap.m.MessageToast");
sap.m.MessageToast.show("Thank you. Your feedback was

}).fail(function() {
jQuery.sap.require("sap.m.MessageToast");
sap.m.MessageToast.show("Something went wrong plese try
again later.");
});
}
});
var vbox = new sap.m.VBox({
fitContainer: true,
displayInline: false,
items: [t1, t2, ind1, t3, textArea, sendBtn]
});
var page1 = new sap.m.Page("page1", {
title: "Feedback Application",
content : vbox
});
app.addPage(page1);
app.placeAt("content");
</script>
</head>
<body class="sapUiBody">
<div id="content"></div>
</body>
</html>

4. Declare a reference to the feedback service destination:


a. Open the WebContent/WEB-INF/web.xml file and add the following content just before the closing webapp tag:
web.xml
...
<resource-ref>
<res-ref-name>FeedbackService</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>
...
5. Test: the application on SAP HANA Cloud Platform local runtime:
a. Deploy the application on the SAP HANA Cloud Platform local runtime.
b. Open the Connectivity tab page of the SAP HANA Cloud Platform local runtime.
c. Create a destination with the name FeedbackService and configure it so it can be consumed by the
application at runtime. For more information, see the Related Links section.
Name=FeedbackService
Type=HTTP
URL=https://feedback-<account_name>.hanatrial.ondemand.com/api/v2/apps/
<your_application_id>/posts
Authentication=NoAuthentication
The application feedback URL which contains the application ID is automatically generated after you have
registered your application in the Administration UI of the feedback service. For more information about

608

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

how to obtain the application feedback URL, see Feedback Service Administration in the Related Links
section.
d. Open the application in your web browser: http://<host>:<port>/feedback-app/. Send sample
feedback.
6. Testing the application on SAP HANA Cloud Platform:
a. Deploy the application on the SAP HANA Cloud Platform.
b. Open the SAP HANA Cloud Platform Cockpit in your web browser. Create a destination with the name
FeedbackService and configure it so it can be consumed by the application at runtime. For more
information, see the Related Links section.
Name=FeedbackService
Type=HTTP
URL=https://feedback-<account_name>.hanatrial.ondemand.com/api/v2/apps/
<your_application_id>/posts
Authentication=NoAuthentication
The application feedback URL which contains the application ID is automatically generated after you have
registered your application in the Administration UI of the feedback service. For more information about
how to obtain the application feedback URL, see Feedback Service Administration in the Related Links
section.
c. Start the application and open it in your web browser.

Related Information
Installing Java Tools for Eclipse and SDK [page 33]
Consuming the Feedback Service [page 598]
Feedback Service Administration [page 610]
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Cockpit [page 301]

1.4.4.2

Getting Feedback for Applications

Once you deploy your application on the SAP HANA Cloud Platform, you need to add the applications for which
feedback is to be collected in the Administration UI of the feedback service. As a result, a dedicated application
feedback URL is generated. The developer uses this URL in the client API to consume the feedback service. Once
the feedback service is consumed by the application and feedback data is collected, the feedback analyst can
explore feedback rating and text analysis in the Analysis UI of the feedback service. As a result, a developer can
use end user feedback to improve the performance and appearance of the specific application.
To be able to operate in the Administration and Analysis UIs of the feedback service, you need the following roles
assigned to your user:
FeedbackAdministrator
FeedbackAnalyst
As an account owner, the roles are automatically assigned to your user once you have enabled the feedback
service. If you want to allow other SAP ID users to access the Analysis and Administration UIs, you need to assign

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

609

the roles manually. For more information about assigning the required roles, see Consuming the Feedback
Service [page 598].
You can also provide your feedback about the feedback service and its UI. To do that, choose the Feedback button
and share your ideas and suggestions for improvement in the feedback form. Note that information for your
landscape host as well as for the specific place (page, view or tab) from which you have called the feedback form
is collected for analysis purpose.

Related Information
Feedback Service Administration [page 610]
Feedback Analysis [page 612]
Managing Roles [page 1282]

1.4.4.2.1

Feedback Service Administration

As a feedback administrator, you can:


Add applications for which feedback is to be collected in the Administration UI of the feedback service
Customize descriptions of feedback questions
Customize descriptions of context attributes
Free up feedback quota space
Once you add an application to your list, you enable it to use the feedback service. As a result, a unique accountspecific and application-specific URL is generated. To start collecting feedback, the developer needs to integrate
the URL in her or his application UI where end users post feedback (for example, in a feedback form). The URL is
called through a POST request by the application that wants to send feedback. That is, once an end user submits
the feedback form, the application calls the feedback service through the URL and the service stores user
feedback.
An application feedback URL looks like this:
https://feedback-<account_name>.hanatrial.ondemand.com/api/v2/apps/<application_id>/
posts
To be able to operate in the Administration UI of the feedback service, you need to assign the
FeedbackAdministrator role to your user.
To access Administration, open the following URL in your browser:
https://feedback-<account_name>.hanatrial.ondemand.com/admin/mobile
Each account has a feedback quota assigned that is, a specific amount of feedback data that can be stored in
the SAP HANA DB. The amount equals to 250 feedback forms filled in by end users. Once you reach 70% of the
feedback quota, you get a warning message. Once you reach the feedback quota limit, however, the feedback
service ceases processing feedback requests and storing feedback data. What you can do in either case is free up
quota space. You do this by deleting the feedback records for a particular time period of your choice.
For each application, you can edit the description of:

610

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

rating questions
free text questions
context attributes

Note
The feedback administrator can enter as descripitons the questions' text from the application feedback form.
Descriptions are displayed in the Analysis UI of the feedback service.
If you have the FeedbackAnalyst role assigned (in addition to the FeedbackAdministrator role), you can analyze
feedback results and export raw feedback data.

Related Information
Administering Application Feedback [page 611]
Feedback Analysis [page 612]
Cockpit [page 84]
Managing Roles [page 1282]

1.4.4.2.1.1 Administering Application Feedback

Context
As a feedback administrator, you can add applications and administer applications' feedback.

Procedure
1. Open the feedback Administration UI.
2. Add an application by choosing the +Add button and enter a name for the application for which feedback is to
be collected.
3. To customize the description of a rating or free text question, click on the pencil icon in the respective
question row.
4. To customize the description of a context attribute, repeat Step 3.
5. To free up quota space, click on the Free Up Quota Space link and choose a specific time period for which
feedback data is to be permanently deleted.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

611

1.4.4.2.2

Feedback Analysis

As a feedback analyst, in the Analysis UI of the feedback service you can explore the feedback collected from end
users by viewing detailed rating or text analysis or exporting the feedback text as raw data.
The rating analysis presents information about rating questions and how feedback rating is distributed according
to time and distribution criteria.

Select Time Period


You can choose a specific time period for which to view analyzed feedback data and to export raw data. By
default, the time period selected is the last 7 days.

Export Raw Data


You can export raw feedback data, so that you can perform more specific or tailored to your needs analysis. You
download raw feedback data in a .CSV format encoded in UTF-8.

Note
When you open the exported file, if there are characters that do not appear correctly, reopen the file as a UTF-8
encoded one.

Related Information
Free Text Questions [page 612]
Rating Questions [page 614]
SAP HANA Developer Guide
Feedback Service Client API [page 599]
Feedback Service Administration [page 610]

1.4.4.2.2.1 Free Text Questions


As a feedback analyst, you can explore the feedback collected from end users by viewing the detailed text
analysis. Text analysis classifies user feedback by:
Type (request, problem)
Sentiment (positive, negative, or neutral)

612

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For further information about text analysis, follow the link in the Related Links section (SAP HANA Developer
Guide) and navigate to the Enabling Search and read the Text Analysis chapter.

Get an Overview of Feedback Text Sentiment


On the Overview screen you can see a summary of all free text feedback questions. Each question tile provides the
following information:
Question text description
Sentiment summary in %
The sentiment summary provides useful overview of negative, positive, and neutral sentiments of user feedback.
Feedback from a single user can result in a small or large amount of the overall sentiment count of the specific
question. In other words, sentiment is calculated not per user feedback but by the sentiment elements (words) in
the feedback text.

View Question Details


Once you click on a question tile, you can see detailed information about the specific feedback question:
Full question text
Number of feedback responses
Filter that enables you to narrow down the responses' list to a specific text analysis group, that is, to feedback
of specific type or sentiment
A list of all feedback responses with short details about feedback type, sentiment, and UTC date when the
feedback was posted
For exmaple, you can filter your responses' list for a specific question to show only feedback of type Problem that
has Negative and Neutral sentiment. The returned list is ordered by date (most recent is on top).

Note
No matter what filter is applied, the list always displays responses (if any) that are not classified by type or
sentiment.

View Feedback Details


You can further drill-in to view details about a specific feedback response and examine the actual feedback text
analysis. You can view the whole text of the feedback response with all detected text analysis "hits". In addition,
you can choose which types of "hits" to highlight within the text. For example, you can once again choose to
highlight just the Problem that has Negative and Neutral text analysis. Alternatively, you can choose to remove all
highlights.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

613

Related Information
SAP HANA Developer Guide
Feedback Service Client API [page 599]
Feedback Service Administration [page 610]

1.4.4.2.2.2 Rating Questions


As a feedback analyst you can examine the feedback collected from users by viewing detailed rating analysis.
Users can reply to each rating question by choosing a number on scale of 1 to 5 where 1 is the lowest rating and 5
is the highest.

Get an Overview of Feedback Rating Questions


On the Overview screen you can see a summary of all rating questions. Each question tile provides the following
information:
Question text description
Average rating

View Question Details


Once you click on a question tile, you can see detailed information about the specific feedback question and for
the time period you specified:
Full question text
Average rating received
Number of feedback responses
Two graph views of feedback rating distribution
Two table views of feedback rating distribution
Depending on the time period you have specified the graph and table views show the following data (just in
different format):
Feedback distribution by rating - graph or table showing what percent of the overall feedback responses
receive a certain rating number. That is, how feedback is distributed in terms of a specific rating.
Feedback distribution by time period - graph or table in which you can choose to see feedback distribution
among various time frame granularities, for exmaple a day or an year. The data displayed is the average rating
to the specified time granularity and only applies to the time period intially selected.

614

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
SAP HANA Developer Guide
Feedback Service Client API [page 599]
Feedback Service Administration [page 610]

1.4.5 Gamification Service


Overview
The SAP HANA Cloud Platform, gamification service allows the rapid introduction of gamification concepts into
applications. The service includes an online development and administration environment (gamification
workbench) for easy implementation and analysis of gamification concepts. The underlying gamification rule
management provides support for sophisticated gamification concepts, covering time constraints, complex
nested missions and collaborative games. The built-in analytics module makes it possible to perform advanced
analysis of the player's behavior in order to facilitate continuous improvement of game concepts.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

615

Key Pain Points Addressed


Development effort for introducing gamification in new and existing apps
Limits of achievement systems and existing platforms regarding the complexity of supported game
mechanics and the speed of feedback
Manageability of sophisticated gamification concepts meeting enterprise performance, security, and
scalability requirements

Key Product Features


Web-based IDE (gamification workbench) for modeling game mechanics and rules
Gamification engine for real-time processing of sophisticated gamification concepts involving time
constraints and cooperation
Built-in runtime game analytics for continuous improvement of game designs
Web API for easy integration
Simple SAP UI5 integration based on widgets
Single-Sign-On (SSO) support based on SAP Cloud Identity Service
Enterprise-level performance and scalability

1.4.5.1

Getting Started

Follow the pages below to learn how to enable the gamification service in your account, and how to configure and
use the sample application HelpDesk.
1. Enable Gamification Service [page 617]
2. Assign Gamification Roles [page 617] (Automated)
3. Configure Destinations [page 619] (Automated, credential of technical user must be provided)
4. Enable Principal Propagation [page 622] (Automated)
5. Generate Demo Content for HelpDesk [page 623]
6. Use the Gamified HelpDesk Application [page 623]
When enabling the service, configuration steps 2, 3, and 4 are executed automatically, as follows:
All gamification roles are assigned to the user that enabled the service
The required destinations are created on the account level. The destination gsdest requires credentials
(user/password). For the Trial version it is possible to use the given SCN user for this. However, it is safer to
create a dedicated technical user for this according to the following procedure.

Note
If you use your SCN user for configuring the technical destination gsdest make sure that you change the
destination configuration after changing the SCN user password in SAP ID Service. Otherwise, your user will be
locked when using the HelpDesk app.

616

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.1.1

Enable Gamification Service

Prerequisites
You have access to a SAP HANA Cloud Platform account for personal development, or to a Trial account.
You are an account member with the role Administrator.
You have an SCN user.

Procedure
1. In the SAP HANA Cloud Platform cockpit, choose the Services tab.
2. Select Gamification Service.

3. Choose Enable in the detailed view of the service.

1.4.5.1.2

Assign Gamification Roles

Prerequisites
You have logged on to the SAP HANA Cloud Platform cockpit with your SCN user and password.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

617

Procedure
1. In the SAP HANA Cloud Platform cockpit, choose the Services tab.
2. Click the Gamification Service tile.
3. Click on the Configure Gamification Service link.

4. Go to the Roles tab.


5. Assign the necessary roles, for example AppStandard, AppAdmin, GamificationDesigner,
TenantOperator, and helpdesk.

Related Information
Managing Roles [page 1282]

618

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.1.3

Configure Destinations

Prerequisites
You have logged into the SAP HANA Cloud Platform cockpit with your SCN user and password.

Context
You need to configure a destination to allow the communication between your application (in this case, a sample
app) and your subscription to the gamification service. For the sample application, two destinations are
necessary:
For the gamification service API to send the events: gsdest
For the gamification service API to request the achievements: gswidgetdest

Note
The destinations must be created on account level for your personal development account.

1.4.5.1.3.1 Create a Destination for Sending Events


Procedure
1. In the cockpit, choose the Destinations sub-tab in the Connectivity tab.
2. Enter the name: gsdest.
3. Select the type: HTTP.
4. Optional: Enter a description.
5. Enter the URL of the API of your subscription: https://<application_URL>/gamification/api/tech/
JsonRPC
You can find the application URL of your service instance by navigating to the gamification workbench
Account

Services

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Gamification Service

Go to Service .

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

619

6. Select the proxy type: Internet.


7. Select the authentication: Basic Authentication
8. Enter user ID. Recommendation: Use a separate technical user, see following procedure. Alternatively, you
can use your SCN user. In this case make sure to update the destination as well in case of password changes.
Otherwise the SAP ID Service will lock you user when using the HelpDesk app.
9. Enter the SCN password.
10. Choose Save.

Note
It may take up to 5 minutes until the destinations are available for the service.

Related Information
HTTP Destinations [page 322]

620

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.1.3.2 Create a Destination for Getting Players'


Achievements
Procedure
1. In the cockpit, choose the Destinations sub-tab in the Connectivity tab.
2. Enter the name: gswidgetdest.
3. Select type: HTTP.
4. Optional: Enter a description.
5. Enter the URL of your subscription API: https://<application_URL>/gamification/api/user/
JsonRPC
You can find the application URL of your service instance by navigating to the gamification workbench
Account

Services

Gamification Service

Go to Service .

6. Select proxy type: Internet.


7. Select authentication: AppToAppSSO
8. Choose Save.

Note
It may take up to five minutes until the destinations are available for the service.

Related Information
HTTP Destinations [page 322]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

621

1.4.5.1.4

Enable Principal Propagation

Prerequisites
You have logged into the SAP HANA Cloud Platform cockpit with your SCN user and password.
You are an account member with role Administrator.

Context
To support application-to-application SSO as part of destination gswidgetdest, you have to configure your
account to allow principal propagation.

Procedure
1. Open the cockpit and choose the Trust sub-tab in the Security tab.
2. Choose the Local Service Provider sub-tab.
3. Choose Edit.
4. Change the Principal Propagation value to Enabled.

Related Information
Application-to-Application SSO Authentication [page 332]

622

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.1.5

Generate Demo Content for HelpDesk

Prerequisites
You have logged into the SAP HANA Cloud Platform cockpit with your SCN user and password.
You have the role TenantOperator.

Procedure
1. In the SAP HANA Cloud Platform cockpit, choose the Services tab.
2. Go to Gamification Service and press the Go to Service icon. The gamification workbench is opened.
3. Go to tab Administration.
4. Go to Demo Content Creation and click on Create HelpDesk Demo.

After a while, you will see a notification: Gamification concept successfully created.
5. Switch to the HelpDesk application by using the dropdown box in the upper right corner.
6. Go to the Summary tab to check if all game mechanics are available.

1.4.5.1.6

Use the Gamified HelpDesk Application

Prerequisites
You have the role helpdesk.
HelpDesk demo content is created.
The destinations gsdest and gswidgetdest are available.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

623

Procedure
1. In the SAP HANA Cloud Platform cockpit, choose the Services tab.
2. Go to Gamification Service and choose the Go to Service link. The gamification workbench is opened.
3. Click the Help link in the upper right corner. A help pop-up appears.
4. Click the Open HelpDesk link.

5. Log on to the HelpDesk application.

6. Process a ticket.

624

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

7. You will receive points.

8. Review your user profile.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

625

1.4.5.2

Gamification Development Cycle

The gamification development cycle describes the processes involved in the introduction of gamification in
existing or new applications.
In general, there three major processes are required:
Creation of the gamification concept
Implementation of the gamification concept
Integration with application (target application)
Creation of the gamification concepts is a purely conceptual tasks that is typically executed by gamification
designers. The task is executed during the design phase and covers the specification of a meaningful game /
gamification design.
Implementation of the gamification concept covers the mapping of the gamification concept to the game
mechanics offered by the gamification service. This task is normally performed by gamification designers and/or
IT experts.
Integration with the application is a development tasks which covers the technical integration of the target
application with the APIs of the gamification service. This is normally performed by application developers, since
technical knowledge of the application is required (such as implementation points for listening for events or visual
representation of achievements).

626

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.2.1

Creating a Gamification Concept

A gamification concept is normally developed by gamification designers and domain experts. The gamification
concept describes the (game) mechanics that will serve to encourage users (players) to perform certain tasks. An
example of this is to encourage call center employees to process tickets or motivate them to process
cumbersome tickets first.

Note
Creation of the gamification concept is not a service that is covered or supported by the gamification service.
A simple gamification concept covers elements such as points and badges. Users are awarded experience points
for certain actions for example, and badges as a visual representation. The gamification concept describes how
these elements are used to intrinsically motivate the users. It therefore includes descriptions of the actions (within
the application) that allow users to attain the various achievements.
Examples are missions to foster collaboration or timel constraints that encourage users to work faster.

Related Information
Gamification Design [page 689]

1.4.5.2.2

Implementing the Gamification Concept

The implementation of the gamification concepts is required in order to map the gamification concept to the
elements used in the gamification service. The gamification workbench is used to maintain the gamification
elements, such as points, badges, levels or rules.
The gamification concept can be modified at runtime. Please be aware that gamification is about full transparency
to the users and is used primarily to encourage them. We therefore advise against modifying the gamification
significantly without informing the users, since this might catch them by surprise and could possibly demotivate
them.

Related Information
Configuring Game Mechanics [page 640]

1.4.5.2.3

Integration with the Application

Integration with the application covers the technical integration of the target application with the APIs of the
gamification service. Firstly, integration is required to send events that are of interest to the gamification service,

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

627

for example to send the event that a user in a call center has successfully processed a ticket. Secondly,
integration is necessary to notify the user about his/her achievements, to send notifications to the user for earned
points, or to display the users profile.
The gamification service is designed to support the integration of mainly cloud applications running with SAP
HANA Cloud Platform. Integration of other applications is technically possible, but restricted for security reasons.

Related Information
Integrating Gamification Service into a Target Application [page 673]

1.4.5.2.4

Analyzing Gamification Concepts

Gamification is a continuous process. It is crucial to continuously monitor the influence of a gamification concept
and react to the users' behavior. For example, you want to know if your gamification concept motivates the target
group or if users lose interest.
The gamification service offers basic analytics: for example, the assignment of points or badges to users over
time. Therefore, you can analyze peaks and troughs of user achievements.

Related Information
Analyzing Gamification Concepts [page 681]

1.4.5.2.5

Ensuring Data Privacy

The introduction of gamification often requires the acquisition of sensitive information. It might be necessary for
example to track the user behavior within an application in order to allow the gamification of onboarding
scenarios.
The gamification service makes it possible to anonymize user data. The gamification service also offers secure
communication via the various APIs.
It is the responsibility of the host application to ensure data privacy however. As a developer of the host
application, you are responsible for ensuring that only data that is necessary is sent to the gamification service.

Related Information
Integrating Gamification Service into a Target Application [page 673]

628

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.3

Gamification Workbench

The gamification workbench is the central point for managing all gamification content associated with your
account and for accessing key information about your gamification usage. It allows you to manage the
gamification concepts of all applications deployed in your account from a single dedicated Web-based user
interface.

Summary Dashboard
The figure below shows an example of the Summary dashboard in the workbench and is followed by an
explanation:

The entry page Summary of the gamification workbench provides an overview of the gamification concept for the
selected app, the overall player base and overall landscape.

Logon
You can log on with your account user via SSO (single-sign on).
The gamification workbench can be accessed using the Subscription tab in the SAP HANA Cloud Platform cockpit.
The following link will be used: https://< SUBSCRIPTION_URL>/gamification .

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

629

Navigation
The navigation menu comprises the following elements:
Summary
Game mechanics
Administration
Players
Analytics

Note
You need specific roles in order to access the gamification workbench, see Roles [page 630].
The following table describes the navigation levels in more detail:
Table 248:
Level

Description

Game Mechanics

Allows you to read and configure game mechanics (man


aging points, badges, levels, missions and rules for exam
ple) for multiple applications

Analytics

Allows you to test gamification concepts and APIs

Allows you to import and export gamification concepts

Allows you to view gamification statistics (achievements


gained by players for example)

Administration

Players

1.4.5.3.1

Allows you to manage apps

Allows you to create default content (demo content)

Allows you to manage gamification service users

Allows you to view gamification user profiles

Roles

The following roles can be assigned to users, to enable them to access the gamification workbench:

630

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 249:
Role
GamificationDesigner

Workbench Level

Game Mechanics

Analytics

Description

Full access to game mechanics and


rules (read, write, activate etc.) for
all apps created for the tenant

Read aggregated gamification ana


lytics (no access to individual player
data)

Export or import game mechanics


and rules for a certain app

GamificationReviewer

Game Mechanics (read-only)

Analytics

Read game mechanics and rules


(no write access)

Read aggregated gamification ana


lytics (no access to individual player
data)

Export game mechanics and rules


for a certain app

TenantOperator

Game Mechanics (read-only)

Manage Apps (create, delete)

Administration

Configure tenant

Players

Read game mechanics and rules


(no write access)

Full access to user data, including


player details with player achieve
ments

Full access to team data

Full tenant export or import, includ


ing player data

AppStandard

Game Mechanics (send events in

API Terminal)

Send events using the

handleEvent method (for test


ing purposes only!)

For more information about assigning roles to a user, see Security [page 632].

1.4.5.3.2

Viewing Assigned User Roles

Prerequisites
You have logged on to the gamification workbench.
At least one gamification service role is assigned to your user.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

631

Procedure
1. Hover the cursor over your user name.
2. Wait until the user details are displayed.

1.4.5.4

Security

Context
The gamification service offers the gamification workbench, an API for integration and a demo app. The access to
the user interfaces and API is protected using SAP HANA Cloud Platform roles.

Note
Roles have to be explicitly assigned to a SAP HANA Cloud Platform user.

632

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
The API can be used for the integration of host applications. For productive use a technical user (SAP HANA
Cloud Platform user) should be created for a communication between the host application and the gamification
service. (The use of a personal account or user is only recommended for testing or demo purposes.)

1.4.5.4.1

Roles

The following roles can be assigned to access the gamification service gamification workbench, API or demo app
and have to be explicitly assigned to a SAP HANA Cloud Platform user:
Table 250:
Role

Type

Access Level

GamificationDesigner

User

Workbench

Game Mechanics

Analytics

Description

Full access to game me


chanics and rules (read,
write, activate etc.) for all
apps created for the ten
ant

Read aggregated gamifi


cation analytics (no ac
cess to individual player
data)

Export or import game


mechanics and rules for
a certain app

GamificationReviewer

User

Game Mechanics (read-

only)

Read game mechanics


and rules (no write ac
cess)

Analytics

Read aggregated gamifi


cation analytics (no ac
cess to individual player
data)

Export game mechanics


and rules for a certain
app

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

633

Role

Type

TenantOperator

User

Access Level

Game Mechanics

Administration

Players

Description

Manage Apps (create,


delete)

Configure tenant

Read game mechanics


and rules (no write ac
cess)

Full access to user data,


including player details
with player achievements

Full access to team data

Full tenant export and


import, including player
data

AppStandard

Technical

API (methods are annotated

reading achievements is

with required role)

possible, but should be

API Terminal (send events for


testing purposes)

Write only - using rules;

avoided

Send player-related
events

Read player achieve


ments and available ach
ievements

Sample use cases:

Show aggregated gamifi


cation statistics in a host
application

Visualize specific leader


boards in a host applica
tion

AppAdmin

Technical

API (methods are annotated

Read and delete a player


record for a single app or

with required role)

for the whole tenant

Create and delete a user


or a team

634

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Role

Type

Access Level

Player (automatically as

Technical (implicit role)

API (methods are annotated

signed)

Description

Send player-related
events (only works for

with required role)

the user that is authenti


cated using the identity
provider which is config
ured for your account)

Note
This role is not a standard
SAP HANA Cloud Platform
role. It is automatically as
signed to a user (player)
that is created using the
gamification service and
cannot be explicitly as
signed to a SAP HANA
Cloud Platform user.

helpdesk

User

Demo App

Access to demo app


HelpDesk

1.4.5.4.1.1 Assigning Roles


Prerequisites
You have logged on to the SAP HANA Cloud Platform cockpit with your account user.

Procedure
1. In the SAP HANA Cloud Platform cockpit, choose the Services tab .
2. Go to Gamification Service.
3. In the Service Configuration panel choose Configure Gamification Service.
4. Choose the Roles section.
5. Assign role (GamificationDesigner or TenantOperator).

Related Information
Managing Roles [page 1282]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

635

1.4.5.4.2

Data Privacy

The SAP HANA Cloud Platform, gamification service meets the security and data privacy standards of the SAP
HANA Cloud Platform. In general, the gamification service is not responsible for any content such as game
mechanics or player achievements. It is the responsibility of the host application to meet any local data privacy
standards. Therefore, you need to make sure that the personal information of players is protected according to
the local regulations. In some cases where the gamification is applied to employee scenarios work council
approval for the gamified host application might be necessary.

1.4.5.5

Managing Apps

Prerequisites
You have the role TenantOperator, are logged into the gamification workbench, and have opened the
Administration tab.

Context
The gamification service introduces the concept of apps. An app represents a self-contained, isolated context for
defining and executing game mechanics such as points, levels, and rules.
All data or meta data associated with an app are stored in an isolated way. In addition to this, an isolated rule
engine instance is created and started for each app.

Note
Players are stored independently from apps and can therefore take part in multiple apps.

1.4.5.5.1

Configuring Apps

Prerequisites
You have the role TenantOperator, are logged into the gamification workbench, and have opened the
Administration tab.

Context
An app represents a self-contained, isolated context for defining and executing game mechanics.

636

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Creating Apps
Procedure
1. Enter an app name in the form area App Creation.
2. Optional: Enter an app description.
3. Optional: Enter an app owner.
4. Optional: Set the Auto-Create Players flag: if set to true, players are created automatically on first event.
5. Press Create to add a new app. The app should now appear in the app selection combo box in the upper right
corner of the gamification workbench.

Deleting Apps
Procedure
1. Select the app in the combo box of the form area App Management.
2. Press Delete.
3. Press Ok in the confirmation dialog.

1.4.5.5.2

Switching Apps

Prerequisites
You have the role GamificationDesigner or TenantOperator or both and are logged into the gamification
workbench.

Context
By switching the app, the gamification workbench only shows game mechanics and player achievements
associated with the selected app.

Procedure
1. Select an app in the app selection combo box located in the upper right corner of the gamification workbench.
2. Optional: Review whether the app has been changed successfully, for example by comparing the summary
page (tab Summary).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

637

1.4.5.5.3

Exporting Apps

Prerequisites
You have the role TenantOperator, are logged into the gamification workbench and have opened the
Administration tab.

Context
The gamification service allows exporting all available apps including their content. You can choose between a full
tenant export including all player data and an export of game mechanics only. The latter can be imported again.

Procedure
1. Select the Export mode in the combo box labeled Export in the form area Import / Export.
Full Export: export all game mechanics and player data.
Game Mechanics: export game mechanics only.
2. Press Download to start the export. Your browser should show the file storing dialog.
3. Store the provided ZIP file on your disk.

1.4.5.5.4

Importing Apps

Prerequisites
You have the role TenantOperator, are logged into the gamification workbench and have opened the
Administration tab.
You have a gamification service export file.

Note
See section Exporting Apps [page 638] for details.

Context
The gamification service allows importing game mechanics based on existing gamification service export files (ZIP
format). Section Exporting Apps explains how to do the export.

638

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Press Browse in the form area Import / Export to select the import file.
2. Press Upload to start the import based on the selected file.

Note
If an app with the same name already exists, the import will skip this app and does not overwrite its
content.
3. Apply rule changes to active rules again.

Note
See section Configuring Rules [page 652] for details.

1.4.5.5.5

Generating Demo Apps and Content

Prerequisites
You have the role TenantOperator, are logged into the gamification workbench, and have opened the
Administration tab.

Context
The gamification service is shipped with selected demo content comprising game mechanics as well as demo
players. The demo content is created within the context of a new app.

Procedure
1. Press Create HelpDesk Demo.
2. An app called in the same ways as the demo content should now appear in the app selection combo box in the
upper right corner of the gamification workbench.

Note
Appropriate content (points, levels, badges, and rules) is created for the app automatically.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

639

1.4.5.6

Configuring Game Mechanics

Prerequisites
You have the GamificationDesigner role , are logged on to the gamification workbench and have opened the
Game Mechanics tab.

Context
The gamification concept describes the metrics, achievements and rules that are applied to an application. The
following checklist describes the tasks required to implement your gamification concept in your subscription of
the gamification service.
1. Configuring Achievements:
Configuring Points (Point Categories) [page 641]
Configuring Levels [page 643]
Configuring Badges [page 645]
Configuring Missions [page 647]
2. Configuring and Managing Rules [page 652]

General Procedure
For each game mechanics entity there is a tab with a master and details view.
Master View
Shows the list of available entities.
Add button for adding a new entity.
Edit All button for switching to batch deletion mode.
Details View
Shows entity attributes and images.
Edit button for editing entity attributes.
Duplicate button for cloning the complete entity including attribute values.
Delete button for deleting the given entity.
Each entity has at least the attributes name and a display name. The name serves as the unique identifier and is
immutable.

640

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.1

Configuring Points (Point Categories)

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Points tab.

Context
Points are the fundamental element of a gamification design. For example, points can indicate the progress in
various dimensions. Points can be flagged as "Hidden from Player" for security or privacy reasons. Points that are
flagged as hidden are not visible to players. Instead they can be utilized in rules. Furthermore points can have
various different subtypes. The table lists the available point types.
Table 251: Point Types
Type

Description

ADVANCING

Advancing points are points that can never decrease. They are
used to reflect progress.

REPUTATION

Reputation points should be used within a predefined range.


For examplem, from -100 to 100.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

641

Type

Description

AUXILIARY

Auxiliary points can be used to define specific metrics and


should only be presented to the user within their context. For
example, auxiliary points can be used to track mission prog
ress.

OTHER

Any points that do not match a specific type.

Points can be configured in the Points subtab of the Game Mechanics tab.

1.4.5.6.1.1 Creating Points


Prerequisites
You have the GamificationDesigner role, are logged on to the gamification workbench and have opened the
Points tab.

Procedure
1. Press Add to add a new point category.
2. Enter a name, which serves as an unique identifier.
3. Optional: Enter a display name, which can be used to display the point to the player.
4. Enter an abbreviation which can be used to display the point to the player.
5. Select Point Type.
6. Optional: Select if the points are hidden from players.
7. Select if the point is the default point. There can only be one default point within one app.
8. Press Create.

1.4.5.6.1.2 Updating Points


Prerequisites
You have the GamificationDesigner role, are logged on to the gamification workbench and have opened the
Points tab

642

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Select the point category in the list to be updated.
2. Press Edit.
3. Change the values of the attributes that will be updated.
4. Press Save.

1.4.5.6.1.3 Deleting Points


Prerequisites
You have the GamificationDesigner role, are logged on to the gamification workbench and have opened the
Points tab

Procedure
1. Select the point category in the list to be deleted.
2. Press Delete.
3. Confirm deletion by pressing Confirm in the popup dialog.

1.4.5.6.2

Configuring Levels

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Levels tab.

Caution
Only levels that are based on the default point category are exposed to the default user profile.

Context
A level describes the status of a user once a specific goal is reached. The gamification service allows you to define
levels based on a defined point category. The threshold defines the value of the selected point type to reach the
level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

643

1.4.5.6.2.1 Creating Levels


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Levels tab.

Procedure
1. Press Add to add a new level.
2. Enter a name, which serves as an unique identifier.
3. Optional: Enter a display name, which can be used to display the level to the player.
4. Select the point category on which the level is based on. (The primary player levels are typically based on the
default point.)
5. Enter a point threshold. Reaching it will complete the level for the player.
6. Optional: Choose an inmage for the level.
7. Press Create.

1.4.5.6.2.2 Updating Levels


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Levels tab.

Context

Procedure
1. Select the level in the list to be updated.
2. Press Edit.
3. Change values of attributes that shall be updated.
4. If a level has an image check Delete Image checkbox to remove the image.
5. Press Save.

644

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.2.3 Deleting Levels


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Levels tab.

Procedure
1. Select the level in the list to be deleted.
2. Press Delete.
3. Confirm deletion by pressing Confirm in the popup dialog.

1.4.5.6.3

Configuring Badges

Prerequisites
You have logged onto the gamification workbench with the role GamificationDesigner and you have opened
the Badges tab.

Context
A badge is a graphical representation of an achievement. Hidden badges are not visible to the user before the
assignment and can be used as surprise achievements.

1.4.5.6.3.1 Creating Badges


Prerequisites
You have logged onto the gamification workbench with the role GamificationDesigner and you have opened
the Badges tab.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

645

Procedure
1. Press Add to add a new badge.
2. Enter a name, which serves as an unique identifier.
3. Optional: Enter a display name, which can be used to display the badge to the player.
4. Optional: Enter a description, which will hold information how to recieve this badge.
5. Choose an image for the badge.
6. Select if the badge is hidden from players.
7. Press Create.

1.4.5.6.3.2 Updating Badges


Prerequisites
You have logged onto the gamification workbench with the role GamificationDesigner and you have opened
the Badges tab.

Procedure
1. Select the badge in the list to be updated.
2. Press Edit.
3. Change values of attributes that shall be updated.
4. Press Save.

1.4.5.6.3.3 Deleting Badges


Prerequisites
You have logged onto the gamification workbench with the role GamificationDesigner and you have opened
the Badges tab.

Procedure
1. Select the badge in the list to be deleted.
2. Press Delete.

646

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Confirm deletion by pressing Confirm in the popup dialog.

1.4.5.6.4

Configuring Missions

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Missions tab.

Context
A mission defines what has to be achieved to gain a measurable outcome. Besides basic standalone missions the
gamification service allows modelling complex mission structures using mission conditions and consequences.

Note
Mission conditions and consequences are of descriptive nature only. Actual condition checking and the
execution of consequences has to be done by corresponding rules. These rules are not generated
automatically yet.
Sample structure of complex missions:

Currently two types of completion conditions are supported:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

647

A single point along with a threshold. This point can also be considered as a progress indicator: as soon as the
threshold is reached the condition is met.
A list of missions that have to be completed. Within the API such missions are referred to as sub missions.
The consequences part is limited to a list of follow-up missions, which should be assigned or unlocked after the
current mission has been completed. Within the API such follow-up missions are referred to as nextMissions.
Example for a rule that checks a point condition in its WHEN part and assigns a follow-up mission in its THEN part:
WHEN
$p : Player($playerid : id)
eval(queryAPIv1.hasPlayerMission($playerid, 'Troubleshooting', false) == true)
eval(queryAPIv1.getScoreForPlayer($playerid, 'Critical Tickets', null,
null).getAmount() >= 5)
THEN
updateAPIv1.completeMissionForPlayer($playerid, 'Troubleshooting', null);
updateAPIv1.assignMissionToPlayer($playerid, 'Troubleshooting reloaded', null);

1.4.5.6.4.1 Creating Missions


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Missions tab.

Procedure
1. Press Add to add a new mission.
2. Enter a name that will serve as a unique identifier.
3. Optional: Enter a display name, which can be used to display the mission to the player.
4. Enter a meaningful description, what is the mission about.
5. Optional: Select the point category that the mission is based on. This point category can be used to display
the mission progress.
6. Optional: Set the point threshold (condition) for the point, for example the amount of points required to
complete the mission.
7. Optional: Add required missions by pressing the Add button and selecting them in the pop-up window.
Required missions have to be completed as precondition for completing the given mission. In the API these
missions are referred to as sub missions.
8. Optional: Define follow-up missions by adding missions to the Assigns Missions section. In the API these
missions are referred to as next missions.
9. Press Create.

648

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
Note
Adding a sub mission or follow-up mission only creates relations in the database. The corresponding rules for
checking conditions, assigning follow up missions, or both are not generated yet. They have to be created
manually. But without storing these relationships and making them available through the achievement query
API it would not be possible to create such rules at all.

1.4.5.6.4.2 Updating Missions


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Missions tab.

Procedure
1. Select the mission in the list to be updated.
2. Press Edit.
3. Change the values of the attributes that shall be updated.
4. Press Save.

1.4.5.6.4.3 Deleting Missions


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Missions tab.

Procedure
1. Select the mission in the list to be deleted.
2. Press Delete.
3. Confirm deletion by pressing Confirm in the popup dialog.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

649

1.4.5.6.4.4 Controlling the Mission Life Cycle


Regarding the mission life cycle,there are two types of missions:
System Missions: the mission life cycle is fully controlled by the service using API calls within rules.
User-accepted Missions: the player actively decides whether to accept or reject missions, while the remaining
mission life cycle (unlocking or completing a mission) is controlled by the service. In both cases the API calls
have to be executed within rules to ensure data consistency between the engine and the backend.

System Missions

All state transitions are triggered by calling the respective API methods within rules, while the list of missions in a
certain state can be retrieved either by calling the API directly or within a rule.
Sample rule for assigning a system mission as part of the user init rule:
WHEN
$event : EventObject(type=='initPlayerForApp', $playerid : playerid) from entrypoint eventstream
THEN
updateAPIv1.assignMissionToPlayer($playerid, 'Troubleshooting', null);

650

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Sample rule for completing a system mission:


WHEN
$p : Player($playerid : id)
eval(queryAPIv1.hasPlayerMission($playerid, 'Troubleshooting', false) == true)
eval(queryAPIv1.getScoreForPlayer($playerid, 'Critical Tickets', null,
null).getAmount() >= 5)
THEN
updateAPIv1.completeMissionForPlayer($playerid, 'Troubleshooting', null);

User-accepted Missions

Flow for accepted missions


1. System via rule: unlockMissionForPlayer (allowing users to start missions)
2. User via API: getAvailableMissionsForPlayer (listing or offering missions for the user to pick from)
3. User via rule: acceptMissionForPlayer (accepting a specific mission)
4. (User progresses while having this set as active mission)
5. System via rule: completeMissionForPlayer (when all conditions are met, the rule completes the mission)
Flow for rejected missions
1. System via rule: unlockMissionForPlayer (allowing users to start missions)
2. User via API: getAvailableMissionsForPlayer (offering specific missions for the user to pick from)
3. User via rule: rejectMissionForPlayer (rejecting an available mission)
4. Mission is no longer available for the user and will not be offered again
5. (Optional) User via rule: unlockMissionForPlayer so that it can be offered or accepted again.
Implementing User Interactions

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

651

Create rules for the required interactions. Within these rules, introduce appropriate events that include the
mission name as property. Example:
WHEN
event : EventObject(type=='acceptMission', $playerid : playerid, $mission :
mission) from entry-point eventstream
THEN
updateAPIv1.acceptMissionForPlayer($playerid, $mission, null);
The host application requires an integration to be able to send these events to the service

1.4.5.6.5

Configuring and Managing Rules

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Context
The rules are a fundamental element of the game mechanics. They describe the consequences of actions, the
corresponding constraints and the goals that can be achieved. The rules allow you to define complex conditions
and consequences based on common complex event processing (CEP) operators.

Related Information
Rules Language [page 653]
http://docs.jboss.org/drools/release/5.6.0.Final/drools-expert-docs/html/ch05.html

1.4.5.6.5.1 Rules Design Principles


Rules are the core elements of the gamification design. Generally they follow the event condition action (ECA)
structure as for active rules in event driven architectures. Each rule is structured in two parts:
Left hand side (LHS): rule conditions or trigger (events conditions and/or player conditions)
Right hand side (RHS): rule consequences (updates from the player and/or event generation)
The rule conditions (LHS) are maintained in the Trigger (when) area. Examples are:

652

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Incoming event type - wait for event of type solvedProblem:


$event : EventObject(type=='solvedProblem', $playerid:playerid) from entry-point
eventstream
Conditions on event parameters - player has more than 10 Experience Points:
$event : EventObject(type=='solvedProblem', data['relevance']=='critical',
$playerid:playerid) from entry-point eventstream
Conditions on player achievements - player has more than 10 "Experience Points":
eval(queryAPI.getPointsForPlayer($playerid, 'Experience Points').getAmount() >
10)
The rule consequences (RHS) are maintained in the Consequences (then) area. Examples are:
Update achievements - Experience Points of the player are increased by 5:
updateAPI.givePoints($playerid, "Experience Points", 5, "Task done" );
update(engine.getPlayerById($playerid));
Create new events - new event with the type solvedProblemDelayed that is triggered with a delay of 1
minute:
EventObject obj = new EventObject();
obj.setType("solvedProblemDelayed");
obj.setEventDuration(60*1000);
obj.setPlayerid($playerid);
entryPoints["unmanagedstream"].insert(obj);

Note
The gamification service follows the rule-first approach. This means that any achievements of a player are
always updated using the rule engine. A modification of player achievements cannot be done using an API
(without any rule execution).

1.4.5.6.5.2 Rules Language


The SAP HANA Cloud Platform, gamification service allows you to write rules in order to reach the best flexibility
for the targeted game concept. Additionally you can write rules in one of the multiple graphical (form based)
editors in the gamification workbench.

1.4.5.6.5.2.1 Defining the Trigger (WHEN)


The declaration of the trigger (when) part is based on the Drools Rules Language (DRL).
The trigger part defines the constraints that must be fulfilled in order to execute the consequences ("then" part).
Variables can be defined and used both in the "when" and in the "then" part. This is generally recommended in
case you want to use the same object more than once. Multiple constraints can be described in one trigger part.
The constraints are typically described using the logical operators (within eval statements) and evaluation of the

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

653

event object. The event object must be defined with a type and can include multiple parameters. Additionally, DRL
allows you to define temporal constraints using common complex event processing (CEP) operators.

Related Information
http://docs.jboss.org/drools/release/5.6.0.Final/drools-expert-docs/html/ch05.html

1.4.5.6.5.2.1.1 Entry Points (Event Streams)


The gamification service rule engine allows the use of two event streams:
Managed event stream - eventstream: All events and user actions that are sent using the API will
automatically be sent using the managed event stream. Managed means that all events are retracted
automatically. Point-in-time events (duration=0) are retracted immediately after execution of the
corresponding rules while long-living events (duration >0) are retracted 1 second after they have expired. If
this automated event retraction is not suitable for your use case, you can use the unmanaged stream instead.
Unmanaged event stream - unmanagedstream: For this stream you have to take care of event retraction
yourself, which offers more flexibility with regards to rule design. For stability reasons, events sent to this
stream are retracted automatically after 28 days.
You have to explicitly declare in the trigger part which event stream will be used. Furthermore, you have to
explicitly declare in the consequences part which event stream is used in case you create new events. Using the
managed stream is strongly recommended. Only use the unmanaged stream if the auto-retraction does not work
with your rule design.

1.4.5.6.5.2.1.2 Variables
Context
Variables can be defined in the trigger part and can afterwards be used in both the trigger and the consequences
part. Variables are recommended in case one object is used more than once. For example, a player object needs
to be updated multiple times.

Procedure
A variable is declared by any string with a leading $ sign, for example $player or $var.
Declaration of a variable:
$<VARIABLE> : <EXPRESSION>

654

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Examples for variable declaration:


Binding of a variable for the player object.
$player : Player($playerid : uid)
Declaration of a variable for the event object.
$event : EventObject(type=="solvedProblem", $playerid:playerid) from entry-point
eventstream

1.4.5.6.5.2.1.3 Event Object with Type and Parameters


Context
An event type must be set for each incoming event. The event type needs to be checked within the trigger part.
The player's ID is sent with each event, it should be stored in a variable for further use.
Multiple parameters can be passed with an event and evaluated. The parameters can be a string or any numeric
values. The parameters can be evaluated with logical operators such as equal(=), larger than(>) and smaller
than(<).
Multiple evaluations of event objects can be triggered in one rule.

Procedure
Declaration of an event object with a given event type and declaration of a variable with a given player ID:
EventObject(type=='<EVENT_TYPE>', $playerid:playerid) from entry-point eventstream

Note
It is recommended to always assign the player ID (playerid) within the event object of a variable since the
player ID is necessary to get the according player object for updating achievements in the consequence part.
Declaration of an event with a given event type, declaration of a variable with a given player ID and evaluation of a
property:
EventObject(type=='<EVENT_TYPE>', data['<PROPERTY>']<OPERATOR><VALUE>
$playerid:playerid) from entry-point eventstream

Note
It is recommended to always evaluate event parameters within the event object instead of defining additional
parameters and using additional eval statements.
Examples for event declaration:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

655

Declaration of event with the given type solvedProblem.


EventObject(type=='solvedProblem', $playerid:playerid) from entry-point
eventstream
Declaration of event with the given type buttonPressed.
EventObject(type=='buttonPressed', $playerid:playerid) from entry-point
eventstream
Examples for an event with given properties:
Declaration of event with the given type solvedProblem and a property with the name relevance and the
value critical.
EventObject(type=='solvedProblem', data['relevance']=='critical',
$playerid:playerid) from entry-point eventstream
Declaration of event with the given type buttonPressed and a property with the name color and the value
red.
EventObject(type=='buttonPressed', data['color']=='red', $playerid:playerid)
from entry-point eventstream
Declaration of event with the given type temperatureIncreased and an integer property with the name
temperatureValue where the numeric value is larger than 30.
EventObject(type=='temperatureIncreased',
Integer.parseInt(data['temperatureValue'])>30, $playerid:playerid) from entrypoint eventstream
Examples for the combination of event declarations:
Declaration of two events of type ticketEventA and ticketEventB. Both events must occur and they have
to belong to different players.
EventObject(type=='ticketEventA', $playerid:playerid)
EventObject(type=='ticketEventB', playerid!=$playerid)
Declaration of two events of type ticketEventA and ticketEventB using the explicit and operator. Both
events must occur and they have to belong to different players.
(EventObject(type=='ticketEventA', $playerid:playerid) &&
EventObject(type=='ticketEventB', playerid!=$playerid))
Declaration of two events of type ticketEventA and ticketEventB using the or operator that describes
that eventA or eventB must occur and the "player IDs" must not be the same.
(EventObject(type=='ticketEventA', $playerid:playerid) ||
EventObject(type=='ticketEventB', playerid!=$playerid))
Declaration of two events of type ticketEvent where the player IDs are different and the ticked id is the
same and another event of the type connectedEvent that must not be true.
EventObject(type=='ticketEvent', $ticketid:data['ticketid'], $playerid:playerid)
EventObject(type=='ticketEvent', data['ticketid']==$ticketid, playerid!=
$playerid, $playerid2:playerid)
not(EventObject(type=='connectedEvent', playerid==$playerid, data['friendid']==
$playerid2))

656

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.5.2.1.4 Eval Statement


Context
Eval statements are used to define constraints with data that is not available in the working memory, such as
status of player achievements. Multiple constraints can be defined in one rule with the combination of multiple
logical operators.

Note
The code within eval statements must follow the Java syntax, just like in the case of the consequences ("then")
part. They are not based on the Drools Rule Language like the rest of the trigger part.

Note
It is recommended to avoid using an eval statement since it is an expensive operation. Use it as late as possible
within your trigger part.

Procedure
Declaration of an eval statement:
eval(<EXPRESSION><OPERATOR><VALUE>)
Expression: It is recommended to only use methods of the Query API in eval conditions. The use of the Query
API allows you to evaluate available player details and achievements using Java statements.
Operator: All logical operators supported by Java are supported.
Examples for eval statements:
Declaration of a eval statement where the mission Troubleshooting is assigned to the player.
(queryAPIv1.hasPlayerMission($playerid, 'Troubleshooting') == true
Declaration of a eval statement where the Experience Points of the player are larger or equal to 10.
eval(queryAPIv1. getScoreForPlayer($playerid, 'Experience Points ', null,
null).getAmount() >= 10)
Declaration of a eval statement where the player does not have the badge Sporting Ace assigned.
eval(queryAPIv1.hasPlayerBadge($playerid, 'Sporting Ace') == false)

Note
The use of an invalid expressions may lead to an error during rule execution. Make sure that referenced point
categories or missions exist and the spelling is correct.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

657

1.4.5.6.5.2.1.5 Temporal Constraints


The SAP HANA Cloud Platform, gamification service supports temporal reasoning as introduced with Drools
Fusion. Interval-based time event semantics and point-in-time events are supported. Supported temporal
operators for example are: after, before, coincides, during, finishes, and meets. For a full description of the use of
temporal operators see the related links.
Declaration of a temporal operator statement:
EventObject(this <OPERATOR> $<OTHER_EVENT>)

Note
In order to be able to use temporal constraints the event duration must be set for all temporal evaluated events
(that need to be kept in memory). The parameter in the request of the JSON params is eventDuration and
the according value is passed in milliseconds: "eventDuration":"3600"
Examples for temporal statements:
Declaration of a temporal constraint where event B solvedProblemB has to occur after event A
solvedProblemA.
$eventA:EventObject(type=='solvedProblemA', $playerid:playerid) from entry-point
eventstream
$eventB:EventObject(type=='solvedProblemB', this after $eventA) from entry-point
eventstream
Declaration of a temporal constraint where event B solvedProblemB has to occur before event A
solvedProblemA between 1 Minutes 30 Seconds and 5 Minutes.
$eventA:EventObject(type=='solvedProblemA', $playerid:playerid) from entry-point
eventstream
$eventB:EventObject(type=='solvedProblemB', this before[1m30s, 5m] $eventA) from
entry-point eventstream
Declaration of a temporal constraint where event B solvedProblemB happens during the occurrence of
event A solvedProblemA with a maximum distance of 1 minute.
$eventA:EventObject(type=='solvedProblemA', $playerid:playerid) from entry-point
eventstream
$eventB:EventObject(type=='solvedProblemB', this during[1m] $eventA) from entrypoint eventstream
Examples JSON request with event duration parameter:
An event that has a duration of 1 hour (3600 seconds) and therefore lasts 1 hour in the working memory.
{"id":0, "method":"handleEvent", "params":[{"type": "solvedProblem",
"playerid":"user@mail.com", "eventDuration":"3600", "data":
{ "relevance":"critical" }} ] }

658

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Links:
The Rules Language [jboss Droosl]: http://docs.jboss.org/drools/release/5.6.0.Final/drools-expert-docs/
html/ch05.html

1.4.5.6.5.2.1.6 Generic Facts


Creating generic facts (a Map object with an optional key) and storing them in the working memory is supported.
This allows you to store temporary results and create complex constraints (e.g.: count the number of a specific
event type). Generic facts can be evaluated in all rules as long as long as they exist.
The data structure of a generic fact is Map<String, Object> data. Additionally, you can set a key for the generic
fact in order to identify it. A generic fact has to be initialized in the consequences part.
In the trigger ("when") part you typically query certain facts from the memory using the following syntax:
GenericFact(key=='<KEY>')
Declaration of a variable with a generic fact value:
$<FACT_VARIABLE>: GenericFact(key=='<KEY>')
Examples for querying generic facts and assignment to a variable that can be used for evaluation:

$loginCounter: GenericFact(key=='LoginCounter')
Declaration of a generic fact loginCounter.

$daysOfWeek: GenericFact(key=='DaysOfWeek')
Declaration of a generic fact daysOfWeek.

1.4.5.6.5.2.2 Defining the Consequences ("THEN")


The declaration of the consequences (then) part supports writing code with the Drools Rules Language (DRL) in
version 5.6.0 and Java code.

Note
The formatting in the consequences part has to be in the Java style. The DRL can be used in combination with
Java code.
The consequences part defines what will be executed once the trigger part is fulfilled. It allows you to update the
player achievements or to create new events. Multiple consequences can be defined within one consequences
part.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

659

Related Information
http://docs.jboss.org/drools/release/5.6.0.Final/drools-expert-docs/html/ch05.html

1.4.5.6.5.2.2.1 Updating Player Achievements


The Update API can be used to update any player achievements. Multiple updated can be executed within on the
consequences part.
Declaration of an update on a player achievement:
updateAPIv1.<QUERY_API_METHOD>(<PLAYER_ID>, <PARAMS>);
update(engine.getPlayerById(<PLAYER_ID>));
The player ID has to be declared in the trigger part. Once all updates are executed the update method with the
player ID has to be executed once.
Examples for player achievement update declaration:
Increasing the Experience Points of the player by one.
updateAPIv1.givePoints($playerid, 'Experience Points', 1, 'Task completed.');
update(engine.getPlayerById($playerid));
Assign the mission Troubleshooting to the player.
updateAPIv1.addMissionToPlayer($playerid, 'Troubleshooting');
update(engine.getPlayerById($playerid));
Player completed the mission Troubleshooting.
updateAPIv1.completeMission($playerid, 'Troubleshooting');
update(engine.getPlayerById($playerid));
Assign the badge Champion Badge to the player.
updateAPIv1.addBadgeToPlayer($playerid, 'Champion Badge', '1. place');
update(engine.getPlayerById($playerid));
Examples for multiple player achievement update declaration:
Increasing the Experience Points of the player by one, complete mission Troubleshooting, and add badge
Champion Badge.
updateAPIv1.givePoints($playerid, 'Experience Points', 1, 'Task completed.');
updateAPIv1.completeMission ($playerid, 'Troubleshooting');
updateAPIv1.addBadgeToPlayer($playerid, 'Champion Badge', '1. place');
update(engine.getPlayerById($playerid));

660

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.5.2.2.2 Creating New Events


New events can be created in the consequences part. They can be used for more complex game mechanics
(cascading rules), changing the state of facts or even for temporal triggers.
Declaration of a new event:
The player ID has to be declared in the trigger part.
EventObject obj = new EventObject();
obj.setType(<TYPE>);
obj.setPlayerid(<PLAYER_ID>);
entryPoints["eventstream"].insert(obj);
Examples for creating new events:
New event of type solvedProblemCriticalTwice.
EventObject obj = new EventObject();
obj.setType("solvedProblemTwice");
obj.setPlayerid($playerid);
entryPoints["eventstream"].insert(obj);
New event of type solvedProblemCriticalTwice with a parameter relevance.
EventObject obj = new EventObject();
obj.setType("solvedProblemTwice");
obj.setPlayerid($playerid);
obj.put("relevance", "critical");
entryPoints["eventstream"].insert(obj);
Examples for creating new events which is executed delayed:
New event of type solvedProblemDelayed which is executed with a delay of 1 hour.
EventObject obj = new EventObject();
obj.setType("solvedProblemTwice");
obj.setPlayerid($playerid);
obj.setEventDuration(60 *60*1000);
entryPoints["eventstream"].insert(obj);

1.4.5.6.5.2.2.3 Working with Generic Facts (Storing Arbitrary


States)
Generic facts can be used as global variables and are stored in the working memory. The creation of a generic fact
instance has to be done in the consequences part. In the trigger part you can query for certain generic fact
instances and (if required) bind them to local variables. This works just like querying the EventObject.
Creation of a generic fact:
Creation of a generic fact with a given key.
GenericFact myFact = new GenericFact(<KEY>);
insert(myFact);
Examples for the creation of generic facts:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

661

Declaration of a generic fact with the key factA.


GenericFact factA = new GenericFact('factA');
insert(factA);
Declaration of a generic fact with the key factB with a property relevance and according value critical.
GenericFact factB = new GenericFact('factB');
factB.addData('relevance', 'critical');
insert(factB);
Reading a generic fact:
The generic fact variable has to be declared in the trigger part.
$<FACT_VARIABLE>.getData();
Examples for reading generic facts:
Assigning the value of the generic fact loginCounter to a variable.
int lCounter = $loginCounter.getData();
Assigning the data of the generic fact daysOfWeek to a variable of type HashMap.
HashMap<String,Object> hmDays = $daysOfWeek.getData();
Updating a generic fact:
The generic fact variable has to be declared in the trigger part.
$<FACT_VARIABLE>.setData(<VALUE>);
update($<FACT_VARIABLE>);
Examples for updating generic facts:
Assigning the value 59 to the generic fact loginCounter.
$loginCounter.setData("59");
update($loginCounter);
Assigning the value of the variable lCounter to the generic fact loginCounter.
$loginCounter.setData(lCounter);
update($loginCounter);
Deleting a generic fact:
The generic fact variable has to be declared in the trigger part.
retract($<FACT_VARIABLE>);
Examples for deleting generic facts:
retract($loginCounter);
Examples for querying or binding generic facts in WHEN-part:

662

$event : EventObject(type=='wpbStartChapter', $playerid:playerid,


$chapter:data['chapterId']) from entry-point eventstream

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

$p : Player($playerid == uid)
not GenericFact(key==$playerid,data['chapterId']==$chapter)

1.4.5.6.5.2.2.4 Advanced Consequences


Using Java code in the consequences part is allowed and very complex rules can be created. You can work with all
Java control flow statements, a selected set of Java objects, for example collections, create generic facts or
update the player's achievements.
Example code for advanced consequences:
Getting the day of the week.
java.text.SimpleDateFormat df = new java.text.SimpleDateFormat('d/MM/yy');
df.applyPattern("F");
java.util.Date _date = new Date();
int day=Integer.parseInt(df.format(_date));

1.4.5.6.5.3 Creating Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Procedure
1. Create a rule context.
a. Press Add in the rules entity list to add a new rule.
b. Enter a name.
c. Optional: Enter a display name.
d. Optional: Enter a description.
e. Optional: Enter the priority (Rules with lower number have higher priority.)
f. Press Create.
2. Enter the Rule logic (rules language).
a. Enter rule code for trigger in the Condition window. The trigger code describes when a rule shall become
valid.
b. Enter rule code in the Consequences window. The consequence code describes what shall happen once a
rule becomes valid.
c. Optional: Select Activate on Engine Update if the rule should become enabled after applying the rule
changes. (Value is selected by default.)
d. Press Save.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

663

e. Optional: Create or modify additional rules.

Caution
A newly created rule is not automatically deployed. The deployment is initiated once you apply the
changes. The rule must be activated in order to be deployed.

1.4.5.6.5.4 Defining Schedules for Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Context
Drools allows the specification of timer or scheduling constraints for rules using Java interval expression or cron
expressions. If the WHEN-part of such a rule is satisfied this results in a scheduled activation, which is put on the
Drools agenda. Unlike normal activations, these scheduled activations are not executed as part of a fireAllRules.
Instead, a scheduler executes these activations according to the specified timer or scheduling expression.

Note
As soon as the rule condition (WHEN-part) is not satisfied anymore, all scheduled activations are canceled. If
for instance a rule is triggered based on a certain event type, the scheduled activations are canceled as soon as
the corresponding event that activated the rule is retracted.

Procedure
1. Create a rule just as described in Creating Rules [page 663].
2. Open the rule details screen, switch to Edit mode and navigate to the Scheduling tab.
3. Use the radio buttons to select between Cron Job, Interval or Expression.
4. Define schedule or timer.
Cron Job: Specify a schedule based on a valid cron expression. A simple wizard appears that helps to
create simple expressions. For more advanced expressions: http://www.quartz-scheduler.org/
documentation/quartz-1.x/tutorials/crontrigger .
Interval: Use a Java interval expression. The first parameter specifies the initial delay. The second
parameter specifies the interval. For example:. "0 3m", "10h 10s", "3h". For more information refer to the
Drools language documentation .
Expression: Provide a valid Drools expression - either a delay in ms or a variable from the drools when
statement. The variable has to contain the delay in ms.

664

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.5.5 Enabling Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab. A rule already exists and is not enabled.

Procedure
1. Check the Activate on Engine Update checkbox of the rule you want to enable.
2. Open the Rule Engine Manager by pressing Rule Engine.
3. Commit your changes by pressing the Apply Changes button in the Rule Engine Manager. The rule will be
deployed immediately after successful validation. A blue flag next to the rule indicates that the rule has been
changed.

Note
A rule that contains errors will not be deployed. Errors can be viewed by pressing the Show Issues button in
the Rule Engine Manager.

1.4.5.6.5.6 Disabling Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab. A rule already exists and is enabled.

Procedure
1. Uncheck the Activate on Engine Update checkbox of the rule you want to disable.
2. Open the Rule Engine Manager by pressing Rule Engine.
3. Commit your changes by pressing the Apply Changes button in the Rule Engine Manager. The rule will be
deployed immediately once the validation was successful.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

665

1.4.5.6.5.7 Updating Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Procedure
1. Click on the name of the rule in the entity list to open the rule editor.
2. Change the rule code.
3. Press Save.
4. Optional: Create or modify additional rules.
5. Close the rule editor and apply changes to deploy the rules.

Caution
A modified rule is not automatically deployed. The deployment is initiated once you press Apply Changes in
the rules overview. The rule must be enabled in order to be deployed.

1.4.5.6.5.8 Deleting Rules


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Procedure
1. Select the rule in the entity list to be deleted.
2. Press Delete.
3. Confirm deletion by pressing Confirm in the popup dialog.

Caution
Only rules that are disabled can be deleted.

666

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.5.9 Error Detection for Rules (Design and Run Time)


Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Rules tab.

Context
The gamification workbench supports to detect issues with rules during design time and during runtime. Any
detected issues will be displayed in the Rules tab. Syntax errors are already checked during design time after the
user applied the changes.

Procedure
1. Open Rule Engine Manager by pressing on the Rule Engine button.
2. Press Show Issues.
3. Optional: Filter the rule with the issue in the upper list.
4. Select the according issue in the list of rule issues.

1.4.5.6.6

Using the Notification Mechanism

Notifications are messages that inform users about certain state changes, for example earned achievements, new
missions, new teams. They are considered "see and forget" information and won't stay long in the system.

Context
On one hand, notifications are created automatically when calling certain API methods. On the other hand, you
can also create and assign custom notifications by using the methods addCustomNotificationToPlayer and
addCustomNotificationToTeamMembers.
Notifications are delivered to players or teams by implementing a polling-based approach using the API methods
getNotificationsForPlayer and getAllNotifications.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

667

1.4.5.6.6.1 Automatic Notifications


The gamification service automatically creates notification for users when calling certain API methods. The table
below lists all methods, which implicitly generate notifications and explains the corresponding notification
parameters.
Table 252:
API Method

Player

Type

Category

Subject

Details

Message

Date Created

addBadgeTo

id

ADD

BADGE

Badge Name

custom

timestamp

givePoints

id

ADD

BADGE

Point Name

amount

custom

timestamp

addMission

id

ADD

MISSION

Mission

custom

timestamp

custom

timestamp

Player

ToPlayer
completeMis

Name
id

COMPLETE

MISSION

sion

Mission
Name

addPlayerTo

id

ADD

TEAM

Team Name

Player Name

custom

timestamp

id

REMOVE

TEAM

Team Name

Player Name

custom

timestamp

id

ADD

TEAMMIS

Mission

Team Name

custom

timestamp

SION

Name

TEAMMIS

Mission

Team Name

custom

timestamp

SION

Name

TEAM

Point Name

amount

custom

timestamp

Team
deletePlayer
FromTeam
addMission
ToTeam
complete

id

COMPLETE

TeamMission
givePointsTo id

ADD

Team

Custom messages can usually be specified using an optional parameter <notificationMessage> of the
corresponding API method.
Examples:

addBadgeToPlayer(String playerId, String badgeName, String <notificationMessage>)

givePointsToPlayer(String playerId, String pointType, double amount, String


<notificationMessage>)

668

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.6.2 Custom Notifications


Besides the automatically generated notification it is possible to add custom notifications to players or teams
using the methods addCustomNotificationToPlayer and addCustomNotificationToTeamMembers from
within rules.
The table explains how the notification parameters are used when creating custom notifications.
Table 253:
API Method

Player

Type

Category

Subject

Detail

Message

Date Created

addCustom

id

CUSTOM

Any

optional

custom

timestamp

id

CUSTOM

Any

optional

custom

timestamp

1[6%6$\id/w
ToPlayer
addCustom
1[6%6$\id/w
1[,%$6(Xi}
bers

1.4.5.6.6.3 Consuming Notifications


Context
Notifications are strictly defined as "see and forget". The gamification service will only store the last 25
notifications for each player (currently "X" defaults to 25). The show notifications to players a polling-based
approach has to be implemented using the following API methods:
getNotificationsForPlayer(playerId, timestamp)&app=APPNAME
Returns the latest notifications for a player starting from the timestamp. This mechanism allows other
applications to better track which notifications have been requested or displayed already. This is the current
approach for "user2service" communication. It works well with the user endpoint using JavaScript.
getAllNotifications(timestamp)&app=APPNAME
Returns all generated notifications for all players within one app starting from the provided timestamp. This is
the current approach for "application2service" communication. An application can query all notifications for
the app using the tech endpoint and forward the information to the user using custom events or
communication channels. This avoids having all clients in parallel polling for notifications.

Procedure
You can see the Notification Widget in the Helpdesk Scenario (sap_gs_notifications.js) for more information on
how the polling of notifications can be implemented at the client side. The notification polling is handled as follows:
1. Retrieve the gamification service server time on initialization, using the method getServerTime.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

669

2. Use this server time to initially poll for notifications.


For example getNotificationsForPlayer(playerId, servertime) or
getAllNotifications(servertime).
3. When new notifications are received from the service, replace the polling timestamp with the dateCreated
timestamp from the youngest notification received.
For example getNotificationsForPlayer(playerId, youngestNotificationDateCreated) or
getAllNotifications(youngestNotificationDateCreated).

1.4.5.6.7

Using the API Terminal

Prerequisites
You have logged into the gamification workbench and opened the API Terminal tab.
You have the role GamificationDesigner.

Context
The API Terminal within the game mechanics area allows you to quickly execute one or more API calls. Make sure
that you have the appropriate access rights for executing the call.
A comprehensive documentation of the API can be found in your SAP HANA Cloud Platform, gamification service
subscription under

Help

API Documentation .

Procedure
1. Enter the list of JSON RPC calls as a JSON array: [JSON_RPC_CALL1, JSON_RPC_CALL2,]
Example:
[{"method":"createMission", "id":1, "params":["missionname", "mission
description", "mission consequence"]},{"method":"createLevel", "id":1, "params":
["name","1","Experience Points"]}]
2. Press Execute to execute the calls. Check Force synchronous execution checkbox to enforce sequential
execution of calls in the JSON array.
3. Review server response. You can view the detailed JSON response by clicking on the symbol on the right.

Note
The calls are executed in the context of the currently selected app (see dropdown box in the upper right
corner of the gamification workbench). The defined JSON RPC calls are stored in the browser cache. For
restoring the initial sample calls press Restore Example.

670

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.6.7.1 Sending Player Events


Prerequisites
Open the API Terminal in the Game Mechanics tab. Your user has the role AppAdmin.

Context
The API Terminal allows you to send events that are typically sent to the host application.

Note
The API Terminal should be only used to send events for testing purposes. In case you send events for a user
that is used in a productive environment it will modify the real achievements!

Procedure
1. Enter the list of JSON RPC calls with the method handleEvent.
[ {"method":"handleEvent", "params":[{"type":"myEvent","playerid":"demouser@mail.com","data":{}}]} ]
2. Press Execute to execute the calls. Check Force synchronous execution checkbox to enforce sequential
execution of calls in a JSON array.
3. Review server response. You can view the detailed JSON response by clicking on the symbol on the right.
Once the event is send successfully the response is true.
4. All rules that listen on the according event type (when clause) will be executed.

1.4.5.6.7.2 Getting Player Achievements


Prerequisites
Open the API Terminal in the Game Mechanics tab.

Context
The API Terminal allows you to execute all methods for retrieving the user achievements data.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

671

Procedure
1. Enter list of JSON RPC calls with the method with the desired achievement query methods.
Example getPlayerRecord:
[ {"method":"getPlayerRecord","id":"99","params":["demo-user@mail.com"]} ]
2. Press Execute to execute the calls. Check Force synchronous execution checkbox to enforce sequential
execution of calls in a JSON array.
3. Review server response. You can view the detailed JSON response by clicking on the symbol on the right.
Once the event is send successfully you will see the result.

1.4.5.6.8

Using the Event Logging View

Prerequisites
You are logged into the gamification workbench and have opened the Logging tab.
You have the role TenantOperator.

Context
The logging view allows you to search the event log for the selected app. The event log includes all API calls related
to Event Submission as well as the corresponding API calls executed from within the rules, which were triggered
by the corresponding events.

Procedure
1. View event log for most recent entries, covering:
Event Submission API calls, for example handleEvent or applyChanges
All API calls executed within triggered rules
2. (Optional) Configure the filter for the event log. Supported filtering options:
Event Submission API calls, for example handleEvent or applyChanges
All API calls executed within triggered rules
3. (Optional) Press Go to update the event log using the specified filter.

672

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
The maximum retention time for the event log is 7 days, but not exceeding 500,000 log entries.

1.4.5.7

Integrating Gamification Service into a Target


Application

Context
The integration of a (gamified) cloud application must consider the following aspects:
1. Sending gamification-relevant events to a player or a team, for example the user has completed a task for
which the gamification service grants a point.
2. Giving feedback to the players/teams, for example by showing achievements, progress, and game
notifications, .
3. Integrating the user management - creating or enabling players/teams, blocking players/teams, deleting
players/teams.
The following sections describe how you can deal with these aspects using the Web APIs provided. The sample
code shown is based on the demo application "Help Desk". The demo application's source code is also available in
GitHub .

Note
The sample code used to demonstrate the integration is not ready for production.

1.4.5.7.1

Gamification Service API

The Application Programming Interface (API) of the gamification service is the central integration point of your
application.
The gamification service API comprises two endpoints:
Technical endpoint for integrating gamification events and user management in the back end.
User endpoint for integrating user achievements in the application front end.
It is recommended to use the technical endpoint only for executing methods of the gamification service that must
not be executed by the users themselves, such as sending events to the gamification service that trigger certain
achievements or performing user management tasks, creating players for example. Authentication and
authorization in this case is based on a technical user that is created for the application itself.
The user endpoint should be used for accessing user related information for example earned achievements,
available achievements/mission, notifications and others. A great advantage of this approach is that the
gamification service manages access control, based on the user roles. For instance to make sure that a user
cannot access other users' data. For this, the authenticated user has to be passed to the user endpoint.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

673

Note
The whole integration can be done by using only the technical endpoint. However, in this case you have to
manage access control yourself..
The documentation for the API can be found in your gamification service under Help API Documentation
at https://gamification.hana.ondemand.com/gamification/documentation/documentation.html.

1.4.5.7.2

or

Integration Architecture Overview

The graphic below illustrates how a gamified application (gamified app) running on SAP HANA Cloud Platform is
typically integrated with the gamification service. The demo application "Help Desk" follows this integration
architecture:

In a SAP HANA Cloud Platform setting we assume that the gamified app and the gamification service subscription
are located in the same account. Furthermore, we assume that the application back end is written in Java, while
the application front end is based on HTML5 or SAP UI5.
The technical endpoint is used to send gamification-relevant events and perform user management tasks from
the application back end. Communication is based on a BASIC AUTH destination that uses the user name and
password of a technical user.
The easiest way to show player achievements is to integrate a default user profile that comes with the
gamification service subscription as an iFrame in the application's web front end.
To implement a user profile or single widgets (for example a progress bar tailored to the application's front end),
we recommend you use the user endpoint in combination with a local proxy servlet and an app-to-app SSO
destination. The proxy servlet prevents running into cross-site scripting issues and the app-to-app SSO
destination automatically forwards the credentials of the authenticated user to the gamification service. This
allows reuse of the access control mechanisms offered by the gamification service.

674

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Since the user endpoint is used from a browser it is protected against cross-site request forgery. Accordingly, an
XSRF token has to be acquired by the client first.

Related Information
Exchanging Data via HTTP Protocol [page 319]
Application-to-Application SSO Authentication [page 332]
Security Development [page 1212]

1.4.5.7.3

Sending Gamification Events

Context
If the user performs actions in the application that are relevant to gamification, the gamification service has to be
informed by invoking the corresponding API method. To prevent cheating this should be done in the application
back end using the technical endpoint offered by the API.

Procedure
1. Create a destination to the technical endpoint
a. Type: HTTP.
b. URL: https://<Subscription URL>/gamification/api/tech/JsonRPC .
c. Authentication: Basic Authentication.
d. User: Technical user ID. The technical user must have roles AppStandard and AppAdmin.
e. Password: The technical user's password.
2. Invoke method "handleEvent" in the appropriate place in the back end, for example after user action has been
executed.
http:// <Subscription URL>/gamification/api/tech/JsonRPC?
json={"method":"handleEvent","id":1,"params":
[{"siteId":"HelpDesk","type":"solvedProblem","playerid":"abc@abc.com"}]}

Note
See also:
Demo application source code: https://github.com/SAP/gamification-demo-app
API Documentation: SAP HANA Cloud Platform, gamification service subscription, under

Help

API

Documentation .

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

675

Related Information
Exchanging Data via HTTP Protocol [page 319]

1.4.5.7.4

Including the Default User Profile

Context
The gamification service subscription includes a default user profile, which you can include in your application as
an iFrame.

676

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

677

Procedure
1. See the default user profile using the following URL:
https://<Subscription URL>/gamification/userprofile.html?name=<userid>&app=<appid>
2. Include the default user profile in your HTML5 code as an iFrame:
<iframe src="https://<Subscription URL>/gamification/ userprofile.html?
name=<userid>&amp;app=<appid>" width="100%" height="100%"
frameborder="0" data-sap-ui-preserve="iframeProfile"
id="iframeProfile">Alternate text if the iframe cannot be rendered</iframe>

1.4.5.7.5

Integrating Custom Widgets

Prerequisites
Configure your account to allow principal propagation. For more information, see HTTP Destinations [page 322]

Context
The integration of custom gamification elements tailored to your application's user interface requires the
development of custom JavaScript/HTML5 widgets. To avoid cross-site-scripting issues, you should introduce a
proxy servlet in the application. This servlet forwards JSON-RPC requests to the user endpoint using an App-toApp SSO destination. This way, the gamification service has access to the user principle and the built-in access
control is active.

Procedure
1. Configure your account to allow principal propagation.
2. Create a destination to user endpoint.
a. Type: HTTP.
b. URL: https://<Subscription URL>/gamification/api/tech/JsonRPC .
c. Authentication: AppToAppSSO.
3. Include a proxy servlet that receives JSON-RPC strings and forwards them to the user endpoint using the
previously created destination. Refer to the API documentation for a list of available methods.
4. Include a JavaScript/HTML5 widget that sends JSON-RPC requests to the proxy servlet.
API Documentation: SAP HANA Cloud Platform, gamification service subscription under

Help

API

Documentation .
Demo application source code: https://github.com/SAP/gamification-demo-app

678

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Application-to-Application SSO Authentication [page 332]
Protecting from Cross-Site Request Forgery [page 1235]

1.4.5.7.6

Integrating Player (User) Management

Context
The players (users) must be explicitly created before they can be used to assign achievements. A player context is
always valid for one tenant and therefore can be used across multiple apps (managed in one tenant).

Procedure
1. Register (create) a player (user) for a tenant subscription using the API method createPlayer.

Note
This is done automatically on the first event if the flag Auto-Create Players is set to true for the given app.
2. (Optional) Initialize a player (user) by creating a rule listening for an event of type initPlayerForApp.
a. Precondition: The player is registered.
b. On event: if a player has not been initialized for the given app yet an event of type initPlayerForApp is
automatically inserted into the engine. The THEN-part of this rule should include the user-defined init
actions, for example assigning initial missions.
c. (Optional) If you want players to be created with a display name you can add the optional parameter
playerName to the event. During the automated player creation this parameter is used for setting the
player name. Example:
{"method":"handleEvent","params":
[{"type":"linkProvided","playerid":"maria.rossi@sap.com", "playerName":
"Maria Rossi", "data":{}}]}
3. Submit any events using the API method handleEvent.
a. Precondition: The player is registered. Otherwise the call is rejected.
b. According rules are triggered.
4. Optional: Remove a player from the app using the event removePlayerFromApp.
a. Precondition: The player is registered and has been initialized (if necessary).
b. The event has to be triggered explicitly by the host application.
c. A rule has to be provided that removes the player fact and performs all further scenario-specific clean-up
actions.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

679

Sample minimal clean-up rule:


WHEN-Part: Select user fact based on id provided with removePlayerForApp event
$event : EventObject(type=='removePlayerFromApp', $playerid:playerid)
from entry-point eventstream
$p : Player(id==$playerid)
THEN-Part: Retract the given player fact
retract($p);
5. Delete player (user) for tenant subscription using the API method deletePlayer.

680

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.8

Analyzing Gamification Concepts

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Game Mechanics tab.

Context
The gamification introduction is a continuous process since the modification of game mechanics can be done at
any point in time. For example, the number of points a player can reach might be changed in order to change the
behavior of the user.
The analytics can be executed in the Analytics tab.

1.4.5.8.1

Viewing Statistics of Points Metric

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Analytics tab.

Context
You can view the statistics of achievements such as points and badges. The points metrics that can be viewed are
all point categories and badges that are maintained for your application.
The following aggregations can be selected (the values for badges cannot be aggregated):
Max - The maximum of the selected values.
Sum - The sum of the selected values.
Avg - The average of the selected values.
Count - The number of occurrences of the selected values.
The values can be grouped by time or other values:
Day - Group by day.
Month - Group by month.
Year - Group by year.
Team - Group by team.
Badge - Group by badge.
Level - Group by level of players.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

681

The data can be filtered for a user defined time range (if no time range is selected, all data is displayed):
From - The minimum value of the time range.
To - The maximum value of the time range.
The selected values will be displayed as a bar chart.

Note
The analytics are currently limited to point categories and badges. Analytics on player level are not available
due to privacy reasons.

Procedure
View statistics for a point metric:
1. Select the points metric.
2. Optional: Select the aggregation.
3. Optional: Select the group by filter.
4. Optional: Check the Time range checkbox.
5. Optional: Select the time range (from / to) in case you have selected the Time range checkbox.

1.4.5.8.2

Viewing Difference in Values to Earlier Time Range

Prerequisites
You have logged on to the gamification workbench with the role GamificationDesigner and you have opened
the Analytics tab. You have selected the statistics you are interested in. A time range must be selected.

Context
You can view the statistics of achievements such as points and badges. The selected values can be compared to
an earlier time range in order to identify changes in the assignment of achievements.

Note
A time range for the statistics must be selected.

682

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
View a lag chart for a comparison of the selected data to an earlier time range.
1. Select the Enable lag chart checkbox.
2. Select the lag amount for comparison.
The lag chart displays the difference of the aggregated values to the values before the lag amount. For
example, when you select the sum of point category for the current month, the lag chart will show the
difference compared to the month before, provided you have selected a lag amount equal to one month.

1.4.5.9

Case Study: Gamified Help Desk Application

In this case study, a demo application will be gamified in order to demonstrate the implementation and
configuration of a gamification concept step by step.
The demo host application is a Help Desk software, which is typically used by call center employees. Customers
can create tickets (for an issue with software or hardware, for example) and call center employees can process
these tickets.

The image below shows the welcome screen of the Help Desk application. The welcome screen appears once the
user is successfully authenticated using the identity provided. The user must have the role helpdesk. The
assignment of roles is described in page Roles [page 630].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

683

Once the user is logged on, an overview of the open tickets is displayed on the left side (see the picture below).
The user can select a ticket and process it by entering comments. No further actions are necessary in the demo
application. Once the user has entered an appropriate response, the user can click Send Answer to process the
ticket.

684

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The demo application already includes a gamification implementation.

1.4.5.9.1

HelpDesk App - Configuration of Available


Subscription

Context
The demo application (Help Desk) will be automatically subscribed for each account that is subscribed to the
gamification service.
The gamification service has already been integrated within the demo application. Events such as the processing
of tickets will be sent to the gamification service of the account subscription for example, and the achievements
are going to be retrieved by the corresponding interfaces.
Since the gamification service and the demo applications are subscriptions, a destination has to be enabled in
order to allow communication between the services. A technical user is also required in order to allow secure
communication.

Procedure
The Help Desk app can be accessed via the menu Help Open Help Desk . The following link will be used:
https://< SUBSCRIPTION_URL>/helpdesk. The role helpdesk must be granted to the user.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

685

1.4.5.9.1.1 Assign Help Desk Role


Context
The user requires the role helpdesk in order to access the help desk application.

Procedure
1. Go to the Services tab in your SAP HANA Cloud Platform cockpit account.
2. Click the Gamification Service tile.
3. Click on the Configure Gamification Service link.
4. Go to the Roles tab.
5. Assign the role helpdesk to your user.

Related Information
Managing Roles [page 1282]
Assign Gamification Roles [page 617]

1.4.5.9.1.2 Create Technical User


The destination requires a technical user for secure communication between your application and the
gamification service subscription.

Context

Note
You can request user IDs at the SAP Service Marketplace: http://service.sap.com/request-user
SAP
Service Marketplace users are automatically registered with the SAP ID service, which controls user access to
SAP HANA Cloud Platform.

686

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Request a technical user via SMP. (You can use your account user as well, but this is not recommended for
security reasons.)
2. In the SAP HANA Cloud Platform cockpit, choose the Services tab.
3. Click the Gamification Service tile.
4. Click on the Configure Gamification Service link.

5. Go to the Roles tab.


6. Assign the AppAdmin role.

Related Information
Managing Roles [page 1282]

1.4.5.9.2

HelpDesk App - Standalone Deployment

Prerequisites
You have an Eclipse IDE with SAP HANA Cloud Platform tools.
For more information about how to install the SAP HANA Cloud Platform tools, see Eclipse Tools [page 86].

Context
The demo application's (Help Desk) source code is also available in GitHub

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

687

This section explains how to set up an Eclipse project, deploy the demo application on SAP HANA Cloud Platform,
and configure it to run with your gamification service subscription.

Procedure
1. Download sources as a zip from GitHub

2. Extract the archive.


3. Open Eclipse with SAP HANA Cloud Platform tools and choose
4. Choose

688

Maven

File

Import .

Existing Maven Projects .

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Choose the folder containing the demo application sources and choose Finish.
6. Deploy and start the demo application on the cloud from Eclipse IDE. Select Java Web as a Runtime.
For more information, see Deploying on the Cloud from Eclipse IDE [page 977].
7. Configure destinations and roles for the deployed application. Use the same configuration as described in
section HelpDesk App - Configuration of Available Subscription [page 685].

1.4.5.9.3

Gamification Design

The host application without the application does not allow the user (call center employee) to see any feedback on
his/her daily work. The user does not really know how s/he performs compared to other colleagues either.
The requirement for gamification in the demo applications is to intrinsically motivate the users with instant
feedback (achievements). Collaborative feedback will be introduced, and the progress for each individual user will
be visible as well as the performance compared to others.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

689

In order to meet the introduced gamification requirements, an example gamification design is introduced. All
users (call center employees) are considered as players where the gamification concept will apply.

Points Categories
Points are introduced to represent the experience of the users:
Experience Points (XP)
Critical Tickets (CT)

Levels
Based on the number of experience points a user gains, s/he can reach different levels. Three levels are
introduced:
Novice - this level can be reached already with 0 Experience Points
Competent - this level can be reached once the user has gained 10 Experience Points
Expert - this level can be reached once the user has gained 50 Experience Points

Badges
Based on the successful completion of a mission, the user will gain a badge. The following badges are introduced:
Troubleshooting Champion

Missions
Missions will be introduced to motivate continuous efforts. The following missions will be introduced:
Troubleshooting

Rules
For each processed ticket, the user will gain 1 Experience point.
For each processed ticket categorized as critical, the user will gain 2 additional Experience Points in order to
motivate him/her to solve critical tickets with higher priority.
For each processed ticket categorized as critical, the user will gain 1 Critical Tickets point.

690

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Once a user has processed 5 critical tickets (gained 5 Critical Tickets points), the Troubleshooting mission is
completed.
Once the mission troubleshooting is completed, the user will gain the Troubleshooting Champion badge.

1.4.5.9.4

Gamification Concept Content Generation

The gamification concept introduced above can be generated automatically within the gamificationworkbench.
The generated gamification concept is designed for the demo application only and is designed to provide an
example of a gamification concept.
The demo content for the Help Desk application can be generated in the Administration tab. You need to have the
TenantOperator role. Go to "Demo Content Creation" (shown in the picture below), select HelpDesk and click on
Create. Once the content has been generated successfully, you will see the following a notification: Gamification
concept successfully created. The app does not need to be created in App Creation. The app will be created
automatically during generation of the content.

1.4.5.9.5

Gamification Concept Manual Implementation

The following sections describe how the gamification design is implemented in the gamification workbench.

1.4.5.9.5.1 Create Application


The gamification workbench makes it possible to manage gamification concepts for multiple apps. An app must
be created before the gamification concept can be implemented.

Procedure
1. Go to the Administration tab. The user must have the TenantOperator role.
2. Go to App Creation:
3. Enter App name: HelpDesk.
4. Enter App description: HelpDesk Demo App.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

691

5. Enter owner: <Name>.


6. Click on Create.

Next Steps
Once the app has been created, it must be selected in the top right corner so that the gamification concept can be
implemented for it.

1.4.5.9.5.2 Create Point Categories

Procedure
1. Go to Game Mechanics in the navigation menu and select Points.
2. Press Add.
3. Enter Name: Experience Points.
4. Enter Abbreviation: XP.
5. Select point type: ADVANCING.
6. Press Create.

692

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

7. Press Add.
8. Enter Name: Critical Tickets.
9. Enter Abbreviation: CT.
10. Select point type: ADVANCING.
11. Check Hidden from Player
12. Press Create.

Results
You should now see both point categories (Experience Points and Critical Tickets) in the list for Points.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

693

1.4.5.9.5.3 Create Levels


Procedure
1. Go to Game Mechanics in the navigation menu and select Levels.
2. Press Add.
3. Enter Name: Novice.
4. Select Points: Experience Points.
5. Enter Threshold: 0.
6. Press Create.

7. Press Add.
8. Enter Name: Competent.
9. Select Points: Experience Points.
10. Enter Threshold: 10.
11. Press Add.

694

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

12. Press Add.


13. Enter Name: Expert.
14. Select Points: Experience Points.
15. Enter Threshold: 50.
16. Press Create.

Results
You should now see all three levels (Novice, Competent, and Expert) in the list for Levels.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

695

1.4.5.9.5.4 Create Badges


Procedure
1. Go to Game Mechanics in the navigation menu and select Badges.
2. Press Add
3. Choose file for upload: Troubleshooting_Chamption.png.

4. Enter Name: Troubleshooting Champion.


5. Enter Description: Solve 5 critical problems.
6. Press Create.

696

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
You should now see all badges (Troubleshooting Champion) in the list for Badges.

1.4.5.9.5.5 Create Missions


Procedure
1. Go to Game Mechanics in the navigation menu and select Missions.
2. Press Add.
3. Enter Name: Troubleshooting.
4. Enter Description: Solve five critical tickets..
5. Enter Consequence: Troubleshooting Champion.
6. Select Point Category: Critical Tickets.
7. Enter Lower bound: 1.
8. Enter Upper bound: 5.
9. Press Create.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

697

Results
You should now see all missions (Troubleshooting) in the list for Missions.

698

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.5.9.5.6 Create Rules

Context
In order to create rules, you have to perform the following activities:
Give Experience Points [page 699]
Give Experience Points for a Critical Mission [page 700]
Give Critical Ticket Points [page 700]
Assign Troubleshooting Mission [page 701]
Complete Troubleshooting Mission [page 701]

1.4.5.9.5.6.1 Give Experience Points

Procedure
1. Go to Game Mechanics in the navigation menu and select Rules.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

699

2. Go to All Rules in the sub navigation.


3. Press Add.
4. Enter Name: GiveXP
5. Enter Description: Give Experience Points for processed ticket.
6. Enter the following text for the trigger:
$event : EventObject(type=='solvedProblem', $playerid:playerid) from entry-point
eventstream
7. Enter the following text for the consequence:
updateAPI.givePoints($playerid, 'Experience Points', 1, 'Ticket processed');
update(engine.getPlayerById($playerid));
8. Press Save. The Activate on Engine Update checkbox must be checked.

1.4.5.9.5.6.2 Give Experience Points for a Critical Mission


Procedure
1. Press Add.
2. Enter Name: GiveXPCritical
3. Enter Description: Give additional Experience Points for critical ticket.
4. Enter the following text for the trigger:
$event : EventObject(type=='solvedProblem', data['relevance']=='critical',
$playerid:playerid) from entry-point eventstream
5. Enter the following text for the result:
updateAPI.givePoints($playerid, 'Experience Points', 2, 'Critical ticket
processed');
update(engine.getPlayerById($playerid));
6. Press Save. The Activate on Engine Update checkbox must be checked.

1.4.5.9.5.6.3 Give Critical Ticket Points


Procedure
1. Press Add.
2. Enter Name: GiveCT
3. Enter Description: Give Critical Ticket Points for processed ticket.

700

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Enter the following text for the trigger:


$event : EventObject(type=='solvedProblem', $playerid:playerid) from entry-point
eventstream
5. Enter the following text for the consequence:
updateAPI.givePoints($playerid, 'Critical Tickets', 1, 'Critical ticket
processed');
update(engine.getPlayerById($playerid));
6. Press Save. The Activate on Engine Update checkbox must be checked.

1.4.5.9.5.6.4 Assign Troubleshooting Mission


Procedure
1. Press Add.
2. Enter Name: AssignMissionTS
3. Enter Description: Assign Troubleshooting mission.
4. Enter the following text for the trigger:
$p : Player($playerid : uid)
$event : EventObject(type=='initPlayerForApp', $playerid==playerid) from entrypoint eventstream
5. Enter the following text for the consequence:
updateAPI.addMissionToPlayer($playerid, 'Troubleshooting');
update($p);
6. Press Save. The Activate on Engine Update checkbox must be checked.

1.4.5.9.5.6.5 Complete Troubleshooting Mission


Procedure
1. Press Add.
2. Enter Name: CompleteMissionTS
3. Enter Description: Complete Troubleshooting Mission.
4. Enter the following text for the trigger:
$p : Player($playerid : uid);
eval(queryAPI.hasPlayerMission($playerid, 'Troubleshooting') == true)
eval(queryAPI.getPointsForPlayer($playerid, 'Critical Tickets').getAmount() >= 5)
5. Enter the following text for the consequence:
updateAPI.completeMission($playerid, 'Troubleshooting');

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

701

updateAPI.addBadgeToPlayer($playerid, 'Troubleshooting Champion', 'You solved 5


critical tickets!');
update($p);
6. Press Save. The Activate on Engine Update checkbox must be checked.

1.4.5.9.5.6.6 Result
You should now see the created rules in the list for Rules.

Deploy and Activate Rules


7. Press Rule Engine to open Rule Engine Manager.
8. Press Apply Changes.

Results
All rules are shown as active without any issue warnings.

702

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.6 Monitoring Service


You can use the monitoring service to receive the metrics of your Java applications running on SAP HANA Cloud
Platform.

Overview
You can develop a custom application to request the states or the metric details of your Java applications and the
applications' processes. That is accomplished via GET REST API calls. For more information about the format of
the REST APIs, see Monitoring API.

Example
Use the following request to receive all the metrics of a Java application located in the European data center
(with hana.ondemand.com host):
https://api.hana.ondemand.com/monitoring/v1/accounts/<account_name>/apps/
<application_name>/metrics

Default Metrics of a Java Application


All Java applications include these default metrics. Custom metrics can also be added to the default metrics.
Table 254:
Metric

Value

Used Disc Space

Percentage of the whole disc space currently used.

Requests per Minute

Number of HTTP requests processed by the Java application


during the last minute.

CPU Load

Average percentage CPU usage during the last minute.

Disk I/O

Number of bytes per second currently being read or written to


the disc.

OS Memory Usage

Percentage of the operating system memory currently used.

Heap Memory Usage

Percentage of the heap memory currently used.

Average Response Time

Average response time in milliseconds for all requests proc


essed during the last minute.

Busy Threads

Current number of threads that are processing HTTP re


quests.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

703

Benefits
You can use the monitoring service for the following actions:
To implement elastic scaling for your Java applications.
For more information, see Elastic Scaling on HCP - How to create a simple Automatic Application Scaler on
HANA Cloud Platform
To retrieve and show the metrics of many Java applications located on different accounts and in different data
centers.
For more information, see Use the Monitoring Service to Retrieve Metrics from Different HCP Applications .
To be notified of all critical metrics of many Java applications via e-mail, SMS, or another channel.
For more information, see Use the Monitoring Service for Critical Notifications and Self-Healing of HCP Java
Applications .
To take actions for application self-healing when critical metrics are received.
This operation is accomplished with the help of a lifecycle API. For more information, see Use the Monitoring
Service for Critical Notifications and Self-Healing of HCP Java Applications .

Process Flow

1. A custom application requests metrics of a Java application from the monitoring service via a REST API call.
2. The monitoring service sends back a JSON response with a status code 200 OK.

704

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The format of the REST API request specifies the metrics to be returned in the JSON response. For more
information about the requests, see Monitoring API.
3. The custom application uses these metrics to perform operations.
4. The custom application requests the metrics of other Java applications by repeating steps 1 to 3.

Related Information
Lifecycle API documentation
Structure of a Monitoring Service Response [page 705]
Tutorial: Implementing a Dashboard Application [page 708]
Tutorial: Implementing a Notification Application [page 712]
Monitoring Java Applications [page 1149]

1.4.6.1

Structure of a Monitoring Service Response

You retrieve Java application metrics in a JSON format by performing a REST API request defined by the
monitoring API.

Note
The easiest way to view the metrics is to enter the request URI in your browser. You may be asked to provide
your credentials before the retrieval process is performed. You can then use any JSON prettifier or formatter to
improve the readability of the results.
Table 255: JSON Response Parameters
Parameter

Value

account

The name of the account as a string

application

The name of the application as a string

state

"OK", "WARNING" (not used for a status metric), or


"CRITICAL"
This parameter is used to specify the state of the application,
metric, or process.

processes

A list of processes. Each process contains the process ID, the


state of the process, and the list of the metrics for that proc
ess.

process

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The process ID as a string

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

705

Parameter

Value

metrics

A list of metrics. Each metric contains the following parame


ters:

name

The name of the metric as a string

value

The metric value as an integer

unit

The unit for the value as a string

warningThreshold

The warning threshold or the lower threshold as an integer

errorThreshold

The critical threshold or the upper threshold as an integer

timestamp

The time in milliseconds from January 1, 1970 to this call as a


positive integer

output

A summary of the metric as a string

min

The minimum value as an integer.

max

The maximum value as an integer.

metricType

"status", "performance", or "rate"


The state of each type of metric is determined based on the
following metrics:

status metric - "OK" or "CRITCAL" state of the metric is


returned directly.

performance metric - the returned value is compared


with the predefined warning and critical thresholds. Val
ues less than the warning threshold result in an "OK"
state, values between the warning and the critical thresh
olds result in a "WARNING" state, and values greater than
the critical threshold are considered as "CRITICAL".

rate metric - similar to the performance metric, but the


returned value is calculated as a percent using the mini
mum and maximum values and compared with the warn
ing and critical thresholds.

Example
The JSON response for Java application metrics may look like the following example:
[

706

"account": "myAccount",
"application": "hello",
"state": "Ok",
"processes": [
{

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"process": "bf061f611cc520f39839f2fa9e44813b2a20cdb7",
"state": "Ok",
"metrics": [
{
"name": "Used Disc Space",
"state": "Ok",
"value": 43,
"unit": "%",
"warningThreshold": 90,
"errorThreshold": 95,
"timestamp": 1456408611000,
"output": "DISK OK - free space: / 4177 MB (54% inode=84%); /
var 1417 MB (74% inode=98%); /tmp 1845 MB (96% inode=99%);",
"metricType": "rate",
"min": 0,
"max": 8063
},
{
"name": "Requests per Minute",
"state": "Ok",
"value": 0,
"unit": "requests",
"warningThreshold": 0,
"errorThreshold": 0,
"timestamp": 1456408611000,
"output": "JMX OK - RequestsCountMin = 0 ",
"metricType": "performance",
"min": 0,
"max": 0
},
{
"name": "CPU Load",
"state": "Ok",
"value": 2,
"unit": "%",
"warningThreshold": 80,
"errorThreshold": 90,
"timestamp": 1456408611000,
"output": "OK CPUValue: 2 (W> 80, C> 90) ",
"metricType": "performance",
"min": 0,
"max": 0
},
{
"name": "Disk I/O",
"state": "Ok",
"value": 36386,
"unit": "B/s",
"warningThreshold": 1.0E7,
"errorThreshold": 1.5E7,
"timestamp": 1456408611000,
"output": "OK: DiskRead: 0 B/s (W> 10000000, C> 15000000)
DiskWrite: 36386 B/s (W> 10000000, C> 15000000)",
"metricType": "performance",
"min": 0,
"max": 0
},
{
"name": "OS Memory Usage",
"state": "Ok",
"value": 41,
"unit": "%",
"warningThreshold": 98,
"errorThreshold": 98,
"timestamp": 1456408611000,
"output": "OK: MemoryValue: 41 (W> 98, C> 98) ",
"metricType": "performance",
"min": 0,

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

707

},
{

},
{

},
{

"max": 0
"name": "Heap Memory Usage",
"state": "Ok",
"value": 8,
"unit": "%",
"warningThreshold": 0,
"errorThreshold": 0,
"timestamp": 1456408611000,
"output": "HeapMemoryUsage.used = 101 of 1224m MB ",
"metricType": "rate",
"min": 0,
"max": 1224
"name": "Average Response Time",
"state": "Ok",
"value": 0,
"unit": "ms",
"warningThreshold": 0,
"errorThreshold": 0,
"timestamp": 1456408611000,
"output": "JMX OK - AverageResponseTimeMin = 0ms ",
"metricType": "performance",
"min": 0,
"max": 0
"name": "Busy Threads",
"state": "Ok",
"value": 0,
"warningThreshold": 150,
"errorThreshold": 180,
"timestamp": 1456408611000,
"output": "JMX OK - currentThreadsBusy = 0 ",
"metricType": "performance",
"min": 0,
"max": 0

Related Information
Monitoring API documentation
Monitoring Service [page 703]

1.4.6.2

Tutorial: Implementing a Dashboard Application

This tutorial describes the configuration of a custom application that retrieves the metrics of Java applications
running on SAP HANA Cloud Platform. Consequently, the implemented dashboard displays the states of the Java
applications and can display the state and metrics of the processes running on those applications.

708

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Prerequisites
To test the whole scenario, you need accounts on SAP HANA Cloud Platform in two data centers (EU and US
East).
To retrieve the metrics of Java applications as shown in this scenario, you need two deployed and running
Java applications.

Context
This tutorial uses a Java project published on GitHub. This project contains a notification application that requests
the metrics of the following Java applications (running on SAP HANA Cloud Platform):
app1 located in a1 account and EU data center
app2 located in a2 account and US East data center
After receiving each JSON response, the dashboard application parses the response and retrieves the name and
state of each application as well as the name, state, value, thresholds, unit, and timestamp of the metrics for each
process. All these data are arranged in a list and then displayed in the browser as a dashboard. For more
information about the JSON response, see Structure of a Monitoring Service Response [page 705].

Procedure
1. Download the cloud-metrics-dashboard project as a ZIP file from https://github.com/SAP/cloud-metricsdashboard .
2. Extract the files into a local folder and import the folder in Eclipse as an existing Maven project.

Note
You can also upload your project by copying the URL from GitHub and pasting it as a Git repository path or
URI after you switch to the Git perspective. Remember to switch back to a Java perspective afterward.
3. Open the Configuration.java class in Eclipse and update the following information: your logon
credentials, your Java applications and their accounts and data centers (landscape hosts).
...
private final String user = "my_username";
private final String password = "my_password";
private final List<ApplicationConfiguration> appsList = new
ArrayList<ApplicationConfiguration>();
public void configure(){
String landscapeFQDN1 = "api.hana.ondemand.com";
String account1 = "a1";
String application1 = "app1";
ApplicationConfiguration app1Config = new
ApplicationConfiguration(application1, account1, landscapeFQDN1);
this.appsList.add(app1Config);
String landscapeFQDN2 = "api.us1.hana.ondemand.com";
String account2 = "a2";
String application2 = "app2";

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

709

ApplicationConfiguration app2Config = new


ApplicationConfiguration(application2, account2, landscapeFQDN2);
this.appsList.add(app2Config);
}
...

Note
The example above shows only two applications, but you can create more and add them to the list.
4. Test your scenario.
a. If necessary, start your Java applications.
You can retrieve metrics of only running Java applications.

Tip
View the status of your Java applications and start them in the SAP HANA Cloud Platform cockpit.
b. Create a Java Web server in Eclipse and start it.
For more information, see Testing and publishing on your server

c. Run your Eclipse project on the server.


d. Verify the following:
Initially the dashboard displays all the states of the Java applications.

When you select an application, you can view the states of the applications processes.
When you select a process, you can view the processs metrics.

710

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
An empty field in the Thresholds column signifies that the warning and critical values are set to
zeros.

Related Information
Cockpit [page 84]
Java: Application Operations [page 1096]
Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

711

1.4.6.3

Tutorial: Implementing a Notification Application

This tutorial will help you configure an example notification scenario. The scenario includes a custom application
that notifies you of critical metrics via e-mail or SMS. The application also performs actions to fix issues based on
these critical metrics.

Prerequisites
To test the whole scenario, you need accounts on SAP HANA Cloud Platform in two data centers (EU and US
East).
To retrieve the metrics of Java applications as shown in this scenario, you need two deployed and running
Java applications.

Note
If a Java application is not started yet, the notification application will trigger the start process.

Context
In this tutorial, you will implement a notification application that requests the metrics of the following Java
applications (running on SAP HANA Cloud Platform):
app1 located in a1 account and EU data center
app2 located in a2 account and US East data center

Note
Since the requests are only sent to two applications, the Maven project that you import in Eclipse only spawns
two threads. However, you can change this number in the MetricsWatcher class, where the
ScheduledThreadPoolExecutor(2) method is called. Furthermore, if you decide to change the list of
applications, you also need to correct the list in the Demo class of the imported project.
When the notification application receives the Java application metrics, it checks for critical metrics. The
application then sends an e-mail or SMS depending on whether the metrics are received as critical once or three
times. In addition, the application restarts the Java application when the metrics are detected as critical three
times.

Procedure
1. Download the cloud-metricswatcher project as a ZIP file from https://github.com/SAP/cloudmetricswatcher .

712

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Extract the files into a local folder and import the folder in Eclipse as an existing Maven project.

Note
You can also upload your project by copying the URL from GitHub and pasting it as a Git repository path or
URI after you switch to the Git perspective. Remember to switch back to a Java perspective afterward.
3. Open the Demo.java class and update the following information: your e-mail and SMS addresses, your logon
credentials, your Java applications and their accounts and data centers.
...
String mail_to = "my_email@email.com";
String mail_to_sms = "my_email@sms-service.com";
private final String auth_user = "my_user";
private final String auth_pass = "my_password";
String landscapeFqdn1 = "api.hana.ondemand.com";
String account1 = "a1";
String application1 = "app1";
String landscapeFqdn2 = "api.us1.hana.ondemand.com";
String account2 = "a2";
String application2 = "app2";
...
4. Open the Mailsender.java class and update your e-mail account settings.
...
private static final String FROM = "my_email_account@email.com";
final String userName = "my_email_account";
final String password = "my_email_password";
...
public static void sendEmail(String to, String subject, String body) throws
AddressException, MessagingException {
// Set up the mail server
Properties properties = new Properties();
properties.setProperty("mail.transport.protocol", "smtp");
properties.setProperty("mail.smtp.auth", "true");
properties.setProperty("mail.smtp.starttls.enable", "true");
properties.setProperty("mail.smtp.port", "587");
properties.setProperty("mail.smtp.host", "smtp.email.com");
properties.setProperty("mail.smtp.host", "mail.email.com");
...
5. Test your scenario.
a. Open SAP HANA Cloud Platform cockpit and find your Java applications.
b. Configure your Java applications to return critical metrics.
To do this, you can create a JMX check with a very low critical threshold for HeapMemoryUsage so that
the check will always be received in a critical state.

Example
neo create-jmx-check -a myaccount -b demo -u p1234567 -n "JMX Check Test Heap Memory" -O java.lang:type=Memory -A HeapMemoryUsage -K used -U B -C
20000000 -h hana.ondemand.com
To use the console commands, you need to set up the console client. For more information, see
Setting Up the Console Client [page 42].
c. Run your notification application in Eclipse and check the following:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

713

You receive an e-mail with subject A metric has reached a critical state. and body
Metric HeapMemoryUsage for application app1 has reached critical state.
when a critical metric is received.
You receive an SMS with text Metric HeapMemoryUsage for application app1 has
reached critical state 3 times. The application will be restarted. when a
critical metric is received three times.
Your Java application is restarted when its critical metric is received three times.
You can follow the status of your Java applications in the SAP HANA Cloud Platform cockpit.

Related Information
create-jmx-check [page 120]
Monitoring Service [page 703]
Landscape Hosts [page 32]
Use the Monitoring Service for Critical Notifications and Self-Healing of HCP Java Applications

1.4.7 Performance Statistics Service (Beta)


Performance statistics enable you to monitor the resources used by your applications and to investigate the
causes of performance issues.

Note
This is a beta feature available on SAP HANA Cloud Platform for developer accounts. For more information
about the beta features, see Using Beta Features in Accounts [page 22].
Performance statistics are disabled by default, and you need to enable them to start gathering data. In the
cockpit, the Performance Statistics tab of a started application allows you to enable the collection of performance
statistics data. To view the collected performance statistics data, you have to generate a report.
Each report provides a breakdown of the time and resources such as CPU, memory and so on, used by the
different services of the platform for each HTTP request to your application. You can get insight on specific
requests and the respective behavior of your application. Currently, the supported services are the platform
runtime and the persistence service.

Note
The performance statistics service does not support the persistence service metrics for Java Web Tomcat 7
and Java Web Tomcat 8 application runtime container.

Related Information

714

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Metrics of a Performance Statistics Report [page 715]


Enabling Performance Statistics Collection [page 719]
Java Web Tomcat 7 [page 957]
Java Web Tomcat 8 [page 959]

1.4.7.1

Metrics of a Performance Statistics Report

You can see the report's metrics in a viewer, or you can download them as a JSON file.

Note
This is a beta feature available on SAP HANA Cloud Platform for developer accounts. For more information
about the beta features, see Using Beta Features in Accounts [page 22].
Table 256:
Metric Displayed in Viewer

Respective Metric in JSON File

Value

URL

action

The requested URL

Start Time

startTime

Time in miliseconds from January 1,


1970 until the start of the request

Memory (bytes)

allocMem

Memory in bytes allocated to the thread


processing the HTTP request

CPU (ms)

cpuTime

CPU time in milliseconds used by the


thread processing the HTTP request

Request Body (bytes)

sentBytes

Request's size; it is set to -1 if it is un


known.

Response (bytes)

receivedBytes

Size of the response in bytes

Response (ms)

respTime

Response time in milliseconds

DB Calls (count)

dbCalls

Number of DB calls by the thread proc


essing the HTTP request

Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.
DB Calls (bytes)

dbIO

IO in bytes from DB calls by the thread


processing the HTTP request

Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

715

Metric Displayed in Viewer

Respective Metric in JSON File

Value

DB Calls (ms)

dbTime

Time spent in the DB in nanoseconds (in


JSON file) or in milliseconds (in viewer).

Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.
External Calls (ms)

extTime

Time in milliseconds of the calls from the


application to systems that are not part
of SAP HANA Cloud Platform

ID

transId

The SAP-PASSPORT ID if available. If


not, it is set to n.a.

User

userId

The user who initiated the HTTP request.


If there is no authentication, it is set to
n.a.

Not displayed

actionType

Not supported yet

Not displayed

addInfo

Not supported yet

Not displayed

externalCalls

Number of calls from the application to


systems that are not part of SAP HANA
Cloud Platform

Not displayed

externalRecords

Detailed information about each external


call such as time, connection ID, destina
tion URL, and additional information.

Not displayed

serviceType

Not supported yet

Not displayed

sessionSize

Not supported yet

Example
The JSON file may look like the following:
{

716

"name": "AllRecords",
"children": [{
"name": "0",
"children": [{
"name": "action",
"value": "https://myappmyaccount.hana.ondemand.com/test"
}, {
"name": "actionType",
"value": "0"
}, {
"name": "addInfo",
"value": ""
}, {
"name": "allocMem",
"value": "126656"
}, {
"name": "cpuTime",
"value": "10"
}, {

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"name": "dbCalls",
"value": "0"
}, {
"name": "dbIO",
"value": "0"
}, {
"name": "dbTime",
"value": "0"
}, {
"name": "extTime",
"value": "0"
}, {
"name": "externalCalls",
"value": "0"
}, {
"name": "externalRecords",
"children":[{
"name":"0",
"children":[{
"name":"addInfo",
"value":"HttpDestination details: Name: googledestination;Authentication:
NoAuthentication;ProxyType: Internet"
}, {
"name":"callTime",
"value":"106"
}, {
"name":"connectionCounter",
"value":"1"
}, {
"name":"connectionId",
"value":"a7b8c385-fc04-4187-98fd-eb6b61c098ff"
}, {
"name":"destination",
"value":"http://google.com"
}, {
"name":"receivedBytes",
"value":"-1"
}, {
"name":"sentBytes",
"value":"-1"
}, {
"name":"systemId",
"value":"myapp:
5a351d8b2d914cf54d7d16f6315084e78ba00086"
}, {
"name":"type",
"value":"HTTP"
}]
}]
}, {
"name": "receivedBytes",
"value": "2707"
}, {
"name": "respTime",
"value": "832"
}, {
"name": "sentBytes",
"value": "-1"
}, {
"name": "serviceType",
"value": "0"
}, {
"name": "sessionSize",
"value": "0"
}, {
"name": "startTime",
"value": "1362992177712",

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

717

}, {

"name": "transId",
"value": "n.a."
}, {
"name": "userId",
"value": "n.a."
}]

}, {

718

}]

"name": "1",
"children": [{
"name": "action",
"value": "https://myappmyaccount.hana.ondemand.com/test"
}, {
"name": "actionType",
"value": "0"
}, {
"name": "addInfo",
"value": ""
}, {
"name": "allocMem",
"value": "71936"
}, {
"name": "cpuTime",
"value": "10"
}, {
"name": "dbCalls",
"value": "0"
}, {
"name": "dbIO",
"value": "0"
}, {
"name": "dbTime",
"value": "0"
}, {
"name": "extTime",
"value": "0"
}, {
"name": "externalCalls",
"value": "0"
}, {
"name": "externalRecords",
}, {
"name": "receivedBytes",
"value": "2707"
}, {
"name": "respTime",
"value": "371"
}, {
"name": "sentBytes",
"value": "24"
}, {
"name": "serviceType",
"value": "0"
}, {
"name": "sessionSize",
"value": "0"
}, {
"name": "startTime",
"value": "1362992181217"
}, {
"name": "transId",
"value": "n.a."
}, {
"name": "userId",
"value": "n.a."
}]

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tip
For better readability of the results, you can use any formatter or prettifier for the JSON.

Related Information
Performance Statistics Service (Beta) [page 714]
Enabling Performance Statistics Collection [page 719]
Java Web Tomcat 7 [page 957]
Java Web Tomcat 8 [page 959]

1.4.7.2

Enabling Performance Statistics Collection

You collect performance statistics to monitor the resources used by your applications and to investigate the
causes of performance issues.

Note
This is a beta feature available on SAP HANA Cloud Platform for developer accounts. For more information
about the beta features, see Using Beta Features in Accounts [page 22].

Prerequisites
You have an account with a deployed and started application.
You are a member of the account.

Procedure
1. In the cockpit, navigate to your application.
2. In the navigation area, choose

Monitoring

Performance Statistics (BETA) .

3. To start collecting performance statistics data, choose the Start Collecting button.
4. To delete the collected data up till now for the running collection, choose the Reset Collected Data button.
5. Execute your requests and choose one of the following:
To generate an intermediate report without terminating the data collection, choose the Generate Report
button.
To generate a report and terminate the data collection, choose the Stop Collecting button.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

719

6. To view the details of a report, choose one of the following:


To see the results in a viewer, choose
To view the results in a JSON file, choose

(Show).
(Download).

Related Information
Browser Support [page 8]
Cockpit [page 84]
Performance Statistics Service (Beta) [page 714]
Metrics of a Performance Statistics Report [page 715]

1.4.8 Persistence Service


Store data using in-memory and relational data persistence made available to your applications that run on SAP
HANA Cloud Platform by the persistence service. This ensures data availability and resiliency. In addition to
managing and providing access to databases, the persistence service also performs other tasks such as backup,
recovery and load balancing.
The persistence service supports the SAP HANA, SAP ASE database and SAP MaxDB, as shown in the high-level
overview below:

720

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SAP HANA Development


For productive use, a dedicated SAP HANA database is available as a hosted solution and enables you to work
with SAP HANA in the same way as with an on-premise version. There are some obvious restrictions, such as no
access to the operating system. A shared SAP HANA database system, on the other hand, available on a trial
basis, provides a managed environment in which additional restrictions apply to ensure user and data isolation.
You can use the SAP HANA database with multitenant database container support enabled (beta), both in a trial
and in a productive landscape. The main differences are outlined below:
Productive SAP HANA database
A database reserved for your exclusive use. Only your applications run on this database platform.
Full control of user management (as with an on-premise system)
An application is bound to the database by providing user and password (Custom Logon)
Includes the use of the SAP HANA XS Administration Tool and SAP HANA Web-based Development
Workbench
Trial SAP HANA database
A database you can use in a trial mode on a shared HANA system.
Support for the full feature set of an SAP HANA database based on MDC for a working day

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

721

Java Development
The persistence service supports JPA (Java Persistence API) and JDBC (Java Database Connectivity), with the
recommended programming model being JPA 2.0, with EclipseLink as the persistence provider.
It provides the following:
Application redeployment with the same schema: Provided the schema has not been dropped, a redeployed
application can reuse the schema with its associated database objects and data.
Shared schemas: Allow data to be shared between applications
Multiple schemas: Allow multiple databases to be used in parallel
Local test facility: On the local runtime, the persistence service automatically enables an embedded Apache
Derby database and configures the default data source accordingly. You can reconfigure the persistence
service to replace the standard database with a database of your choice.

Restrictions
When consuming the persistence service in your Java applications, be aware of the following restrictions:
No database abstraction
The persistence service does not provide database abstraction for the supported database types (SAP HANA
database, SAP ASE database, and SAP MaxDB). Applications must be aware of the type of database they use
and must be written, if necessary, in a database-specific way.
No automatic life cycle management for database objects
The persistence service does not provide automatic life cycle management for database objects, such as
tables, indices, sequences, and so on. It is the responsibility of the application to create the necessary
database objects, either by using JDBC to send the corresponding data definition statements to the database
or by using the schema creation capabilities of EclipseLink. Due to limitations of the EclipseLink schema
creation feature, changes to the schema, like altering a table definition, must be done by the application.
Alternatively, open source tools for database schema management (like Liquibase) can be used for life cycle
management for database objects, but must be bundled with the application.
No external access to SAP MaxDB
At present, the database can only be accessed from within the application using JDBC (or JPA). It is therefore
not possible to use external data administration tools to manage the application data.

Related Information
Consuming the Persistence Service [page 723]
Databases and Database Systems [page 770]
Managing Database Systems [page 774]
Managing Databases [page 781]
SAP HANA: Development [page 1008]
Java: Development [page 951]

722

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.1

Consuming the Persistence Service

The persistence service provides relational database storage for applications that are hosted on SAP HANA Cloud
Platform. This section introduces the key concepts of the persistence service and shows how you can use JPA and
JDBC to manage relational data in your applications.
Table 257:
Topic

Description

Tutorials [page 723]

Familiarize yourself with the JPA and JDBC technologies on SAP HANA Cloud Platform by com
pleting the tutorials.

Managing Database Sys


tems [page 774]

Find out how to manage database systems.

Managing Databases [page


781]

Find out how to manage your applications' databases.

Managing Schemas [page


804]

Find out how to manage your applications' database schemas.

Programming with JPA


[page 822]

Particular aspects about working with JPA and JDBC that were introduced in the tutorials are
explained in more detail.

Using Plain JDBC [page


843]
Creating SAP HANA Col
umn-Store Tables [page
837]
Using the SQL Trace [page
846]

Activate the SQL trace to include SQL details in the standard trace files.

EclipseLink Weaving [page


842]

Enable static weaving in Eclipse.

Remote Database Access


[page 849]

Access your database schema and tables in the cloud.

Local Testing [page 867]

Check the configuration requirements for local testing.

Frequently Asked Questions


[page 870]

Frequently asked questions about the persistence service

Related Information
Persistence Service [page 720]
Databases and Database Systems [page 770]

1.4.8.2

Tutorials

The tutorials provide an introduction to object-relational persistence using JPA 2.0, with EclipseLink as the
persistence provider, and relational persistence using JDBC. JPA is considered the standard approach for

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

723

developing applications for the SAP HANA Cloud Platform, with container-managed persistence representing the
model most commonly adopted by Web applications.
JPA provides an object-oriented view of the persisted data and allows you to work directly with Java objects that
are automatically synchronized with the database. Unlike JDBC, it does not require you to manually write SQL
statements to read and write objects from and to the database tables.
The tutorials can be run on all databases supported on the SAP HANA Cloud Platform. For local deployment, the
persistence service provides an embedded Apache Derby database instance.

Related Information
Adding Container-Managed Persistence With JPA (Java EE 6 Web Profile SDK) [page 724]
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]
Adding Persistence With JDBC (Java Web SDK) [page 746]
Migrating Web Applications That Use context.xml [page 756]
Creating an SAP HANA Database from the Cockpit [page 757]
Creating an SAP HANA Database Using Console Client [page 763]

1.4.8.2.1

Adding Container-Managed Persistence With JPA


(Java EE 6 Web Profile SDK)

This step-by-step tutorial shows how you can use JPA together with EJB to apply container-managed persistence
in a simple Java EE web application that manages a list of persons.
Table 258:
Sample Application

Steps
Prerequisites [page 725]
1. Create a Dynamic Web Project and Servlet [page 725]
2. Create the JPA Persistence Entity [page 728]
3. Configure the persistence.xml File of the Person Entity
[page 729]

The application is also available as a sample in the SDK for


Java EE 6 Web Profile:

4. Create an EJB Session Bean [page 729]

Sample name: persistence-with-ejb

5. Prepare the Web Application Project for JPA [page 730]

Location: <sdk>/samples folder

6. Extend the Servlet to Use Persistence [page 730]

More information: Samples [page 51]

7. Test the Web Application on the Local Server [page 732]


8. Deploy Applications Using Persistence on the Cloud from
Eclipse [page 732]

Note
The tutorial is based on the SDK for Java EE 6 Web Profile.

724

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
The tutorial and sample use EclipseLink version 2.5. If you use an earlier version of EclipseLink, bear in mind
that additional settings are required to deploy with the SAP HANA database. For more information, see Special
Settings for EclipseLink Versions Prior to 2.5 [page 824].

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install the SDK for Java EE 6 Web Profile.
SAP HANA database only: You have downloaded the EclipseLink JAR file (eclipselink.jar):
1. Download the latest 2.5.x version of EclipseLink from: http://www.eclipse.org/eclipselink/downloads
Select the EclipseLink 2.5.x Installer Zip (intended for use in Java EE environments).
2. Extract the archive. You will need to add the EclipseLink JAR to your web application in a later step.

1. Create a Dynamic Web Project and Servlet


Create a dynamic web project with the JPA project facet. This enables the relevant JPA tooling and adds the
required libraries and artifacts, such as the persistence.xml file. Then add a servlet (you will extend it in step 6
to use the JPA persistence entity and EJB session bean).
1. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

2. On the Dynamic Web Project screen, define the following settings:


1. Enter the Project name persistence-with-ejb.
2. In the Target Runtime pane, select Java EE 6 Web Profile as the runtime you want to use to deploy the
application.
3. In the Dynamic web module version section, select 3.0.
4. In the Configuration section, choose Modify and select the JPA checkbox in the Project Facets screen.
5. Choose OK and return to the Dynamic Web Project screen.
6. Choose Next

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

725

3. On the Java screen, leave the default settings and choose Next.
4. On the JPA Facet screen, define the following settings:
1. In the Platform section, select EclipseLink 2.4.x/2.5.x.
2. In the JPA implementation section, select Disable Library Configuration.
3. In the Persistent class management section, make sure that Discover annotated classes automatically is
selected and choose Next.

726

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. In the Web Module configuration settings, select the Generate web.xml deployment descriptor checkbox and
choose Finish.
6. To add a servlet to your project, choose

File

New

Servlet

from the Eclipse main menu.

7. Enter the Java package com.sap.cloud.sample.persistence and the class name


PersistenceEJBServlet.
8. To generate the servlet, choose Finish.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

727

2. Create the JPA Persistence Entity


Create a JPA persistence entity class named Person. Add an auto-incremented ID to the database table as the
primary key and person attributes. You also need to define a query method that retrieves a Person object from
the database table. Each person stored in the database is represented by a Person entity object.
1. In the Project Explorer view, select the persistence-with-ejb/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. From the Eclipse main menu, choose

File

New

Other

Class

and choose Next.

3. Make sure that the Java package is com.sap.cloud.sample.persistence.


4. Enter the class name Person and choose Finish.
5. Replace the entire class with the following content:
package com.sap.cloud.sample.persistence;
import javax.persistence.Basic;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.NamedQuery;
import javax.persistence.Table;
/**
* Class holding information on a person.
*/
@Entity
@Table(name = "T_PERSON")
@NamedQuery(name = "AllPersons", query = "select p from Person p")
public class Person {
@Id
@GeneratedValue
private Long id;
@Basic
private String firstName;
@Basic
private String lastName;
public long getId() {
return id;
}
public void setId(long newId) {
this.id = newId;
}
public String getFirstName() {
return this.firstName;
}
public void setFirstName(String newFirstName) {
this.firstName = newFirstName;
}
public String getLastName() {
return this.lastName;
}
public void setLastName(String newLastName) {
this.lastName = newLastName;
}
}
6. Save the class.

728

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Configure the persistence.xml File of the Person Entity


In the persistence-with-ejb/Java Resources/src/META-INF folder, define additional settings in the
persistence.xml file:
1. Select persistence.xml, and from the context menu choose

Open With

Persistence XML Editor .

2. On the General tab, make sure that org.eclipse.persistence.jpa.PersistenceProvider is entered


in the Persistence provider field.
3. On the Options tab, make sure that the DDL generation type Create Tables is selected.
4. On the Connection tab, select the transaction type JTA.
5. Save the file.

4. Create an EJB Session Bean


Create an EJB session bean to handle the database operations.
1. In the Project Explorer view, select the persistence-with-ejb/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. From the Eclipse main menu, choose
Next.

File

New

Other

EJB

Session Bean (EJB 3.x)

and choose

3. Make sure that the Java package is com.sap.cloud.sample.persistence.


4. Enter the class name PersonBean, leave the default setting Stateless, and choose Finish.
5. Leave the default setting Stateless and choose Finish.
6. Replace the entire class with the following content:
package com.sap.cloud.sample.persistence;
import java.util.List;
import javax.ejb.LocalBean;
import javax.ejb.Stateless;
import javax.persistence.EntityManager;
import javax.persistence.PersistenceContext;
/**
* Session Bean implementation class PersonBean
*/
@Stateless
@LocalBean
public class PersonBean {
@PersistenceContext
private EntityManager em;
public List<Person> getAllPersons() {
return em.createNamedQuery("AllPersons").getResultList();
}
public void addPerson(Person person) {
em.persist(person);
em.flush();
}
}
7. Save the class.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

729

5. Prepare the Web Application Project for JPA


Add the XSS Protection Library to the web application project.
1. In the Project Explorer view, select the persistence-with-ejb/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and choose Next.

3. Browse to the local directory where you downloaded and unpacked the SDK for Java EE 6 Web Profile, select
the repository/plugins directory, and choose OK.
4. Select the com.sap.security.core.server.csi_1.x.y.jar checkbox and choose Finish.
If you intend to deploy with the SAP HANA database, add the EclipseLink JAR file to the web application project:
1. In the Project Explorer view, select the persistence-with-ejb/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and choose Next.

3. Browse to your local directory where you downloaded and extracted the EclipseLink JAR (see the
Prerequisites section). Select the eclipselink/jlib directory and make sure the eclipselink.jar checkbox is
selected.
4. Choose Finish.

6. Extend the Servlet to Use Persistence


Extend the servlet to use the Person entity and EJB session bean. The servlet adds Person entity objects to the
database, retrieves their details, and displays them on the screen.
1. In the Project Explorer view, expand the persistence-with-ejb/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. Select PersistenceEJBServlet.java, and from the context menu choose

Open With

Java Editor .

3. Replace the entire servlet class with the following content:


package com.sap.cloud.sample.persistence;
import java.io.IOException;
import java.sql.SQLException;
import java.util.List;
import javax.ejb.EJB;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.security.core.server.csi.IXSSEncoder;
import com.sap.security.core.server.csi.XSSEncoder;
/**
* Servlet implementation class PersistenceEJBServlet
*/
@WebServlet("/")
public class PersistenceEJBServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final Logger LOGGER = LoggerFactory
.getLogger(PersistenceEJBServlet.class);
@EJB
PersonBean personBean;
/** {@inheritDoc} */

730

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

@Override
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
response.getWriter().println("<p>Persistence with JPA!</p>");
try {
appendPersonTable(response);
appendAddForm(response);
} catch (Exception e) {
response.getWriter().println(
"Persistence operation failed with reason: "
+ e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
/** {@inheritDoc} */
@Override
protected void doPost(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
try {
doAdd(request);
doGet(request, response);
} catch (Exception e) {
response.getWriter().println(
"Persistence operation failed with reason: "
+ e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
private void appendPersonTable(HttpServletResponse response)
throws SQLException, IOException {
// Append table that lists all persons
List<Person> resultList = personBean.getAllPersons();
response.getWriter().println(
"<p><table border=\"1\"><tr><th colspan=\"3\">"
+ (resultList.isEmpty() ? "" : resultList.size()
+ " ")
+ "Entries in the Database</th></tr>");
if (resultList.isEmpty()) {
response.getWriter().println(
"<tr><td colspan=\"3\">Database is empty</td></tr>");
} else {
response.getWriter()
.println(
"<tr><th>First name</th><th>Last name</th><th>Id</th></tr>");
}
IXSSEncoder xssEncoder = XSSEncoder.getInstance();
for (Person p : resultList) {
response.getWriter().println(
"<tr><td>" + xssEncoder.encodeHTML(p.getFirstName())
+ "</td><td>"
+ xssEncoder.encodeHTML(p.getLastName())
+ "</td><td>" + p.getId() + "</td></tr>");
}
response.getWriter().println("</table></p>");
}
private void appendAddForm(HttpServletResponse response) throws IOException {
// Append form through which new persons can be added
response.getWriter()
.println(
"<p><form action=\"\" method=\"post\">"
+ "First name:<input type=\"text\" name=
\"FirstName\">"
+ "&nbsp;Last name:<input type=\"text\" name=
\"LastName\">"
+ "&nbsp;<input type=\"submit\" value=\"Add
Person\">"
+ "</form></p>");
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

731

private void doAdd(HttpServletRequest request) throws ServletException,


IOException, SQLException {
// Extract name of person to be added from request
String firstName = request.getParameter("FirstName");
String lastName = request.getParameter("LastName");
if (firstName != null && lastName != null
&& !firstName.trim().isEmpty()
&& !lastName.trim().isEmpty()) {
Person person = new Person();
person.setFirstName(firstName);
person.setLastName(lastName);
personBean.addPerson(person);
}
}

4. Save the servlet. The project should compile without any errors.

7. Test the Web Application on the Local Server


1. To test your web application on the local server, follow the steps for deploying a web application locally as
described in Deploying Locally from Eclipse IDE [page 975].
You should see the following output:

2. Enter a first name (for example, John) and a last name (for example, Smith) and choose Add Person.
John Smith is added to the database as shown below:

If you add more names to the database, they will also be listed in the displayed table. This confirms that you
have successfully enabled persistence using the Person entity.

8. Deploy Applications Using Persistence on the Cloud from Eclipse


To test your web application in the cloud, define a server in Eclipse. Use the cockpit to create a default binding for
your application. Add the application to the new server and start it. This will the deploy the application on the
cloud, and you should see the same output as when the application was tested on the local server.

732

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Prerequisites
You have set up your runtime environment in the Eclipse IDE. For more information, see Setting Up the
Runtime Environment [page 39].
You have developed or imported a Java Web application in Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53]
1. Switch to the Servers view in the Eclipse IDE.
2. Open the context menu and define a server with the following settings:
Select the server type

SAP

SAP HANA Cloud Platform .

Use the landscape host depending on your account type and choose Next. For more information, see
Landscape Hosts [page 32].
Specify your application name (only lowercase Latin letters and digits are allowed).

Note
The application name should be unique enough so that your deployed application can be easily
identified.
Select a runtime. If you leave the Automatic option, the server will load the target runtime of your
application.
Enter your account name, e-mail or user name, and password and choose Next.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

733

Note
If you have previously entered an account and user name for your landscape host, these names will
be prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.
If you select the Save password box, the entered password for a given user name will be
remembered and kept in the secure store.
Do not select your application on the Add and Remove screen.

Note
Adding an application would automatically start this application with the effect that it would fail
because no data source binding exists. You will add an application in a later step.
Choose Finish.

734

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. On the Servers view, open the context menu for the server you just created and choose

Show In

Cockpit . The cockpit opens inside Eclipse.


4. In the cockpit, select an account and choose

Persistence

Databases & Schemas

in the navigation area.

5. Select the database that you want to create a binding for.


6. Choose Data Source Bindings in the navigation area.
7. Define a binding (<DEFAULT>) for the application and select a database ID. Choose Save.
This creates a default binding for the application. You can use an existing database or create a new one.
8. On the Servers view in Eclipse, open the context menu for the server and choose

Add and Remove...

<application name> . To add the application to the server, add the application to the panel on the right side.
Choose Finish.
9. Start the server. This will deploy the application and start it on the SAP HANA Cloud Platform.
You can access the application by clicking the application URL on the application overview page in the cockpit.

Note
You cannot deploy multiple applications on the same application process. Deployment of a second application
on the same application process overwrites any previous deployments. If you want to deploy several
applications, deploy each of them on a separate application process.

1.4.8.2.2

Adding Application-Managed Persistence With JPA


(Java Web SDK)

This step-by-step tutorial shows how you can use JPA to apply application-managed persistence in a simple Java
EE web application that manages a list of persons.
Table 259:
Steps

Sample Application

Prerequisites [page 736]


1. Create a Dynamic Web Project and Servlet [page 736]
2. Create the JPA Persistence Entity [page 739]
3. Maintain the Metadata of the Person Entity [page 740]
4. Prepare the Web Application Project for JPA [page 740]

The application is also available as a sample in the SDK for


Java Web:
Sample name: persistence-with-jpa

5. Extend the Servlet to Use Persistence [page 741]

Location: <sdk>/samples folder

6. Test the Web Application on the Local Server [page 744]

More information: Samples [page 51]

7. Deploy Applications Using Persistence on the Cloud from


Eclipse [page 744]

Note
The tutorial is based on the SDK for Java Web.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

735

Note
The tutorial and sample use EclipseLink version 2.5. If you use an earlier version of EclipseLink, bear in mind
that additional settings are required to deploy with the SAP HANA database. For more information, see Special
Settings for EclipseLink Versions Prior to 2.5 [page 824].

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install the SDK for Java Web.
You have downloaded the JPA Provider, EclipseLink:
1. Download the latest 2.5.x version of EclipseLink from: http://www.eclipse.org/eclipselink/downloads
Select the EclipseLink 2.5.x Installer Zip (intended for use in Java EE environments).
2. Extract the archive.
3. Copy the following two files to a separate directory in your local file system:
eclipselink.jar from the directory eclipselink/jlib
javax.persistence_2.*.jar from the directory eclipselink/jlib/jpa
You will need to add these files to your web application in a later step.

1. Create a Dynamic Web Project and Servlet


Create a dynamic web project with the JPA project facet. This enables the relevant JPA tooling and adds the
required libraries and artifacts, such as the persistence.xml file. Then add a servlet (you will extend it later to
use the JPA persistence entity).
1. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

2. On the Dynamic Web Project screen, define the following settings:


1. Enter the Project name persistence-with-jpa.
2. In the Target Runtime pane, select Java Web as the runtime you want to use to deploy the application.
3. In the Dynamic web module version section, select 2.5.
4. In the Configuration section, choose Modify and select the JPA checkbox in the Project Facets screen.
5. Choose OK and return to the Dynamic Web Project screen.
6. Choose Next.

736

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. On the Java screen, leave the default settings and choose Next.
4. On the JPA Facet screen, define the following settings:
1. In the Platform section, select EclipseLink 2.5.x.
2. In the JPA implementation section, select Disable Library Configuration.
3. In the Persistent class management section, select Annotated classes must be listed in persistence.xml
and choose Next.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

737

5. In the Web Module configuration settings, select the Generate web.xml deployment descriptor checkbox and
choose Finish.
6. To add a servlet to the project you have just created, choose
menu.

File

New

Servlet

from the Eclipse main

7. Enter the Java package com.sap.cloud.sample.persistence and the class name


PersistenceWithJPAServlet.
8. To generate the servlet, choose Finish.

738

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Create the JPA Persistence Entity


Create a JPA persistence entity class named Person. Add an auto-incremented ID to the database table as the
primary key and person attributes. You also need to define a query method that retrieves a Person object from
the database table. Each person stored in the database is represented by a Person entity object.
1. In the Project Explorer view, select the persistence-with-ejb/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. From the Eclipse main menu, choose

File

New

Other

Class

and choose Next.

3. Make sure that the Java package is com.sap.cloud.sample.persistence.


4. Enter the class name Person and choose Finish.
5. In the editor, replace the entire class with the following content:
package com.sap.cloud.sample.persistence;
import javax.persistence.Basic;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.Id;
import javax.persistence.NamedQuery;
import javax.persistence.Table;
/**
* Class holding information on a person.
*/
@Entity
@Table(name = "T_PERSON")
@NamedQuery(name = "AllPersons", query = "select p from Person p")
public class Person {
@Id
@GeneratedValue
private Long id;
@Basic
private String firstName;
@Basic
private String lastName;
public long getId() {
return id;
}
public void setId(long newId) {
this.id = newId;
}
public String getFirstName() {
return this.firstName;
}
public void setFirstName(String newFirstName) {
this.firstName = newFirstName;
}
public String getLastName() {
return this.lastName;
}
public void setLastName(String newLastName) {
this.lastName = newLastName;
}
}
6. Save the class.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

739

3. Maintain the Metadata of the Person Entity


In the persistence-with-jpa/Java Resources/src/META-INF folder, define additional settings in the
persistence.xml file:
1. Select the persistence.xml and from the context menu choose

Open With

Persistence XML Editor .

2. On the General tab, define the following settings:


1. Make sure that org.eclipse.persistence.jpa.PersistenceProvider is entered in the
Persistence provider field.
2. In the Managed Class section, choose Add.... Enter Person and choose Ok.
3. On the Connection tab, make sure that the transaction type Resource Local is selected.
4. On the Schema Generation tab, make sure the DDL generation type Create Tables in the EclipseLink
Schema Generation section is selected.
5. Save the file.

4. Prepare the Web Application Project for JPA


1. Add EclipseLink executables to the web application project:
1. In the Project Explorer view, select the persistence-with-jpa/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and choose Next.

3. Browse to the local directory to which you copied the downloaded EclipseLink JAR files (see the
Prerequisites [page 736] section), and choose OK.
4. Choose the Select All button to select the checkboxes for the EclipseLink JAR files, eclipselink.jar and
javax.persistence_2.*.jar. Choose Finish.
2. Add the XSS Protection Library to the web application project:
1. In the Project Explorer view, select the persistence-with-jpa/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and choose Next.

3. Browse to the local directory where you downloaded and unpacked the SAP HANA Cloud Platform SDK
for Java Web (neo-java-web-sdk-1.<version>), select the repository/plugins directory, and choose
OK .
4. Select the checkbox com.sap.security.core.server.csi_1.x.y.jar and choose Finish.
3. Adapt the Java build path order:
1. In the Project Explorer view, select the persistence-with-jpa node, and from the context menu
choose Properties.
2. Select Java Build Path and switch to the Order and Export tab.
3. Select Web App Libraries and move it up so that it is positioned above Java Web.
4. Choose OK to finish this step.
4. Add the resource reference description to web.xml:
1. In the Project Explorer view, expand the persistence-with-jpa/WebContent/WEB-INF node.
2. Select web.xml and from the context menu choose

Open With

Text Editor

3. Insert the following content after the <servlet-mapping> elements:


<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>

740

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

<res-type>javax.sql.DataSource</res-type>
</resource-ref>
4. Save the file.
5. Optionally modify the servlet deployment descriptor information:
1. Open the web.xml file as in the previous step.
2. Replace the URL pattern "/PersistenceWithJPAServlet" that was generated for the servlet with "/" as
shown below:
<servlet-mapping>
<servlet-name>PersistenceWithJPAServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
3. Save the file.

Note
An application's URL path contains the context root followed by the optional URL pattern ("/<URL
pattern>"). The servlet URL pattern that is automatically generated by Eclipse uses the servlets class
name as part of the pattern. Since the cockpit only displays the context root, this means that you cannot
directly open the application in the cockpit without adding the servlet name. To call the application by only
the context root, use "/" as the URL mapping, then you will no longer have to correct the URL in the
browser.

5. Extend the Servlet to Use Persistence


Extend the servlet to use the Person entity. The servlet adds Person entity objects to the database, retrieves
their details, and displays them on the screen.
1. In the Project Explorer view, expand the persistence-with-jpa/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. Select PersistenceWithJPAServlet.java and from the context menu choose

Open With

Java

Editor .
3. In the opened editor, replace the entire servlet class with the following content:
package com.sap.cloud.sample.persistence;
import java.io.IOException;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
import org.eclipse.persistence.config.PersistenceUnitProperties;
import org.slf4j.Logger;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

741

import org.slf4j.LoggerFactory;
import com.sap.security.core.server.csi.IXSSEncoder;
import com.sap.security.core.server.csi.XSSEncoder;
/**
* Servlet implementing a simple JPA based persistence sample application for
SAP HANA Cloud Platform.
*/
public class PersistenceWithJPAServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final Logger LOGGER =
LoggerFactory.getLogger(PersistenceWithJPAServlet.class);
private DataSource ds;
private EntityManagerFactory emf;
/** {@inheritDoc} */
@SuppressWarnings({ "rawtypes", "unchecked" })
@Override
public void init() throws ServletException {
Connection connection = null;
try {
InitialContext ctx = new InitialContext();
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/DefaultDB");
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds);
emf = Persistence.createEntityManagerFactory("persistence-with-jpa",
properties);
} catch (NamingException e) {
throw new ServletException(e);
}
}
/** {@inheritDoc} */
@Override
public void destroy() {
emf.close();
}
/** {@inheritDoc} */
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
response.getWriter().println("<p>Persistence with JPA Sample!</p>");
try {
appendPersonTable(response);
appendAddForm(response);
} catch (Exception e) {
response.getWriter().println("Persistence operation failed with
reason: " + e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
/** {@inheritDoc} */
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse
response) throws ServletException,
IOException {
try {
doAdd(request);
doGet(request, response);
} catch (Exception e) {
response.getWriter().println("Persistence operation failed with
reason: " + e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
private void appendPersonTable(HttpServletResponse response) throws
SQLException, IOException {
// Append table that lists all persons
EntityManager em = emf.createEntityManager();
try {
@SuppressWarnings("unchecked")

742

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

List<Person> resultList =
em.createNamedQuery("AllPersons").getResultList();
response.getWriter().println(
"<p><table border=\"1\"><tr><th colspan=\"3\">"
+ (resultList.isEmpty() ? "" : resultList.size() +
" ")
+ "Entries in the Database</th></tr>");
if (resultList.isEmpty()) {
response.getWriter().println("<tr><td colspan=\"3\">Database is
empty</td></tr>");
} else {
response.getWriter().println("<tr><th>First name</th><th>Last
name</th><th>Id</th></tr>");
}
IXSSEncoder xssEncoder = XSSEncoder.getInstance();
for (Person p : resultList) {
response.getWriter().println(
"<tr><td>" + xssEncoder.encodeHTML(p.getFirstName()) +
"</td><td>"
+ xssEncoder.encodeHTML(p.getLastName()) + "</
td><td>" + p.getId() + "</td></tr>");
}
response.getWriter().println("</table></p>");
} finally {
em.close();
}
}
private void appendAddForm(HttpServletResponse response) throws IOException {
// Append form through which new persons can be added
response.getWriter().println(
"<p><form action=\"\" method=\"post\">" + "First name:<input
type=\"text\" name=\"FirstName\">"
+ "&nbsp;Last name:<input type=\"text\" name=\"LastName
\">"
+ "&nbsp;<input type=\"submit\" value=\"Add Person\">" +
"</form></p>");
}
private void doAdd(HttpServletRequest request) throws ServletException,
IOException, SQLException {
// Extract name of person to be added from request
String firstName = request.getParameter("FirstName");
String lastName = request.getParameter("LastName");
// Add person if name is not null/empty
EntityManager em = emf.createEntityManager();
try {
if (firstName != null && lastName != null && !
firstName.trim().isEmpty() && !lastName.trim().isEmpty()) {
Person person = new Person();
person.setFirstName(firstName);
person.setLastName(lastName);
em.getTransaction().begin();
em.persist(person);
em.getTransaction().commit();
}
} finally {
em.close();
}
}
}
4. Save the servlet. The project should compile without any errors.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

743

6. Test the Web Application on the Local Server


1. To test your web application on the local server, follow the steps for deploying a web application locally as
described in Deploying Locally from Eclipse IDE [page 975]. You should see the following output:

2. Enter a first name (for example, John) and a last name (for example, Smith) and choose Add Person.
John Smith is added to the database as shown below:

If you add more names to the database, they will also be listed in the displayed table. This confirms that you
have successfully enabled persistence using the Person entity.

7. Deploy Applications Using Persistence on the Cloud from Eclipse


To test your web application in the cloud, define a server in Eclipse. Use the cockpit to create a default binding for
your application. Add the application to the new server and start it. This will the deploy the application on the
cloud, and you should see the same output as when the application was tested on the local server.
Prerequisites
You have set up your runtime environment in the Eclipse IDE. For more information, see Setting Up the
Runtime Environment [page 39].
You have developed or imported a Java Web application in Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53]
1. Switch to the Servers view in the Eclipse IDE.
2. Open the context menu and define a server with the following settings:
Select the server type

SAP

SAP HANA Cloud Platform .

Use the landscape host depending on your account type and choose Next. For more information, see
Landscape Hosts [page 32].
Specify your application name (only lowercase Latin letters and digits are allowed).

744

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
The application name should be unique enough so that your deployed application can be easily
identified.
Select a runtime. If you leave the Automatic option, the server will load the target runtime of your
application.
Enter your account name, e-mail or user name, and password and choose Next.

Note
If you have previously entered an account and user name for your landscape host, these names will
be prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

745

If you select the Save password box, the entered password for a given user name will be
remembered and kept in the secure store.
Do not select your application on the Add and Remove screen.

Note
Adding an application would automatically start this application with the effect that it would fail
because no data source binding exists. You will add an application in a later step.
Choose Finish.
3. On the Servers view, open the context menu for the server you just created and choose

Show In

Cockpit . The cockpit opens inside Eclipse.


4. In the cockpit, select an account and choose

Persistence

Databases & Schemas

in the navigation area.

5. Select the database that you want to create a binding for.


6. Choose Data Source Bindings in the navigation area.
7. Define a binding (<DEFAULT>) for the application and select a database ID. Choose Save.
This creates a default binding for the application. You can use an existing database or create a new one.
8. On the Servers view in Eclipse, open the context menu for the server and choose

Add and Remove...

<application name> . To add the application to the server, add the application to the panel on the right side.
Choose Finish.
9. Start the server. This will deploy the application and start it on the SAP HANA Cloud Platform.
You can access the application by clicking the application URL on the application overview page in the cockpit.

Note
You cannot deploy multiple applications on the same application process. Deployment of a second application
on the same application process overwrites any previous deployments. If you want to deploy several
applications, deploy each of them on a separate application process.

1.4.8.2.3

Adding Persistence With JDBC (Java Web SDK)

This step-by-step tutorial shows how you can use JDBC to persist data in a simple Java EE web application that
manages a list of persons.
Table 260:
Sample Application

Steps
Prerequisites [page 747]
1. Create a Dynamic Web Project and Servlet [page 747]
2. Create the Person Entity [page 747]
3. Create the Person DAO [page 748]
4. Prepare the Web Application Project for JDBC [page 750]
5. Extend the Servlet to Use Persistence [page 751]

746

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

The application is also available as a sample in the SDK for


Java Web:
Sample name: persistence-with-jdbc
Location: <sdk>/samples folder
More information: Samples [page 51]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Steps

Sample Application

6. Test the Web Application on the Local Server [page 753]


7. Deploy Applications Using Persistence on the Cloud from
Eclipse IDE [page 754]

Note
The tutorial is based on the SDK for Java Web.

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].

Note
You need to install the SDK for Java Web.

1. Create a Dynamic Web Project and Servlet


Create a dynamic web project and add a servlet, which you extend in step 4.
1. From the Eclipse main menu, choose

File

New

Dynamic Web Project .

2. Enter the Project name persistence-with-jdbc.


3. In the Target Runtime pane, select Java Web as the runtime you want to use to deploy the application.
4. Leave the default values for the other project settings and choose Next.
5. On the Java screen, leave the default settings and choose Next.
6. In the Web Module configuration settings, select the Generate web.xml deployment descriptor checkbox and
choose Finish.
7. To add a servlet to the project you have just created, choose
main menu.

File

New

Web

Servlet

from the Eclipse

8. Enter the Java package com.sap.cloud.sample.persistence and the class name


PersistenceWithJDBCServlet. Choose Finish to generate the servlet.

2. Create the Person Entity


Create an entity class named Person with basic attributes.
1. In the Project Explorer view, select the persistence-with-jdbc/Java Resources/src/
com.sap.cloud.sample.persistence node.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

747

2. From the context menu, choose New Class , check that the package entered is
com.sap.cloud.sample.persistence, enter the class name Person, and choose Finish.
3. Open the file in the text editor and insert the following content:
package com.sap.cloud.sample.persistence;
/**
* Class holding information on a person.
*/
public class Person {
private String id;
private String firstName;
private String lastName;
public String getId() {
return id;
}
public void setId(String newId) {
this.id = newId;
}
public String getFirstName() {
return this.firstName;
}
public void setFirstName(String newFirstName) {
this.firstName = newFirstName;
}
public String getLastName() {
return this.lastName;
}
public void setLastName(String newLastName) {
this.lastName = newLastName;
}
}
4. Save the class.

3. Create the Person DAO


Create a DAO class, PersonDAO, in which you encapsulate the access to the persistence layer.
1. In the Project Explorer view, select the persistence-with-jdbc/Java Resources/src/
com.sap.cloud.sample.persistence node.
2. From the context menu, choose New Class , check that the package entered is
com.sap.cloud.sample.persistence, enter the class name PersonDAO, and choose Finish.
3. Open the file in the text editor and insert the following content:
package com.sap.cloud.sample.persistence;
import java.sql.Connection;
import java.sql.DatabaseMetaData;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
import javax.sql.DataSource;
/**
* Data access object encapsulating all JDBC operations for a person.
*/
public class PersonDAO {
private DataSource dataSource;

748

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

/**
* Create new data access object with data source.
*/
public PersonDAO(DataSource newDataSource) throws SQLException {
setDataSource(newDataSource);
}
/**
* Get data source which is used for the database operations.
*/
public DataSource getDataSource() {
return dataSource;
}
/**
* Set data source to be used for the database operations.
*/
public void setDataSource(DataSource newDataSource) throws SQLException {
this.dataSource = newDataSource;
checkTable();
}
/**
* Add a person to the table.
*/
public void addPerson(Person person) throws SQLException {
Connection connection = dataSource.getConnection();
try {
PreparedStatement pstmt = connection
.prepareStatement("INSERT INTO PERSONS (ID, FIRSTNAME,
LASTNAME) VALUES (?, ?, ?)");
pstmt.setString(1, UUID.randomUUID().toString());
pstmt.setString(2, person.getFirstName());
pstmt.setString(3, person.getLastName());
pstmt.executeUpdate();
} finally {
if (connection != null) {
connection.close();
}
}
}
/**
* Get all persons from the table.
*/
public List<Person> selectAllPersons() throws SQLException {
Connection connection = dataSource.getConnection();
try {
PreparedStatement pstmt = connection
.prepareStatement("SELECT ID, FIRSTNAME, LASTNAME FROM
PERSONS");
ResultSet rs = pstmt.executeQuery();
ArrayList<Person> list = new ArrayList<Person>();
while (rs.next()) {
Person p = new Person();
p.setId(rs.getString(1));
p.setFirstName(rs.getString(2));
p.setLastName(rs.getString(3));
list.add(p);
}
return list;
} finally {
if (connection != null) {
connection.close();
}
}
}
/**
* Check if the person table already exists and create it if not.
*/
private void checkTable() throws SQLException {
Connection connection = null;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

749

try {
connection = dataSource.getConnection();
if (!existsTable(connection)) {
createTable(connection);
}
} finally {
if (connection != null) {
connection.close();
}
}

}
/**
* Check if the person table already exists.
*/
private boolean existsTable(Connection conn) throws SQLException {
DatabaseMetaData meta = conn.getMetaData();
ResultSet rs = meta.getTables(null, null, "PERSONS", null);
while (rs.next()) {
String name = rs.getString("TABLE_NAME");
if (name.equals("PERSONS")) {
return true;
}
}
return false;
}
/**
* Create the person table.
*/
private void createTable(Connection connection) throws SQLException {
PreparedStatement pstmt = connection
.prepareStatement("CREATE TABLE PERSONS "
+ "(ID VARCHAR(255) PRIMARY KEY, "
+ "FIRSTNAME VARCHAR (255),"
+ "LASTNAME VARCHAR (255))");
pstmt.executeUpdate();
}

4. Save the class.

4. Prepare the Web Application Project for JDBC


1. Add the XSS Protection Library to the web application project:
1. In the Project Explorer view, select the persistence-with-jdbc/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and then choose Next.

3. Browse to the local directory where you downloaded and unpacked the SAP HANA Cloud Platform SDK,
select the repository/plugins directory, and choose OK.
4. Select the com.sap.security.core.server.csi_1.x.y.jar checkbox and choose Finish.
2. Adapt the Java build path order:
1. In the Project Explorer view, select the persistence-with-jdbc node, and from the context menu
choose Properties.
2. Select Java Build Path and switch to the Order and Export tab.
3. Select Web App Libraries.
4. Choose OK.
3. Add the resource reference description to web.xml:
1. In the Project Explorer view, expand the persistence-with-jdbc/WebContent/WEB-INF node.

750

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Select web.xml, and from the context menu choose

Open With

Text Editor

3. Insert the following content after the <servlet-mapping> or <welcome-file-list> element:


<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
4. Save the file.
4. Optionally modify the servlet deployment descriptor information:
1. Open the web.xml file as in the previous step.
2. Replace the URL pattern "/PersistenceWithJDBCServlet" that was generated for the servlet with "/" as
shown below:
<servlet-mapping>
<servlet-name>PersistenceWithJDBCServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>

Note
If your servlet version is 3.0 or higher, you just need to change the WebServlet annotation in the
PersistenceWithJDBCServlet.java class to be as the following: @WebServlet("/").
3. Save the file.

Note
An application's URL path contains the context root followed by the optional URL pattern ("/<URL
pattern>"). The servlet URL pattern that is automatically generated by Eclipse uses the servlets class
name as part of the pattern. Since the cockpit only displays the context root, this means that you cannot
directly open the application in the cockpit without adding the servlet name. To call the application by only
the context root, use "/" as the URL mapping, then you will no longer have to correct the URL in the
browser.

5. Extend the Servlet to Use Persistence


Extend the servlet to use the persistence functionality. The servlet adds Person entity objects to the database,
retrieves their details, and displays them on the screen.
1. In the Project Explorer view, expand the persistence-with-jdbc/src/
com.sap.cloud.sample.persistence node.
2. Select PersistenceWithJDBCServlet.java, and from the context menu choose

Open With

Java

Editor .
3. In the opened editor, replace the entire servlet class with the following content:
package com.sap.cloud.sample.persistence;
import java.io.IOException;
import java.sql.SQLException;
import java.util.List;
import javax.naming.InitialContext;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

751

import javax.naming.NamingException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.security.core.server.csi.IXSSEncoder;
import com.sap.security.core.server.csi.XSSEncoder;
/**
* Servlet implementing a simple JDBC based persistence sample application for
* SAP HANA Cloud Platform.
*/
public class PersistenceWithJDBCServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final Logger LOGGER = LoggerFactory
.getLogger(PersistenceWithJDBCServlet.class);
private PersonDAO personDAO;
/** {@inheritDoc} */
@Override
public void init() throws ServletException {
try {
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx
.lookup("java:comp/env/jdbc/DefaultDB");
personDAO = new PersonDAO(ds);
} catch (SQLException e) {
throw new ServletException(e);
} catch (NamingException e) {
throw new ServletException(e);
}
}
/** {@inheritDoc} */
@Override
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
response.getWriter().println("<p>Persistence with JDBC!</p>");
try {
appendPersonTable(response);
appendAddForm(response);
} catch (Exception e) {
response.getWriter().println(
"Persistence operation failed with reason: "
+ e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
/** {@inheritDoc} */
@Override
protected void doPost(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
try {
doAdd(request);
doGet(request, response);
} catch (Exception e) {
response.getWriter().println(
"Persistence operation failed with reason: "
+ e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
private void appendPersonTable(HttpServletResponse response)
throws SQLException, IOException {
// Append table that lists all persons
List<Person> resultList = personDAO.selectAllPersons();
response.getWriter().println(
"<p><table border=\"1\"><tr><th colspan=\"3\">"

752

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

tr>" +

tr>"));

+ resultList.size() + " entries in the Database</th></


(resultList.isEmpty()
? "<tr><td colspan=\"3\">Database is empty</td></tr>"
: "<tr><th>First Name</th><th>Last Name</th><th>Id</th></

IXSSEncoder xssEncoder = XSSEncoder.getInstance();


for (Person p : resultList) {
response.getWriter().println(
"<tr><td>" +
xssEncoder.encodeHTML(p.getFirstName())
+ "</td><td>"
+
xssEncoder.encodeHTML(p.getLastName())
+ "</td><td>" + p.getId() + "</td></
tr>");
}
response.getWriter().println("</table></p>");
}
private void appendAddForm(HttpServletResponse response) throws IOException {
// Append form through which new persons can be added
response.getWriter()
.println(
"<p><form action=\"\" method=\"post\">"
+ "First name:<input type=\"text\" name=
\"FirstName\">"
+ "&nbsp;Last name:<input type=\"text\" name=
\"LastName\">"
+ "&nbsp;<input type=\"submit\" value=\"Add
Person\">"
+ "</form></p>");
}
private void doAdd(HttpServletRequest request) throws ServletException,
IOException, SQLException {
// Extract name of person to be added from request
String firstName = request.getParameter("FirstName");
String lastName = request.getParameter("LastName");
// Add person if name is not null/empty
if (firstName != null && lastName != null
&& !firstName.trim().isEmpty() && !lastName.trim().isEmpty()) {
Person person = new Person();
person.setFirstName(firstName.trim());
person.setLastName(lastName.trim());
personDAO.addPerson(person);
}
}
}
4. Save the servlet. The project should compile without any errors.

6. Test the Web Application on the Local Server


1. To test your web application on the local server, follow the steps for deploying a web application locally as
described in Deploying Locally from Eclipse IDE [page 975]. You should see the following output:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

753

2. Enter a first name (for example, John) and a last name (for example, Smith) and choose Add Person.
John Smith is added to the database as shown below:

If you add more names to the database, they will also be listed in the table displayed.

7. Deploy Applications Using Persistence on the Cloud from Eclipse IDE


To test your web application in the cloud, define a server in Eclipse. Use the cockpit to create a default binding for
your application. Add the application to the new server and start it. This will the deploy the application on the
cloud, and you should see the same output as when the application was tested on the local server.
Prerequisites
You have set up your runtime environment in the Eclipse IDE. For more information, see Setting Up the
Runtime Environment [page 39].
You have developed or imported a Java Web application in Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53]
1. Switch to the Servers view in the Eclipse IDE.
2. Open the context menu and define a server with the following settings:
Select the server type

SAP

SAP HANA Cloud Platform .

Use the landscape host depending on your account type and choose Next. For more information, see
Landscape Hosts [page 32].
Specify your application name (only lowercase Latin letters and digits are allowed).

Note
The application name should be unique enough so that your deployed application can be easily
identified.
Select a runtime. If you leave the Automatic option, the server will load the target runtime of your
application.
Enter your account name, e-mail or user name, and password and choose Next.

754

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
If you have previously entered an account and user name for your landscape host, these names will
be prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.
If you select the Save password box, the entered password for a given user name will be
remembered and kept in the secure store.
Do not select your application on the Add and Remove screen.

Note
Adding an application would automatically start this application with the effect that it would fail
because no data source binding exists. You will add an application in a later step.
Choose Finish.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

755

3. On the Servers view, open the context menu for the server you just created and choose

Show In

Cockpit . The cockpit opens inside Eclipse.


4. In the cockpit, select an account and choose

Persistence

Databases & Schemas

in the navigation area.

5. Select the database that you want to create a binding for.


6. Choose Data Source Bindings in the navigation area.
7. Define a binding (<DEFAULT>) for the application and select a database ID. Choose Save.
This creates a default binding for the application. You can use an existing database or create a new one.
8. On the Servers view in Eclipse, open the context menu for the server and choose

Add and Remove...

<application name> . To add the application to the server, add the application to the panel on the right side.
Choose Finish.
9. Start the server. This will deploy the application and start it on the SAP HANA Cloud Platform.
You can access the application by clicking the application URL on the application overview page in the cockpit.

Note
You cannot deploy multiple applications on the same application process. Deployment of a second application
on the same application process overwrites any previous deployments. If you want to deploy several
applications, deploy each of them on a separate application process.

1.4.8.2.4

Migrating Web Applications That Use context.xml

This three-step guide shows how applications can replace context.xml with web.xml.

Overview
Earlier versions of the persistence tutorials used context.xml to declare a reference to the default data source
provided by the persistence service. The tutorials have since been adapted to include the resource reference
description in the web.xml deployment descriptor, in accordance with the Java EE Specification, as follows:
<resource-ref>
<res-ref-name> NAME </res-ref-name>
<res-type> TYPE </res-type>
</resource-ref>
If you have Web applications that use context.xml, you are advised to switch to web.xml as soon as possible by
completing the migration steps described below. The use of context.xml is no longer supported.

756

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Open the context.xml file in the WebContent/META-INF folder of your Web application project. You should
see the following with similar values (the values shown below are based on the tutorials):
<Resource name="jdbc/DefaultDB"
auth="Container"
type="javax.sql.DataSource"
factory="com.sap.jpaas.service.persistence.core.JNDIDataSourceFactory"/>
You require the resource name and type values in the next step.
2. Add the resource reference description to the web.xml file:
1. Open web.xml in the WebContent/WEB-INF folder of your Web application project.
2. Insert the following content after the <servlet-mapping> elements:
<resource-ref>
<res-ref-name>NAME</res-ref-name>
<res-type>TYPE</res-type>
</resource-ref>
3. Replace the values for the resource name and type with those from step 1, as shown in the example
below, and save:
<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
3. Delete context.xml from the WebContent/META-INF folder of your Web application project.

Related Information
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]
Adding Persistence With JDBC (Java Web SDK) [page 746]

1.4.8.2.5

Creating an SAP HANA Database from the Cockpit

This step-by-step tutorial shows how you can create a database on an SAP HANA database system from a
selected account in the SAP HANA Cloud Platform cockpit.

Context
In your account in the SAP HANA Cloud Platform cockpit (cockpit), you create a database on an SAP HANA
database system that is enabled for multitenant database container support. Once the database is available, you
start the SAP HANA Web-based Development Workbench (Web IDE) from the cockpit and create an SAP HANA
XS Hello World. Then you run the program from the Web IDE.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

757

In the cockpit you create a binding between the database and an existing Java application. You deploy the Java
application from the cockpit and run it.
You can view the application in the browser and enter first names and last names in the table. Then switch to the
Catalog view in the Web IDE and search for the new table. Check that the names you entered are available in the
database.

Note
This document relates to beta functionality available on SAP HANA Cloud Platform. To be able to use this
functionality, please order an SAP HANA database system enabled for SAP HANA multitenant database
containers..
Please contact SAP for details at the SAP Support Portal as described at Get Support [page 1325].

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use of
the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by
the use of beta features.
Go through the relevant steps:
Table 261:
Tools

Steps
Prerequisites [page 758]
1. Create a Database in the Cockpit [page 759]

SAP HANA Cloud Platform cockpit

2. Create a Database User with Permissions for Working with Web IDE [page 760]

SAP HANA cockpit

3. Start and Work with the Web IDE [page 761]

SAP HANA Cloud Platform cockpit


SAP HANA Web-based Development
Workbench

4. Deploy the Persistence with JDBC Java Application [page 761]

Maven
Console client, SDK
SAP HANA Cloud Platform cockpit
Browser

5. View Table Content in Web IDE [page 762]

SAP HANA Web-based Development


Workbench

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Tools for Eclipse, SAP HANA Cloud Tools for
Java, and SDK. For more information, see Installing SAP HANA Tools for Eclipse [page 58] and https://
tools.hana.ondemand.com/#cloud.

758

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
The tutorial is based on the SDK for Java Web.
You have installed an SAP HANA database system enabled for multitenant database container support. This
system must be assigned to an account.
You have a user with the administrator role for the account.
You have installed Maven.

1. Create a Database in the Cockpit


You create a database in your account.
1. Log on to the cockpit on the productive landscape and select an account.
Use the relevant URL for your account type and, if you are using a customer or a partner account, the
associated region. For more information, see Account Types [page 12].
2. Choose

Persistence

Databases & Schemas

in the navigation area.

3. To create a database, choose New on the Databases & Schemas page.


The New Database/Schema screen is displayed.
4. Enter the required data:
Table 262:
Property

Value

Database ID

Example: tutorial

Database System

An example of a database system is an SAP HANA system that has multitenant


database container support enabled (productive and trial).
Example: Productive SAP HANA tenant database

mdc1 (HANAMDC)

Note
mdc1 corresponds to the database system on which you create the data
base.
Example: Trial SAP HANA tenant database

mdc2 (HANA MDC (<trial>))


SYSTEM User Password

Provide the password for the SYSTEM user of the database.

5. Choose Save.
The Events page is displayed. It shows the progress of the database creation. Wait until the tenant database is
in state Started.
6. (Optional) To view the details of the new database, choose Overview in the navigation area and select the
database in the list. Verify that the status STARTED is displayed.
Result: You have created a database.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

759

Next step: You can start the SAP HANA Web-based Development Workbench (Web IDE) to work with the new
database. To open the link to the Web IDE, you need a database user with the required permissions to work with
the Web IDE. To create the user with the required permissions, proceed as described in 2. Create a Database User
with Permissions for Working with Web IDE [page 760].

2. Create a Database User with Permissions for Working with Web IDE
You want to connect to the Web IDE and work with it. First you need to create a new database user in the SAP
HANA cockpit and assign the user the required permissions.
1. Go to the cockpit and log on to the SAP HANA cockpit with the SYSTEM user and password.
A message is displayed to inform you that at that point, you lack the roles that you need to open the SAP
HANA cockpit.
1. To open the SAP HANA cockpit, go to the database overview page in the SAP HANA Cloud Platform
cockpit.
2. Choose Persistence
in the list.

Databases & Schemas

in the navigation area and select the relevant database

3. In the database overview, open the SAP HANA cockpit link under Development Tools.
2. To confirm the message, choose OK.
You receive a confirmation that the required roles are assigned to you automatically.
3. Choose Continue.
You are now logged on to the SAP HANA cockpit.
4. Choose Manage Roles and Users.
5. To create database users and assign them the required roles, expand the Security node.
6. Open the context menu for the Users node and choose New User.
7. On the User tab, provide a name for the new user.
The user name always appears in upper case letters.
8. In the Authentication section, make sure the Password checkbox is selected and enter a password.
The password must start with a letter and only contain uppercase and lowercase letters ('a' - 'z', 'A' - 'Z'), and
numbers ('0' - '9').
9. To create the user, choose Save.
The new database user is displayed as a new node under the Users node.
10. To assign your user the roles with the required permissions for working with SAP HANA Web-based
Development Workbench, go to the Granted Roles section and choose the + (Add Role) button.
11. Type ide in the search field and select all roles in the result list.
The roles are added on the Granted Roles tab.
12. Save your changes.
13. To assign the CONTENT_ADMIN role to the user, repeat the step.
14. Make sure you save your changes.
Before you continue to work with Web IDE, make sure you log out first and log on again with your new
database user.

Caution
At this point, you are still logged on with the SYSTEM user. You can only use your new database user to work
with SAP HANA Web-based Development Workbench by logging out from SAP HANA cockpit first. Otherwise,
you would automatically log in to the SAP HANA Web-based Development Workbench with the SYSTEM user

760

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

instead of your new database user. Therefore, choose the Logout button before you continue to work with the
SAP HANA Web-based Development Workbench, where you need to log on again with the new database user.
Result: You have created a database user and assigned the user the required roles.
Next step: You continue to work with the Web IDE.

3. Start and Work with the Web IDE


Start the SAP HANA Web-based Development Workbench (Web IDE) from the cockpit and log on with your new
database user and password. Use the Editor to create an SAP HANA XS project and start it.
1. In the SAP HANA Cloud Platform cockpit, choose
area.

Persistence

Databases & Schemas

in the navigation

2. Select the relevant database in the list.


3. In the overview that is shown in the lower part of the screen, click the SAP HANA Web-based Development
Workbench link under Development Tools.
4. Log on to the Web IDE with your new database user and password.
5. Select the Editor.
The editor is displayed. The header shows details for your user and database. Hover over the entry for the SID
to view the details.

Note
Use the Logout button in the header to log on with a different user.
6. To create a new package, choose

New

Package

from the context menu for the Content folder.

7. Enter a package name.


The package appears under the Content folder node.
8. From the context menu for the new package node, choose Create Application.
9. Select HANA XS Hello World as template and choose Create.
When you click the files under the new package in the hierarchy, they open in the editor.
10. To deploy the program, select the logic.xsjs file from the new package and choose Run.
The program is deployed and displayed in the browser: Hello World from User <Your User>.

4. Deploy the Persistence with JDBC Java Application


You want to work with the application. Deploy the Persistence with JDBC sample in the cockpit, create a binding,
and start the application.
Build the War File
You have downloaded and set up your Eclipse IDE, SAP HANA Tools for Eclipse, and SDK.
For more information, see Installing SAP HANA Tools for Eclipse [page 58].
1. Open the command window and navigate to the <SDK>/samples/persistence-with-jdbc folder.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

761

2. To build the war file that you want to deploy with Maven, execute the mvn clean install command.
The generated persistence-with-jdbc.war file is available in the target folder.
Deploy the Java File
1. In the cockpit, choose

Applications

Java Applications

in the navigation area.

2. Choose Deploy Application.


3. Select the persistence-with-jdbc.war file in the target folder.
4. Enter a valid application name such as javatest.
5. Choose Java Web as the runtime.
6. Select your installed version as the runtime version.
7. Choose Deploy.
A confirmation appears when the application has been deployed.

Note
Do not choose Start. If you choose Start, a default schema and binding will be created for the database.
Create a Binding for the Database
In the cockpit, you bind the database to a Java application and start it.
1. In the cockpit, choose

Persistence

Databases & Schemas

in the navigation area.

2. Select the database in the list.


3. Choose New Binding.
4. Leave the default settings for the data source (<DEFAULT>).
5. Select your Java application.
6. Enter your user for the database and your password.
7. Save your entries.
The binding appears in the list.
Start the Application
1. Choose

Applications

Java Applications

in the navigation area.

2. To start the application, choose Start.


The changed status is indicated by the State icon.
3. Select the link for the application name.
The Application Details overview appears.
4. Select the application URL in the Application URL panel.
A browser window appears showing the Persistence with JDBC sample.
5. To add persons to the table, provide the names and choose Add Person.

5. View Table Content in Web IDE


To verify that the data you entered in the table is available, use the Web IDE.
1. To view the table in the Web IDE, you have the following options:
If the Web IDE is still open, choose

762

Navigation Links

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Catalog .

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If you need to reopen the Web IDE, proceed as described in 3. Start and Work with the Web IDE [page
761], and on the entry page choose the Catalog entry point.
2. In the tree, choose Catalog/YourUser/Tables/T_PERSONS.
3. In the table view, choose Open Content to view the table entries.

Related Information
Accounts [page 11]
Databases and Database Systems [page 770]
Creating Databases [page 783]
Managing Databases [page 781]
Creating an SAP HANA Database Using Console Client [page 763]
Installing SAP HANA Tools for Eclipse [page 58]

1.4.8.2.6

Creating an SAP HANA Database Using Console


Client

This step-by-step tutorial shows how you create a database in an SAP HANA database system with multitenant
database container support enabled, using SAP HANA Cloud Platform Console Client commands.

Context
In the console client command line, you execute the command to create a database. Once the database is
available, you use the console client command to create a binding between the database and an existing Java
application. You use the commands to deploy the Java application and run it. You can view the application in the
browser, enter first names and last names in the table, and check in SAP HANA Client that the names you entered
are available in the database.

Note
To be able to use this functionality, please order an SAP HANA database system enabled for SAP HANA
multitenant database containers.
Please contact SAP for details at the SAP Support Portal as described at Get Support [page 1325].

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use of
the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by
the use of beta features.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

763

Go through the relevant steps:


Table 263:
Steps

Tools

Prerequisites [page 764]


1. Create a Database Using Database System mdc1 [page
764]

Console client, SDK

2. Deploy Java Application (Person Sample) into Account


[page 765]

Maven
Console client, SDK

3. Create a Database User and Assign a Role [page 766]

Console client, SDK


Database tunnel
SAP HANA Client

4. Bind Java Application to the Database [page 768]

Console client, SDK

5. Start Java Application and Add Person Data with Servlet


[page 768]

Console client, SDK


Browser
SAP HANA Client

Prerequisites
You have downloaded and set up your SDK and SAP HANA client. For more information, see https://
tools.hana.ondemand.com/#cloud.

Note
The tutorial is based on the SDK for Java Web.
You have installed an SAP HANA database system enabled for multitenant database container support. This
system is assigned to an account.
You have a user with the administrator role for the account.
You have installed Maven.

1. Create a Database Using Database System mdc1


Open a command window and navigate to the <SDK>/tools folder.
Optional: Check That Database System Is Available
\tools>neo list-dbms -a multidb -h hana.ondemand.com -u myuser

764

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Output Code
SAP HANA Cloud Platform Console Client
Password for your user:
Dedicated:
DB System DB Type
DB Version
mdc1
HANAMDC
1.00.93.00.1424770727
mdc2
HANAMDC
1.00.93.00.1424770727

Create Database
\tools>neo create-db-hana -a multidb -h hana.ondemand.com --dbsystem mdc1
-u myuser -i mydb

Note
To create a tenant database on a trial landscape, use -trial- instead of the ID of a SAP HANA tenant database.

Output Code
SAP HANA Cloud Platform Console Client
Password for your user:
Password for HANA database SYSTEM user:
Repeat password for HANA database SYSTEM user:
Request to create HANA tenant database 'mydb' as part of HANA system 'mdc1' is
accepted.
The request should be processed within next 10-20 minutes. To check the status of
this
request you may use display-db-info command.
To access the SAP HANA database, provide the SYSTEM user password.
Optional: Check Status of Database Is STARTED
\tools>neo display-db-info -a multidb -h hana.ondemand.com -u myuser -i mydb
If the console client reponse is that the status is CREATING, repeat the command until the status is STARTED.

2. Deploy Java Application (Person Sample) into Account


Build Java Application from SDK Sample
1. Open the command window and navigate to the <SDK>/samples/persistence-with-jdbc folder.
2. To build the war file that you want to deploy with Maven, execute the mvn clean install command.
The generated persistence-with-jdbc.war file is available in the target folder.
3. Move the persistence-with-jdbc.war file to the <SDK>/tools folder.
Deploy the Java Application
\tools>neo deploy -h hana.ondemand.com -a multidb -b mytestapp -u myuser -s
persistence-with-jdbc.war

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

765

Output Code
SAP HANA Cloud Platform Console Client
Requesting deployment for:
application
: mytestapp
account
: multidb
source
: persistence-with-jdbc.war
host
: https://hana.ondemand.com
elasticity data
: [1 .. 1]
SDK version
: 1.75.11
user
: myuser
Password for your user:
Deployment started...
Uploading started......100%
Uploaded 49.1 KB in 7.0 s Speed: 6 KB/s
Processing started...
Processing completed in 0.0 s
Deployment finished successfully
Warning: No compute unit size was specified for the application so size was set
automatically to 'lite'.

3. Create a Database User and Assign a Role


Opening a Database Tunnel
You need the tunnel to connect to your database. You can use the connection details you obtain from the tunnel
response to connect to database clients, for example, Eclipse Data Tools Platform (DTP).

Note
The database tunnel must remain open while you work on the remote database instance. Only close the tunnel
once you have completed the session.
Open the command window and navigate to the <SDK>/tools folder.

Tip
Only use this command window for the tunnel command.
\tools>neo open-db-tunnel -a multidb -h hana.ondemand.com -i mydb -u myuser

Output Code
SAP HANA Cloud Platform Console Client
Password for your user:
Opening tunnel...
Tunnel opened.
Use these properties to connect to your schema:
Host name
: localhost
Database type
: HANAMDC
JDBC Url
: jdbc:sap://localhost:30015/
Instance number : 00
Use any valid database user for the tunnel.
This tunnel will close automatically in 24 hours or when you close the shell.

766

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Press ENTER to close the tunnel now.


Create Database User with SAP HANA Client
You create a database user with SAP HANA client.

Note
You can also create a database user with SAP HANA studio in Eclipse IDE. For more information, see Creating
an SAP HANA Database from the Cockpit [page 757].
Open a new command window and navigate to the <SAP>/hdbclient folder. Start the client to work in
interactive mode.
\hdbclient>hdbsql

Output Code
Welcome to the SAP HANA Database interactive terminal.
Type: \h for help with commands
\q to quit
Connect to the database using the connect command. Use the connection details you obtained from the tunnel
response.
hdbsql=> \c -n localhost:30015 -u system

Output Code
Password:
Connected to localhost:30015
You create the database user.
hdbsql NEO_MULTID...=> create user mydbuser password mypassword

Output Code
0 rows affected (overall time 286,192 msec; server time 11,370 msec)
Assign the Role to the Database User
You assign the content_admin to the database user.
hdbsql NEO_MULTID...=> grant content_admin to mydbuser with admin option
Log on to Database with New Database User and Change Password
If the database has a password policy that requires users to change their password after the initial logon, you need
to provide a new password, otherwise you cannot work with the servlet.
Use the quit command to log off from the hdbsql client.
hdbsql NEO_MULTID...=> \q

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

767

In the command window, restart the hdbsql client.


\hdbclient>hdbsql

Output Code
Welcome to the SAP HANA Database interactive terminal.
Type: \h for help with commands
\q to quit

hdbsql=> \c

-n localhost:30015 -u mydbuser

Output Code
Password:
You have to change your password.
Enter new Password:
Confirm new Password:
Connected to localhost:30015

4. Bind Java Application to the Database


Go to the command window you used to create the database.
\tools>neo bind-db -h hana.ondemand.com -a multidb -b mytestapp -i mydb
--db-user mydbuser -u myuser

Output Code
SAP HANA Cloud Platform Console Client
Password for your user:
Password for your database user:
Database 'mydb' bound to the default data source of the account 'multidb',
application 'mytestapp' using database user 'mydbuser'

5. Start Java Application and Add Person Data with Servlet


Start Java Application 'mytestapp'
\tools>neo start -h hana.ondemand.com -a multidb -b mytestapp -u myuser

Output Code
SAP HANA Cloud Platform Console Client
Requesting start for:
application
: mytestapp

768

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

account
: multidb
host
: https://hana.ondemand.com
synchronous
: false
SDK version
: 1.75.11
user
: myuser
Password for your user:
Start request performed successfully.
Triggered start of application process.
Status: STARTING

Optional: Check That Java Application Is Started


\tools>neo start -h hana.ondemand.com -a multidb -b mytestapp -u myuser

Output Code
SAP HANA Cloud Platform Console Client
Requesting status for:
application: mytestapp
account
: multidb
host
: https://hana.ondemand.com
SDK version: 1.75.11
user
: myuser
Password for your user:
Status: STARTED
URL: https://mytestappmultidb.hana.ondemand.com
Access points:
https://mytestappmultidb.hana.ondemand.com
Runtime: Java Web, 1.76 (valid until 16-Jul-2016)
Application processes:
ID
State
Last Change
15a9cb6
STARTED
17-Apr-2015 15:06:35

Runtime
hana-java-web 1.76.7.1

Add Person Data


Copy the URL from the status command into the address field of your browser and add /persistence-withjdbc/. Start the servlet in the browser and add person data.

Verify Person Data Exists in Database

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

769

Go to the hdbsql command window.


hdbsql=> select * from t_persons
ID,FIRSTNAME,LASTNAME
"a505a56c-aa04-4b91-b636-7b97b4185125","Michael","Adams"
"b3b0af0b-caaa-4383-892a-313e2b611ed8","Donna","Moore"

Output Code
2 rows selected (overall time 291,603 msec; server time 156 usec)

Related Information
list-dbms [page 191]
create-db-hana [page 116]
display-db-info [page 152]
deploy [page 141]
Deploying on the Cloud with the Console Client [page 983]
open-db-tunnel [page 210]
Opening a Database Tunnel [page 851]
bind-db [page 102]
start [page 240]
Databases and Database Systems [page 770]
Managing Databases [page 781]
Creating an SAP HANA Database from the Cockpit [page 757]
SAP HANA Client Installation and Update Guide

1.4.8.3

Databases and Database Systems

SAP HANA Cloud Platform account administrators can create databases on database management systems in
their account. Developers can bind databases to applications running on the cloud platform.
A database is associated with a particular account and is available to applications in this account. You can create
databases, bind them to applications, and delete them using the console client or the cockpit. You can bind the
same database to multiple applications, and the same application to multiple databases.
You can work with different database systems on the cloud platform, each of which has different capabilities and
may be suited better in a trial or a productive scenario. Read the following explanation and choose the one that fits
your scenario best.

770

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Terminology
We use the term database to refer commonly to all database types and systems currently in use with SAP HANA
Cloud Platform. Note that more specific names might be used to refer to databases in the context of the
corresponding technology. SAP Adaptive Server Enterprise(SAP ASE) speaks of user databases for example. SAP
HANA speaks of multitenant database containers (MDC), also called tenant databases.
A database management system (DBMS) is a computer system that enables administrators, developers, and
applications to interact with one or more databases and provides access to the data contained in the database. It
runs on a hardware host (or several hosts for distributed database systems) and has a version. Examples for
DBMSs are SAP HANA and SAP ASE.
A database is an organized collection of the data that can be backed up and restored separately. The database is
the technical unit that contains the data where DBMS is a service that enables users to define, create, query,
update, and administer the data. Therefore, the term database is not equivalent with the term database
system even if the term database is often used to refer to both a database and the DBMS used to access and
manage it.

Database System: SAP HANA


Table 264:
Use Case

Description

You want to use an SAP

You can use an SAP HANA database in productive mode.

HANA database on a pro


ductive landscape.

The productive SAP HANA database provides you with a database reserved for your exclusive
use, enabling you to develop with SAP HANA as with an on-premise system. You have full con
trol of user management and can use a range of tools.
For more information, see Using a Productive SAP HANA Database System [page 1010].

You want to use an SAP


HANA database on the trial
landscape.

You can try out working with an SAP HANA database on the trial landscape.
The trial SAP HANA database provides you with a single database schema or repository pack
age on a shared HANA database, enabling you to work with SAP HANA in a managed environ
ment. Your SAP HANA packages or schemas (and therefore your data) might be distributed
across different databases. Restrictions apply to ensure user and data isolation. Developers
have limited access rights. You use predefined scripts to grant additional rights and privileges.

Database System: SAP ASE


You can create SAP ASE databases on database management systems in your account and bind databases to
applications running in the cloud.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

771

Database System: SAP HANA with multitenant database container support


enabled (beta)
You receive a database reserved for you that resides in a multiple-container system (MDC, tenant database).
Hosting of multiple SAP HANA databases on a single SAP HANA database system is possible when the support
for multitenant database container is enabled for the SAP HANA databases (currently a beta feature). All tenant
databases in the same system share the same system resources (memory and CPU cores) but each tenant
database is fully isolated with its own database users, catalog, repository, persistence (data files and log files) and
services.

Restriction
To be able to use this functionality, please order an SAP HANA database system enabled for SAP HANA
multitenant database containers. It is not possible to enable SAP HANA multitenant database containers for
existing SAP HANA database systems.
Please contact SAP for details at the SAP Support Portal as described at Get Support [page 1325].

772

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 265:
Use Case

Description

You want to use an SAP

You can use a tenant database reserved for you in productive mode. However, some restric

HANA tenant database on a

tions apply.

productive landscape.

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any
productive use of the beta functionality is at the customer's own risk, and SAP shall not be
liable for errors or damages caused by the use of beta features.

Restriction
Backup

When you delete tenant databases, data and log backups are also deleted so that the
database cannot be recovered.

When you stop a tenant database for several days, it may not be possible to recover
the database. It is important to keep databases running without longer downtimes.

Monitoring

The availability of SAP HANA databases enabled for multitenant database container
support is not monitored and no alerts are sent when a database is not available.

The registration of availability checks for HANA native applications is not supported
yet.

Memory Management

Memory allocation limits must be set manually per tenant database using HANA tools
like HANA studio or HANA Web IDE. The sum of the specified allocation limits must not
exceed the memory available for tenant databases. There is no overview available on
database system level regarding actual memory consumption and specified memory
limits.

If the specified memory limit for a certain tenant database is exceeded, the connection
to the tenant database may not be possible anymore until the tenant database is re
started or the limit is increased by HCP operators.

Be aware that setting tight memory limits for tenant databases may lead to failing
backups and a recovery may not always be possible.

Connectivity

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Certificate-based authentication is not supported when accessing services provided


by SAP HANA Cloud Platform, for example, the Document service.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

773

Use Case

Description

You want to use an SAP

You can try out working with a tenant database on the trial landscape.

HANA tenant database on


the trial landscape.

The trial tenant database offers you the same user experience as the productive tenant data
base. You create a trial tenant database in the same way with the only difference that you se
lect the database system HANA MDC (<trial>).
Some restrictions apply when using a trial tenant database:

Restriction

You can create your own trial database on a shared HANA MDC system. The persis
tence service determines to which database system the tenant is assigned.

You can create only one trial tenant database in the account.

Trial databases are configured using fixed quota for RAM and CPU.

You can use the trial tenant database for 12 hours. It will be shut down automatically
after this period to free resources.

If you do not use the tenant database for 7 days, it will be deleted automatically.

There are some other restrictions which HANA features can be used in the trial sce
nario and which not.

Related Information
Managing Database Systems [page 774]
Database System Commands [page 781]
Managing Databases [page 781]
Database Commands [page 803]
Managing Schemas [page 804]
SAP HANA: Development [page 1008]
Creating SAP HANA MDC Databases [page 784]
Creating SAP ASE Databases [page 786]

1.4.8.3.1

Managing Database Systems

You can manage the database systems available in your account on the cloud platform.

Prerequisites
You have the Administrator role for the account.

774

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Overview
A database management system (DBMS) is a computer system that enables administrators, developers, and
applications to interact with one or more databases and provides access to the data contained in the database. It
runs on a hardware host (or several hosts for distributed database systems) and has a version. Examples for
DBMSs are SAP HANA and SAP ASE.
A database is an organized collection of the data that can be backed up and restored separately. The database is
the technical unit that contains the data where DBMS is a service that enables users to define, create, query,
update, and administer the data. Therefore, the term database is not equivalent with the term database
system even if the term database is often used to refer to both a database and the DBMS used to access and
manage it.
SAP HANA Cloud Platform account administrators can create databases on database management systems in
their account. You can use the cockpit or the console client to manage the database systems in the cloud. Typical
tasks that you perform for database management systems are installing and updating database systems,
monitoring, or restart.

Note
We do not offer database systems on the trial landscape.
You can view all the information related to database systems in the cockpit. Start on the dashboard for a selected
account by checking the number of available database systems. Navigate to Persistence Database Systems
and drill down to the level of individual database systems to trigger actions like restart, install, or update.
The following sections are about tasks you perform related to database systems in the cloud.

Related Information
Database System Commands [page 781]
Installing SAP HANA Components [page 776]
Updating Database Systems [page 778]
Restarting Database Systems [page 780]
Managing Databases [page 781]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

775

1.4.8.3.1.1 Installing SAP HANA Components


Learn how to install new SAP HANA components.

Prerequisites
Basic authentication must be enabled for SAP HANA Application Lifecycle Management to be able to install SAP
HANA XS-based components. You can check and enable basic authentication using the SAP HANA XS
Administration Tool. Navigate to the sap/hana/xs/lm package and add Basic in the Authentication section.

Context
You can install the following types of SAP HANA components:
SAP HANA platform components, which are installed on the SAP HANA database system on operating
system level
SAP HANA XS applications, which are deployed on the SAP HANA database system

Note
You can install only SAP HANA components, which are enabled in your account.

Restriction
Installation of SAP HANA XS-based components on SAP HANA database systems, which are configured to
support SAP HANA multitenant database containers, is currently not supported.
Installation of SAP HANA XS-based components is supported on SAP HANA database systems with version
SPS09 or higher.

Recommendation
We recommend always using the latest available version.
Please expect a temporary downtime for the SAP HANA database or SAP HANA XS Engine when installing some
SAP HANA components. You might not be able to work with SAP HANA studio, SAP HANA Web-based
Development Workbench, and cockpit UIs that depend on SAP HANA XS.

Procedure
1. Log on to the cockpit with the administrator role on the productive landscape and select an account.
2. Choose

776

Persistence

Database Systems

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

in the navigation area.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

All database systems available in the account are listed with their details, including the database type, version,
memory size, state, and the number of associated databases.

Tip
To view the details of a database, for example, its state and the number of existing bindings, select a
database in the list and click the link on its name. On the overview of the database, you can perform further
actions, for example, delete the database.
3. To select the entry for the relevant database system in the list, click the link on its name.
The overview of the database system shows details, including the database version and state, and the number
of associated databases.
4. To install an SAP HANA component for the selected productive database system, choose Install components.
All solutions which are available for the installation are listed.
5. Select a solution to install.
If you have a license for the solution in your account, all SAP HANA components, which are part of the
solution, are listed.
6. Select the target version for all listed components.
7. (Optional) Specify if you would like the installation process to stop and prompt for confirmation before the
SAP HANA components are installed and the system downtime is started.
This option is selected by default. If you deselect it, the installation is performed without any user interaction.
8. Choose Continue/Install.
The system begins preparing to install. The installation process will take some time and is executed
asynchronously. The installation dialog box remains on the screen while the installation is in progress. It is
safe to close the dialog box and reopen it later.
9. (Optional) If you chose to be prompted for confirmation after preparation of the installation, the installation
process will stop and prompt for your confirmation to start the installation.
While preparing the installation, the SAP HANA database system is not modified, so it is safe to cancel the
installation process.
10. Choose Install.
The installation starts and takes about 20 minutes.

Results
SAP HANA components are installed on your SAP HANA database system.

Related Information
SAP HANA XS Administration Tools
SAP HANA Developer Guide SAP HANA XS Application Authentication

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

777

1.4.8.3.1.2 Updating Database Systems


Learn about the activities that you need to perform to update your SAP HANA database systems.

Prerequisites
Basic authentication must be enabled for SAP HANA Application Lifecycle Management to be able to update SAP
HANA XS-based components. You can check and enable basic authentication using the SAP HANA XS
Administration Tool. Navigate to the sap/hana/xs/lm package and add Basic in the Authentication section.

Context
To update your SAP HANA database systems, you have the following options:
Update the software components installed on your SAP HANA database system to a higher version
Apply a single Support Package on top of an existing SAP HANA database system

Remember
Make sure that you read the SAP Notes listed in the UI before the update. Apply all the steps required before or
after the update.

Recommendation
We recommend always using the latest available version. For more information about the availability of new
HANA revisions for the update, please refer to the release notes
of SAP HANA Cloud Platform. To ensure
that you can use a new HANA revision for productive use, check whether it is marked as production-ready in
SAP Note 2021789
- SAP HANA Revision and Maintenance Strategy.
Please expect a temporary downtime for the SAP HANA database or SAP HANA XS Engine when updating SAP
HANA. You might not be able to work with SAP HANA studio, SAP HANA Web-based Development Workbench,
and cockpit UIs that depend on SAP HANA XS.

Procedure
1. Log on to the cockpit with the administrator role on the productive landscape.
2. Select an account.
3. Choose

Persistence

Database Systems

in the navigation area.

All database systems available in the account are listed with their details, including the database type, version,
memory size, state, and the number of associated databases.

778

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tip
To view the details of a database, for example, its state and the number of existing bindings, select a
database in the list and click the link on its name. On the overview of the database, you can perform further
actions, for example, delete the database.
4. To select the entry for the relevant database system in the list, click the link on its name.
The overview of the database system shows details, including the database version and state, and the number
of associated databases.
5. To update an SAP HANA database system, choose Check for updates.
All versions available for the specified productive SAP HANA database system are listed.
6. Select a version to update.
Remember to read the corresponding release note if you select the option to update to a higher version.

Note
You can select SAP HANA revisions approved for use in SAP HANA Cloud Platform only. If you want to
update to another revision, please contact SAP Support.
Updating a SAP HANA database system to a maintenance revision can result in upgrade path limitations.
See SAP Note 1948334
for details.
7. (Optional) Specify if you would like the update process to stop and prompt for confirmation before the update
of the SAP HANA database system is applied and the system downtime is started.
This option is selected by default. If you deselect it, the update is performed without any user interaction.
8. Choose Continue/Update.
The system begins preparing to update. The update process will take some time and is executed
asynchronously. The update dialog box remains on the screen while the update is in progress. It is safe to
close the dialog box and reopen it later.
9. (Optional) If you chose to be prompted for confirmation after preparation of the update, the update process
will stop and prompt for your confirmation to start the update.
While preparing the update, the SAP HANA database system is not modified, so it is safe to cancel the update
process.
10. Choose Update.
The update starts and takes about 20 minutes.

Results
Your SAP HANA database system has been updated.

Related Information
SAP HANA XS Administration Tools

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

779

SAP HANA Developer Guide SAP HANA XS Application Authentication


SAP Note 1948334 - SAP HANA Database Update Paths for Maintenance Revisions
SAP Note 2021789 - SAP HANA Revision and Maintenance Strategy

1.4.8.3.1.3 Restarting Database Systems


You can restart the database system.

Context
If your databases are not working properly, you can try to solve the issues by restarting the corresponding SAP
HANA database system. The restart is done for the whole database system.

Procedure
1. Log on to the cockpit and select an account for which SAP HANA database systems are available.
2. Choose

Persistence

Database Systems

in the navigation area.

3. To select the entry for the relevant database system in the list, click the link on its name.
4. In the overview of the database system, choose Restart.

Results
During the restart, you can monitor the system status using the HANA tools. Connected applications and
database users cannot access the system until it is restarted. The restart for the database system is complete
when HANA tools like SAP HANA cockpit are available again.

Next Steps
To restart an SAP HANA database system from the console client, use the restart-hana [page 220]
command.
To restart a single tenant database instead of the whole database system, use the stop-db-hana [page 246]
and start-db-hana [page 241] commands or the cockpit.

780

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.3.1.4 Database System Commands


The persistence service provides a set of console client commands for managing database systems. For example,
you can list database systems available for an account or restart a whole SAP HANA database system.

Related Information
list-dbms [page 191]
bind-hana-dbms [page 104]
restart-hana [page 220]
unbind-hana-dbms [page 252]
Managing Database Systems [page 774]

1.4.8.3.2

Managing Databases

You can create databases, bind them to applications running on the cloud platform, and delete them.

Note
This section explains working with SAP HANA multitenant database containers (MDC - also called tenant
databases), and SAP ASE databases.
For more information about working with SAP HANA database systems (using schemas instead of tenant
databases), see Managing Schemas [page 804] and SAP HANA: Development [page 1008].

Create
You can create databases on database management systems in your account and assign properties like database
size. The database is independent of any single application and has to be explicitly bound.
You can use a freely definable database ID. What elements you are allowed to use depends on the database type
that you create. A database ID must only occur once throughout the databases in an account. Remember that the
physical database name is not the same as the database ID.
You can create databases using the cockpit and the console client. In the cockpit, you can create databases at the
account, the application, and the database system level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

781

Bind
Bindings are identified by a data source name, which must only occur once in any one application. You can bind
databases to applications based on an explicitly named data source or using the default data source. The main
differences are as follows:
Explicitly named data source
When you bind the database to an application, you specify a data source name. This establishes a named
binding between the database and application, and allows the database to be addressed by the application.
The data source name is equivalent to the name used for the JNDI lookup.
Named bindings allow an application to be bound to more than one database and, in turn, to use more than
one database at the same time. The databases can be distinguished by the binding names.
Default data source
The database is bound to the application without an explicitly specified data source name, and is
consequently associated with the default data source. The following applies:
The database can be addressed by the application by any name.
The default data source is a convenient option for applications that require only one database. An
application bound to the default data source cannot be bound to any additional databases.
You can share a database between applications by binding the same database to more than one application.
Remember the following when binding databases to applications:
An applications bindings are based on either named data sources or the default data source. An application
cannot use a combination of the two types of bindings.
When named data sources are used, binding names must only occur once in any one application.
When you bind the database to an application, you specify a custom logon, which consists of a database user
name and a password, that is then used by the application to access the database.

Delete
You should drop a database if it is no longer required, or if you want to redeploy an application from scratch
cleaning old data.
Before deleting a database, you should explicitly remove any bindings that still exist between the database and an
application. You can also remove all bindings by enforcing deletion of the database by executing the
corresponding console client command.

Restart
If your databases are not working properly, you can try to solve the issues by restarting either the whole SAP
HANA database system, or a single tenant database.
To restart a single tenant database instead of the whole database system, use the stop-db-hana [page 246] and
start-db-hana [page 241] commands or the cockpit.
For more information about restarting a SAP HANA database system, see Restarting Database Systems [page
780].

782

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Creating Databases [page 783]
Creating an SAP HANA Database from the Cockpit [page 757]
Creating an SAP HANA Database Using Console Client [page 763]
Binding Databases [page 787]
Database Commands [page 803]

1.4.8.3.2.1 Creating Databases


Use the cockpit to create databases on database management systems in your account and assign properties like
database size.

Context
In the cockpit, you can create databases at the account and the database system level. The procedures below
describe how to create a database at the account level.

Note
To create a database at the database system level, choose Persistence Database Systems in the
navigation area at the account level. Select a database system in the list. Choose Databases in the navigation
area at the database system level. Then choose New Database and enter the required details.
For more information, see:
Creating SAP HANA MDC Databases [page 784]
Creating SAP ASE Databases [page 786]

Related Information
Cockpit [page 84]
Database Commands [page 803]
Databases and Database Systems [page 770]
Managing Databases [page 781]
Creating Databases [page 783]
Binding Databases [page 787]
create-db-ase [page 114]
create-db-user-ase [page 117]
delete-db-ase [page 127]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

783

delete-db-user-ase [page 129]


create-db-hana [page 116]
delete-db-hana [page 128]
set-db-properties-hana [page 233]
start-db-hana [page 241]
stop-db-hana [page 246]
Creating SAP HANA MDC Databases [page 784]
Creating SAP ASE Databases [page 786]
Creating an SAP HANA Database from the Cockpit [page 757]
Creating an SAP HANA Database Using Console Client [page 763]

1.4.8.3.2.1.1 Creating SAP HANA MDC Databases


Use the cockpit to create an SAP HANA database enabled for multitenant database container support (beta) on
an SAP HANA database management system in your account.

Context
The procedure below describes how to create a database at the account level.

Procedure
1. Log on to the cockpit and select an account.
2. Choose Persistence Databases & Schemas in the navigation area.
All databases available in the selected account are listed with their ID, type, version, and related database
system.

Tip
To view the details of a database, for example, its state and the number of existing bindings, select a
database in the list and click the link on its name. On the overview of the database, you can perform further
actions, for example, delete the database.
3. To create a database, choose New on the Databases & Schemas page.
The New Database/Schema screen is displayed.
4. Specify a Database ID.
A database ID is freely definable, but must start with a letter and include lowercase letters ('a' - 'z') and
numbers ('0' - '9') only. Remember that the physical database name is not the same as the database ID.
5. Select a Database System from the dropdown box, for example HANA MDC (<trial>).
6. Specify the SYSTEM user password to access the database.

784

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

7. (Optional) Select the parameters.


For details, please see the documentation for the create-db-hana command.
8. Choose Save.

Results
The Events page is displayed. It shows the progress of the database creation. Wait until the tenant database is in
state Started.

Next Steps
You can perform further actions for the newly created database, for example, configure, or delete it. Proceed as
follows:
To create bindings for the database, choose Data Source Bindings in the navigation area.
To monitor the progress of the database creation in detail, choose Events in the navigation area.
To delete a database, first delete all existing bindings to the database. In the overview of the database, choose
the Delete button. It is only enabled if a database does not have any bindings.

Related Information
Cockpit [page 84]
Creating Databases [page 783]
Database Commands [page 803]
Databases and Database Systems [page 770]
Managing Databases [page 781]
Creating Databases [page 783]
Binding Databases [page 787]
create-db-hana [page 116]
delete-db-hana [page 128]
set-db-properties-hana [page 233]
start-db-hana [page 241]
stop-db-hana [page 246]
Creating an SAP HANA Database from the Cockpit [page 757]
Creating an SAP HANA Database Using Console Client [page 763]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

785

1.4.8.3.2.1.2 Creating SAP ASE Databases


Use the cockpit to create an SAP ASE database on an SAP ASE database management system in your account
and assign properties like database size.

Context
The procedure below describes how to create a database at the account level.

Procedure
1. Log on to the cockpit and select an account.
2. Choose Persistence Databases & Schemas in the navigation area.
All databases available in the selected account are listed with their ID, type, version, and related database
system.

Tip
To view the details of a database, for example, its state and the number of existing bindings, select a
database in the list and click the link on its name. On the overview of the database, you can perform further
actions, for example, delete the database.
3. To create a database, choose New on the Databases & Schemas page.
The New Database/Schema screen is displayed.
4. Specify a Database ID.
A database ID is freely definable, but must start with a letter and include lowercase letters ('a' - 'z'), numbers
('0' - '9'), and the special character '.' only. Remember that the physical database name is not the same as the
database ID.
5. Select a Database System from the dropdown box, for example name (ASE).
6. Specify the size of the database in MB.
This parameter sets the maximum database size. The minimum database size is 24 MB. An error message
appears if you enter a database size that exceeds the quota for this database system.
7. Specify a database user.
The user is created for you on the database and enables you to access the database.
8. Specify the database user password to access the database.
9. Choose Save.

786

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
The Events page is displayed. It shows the progress of the database creation. Wait until the database is in state
Started.

Next Steps
You can perform further actions for the newly created database, for example, configure, or delete it. Proceed as
follows:
To create bindings for the database, choose Data Source Bindings in the navigation area.
To monitor the progress of the database creation in detail, choose Events in the navigation area.
To delete a database, first delete all existing bindings to the database. In the overview of the database, choose
the Delete button. It is only enabled if a database does not have any bindings.

Related Information
Cockpit [page 84]
Creating Databases [page 783]
Database Commands [page 803]
Databases and Database Systems [page 770]
Managing Databases [page 781]
Creating Databases [page 783]
Binding Databases [page 787]
create-db-ase [page 114]
create-db-user-ase [page 117]
delete-db-ase [page 127]
delete-db-user-ase [page 129]

1.4.8.3.2.2 Binding Databases


Bind databases to your applications running on the cloud platform.

Context
In the cockpit, you can create and delete database bindings at both the database and application level:
To create bindings by database, use the Data Source Bindings panel at the database level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

787

To create bindings by application, use the Data Source Bindings panel at the application level.

Procedure
1. Log on to the cockpit and select an account.
2. Choose one of the following options:
To create bindings...
By database

Do the following
1.

Choose
Persistence Databases & Schemas in the navigation area.
All databases available in the selected account are listed with their ID, type, version,
and related database system.

2. Select the database that you want to create a binding for.


The overview shows the database details, for example, its state, and the number of ex
isting bindings, and provides access to further actions.
3. Choose Data Source Bindings in the navigation area.
The overview shows the bindings available for the specific database.
4. Choose the New Binding button.
5. In the New Binding screen, enter the following details:
1. Enter a data source name.
2. Select the application that you want the database to be bound to.

Note
The application must be deployed in the selected account.
3. Enter a database user name and a password in the Custom Logon section and
save your entries.
By application

1.

Choose
Applications Java Applications
relevant application in the application list.

in the navigation area and select the

2. Choose
Configuration Data Source Bindings in the navigation area.
The overview shows the bindings available for the specific application.
3.
4.
5.
6.

Choose the New Binding button.


Enter a data source name.
Select the database that you want the application to be bound to.
(optional) If the database does not already exist, create it first. For more information,
see Creating Databases [page 783].
7. Enter a database user name and a password in the Custom Logon section and save
your entries.

Note
The Custom Logon consists of a database user name and password used specifically to bind databases
to Java applications. The specified database user, in effect a schema owner, determines which
schemas the Java application can access.
To create a binding to the default data source, enter the data source name <DEFAULT>.
An application that is bound to the default data source (shown as <DEFAULT>) cannot be bound to any
other databases. To use other databases, first rebind the application using a named data source.

788

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Data source names are freely definable but need to match the JNDI data source names used in the
corresponding applications, as defined in the web.xml or persistence.xml file. For more
information, see the example scenarios.

Next Steps
The state of an application decides when a newly bound database will become effective. If an application is already
running (Started state), it will continue using the old database until restarted. A restart is also required if
additional databases have been bound to the application.

Note
To unbind a database from an application, simply delete the binding. The application will maintain access to the
database until restarted.

Related Information
Cockpit [page 84]
Creating Databases [page 783]
Creating an SAP HANA Database from the Cockpit [page 757]
Creating an SAP HANA Database Using Console Client [page 763]
create-db-ase [page 114]
create-db-hana [page 116]
bind-db [page 102]
unbind-db [page 250]

Create an SAP HANA Database User


Procedure
1. Open the SAP HANA Administration Console in Eclipse.
2. In the Systems view, choose

Security

Users .

3. From the context menu, choose New User.


4. On the New User screen, enter a unique user name and password. Enter the password a second time to
confirm and then save your entries.
The new user now appears in the Users folder. A new schema has been automatically created in the catalog
with an identical name, but is not visible under your current logon.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

789

Note
By default, the user has the permissions required to use the new schema. You can assign the user
additional permissions or remove permissions, as necessary.
5. Log off and then reconnect to the SAP HANA system using the database user and password you just created.
6. Change the initial password when prompted.

Note
Remember to change the initial password before binding the HANA database to the application, since the
application will otherwise throw an exception.
7. In the Systems view, expand the Catalog node. You should see a schema with the same name as your
database user.

Related Information
Managing SAP HANA Users
Setting Up Roles and Authorizations
SAP HANA User and Role Management
Using a Productive SAP HANA Database System [page 1010]

Create an SAP ASE Database User


Procedure
In the console client command line, execute the create-db-user-ase command. This command creates a user
for an SAP ASE database.

Related Information
Console Client [page 88]
create-db-user-ase [page 117]

790

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.3.2.2.1 Database Users with Multiple Schemas


When using custom logons, the database user specified determines which schemas an application is able to
access. Typically the application uses the database users default schema, but since a database user may have
access to more than one schema, it could potentially use any of these schemas.

Default Schemas
The default schema is the schema whose name is identical to that of the database user. It is created automatically
when a database user is created.
We recommend working with a database users default schema. If you require multiple schemas, simply create
separate appropriately named database users and then bind each of their default schemas to the application
using named data sources. If you choose to use non-default schemas, be aware that this is more error prone and
requires greater care with the application code.

Non-default Schemas
An application can access a non-default schema in its program code by adding the schema name as a prefix to the
table name as follows: <schema name>.<table name>
When programming with JPA, you add the schema prefix to the table annotation in the JPA entity class.

Example
Table T_PERSON in the schema COMPANYDATA:
@Entity
@Table(name = "COMPANYDATA.T_PERSON")
For JDBC, all occurrences of the table names in SQL statements require the schema prefix.

Example
Table T_PERSONS in the schema COMPANYDATA:
Table 266:
INSERT

"INSERT INTO COMPANYDATA.T_PERSONS (ID, FIRSTNAME, LASTNAME) VALUES (?, ?, ?)"

SELECT

"SELECT ID, FIRSTNAME, LASTNAME FROM COMPANYDATA.T_PERSONS"

CREATE

"CREATE TABLE COMPANYDATA.T_PERSONS (ID VARCHAR(255) PRIMARY KEY NOT NULL,


FIRSTNAME VARCHAR (255), LASTNAME VARCHAR (255))"

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

791

Note
When you retrieve database metadata in order to check whether a table already exists, bear in mind that you
might also need to specify the schema parameter, in particular, if you have multiple schemas containing tables
with identical names:
DatabaseMetaData meta = conn.getMetaData();
ResultSet rs = meta.getTables(null, <schema-name>, <table-name>, null);

Example
DatabaseMetaData meta = conn.getMetaData();
ResultSet rs = meta.getTables(null, "COMPANYDATA", "T_PERSONS", null);

1.4.8.3.2.3 Binding SAP HANA Databases to Java Applications


Java applications deployed on the SAP HANA Cloud Platform can be assigned one or more database schemas.
For developing Java applications on productive SAP HANA databases, custom logons allow you to control which
schemas an application is able to access.

Prerequisites
You have installed the required tools. See Installing SAP HANA Tools for Eclipse [page 58].
You have connected to the productive SAP HANA database from Eclipse. See Connecting to SAP HANA
Databases via the Eclipse IDE [page 861].
You have set up the console client. See Setting Up the Console Client [page 42].
You have created a database user that you use to access the database. See Creating a Database
Administrator User [page 1014].

Context
Productive SAP HANA databases are designed for developing with SAP HANA in a productive environment and
provide you with a database reserved for your exclusive use. When you bind Java applications to a productive SAP
HANA database, you specify a custom logon, which consists of an SAP HANA database user, in effect the relevant
schema owner, and a password. The database user is then used by the application to access the SAP HANA

792

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

database. Since a database user is by default associated with a schema of the same name, the application will also
by default use this schema, as shown below:

To use a custom logon, complete the following steps:


1. Create an SAP HANA database user. You can use Eclipse (as described below) or the SAP HANA Web-based
Development Workbench.
2. Bind the HANA database to the Java application using the new database user. You can use the cockpit or
console client.

Create an SAP HANA Database User


Procedure
1. Open the SAP HANA Administration console in Eclipse.
2. In the Systems view, choose

Security

Users .

3. From the context menu, choose New User.


4. On the New User screen, enter a unique user name and password. Enter the password a second time to
confirm and then save your entries.
The new user now appears in the Users folder. A new schema has been automatically created in the catalog
with an identical name, but is not visible under your current logon.

Note
By default, the user has the permissions required to use the new schema. You can assign the user
additional permissions or remove permissions, as necessary.
5. Log off and then reconnect to the SAP HANA system using the database user and password you just created.
6. Change the initial password when prompted.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

793

Note
Remember to change the initial password before binding the HANA database to the application, since the
application will otherwise throw an exception.
7. In the Systems view, expand the Catalog node. You should see a schema with the same name as your
database user.

Related Information
Managing SAP HANA Users
Setting Up Roles and Authorizations
SAP HANA User and Role Management
Using a Productive SAP HANA Database System [page 1010]

Bind the HANA Database to the Java Application (Cockpit)


In the cockpit, you can create bindings at both the account and application level, that is, by HANA database or by
Java application.

Procedure
1. Log on to the cockpit and select an account.
2. Choose one of the following options:
To create bindings...
By HANA database

Do the following
1.

In the navigation area, choose one of the following:

Persistence

Database Systems

: In the list, select the relevant database

system. Choose Databases in the navigation area at the database system level. In
the list, select the relevant SAP HANA database.

Persistence

Databases & Schemas

: In the list, select the relevant SAP

HANA database.

Note
For productive SAP HANA databases, the ID is identical to the database system
name.
2. Choose Data Source Bindings in the navigation area.
The overview lists all Java applications that the specified SAP HANA database is cur
rently bound to, including the custom logon used in each case.

794

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To create bindings...

Do the following
3. Choose the New Binding button.
4. In the New Binding dialog box, enter a data source name and the name of the applica
tion that you want the productive HANA database to be bound to.

Note

The specified application must be deployed in the selected account.

To create a binding to the default data source, enter the data source name

<DEFAULT>.
5. Enter the custom logon details:

Database user: The applicable schema owner in the SAP HANA system.

Password: The specified database users password.

6. Save your entries.


By Java application

1.

Choose

Applications

Java Applications

in the navigation area and select the

relevant application in the application list.


2. Choose

Configuration

Data Source Bindings

in the navigation area.

The overview lists all applications that the selected application is currently bound to.
Note that when an application is bound to a productive SAP HANA database, the data
base ID is identical to the database name.
3. Choose the New Binding button.
4. Enter a data source name.
5. In the Database ID field, enter the productive SAP HANA database to which the appli
cation should be bound.
6. Enter the custom logon details:

Database user: The applicable schema owner in the SAP HANA system.

Password: The specified database users password.

7. Save your entries.

Next Steps
An applications state influences when a newly bound SAP HANA database becomes effective. If an application is
already running (Started state), it will not have access to the newly bound HANA database until it has been
restarted.

Related Information
Cockpit [page 84]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

795

Bind the HANA database to the Java Application (Console


Client)
Procedure
1. Open the command window in the <SDK>/tools folder and enter the following command, replacing the
values as appropriate:
neo bind-hana-dbms --account <account_name> --host <landscape_host> -application <application_name> --user <e-mail_or_user> --id
<productive_HANA_database> --db-user <HANA_database_user> --db-password
<database_user_password>
Example:
neo bind-hana-dbms --account myaccount --host hana.ondemand.com --application
myapp --id myhana --db-user MYSCHEMA --db-password SECRET
Note that in this example a data source name has not been specified and the application therefore uses the
default data source.
2. Optionally check that the HANA database has been bound:
neo list-application-datasources --account <account_name> --host
<landscape_host> --application <application_name> --user <e-mail_or_user>
For the example above, the output should show the following:
Table 267:
Schema ID

DB Type

Data Source

Database User

myhana

hanaxs

<DEFAULT>

MYSCHEMA

Related Information
bind-hana-dbms [page 104]
unbind-hana-dbms [page 252]
list-application-datasources [page 185]
Database Users with Multiple Schemas [page 791]

1.4.8.3.2.3.1 Database Users with Multiple Schemas


When using custom logons, the database user specified determines which schemas an application is able to
access. Typically the application uses the database users default schema, but since a database user may have
access to more than one schema, it could potentially use any of these schemas.

796

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Default Schemas
The default schema is the schema whose name is identical to that of the database user. It is created automatically
when a database user is created.
We recommend working with a database users default schema. If you require multiple schemas, simply create
separate appropriately named database users and then bind each of their default schemas to the application
using named data sources. If you choose to use non-default schemas, be aware that this is more error prone and
requires greater care with the application code.

Non-default Schemas
An application can access a non-default schema in its program code by adding the schema name as a prefix to the
table name as follows: <schema name>.<table name>
When programming with JPA, you add the schema prefix to the table annotation in the JPA entity class.

Example
Table T_PERSON in the schema COMPANYDATA:
@Entity
@Table(name = "COMPANYDATA.T_PERSON")
For JDBC, all occurrences of the table names in SQL statements require the schema prefix.

Example
Table T_PERSONS in the schema COMPANYDATA:
Table 268:
INSERT

"INSERT INTO COMPANYDATA.T_PERSONS (ID, FIRSTNAME, LASTNAME) VALUES (?, ?, ?)"

SELECT

"SELECT ID, FIRSTNAME, LASTNAME FROM COMPANYDATA.T_PERSONS"

CREATE

"CREATE TABLE COMPANYDATA.T_PERSONS (ID VARCHAR(255) PRIMARY KEY NOT NULL,


FIRSTNAME VARCHAR (255), LASTNAME VARCHAR (255))"

Note
When you retrieve database metadata in order to check whether a table already exists, bear in mind that you
might also need to specify the schema parameter, in particular, if you have multiple schemas containing tables
with identical names:
DatabaseMetaData meta = conn.getMetaData();
ResultSet rs = meta.getTables(null, <schema-name>, <table-name>, null);

Example
DatabaseMetaData meta = conn.getMetaData();

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

797

ResultSet rs = meta.getTables(null, "COMPANYDATA", "T_PERSONS", null);

1.4.8.3.2.4 Accessing Databases Across Accounts


You can bind productive SAP HANA and SAP ASE databases to applications in other accounts.
Databases can be used by applications in the same account. You can give applications in other accounts
(consumer account) controlled access to productive SAP HANA databases and SAP ASE databases in your
account.
The table below lists the commands used for binding and specifies the database (or database system, as
applicable):
Table 269:
Command

Database

bind-hana-dbms

Productive SAP HANA database system

bind-db

SAP HANA database with multitenant database container


(MDC) support enabled (tenant database)
SAP Adaptive Server Enterprise (SAP ASE) database

Restriction
Binding an application to a database in another account works only using the SAP HANA Cloud Platform
console client, not with the cockpit.
When an external application, that is, an application that does not belong to your account, requests access to one
or more of your databases, you can give access permission to that application by generating an access token. The
other account might be one of your own accounts or a third-party account. The token uniquely identifies the
access permission based on the following:
Account giving the access permission
Database ID
Consumer account and application
The access token is used by the consumer account to bind the database to the application in its own account. You
can use this token as long as application bindings exist or until the permission is revoked. An unbind operation
does not require an access token. You use the access token parameter for the bind command instead of the
database ID parameter.
The following applies for an access token:
Always applies to one database and one application and is not transferrable
Has an unlimited validity period
Can be revoked whenever you wish, irrespective of whether the target application has already been bound to
the database

798

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Restriction
This functionality is not available for SAP MaxDB.
To give access permission, create a database user and a password and provide it together with the access token
to the consumer account member.

Related Information
Providing Access to Databases for Other Accounts [page 799]
bind-hana-dbms [page 104]
bind-db [page 102]

1.4.8.3.2.4.1 Providing Access to Databases for Other


Accounts
As an account member with the administrator or developer role, you can give applications in other accounts
controlled access to productive SAP HANA and SAP ASE databases databases in your account.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
To give access permission, you generate an access token using the grant-schema-access command that
allows the requesting application to access your database from its account.
The following example data is used in the procedure below:
Account (database owner): owner
Host: hana.ondemand.com
Database: database1

Note
This must be a SAP HANA database, a SAP HANA database enabled for multitenant database container
support, or a SAP ASE database.
Account (consumer account): salescorp

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

799

Application (consumer account): salesapp

Procedure
Open the command window in the <SDK>/tools folder and enter the following command:
neo grant-schema-access --account owner --host hana.ondemand.com --user myuser --id
database1 --application salescorp:salesapp

Note
Specify the requesting application in the format <account>:<application>.
If generated successfully, the access token (an alphanumeric string) is displayed.

Next Steps
The consumer account member can now use the generated access token to bind the application to the database.
To give access permission, create a database user and a password and provide it together with the access token
to the consumer account member.

Related Information
grant-schema-access [page 165]
Binding Databases in Other Accounts [page 800]
Revoking Access to Databases [page 802]
Using a Productive SAP HANA Database System [page 1010]

1.4.8.3.2.4.2 Binding Databases in Other Accounts


To bind productive SAP HANA and SAP ASE databases to applications in other accounts, you use a remote
access token that indicates that access to the database has been permitted.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].
You have received an access token and a database user and password from the database owner.

800

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
When you bind Java applications to the specified database in other accounts, you provide a database user and
password that you have received from the database owner. You can use this token as long as application bindings
exist or until the permission is revoked.

Note
The token is not transferrable to other applications in your account. The owner account can revoke access to
the database at any point in time.
The following example data is used in the procedure below:
Account (database owner): owner
Host: hana.ondemand.com
Database: database1
Account (consumer account): salescorp
Application (consumer account): salesapp
Data source: jdbc/dshana

Procedure
1. Open the command window in the <SDK>/tools folder and enter the following command:
Table 270:
Database

Command

Productive SAP HANA database system

neo bind-hana-dbms --account


salescorp --application salesapp -host hana.ondemand.com --user
salesuser --access-token
vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf
1c6uu8b9pt9z --db-user
<HANA_database_user> --db-password
<database_user_password>

SAP HANA and SAP ASE database

neo bind-db --account salescorp -application salesapp --host


hana.ondemand.com --user salesuser -access-token
vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf
1c6uu8b9pt9z --db-user
<HANA_database_user> --db-password
<database_user_password>

Note that you use the access-token parameter instead of the database ID parameter.
2. Optionally check that the database has been successfully bound:
neo list-application-datasources --account salescorp --application salesapp -host hana.ondemand.com --user salesuser

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

801

You bound your application successfully to the database in the other account.

Related Information
grant-schema-access [page 165]
bind-hana-dbms [page 104]
bind-db [page 102]

1.4.8.3.2.4.3 Revoking Access to Databases


You receive permission from a database owner to bind your applications to a specific database in another
account. The permission applies to this database only and is identified by an access token. It is valid until it is
revoked by a member of the owner account.

Context
The following example data is used in the procedure below:
Account (database owner): owner
Host: hana.ondemand.com
Database: database1
Account (consumer): salescorp
Application (consumer): salesapp

Procedure
1. Open the command window in the <SDK>/tools folder and enter the following command to list all
permissions for the specified database:
neo list-schema-access-grants --account owner --host hana.ondemand.com --user
myuser --id database1
Example output:
Table 271:

802

Access Token

Database ID

Provided To

Bound

vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1
c6uu8b9pt9z

database1

salescorp:salesapp

yes

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. To revoke the permission, enter the following command and copy across the access token obtained in the
previous step:
neo revoke-schema-access --account owner --host hana.ondemand.com --user myuser
--access-token vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1c6uu8b9pt9z
We highly recommend that you also delete the database user and password you provided to the other
account requesting the access to your database.
If the access token has already been used to bind the database, then revoking the access permission will also
unbind the database. If the application is running, it will continue to use the database until it is restarted.
3. Optionally check that the access token has been revoked by listing all permissions again as described in step 1
or using the display-schema-info command.

Related Information
list-schema-access-grants [page 205]
revoke-schema-access [page 223]
display-schema-info [page 153]
grant-schema-access [page 165]
Providing Access to Databases for Other Accounts [page 799]
Binding Databases in Other Accounts [page 800]

1.4.8.3.2.5 Database Commands


The persistence service provides a set of console client commands for managing databases. These allow you to
create databases with specific properties, bind and unbind databases, delete databases, and display information
about databases.

Related Information
list-dbs [page 192]
create-db-ase [page 114]
create-db-user-ase [page 117]
display-db-info [page 152]
set-db-properties-ase [page 232]
bind-db [page 102]
unbind-db [page 250]
delete-db-ase [page 127]
delete-db-user-ase [page 129]
create-db-hana [page 116]
set-db-properties-hana [page 233]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

803

start-db-hana [page 241]


stop-db-hana [page 246]
delete-db-hana [page 128]

1.4.8.3.3

Managing Schemas

Each application deployed on SAP HANA Cloud Platform can be assigned one or more database schemas. A
schema is associated with a particular account and is available solely to applications within this account. A
schema can be bound to multiple applications.
In a typical life cycle, a schema is created, bound, unbound, and deleted.

Creation
You can create schemas explicitly with a freely definable name and assign them certain properties, such as a
specific database type. The schema is independent of any application and has to be explicitly bound.
Schemas can also be created automatically for applications. If you have not explicitly bound a schema to an
application when it is deployed and started for the first time, a schema is created and bound implicitly. This is the
fallback behavior on the platform.
Note that a schema ID is unique within an account. When a schema is created automatically, an ID is also created
based on a combination of the account and application names and the suffix web.

Binding
Schemas can be bound to applications based on an explicitly named data source or using the default data source.
The main differences are as follows:
Explicitly named data source
When you bind the schema to an application, you specify a data source name. This establishes a named
binding between the schema and application and allows the schema to be addressed by the application. The
data source name is equivalent to the name used for the JNDI lookup.
Named bindings allow an application to be bound to more than one schema and, in turn, to use more than one
database at the same time. The databases can be distinguished by the binding names.
Default data source
The schema is bound to the application without an explicitly specified data source name and is consequently
associated with the default data source. It can be addressed by the application by any name. An application
bound to the default data source cannot be bound to any additional schemas. This applies when a schema
was automatically created and bound.
The use of the default data source is a convenient option for applications that require only one database.

804

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can share a schema between applications by binding the same schema to more than one application. Bear in
mind the following when binding schemas to applications:
An applications bindings are based on either named data sources or the default data source. An application
cannot use a combination of the two types of bindings.
When named data sources are used, binding names must be unique per application.
In the overview below, applications 1 and 2 have been explicitly bound to the associated schemas, while
application 3 uses a schema that was automatically created and bound:

Note that applications can also use schemas belonging to other accounts if they are explicitly granted access
permission.

Unbinding
Unbind a schema from an application if the application no longer needs it. It can still be used by other applications
to which it is still bound. Before a schema can be deleted, it has to be unbound from all applications. Schemas can
only be deleted if they no longer have any bindings.
If an application is undeployed but was not unbound from the schema beforehand, the schema will still be listed as
bound to the application and will therefore still be bound if the application is redeployed.

Deletion
You should drop a schema when it is no longer required or if you want to redeploy an application from scratch.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

805

Before deleting a schema, you should explicitly remove any bindings that still exist between the schema and an
application. You can also remove all bindings by enforcing the deletion of the schema.

JNDI Lookup
When using explicitly named data sources to create bindings between schemas and applications, make sure that
the data source names are the same as the JNDI names used in the applications.
Data sources are defined as resources in the web.xml file, or as JTA or non-JTA data sources in the
persistence.xml file in the normal manner. Data sources can be referenced in the application code using a
context.lookup or annotations (@Resource, @PersistenceUnit, @PersistenceContext).

Java EE 6 Web Profile Runtime Environment


When using explicitly named data sources in the Java EE 6 Web Profile runtime environment, you need to create
two additional bindings:
A binding between the application and schema using a data source named jdbc/
defaultManagedDataSource
A binding between the application and schema using a data source named jdbc/
defaultUnmanagedDataSource

Related Information
Creating Schemas [page 807]
Binding Schemas [page 808]
Changing the Default Database System [page 810]
Example Scenarios [page 811]
Accessing Schemas Across Accounts [page 817]
Schema Commands [page 821]
Configuring Data Sources As Connection Properties [page 867]
Managing Databases [page 781]

806

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.3.3.1 Creating Schemas


You create schemas for a selected account. Schemas have properties, such as a database type and database
version, and are identified by an ID that is unique within the account. The schema is independent of any
application.

Context
You can create schemas using the cockpit and the console client. The procedure below describes schema
creation using the cockpit.

Procedure
1. Log on to the cockpit and select an account.
2. Choose Persistence Databases & Schemas in the navigation area.
All schemas available in the selected account are listed with their ID, type, version, and related database
system.

Note
To display a schemas details, for example, its state and the number of existing bindings,select the relevant
schema in the list and click the link on its name. On the overview of the schema, you can perform further
actions, for example, delete the schema.
3. To create a new schema, choose New on the Databases & Schemas page.
An empty New Database/Schema screen is displayed.
4. Enter the following schema details:
Schema ID: A schema ID is freely definable but must start with a letter and contain only uppercase and
lowercase letters ('a' - 'z', 'A' - 'Z'), numbers ('0' - '9'), and the special characters '.' and '-'. Note that the
actual schema ID assigned in the database will be different to this version.
Database System: Select an available database (HANA (<shared>) or MaxDB (<shared>)) from the
dropdown box.
To create schemas on your productive HANA instances, you have to use the HANA-specific tools.
5. Save your entries.
The overview of the new schema is displayed with details about its state, quota used, and the number of
existing bindings. You can perform further actions for the newly created schema, for example, delete it.

Note
To delete a schema, first delete all existing bindings to the schema. The Delete button is only enabled if a
schema has no bindings.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

807

Related Information
Cockpit [page 84]
Changing the Default Database System [page 810]
create-schema [page 123]
Managing Schemas [page 804]

1.4.8.3.3.2 Binding Schemas


To use a schema, you bind it to an application. Bindings are identified by a data source name, which must be
unique per application. You can bind the same schema to multiple applications, and the same application to
multiple schemas.

Context
In the cockpit, you can create and delete schema bindings at both the schema and application level:
To create bindings by schema, use the Data Source Bindings panel at the schema level.
To create bindings by application, use the Data Source Bindings panel at application level.

Procedure
1. Log on to the cockpit and select an account.
2. Choose one of the following options:
To create bindings...
By schema

Do the following
1.

Choose

Persistence

Databases & Schemas

in the navigation area.

2. Select the schema for which you want to create a new binding.
The overview shows the schema details, for example, its state, and the number of ex
isting bindings, and provides access to further actions.
3. Choose Data Source Bindings in the navigation area.
The overview shows the bindings available for the specific schema.
4. Choose the New Binding button.
5. In the New Binding dialog box, enter a data source name and select the name of the
application to which the schema should be bound. Note that the application must be
deployed in the selected account.
6. Save your entries.

808

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To create bindings...
By application

Do the following
1.

Choose

Applications

Java Applications

in the navigation area and select the

relevant application in the application list.


2. Choose

Configuration

Data Source Bindings

in the navigation area.

The overview shows the bindings available for the specific application.
3. Choose the New Binding button.
4. Enter a data source name and select the schema to which the application should be
bound:

If the schema already exists, select the schema from the dropdown box.

To create a schema, choose New, then enter the schema ID, select a database
from the dropdown box, and save your entries. The newly created schema is en
tered in the Schema ID field.

5. Save your entries.

Note
To create a binding to the default data source, enter the data source name <DEFAULT>.
An application that is bound to the default data source (shown as <DEFAULT>) cannot be bound to
additional schemas. To use additional schemas, first rebind the application using a named data source.
Data source names are freely definable but need to match the JNDI data source names used in the
respective applications, as defined in the web.xml or persistence.xml file. For more information,
see the example scenarios.

Next Steps
An applications state influences when a newly bound schema becomes effective. If an application is already
running (Started state), it will continue to use the old schema until it is restarted. A restart is also required if
additional schemas have been bound to the application.

Note
To unbind a schema from an application, simply delete the binding. The application will retain access to the
schema until it is restarted.

Related Information
Cockpit [page 84]
Example Scenarios [page 811]
bind-schema [page 106]
unbind-schema [page 253]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

809

1.4.8.3.3.3 Changing the Default Database System


Database schemas contain a database property, which determines on which database an application will run.
Each account has a default database system.

Context
The default database system is used when schemas are created automatically. This occurs if an application is
started but has not yet been assigned a schema.
You can change the default database system at any point in time, however, bear in mind the following:
A new application that has not been explicitly assigned a schema will use whichever default database system
is effective when automatic schema creation is triggered, that is, when the application is started for the first
time.
When deploying an application from the Eclipse IDE, in contrast to the console client, an application is
deployed and started in one step.
An application that is already using a default database system will not be affected by any changes. Its schema
remains associated with the default database system effective at the time when it was created.

Procedure
1. Log on to the cockpit and go to the list of accounts available to you.
The accounts are displayed as tiles.
2. Choose the

(edit) icon on the tile for the account in question.

3. Select the new default database system from the dropdown box and save your changes.

Related Information
Cockpit [page 84]
Managing Accounts and Quota [page 17]

810

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.3.3.4 Example Scenarios


The schema management scenarios outline the steps involved for the most typical use cases of schemas. To
manipulate schemas, the scenarios use the console client together with the schema commands provided by the
persistence service. The scenarios can also be performed from the cockpit in a similar manner.
For the sake of simplicity, the scenarios described in this section use JDBC and web.xml to illustrate the
definition of data sources. Depending on your application and runtime environment, you can obviously use other
options, such as the persistence.xml file and annotations.

Related Information
Creating and Binding Schemas [page 811]
Using Multiple Schemas [page 813]
Migrating Auto-Bound Schemas [page 815]

1.4.8.3.3.4.1 Creating and Binding Schemas


You can create schemas with a freely definable name and assign them certain properties, such as a specific
database type. This allows you, for example, to create schemas that are associated with a database platform of
your choice, rather than the default database platform assigned to the account. To use a schema, you bind it to an
application.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
In this scenario, an application has been deployed with the default database type assigned to the account. You use
the unbind-schema command to first remove the schema already assigned to the application and then create a
schema with the database type you want to use (create-schema) and bind it to the application (bind-schema).
The following example data is used:
The application myapp runs on the SAP MaxDB database and is bound to a schema that was created
automatically. The application has been stopped.
Runtime environment: Java Web
Data source name: jdbc/dshana
Schema: myhana

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

811

User: test
Account: myaccount
Deployment landscape: hana.ondemand.com (replace as necessary, for example, with
hanatrial.ondemand.com for developer accounts)

Procedure
1. In the application's web.xml file, update the resource definition by replacing the default data source <resref-name>jdbc/DefaultDB</res-ref-name>, or similar, with the named data source <res-refname>jdbc/dshana</res-ref-name>:
<resource-ref>
<res-ref-name>jdbc/dshana</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
2. Adjust the JNDI lookup in the application to use the data source you just defined in the web.xml file. You will
later bind the the application to the myhana schema using this data source:
# JNDI lookup
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/dshana");
3. Open the command window in the <SDK>/tools folder and enter the following command to create a schema
for the SAP HANA database:
neo create-schema -h hana.ondemand.com -u test -a myaccount --id myhana --dbtype
hana
4. Check the schema has been created:
neo list-schemas -a myaccount -h hana.ondemand.com -u test --verbose
Example output:
Schema ID DB Type
myhana
hana
5. Unbind the current schema from the application. Since the application has a default binding, you do not need
to specify a data source name:
neo unbind-schema -a myaccount -b myapp -h hana.ondemand.com -u test
A confirmation is displayed that the schema was successfully unbound.
6. Since you have made code changes, redeploy the application.
7. Bind the schema to the application using the data source you defined in the application. Make sure that the
name is identical to that in the web.xml file and in the JNDI lookup (jdbc/dshana):
neo bind-schema -h hana.ondemand.com -u test -a myaccount -b myapp --data-source
jdbc/dshana --id myhana
A confirmation is displayed that the schema was successfully bound.

812

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

8. Optionally check as follows:


neo list-application-datasources -a myaccount -h hana.ondemand.com -u test -b
myapp
Example output:
Schema ID DB Type Data Source
myhana
hana
jdbc/dshana
9. Start the application so that it uses the new schema.

Related Information
Landscape Hosts [page 32]

1.4.8.3.3.4.2 Using Multiple Schemas


Multiple schemas allow you to use multiple databases in parallel. You might, for example, want to use SAP MaxDB
for normal transaction processing and the SAP HANA database for analytics.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
In this scenario, you use the create-schema command to create two schemas, one associated with SAP MaxDB
and the other with the SAP HANA database. You then use the bind-schema command to bind both schemas to
the application. The following example data is used:
The application is named myapp and not yet been deployed.
Runtime environment: Java Web
Schemas: myhana (SAP HANA database) and mymaxdb (SAP MaxDB)
Data source names: jdbc/dshana and jdbc/dsmaxdb
User: test
Account: myaccount
Deployment landscape: hana.ondemand.com (replace as necessary, for example, with
hanatrial.ondemand.com for developer accounts)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

813

Procedure
1. In the application's web.xml file, add resource definitions for the two data sources:
<resource-ref>
<res-ref-name>jdbc/dshana</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
<resource-ref>
<res-ref-name>jdbc/dsmaxdb</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
2. Add JNDI lookups in the application code using the two data sources. This will allow the application to access
both the myhana and mymaxdb schemas:
# JNDI lookup
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/dshana");
...
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/dsmaxdb");
3. Deploy the application but do not start it.
4. Open the command window in the <SDK>/tools folder and enter the following command to create a schema
for the SAP HANA database:
neo create-schema -h hana.ondemand.com -u test -a myaccount --id myhana --dbtype
hana
5. Create a schema for SAP MaxDB:
neo create-schema -h hana.ondemand.com -u test -a myaccount --id mymaxdb -dbtype maxdb
6. Check the schemas have been created:
neo list-schemas -a myaccount -h hana.ondemand.com -u test --verbose
Example output:
Schema ID DB Type
myhana
hana
mymaxdb
maxdb
7. Bind the schemas to the application using the data source names jdbc/dshana and jdbc/dsmaxdb:
neo bind-schema -h hana.ondemand.com -u test -a myaccount -b myapp --data-source
jdbc/dshana --id myhana
neo bind-schema -h hana.ondemand.com -u test -a myaccount -b myapp --data-source
jdbc/dsmaxdb --id mymaxdb
In both cases, a confirmation is displayed that the schema was successfully bound.
8. Optionally check as follows:
neo list-application-datasources -a myaccount -h hana.ondemand.com -u test -b
myapp

814

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example output:
Schema ID DB Type Data Source
myhana
hana
jdbc/dshana
mymaxdb
maxdb
jdbc/dsmaxdb
9. Start the application so that it uses the two new schemas.

Related Information
Landscape Hosts [page 32]

1.4.8.3.3.4.3 Migrating Auto-Bound Schemas


You can migrate from an auto-created schema by unbinding the schema currently assigned to your application
and rebinding it to the required one. This step is necessary, for example, if you want to use more than one
database in parallel.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
In this scenario you migrate from the auto-bound schema by unbinding and then rebinding the same schema. This
allows you to retain the schema and all its artifacts. The following example data is used:
The application is named myapp and is up and running (status Started).
Runtime environment: Java Web
User: test
Account: myaccount
Deployment landscape: hana.ondemand.com (replace as necessary, for example, with
hanatrial.ondemand.com for developer accounts)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

815

Procedure
1. Open the command window in the <SDK>/tools folder and use the list-application-datasources
command to obtain the name of the schema currently assigned to the application (you need the schema ID in
step 3):
neo list-application-datasources -a myaccount -h hana.ondemand.com -u test -b
myapp
Example output:
Schema ID
myaccount.myapp.web

DB Type Data Source


maxdb
<DEFAULT>

2. Unbind the current schema from the application. Since the application has a default binding, you do not need
to specify a data source name:
neo unbind-schema -account myaccount -b myapp -h hana.ondemand.com -u test
A message confirms that the schema was successfully unbound.
3. In the application, check the name of data source defined as the resource reference in the web.xml file. You
should see <res-ref-name>jdbc/DefaultDB</res-ref-name>, or similar:
<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>

Note
If you prefer, you can obviously change this name, but then you will also need to change the JNDI lookup in
the application code and redeploy the application.
4. Rebind the application to the same schema using the data source name from the previous step, for example,
jdbc/DefaultDB:
neo bind-schema -h hana.ondemand.com -u test -a myaccount -b myapp --data-source
jdbc/DefaultDB --id myaccount.myapp.web
A confirmation is displayed that the schema was successfully bound.
5. Optionally check as follows:
neo list-application-datasources -a myaccount -h hana.ondemand.com -u test -b
myapp
Example output:
Schema ID
myaccount.myapp.web

DB Type Data Source


maxdb
jdbc/DefaultDB

6. The application will continue to use the old schema and default data source until it is restarted. Restart the
application so that it uses the new binding to the schema.

816

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Landscape Hosts [page 32]

1.4.8.3.3.5 Accessing Schemas Across Accounts


Schemas can normally only be used by applications within the same account. You can, however, allow
applications belonging to other accounts controlled access to your accounts schemas. The other account might
be one of your own accounts or a third-party account.
When an external application, that is, an application that does not belong to your account, requests access to one
or more of your schemas, you can specifically grant access permission to that application by generating an access
token. It uniquely identifies the access permission based on the following:
Account granting the access permission
Schema ID
Target account and application
The access token is used by the consumer account to bind the schema to the application. It can be used once
only. An unbind operation does not require an access token.
Note that an access token:
Always applies to one schema and one application and is not transferrable
Has an unlimited validity period
Can be revoked whenever you wish, irrespective of whether the schema has already been bound to the target
application

Restriction
This functionality is not available for SAP MaxDB.

Related Information
Granting Access to Schemas [page 818]
Binding External Schemas [page 819]
Revoking Access to Schemas [page 820]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

817

1.4.8.3.3.5.1 Granting Access to Schemas


As an account member with the Administrator or Developer role, you can grant applications in other accounts
access to any of your accounts schemas.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
To allow access, you generate a one-time access token that permits the requesting application to access your
schema from its account.
The following example data is used in the procedure below:
Account (schema owner): owner
Host: hanatrial.ondemand.com
Schema: schema1
Account (consumer): salescorp
Application (consumer): salesapp

Procedure
Open the command window in the <SDK>/tools folder and enter the following command:
neo grant-schema-access --account owner --host hanatrial.ondemand.com --user myuser
--id schema1 --application salescorp:salesapp
Note that the requesting application is specified in the format <account>:<application>.
If generated successfully, the access token (an alphanumeric string) is displayed.

Next Steps
The generated access token can now be used by the consumer account to bind the schema to the application.
Note the following specifics for productive SAP HANAs:
When the target application binds the schema to which it has been granted access, a new technical database
user is created automatically (name: DEV_<guid>) that has access permission only for the specified schema
(technical name: NEO_<guid>).

818

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To allow the application to access other schemas or packages on the productive SAP HANA instance, you can
grant the technical database user additional privileges (

Security

Users

DEV_<guid> ).

The technical database user is not the same as a normal database user and is provided purely as a
mechanism for enabling schema access.

Related Information
grant-schema-access [page 165]

1.4.8.3.3.5.2 Binding External Schemas


To bind a schema contained in another account to your application, you use a remote access token that indicates
that access to this specific schema has been permitted.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
To prevent misuse, the remote access token can be used once only and is not transferrable to other applications
in your account. Note that it is possible for the owner account to revoke access to the schema at any point in time.
The following example data is used in the procedure below:
Account (schema owner): owner
Host: hanatrial.ondemand.com
Schema: schema1
Account (consumer): salescorp
Application (consumer): salesapp
Data source: jdbc/dshana

Procedure
1. Open the command window in the <SDK>/tools folder and enter the following command:
neo bind-schema --account salescorp --host hanatrial.ondemand.com --user
salesuser --application salesapp --data-source jdbc/dshana --access-token
vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1c6uu8b9pt9z

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

819

Note that you use the access-token parameter instead of the schema ID parameter.
2. Optionally check that the schema has been successfully bound:
neo list-application-datasources --account salescorp --host
hanatrial.ondemand.com --user salesuser --application salesapp
Since the schema does not belong to your account, the schema ID is prefixed with the owner accounts name
(account:schemaID), as shown in the example output below:
Schema ID
owner:schema1

DB Type
hana

Data Source
jdbc/dshana

Related Information
bind-schema [page 106]
list-application-datasources [page 185]

1.4.8.3.3.5.3 Revoking Access to Schemas


A grant applies to a specific schema and specific application and is identified by an access token. It is valid until it
is revoked by a member of the owner account.

Context
The following example data is used in the procedure below:
Account (schema owner): owner
Host: hanatrial.ondemand.com
Schema: schema1
Account (consumer): salescorp
Application (consumer): salesapp

Procedure
1. Open the command window in the <SDK>/tools folder and enter the following command to list all grants for
the specified schema:
neo list-schema-access-grants --account owner --host hanatrial.ondemand.com -user myuser --id schema1

820

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example output:
Table 272:
Access Token

Schema ID

Granted To

Bound

vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1
c6uu8b9pt9z

schema1

salescorp:salesapp

yes

2. To revoke the grant, enter the following command and copy across the access token obtained in the previous
step:
neo revoke-schema-access --account owner --host hanatrial.ondemand.com --user
myuser --access-token vm6431dhjcr2e3dbt0fk6jpzm2w7oo3q48yumf1c6uu8b9pt9z
If the access token has already been used to bind the schema, then revoking the access permission will also
unbind the schema. If the application is running, it will continue to use the schema until it is restarted.
3. Optionally check that the access token has been revoked by listing all grants again as described in step 1 or
using the display-schema-info command.

Related Information
list-schema-access-grants [page 205]
revoke-schema-access [page 223]
display-schema-info [page 153]

1.4.8.3.3.6 Schema Commands


The persistence service provides a set of console client commands for managing schemas. These allow you to
create schemas with specific properties, bind and unbind schemas, delete schemas, and display information
about schemas.

Related Information
list-dbms [page 191]
list-application-datasources [page 185]
list-schemas [page 204]
create-schema [page 123]
bind-schema [page 106]
unbind-schema [page 253]
delete-schema [page 140]
display-schema-info [page 153]
grant-schema-access [page 165]
revoke-schema-access [page 223]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

821

list-schema-access-grants [page 205]


bind-hana-dbms [page 104]
unbind-hana-dbms [page 252]

1.4.8.4

Programming with JPA

JPA offers two main types of persistence, container-managed persistence and application-managed persistence,
which differ in terms of the management and life cycle of the entity manager.
The main features of each scenario are shown in the table below. We recommend that you use containermanaged persistence (Java EE 6 Web Profile runtime), which is the model most commonly used by Web
applications:
Table 273:
JPA Scenario

Java Web SDK

Java EE 6 Web Profile SDK

Container-managed persistence

Not supported

JTA transactions
Entity manager injection using the

@PersistenceContext annotation
Application-managed persistence

Resource-local transactions
Not supported

Injection of the entity manager factory us


ing the @PersistenceUnit annotation
Manual creation of the entity manager factory using

javax.persistence.Persistence. createEntityManagerFactory

EclipseLink
You are advised to download the latest version of EclipseLink. Note that EclipseLink versions as of 2.5 contain the
SAP HANA database platform.
You require the following JAR files:
Table 274:
JPA Scenario

SDK

EclipseLink JARs

Container-managed persistence

Java EE 6 Web Pro eclipselink\jlib\eclipselink.jar


file
Only required for EclipseLink versions as of 2.5.

Application-managed persistence

Java Web

eclipselink\jlib\eclipselink.jar

eclipselink\jlib\jpa
\javax.persistence_2.*.jar

Java EE 6 Web Pro eclipselink\jlib\eclipselink.jar


file

The EclipseLink download is available from http://www.eclipse.org/eclipselink/downloads . Click EclipseLink


2.5.x Installer Zip and then download the archive and extract it to your local file system. For the Java Web

822

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

scenario, where you require two JAR files, we recommend that you copy the two files (see above) to a separate
directory in your local file system.
For details about importing the files into your Web application project and specifying the JPA implementation
library EclipseLink, see the tutorials Adding Application-Managed Persistence With JPA (Java Web SDK) [page
735] and Adding Container-Managed Persistence With JPA (Java EE 6 Web Profile SDK) [page 724].

SAP HANA Database


The SAP HANA database platform is not part of EclipseLink versions prior to 2.5. If you use an earlier EclipseLink
version, you should bear in mind that additional steps are required if you want to deploy applications on the SAP
HANA database.

Note
In individual cases, issues have been observed with the SAP HANA database version SPS6 in combination with
EclipseLink versions prior to 2.5. If you experience problems, you are advised to consider switching to
EclipseLink 2.5 or later.

Note
The SAP HANA database is available in the cloud only. The persistence service does not provide the SAP HANA
database for local deployment.

Related Information
Special Settings for EclipseLink Versions Prior to 2.5 [page 824]
Persistence Units [page 825]
Using Container-Managed Persistence [page 826]
Using Application-Managed Persistence [page 829]
Entity Classes [page 836]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

823

1.4.8.4.1

Special Settings for EclipseLink Versions Prior to


2.5

EclipseLink versions prior to 2.5 do not contain the SAP HANA database platform. To deploy applications on the
SAP HANA database, you need to specify it as the target database and, for application-managed persistence,
import the corresponding JAR file into your project.

Container-Managed Persistence
Specify the target database as a persistence unit property:
1. Select the <project>/Java Resources/src/META-INF/persistence.xml file and from the context
menu choose

Open With

Persistence XML Editor .

2. On the Options tab enter com.sap.persistence.platform.database.HDBPlatform in the Target


database field.
The source code should now contain the following:
<properties>

<property name="eclipselink.target-database"
value="com.sap.persistence.platform.database.HDBPlatform"/>
</properties>

Application-Managed Persistence
Specify the target database as shown above or directly in the servlet code, as shown in the example below:
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/DefaultDB");
connection = ds.getConnection();
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds);
properties.put("eclipselink.target-database",
"com.sap.persistence.platform.database.HDBPlatform");
Add the SAP HANA JAR to the Web application project:
1. Select the <project>/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and then choose Next.

3. Browse to the local directory where you downloaded and unpacked the SAP HANA Cloud Platform SDK,
select the repository/plugins directory, and choose OK.
4. Select the checkbox com.sap.core.persistence.osgi.hdb.platform_x.y.z.jar and choose Finish.

General Points
The target database property should be set before you deploy the application on the SAP HANA database,
otherwise an error will occur. If this happens, you need to re-create the table with the correct definitions by setting

824

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

the DDL generation type to Drop and Create Tables and then redeploy the application. Afterwards, set it
back to Create Tables so that you do not lose your data once you deploy again.
When testing the application locally, remember to remove this property.

1.4.8.4.2

Persistence Units

A JPA model contains a persistence configuration file, persistence.xml, which describes the defined
persistence units. A persistence unit in turn defines all entity classes managed by the entity managers in your
application and includes the metadata for mapping the entity classes to the database entities.

JPA Provider
The persistence.xml file is located in the META-INF folder within the persistence unit src folder. The JPA
persistence provider used by the persistence service is org.eclipse.persistence.jpa.PersistenceProvider.

Example
In the persistence.xml file in the tutorial Adding Container-Managed Persistence with JPA (Java EE 6 Web
Profile SDK), the persistence unit is named persistence-with-ejb, the transaction type is JTA (default
setting), and the DDL generation type has been set to Create Tables, as shown below:
<?xml version="1.0" encoding="UTF-8"?>
<persistence version="2.0" xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://
java.sun.com/xml/ns/persistence/persistence_2_0.xsd">
<persistence-unit name="persistence-with-ejb">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables" />
</properties>
</persistence-unit>
</persistence>

DDL Generation Type


The persistence service uses the EclipseLink capabilities for generating database tables. The following values are
valid for generating the DDL for the entity specified in the persistence.xml file:
none: EclipseLink does not generate a DDL (no schema is generated).
create-tables: EclipseLink attempts to execute a CREATE TABLE SQL. It creates a DDL for non-existent
tables and leaves existing tables unchanged (they are not dropped or replaced).
drop-and-create-tables: EclipseLink attempts to DROP all tables and then CREATE all tables.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

825

Note
This option will often be used during the development phase, when there are frequent changes to the
schema or data needs to be deleted. Don't forget to change it to create-tables before the application
goes live, since all data is lost when a table is dropped.

Transaction Type
JTA transactions are used for container-managed persistence, and resource-local transactions for applicationmanaged persistence. Note that the Java Web SDK supports resource-local transactions only.

Related Information
Adding Container-Managed Persistence With JPA (Java EE 6 Web Profile SDK) [page 724]

1.4.8.4.3

Using Container-Managed Persistence

Container-managed entity managers are the model most commonly used by Web applications. Containermanaged entity managers require JTA transactions and are generally used with stateless session beans and
transaction-scoped persistence contexts, which are thread-safe.

Context
The scenario described in this section is based on the Java EE 6 Web Profile runtime. You use a stateless EJB
session bean into which the entity manager is injected using the @PersistenceContext annotation.

Procedure
1. Configure the persistence units in the persistence.xml file to use JTA data sources and JTA transactions.
2. Inject the entity manager into an EJB session bean using the @PersistenceContext annotation.

Related Information
Configuring Persistence Units [page 827]

826

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Injecting Entity Managers [page 828]

1.4.8.4.3.1 Configuring Persistence Units


To use container-managed entity managers, you need to configure JTA data sources in the persistence.xml
file. JTA data sources are managed data sources and are associated with JTA transactions.

Context
To configure JTA data sources, you set the transaction type attribute (transaction-type) to JTA and specify
the names of the JTA data sources (jta-data-source), unless the application is using the default data source.

Procedure
1. In the Project Explorer view, select <project>/Java Resources/src/META-INF/persistence.xml, and
from the context menu choose

Open With

Persistence XML Editor .

2. On the Connection tab, enter the transaction type JTA or leave the default setting, which is JTA.
3. If the application is using an explicitly named data source, enter the JNDI name of the data source in the JTA
data source field.
If it uses the default data source, it is not necessary to specify a data source in the persistence.xml file.
4. If the application uses more than one data source, define a corresponding number of persistence units, each
with its own data source. The data source name is the JNDI name used for the lookup and must match the
name used for the schema binding. To do this, switch to the Source tab of the persistence.xml file.
The example below shows the persistence units defined for two data sources, where each data source is
associated with a different database:
<persistence>
<persistence-unit name="hanadb" transaction-type="JTA">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<jta-data-source>jdbc/hanaDB</jta-data-source>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables" />
</properties>
</persistence-unit>
<persistence-unit name="maxdb" transaction-type="JTA">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<jta-data-source>jdbc/maxDB</jta-data-source>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables" />
</properties>
</persistence-unit>
</persistence>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

827

5. Save the file.

Related Information
Managing Schemas [page 804]
Configuring Data Sources As Connection Properties [page 867]

1.4.8.4.3.2 Injecting Entity Managers


EJB session beans, which typically perform the database operations, can use the @PersistenceContext
annotation to directly inject the entity manager. The corresponding entity manager factory is created
transparently by the container.

Procedure
1. In the EJB session bean, inject the entity manager as follows. Note that a persistence context type has not
been explicitly specified in the example below and is therefore, by default, transaction-scoped:
@PersistenceContext
private EntityManager em;
To use an extended persistence context, the value of the persistence context type has to be set to EXTENDED
(@PersistenceContext(type=PersistenceContextType.EXTENDED)) and the session bean declared as
stateful. An extended persistence context allows a session bean to maintain its state across multiple JTA
transactions. Bear in mind that an extended persistence context is not thread-safe.
2. If you have more than one persistence unit, inject the required number of entity managers by specifying the
persistence unit name as defined in the persistence.xml file:
@PersistenceContext(unitName="hanadb")
private EntityManager em1;
...
@PersistenceContext(unitName="maxdb")
private EntityManager em2;
3. Inject an instance of the EJB session bean class into, for example, the servlet of the web application with an
annotation in the following form, where PersonBean is an example session bean class:
@EJB PersonBean personBean;
The persistence context made available is based on JTA and provides automatic transaction management.
Each EJB business method automatically has a managed transaction, unless specified otherwise. The entity
manager life cycle, such as its instantiation and closing, is controlled by the container. Methods designed for
resource-local transactions, such as em.getTransaction().begin(),
em.getTransaction().commit(), and em.close(), must therefore not be used.

828

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Configuring Data Sources As Connection Properties [page 867]

1.4.8.4.4

Using Application-Managed Persistence

Application-managed entity managers are created manually using the EntityManagerFactory interface.
Application-managed entity managers require resource-local transactions and non-JTA data sources, which need
to be declared as JNDI resource references.

Context
The scenario described in this section is based on the Java Web runtime, which only supports manual creation of
the entity manager factory.

Procedure
1. Declare a JNDI resource reference.
2. Configure the persistence units in the persistence.xml file to use resource-local transactions and non-JTA
data sources.
3. Use a JNDI lookup in the application code to retrieve the data source.
4. Create an entity manager factory and entity manager.

Related Information
Declaring JNDI Resource References [page 830]
Configuring Persistence Units [page 830]
Retrieving Data Sources [page 832]
Creating Entity Managers [page 833]
Using Dynamic Data Source Lookup [page 835]
Entity Transaction API [page 834]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

829

1.4.8.4.4.1 Declaring JNDI Resource References


An application can use one or more data sources. A data source can be a default data source or an explicitly
named data source. Before a data source can be used, it needs to be declared as a JNDI resource reference in the
web.xml deployment descriptor.

Procedure
1. In the Project Explorer view, open the WebContent/WEB-IN/web.xml file.
2. Add the following code after the <servlet-mapping> elements. Note that the resource reference name is
just an example:
<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
The resource attributes denote the following:
Name The JNDI name of the resource. The Java EE Specification recommends that the data source
reference be declared in the jdbc subcontext (jdbc/NAME).
Type The type of resource that will be returned during the lookup.
3. If the application uses multiple data sources, add a resource reference for each data source:
<resource-ref>
<res-ref-name>jdbc/datasource1</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
<resource-ref>
<res-ref-name>jdbc/datasource2</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
The data source name is the JNDI name used for the lookup.
The same name must be used for the schema binding.
4. Save the file.

Related Information
Managing Schemas [page 804]
Configuring Data Sources As Connection Properties [page 867]

1.4.8.4.4.2 Configuring Persistence Units


To use application-managed entity managers, you need to configure resource-local transactions in the
persistence.xml file. Resource-local transactions are associated with non-JTA data sources (that is,

830

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

unmanaged data sources) and are explicitly controlled by the application through the EntityTransaction
interface of the entity manager.

Context
To use resource-local transactions, the transaction type attribute has to be set to RESOURCE_LOCAL, indicating
that the entity manager factory should provide resource-local entity managers. When you work with a non-JTA
data source, the non-JTA data source element also has to be set in the persistence unit properties in the
application code.

Procedure
1. In the Project Explorer view, select <project>/Java Resources/src/META-INF/persistence.xml, and
from the context menu choose

Open With

Persistence XML Editor .

2. On the Connection tab, enter the transaction type Resource Local.


3. If the application uses multiple data sources, define a persistence unit for each resource reference specified in
the web.xml file. To do this, switch to the Source tab of the persistence.xml file.
The example below shows the persistence units defined for two data sources, where each data source is
associated with a different database:
<persistence>
<persistence-unit name="hanadb" transaction-type="RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables"/>
</properties>
</persistence-unit>
<persistence-unit name="maxdb" transaction-type="RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables"/>
</properties>
</persistence-unit>
</persistence>
Note that if you intend to use resource injection rather than a context.lookup, you can define the data sources
in the persistence.xml file instead of the web.xml file. For example:
persistence-unit name="hanadb" transaction-type="RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<non-jta-data-source>jdbc/hanaDB</non-jta-data-source>
...
<persistence-unit name="maxdb" transaction-type=" RESOURCE_LOCAL">
<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<non-jta-data-source>jdbc/maxDB</non-jta-data-source>
...
4. Save the file.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

831

Related Information
Managing Schemas [page 804]

1.4.8.4.4.3 Retrieving Data Sources


In the application code, you can obtain an initial JNDI context by creating a javax.naming.InitialContext
object, and then retrieve the data source by looking up the naming environment through the InitialContext.
Alternatively, you can directly inject the data source.

Procedure
1. To create an intitial JNDI context and look up the data source, add the following code to your application and
make sure that the JNDI name matches the one specified in the web.xml file:
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/DefaultDB");
Note that according to the Java EE Specification, the prefix java:comp/env should be added to the JNDI
resource name (as specified in the web.xml) to form the lookup name. For more information about defining
and referencing resources according to the Java EE standard, see the Java EE Specification.
2. If the application uses multiple data sources, create the lookup in a similar manner:
InitialContext ctx = new InitialContext();
DataSource ds1 = (DataSource) ctx.lookup("java:comp/env/jdbc/datasource1");
DataSource ds2 = (DataSource) ctx.lookup("java:comp/env/jdbc/datasource2");
3. Alternatively, to directly inject the data source, use the @Resource annotation:
Default data source
Since the default data source is provided automatically, it can be injected without an explicit resource
name, as shown below. It is also not necessary to declare the JNDI resource reference in the web.xml or
persistence.xml file:
@Resource
private javax.sql.DataSource ds;
Explicitly named data sources
These are injected with a specific resource name, as specified in the web.xml or persistence.xml file:
@Resource(name="jdbc/datasource1")
private javax.sql.DataSource ds1;
@Resource(name="jdbc/datasource2")
private javax.sql.DataSource ds2;

832

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Java EE Specification

1.4.8.4.4.4 Creating Entity Managers


You use the EntityManagerFactory interface to manually create and manage the entity managers in your Web
application.

Procedure
1. Use javax.persistence.Persistence.createEntityManagerFactory to create an
EntityManagerFactory object that operates on the data source that you have retrieved as follows:
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds);
emf = Persistence.createEntityManagerFactory("persistence-with-jpa", properties);
In the code above, the non-JTA data source element has been set in the persistence unit properties, and the
persistence unit name is the name of the persistence unit declared in the persistence.xml file.

Note
You are advised to include the above code in the servlet init() method, as illustrated in the tutorial
Adding Application-Managed Persistence with JPA (Java Web SDK), since this method is called only once
during initialization when the servlet instance is loaded.
2. If the application uses multiple data sources, create an entity manager factory for each data source:
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds1);
emf1 = Persistence.createEntityManagerFactory("hanadb", properties);
...
Map properties2 = new HashMap();
properties2.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds2);
emf2 = Persistence.createEntityManagerFactory("maxdb", properties);
3. Use the entity manager factory obtained above to create an entity manager as follows:
EntityManager em = emf.createEntityManager();

Next Steps
Application-managed entity managers are always extended and therefore retain the entities beyond the scope of
a transaction. You should therefore close an entity manager when it is no longer needed by calling

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

833

EntityManager.close() or alternatively EntityManager.clear() wherever appropriate, such as at the end


of a transaction. Bear in mind that an entity manager must not be used concurrently by multiple threads, so
design your entity manager handling in such a way that concurrent access of entity managers is prevented.

Related Information
Entity Transaction API [page 834]
Configuring Data Sources As Connection Properties [page 867]
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]

1.4.8.4.4.5 Entity Transaction API


When working with a resource-local entity manager, the transaction boundaries need to be set manually in your
application code using the EntityTransaction API. You can obtain the entity transaction attached to the entity
manager by calling EntityManager.getTransaction().
To create and update data in the database, you require an active transaction. The EntityTransaction API provides
the begin() method for starting a transaction, and the commit() and rollback() methods for ending a
transaction. When a commit is executed, all changes are synchronized with the database.

Example
The tutorial code (Adding Application-Managed Persistence with JPA (Java Web SDK)) shows how to create and
persist an entity:
Person person = new Person("<name>");
em.getTransaction().begin();
em.persist(person);
em.getTransaction().commit();
em.close();
The EntityManager.persist() method makes an entity persistent by associating it with an entity manager.
It is inserted into the database when the commit() method is called. The persist() method can only be
called on new entities.

Related Information
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]

834

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.4.4.6 Using Dynamic Data Source Lookup


The data source is determined dynamically at runtime and does not need to be defined beforehand in the
web.xml or persistence.xml file. This allows you to bind additional schemas to an application and obtain the
corresponding data source, without having to modify the application code or redeploy the application.

Context
A dynamic JNDI lookup is applied as follows, depending on whether you are using an unmanaged or a managed
data source:
Unmanaged
context.lookup("unmanageddatasource:<data source name>")
This is supported in the Java Web, Java EE 6 Web Profile, and Java Web Tomcat 7 runtimes.
Managed
context.lookup("manageddatasource:<data source name>")
This is supported in the Java EE 6 Web Profile runtime only.

Note
For the Java Web and Java EE 6 Web Profile runtimes only, but not for the Java Web Tomcat 7, you can
continue to use the earlier variants of the JNDI lookup:
Unmanaged
context.lookup("unmanaged-datasource:<data source name>")
Managed
context.lookup("managed-datasource:<data source name>")
The steps described below are based on JPA application-managed persistence using the Java Web runtime.

Procedure
1. Create the persistence unit to be used for the dynamic data source lookup:
a. In the Project Explorer view, select <project>/Java Resources/src/META-INF/persistence.xml,
and from the context menu choose

Open With

Persistence XML Editor .

b. Switch to the Source tab of the persistence.xml file and create a persistence unit, as shown in the
example below. Note that the corresponding data source is not defined in either the persistence.xml
or web.xml file:
<persistence-unit name="dynamic" transaction-type="RESOURCE_LOCAL">

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

835

<provider>org.eclipse.persistence.jpa.PersistenceProvider</provider>
<class>com.sap.cloud.sample.persistence.Person</class>
<properties>
<property name="eclipselink.ddl-generation" value="create-tables"/>
</properties>
</persistence-unit>
2. In the servlet code, implement a JNDI data source lookup. In the example below, the data source name is
"datasource2":
ds = (DataSource) context.lookup("unmanageddatasource:datasource2");
3. Create an entity manager factory in the normal manner. In the example below, the persistence unit is named
"dynamic", as defined in the persistence.xml file:
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds);
emf = Persistence.createEntityManagerFactory("dynamic", properties);
4. Use the console client to create a schema binding with the same data source name. To do this, open the
command window in the <SDK>/tools folder and enter the following command:
neo bind-schema -h <host> -u <user> -a <account> -b <application name> --datasource datasource2 --id <schema ID>

1.4.8.4.5

Entity Classes

To declare a class as an entity and define how that entity maps to the relevant database table, you can either
decorate the Java object with metadata using Java annotations or denote it as an entity in the XML descriptor.
The Dali Java Persistence Tools provided as part of the Eclipse IDE for Java EE Developers allow you to use a JPA
diagram editor to create, edit, and display entities and their relationships (your applications data model) in a
graphical environment.

Example
The tutorial Adding Application-Managed Persistence with JPA (Java Web SDK) defines the entity class Person,
as shown below:
package com.sap.cloud.sample.persistence;
import javax.persistence.*;
@Entity
@Table(name = "T_PERSON")
@NamedQuery(name = "AllPersons", query = "select p from Person p")
public class Person {
@Id
@GeneratedValue
private long id;
@Basic
private String FirstName;
@Basic
private String LastName;
The Person class has been annoted as an entity: @Entity.
The @Table annotation maps the entity to the database table T_PERSON.

836

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The @NamedQuery annotation indicates that a static query has been created in the metadata. The name
element of @NamedQuery gives the name of the query that will be used with the createNamedQuery()
method, while the query element specifies the actual query.
The definition of the field serving as the unique identifier of the entity has been annotated with @Id,
indicating it is the primary key in the database. Its value is generated automatically (@GeneratedValue).

Related Information
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]
Dali Java Persistence Tools User Guide

1.4.8.4.6

Creating SAP HANA Column-Store Tables

The SAP HANA database allows tables to be created with row-based storage or column-based storage. By default,
tables are created with row-based storage, but you can change the type of table storage you have applied, if
necessary.
The example below shows the SQL syntax used by the SAP HANA database to create different table types. The
first two SQL statements both create row-store tables, the third a column-store table, and the fourth changes the
table type from row-store to column-store:
CREATE TABLE T_PERSON
CREATE ROW TABLE T_PERSON
CREATE COLUMN TABLE T_PERSON
ALTER TABLE T_PERSON COLUMN

EclipseLink JPA
When using EclipseLink JPA for data persistence, the table type applied by default in the SAP HANA database is
row-store. To create a column-store table or alter an existing row-store table, you can manually modify your
database using SQL DDL statements, or you can use open source tools, such as Liquibase (with plain SQL
statements), to handle automated database migrations.
Due to the limitations of the EclipseLink schema generation feature, you will need to use one of the above options
anyway to handle the life cycle management of your database objects.

ALTER TABLE Example


This section shows how you can use the ALTER TABLE statement to change a row-store table created by default
in the SAP HANA database to a column-store table. The example is based on the Adding Application-Managed

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

837

Persistence with JPA (Java Web SDK) tutorial and provides a solution designed specifically for this tutorial and use
case.
The example allows you to take advantage of the automatic table generation feature provided by JPA EclipseLink.
You merely alter the existing table at an appropriate point, when the schema containing the relevant table has just
been created. The applicable code snippet is added to the init() method of the servlet
(PersistenceWithJPAServlet). The main changes to the servlet code are outlined below:
1. Since the table must already exist when the ALTER statement is called, a small workaround is introduced in
the init() method. An entity manager is created at an earlier stage than in the original version of the tutorial
in order to trigger the generation of the schema:
//workaround: create EntityManager to trigger schema generation
emf.createEntityManager().close();
2. The SAP HANA database table SYS.M_TABLES contains information about all row and column tables in the
current schema. A new method is added to the servlet which uses this table to check that T_PERSON is not
already a column-store table.
3. Another new method alters the table using the SQL statement ALTER TABLE <table name> COLUMN.
To apply the solution, replace the entire servlet class PersistenceWithJPAServlet with the following content:
package com.sap.cloud.sample.persistence;
import java.io.IOException;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.sql.DataSource;
import org.eclipse.persistence.config.PersistenceUnitProperties;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.sap.security.core.server.csi.IXSSEncoder;
import com.sap.security.core.server.csi.XSSEncoder;
/**
* Servlet implementing a simple JPA based persistence sample application for SAP
HANA Cloud.
*/
public class PersistenceWithJPAServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
private static final Logger LOGGER =
LoggerFactory.getLogger(PersistenceWithJPAServlet.class);
private static final String SQL_GET_TABLE_TYPE = "SELECT TABLE_NAME, TABLE_TYPE
FROM SYS.M_TABLES WHERE TABLE_NAME = ?";
private static final String PERSON_TABLE_NAME = "T_PERSON";
private DataSource ds;
private EntityManagerFactory emf;
/** {@inheritDoc} */
@SuppressWarnings({ "rawtypes", "unchecked" })
@Override
public void init() throws ServletException {

838

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Connection connection = null;


try {
InitialContext ctx = new InitialContext();
ds = (DataSource) ctx.lookup("java:comp/env/jdbc/DefaultDB");
Map properties = new HashMap();
properties.put(PersistenceUnitProperties.NON_JTA_DATASOURCE, ds);
boolean onHANA = runsOnHANADatabase();
if (onHANA) {
properties.put("eclipselink.target-database",
"com.sap.persistence.platform.database.HDBPlatform");
}
emf = Persistence.createEntityManagerFactory("persistence-with-jpa",
properties);
// convert T_PERSON to column table
// workaround: create EntityManager to trigger schema generation
emf.createEntityManager().close();
if (onHANA) {
convertToColumnTable(PERSON_TABLE_NAME);
}
} catch (NamingException e) {
throw new ServletException(e);
} catch (SQLException e) {
LOGGER.error("Could not determine database product.", e);
throw new ServletException(e);
} finally {
if (connection != null) {
try {
connection.close();
} catch (SQLException x) {
LOGGER.debug("Unable to close connection.", x);
}
}
}
}
/** {@inheritDoc} */
@Override
public void destroy() {
emf.close();
}
/** {@inheritDoc} */
@Override
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.getWriter().println("<p>Persistence with JPA Sample!</p>");
try {
appendPersonTable(response);
appendAddForm(response);
} catch (Exception e) {
response.getWriter().println("Persistence operation failed with reason:
" + e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}
/** {@inheritDoc} */
@Override
protected void doPost(HttpServletRequest request, HttpServletResponse response)
throws ServletException,
IOException {
try {
doAdd(request);
doGet(request, response);
} catch (Exception e) {
response.getWriter().println("Persistence operation failed with reason:
" + e.getMessage());
LOGGER.error("Persistence operation failed", e);
}
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

839

private void appendPersonTable(HttpServletResponse response) throws


SQLException, IOException {
// Append table that lists all persons
EntityManager em = emf.createEntityManager();
try {
@SuppressWarnings("unchecked")
List<Person> resultList =
em.createNamedQuery("AllPersons").getResultList();
response.getWriter().println(
"<p><table border=\"1\"><tr><th colspan=\"3\">"
+ (resultList.isEmpty() ? "" : resultList.size() + " ")
+ "Entries in the Database</th></tr>");
if (resultList.isEmpty()) {
response.getWriter().println("<tr><td colspan=\"3\">Database is
empty</td></tr>");
} else {
response.getWriter().println("<tr><th>First name</th><th>Last name</
th><th>Id</th></tr>");
}
IXSSEncoder xssEncoder = XSSEncoder.getInstance();
for (Person p : resultList) {
response.getWriter().println(
"<tr><td>" + xssEncoder.encodeHTML(p.getFirstName()) + "</
td><td>"
+ xssEncoder.encodeHTML(p.getLastName()) + "</
td><td>" + p.getId() + "</td></tr>");
}
response.getWriter().println("</table></p>");
} finally {
em.close();
}
}
private void appendAddForm(HttpServletResponse response) throws IOException {
// Append form through which new persons can be added
response.getWriter().println(
"<p><form action=\"\" method=\"post\">" + "First name:<input type=
\"text\" name=\"FirstName\">"
+ "&nbsp;Last name:<input type=\"text\" name=\"LastName\">"
+ "&nbsp;<input type=\"submit\" value=\"Add Person\">" + "</
form></p>");
}
private void doAdd(HttpServletRequest request) throws ServletException,
IOException, SQLException {
// Extract name of person to be added from request
String firstName = request.getParameter("FirstName");
String lastName = request.getParameter("LastName");
// Add person if name is not null/empty
EntityManager em = emf.createEntityManager();
try {
if (firstName != null && lastName != null && !
firstName.trim().isEmpty() && !lastName.trim().isEmpty()) {
Person person = new Person();
person.setFirstName(firstName);
person.setLastName(lastName);
em.getTransaction().begin();
em.persist(person);
em.getTransaction().commit();
}
} finally {
em.close();
}
}
private boolean runsOnHANADatabase() throws SQLException {
boolean onHANA = false;
Connection connection = ds.getConnection();
try {
String databaseProductName =
connection.getMetaData().getDatabaseProductName();

840

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

if (databaseProductName.equals("HDB")) {
onHANA = true;
}
} finally {
connection.close();
}
return onHANA;

}
private void convertToColumnTable(String tableName) throws SQLException {
if (!isColumnTable(tableName)) {
Connection connection = ds.getConnection();
try {
String sql = "ALTER TABLE " + tableName + " COLUMN";
PreparedStatement stmt = connection.prepareStatement(sql);
stmt.executeUpdate();
stmt.close();
} finally {
connection.close();
}
}
}
private boolean isColumnTable(String tableName) throws SQLException {
boolean exists = false;
boolean columnTable = false;
Connection connection = ds.getConnection();
String tableTypeStart = null;
try {
PreparedStatement stmt =
connection.prepareStatement(SQL_GET_TABLE_TYPE);
stmt.setString(1, tableName);
ResultSet rs = stmt.executeQuery();
while (rs.next()) {
exists = true;
tableTypeStart = rs.getString(2);
break;
}
rs.close();
if (!exists) {
throw new SQLException("Table " + tableName + " does not exist");
}
if (tableTypeStart.equalsIgnoreCase("COLUMN")) {
columnTable = true;
}
} finally {
connection.close();
}
return columnTable;
}
}

Related Information
Adding Application-Managed Persistence With JPA (Java Web SDK) [page 735]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

841

1.4.8.4.7

EclipseLink Weaving

EclipseLink provides weaving as a means of enhancing JPA entities and classes for performance optimization. At
present, SAP HANA Cloud Platform supports static weaving only. Static weaving occurs at compile time and is
available in both the Java Web and Java EE 6 Web Profile environments.
Note that dynamic weaving is currently not supported on SAP HANA Cloud Platform.

Prerequisites
For static weaving to work, the entity classes have to be listed in the persistence.xml file.

EclipseLink Library
To use the EclipseLink weaving options in your web applications, you need to add the EclipseLink library to the
classpath:
Java Web SDK
The EclipseLink library has already been added to the WebContent/WEB-INF/lib folder, since it is required
for the JPA persistence scenario.
Java EE 6 Web Profile SDK
The EclipseLink library is already part of the Java EE 6 Web Profile SDK, allowing you to run JPA scenarios
without any additional steps. To use the weaving options, however, you need to add the EclipseLink library to
the classpath, as described below.

Java EE 6 Web Profile SDK: Adding the EclipseLink Library to the Classpath
1. In the Eclipse IDE in the Project Explorer view, select the web application and from the context menu choose
Properties.
2. In the tree, select JPA.
3. In the Platform section, select the correct EclipseLink version from the dropdown list. It should match the
version available in the SDK.
4. In the JPA implementation section, select the type User Library from the dropdown list.
5. To the right of the user library list box that is now visible, choose Download library.
6. In the dialog box, select the correct version of the EclipseLink library (currently EclipseLink 2.5.2) and
choose Next.
7. Accept the EclipseLink license and choose Finish.
8. The new user library now appears in the list box. Make sure that the checkbox is selected.
9. Deselect the Include libraries with this application checkbox just below the user library box and choose OK.

842

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Enabling Static Weaving in Eclipse


1. In the Eclipse IDE in the Project Explorer view, select the web application and from the context menu choose
Properties.
2. In the tree, select

JPA

EclipseLink .

3. In the Static weaving section, select the Weave classes on build checkbox.
4. Leave the default values for the source classes, target classes, and persistence XML root. You might need to
adapt them if you have a non-standard web application project layout. Choose OK to complete the step.

Note
If you change the target class settings, make sure you deploy these classes.
Your web application project will be rebuilt so that the JPA entity class files contain weaving information. This will
also occur on each (incremental) project build. The woven entity classes will be used whenever you publish the
web application to the cloud.

More Information
For information about using an ant task or the command line to perform static weaving, see the EclipseLink User
Guide .

1.4.8.5

Using Plain JDBC

Although JPA is suited for most application development scenarios and is the recommended approach on SAP
HANA Cloud Platform, there might be cases where the low-level control provided by JDBC is more appropriate.
Bear in mind that working with JDBC entails manually writing SQL statements to read and write objects from and
to the database.

JNDI Resource Reference


An application can use one or more data sources. A data source can be a default data source or an explicitly
named data source. Before a data source can be used, it needs to be declared as a JNDI resource reference.
You declare a JNDI resource reference to a JDBC data source in the web.xml deployment descriptor located in
the WebContent/WEB-INF directory as shown below. Note that the resource reference name is just an example:
<resource-ref>
<res-ref-name>jdbc/DefaultDB</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
The resource attributes denote the following:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

843

Name: The JNDI name of the resource. The Java EE Specification recommends that the data source reference
be declared in the jdbc subcontext (jdbc/NAME).
Type: The type of resource that will be returned during the lookup.
The <resource-ref> elements should be added after the <servlet-mapping> elements in the deployment
descriptor.
If the application uses multiple data sources, you need to add a resource reference for each data source:
<resource-ref>
<res-ref-name>jdbc/datasource1</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>
<resource-ref>
<res-ref-name>jdbc/datasource2</res-ref-name>
<res-type>javax.sql.DataSource</res-type>
</resource-ref>

Data Source Lookup


You can obtain an initial JNDI context from Tomcat by creating a javax.naming.InitialContext object, and
then consume the data source by looking up the naming environment through the InitialContext, as follows:
InitialContext ctx = new InitialContext();
DataSource ds = (DataSource) ctx.lookup("java:comp/env/jdbc/DefaultDB");
Note that according to the Java EE Specification, the prefix java:comp/env should be added to the JNDI
resource name (as specified in web.xml) to form the lookup name. For more information about defining and
referencing resources according to the Java EE standard, see the Java EE Specification.
If the application uses multiple data sources, the lookup is constructed in a similar manner:
InitialContext ctx = new InitialContext();
DataSource ds1 = (DataSource) ctx.lookup("java:comp/env/jdbc/datasource1");
DataSource ds2 = (DataSource) ctx.lookup("java:comp/env/jdbc/datasource2");

Data Source Injection


You can directly inject the data source using annotations as shown below:
Default data source
You do not need to declare the JNDI resource reference in the web.xml deployment descriptor nor in the
resource name, since the default data source will be provided automatically:
@Resource
private javax.sql.DataSource ds;
If the application uses explicitly named data sources, these must be declared in the web.xml file and injected
as shown in the example below:
@Resource(name="jdbc/datasource1")

844

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

private javax.sql.DataSource ds1;


@Resource(name="jdbc/datasource2")
private javax.sql.DataSource ds2;

JDBC Connection
The data source that you have retrieved in the section above allows you to create a JDBC connection to the
database. You can use the resulting Connection object to instantiate a Statement object and execute SQL
statements, as shown in the example below.
private static final String STMT_SELECT_ALL = "SELECT ID, FIRSTNAME, LASTNAME FROM
" + TABLE_NAME;
Connection conn = dataSource.getConnection();
try {
PreparedStatement pstmt = conn.prepareStatement(STMT_SELECT_ALL);
ResultSet rs = pstmt.executeQuery();
...

Database Tables
You use plain SQL statements to create the tables you require. Since there is currently no tool support available,
you have to manually maintain the table life cycles. The exact syntax to be used may differ depending on the
underlying database. The Connection object provides metadata about the underlying database and its tables and
fields, which can be accessed as shown in the code below:
String database = conn.getMetaData().getDatabaseProductName();
To create a table in the Apache Derby database, you could use the following SQL statement executed with a
PreparedStatement object:
private static final String STMT_CREATE_TABLE_DERBY = "CREATE TABLE "
+ TABLE_NAME + " (ID INTEGER GENERATED ALWAYS AS IDENTITY
PRIMARY KEY, " + "FIRSTNAME VARCHAR (255), LASTNAME VARCHAR
(255))";
PreparedStatement pstmt = conn.prepareStatement(STMT_CREATE_TABLE_DERBY);
pstmt.executeUpdate();
Note that the equivalent statement for SAP MaxDB differs as follows:
private static final String STMT_CREATE_TABLE_MAXDB = "CREATE TABLE "
+ TABLE_NAME + " (ID INTEGER DEFAULT SERIAL PRIMARY KEY, " +
"FIRSTNAME VARCHAR (255), LASTNAME VARCHAR (255))";

DAO Objects and SQL Statements


See the tutorial Adding Persistence Using JDBC for an example of how to execute SQL statements and apply the
Data Access Object (DAO) design pattern in your Web application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

845

Note
Remember that the persistence service only supports SAP MaxDB and the SAP HANA database in the cloud. If
you use Apache Derby for local development, bear in mind that the syntax of the SQL statements is not
identical on these databases.

Related Information
Adding Persistence With JDBC (Java Web SDK) [page 746]
Java EE Specification

1.4.8.6

Using the SQL Trace

The SQL trace provides a log of selected SQL statements with details about when a statement was executed and
its duration, allowing you to identify inefficient SQL statements used in your applications and investigate
performance issues. SQL trace records are integrated in the standard trace log files written at runtime.

Context
The SQL trace is disabled by default. Generally, you enable it when you require SQL trace information for a
particular application and disable it again once you have completed your investigation. It is not intended for
general performance monitoring.
You can use the cockpit to enable the SQL trace by setting the log level of the logger
com.sap.core.persistence.sql.trace to the log level DEBUG in the applications log configuration. SQL
trace information can subsequently be viewed in the log files.

Enable the SQL Trace


Procedure
1. Log onto the cockpit and choose

Applications

Java Applications

in the navigation area.

2. Click the relevant application to go to the dashboard.


3. Choose

Monitoring

Logging

in the navigation area.

4. Choose Configure Loggers.


In the Logger Configuration dialog box, all loggers used since the application was started are listed with the log
levels that are currently applicable.

846

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
You can only set log levels when an application is running. Loggers are not listed if the relevant application
code has not been executed.
5. Enter com.sap.core.persistence.sql.trace in the Filter field.
6. In the row containing the com.sap.core.persistence.sql.trace logger, select the log level Debug from
the dropdown list:

The new log setting takes effect immediately. Note that log settings are saved permanently and do not revert
to their initial values when an application is restarted.

View the SQL Trace Details


See the application's trace logs, which contain the SQL trace records, either in the Most Recent Logging panel on
the application dashboard or on the Logging page by navigating to
area.

Monitoring

Logging

in the navigation

Procedure
To display the contents of a particular log file, choose
choosing

(Show). Note that you can also download the file by

(Download).

In the log file, you can identify the SQL trace information by the logger name
com.sap.core.persistence.sql.trace.The entries written by the logger include the following details:
Date and time when written
System time in nanoseconds
The name of the interface and method that produced the log entry, for example,
java.sql.Connection.prepareStatement (sql)
The status of the method call (begin and end)
The database connection ID, for example, conn=[3d194ab9]
The text of the SQL statement, for example, "INSERT INTO T_PERSONS (ID, FIRSTNAME, LASTNAME)
VALUES (?, ?, ?)". Note that for security reasons parameter values are not shown.
Duration of the request (in milliseconds with microsecond precision), for example, Request duration =
2,770.743s

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

847

Example
The SQL-specific information from the default trace is shown below in plain text format:
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676098596447 - javax.sql.DataSource.getConnection() - begin|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676344945627 - javax.sql.DataSource.getConnection() - end - conn=[3d194ab9] Request duration = 227,773.804s - Network traffic = 1462 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676677332569 - java.sql.Connection.prepareStatement(sql) - begin conn=[3d194ab9]|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676723144228 - java.sql.Connection.prepareStatement(sql) - end conn=[3d194ab9] - Request duration = 2,850.647s - Network traffic = 384 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676723530647 - java.sql.PreparedStatement.executeUpdate() - begin conn=[3d194ab9] - SQL="CREATE TABLE T_PERSONS (ID VARCHAR(255) PRIMARY KEY NOT
NULL, FIRSTNAME VARCHAR (255),LASTNAME VARCHAR (255))"|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676736488953 - java.sql.PreparedStatement.executeUpdate() - end conn=[3d194ab9] - Request duration = 12,760.375s - Network traffic = 272 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676767170228 - java.sql.Connection.prepareStatement(sql) - begin conn=[3d194ab9]|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676781082955 - java.sql.Connection.prepareStatement(sql) - end conn=[3d194ab9] - Request duration = 12,987.704s - Network traffic = 464 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676781376595 - java.sql.PreparedStatement.executeQuery() - begin conn=[3d194ab9] - SQL="SELECT ID, FIRSTNAME, LASTNAME FROM T_PERSONS"|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:03 UTC 2014 4913676786626464 - java.sql.PreparedStatement.executeQuery() - end conn=[3d194ab9] - Request duration = 5,118.69s - Network traffic = 264 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682088475475 - java.sql.Connection.prepareStatement(sql) - begin conn=[3d194ab9]|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682093620026 - java.sql.Connection.prepareStatement(sql) - end conn=[3d194ab9] - Request duration = 4,676.661s - Network traffic = 392 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682094713377 - java.sql.PreparedStatement.executeUpdate() - begin conn=[3d194ab9] - SQL="INSERT INTO T_PERSONS (ID, FIRSTNAME, LASTNAME) VALUES
(?, ?, ?)"|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682097611865 - java.sql.PreparedStatement.executeUpdate() - end conn=[3d194ab9] - Request duration = 2,770.743s - Network traffic = 336 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682099273612 - java.sql.Connection.prepareStatement(sql) - begin conn=[3d194ab9]|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682100587082 - java.sql.Connection.prepareStatement(sql) - end conn=[3d194ab9] - Request duration = 1,097.86s - Network traffic = 464 bytes|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682100784872 - java.sql.PreparedStatement.executeQuery() - begin conn=[3d194ab9] - SQL="SELECT ID, FIRSTNAME, LASTNAME FROM T_PERSONS"|
#DEBUG#com.sap.core.persistence.sql.trace#Thu Apr 10 13:25:09 UTC 2014 4913682104569784 - java.sql.PreparedStatement.executeQuery() - end conn=[3d194ab9] - Request duration = 3,626.846s - Network traffic = 308 bytes|

848

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Alternative Tools for Enabling the SQL Trace [page 849]
Cockpit [page 84]
Using Logs in the Cockpit [page 1137]

1.4.8.6.1

Alternative Tools for Enabling the SQL Trace

Besides the cockpit, the SQL trace can be enabled from the Eclipse IDE and using the console client. Whichever
tool you use, you need to set the log level of the logger com.sap.core.persistence.sql.trace to the log
level DEBUG.

Eclipse
You can set the log level for applications deployed locally or in the cloud.
See Using Logs in the Eclipse IDE [page 1131]

Console Client
You can use the console client to set the log level as a logging property for one or more loggers. To do so, use the
command neo set-log-level with the log parameters logger <logger_name> and level <log_level>.
See Using Logs in the Console Client [page 1134]

Related Information
Deploying on the Cloud with the Console Client [page 983]

1.4.8.7

Remote Database Access

Database instances in the cloud are protected by a firewall, in other words, they are not directly accessible.
Access to remote database instances is therefore only possible through a database tunnel, which provides a
secure connection from your local machine and bypasses the firewall.
A database tunnel allows you to use database tools, such as the SAP HANA studio or Eclipse Data Tools Platform,
to connect to the remote database instance. It provides you with direct access to a schema and allows you to
manipulate it at database level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

849

SAP HANA Database


The SAP HANA studio provides the most convenient option for connecting to the remote database, since it
automatically opens the database tunnel for you and closes it when you disconnect. It is therefore the
recommended tool to use. Bear in mind that if you choose to use another tool you will have to explicitly open the
database tunnel yourself.
To connect to the remote database using the SAP HANA studio (Eclipse with appropriate plugins), proceed as
described in:
Connecting to SAP HANA Schemas via the Eclipse IDE [page 864]
In the wizard, select the Trial instances radio button and then select your database schema from the dropdown
box.
For continuous integration and test automation, you can open a database tunnel using scripting or as part of a
Maven build. See Automating the Use of Database Tunnels [page 856].

SAP ASE Database


If you are working with SAP ASE databases, you need to explicitly open a database tunnel:
1. To open a database tunnel, see Opening a Database Tunnel [page 851].
2. To connect to the remote database using the Eclipse Data Tools Platform (DTP), see Connecting to the
Remote SAP ASE Database [page 858].

SAP MaxDB
If you are working with SAP MaxDB, you need to explicitly open a database tunnel:
1. To open a database tunnel, see Opening a Database Tunnel [page 851].
2. To connect to the remote database using the Eclipse Data Tools Platform (DTP), see Connecting to the
Remote SAP MaxDB Database [page 865].

Restriction
For SAP MaxDB, the functionality described in this section is available as a beta version and can be used on the
trial landscape only.

Related Information
Opening a Database Tunnel [page 851]
Automating the Use of Database Tunnels [page 856]
Connecting to the Remote SAP MaxDB Database [page 865]

850

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

open-db-tunnel [page 210]

1.4.8.7.1

Opening a Database Tunnel

A database tunnel allows you to connect to a remote database instance through a secure connection. To open a
tunnel, use the open-db-tunnel command. When you open the tunnel, you will obtain the connection details
required for the remote database instance, including a user and password.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Procedure
1. Open the command window in the <SDK>/tools folder.
2. Enter the following command to open a tunnel:
neo open-db-tunnel -h <host> -u <user> -a <account> --id <schema ID>
If the tunnel is opened successfully, the following details are displayed:
Host name: Always localhost
Database type: HANA, HANAMDC, HANAXS, ASE, or MaxDB
JDBC URL: For example, jdbc:sap://localhost:30015. Required for the Eclipse Data Tools Platform
(DTP).
Instance number: For example, 00. Required for the SAP HANA studio.
User: User for connecting to the database
For SAP HANA database (MDC) and SAP ASE database, no user or password is displayed. You can use
the user that you created.
Password/Initial password: Password for the database login. An initial password is only shown for
schemas with database type HANAXS on productive SAP HANA instances.
Schema name: For database types HANA and HANAXS

Next Steps
Now that you have opened the database tunnel, you can connect to the remote database instance using the
connection details you have just obtained.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

851

Note
The database tunnel must remain open while you work on the remote database instance. Close it only when
you have completed the session.

Related Information
open-db-tunnel [page 210]
Connecting to the Remote SAP MaxDB Database [page 865]
Connecting to SAP HANA Databases via the Eclipse IDE [page 861]
Connecting to SAP HANA Schemas via the Eclipse IDE [page 864]
Access to Databases in Other Accounts [page 852]
create-db-user-ase [page 117]

1.4.8.7.1.1 Access to Databases in Other Accounts


You want to access data from a database in another account (provider account) and you need the required
permissions. The provider account gives you (consumer account) access by providing you with a token and a
database user, which you use to open a database tunnel to the other account.
The table below lists the tasks and the person responsible for providing access to the database in another
account:
Table 275:
Task

Responsible

More Information

Providing Access to Databases in Other


Accounts

Account administrator in the provider


account

Providing Access to Databases for Other


Accounts [page 853]

Opening a Database Tunnel to Data


bases in Other Accounts

Member of the consumer account

Opening Tunnels to Databases in Other


Accounts [page 854]

Giving tunnel access works with productive SAP HANA instances and databases with multitenant database
container support enabled.

Related Information
Providing Access to Databases for Other Accounts [page 853]
Opening Tunnels to Databases in Other Accounts [page 854]
open-db-tunnel [page 210]
grant-db-tunnel-access [page 164]
list-db-tunnel-access-grants [page 194]

852

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

revoke-db-tunnel-access [page 222]

1.4.8.7.1.1.1 Providing Access to Databases for Other Accounts


As an account member with the Administrator or Developer role in the provider account, you can give applications
in other accounts access to a database in your account using a database tunnel. You need the Developer or
Administrator role.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].

Context
To give database access permissions, create a database user (for the consumer account) for connecting to the
database and provide this user, together with an access token, to the consumer account member. This allows the
consumers to open a database tunnel to the database in your account. All members of the consumer account
have permission to access the database in the provider account.
Provide the following information to the consumer account member:
Access token to open the database tunnel

Note
The token is simply a random string, for example,
31t0dpim6rtxa00wx5483vqe7in8i3c1phv759w9oqrutf638l, which remains valid until the provider account
revokes it again.
Database user
Password
In addition, you have the following options:
To check if the database access has been given successfully, you can view a list of all currently active
database access permissions to other accounts, which exist for a specified account, by using the list-dbtunnel-access-grants command.
You can revoke the database access permission at any point in time using the revoke-db-tunnel-access
command.

Note
Only the provider account can revoke the access permission. When you revoke the access permission, we
highly recommend that you disable the database user and password created for the access permission on
the database itself and that you close any open sessions on the SAP HANA database.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

853

If an account member has already used the access token and there are open database tunnels, they remain open
until they are closed, even though the user has been disabled.
We highly recommend that you create a dedicated database user on the database for each access permission.

Procedure
1. Open the command window in the <SDK>/tools folder.
2. Enter the following command:
neo grant-db-tunnel-access -h <host> -u <user> -a <provider account> -i
<database ID> --to-account <consumer account>
If the permission has been given successfully, the access token is displayed. As a database administrator, you
create a database user with the needed permissions. Provide the database user and password together with
the access token to the consumer account member.

Related Information
Opening Tunnels to Databases in Other Accounts [page 854]
Guidelines for Creating Database Users [page 1013]
open-db-tunnel [page 210]
grant-db-tunnel-access [page 164]
list-db-tunnel-access-grants [page 194]
revoke-db-tunnel-access [page 222]

1.4.8.7.1.1.2 Opening Tunnels to Databases in Other Accounts


As a consumer account member you need access to a database in another account. You request permission from
the provider account who provides you an access token, a database user, and password. This allows you to open a
database tunnel from your account to the other account and allows you to access the database.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].
The provider account has given you an access token, a database user, and password.

854

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Once you have the permission from the provider account, you can open the database tunnel. You use the access
token parameter for the open-db-tunnel command instead of the database ID parameter. Then you can use
SAP HANA studio, or any other database tool of your choice, to connect to the database in another account. Log
on to the database with the user and password that you received from the provider. You can then work on the
remote database instance. This works just like the open-db-tunnel command, except that you use the access
token instead of the database ID.

Note
All members of the consumer account have permission to access the database in the provider account.

Procedure
1. Open the command window in the <SDK>/tools folder.
2. Enter the following command to open a tunnel to the database in another account:
neo open-db-tunnel -h <host> -u <user> -a <consumer account> --access-token
<myaccess-token>
If the tunnel is opened successfully, the following details are displayed:
Host name: Always localhost
Database type: HANAXS or HANAMDC
JDBC URL: For example, jdbc:sap://localhost:30015. Required for the Eclipse Data Tools Platform
(DTP).
Instance number: For example, 00. Required for the SAP HANA studio.

Next Steps
Now that you have opened the database tunnel, you can connect to the database instance in another account with
SAP HANA studio, using the connection details you have just obtained. Add a system by choosing Add System
from the Systems context menu in the SAP HANA Administration Console perspective and enter the required
data:
1. Specify the host name and instance number of the system.

Note
Copy the details that you used to open the tunnel from the command window.
2. Authenticate with your database user and password.

Note
Use the details that you received from the provider.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

855

You can now access the database.

Related Information
Providing Access to Databases for Other Accounts [page 853]
Opening a Database Tunnel [page 851]
open-db-tunnel [page 210]

1.4.8.7.2

Automating the Use of Database Tunnels

For the purposes of continuous delivery and automated tests, the open-db-tunnel command supports a
background mode, which allows a database tunnel to be opened by automated scripts or as part of a Maven build.

Opening the Database Tunnel in Scripts


The example below shows how to automatically execute an SQL statement on an SAP HANA database via a
database tunnel.

Prerequisites
You have a continuous integration (CI) server that can execute Bash scripts, for example, Jenkins running on
Linux.
You have set up the console client on the CI server. For more information, see Setting Up the Console Client
[page 42].
You have installed the SAP HANA client on the CI server. For more information, see SAP HANA Client
Installation Guide.

Procedure
1. Create a new job on the CI server.
2. Set the password for your account in the environment variable HCP_PASSWORD, either globally on the CI
server or just for the newly created job.
3. Configure the job to execute the following Bash script:
#!/bin/bash -ex
PATH=$PATH:~/sap/neo/tools:~/sap/hdbclient
to PATH

856

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

# add console client and HANA client

SAP HANA Cloud Platform


SAP HANA Cloud Platform

user=mymail@example.com
account=myaccount
dbSchema=myschema

# TODO replace with your user ID


# TODO replace with your account ID
# TODO replace with your schema

json=$(neo.sh open-db-tunnel -h hanatrial.ondemand.com -a "$account" -u "$user" p "$HCP_PASSWORD" -i "$dbSchema" --background --output json)
regex='.*"host":"([^"]*)".*"port":
([^,]*),.*"instanceNumber":"([^"]*)".*"dbUser":"([^"]*)".*"dbUserPassword":"([^"
]*)".*"sessionId":"([^"]*)".*'
[[ $json =~ $regex ]]
dbHost=${BASH_REMATCH[1]}
dbPort=${BASH_REMATCH[2]}
dbInstance=${BASH_REMATCH[3]}
dbUser=${BASH_REMATCH[4]}
dbPassword=${BASH_REMATCH[5]}
tunnelSessionId=${BASH_REMATCH[6]}
hdbsql -n "$dbHost:$dbPort" -i "$dbInstance" -u "$dbUser" -p "$dbPassword"
"SELECT * FROM dummy"
neo.sh close-db-tunnel --session-id $tunnelSessionId

Results
You have set up a CI job that automatically executes an SQL statement on your SAP HANA database instance.
Depending on what you would like to achieve, you could now modify the job to execute different SQL statements.

Related Information
open-db-tunnel [page 210]
close-db-tunnel [page 109]

Opening the Database Tunnel in Maven Builds


Prerequisites
You have set up the console client on the CI server. For more information, see Setting Up the Console Client [page
42].

Procedure
To open or close the database tunnel in a Maven build, use the following goals of the SAP HANA Cloud Platform
Maven plugin:
open-db-tunnel

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

857

close-db-tunnel

Tip
Take a look at the following samples delivered with the SAP HANA Cloud Platform SDK:
persistence-with-ejb
persistence-with-jpa
Each sample includes a test that opens a database tunnel in background mode within the Maven build and
executes some SQL statements.

Related Information
SAP HANA Cloud Platform Maven Plugin Documentation
persistence-with-ejb [page 724]
persistence-with-jpa [page 735]

1.4.8.7.3

Connecting to the Remote SAP ASE Database

You use the Eclipse Data Tools Platform (DTP) to connect to the SAP ASE database in the cloud. To do this, you
require the connection details you obtained when you opened the database tunnel.

Procedure
1. In Eclipse, choose

Window

Show View

Data Source Explorer .

2. Select the Database Connections node and from the context menu choose New....
3. Select the connection profile type Sybase ASE
4. Enter a connection name, for example, New Sybase ASE, and choose Next.
5. To define a driver, choose

New Driver Definition.

6. As the driver template, select Sybase JDBC Driver for Sybase ASE 15.x and enter a driver name, for example,
Sybase JDBC Driver for Sybase ASE 15.x.
7. On the JAR List tab, select the jconn3.jar driver file.
8. Choose Edit JAR/Zip and choose the neo-java-web-sdk-2.<version>/repository/.archive/lib/jconn4<version>.jar file.

Note
Make sure you use the latest version of the SDK for Java Web Tomcat 7 runtime. You can download the
SDK from the tools page.

858

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

9. On the Properties tab, change the value for the Driver Class property from com.sybase.jdbc3.jdbc.SybDriver
to com.sybase.jdbc4.jdbc.SybDriver and choose Ok.
Use the value from the current SDK version.
10. On the Connection tab, enter the required data for the connection:
Host: localhost
Provide the database host name from the tunnel response.
Port: 30015
Provide the database port from the JDBC URL in the tunnel response.
Database name: Provide the database name from the tunnel response.
User name: Provide the database user that you defined when you created the database.
Password: Provide the password of the database user.
11. On the Other Properties tab, enter two parameters and their values:
a. Enter the following parameter and set it to true: SSL_TRUST_ALL_CERTS=true.
b. Check the value of the parameter ENABLE_SSL in the tunnel response.

If the value is set to true, enter the following on the Other Properties tab: ENABLE_SSL=true. If the value
is set to false or if the parameter does not appear at all in the tunnel response, enter ENABLE_SSL=false.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

859

12. Test the connection.


13. Choose Finish.
14. You are now connected to a remote SAP ASE database.

Next Steps
The new database connection is now shown in the Data Source Explorer view in the database list.

860

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.7.4

Connecting to SAP HANA Databases via the Eclipse


IDE

Connect to a dedicated SAP HANA database using SAP HANA Tools via the Eclipse IDE.

Prerequisites
You have installed and set up all the necessary tools. For more information, see Installing SAP HANA Tools for
Eclipse [page 58].

Procedure
1. Go to

Window

Open Perspective

Other .

2. Select SAP HANA Administration Console and choose OK.


3. From the Systems context menu, choose

Add Cloud System.

4. In the dialog that appears, provide the landscape host and account information:
a. For the landscape host, the default landscape host is displayed. Specify the productive or trial landscape
to which your account is assigned.
A dropdown list is displayed for previously entered landscapes hosts. For more information about
landscapes, see Landscape Hosts [page 32].

Note
Make sure that you specify the landscape host correctly.
b. Specify the account name, e-mail or SCN user name, and your SCN password.
If you have previously entered an account and user name for the selected landscape host, the names are
prompted to you in dropdown lists.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

861

c. Choose Next.
5. Select a database and provide your credentials:
a. Select the Databases radio button.
b. From the dropdown menu, select the database you want to work with.
c. Enter your database user and password.
For more information, see Creating a Database Administrator User [page 1014].

Note
Make sure that you specify the database user and password correctly.
If you select the Save password box, the entered password for a given user name is remembered and kept
in the secure store.
A dropdown list is displayed for previously entered database user names. Database passwords can be
remembered and stored in the principle mentioned above.

862

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

d. Choose Finish.

Results
You are now connected to a dedicated SAP HANA database.

Related Information
Using a Productive SAP HANA Database System [page 1010]
Creating a Database Administrator User [page 1014]
Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

863

1.4.8.7.5

Connecting to SAP HANA Schemas via the Eclipse


IDE

Follow the procedure below to make a direct connection to a shared SAP HANA schema via the Eclipse IDE, using
SAP HANA Tools.

Prerequisites
You have installed and set up all the necessary tools. For more information, see Installing SAP HANA Tools for
Eclipse [page 58].

Procedure
1. Go to

Window

2. Select

Show View

SAP HANA

Systems

Other .
and choose OK.

3. From the Systems context menu, choose

Add Cloud System.

4. The Account Information window displays the landscape host. Modify it manually entering your productive or
trial landscape. For more information about landscapes, see Landscape Hosts [page 32].
5. Enter your SAP HANA Cloud Platform account information: account name, e-mail or user name, and
password. For more information, see Accounts [page 11].

Note
If you have previously entered an account and user name for your landscape host, these names will be
prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.
If you select the Save password box, the entered password for a given user name will be remembered
and kept in the secure store.

864

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Choose Next.
7. In the SAP HANA Schemas and Databases window, choose radio button Schemas.
8. From the dropdown menu, select the schema you want to work with.
You must have created a schema previously to be able to select it in this step.
9. Choose Finish.
10. You are now connected to a shared SAP HANA schema.

1.4.8.7.6

Connecting to the Remote SAP MaxDB Database

You use the Eclipse Data Tools Platform (DTP) to connect to the SAP MaxDB database in the cloud. To do this,
you require the connection details you obtained when you opened the database tunnel.

Prerequisites
You have the connection details available that you obtained when you opened the database tunnel.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

865

Context

Restriction
For SAP MaxDB, this functionality is available on the trial landscape only. Do not use it in productive scenarios
and/or with any personal data.

Procedure
1. In Eclipse, open the Data Source Explorer view.
2. Select the Database Connections node and from the context menu choose New.
3. Select the connection profile type MaxDB.
4. Enter a connection name, for example, Database Tunnel to MaxDB, and choose Next.
5. To define a driver, choose New Driver Definition.
6. As the driver template, select MaxDB JDBC Driver Version 7.7 and enter a driver name, for example,
Database Tunnel JDBC Driver.
7. On the JAR List tab, add the driver JAR <neo-sdk-<version>>\repository\plugins
\com.sap.dbtech<version>.jar, and remove the predefined one.
8. Choose OK to confirm.
9. In the URL field, enter the JDBC URL from your connection details.
These are the connection details you obtained when you opened the database tunnel.
10. Enter the user name and password shown in your connection details.
11. Choose Finish.

Next Steps
The new database connection is now shown in the Data Source Explorer view. You can find your schema in the
schema list under your schema user name.

Tip
To locate your schema, filter the list:
1. Select the database connection and from the context menu choose Properties.
2. Select Default Schema Filter and deselect the Disable filter checkbox.
3. In the Name field, enter your user (NEO_<string>) and choose OK.
Open the schema and navigate down to your Web applications database tables, where you can display their
properties and data and use the SQL Scrapbook editor.

866

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Opening a Database Tunnel [page 851]

1.4.8.8

Local Testing

If an application uses the default data source and runs locally on Apache Derby, provided as standard for local
development, it can be tested on the local runtime without any further configuration. To use explicitly named data
sources or a different database, you need to configure the connection.properties file appropriately.

Related Information
Configuring Data Sources As Connection Properties [page 867]
Replacing the Local Database [page 869]

1.4.8.8.1

Configuring Data Sources As Connection


Properties

To test an application on the local server, you need to define any data sources the application uses as connection
properties for the local database. This step is not necessary if the application uses the default data source.

Prerequisites
The local server has already been started at least once (with or without the application), otherwise the relevant
folder wont exist.

Procedure
1. In the Project Explorer view, open the folder Servers/SAP HANA Cloud local runtime/
config_master/connection_data and select connection.properties.
2. From the context menu, choose

Open With

Properties File Editor .

3. Add the connection parameter com.sap.cloud.persistence.dsname to the block of connection


parameters for the local database you are using, as shown in the example below:
com.sap.cloud.persistence.dsname=jdbc/datasource1
javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

867

javax.persistence.jdbc.url=jdbc:derby:memory:DemoDB;create=true
javax.persistence.jdbc.user=demo
javax.persistence.jdbc.password=demo
eclipselink.target-database=Derby
If the application has been bound to the data source based on an explicitly named data source instead of
using the default data source, ensure the following:
Provide a data source name in the connection properties that matches the name used in the data source
binding definition.
Add prefixes before each property in a property group for each data source binding you define. If an
application is bound only to the default data source, this configuration is considered the default no matter
which name you specified in the connection properties. The application can address the data source by
any name.
4. Repeat this step for all data sources that the application uses.
5. For the Java EE 6 Web Profile runtime, add the connection parameter
com.sap.cloud.persistence.dsname twice, once for the managed data source and once for the
unmanaged data source, with the names given below. Each entry has to be added to its own block of
connection properties:
com.sap.cloud.persistence.dsname=jdbc/defaultManagedDataSource
com.sap.cloud.persistence.dsname=jdbc/defaultUnmanagedDataSource
6. To indicate that a block of parameters belong together, add a prefix to the parameters, as shown in the
example below. Note that the prefix is freely definable and the dot is not mandatory:
1.com.sap.cloud.persistence.dsname=jdbc/datasource1
1.javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
1.javax.persistence.jdbc.url=jdbc:derby:memory:DemoDB;create=true
1.javax.persistence.jdbc.user=demo
1.javax.persistence.jdbc.password=demo
1.eclipselink.target-database=Derby
2.com.sap.cloud.persistence.dsname=jdbc/defaultManagedDataSource
2.javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
2.javax.persistence.jdbc.url=jdbc:derby:memory:DemoDB;create=true
2.javax.persistence.jdbc.user=demo
2.javax.persistence.jdbc.password=demo
2.eclipselink.target-database=Derby
3.com.sap.cloud.persistence.dsname=jdbc/defaultUnmanagedDataSource
3.javax.persistence.jdbc.driver=org.apache.derby.jdbc.EmbeddedDriver
3.javax.persistence.jdbc.url=jdbc:derby:memory:DemoDB;create=true
3.javax.persistence.jdbc.user=demo
3.javax.persistence.jdbc.password=demo
3.eclipselink.target-database=Derby
7. Save the file.
8. Start or restart the server so that the new properties are read.

868

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.8.8.2

Replacing the Local Database

You have the option of replacing your local embedded Derby instance with SAP MaxDB.

Context
The persistence service automatically establishes connections as follows:
Local development: connection to the default databases Apache Derby
Deployment in the cloud: connection to different database systems including SAP HANA database systems
enabled for multitenant database containers, SAP ASE or SAP MaxDB
An application developed for SAP HANA Cloud Platform may be executed in different environments, where
development and testing typically occur on a developer's PC, regression testing on a build server, and deployment
in the cloud. The persistence service allows an application to abstract from the different execution environments
by externalizing the connection data and automatically establishing the connections to the relevant databases.
The following steps explain how to replace the local database:

Procedure
1. In the Project Explorer view, open the folder Servers/SAP HANA Cloud local runtime/
config_master/connection_data and select connection.properties.
2. From the context menu, choose

Open With

Properties File Editor .

3. Comment out the connection parameters for the local Derby database connection and instead comment in
those for SAP MaxDB. (This also changes the target database for EclipseLink.)
4. Specify the parameters for host, instance, user, and password according to your system setup.
5. Save the file.

Note
Since the SAP HANA Cloud Platform SDK includes the MaxDB JDBC driver, you do not need to explicitly
add the JDBC driver JAR to the WEB-INF/lib folder of your Web application project.

Related Information
Opening a Database Tunnel [page 851]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

869

1.4.8.9

Frequently Asked Questions

Answers to some of the most commonly asked questions about the persistence service.

Does the persistence service provide access to a NoSQL database?


The persistence service currently provides access to a relational database only.

Which database platforms are available in the cloud?


SAP HANA Cloud Platform offers SAP ASE and SAP HANA databases.

How often does a backup occur? How much data can I lose in the worst case?
For productive databases, a full data backup is done once a day. Log backup is triggered at least every 30
minutes. The corresponding data or log backups are replicated to a secondary location every two hours. Backups
are kept (complete data and log) on a primary location for the last two backups and on a secondary location for
the last 14 days. Backups are deleted afterwards. Recovery is therefore only possible within a time frame of 14
days. Restoring the system from files on a secondary location might take some time depending on the availability.
SAP offers to back up and recover shared and dedicated database systems only as a whole.
For new database offerings such as SAP ASE and SAP HANA databases with multitenant database container
(MDC) support (beta), you can operate several databases in the same database system and recover them
individually. Thus, when binding applications to databases, you can achieve a fine grained control of the backup
and recovery.

I am using JPA with EclipseLink and have denoted a property of type String
with @Lob. Why is a VARCHAR column of limited length created in the
database?
Due to the EclipsLink bug 317597 , the @Lob annotation is ignored when the corresponding table column is
created in the database. To enforce the creation of a CLOB column, you have to additionally specify
@Column(length=4001) for the property concerned. In fact, any value may be chosen as long as it is at least 4001
for SAP MaxDB or 2001 for the SAP HANA database.

870

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

I tested my app locally with the Apache Derby database, so why do I run into
SQL exceptions when deploying it in the cloud?
Different database systems use different system tables and reserved words. As an application developer, make
sure that the application does not use any of these reserved words for its own table and column names.
JPA does also not shield the application from this. If, for example, your entity class contains an attribute named
"date", this will clash with the reserved word DATE on SAP MaxDB and cause schema creation to fail upon
deployment. In such a case, the attribute should either be renamed to something else, or be mapped to another
column name in the database. This can be done using the @Column annotation like this:
@Column(name="THEDATE")
private String date;
Tips:
Check the root cause in the application log. (A link to the log is provided in the application overview in the
cockpit. For more information, see Using Logs in the Cockpit [page 1137].)
For a complete list of reserved words, refer to the relevant database documentation (SAP MaxDB SQL
Reference Manual , Apache Derby Documentation ).

How can I restart SAP HANA Database Systems?


If your databases are not working properly, you can try to solve the issues by restarting the corresponding SAP
HANA database system. The restart is done for the whole database system.
You can restart a database system in the following ways:
To restart an SAP HANA database system from the cockpit, proceed as follows:
1. Log on to the cockpit and select an account for which SAP HANA database systems are available.
2. Choose

Persistence

Database Systems

in the navigation area.

3. To select the entry for the relevant database system in the list, click the link on its name.
4. In the overview of the database system, choose Restart.
During the restart, you can monitor the system status using the HANA tools. Connected applications and
database users cannot access the system until it is restarted. The restart for the database system is complete
when HANA tools like SAP HANA cockpit are available again.
To restart an SAP HANA database system from the console client, use the restart-hana [page 220]
command.
To restart a single tenant database instead of the whole database system, use the stop-db-hana [page 246] and
start-db-hana [page 241] commands or the cockpit.

1.4.9 Remote Data Sync Service

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

871

Context
The Remote Data Sync service provides bi-directional synchronization of complex structured data between many
remote databases at the edge and SAP HANA cloud databases at the center. The service is based on SAP SQL
Anywhere and its MobiLink technology.
Using Remote Data Sync you can create occasionally-connected applications at the edge. These include
applications that are not suitable or economical to have a permanent connection, or applications that must
continue to operate in the face of unexpected network failures.
Also, you can create applications that use a local database and synchronize with the cloud when a connection
is available.
Remote Data Sync allows you to create remote applications that store and share large amounts of data
between the application and the cloud. This can significantly reduce latency for data-rich applications and
provide a more responsive user experience for remote applications.
A single cloud database may have hundreds of thousands of data collection and action endpoints that operate in
the real world over sometimes unreliable networks. Remote Data Sync provides a way to connect all of these
remote applications and to synchronize all databases at the edge into a single cloud database.

872

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The figure below illustrates a typical IoT scenario using the Remote Data Sync service: Sensors or smart meters
create data that is sent and stored decentrally in small embedded databases, such as SQL Anywhere or SQL
Anywhere UltraLite. To get a consolidated view on the data of all remote locations, this data is synchronized in
the following:
SAP HANA database on the cloud via SQL Anywhere MobiLink clients, running on the edge devices;
SQL Anywhere MobiLink servers, which are provided in the cloud by the Remote Data Sync service.
New insights can be later gained by analytics and data mining on the consolidated data in the cloud.

Process Flow
1. Get [page 874] your licenses.
2. Provision [page 875] a MobiLink server in your account which allows you to use the Remote Data Sync
service.
3. Develop [page 877] a client-initiated synchronization.
4. Access [page 885] the MobiLink logs during development.
5. Protect [page 887] your MobiLink server.
6. Connect [page 888] the SQL Anywhere tools to the MobiLink server.
7. Configure [page 891] an availability monitor for your MobiLink server.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

873

Sizing
Before you start working with the service, you might want to check its sizing requirements in order to choose the
optimal hardware features for fluent run of your applications. For more information, see Performance and
Scalability of the MobiLink Server [page 892].

Related Information
SAP SQL Anywhere 16.0 Documentation

1.4.9.1

Getting Access to the Remote Data Sync Service

Prerequisites
You have an account in a productive SAP HANA Cloud Platform landscape (e.g. hana.ondemand.com,
us1.hana.ondemand.com, ap1.hana.ondemand.com, eu2.hana.ondemand.com).
Your SAP HANA Cloud Platform account has an SAP HANA instance associated to it. The Remote Data Sync
service is currently only supported with SAP HANA database as target database in the cloud.
On the edge side, you need to install SAP SQL Anywhere Remote Database Client version 16. You can
get a free Developer Edition

. See also the existing production packages: Overview

Context
The procedure below helps you to make the Remote Data Sync service available in your SAP HANA Cloud
Platform account. As the service is not available for your SAP HANA Cloud Platform account by default, you need
to first fulfill the prerequisites above and then follow the procedure described below to request the Remote Data
Sync service for your account.

Note
Before you start working with the service, you might want to check its sizing requirements in order to choose
the optimal hardware features for fluent run of your applications. For more information, see Performance and
Scalability of the MobiLink Server [page 892].
To get access to the Remote Data Sync service, you need to extend your standard HCP license with an a-la-carte
license for Remote Data Sync in one of two flavors:

874

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. Remote Data Sync, Standard: MobiLink server on 2 Cores / 4GB RAM (Price list material number: 8003943 )
2. Remote Data Sync, Premium: MobiLink sever on 4 Cores / 8 GB RAM (Price list material number: 8003944 )

Next Steps
Provisioning a MobiLink Server in Your Account [page 875]

1.4.9.2

Provisioning a MobiLink Server in Your Account

Prerequisites
You have received the needed licences and have enabled the Remote Data Sync service for your account. For
more information, see Getting Access to the Remote Data Sync Service [page 874].
You have installed and configured the console client. For more information, see Using the Console Client
[page 89].

Context
To use the Remote Data Sync service, a MobiLink server must be started and bound to the SAP HANA database of
your account. This can be done by the following steps (they are described in detail in the procedure below):
1. Deploy the MobiLink server on a compute unit of your account using the console client.
2. Bind the MobiLink server to your SAP HANA database to connect the MobiLink server to the database.
3. Start the MobiLink server within the console client.

Note
To provision a MobiLink server in your account, you need a free compute unit of your quota. The Remote Data
Sync service license includes an additional compute unit for the MobiLink server.

Procedure
1. Deploy the MobiLink server on a compute unit of your account using the deploy command. You can
configure the MobiLink server to be started with customized server options (see MobiLink Server Options
You can do this either during deployment using the --ev parameter, or later on using the set-

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

).

875

application-property command. You can also specify the compute unit by using the --size parameter
of the deploy command.
neo.bat deploy -h <landscape_host> -a <account> -b <mobilink_service_instance> u <user_name> -s EMPTY_SITE --runtime mobilink
Exemplary MobiLink options configuration during development and starting MobiLink server on a
premium compute unit:
neo.bat deploy -h hana.ondemand.com -a myaccount -b mymlinstance -u
p1234567890 -s EMPTY_SITE --runtime mobilink --ev ML_ARGS="-zf -v" --size prem
Exemplary MobiLink options configuration after deployment.
NOTE: You need to first have a MobiLink server deployed before you can set application properties via the
command below. Also, if your MobiLink server has been already started, you'll need to restart the server
in order for the changes to take effect. All previously set environment variables will be overriden.
neo.bat set-application-property -h hana.ondemand.com -a myaccount -b
mymlinstance -u p1234567890 --ev ML_ARGS="-zf -v"
2. Bind the MobiLink server to your SAP HANA database. This is needed to connect the MobiLink server to the
database.

Note
Prerequisite: You have created a SAP HANA database user dedicated to the MobiLink server instance. For
more information, see Guidelines for Creating Database Users [page 1013].
Hint: In case your SAP HANA instance is configured to create database users with a temporary password
(the user is forced to reset it on first logon), you need to do it before creating the binding.
neo.bat bind-hana-dbms -h <landscape_host> -a <account> -b
<mobilink_service_instance> -u <user_name> -i <hana_instance_name> --db-user
<db_user_name> --db-password <db_user_password>
3. Start your MobiLink server:
neo.bat start -h <landscape_host> -a <account> -b <mobilink_service_instance> -u
<user_name>
4. Test the state of your MobiLink server.
If the application VM is in Started state, your server is up and running.
If the application VM remains in App Server Timeout state and does not manage to start, check the
logs of the MobiLink server. See Accessing MobiLink Server Logs [page 885].

Note
In case you find the log message below, your binding step is missed or unsuccessfully executed:
Persistence binding is missing! Please check your binding configuration. In
case of further issues, contact support team.
5. You can stop or undeploy your MobiLink server. For more information, see stop [page 244] or undeploy [page
254].

876

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Next Steps
Developing Client-Initiated Synchronization [page 877]

1.4.9.3

Developing Client-Initiated Synchronization

Prerequisites
An SQL Anywhere version 16 installation is available on the client side. For more information, see Getting
Access to the Remote Data Sync Service [page 874].
A MobiLink server is running in your account. For more information, see Provisioning a MobiLink Server in
Your Account [page 875].

Context
This page provides a simple example that demonstrates how to synchronize data from a remote SQL Anywhere
database into the SAP HANA database, using the Remote Data Sync service and the underlying SQL Anywhere
MobiLink technology. For more information on MobiLink synchronizations, see Quick start to MobiLink
(Synchronization) .

Tip
The SQL Anywhere database running on the client side is called remote database. The central SAP HANA
database running on SAP HANA Cloud Platform is called consolidated database.

Procedure
1. Connect to a local database
This demo database will be used as a source for the synchronization.
1. Start Sybase Central.
2. From the top-level menu, choose

Connections

Connection Profiles

SQL Anywhere 16 Demo

profile.

3. Choose Connect.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

877

2. Create a new user


1. In Sybase Central, double-click MobiLink Users.
2. From the context menu, choose

New

MobiLink User .

3. Enter a user name, for example TEST_USER, and choose Finish.


4. Choose the Back button in the toolbar menu to get back to the root task level.

878

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Create a new table in the remote database


1. In Sybase Central, goto Database Design Tasks .
2. Open the context menu above the tabs and choose Open Interactive SQL.
3. Execute the following script:

Sample Code
CREATE TABLE hello_world (
pkey BIGINT NOT NULL,
first_name VARCHAR ( 10 ) DEFAULT '' NOT NULL,
last_name VARCHAR ( 10 ) DEFAULT '' NOT NULL,
PRIMARY KEY ( pkey )
);

4. Create a publication
1. In Sybase Central, double-click Publications.
2. From the context menu, select

New

Publication .

3. Enter hello_world_publication as the name and choose Next.


4. Leave the publication type Log scan and choose Next.
5. Select the hello_world table and choose Finish.
6. Choose the Back button in the toolbar menu to get back to the root task level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

879

5. Create a synchronization subscription


1. In Sybase Central, double-click Synchronization Subscriptions.
2. From the context menu, select

New

Subscription .

3. Enter hello_world_subscription as the name and choose v1 as the script version.


4. Select hello_world_publication and TEST_USER, and choose Finish.
5. Choose the Back button in the toolbar menu to get back to the root task level.

880

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Create a synchronization profile


1. In Sybase Central, double-click Synchronization Profiles.
2. From the context menu, select

New

Synchronization Profile .

3. Enter hello_world_sync_profile as the name.


4. Skip the comment wizard and choose Finish.
5. In the new Synchronization Profile Properties view, select hello_world_subscription and choose OK.
6. Set the script version number for Synchronization Profile in the Extended Options tab and choose OK.
7. Choose the Back button in the toolbar menu to get back to the root task level.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

881

7. Connect the MobiLink client to the MobiLink server


1. In Sybase Central, double-click Synchronization Profiles.
2. Select hello_world_sync_profile, and from its context menu, choose Properties.
3. Go to the Connection tab.
4. Fill in the connection details of the MobiLink server as described below:
Protocol: HTTPS
Host: URL to the MobiLink server. To see this URL, open the cockpit and navigate to Java Applications.
From the list of applications, select the MobiLink server (NOTE: as of today, it appears as a Java
application), and then copy the Application URL for the application shown in the Application Details view.
Port: 443

882

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Proxy host: define your local proxy host, if available


Proxy port: define your local proxy port, if available
5. Choose OK.
6. Choose the Back button in the toolbar menu to get back to the root task level.

8. Insert sample data in the hello_world table


1. In Sybase Central, select the demo database.
2. From its context menu, choose Open Interactive SQL.
3. Execute the following script:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

883

Sample Code
insert into hello_world (pkey, first_name, last_name) values (50, 'John',
'Miller');'
insert into hello_world (pkey, first_name, last_name) values (52, 'Olivia',
'Snider');
4. Choose the Back button in the toolbar menu to get back to the root task level.

9. Run a synchronization
1. In Sybase Central, double-click Synchronization Profiles.
2. Select hello_world_sync_profile, and from its context menu, choose Synchronize and then OK.
3. Check for errors in the synchronization output. The lines will be colored in red if there is an sync failure.
4. Use SAP HANA Studio to validate that the data from the remote database has been synchronized into the
consolidated SAP HANA database.
5. Choose the Back button in the Sybase Central toolbar menu to get back to the root task level.

Next Steps
Accessing MobiLink Server Logs [page 885]
Audit Logging of MobiLink Synchronizations [page 886]

1.4.9.4

884

MobiLink Server Logs

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tasks
Accessing MobiLink Server Logs [page 885]
Audit Logging of MobiLink Synchronizations [page 886]

Related Information
Provisioning a MobiLink Server in Your Account [page 875]

1.4.9.4.1

Accessing MobiLink Server Logs

Context
You can access the MobiLink server logs both in the cockpit and the console client.

Procedure
Accessing Logs in the Cockpit
1. Open the cockpit.
2. In the left navigation, choose Java Applications. For the time being, your MobiLink server appears as a Java
application.
3. Find the MobiLink server name which you have specified during MobiLink provisioning and choose it.
4. In the Most Recent Logging section, click the

icon to view the logs, or the

icon to download them.

Accessing Logs in the Console Client


1. Open the console client, navigating to the <SDK_installation>/tools directory.
2. To list all available logs of the MobiLink runtime, execute the list-logs command below (exemplary data is
given):
Example:
neo list-logs --account myaccount --application mymobilinkserver --user
p1234567890 --host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

885

3. To download the log file of the MobiLink server, execute the get-log command below (exemplary data is
given):
Example:
neo get-log --account myaccount --application mymobilinkserver --user
p1234567890 --host hana.ondemand.com --directory C:\MyMobiLink\log --file
mobilink_runtime_2015-03-10.log

Related Information
Audit Logging of MobiLink Synchronizations [page 886]
list-logs [page 201]
get-log [page 162]

1.4.9.4.2

Audit Logging of MobiLink Synchronizations

This page helps you to achieve end-to-end traceability of all synchronizations done via the Remote Data Sync
service of SAP HANA Cloud Platform. This way, you can track who made what changes during work on the SAP
HANA target database in the cloud.

SAP HANA Auditing Activity


To monitor and record which users performed selected actions on SAP HANA database, you can use the SAP
HANA Audit Activity with Database Table as trail target. To use this feature, it must first be activated for your SAP
HANA database, which can be done via SAP HANA Studio by a database user with role HCP_SYSTEM.
Use an SAP HANA database table as the trail target makes it possible to query and analyze auditing
information quickly. It also provides a secure and tamper-proof storage location.
Audit entries are only accessible through the public system view AUDIT_LOG. Only SELECT operations can be
performed on this view by users with the system privilege AUDIT OPERATOR or AUDIT ADMIN.
For more information about how to configure audit policy, see SAP HANA Administration Guide and SAP HANA
Security Guide.

MobiLink Server Log as Audit Log


Additionally to the SAP HANA audit logs, you might want to use the MobiLink server logs to achieve end-to-end
traceability.
We recommend that you set the log level of the MobiLink server to a value that produces logs in granularity
useful for end-to-end traceability of the performed synchronization operations. For example, the log level vtRU. For more information about this log level configuration, see -v parameter documentation .

886

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To configure the log level, use the deploy command in the console client. For more information, see
Provisioning a MobiLink Server in Your Account [page 875].

Remember
SAP HANA Cloud Platform retains the MobiLink server log files for only a week. To fulfill the legal requirements
regarding retention of audit log files, make sure you download the log files regularly (at least once a week), and
keep them for a longer period of time according to your local laws.

Related Information
Accessing MobiLink Server Logs [page 885]

1.4.9.5

Authentication Configuration of a MobiLink Server

Context
This section provides information about security-related operations and configurations you can perform in a
Remote Data Sync scenario.
Currently, as part of SAP HANA Cloud Platform, the MobiLink servers support only basic authentication. For
more information, see User Authentication Architecture

Tasks
Creating MobiLink Users in a Consolidated Database
Configuring a MobiLink Client to Use Transport-Layer Security

using the dbmlsync -e option

Note
On HCP, MobiLink clients can only be connected via HTTPS to MobiLink servers in the cloud, i.e. plain
HTTP connections are not supported.
There are different options how to configure the HTTPS connection, depending on the SQL Anywhere
synchronization tool that is used to trigger synchronizations:
When using SQL Anywhere dbmlsync command line tool to trigger client-initiated synchronizations,
trusted certificates can be specified using the trusted_certificates parameter as described here
.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

887

When using the Sybase Central UI to trigger client-initiated synchronizations, you can specify Trusted
certificates as described here

Related Information
MobiLink Users
MobiLink Security
SQL Anywhere Certificate Utilities
MobiLink Client Configuration to use TLS
SQL Anywhere User and Database Security
MobiLink Client/Server Communication Encryption

1.4.9.6

Connecting SQL Anywhere Tools to MobiLink Servers

Prerequisites
An SQL Anywhere version 16 installation is available on the client side. For more information, see Getting
Access to the Remote Data Sync Service [page 874].
A MobiLink server is running in your account. For more information, see Provisioning a MobiLink Server in
Your Account [page 875].

Context
The page describes how existing tools of SQL Anywhere (SQL Anywhere Monitor and MobiLink Profiler)
can be connected and used with the Remote Data Sync service running on SAP HANA Cloud Platform.

Tasks
Connecting SQL Anywhere Monitor to a MobiLink Server [page 889]
Connecting the MobiLink Profiler to a MobiLink Server [page 890]

888

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
SQL Anywhere Monitor
MobiLink Profiler

1.4.9.6.1

Connecting SQL Anywhere Monitor to a MobiLink


Server

Context
SQL Anywhere Monitor comes as part of the standard SQL Anywhere installation. You can find it under
Administrative Tools of SQL Anywhere 16. The tool provides basic information about the health and availability of a
SQL Anywhere and MobiLink landscape. It also gives basic performance information and overall synchronization
statistics of the MobiLink server.

Procedure
1. To start the SQL Anywhere Monitor tool, open the SQL Anywhere 16 installation and go to Administrative
Tools.
2. Open the SQL Anywhere Monitor dashboard via URL: http://<host_name>:4950, where <host_name> is
the host of the computer where SQL Anywhere Monitor is running.
3. Log in with the default credentials: user= admin , password= admin .
4. In the dashboard, go to

Tools

Administration

Resources

5. Choose Add.
6. Select MobiLink Server and proceed with the wizard, providing the following details:
MobiLink server:
As Host, specify the fully qualified domain name of the MobiLink server running in your SAP HANA
Cloud Platform account.
As Port, specify 8443.
As Connection Type, specify HTTPS. Leave the rest unchanged.
MobiLink user: provide the credentials of a valid MobiLink user.
Collection interval: time interval after which SQL Anywhere Monitor contacts the MobiLink server again to
fetch data
7. Once the resources have been added, you can start monitoring the MobiLink server and add widgets to show
different performance metrics, such as Sync Metrics, MobiLink Server Info, Raw Metrics, and so on.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

889

Next Steps
SQL Anywhere Monitor also allows you to configure e-mail alerts for synchronization problems. For more
information, see Alerts .

Related Information
Monitoring Availability of the MobiLink Server [page 891]

1.4.9.6.2

Connecting the MobiLink Profiler to a MobiLink


Server

Context
MobiLink Profiler comes as part of the standard SQL Anywhere installation. You can find it under Administrative
Tools of SQL Anywhere 16. The tool collects statistical data about all synchronizations during a profiling session,
and provides performance details of the single synchronizations, down to the detailed level of a MobiLink event. It
also provides access to the synchronization logs of the MobiLink server. Therefore, the tool is mostly used to
troubleshoot failed synchronizations or performance issues, and during the development phase to further analyze
synchronizations, errors or warnings.

Procedure
1. Start the MobiLink Profiler under Administrative Tools of SQL Anywhere 16. The tool is a desktop client and
does not run in a Web browser.
2. Open

File

Begin Profiling Session

to connect to the MobiLink server of your cloud account.

3. In the Connect to MobiLink Server window, provide the appropriate connection details, such as:
Host: specify the fully qualified domain name of the MobiLink server running in your SAP HANA Cloud
Platform account.
Port: 8443
User/Password: the credentials of a valid MobiLink user.
Protocol: HTTPS
Trusted certificate file: Needed in case certificate based authentication is used to connect to the MobiLink
server. You need to specify the local path to the certificate file.
Additional protocol options: Specify additional protocol options, such as proxy_host and proxy_port if
needed for connecting to the MobiLink server.

890

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Next Steps
To learn more about the UI of the MobiLink Profiler, see MobiLink Profiler Interface

1.4.9.7

Monitoring Availability of the MobiLink Server

Prerequisites
An SQL Anywhere version 16 installation is available on the client side. For more information, see Getting
Access to the Remote Data Sync Service [page 874].
A MobiLink server is running in your account. For more information, see Provisioning a MobiLink Server in
Your Account [page 875].

Context
This page describes how you can configure an availability check for your MobiLink server and subscribe recipients
to receive alert e-mail notifications when your server is down or responds slowly. Furthermore, recommended
actions are listed in case of issues.

Procedure
1. Open the console client, navigating to the <SDK_installation>/tools directory.
2. To create the availability check, execute the following command (exemplary data).
Example:
neo create-availability-check -a myaccount -b mymlinstance -u p1234567890 -U /
status -C 6 -W 4 -h hana.ondemand.com
3. To subscribe recipients to notification alerts, execute the following command (exemplary data).
Example:
neo set-alert-recipients -a myaccount -b mymlinstance -u p1234567890 -e
john.smith@google.com -h hana.ondemand.com

Tip
To add multiple e-mail addresses, separate them with commas. We recommend that you use distribution
lists rather than personal e-mail addresses. Keep in mind that you will remain responsible for handling of
personal e-mail addresses with respect to data privacy regulations applicable.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

891

Next Steps
Recommended actions in case of issues:
Check the logs. In case of synchronization errors, use the MobiLink Profiler tool to drill down into the
problem for root cause analysis.
In case of crude server startup parameters, reset the MobiLink server.
If your MobiLink server hangs, restart it.

Related Information
Configuring Availability Checks for Java Applications from the Console Client [page 1154]

1.4.9.8

Performance and Scalability of the MobiLink Server

This page provides sizing information for applications using the Remote Data Sync service.
Although the only realistic answers to optimal resource planning are It depends and Testing will show what you
need, this section aims to help you choose the right hardware parameters.

Synchronization Phases
The figure below shows the major phases of a synchronization session. Though not complete, it covers many
common use cases.
1. Synchronization is initiated by a remote database client. It uploads any changes made at the remote database
to the server.
2. MobiLink applies the changes to the database.
3. MobiLink queries the database and prepares the changes to be sent to the remote database client.
4. MobiLink sends the changes to the remote database client.

892

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Roughly, the MobiLink server uses two thread pools one for database connections, and one for the network side.
These can be controlled by command-line options, although, by default, the Remote Data Sync service
dynamically tunes the size of the worker thread pool to accommodate load changes.

Database Capacity
When the Remote Data Sync server applies changes to the consolidated database and prepares changes to be
sent to the remote database client, it typically does so by executing SQL statements or stored procedures that are
invoked by MobiLink events. For example, to apply an upload MobiLink may execute insert, update, and delete
statements for each table being synchronized; to prepare a download MobiLink may execute a query for each
table being synchronized.
Database tuning is outside the scope of this document, but the load on the database can be substantial. Think of
MobiLink as a concentrator of database load. All the operations that are carried out against the remote database
while disconnected, in addition to the requests for updates to be downloaded to the remote database, are
executed in two transactions (1 upload, 1 download) against the consolidated database. This can place a heavy
load on the database.

Maximum Number of Concurrent Synchronizations


You should know the number of concurrent synchronizations as a starting point, and from there on, calculate
back on the required resources. Typically, this number is limited by RAM requirements. To estimate, you need a
typical upload and download data volume as a starting point.
A machine with N MB of RAM can have C clients each with about V MB of upload or download data volume, where
C = N/V.
Following this formula, for large synchronizations (< 20 MB), you can have:
Remote Data Sync service, Standard: C = 4096/20 C @ 200 simultaneous syncs
Remote Data Sync service, Premium: C = 8192/20 C @ 400 simultaneous syncs

Maximum Sustainable Throughput


The rate limiting steps of a synchronization are commonly:
Data transfer, in the case of slow networks
Database operations, especially in the case of complex schemas and complex synchronization logic.
Remote Data Sync servers are not typically CPU intensive, and typically require less than half the processing that
is required by the consolidated database. When selecting the appropriate compute units for MobiLink, memory is
more likely to limit the maximum sustainable throughput for a Remote Data Sync server than CPU.
Example:
1. Let's assume the database can process the target load of L synchronizations per second (and that is a matter
for testing).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

893

2. At this throughput, one database thread will come open every 1/L seconds. To keep throughput high, a
synchronization request should be ready, with data uploaded and available to pass to the database thread.
3. To keep the database busy, if a synchronization request takes t seconds to upload (which will depend on
network speed and data volume, and which should be determined by testing), then the Remote Data Sync
server must be able to hold (L x t) client data uploads in memory.
4. The Remote Data Sync server must also be able to download the data to the client to prevent the database
threads having to wait for a network connection to download. In the case, this volume is similar to the uploads
we end up with: MobiLink should be able to support (2 x L x t) simultaneous synchronizations to maintain a
throughput of L synchronizations per second.

Note
For example, to support a peak sustained throughput of 50 synchronizations per second, with a client that
takes 0.5 seconds to upload and download data, then the Remote Data Sync server should be able to support
50 simultaneous synchronizations in RAM to sustain this rate as a peak throughput. Assuming data transfer
volumes per client are less than 80 MB (which is a very high number for data synchronization), a Standard
machine would be a good choice to start with.

1.4.10 SAP Translation Hub (Beta)


SAP Translation Hub enables you to translate texts by accessing records in a multilingual database using a range
of Web services.

Note
This is a beta feature available on SAP HANA Cloud Platform for developer accounts. For more information
about the beta features, see Using Beta Features in Accounts [page 22].
To provide users of software in a global market with texts in their own language, translations are required. SAP
Translation Hub enables you to satisfy the demands of a global market by enabling you to translate short texts in
applications into additional languages quickly and easily. SAP Translation Hub enables you to draw on SAP's
translation experience across multiple products and languages to propose translations for short texts in
applications.
You can consume the services of SAP Translation Hub in the following ways:
Direct consumption of Web services to propose texts in English or to provide translations of texts that are
created during the development of applications
For more information, see Consuming the SAP Translation Hub Services in the Related Information section.
Indirect consumption of Web services to translate properties files in Git projects as part of the translation
workflow
For more information, see Translation Workflow with SAP Translation Hub in the Related Information section.

894

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Architecture Overview
SAP Translation Hub is an SAP HANA Cloud Platform service that uses the in-memory technology of SAP HANA.
At the core of SAP Translation Hub are multilingual texts from SAP applications that are stored in an SAP HANA
database.
SAP Translation Hub comprises a set of Web services that you can use to access the multilingual texts in the
database.
The following figure shows the high-level architecture of SAP Translation Hub:

Related Information
Supported Languages [page 896]
Consuming the SAP Translation Hub Services [page 899]
Translation Workflow with SAP Translation Hub [page 919]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

895

Troubleshooting [page 927]


SAP Translation Hub - FAQ

1.4.10.1 Supported Languages


SAP Translation Hub contains texts in a number of different languages.
The languages in which SAP Translation Hub contains texts are listed in the following table:

Note
To get the latest list of languages, call <base URL of SAP Translation Hub>/translationhub/api/v1/
languages.
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
Table 276:
Name of Language

ID of Language

Afrikaans

af

Arabic

ar

Bulgarian

bg

Catalan

ca

Chinese

zh

Chinese (Traditional)

zf

Croatian

hr

Czech

cs

Danish

da

Dutch

nl

English

en

Estonian

es

Finnish

fi

French

fr

German

de

Greek

el

Hebrew

he

Hindi

hi

Hungarian

hu

Icelandic

is

Indonesian

in

896

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Name of Language

ID of Language

Italian

it

Japanese

ja

Kazakh

kk

Korean

ko

Latvian

lv

Lithuanian

lt

Malay

ms

Norwegian

no

Polish

pl

Portuguese

pt

Romanian

ro

Russian

ru

Serbian

sr

Serbian (Latin)

sh

Slovak

sk

Slovenian

sl

Spanish

es

Swedish

sv

Thai

th

Turkish

tr

Ukrainian

uk

Vietnamese

vi

Related Information
Building Base URL of SAP Translation Hub [page 897]

1.4.10.2 Building Base URL of SAP Translation Hub


The base URL is main part of the complete URL that you need to access the services of SAP Translation Hub.
To access the services and user interface of SAP Translation Hub on SAP HANA Cloud Platform, you require the
base URL plus additional parameters that are specific to the individual services and features in SAP Translation
Hub.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

897

The following table summarizes the parts of the base URL:


Table 277:
Landscape Host

Base URL

Sample Base URL

Trial

https://saptranslation<account name on
HCP>.hanatrial.condemand.co
m/

https://saptranslations0001001002trial.hanatrial.
ondemand.com/

Note
For details about the name of the service and the query parameters that you add to the base URL, see the
documentation for the individual services.

Related Information
Domain Service [page 902]
Language Service [page 903]
Suggestion Service [page 905]
Text Type Service [page 908]
Translation Service [page 910]
Translation Project Service [page 914]
Translation Workflow with SAP Translation Hub [page 919]

1.4.10.3 User Authentication and Authorization


An authorization process controls access to SAP Translation Hub.
To be able to consume the services and features of SAP Translation Hub, you must set up authorizations for the
users on SAP HANA Cloud Platform who are to access SAP Translation Hub.

Prerequisites
The users who need to access SAP Translation Hub have user credentials in SAP Identity Service.

Note
If you have an S user that you use to log on to platforms like SAP Jam or SAP Community Network (SCN), you
can use the same user ID to register for a trial account on SAP HANA Cloud Platform. The resulting account
name on SAP HANA Cloud Platform will be <s user>trial.

898

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Process
When you enable SAP Translation Hub in the SAP HANA Cloud Platform service catalog, the system automatically
assigns your HCP user to the required role. No further assignments are required for your user.
If you want to enable other users to use the service, assign the required users to the User role.

Note
For the role assignments to take effect once you have made them, either open a new browser session or log out
from the cockpit and log on to it again.

1.4.10.4 Consuming the SAP Translation Hub Services


SAP Translation Hub comprises a set of Web services that applications can consume to translate texts using a
multilingual text repository.
You can use the Web services to translate texts, for example, in SAP Cloud for Customer, your own translation
user interface, or through a translation tool that you create in an integrated development environment (IDE). In
this section, you will learn how to consume the SAP Translation Hub services on SAP HANA Cloud Platform.
The Web services that SAP Translation Hub comprises are as follows:
Domain
Language
Suggestion
Text type
Translation
Translation project

Access
You access the Web services only through the HTTPS protocol. Standard functions of SAP Identity Service
manage user authorizations for the services.
To be able to consume the SAP Translation Hub services, work through the following items:
1. Have you got a developer account on SAP HANA Cloud Platform?
If you have, proceed to the next step. If you don't, no worries. It takes just a moment to request a free trial
developer account at https://account.hanatrial.ondemand.com/.

Note
If you have an S user that you use to log on to platforms like SAP Jam or SAP Community Network (SCN),
you can use the same user ID to register for a trial account on SAP HANA Cloud Platform. The resulting
account name on SAP HANA Cloud Platform will be <s user>trial.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

899

2. If you've heard about SAP Translation Hub before, maybe you've already enabled the SAP Translation Hub
service for your account? If you have, you're good to go with the next step. If you haven't, complete the next
couple of steps:
1. In the SAP HANA Cloud Platform cockpit, choose Services in the navigation tree.
2. Choose SAP Translation Hub Enable .
For more information about enabling services, see Accessing Services in the Related Information section.

Note
You don't need to configure any destinations.
3. If several people need to access the SAP Translation Hub services, assign the roles of those users.
For more information about role assignments, see User Authentication and Authorization in the Related
Information section.

URL of Services
To access the services, you'll need the base URL of SAP Translation Hub plus the service name and servicespecific parameters. For information about the base URL, see Building Base URL of SAP Translation Hub in the
Related Information section.

Parameters
To filter or modify the response, the Web services use query parameters that are located in the query part of the
URL, for example, as follows:
<base URL of SAP Translation Hub>/translationhub/api/v1/languages?
search=<query_parameters>

Content
The Web services use JSON as the content of the HTTPS request or response. All of the service responses that
contain JSON have the JSON content type application/json; charset=utf-8.

Troubleshooting
If you run into difficulties when trying to consume the services in SAP Translation Hub, check out the frequently
asked questions (FAQ) page on SCN at SAP Translation Hub - FAQ .

900

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Error Handling
Table 278: Error Codes
Error

400 Bad Request


Content-Length: 0
404 Not Found

Description
If not all of the required query parameters are specified or an
invalid value type is passed, an HTTPS Bad Request status is
returned.
If the wrong URL is used to call a service, an HTTPS Not Found
status is returned.

Content-Length: 0

SAP API Hub


Interesting in consumuing the services of SAP Translation Hub from a central console? Check out the SAP API
Hub service on SAP HANA Cloud Platform.

Related Information
Accessing Services
Building Base URL of SAP Translation Hub [page 897]
Consuming APIs in SAP API Hub
Domain Service [page 902]
Language Service [page 903]
Suggestion Service [page 905]
Text Type Service [page 908]
Translation Service [page 910]
Translation Project Service [page 914]
Testing the Services [page 918]
User Authentication and Authorization [page 898]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

901

1.4.10.4.1 Domain Service


The domain service enables you to access the domains available in SAP Translation Hub.

Usage
SAP product terminology is organized by domains. Domains are used in the translation process to determine the
correct terminology for a given application.
The domain service returns a list of the domains that are available in SAP Translation Hub. You can combine the
domain service with the suggestion service to narrow down the results of the suggestion service.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/domains

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: GET
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8.

Note
If you do not use this content type, the service call fails.
To check whether a specific domain is available, you can add the following parameter to the URL:
Table 279:
Parameter

Description

Type

search

Shows whether a particular domain is available in SAP Trans


lation Hub. For example: <base URL of SAP

Optional

Translation Hub>/translationhub/api/v1/
domains?search=<domain_name>

Note
You can enter all or part of the domain name, for example,
accounting.

902

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Request Body Example


<base URL of SAP Translation Hub>/translationhub/api/v1/domains?search=Financial

Response
The result is a JSON object, and contains the following key-value pairs:
Table 280:
Key

Description

Part of Response?

id

The ID of a domain.

Always in response

name

The short description of a domain.

Always in response

Response Body Example


{

"domains":[
{
},
{
},
{

"id":"FI",
"name":"Financial Accounting"
"id":"FS",
"name":"Financial Services"
"id":"FB",
"name":"Financials Basis"

1.4.10.4.2 Language Service


The language service enables you to access the languages available in SAP Translation Hub.

Usage
Returns a list of the languages that SAP Translation Hub supports.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/languages

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

903

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: GET
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8.

Note
If you do not use this content type, the service call fails.
To check whether a specific language is available, you can add the following parameter to the URL:
Table 281:
Parameter

Description

Type

search

Determines whether a particular language is available in SAP


Translation Hub. For example: <base URL of SAP

Optional

Translation Hub>/translationhub/api/v1/
languages?search=<language_name>

Note
You enter the name of the language, for example, Chinese,
not the ID for Chinese.

Request Body Example


<base URL of SAP Translation Hub>/translationhub/api/v1/languages?search=Bulgarian

Response
The result is a JSON object, and contains the following key-value pairs:
Table 282:
Languages Key

Description

Part of Response?

id

The ID of a language.

Always in response

name

The name of the language.

Always in response

Response Body Example


{

904

"languages":[
{
"id":"bg",
"name":"Bulgarian"
}

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Building Base URL of SAP Translation Hub [page 897]
Testing the Services [page 918]

1.4.10.4.3 Suggestion Service


The suggestion service enables you to get suggestions for short texts during the development process.

Usage
Provides suggestions for short texts in English based on comlpete or partial texts and their translations used in
SAP products. You can, for example, use the suggestion service to propose texts while you type in a development
environment. The texts that the service proposes are already available in additonal languages in the multilingual
text repository.

Note
You can search for suggestions only by using English as the source language.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/suggestions

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: GET
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8.

Note
If you do not use this content type, the service call fails.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

905

You can use the following parameters by adding them to the URL:

Note
If you want to use multiple parameters, prefix each parameter name with an ampersand (&). If you want to
enter multiple parameter values for a given parameter, enter a comma between each parameter value.
Table 283:
Parameter

Description

Type

search

Searches for a text in SAP Translation Hub. For example:


<base URL of SAP Translation Hub>/
translationhub/api/v1/suggestions?search=<text>

Mandatory

language

Searches for a text that has translations in the specified lan


guage(s). For example, you can search for texts that have
translations in German (DE) and French (FR).

Optional

domain

Searches for texts in the specified domain(s). For example,


you can search for terms that are assigned to the domain for
Customer Relationship Management (B2).

Optional

texttype

Searches for texts assigned to the specified text type(s). For


example, you can search for terms that are assigned to the
text type field label (XFLD).

Optional

Request Body Example


<base URL of SAP Translation Hub>/translationhub/api/v1/suggestions?
search=user_name&texttype=XFLD&domain=B2&language=de,fr

Response
The suggestion service response has a JSON root object with a single property suggestion. The response contains
the following key-value pairs:
Table 284:
Parameter

Description

Part of Response?

id

A key that uniquely identifies the text's entry in the database.

Always in response

value

The text entered in the request.

Always in response

domainId

The ID of the domain assigned to the translations of the text


entered in the request.

Depends on request

domainName

The name of the domain assigned to the translations of the


text entered in the request.

Depends on request

texttypeId

The ID of the text type assigned to the text entered in the re


quest.

Depends on request

texttypeName

The name of the text type assigned to the text entered in the
request.

Depends on request

englishValue

The text - in English - entered in the request.

Always in response

906

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameter

Description

Part of Response?

availableLanguages

The total number of languages, including English, in which


Always in response
there are translations of the requested text in SAP Translation
Hub.

availableFilteredLanguages

If you use the language parameter in the request, this parame Depends on request
ter shows the number of languages in that parameter in which
translations of the text was found. For example, if you specify
French (FR) and German (DE) in the language parameter of
the request, but there are translations of the requested text
only in French, the value of this key is 1. If there are transla
tions in both French and German, the value of this key is 2.

textSpace

Indicates length specifications of the text entered in the re


quest. textSpace comprise multiple parameters see next ta
ble.

Always in response

textSpace Parameter

Description

Part of Response?

inputChars

The number of characters contained in the text entered in the


request.

Always in response

minRecChars

The minimum recommended number of characters to set


aside in the UI to accommodate a potential length increase in
translations.

Always in response

minRecEm

The minimum recommended length to set aside in the UI to


accommodate a potential length increase in translations. It is
measured in em.

Always in response

Table 285:

Response Body Example


{

"suggestions" : [
{
"id": 6260958,
"value": "User Name",
"domainID": "B2",
"domainName": "Customer Relationship Management",
"texttypeId": "XFLD",
"texttypeName": "Label",
"englishValue": "User Name",
"availableLanguages": 30,
"availableFilteredLanguages": "2",
"textSpace":
{
"inputChars": 9,
"minRecEm": 13,
"minRecChars": 20
}
}
]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

907

1.4.10.4.4 Text Type Service


The text type service enables you to access the text types available in SAP Translation Hub.

Usage
Short texts, for example, those used on user interfaces (UIs), in SAP products are characterized by various text
types. The type of a specific text is determined by the UI element that it describes.
The text type service returns a list of the text types that are available in SAP Translation Hub. You can combine
the text type service with the suggestion service to narrow down the results of the suggestion service.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/texttypes

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: GET
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8.

Note
If you do not use this content type, the service call fails.

908

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To check whether a specific text type is available, you can add the following parameter to the URL:
Table 286:
Parameter

Description

Type

search

Shows whether a particular text type is available in SAP


Translation Hub. For example: <base URL of SAP

Optional

Translation Hub>/translationhub/api/v1/
texttypes?search=<text type name>

Note
You can enter all or part of the name of the text type, for
example, message.

Request Body Example


<base URL of SAP Translation Hub>/translationhub/api/v1/texttypes?search=message

Response
The result is a JSON object, and contains the following key-value pairs:
Table 287:
Key

Description

Part of Response?

id

The ID of a text type.

Always in response

name

The short description of a text type.

Always in response

Response Body Example


{

"texttypes":[
{
"id":"MSAG",
"name":"Message Classes"
},
{
"id":"XMSG",
"name":"Message text"
}
]
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

909

1.4.10.4.5 Translation Service


The translation service enables you to get translations of English short texts that exist in SAP Translation Hub.

Usage
Provides translations of English short texts based on existing texts and their translations that are used in SAP
products.
Each record in the multilingual text repository comprises the source language in English plus translations for a
combination of domain and text type, which you can enter as additional request parameters.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/translate

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: POST
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8. If you do not use this content type, the service call fails.
The JSON request contains an array of bundle JSON objects. A bundle represents a single localization object, for
example, a Java property file or an Android XML file. The following tables below show the different key-value pairs
in the JSON request:

Note
To better understand the keys of the JSON request shown in the following tables, see the sample code for the
request body below the tables.
Table 288:
Root Key

Description

targetLanguages

The IDs of the target languages in which you want the service Optional
to return translations of texts. To view the supported language
IDs, call the language service. If you do not specify any target
languages, the service returns the texts in all available target
languages.

910

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Type

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Root Key

Description

Type

enableTranslationQualityEsti
mation

Shows an estimation of the linguistic quality of translations


based on ratings that language specialists provide.

Optional

bundles

Represents a single localization object (for example, a Java


property file or an Android XML file). Each bundle comprises
one or more bundles keys - see the next table.

Mandatory

Bundles Key

Description

Type

domain

The ID of a translation domain, for example, BC. If you do not


specify a domain, the service searches for translations in all
available domains.

Optional

Table 289:

Note
It is not possible to enter multiple domains.
units

Describes a single text that you want to translate. The units


key comprises multiple property keys - see the next table.

Mandatory

Units Key

Description

Type

value

The text to be translated.

Mandatory

textType

The ID of a text type, for example, XFLD for a field label.

Optional

Table 290:

Note
It is not possible to enter multiple text types.
key

A key that uniquely identifies the UI text in the bundle.

Optional

searchData

Optional
A parameter that allows you to specify the translation of a UI
text in a language other than English. For example, take the
text 'Cancel'. In German, this could be translated as 'Abbre
chen' or 'Stornieren'. If you know that the translation in a given
instance should be 'Abbrechen', you can specify 'Abbrechen'
so that the correct translation in German (and in other lan
guages) is returned. This parameter has two mandatory prop
erties: language (the language ID provided by the language
service) and value (the UI text in the required target language,
that is, a language other than English).

Request Body Example


{

"targetLanguages" : ["en", "de", "fr", "bg", "ru"],


"enableTranslationQualityEstimation" : true,
"bundles" : [
{
"domain" : "B2",
"units" : [
{
"textType" : "XFLD",

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

911

"key" : "LOGIN_USERNAME_FIELD",
"value" : "User Name",
"searchData" :
{
"language" : "de",
"value" : "Benutzername"
}
}
]

Response
The translation response is in JSON format. The response contains an array of bundles keys; each bundles key in
the response corresponds to a bundles key in the request. If there is more than one bundles key, the sequence of
these keys from the request is retained. The response contains the following key-value pairs:
Table 291:
Root Key

Description

Part of Response?

bundles

Represents a single localization object (for example, a Java


property file or an Android XML file). Each bundles key can
comprise multiple keys - see the next table.

Always in response

Each bundles key in the response corresponds to a bundles key in the request, and contains the following keys:
Table 292:
Bundles Key

Description

Part of Response?

domain

The ID of the translation domain specified in the response, for


example, BC.

Depends on request

units

Describes a single text that you want to translate and addi


tional context information. The units key comprises multiple
keys - see the next table.

Always in response

Each units key in the response corresponds to a units key in the request, and contains the following keys:
Table 293:
Units Key

Description

Part of Response?

value

The text to be translated.

Always in response

textType

The ID of the text type, for example, XFLD.

Depends on request

key

A key that uniquely identifies the UI text in the bundle.

Depends on request

translations

Describes the translated text. The translations key comprises


multiple keys - see the next table.

Always in response

For each target language that is specified in the targetLanguages key in the request, there is a set of translations
keys in the response. If you specify a value for the searchData key in the request, the translation is based on the
text in the value parameter that you specify in the request.

912

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
If a translation does not exist in one of the target languages specified in the request, the set of translations keys
for that target language is not part of the response. If there are no translations of the text, the translations key
is part of the response, but is empty.
Table 294:
Translations Key

Description

Part of Response?

language

The ID of the target language in which the text is translated.

Depends on request

value

The translation of the text.

Depends on request

translationQualityEstimation

The translationQualityEstimation key comprises the


qualityIndex key, which shows the estimated translation qual
ity based on ratings that language specialists provide. The
higher the number on a scale of 1-100, the better the quality.

Depends on request

Response Body Example


{
"bundles" : [
{
"domain":"B2",
"units" : [
{
"textType" : "XFLD",
"key" : "LOGIN_USERNAME_FIELD",
"value" : "User Name",
"translations" : [
{
"language":"de",
"value":"Benutzername"
},
{
"language":"fr",
"value":"Nom utilisateur"
},
{
"language":"en",
"value":"User Name"
},
{
"language":"ru",
"value":" "
}
]
}
]
}
]
}

Related Information
Building Base URL of SAP Translation Hub [page 897]
Language Service [page 903]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

913

Testing the Services [page 918]

1.4.10.4.6 Translation Project Service


The translation project service enables you to translate English short texts that exist in SAP Translation Hub, and
to edit the translations in a translation project.

Usage
Provides translations of English short texts based on existing texts and their translations that are used in SAP
products. The service provides translations in the response and creates a translation project in SAP Translation
Hub. You can use the translation project to view and revise translations.

Note
You can translate texts only by using English as the source language.

Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/translationProject

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.
HTTP Method: POST
Request Parameters
The service requires a JSON request payload and the request content type: application/json;
charset=utf-8. If you do not use this content type, the service call fails.
The JSON request contains data and entries keys. The data key contains meta information, such as the domain
and required target languages, and the entries key contains the texts to be translated. The following tables show
the key-value pairs in the JSON request:

Note
To better understand the keys of the JSON request shown in the following tables, see the sample code for the
request body below the tables.

914

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 295:
Data Key

Description

Type

domain

The ID of a translation domain, for example, BC. If you do not


specify a domain, the service searches for translations in all
available domains.

Optional

Note
It is not possible to enter multiple domains.
languages

The IDs of the target languages in which you want the service Optional
to return translations of texts. To view the supported language
IDs, call the language service. If you do not specify any target
languages, the service returns the texts in all available target
languages.

textType

The ID of a text type, for example, XFLD for a field label.

Optional

objectName

The unique ID of the object whose texts you want to translate.

Mandatory

Entries Key

Description

Type

key

Describes a single text that you want to translate.

Mandatory

value

The text to be translated.

Mandatory

Table 296:

Request Body Example


{

"data": {
"domain": "BC",
"languages": "de,it,fr,zh",
"objectName": "ba2d72da-73x8-491b-k684-f59397ed786e"
},
"entries": [
{
"key": "TEXT1",
"value": "User Name"
},
{
"key": "TEXT2",
"value": "Purchase Order"
}
]

Response
The translation response is in JSON format. The response contains the following key-value pairs:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

915

Table 297:
Data Key

Description

Part of Response?

objectName

The unique ID of the object whose texts you want to translate.

Always in response

The entries key in the response contains a set of key-value pairs for each combination of text and required target
language specified in the entries key in the request, as shown in the following table:.
Table 298:
Entries Key

Description

Part of Response?

key

The ID of the translation domain specified in the request, for


example, BC.

Depends on request

value

The translated text.

Always in response

language

The ID of the target language in which the text is translated.

Always in response

Note
If a translation does not exist in one of the target languages specified in the request, the response does not
contain the set of key-value pairs for that target language. If there are no translations of a text in the request,
the entries key is part of the response, but is empty.
Response Body Example
{

"data": {
"objectName": "ba2d72da-73x8-491b-k684-f59397ed786e"
}
"entries": {
"key": "TEXT2"
"value": "Bestellung"
"language": "de"
}
{
"key": "TEXT2"
"value": "Commande d'achat"
"language": "fr"
}
{
"key": "TEXT2"
"value": "Ordine di acquisto"
"language": "it"
}
{
"key": "TEXT2"
"value": ""
"language": "zh"
}
{
"key": "TEXT1"
"value": "Benutzername"
"language": "de"
}
{
"key": "TEXT1"
"value": "Nom de l'utilisateur"
"language": "fr"
}
{

916

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

"key": "TEXT1"
"value": "Nome utente"
"language": "it"
}
{
"key": "TEXT1"
"value": ""
"language": "zh"
}

Related Information
Building Base URL of SAP Translation Hub [page 897]
Language Service [page 903]
Revising Translations in a Translation Project [page 917]

1.4.10.4.6.1 Revising Translations in a Translation Project


You can use a translation project to revise the translations that SAP Translation Hub provides when you translate
texts using the translation project service.

Context
When you call the translation project service, the service does the following:
Provides translations in the service response
Creates a translation project in SAP Translation Hub
To revise translations in a translation project, proceed as follows:

Procedure
1. Call the SAP Translation Hub UI by choosing Go to Service in the service description for SAP Translation Hub
in the SAP HANA Cloud Platform cockpit. Alternatively, you can access the UI by calling the following URL:
<base URL of SAP Translation Hub>/ui
2. On the SAP Translation Hub UI, choose the translation project that refers to the object whose translations you
want to view or change.
The name of the project is the ID that you specify for the objectName key in the request payload of the
translation project service.
3. Choose the Edit Translations tab.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

917

4. Change the translations as required and save the translation project.


SAP Translation Hub saves the updated translations in the translation project. To consume the updated
translations in the translation project service, call the translation project service again.

Related Information
Building Base URL of SAP Translation Hub [page 897]

1.4.10.4.7 Testing the Services


To test the individual Web services, for example, the translation service, in SAP Translation Hub, you can use a
REST service client.
This topic explains how you can test the SAP Translation Hub services using the sample data provided in the
corresponding service documentation.
To test the services, you can use a REST service client, for example, one of the clients that you can install as an
extension to a Web browser.

Process
1. In the REST service client, enter the URL specified in the service documentation.
2. Ensure that you specify the following attributes correctly for each service:
Method value: GET or POST
Content-Type parameter in the header: application/json; charset=utf-8

Note
To consume the services, you must enter the user and password for your trial account on SAP HANA Cloud
Platform. Depending on the REST service client that you use, you are asked to enter the user and password
after sending the request or you have to store the user name and password as an attribute in the request
header. For more information, see the documentation for the REST service client that you are using.
3. As a starting point for testing the services, use the sample code provided in the service documentation, and
then adapt the service calls using the optional parameters as required.

Example
The following video shows how to test the translation service, starting with the enabling of SAP Translation Hub
through entering the required service details in a REST service client: https://www.youtube.com/embed/
WL3y-ozcXV8 .

918

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.10.4.8 Integration of SAP Translation Hub with SAP Cloud


for Customer
The integration of SAP Translation Hub in SAP Cloud for Customer for translating short texts is a sample use case
for the integration with other products.
You can use the Language Adaptation work center in SAP Cloud for Customer to translate work center texts that
are proposed by SAP Translation Hub.

Example
Assume that you use SAP Cloud for Customer and want to expand your operations to a country whose
language is currently not supported by SAP Cloud for Customer. In this scenario, you can translate work center
texts into one of the languages that SAP Translation Hub supports, but that SAP Cloud for Customer does not
support as standard.

Related Information
Supported Languages [page 896]
SAP Cloud for Customer Solution Help

Administrator Guide

Translating and Adapting UI Texts

1.4.10.5 Translation Workflow with SAP Translation Hub


The integration of SAP Translation Hub with Git projects enables you to translate texts in source properties files
for HTML5 applications.
If you want an initial translation of the texts in HTML5 applications that are stored in the Git repository of SAP
HANA Cloud Platform, you can use the translation workflow of SAP Translation Hub.
Each HTML5 application comprises at least one properties file that contains texts relevant for translation. The
translation workflow reads the texts in a source properties file from the Git repository, gets translations uisng one
of SAP Translation Hub's translation providers, and stores the translations in language-specific properties files in
the Git repository.

Prerequisites
The source language of the properties files must be English and the encoding of the properties file must be
ISO 8859-1, which is also known as Latin-1.
If you use the suggestion service to propose texts in the code editor of SAP Web IDE, use one of the browsers
listed in Opening SAP Web IDE.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

919

Translation Projects
To manage the translation workflow, SAP Translation Hub requires metadata about the HTML5 application, such
as the location of the source properties file in the Git repository and the required target languages. You record this
information for each source properties file of the HTML5 applications that you want to translate in a separate
translation project. For information about how to create a translation project, see the Related Information section.

Main Steps of Translation Workflow


When you start the translation workflow, SAP Translation Hub does the following:
1. Reads the translation project for the source properties file of the HTML5 application to be translated.
2. Gets translations from the multilingual text repository.
3. Creates a properties file for each of the target languages specified in the translation project, and places the
translations in the corresponding language-specific properties files.

Note
The language-specific properties files are stored in the HTML5 application's project in the Git repository.
The following figure shows the main parts of the translation workflow:

920

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Creating Translation Projects for the Translation Workflow [page 922]
Translating Properties Files [page 924]
Updating Translations in Properties Files [page 925]
Sample Scenario for Translation Workflow [page 926]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

921

1.4.10.5.1 Creating Translation Projects for the Translation


Workflow
SAP Translation Hub uses translation projects to manage the translation workflow of properties files used in
HTML5 applications.

Context
To translate texts in the source properties files of HTML5 applications, SAP Translation Hub requires some details
about the HTML5 application, such as the location of the source properties file in the Git repository and the
required target languages.

Procedure
1. Create a translation project for each source properties file in an HTML5 application that you want to translate.
2. Enter the following data about the source properties file:
Field

Entry

Application Name

Enter the name of the HTML5 application that contains the source properties file that you want
to translate.

Branch

By default, the branch is master. If you're using a different branch in the Git repository, change
the entry as required.

Path to Properties File

Enter the path to - and the name of - the source properties file of your HTML5 application in SAP
Web IDE.

Note
Use the following notation, starting with the level below the name of your HTML5 application
in SAP Web IDE:

<first folder under HTML5 application>

additional folders>
For example,

i18n

/<name of properties file>

/i18n.properties

/<names of any

Target Languages

Choose the target languages into which you want to translate the texts in the properties file.

Domain

Select the translation domain that most closely matches the application area of the HTML5 appli
cation.

3. Save the translation project.

922

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
Your translation project contains the data required to translate the texts in a properties file. You can use the
translation workflow to get an initial translation of the texts in the properties file, as well as to update translations
whenever changes are made to the texts in the source properties file.

Related Information
Accessing SAP Translation Hub User Interface [page 923]
Building Base URL of SAP Translation Hub [page 897]
Creating Translation Projects for the Translation Workflow [page 922]
Translating Properties Files [page 924]
Updating Translations in Properties Files [page 925]

1.4.10.5.1.1 Accessing SAP Translation Hub User Interface


You create translation projects for SAP Translation Hub on a special user interface (UI).
You access the UI by choosing Go to Service in the service description, which you access by choosing the SAP
Translation Hub tile in the Services area of the SAP HANA Cloud Platform cockpit.
Alternatively, you can access the UI by calling the following URL: <base URL of SAP Translation Hub>/ui.

Note
For information about the base URL, see Building Base URL of SAP Translation Hub in the Related Information
section.

Related Information
Building Base URL of SAP Translation Hub [page 897]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

923

1.4.10.5.2 Translating Properties Files


You use translation projects to translate properties files, which are stored in a Git repository, as part of the
translation workflow of SAP Translation Hub.

Prerequisites
The source language of the properties files is English.
The encoding of the properties file must be ISO 8859-1, which is also known as Latin-1.
There is a translation project for the HTML5 application that contains the properties file to be translated.

Context
On the SAP Translation Hub UI (<base URL of SAP Translation Hub>/ui), choose the translation project
that refers to the properties file to be translated, and choose Get Translations.

Results
The properties file is translated into the target languages specified in the translation project, and a properties file
for each target language is stored in the Git repository. To check the translations in the translation project, a list of
all translations and the translation provider that SAP Translation Hub uses for each text appears on the Edit
Translations tab.

Note
To view the properties files in your development environment, for example, in SAP Web IDE, you pull the latest
changes from the Git repository.

Related Information
Building Base URL of SAP Translation Hub [page 897]
Creating Translation Projects for the Translation Workflow [page 922]
Updating Translations in Properties Files [page 925]

924

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.10.5.3 Updating Translations in Properties Files


You can use the SAP Translation Hub UI to add or change translations created by SAP Translation Hub during the
translation workflow.

Prerequisites
You have used the translation workflow of SAP Translation Hub to translate the texts in the properties file of an
HTML5 application.

Context
When you use the translation workflow of SAP Translation Hub, SAP Translation Hub enters translations in
properties files for each target language. If required, you can create or update the texts in the properties files for
each target language.

Procedure
1. On the SAP Translation Hub UI (<base URL of SAP Translation Hub>/ui), choose the translation
project that refers to the properties files whose translations you want to update.
2. Choose the Edit Translations tab.
SAP Translation Hub shows the languages defined in the translation project along with the source texts from
the properties file and the translations.
3. Choose the target language in which you would like to check or update translations.
4. In the Translated Text column, update translations as required. If SAP Translation Hub didn't find a translation
for some texts, enter your own translation.
The translation provider is updated to show that you changed the text that SAP Translation Hub entered.
5. Save your changes.
If you need to change the translations in other target languages, repeat the previous steps for each target
language.
6. To add any translation changes to the properties files in the Git repository, choose Push to Git.

Related Information
Building Base URL of SAP Translation Hub [page 897]
Creating Translation Projects for the Translation Workflow [page 922]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

925

1.4.10.5.4 Sample Scenario for Translation Workflow


A sample use case for the translation workflow of SAP Translation Hub is the translation of an HTML5 application
that you create in SAP Web IDE.

Prerequisites
You have a developer account on SAP HANA Cloud Platform.
You have enabled SAP Translation Hub in the service catalog on SAP HANA Cloud Platform.
You are using one of the browsers listed in Opening SAP Web IDE.
For more information, see Consuming the SAP Translation Hub Services in the Related Information section.

Context
This section describes how to get an initial translation of the texts that you create for an HTML5 application in SAP
Web IDE on SAP HANA Cloud Platform.

Note
The following video shows the main steps in the sample scenario: https://youtu.be/nQt5euCU288

Procedure
1. On SAP HANA Cloud Platform, create an HTML5 application using SAP Web IDE.
During the development process, you can use SAP Translation Hub in the SAP Web IDE code editor to
propose texts in English. Note
2. Save your HTML5 project, and commit and push your changes to the Git repository.
If you use the SAP HANA Cloud Platform Git repository, note the steps required to deploy your application to
SAP HANA Cloud Platform and to connect your project to the SAP HANA Cloud Platform Git repository.
3. Call the SAP Translation Hub UI, and create a translation project for the required source properties file in your
HTML5 application.
4. Choose the translation project for the required source properties file in your HTML5 application, and choose
Get Translations.
5. To see the translated properties files in SAP Web IDE, pull the changes from your Git repository.

926

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Results
There is a properties file for each of the target languages that you entered in the translation project for your
HTML5 application. The properties files are stored in the same project in the Git repository as the rest of the
project files.

Related Information
Consuming the SAP Translation Hub Services [page 899]
Translation Workflow with SAP Translation Hub [page 919]
Creating Translation Projects for the Translation Workflow [page 922]
Translating Properties Files [page 924]
Updating Translations in Properties Files [page 925]
SAP Web IDE
Deploying Applications to SAP HANA Cloud Platform

1.4.10.6 Troubleshooting
While working with SAP Translation Hub, you might encounter some issues that others have already solved. To
get to the bottom of your particular issue, check out the different options in the following sections.

Use the Community


Check out our blogs and documents on SAP Community Network (SCN)

or browse our FAQ

Create a Customer Incident


To track and manage issues following the standard SAP approach, please create a customer incident in the SAP
ONE Support Launchpad . The component to use is SAP Translation Hub (LOD-TH).

Mail Us
If you prefer more direct communication, drop us a line at mailto:translationhub@sap.com.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

927

1.4.11 Git Service


The SAP HANA Cloud Platform, Git service can be used to store and version source code of applications, for
example HTML5 and Java applications, in Git repositories.
Git is a widely used open source system for revision management of source code that facilitates distributed and
concurrent large-scale development workflows.
You can use any standard compliant Git client to connect to the Git service. Many modern integrated development
environments, including but not limited to Eclipse and the SAP Web IDE, provide tools for working with Git. There
are also native clients available for many operating systems and platforms.

Features
Highly distributed. Every clone of a repository contains the complete version history.
Cheap and simple creation and merging of branches supporting a multitude of development styles.
Almost all operations are performed on a local clone of a repository and therefore are very fast.
No need to be permanently online, only when synchronizing with the Git service.
Only differences between versions are recorded allowing for very compact storage and efficient transport.
Widely used and supported by many tools.

Restrictions
The Git service is a dedicated service for source code versioning.
While Git can manage and compare text files very efficiently, it was not designed for processing large files or files
with binary content, such as libraries, build artifacts, multimedia files (images or movies), or database backups.
Consider using the document service or some other suitable storage service for storing such content.
To ensure best possible performance and health of the service, the following restrictions apply:
The size of an individual file must not exceed 20 MB. Pushes of changes that contain a larger file will be
rejected.
The overall size of the bare repository stored in the Git service must not exceed 500 MB.
The number of repositories per account is not currently limited. Note, however, that SAP may take measures
to protect the Git service against misuse.

Third Party Notice


This product makes use of the Git-Icon-1788C image made available by Git (https://git-scm.com/downloads/
logos ) under the Creative Commons Attribution 3.0 Unported License (CC BY 3.0) http://
creativecommons.org/licenses/by/3.0 .

928

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Managing Repositories [page 929]
Working with Repositories [page 934]
Security [page 938]
Best Practices [page 939]
Troubleshooting [page 940]
Git
Eclipse
SAP Web IDE
Document Service [page 545]

1.4.11.1 Managing Repositories


In the cockpit, you can create and delete Git repositories, as well as lock and unlock repositories for write
operations. In addition, you can monitor the current disk consumption of your repositories and perform garbage
collections to clean up and compact repository content.

Related Information
Creating a Repository [page 929]
Changing the State of a Repository [page 931]
Deleting a Repository [page 932]
Cleaning a Repository [page 933]

1.4.11.1.1 Creating a Repository


In the SAP HANA Cloud Platform cockpit, you can create Git repositories for your accounts.

Prerequisites
You are an administrator of the account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

929

Context
Note
To create a repository for the static content of an HTML5 application, see Creating an HTML5 Application [page
71].

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the required account.
2. Choose the

Repositories

Git Repositories

in the navigation area.

3. To create a new repository, choose New Repository and enter the following data.
Table 299:
Field

Entry

Name

Mandatory. Enter a unique name starting with a lowercase letter, followed by digits and lower
case letters. The name is restricted to 30 characters.

Description

Optional. Enter a descriptive text for the repository. You can change this description later on.

Create empty commit

Select this checkbox if you want to have an initial empty commit in the history of the repository.
This might be useful if you want to import the content of another repository.

4. Choose OK.
A new entry appears in the list of Git repositories.
5. To navigate to the details page of the repository, follow the link on its name.
6. Assign developers to the new repository.

Results
The URL of the Git repository is displayed under Source Location on the detail page of the repository. You can use
this URL to access the repository with a standard-compliant Git client. Note that you cannot use this URL in a
browser to access the Git repository.

Related Information
Creating an HTML5 Application [page 71]
Assigning Developers to a Repository [page 931]

930

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.11.1.1.1 Assigning Developers to a Repository


Permissions for Git repositories are granted based on the account member roles of users. To grant an account
member access to a Git repository, assign one of these roles: Administrator, Developer, or Support User.

Prerequisites
You are an administrator of the account.
New members to be added already have SAP user IDs.

Context
For details about the permissions associated with the individual roles, see Security [page 938].

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit.
2. Assign members to accounts and define their roles (see Related Information).
Make sure that you assign at least one of these roles: Administrator, Developer, or Support User.

Related Information
Managing Members [page 23]
Account Member Roles [page 27]

1.4.11.1.2 Changing the State of a Repository


In the SAP HANA Cloud Platform cockpit, you can change the state of a Git repository temporarily to READ ONLY
to block all write operations. Read access will still be possible.

Prerequisites
You are an administrator of the account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

931

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the required account.
2. In the list of Git repositories, locate the repository you want to work with and follow the link on the repository's
name.
3. On the details page of the repository, choose Set Read Only.

Results
The state flag of the repository changes from ACTIVE to READ ONLY and all further write operations on this
repository are prohibited.

Note
To unlock the repository again and allow write access, choose Set Active on the details page of the repository.

1.4.11.1.3 Deleting a Repository


In the SAP HANA Cloud Platform cockpit, you can delete a Git repository unless it is associated with an HTML5
application. In this case, delete the HTML5 application.

Prerequisites
You are an administrator of the account.

Context

Caution
Be very careful when using this command. Deleting a Git repository also permanently deletes all data and the
complete history. Clone the repository to some other storage before deleting it from the Git service in case you
need to restore its content later on.

932

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the appropriate account.
2. Choose the

Repositories

Git Repositories

in the navigation area.

3. In the list of Git repositories, locate the repository you want to delete.
4. Choose the delete icon (

) in the Actions column.

5. Confirm that you want to delete the repository.

1.4.11.1.4 Cleaning a Repository


In the SAP HANA Cloud Platform cockpit, you can trigger a garbage collection for a repository to clean up
unnecessary objects and compact the repository content aggressively.

Prerequisites
You are an administrator of the account.

Context
Perform this operation from time to time to ensure the best possible performance for all Git operations. In
addition, the Git service runs normal garbage collections periodically.

Note
This operation might take a considerable amount of time and might impact the performance of some Git
operations while it is running.

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the required account.
2. Choose the

Repositories

Git Repositories

in the navigation area.

3. In the list of Git repositories, locate the repository you want to work with and follow the link on the repository's
name.
4. On the details page of the repository, choose Garbage Collection.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

933

Results
The garbage collection runs in the background. You can use the Git repository without restrictions while the
process is running.

1.4.11.2 Working with Repositories


Git supports a large variety of commands for working with repositories.
The following assumes that you are familiar with the concepts of Git and that you have access to a suitable Git
client, for example SAP Web IDE, to perform Git operations.
If you are new to Git, we strongly recommend that you read a text book about Git and consult the Best Practices
guide before using the Git service. The Troubleshooting Guide helps solve some common issues you may
encounter when working with the Git service.

Related Information
Using Source Control (Git) in SAP Web IDE
Best Practices [page 939]
Troubleshooting [page 940]

1.4.11.2.1 Determining the Repository URL


The URL of the Git repository is displayed under Source Location on the details page of the repository. You can
use this URL to access the repository using a Git client.

Prerequisites
In the account where the repository resides, you are an account member with the role Administrator, Developer,
or Support User.

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the required account.
2. Choose the

934

Repositories

Git Repositories

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

in the navigation area.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. In the list of Git repositories, locate the repository you want to work with and follow the link on the repository's
name.
4. In the Source Location panel, copy the link labeled Git Repository URL.

1.4.11.2.2 Cloning a Repository


Before you can start developing, you must clone the repository you want to work with to your workplace.

Prerequisites
You are an account member with the role Administrator, Developer, or Support User.
You have determined the URL of the repository you want to clone (see Determining the Repository URL [page
934]).

Context
Refer to the SAP Web IDE documentation if you want to clone the repository to SAP Web IDE. Otherwise, see the
documentation of your Git client to learn how to clone a remote Git repository.

Procedure
1. Execute the clone command with your Git client.
2. Authenticate yourself with your SAP ID credentials.

Related Information
SAP Web IDE

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

935

1.4.11.2.3 Fetching Changes from a Repository


The Git fetch operation transfers changes from the remote repository to your local repository.

Prerequisites
You are an account member with the role Administrator, Developer, or Support User.
You have cloned the repository to your workspace, see Cloning a Repository [page 935].

Context
Refer to the SAP Web IDE documentation if you want to fetch changes to SAP Web IDE. Otherwise, see the
documentation of your Git client to learn how to fetch changes from a remote Git repository.

Procedure
1. Execute a fetch or a pull command with your Git client.
2. Authenticate yourself with your SAP ID credentials.

Related Information
SAP Web IDE

1.4.11.2.4 Pushing Changes to a Repository


The Git push operation transfers changes from your local repository to a remote repository.

Prerequisites
You are an account member with the role Administrator or Developer.
You have already committed the changes you want to push in your local repository.
You have ensured that the e-mail address in the push commit matches the e-mail address you registered with
the SAP ID service.

936

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Refer to the SAP Web IDE documentation if you want to push changes from SAP Web IDE. Otherwise, see the
documentation of your Git client to learn how to push changes to a remote Git repository.

Procedure
1. Execute a push command with your Git client.
2. Authenticate yourself with your SAP ID credentials.

Related Information
SAP Web IDE

1.4.11.2.5 Browsing the Content of a Repository


The Git service offers a web-based repository browser that allows you to inspect the content of a repository.

Prerequisites
In the account where the repository resides, you are an account member with the role Administrator, Developer,
or Support User.

Context
The repository browser gives read-only access to the full history of a Git repository. This includes its branches and
tags as well as the content of the files. Moreover, it allows you to download specific versions as ZIP files.
The repository browser automatically renders *.md Markdown files into HTML to make it easier to create
documentation.

Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the required account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

937

2. Choose the

Repositories

Git Repositories

in the navigation area.

3. In the list of Git repositories, locate the repository you want to work with and follow the link on the repository's
name.
4. In the Source Location panel, click the Repository Browser link.

1.4.11.3 Security
Access to the Git service is protected by SAP HANA Cloud Platform roles and granted only to members of an
account.

Restrictions
The Git service cannot be used to host public repositories or repositories with anonymous access.

Authentication
Access to a Git repository is only granted to users authenticated by the SAP ID service. When sending requests,
users must authenticate with SAP ID service credentials.

Permissions
The permitted operations depend on the account member role of the user.
Read access is granted to all users with the Administrator, Developer, or Support User role. They have permission
to:
Clone a repository.
Fetch commits and tags.
Write access is granted to all users with the Administrator or Developer role. They have permission to:
Push commits.
Push tags.

Note
If the repository is associated with an HTML5 application, pushing a tag defines a new version for the
HTML5 application. The version name will be the same as the tag name.
Create new remote branches.
Push commits authored by other users (forge author identity).

938

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Only users with the Administrator role have permission to:


Create and delete repositories.
Run garbage collection on repositories.
Lock and unlock repositories.
Delete remote branches.
Delete tags.
Push commits committed by other users (forge committer identity).
Forcefully push commits, for example to rewrite the history of a Git repository.
Forcefully push tags, for example to move the version of an HTML5 application to a different commit.

Related Information
Account Member Roles [page 27]
Creating a Version [page 74]

1.4.11.4 Best Practices


Use these best practices to get started with Git and to avoid common pitfalls.
If you are new to Git, we strongly recommend reading a text book about Git, search the Internet for
documentation and guides available online, or get in touch with the large worldwide community of developers
working with Git.
Perform a fetch or pull command before creating a new branch.
In general, base your work on the most recent changes of your co-workers. Otherwise, you might have to
resolve conflicts before the changes can be pushed.
Create a new local branch for every new feature or bug-fix you want to start.
Derive new local branches from origin/master
Write meaningful commit messages.
A commit message should describe why, unless you want to provide, for example, you are doing a particular
change rather than describing what you did. The why, unless you want to provide, for example, helps your coworkers to understand the intention and consequences of your change. The what on the other side can easily
be deduced from the source code, that is, from the difference between the old and new version.
Commit early and often.
While developing larger features, create periodic checkpoints in form of commits, for example when you are
experimenting with different possible solutions. If you did something wrong, you can easily go back to the last
known good commit and start over. Before pushing the feature, squeeze the checkpoints into one final
commit.
Create small, easy to digest commits.
A commit that touches thousands of lines of code is likely to be much more difficult to understand and
integrate than a commit that changes only a tiny piece of code. For example, it is usually considered bad
practice to refactor your code and implement a new feature in one and the same commit.
Avoid pushing patches that break your code.
Git supports amendments to commits that have not yet been pushed to the Git service. This means you can
correct and improve your changes incrementally before pushing them.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

939

Never rewrite a commit that has already been pushed to the Git service.
Your co-workers might already have fetched that commit to their local repositories and based their work on it.
Instead push a new commit.

Note
The only valid exception to this rule is if you accidentally pushed a secret, for example a password, to the
Git service.
Avoid dependencies on changes that have not been pushed yet.
While Git provides some powerful mechanisms for handling chains of commits, for example interactive
rebasing, these are usually considered to be for experienced users only.
Do not push binary files.
Git is very efficient in calculating differences in text files, but not in binary files. Pushing binary files bloats your
repository size and affects performance, for example in clone operations.
Store source code, not generated files and build artifacts.
Keep build artifacts in a separate artifact repository because they tend to change frequently and bloat your
commit history. Furthermore, build artifacts are usually stored in some sort of binary or archive format that
Git cannot handle efficiently.
Run garbage collection periodically.
Trigger a garbage collection in the SAP HANA Cloud Platform cockpit from time to time to compact and clean
up your repository. Also run garbage collection regularly for repositories cloned to your workplace. This will
minimize the disk usage and improve the performance of common Git commands.

1.4.11.5 Troubleshooting
While working with the Git service, you might encounter these common problems and error messages. Note that
the actual error messages and their presentation depend on the Git client you are using for communication with
the Git service.

General Issues
Cloning a repository fails with Git repository not found.
Ensure that you have the correct URL of the repository. Copy the URL from the Source Location error
messages and their presentation depend on the Git client you are using for section of the repository's details
page in the SAP HANA Cloud Platform cockpit.
Pushes of changes to a remote branch are rejected with a message similar to this one: HEAD -> master
(non-fast-forward).
The update failed because the commit you tried to push is not a successor of the tip of the remote branch.
Fetch the latest changes from the remote branch and either rebase your local changes to the tip of the remote
branch or merge the two branches. Then push again.
Remote operation fails with cannot open git-receive-pack or cannot open git-upload-pack.
These error messages usually indicate a communication issue with the Git service, for example due to
downtime or an issue with your network connection to the Git service. If you are behind a proxy, configure
your Git client appropriately. If the problem persists, contact SAP Support for help.

940

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Issues Related to Access and Permissions


All remote operations on a repository fail with Authentication failed for ....
Make sure that you enter your correct SAP ID credentials. Check that you can log on to the SAP HANA Cloud
Platform, for example to the cockpit. If that fails as well, your account may have been locked temporarily due
to too many failed logon attempts. If the problem persists, contact SAP Support for help.
A remote operation on a repository fails with Git access forbidden.
You don't have permission to access the repository at all or to perform the requested Git operation. Ensure
that you are member of the account that owns the repository. For read access (clone, fetch, pull), you
must have the role Administrator, Developer, or Support User. For write access (push, push tags), you must
have the Administrator or Developer role. For more information about required roles for certain Git
operations, see Security [page 938].
Pushes of changes fail with a message similar to this one: You are not allowed to perform this
operation. To push into this reference you need 'Push' rights. ... HEAD -> master
(prohibited by Gerrit).
You don't have the account member role Developer or Administrator or the repository is currently locked for
write operations. Check your roles in the SAP HANA Cloud Platform cockpit or ask an account administrator
to assign the necessary roles. Check the state of the repository in the cockpit and unlock it to enable write
operations.
Pushes of changes fail with You are not committer ....
The Git service verifies that the e-mail address of the committer associated with a commit matches the e-mail
address you registered with the SAP ID service.
Users with the account member role Developer are not allowed to submit changes in the name of other users
(forge committer identity). This error might indicate that your Git client is not properly configured to use the
e-mail address registered with the SAP ID service. To check your client configuration, use the git config
command:
$ git config -l ... user.name=John Doe user.email=john.doe@example.com ...
To submit changes in the name of another user, for example when transferring changes between different
repositories, you must have the account member role Administrator.
Deleting a tag or remote branch fails.
Users with the account member role Developer are not allowed to delete or move tags or to delete remote
branches. You must have the account member role Administrator to do this.

Issues Related to Violation of Restrictions


Pushes of changes fail with Pack exceeds the limit of ..., rejecting the pack.
This error message indicates that the maximum size of your Git repository would be exceeded by accepting
this change. The Git service imposes a hard limit of 500 MB as the maximum size of repositories to ensure the
best possible performance and health of the service. You can see this limit in the SAP HANA Cloud Platform
cockpit as well as your current repository size.
Run a garbage collection in the SAP HANA Cloud Platform cockpit to clean up unnecessary objects and
compact the repository content. If this does not significantly reduce the size of the repository, this usually
indicates that the repository contains build artifacts or some other binary data that cannot be compressed
efficiently and not just source code. Remove such files from the history of the repository and consider storing
them outside the Git service.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

941

Pushes of changes fail with Object too large (... bytes), rejecting the pack. Max object
size limit is ... bytes.
This error message indicates that the commit you are trying to push contains files that are too large to be
stored by the Git service. The Git service imposes a hard limit of 20 MB as the maximum size of individual files
in a repository to ensure the best possible performance and health of the service. Remove the file or files that
are too big from the commit and push again.

Related Information
Security [page 938]
Cleaning a Repository [page 933]

1.4.12 Business Services with YaaS


Using Hybris-as-a-Service at SAP HANA Cloud Platform (YaaS) you develop business services that are consumed
in your cloud applications.

Overview
With Hybris-as-a-Service at SAP HANA Cloud Platform (YaaS), you can develop business services, publish and
sell them through the YaaS Market, and consume them in your cloud applications. The core design principle
behind YaaS is a microservice architecture, which enables you to build a flexible and scalable platform. A
microservice architecture is another method of bundling components into services. The approach is to develop a
single application as a suite of small services, each running in its own process and communicating with lightweight
mechanisms, often an HTTP resource API. These services are built around business capabilities and are
independently deployable by fully automated deployment machinery.

Business Services and Builder Modules


In YaaS, you develop the following component types when providing new services or consume existing ones:
Business services
A business service is simply a microservice that provides a specific business functionality, such as products,
loyalty, or orders. A set of business services is grouped into a package, which is in turn the entity that gets
published on the YaaS Market.
A business service is a Web application with a RESTful API that exposes the resources and functions of the
service. The service implementation should follow the guidelines for microservices, so that the service has a
clearly defined scope, is highly scalable, resilient against failures, and self-contained. YaaS recommends to
to create new business services, as it provides a lightweight framework that
use the YaaS Service SDK
helps with the API definition and implementation of the service. The SDK uses RAML (RESTful API Modeling
Language) as an API modeling language, and provides code generators to create the JAX-RS compliant Java

942

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

API classes and Java implementation stubs. It further provides helper classes to get, for example, the YaaS
tenant and other YaaS relevant information that is propagated from YaaS to the business service.
Builder modules
A builder module is a user interface in the YaaS Builder application, in which the backoffice functionality of a
business service is managed; for example, an administration UI for a service published in YaaS.
Builder modules are the backoffice clients of YaaS. They allow users to manage the service data from the user
interface. Typically, a builder module is an HTML5 application calling the service APIs. As such, it is very easy
to deploy it as a Java Web Tomcat 7 application on SAP HANA Cloud Platform: create a builder module
according to the tutorial on YaaS Dev Portal , add Cross-origin resource sharing (CORS) configuration to
the web.xml and build a WAR file.
Applications
An application is able to consume the business services to which it is subscribed. Subscribing to existing
packages is possible via the YaaS Market.

Caution
YaaS Dev Portal does not support Microsoft Internet Explorer.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

943

YaaS and SAP HANA Cloud Platform


Table 300:
This is where Yaas and SAP HANA Cloud Platform stand in the
whole picture.
As a User, you need an account and have to be part of an Or
ganization. Within the Organization, there are Dev Teams and
Projects. In the Dev Teams you develop services and builder
modules. In the Projects, you consume these services.
When you are member of a Project, you can manage projects
and subscribe to packages.
The Package stands in the middle of the whole picture. It con
nects the YaaS components, the Yaas Market and the SAP
HANA Cloud Platform components. All available published
packages are listed in the YaaS Market

The Services are the building blocks of YaaS. They are small,
isolated applications that are responsible for one single piece
of functionality.
The Service SDK is a tool that facilitates the development of
the business services. It also provides some YaaS-specific
utilities, for example, retrieving the tenant ID propagated by
an application to the used business services.
After creating a service, you create a Builder Module for that
service. This enables you to have a user interface (UI) to man
age your service from a business perspective.
The Builder SDK helps you create this UI. This is a commandline interface that runs the Builder in developer mode. This
mode implements a builder module faster and more effi
ciently.

Example Business Service: Wishlist Service


To try out an example busness service, follow the steps in the Tutorial: Creating a Wishlist Service [page 945].
For example, once subscribed to the Wishlist package, you can use the wishlist service API to create and manage
wishlists. As a Dev Team member, you can develop and register the Wishlist package.
The Wishlist package contains the services and the builder modules and can make them available in the YaaS
Market. Other users can subscribe to this package and use these services and builder modules.

944

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.4.12.1 Tutorial: Creating a Wishlist Service


This tutorial shows you how to create a Wishlist busness service.

Context
Using YaaS you can build business services and builder modules that run on SAP HANA Cloud Platform, and then
use those services in cloud applications which again can run on SAP HANA Cloud Platform. The example used
here refers to the Wishlist service example
described in the YaaS Dev Portal .

Procedure
1. Building the Wishlist Business Service [page 945].
2. Building a Builder Module for the Wishlist Service [page 948].
3. Using the YaaS Storefront Application Template [page 950].

1.4.12.1.1 Building the Wishlist Business Service


In the first step of this tutorial, you will learn how to create and start a business service, and then register it in the
YaaS Builder.

Prerequisites
You have set up Maven so that you set up the environment to use the YaaS Service SDK.
The YaaS Service SDK uses Maven to resolve all additional software dependencies that are necessary to
create, build, test, run, and debug your new service. See Set up Maven .

Note
If you work in a proxy environment, be sure you set the proxy host and port correctly using the following
command:
SET MAVEN_OPTS=-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080 Dhttps.proxyHost=proxy -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts=nexus
You need Java 8 to create the Wishlist service.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

945

Context

Procedure
1. Create the Wishlist service.
Create the Wishlist service as an example service and test it locally using, for example, Jetty Web server. See
Create a Whishlist Service .
2. (Optional) Import an existing Wishlist service.
If you want to use existing services of SAP HANA Cloud Platform, for example, you can import the Wishlist
service you have already created in Eclipse.
a. Run the mvn eclipse:m2eclipse command. Before importing the project, you can run the mvn
eclipse:m2eclipse command.
b. Import the project in Eclipse. To do that, you choose File Import Existing Maven Projects . In the
Root Directory field you browse to your project and choose OK. Then you choose Finish.
3. Use a HANA database on SAP HANA Cloud Platform to persist the Wishlists service.
You can use the persistence service to store data in the HANA database on SAP HANA Cloud Platform, the
document service to store and retrieve BLOBs, or you can use the connectivity service to fetch or push data
to an on-premise system. You can find an implementation of the Wishlist service that uses a HANA database
on SAP HANA Cloud Platform to persist the Wishlists service at GitHub . The most important parts of the
implementation are the following:
a. Add dependencies to Eclipse Link and JPA persistence.
Open the pom.xml

file, select all the code in the <dependencies> tags and replace this code in the

pom.xml file in your project in Eclipse. The logging libraries are provided by default in the SAP HANA
Cloud Platform runtime environments, you have to add the following code in the pom.xml file as well:
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<packagingExcludes>
WEB-INF/lib/logback-classic-.jar,
WEB-INF/lib/logback-core-.jar,
WEB-INF/lib/slf4j-api-*.jar
</packagingExcludes>
</configuration>
</plugin>
b. Configure the persistence using JPA,specifiy the database connection and the Wishlist and Wishlist item
entity classes.
First you need to create a persistence.xml file in your project. You can automatically do that by adding
the JPA 2.0 facet in the project from Properties Project Facets . Then open the META-INF/
in GitHub and copy and paste the code in your persistence.xml file in Eclipse.
persistence.xml
c. Configure the Spring framework that is used in the Wishlist service implementation.
Open theMETA-INF/applicationContext.xml
the code into the respective XML files.

946

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

and META-INF/wishlist-spring.xml

and copy and paste

SAP HANA Cloud Platform


SAP HANA Cloud Platform

d. Prepare the JPA entity classes WishlistEntity and WishlistItemEntity, and their related DAO
objects.
Create manually the com.sample.wishlist.model package. Then open thecom.sample.wishlist.model
package
and copy and paste the code from each of the Java classes into that package. This will
automatically create these classes in the package in Eclipse.
e. Add the API implementation class that was generated by the YaaS Service SDK.
For each of the RESTful resources, which have been defined in the RAML definition of the service, a
separate method has been generated into this class. The implementation of the service, that is the wiring
with the persistence service in this example, goes in here. Please note that the generated methods get a
parameter of type YaasAwareParameters as an input. This class provides methods to retrieve
information propagated from YaaS to the service, such as getHybrisTenant(), which is used to provide
a multitenant enabled service implementation. Open the com.sample.wishlist.api.generated package
and copy and paste the code into the respective files.
4. Build the project.
Build the project using the mvn clean install command in the console client. This creates a WAR file in
the target directory of the project.
5. Deploy the WAR file created in step 4.
Deploy the WAR file into your SAP HANA Cloud Platform account using the deploy UI of the SAP HANA Cloud
Platform cockpit or the neo command in the console client. Choose Java Web Tomcat 7 as Java runtime for
the service.
6. Start the Wishlist service.
Start the service in a Web browser via the application URL shown in the SAP HANA Cloud Platform cockpit.
This brings up the built-in RAML API Console in a browser which shows the REST API documentation, and
provides a console which allows you to interact with your API from within that documentation.
7. Register the Wishlist service.
Once the implementation is finished, register the service in the YaaS Builder. See Register a Service in the
Builder .

Next Steps
Building a Builder Module for the Wishlist Service [page 948]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

947

1.4.12.1.2 Building a Builder Module for the Wishlist Service


In the second step of this tutorial, you will learn how to create a Builder module.

Context
To create a builder module for the Wishlist service, follow these steps. You can find a simple builder module for
the Wishlist service at GitHub .

Procedure
1. Create a builder module.
Following the Create a Builder Module
tutorial you create a module with default content using the Builder
SDK: builder createModule wishlistModule.
2. Enable CORS requests.
To enable CORS, a simple option is to enable the built-in CORS servlet filter that comes with Java Web
Tomcat 7. To enable a static content as well, be sure you configure the Default servlet as well, because servlet
filters are only applied to servlets configured in the web.xml. A typical wishlistModule/WEB-INF/
web.xml looks like this:
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE web-app
PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
<filter>
<filter-name>CorsFilter</filter-name>
<filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
<init-param>
<param-name>cors.allowed.origins</param-name>
<param-value>*</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.methods</param-name>
<param-value>GET,POST,OPTIONS</param-value>
</init-param>
<init-param>
<param-name>cors.allowed.headers</param-name>
<param-value>DNT,X-CustomHeader,Keep-Alive,User-Agent,X-Requested-With,IfModified-Since,Cache-Control,Content-Type</param-value>
</init-param>
<init-param>
<param-name>cors.exposed.headers</param-name>
<param-value>Access-Control-Allow-Origin,Access-Control-Allow-Credentials</
param-value>
</init-param>
<init-param>
<param-name>cors.support.credentials</param-name>
<param-value>true</param-value>
</init-param>
<init-param>

948

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

<param-name>cors.preflight.maxage</param-name>
<param-value>10</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CorsFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
<servlet>
<servlet-name>default</servlet-name>
<servlet-class>org.apache.catalina.servlets.DefaultServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>default</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>
</web-app>
3. Build a WAR file.
This example uses Maven and adapts the location of the WAR source directory to the directory generated in
the previous step.
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/
2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://
maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example.projects</groupId>
<artifactId>documentedproject</artifactId>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>
<name>Wishlist Builder Module</name>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-war-plugin</artifactId>
<version>2.6</version>
<configuration>
<warSourceDirectory>wishlistModule</warSourceDirectory>
</configuration>
</plugin>
</plugins>
</build>
</project>

Next Steps
Using the YaaS Storefront Application Template [page 950]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

949

1.4.12.1.3 Using the YaaS Storefront Application Template


In the third step of this tutorial, you will learn how to build and deploy an application using the YaaS Storefront
template.

Context
The YaaS Storefront is a ready-to-use template that is integrated with the Commerce service package and other
third-party services such as search, payment, and tax. The Storefront application template is a pure HTML5
application. The easiest way to deploy and run this application on SAP HANA Cloud Platform, is to create a WAR
file. See Set Up a Storefront Application .

Procedure
1. Build the application.
You can build the application as described in the YaaS documentation:
edit the gruntfile.js to include your project and client ID
run grunt build:prod to generate the dist folder
2. Prepare a ROOT.WAR file.
Add the content of the dist/public to a zip file and name the archive ROOT.WAR. By naming it ROOT.WAR, the
application will be deployed to the root context. That is necessary, because otherwise the application
interprets the first path segments as a tenant.
3. Deploy the application.
You can deploy the application to SAP HANA Cloud Platform using one of the following options:
Deploying on the Cloud with the Cockpit [page 985]
Deploying on the Cloud with the Console Client [page 983]
Deploying on the Cloud from Eclipse IDE [page 977]

1.5

Develop Applications

Table 301:
To learn about

See

How to develop, deploy and manage Java applications in a


cloud environment

Java: Development [page 951]

950

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To learn about

See

How to create comprehensive analytical models and build ap


plications with SAP HANA's programmatic interfaces and in
tegrated development environment

SAP HANA: Development [page 1008]

How to develop and run lightweight HTML5 applications in a


cloud environment

HTML5: Development [page 1040]

How to use the UI development toolkit for HTML5 (SAPUI5) to


build and adapt client applications based on SAP HANA Cloud

UI development toolkit for HTML5 (SAPUI5)

1.5.1 Consuming Platform Services


Note
For information about platform services, go to Services [page 264].
See also: Accessing Services [page 30]

1.5.2 Java: Development


SAP HANA Cloud Platform enables you to develop, deploy and use Java applications in a cloud environment.
Applications run on a runtime container where they can use the platform services APIs and Java EE APIs
according to standard patterns.
The SAP HANA Cloud Platform Runtime for Java enables the provisioning and running applications on the
platform. The runtime is represented by Java Virtual Machine, Application Runtime Container and Compute Units.
Cloud applications interact at runtime with the containers and services via the platform APIs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

951

The Java development process is enabled by the SAP HANA Cloud Platform Tools, which comprise the Eclipse IDE
and the SAP HANA Cloud Platform SDK.
During and after development, you can configure and operate an application using the cockpit and the console
client.
Benefits and advantages
Offers standardized environment
Supports a wide-spread Apache Tomcat Web container
Comes with Eclipse IDE and command line tools support
Supports the platform services APIs
Appropriate for
Developing and running Java Web applications based on standard JSR APIs
Executing Java Web applications which include third-party Java libraries and frameworks supporting standard
JSR APIs
Supporting Apache Tomcat Java Web applications.
Not appropriate for
Applications featuring modifications of JSR APIs and their implementations
Applications requiring modified or customized Java Apache Tomcat Web container

Related Information
Java: Getting Started [page 33]

952

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Runtime for Java [page 953]


Development Environment [page 960]
Developing Java Applications [page 964]
Supported Java APIs [page 961]

1.5.2.1

Runtime for Java

The SAP HANA Cloud Platform Runtime for Java comprises the components which create the environment for
provisioning and running applications on SAP HANA Cloud Platform. The runtime is represented by Java Virtual
Machine, Application Runtime Container and Compute Units. Cloud applications can interact at runtime with the
containers and services via the platform APIs.

Components
Java Virtual Machine
SAP HANA Cloud Platform infrastructure runs on SAP's own implementation of a Java Virtual Machine - SAP
Java Virtual Machine (JVM). SAP JVM is a fully certified Java Standard Edition Virtual Machine for Java 7. It is
derived from Oracles HotSpot VM and JDK implementation, but enhanced with several supportability
features.
Application Runtime Container
Applications developed on SAP HANA Cloud Platform run on a modular and lightweight runtime container
which allows them to consume standard Java EE APIs and platform services that are centrally provided and
shared across the platform. SAP HANA Cloud Platform leverages open source as a key element and Java EE 6
Web Profile as a default programming model.
Compute Units
A Compute Unit is a virtualized hardware on which a SAP HANA Cloud Platform application runs.

Related Information
Java Virtual Machine [page 953]
Application Runtime Container [page 955]
Compute Units [page 959]
Supported Java APIs [page 961]

1.5.2.1.1

Java Virtual Machine

SAP HANA Cloud infrastructure runs on SAP's own implementation of a Java Virtual Machine - SAP Java Virtual
Machine (JVM).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

953

SAP JVM is a fully certified Java Standard Edition Virtual Machine for Java 7. It is derived from Oracles HotSpot
VM and JDK implementation, but enhanced with several supportability features such as the SAP JVM Profiler for
better monitoring, and profiling applications running on the SAP HANA Cloud local runtime. Customer support is
provided directly by SAP for the full maintenance period of SAP applications that use the SAP JVM.

SAP JVM
The SAP JVM is a standard compliant certified JDK, supplemented by additional supportability and developer
features and extensive monitoring and tracing information. All these features are designed as interactive, ondemand facilities of the JVM with minimal performance impact. They can be switched on and off without having to
restart the JVM (or the application server that uses the JVM).

Supportability and Developer Features


Debugging on Demand
With SAP JVM debugging on demand, Java developers can activate and deactivate Java debugging directly
there is no need to start the SAP JVM (or the application server on top of it) in a special mode. Java debugging in
the SAP JVM can be activated and deactivated using the jvmmon tool, which is part of the SAP JVM delivery. This
feature does not lower performance if debugging is turned off. The SAP JVM JDK is delivered with full source code
providing debugging information, making Java debugging even more convenient.

Profiling
To address the root cause of all performance and memory problems, the SAP JVM comes with the SAP JVM
Profiler, a powerful tool that supports the developer in identifying runtime bottlenecks and reducing the memory
footprint. Profiling can be enabled on-demand without VM configuration changes and works reliably even for very
large Java applications.
The user interface the SAP JVM Profiler can be easily integrated into any Eclipse-based environment by using
the established plugin installation system of the Eclipse platform. It allows you to connect to a running SAP JVM
and analyze collected profiling data in a graphical manner. The profiler plug-in provides a new perspective similar
to the debug and Java perspective.
A number of profiling traces can be enabled or disabled at any point in time, resulting in snapshots of profiling
information for the exact points of interest. The SAP JVM Profiler helps with the analysis of this information and
provides views of the collected data with comprehensive filtering and navigation facilities.
The profiling traces provided address the following use cases:
Memory Allocation Analysis investigates the memory consumption of your Java application and finds
allocation hotspots
Performance Analysis investigates the runtime performance of your application and finds expensive Java
methods

954

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Network Trace - analyzes the network traffic


File I/O Trace - provides information about file operations
Synchronization Trace - detects sychronization issues within your application
Method Parameter Trace yields detailed information about individual method calls including parameter
values and invocation counts
Profiling Lifecycle Information a lightweight monitoring trace for memory consumption, CPU load, and GC
events.

Extensive Monitoring and Tracing Information


The SAP JVM provides comprehensive statistics about threads, memory consumption, garbage collection, and
I/O activities. For solving issues with SAP JVM, a number of traces may be enabled on demand. They provide
additional information and insight into integral VM parts such as the class loading system, the garbage collection
algorithms, and I/O. The traces in the SAP JVM can be switched on and off using the jvmmon tool, which is part of
the SAP JVM delivery.

Further Information
Critical Java exceptions (such as NullPointerException, ClassCastException, NoClassDefFoundError, or
OutOfMemoryError) provide additional information and further details to help identify the reason for an exception.
Thread dumps not only contain a Java execution stack trace, but also information about monitors or locks,
consumed CPU and memory resources, I/O activities, and a description of communication partners (in the case
of network communication).

Related Information
(Optional) Installing SAP JVM [page 35]
Setting Up SAP JVM in Eclipse IDE [page 41]
Updating SAP JVM [page 45]

1.5.2.1.2

Application Runtime Container

SAP HANA Cloud Platform applications run on a modular and lightweight application runtime container where
they can use the platform services APIs and Java EE APIs according to standard patterns.
Depending on the runtime type and corresponding SDK you are using, SAP HANA Cloud Platform provides the
following profiles of the application runtime container:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

955

Table 302:
Profile

Provides support for

Supported Java Use


versions

Java Web

Some of the standard Java EE 6

6 (default); 7

If you need a small standalone Java Web container.

7 (default); 8

If you need a simplified Java Web application runtime

APIs (Servlet, JSP, EL, Web


socket)

Java Web

Some of the standard Java EE 6

Tomcat 7

APIs (Servlet, JSP, EL, Web

container based on Apache Tomcat 7.

socket)

Java EE 6

Java EE 6 Web Profile APIs

7 (default); 6

If you need an application runtime container to


gether with all containers defined by the Java EE 6

Web Profile

Web Profile specification.

Java Web

Some of the standard Java EE 7

Tomcat 8

APIs (Servlet, JSP, EL, Web

8 (default); 7

If you need a simplified Java Web application runtime


container based on Apache Tomcat 8.

socket)

For the complete list of supported APIs, see Supported Java APIs [page 961]

Related Information
Java Web [page 956]
Java Web Tomcat 7 [page 957]
Java EE 6 Web Profile [page 958]
Java Web Tomcat 8 [page 959]

1.5.2.1.2.1 Java Web


Java Web is a minimalistic application runtime container in SAP HANA Cloud Platform that offers a subset of Java
EE standard APIs typical for a standalone Java Web Container.
This runtime container is suitable for SAP HANA Cloud Platform applications that need a small, low memory
consuming container. The default supported Java version for Java Web is 6; you can also use Java version 7.
The current version 1 of the Java Web application runtime container (neo-java-web 1.x) provides implementation
for the following set of Java Specification Requests (JSRs):
Table 303:
Specification version

JSR

Servlet 3.0

JSR - 315

JavaServer Pages (JSP) 2.2

JSR - 245

956

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Specification version

JSR

Expression Language (EL) 2.2

JSR - 245

Debugging Support for Other Languages 1.0

JSR - 45

Java API for WebSocket

JSR - 356

Development Process
The Java Web enables you to easily create your applications for SAP HANA Cloud Platform utilizing standard
defined APIs suitable for a Web Container in addition to SAP HANA Cloud Platform services APIs.
For more information, see SAP HANA Cloud SDK Java Docs.

Related Information
Choosing JRE Version [page 1103]
Supported Java APIs [page 961]

1.5.2.1.2.2 Java Web Tomcat 7


Java Web Apache Tomcat 7 (Java Web Tomcat 7) is the next simplified edition of Java Web application runtime
container providing optimized performance particularly in the area of startup time and memory footprint.
This container leverages Apache Tomcat 7 without modifications and adds a subset of SAP HANA Cloud Platform
services client APIs. Applications running in the Apache Tomcat 7 container are portable on Java Web Tomcat 7.
Existing applications running on the first edition of Java Web application runtime container can run unmodified on
Java Web Tomcat 7 in case they share same set of enabled APIs.
The default supported Java version for Java Web Tomcat 7 is 7; you can also use Java version 8.
The current version of Java Web Tomcat 7 application runtime container (neo-java-web 2.x) provides
implementation for the following set of Java Specification Requests (JSRs) defined specifications:
Table 304:
Specification version

JSR

Servlet 3.0

JSR - 315

JavaServer Pages (JSP) 2.2

JSR - 245

Expression Language (EL) 2.2

JSR - 245

Debugging Support for Other Languages 1.0

JSR - 45

Java API for WebSocket

JSR - 356

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

957

The following subset of APIs of SAP HANA Cloud Platform services are available within Java Web Tomcat 7:
document service APIs, mail service APIs, connectivity service APIs (destination configuration and authentication
header provider), persistence service JDBC APIs, and security APIs.

1.5.2.1.2.3 Java EE 6 Web Profile


The Java EE 6 Web Profile application runtime container of SAP HANA Cloud Platform is Java EE 6 Web Profile
certified.
The lightweight Web Profile of Java EE 6 is targeted at next-generation Web applications. Developers benefit from
productivity improvements with more annotations and less XML configuration, more Plain Old Java Objects
(POJOs), and simplified packaging.
The default supported Java version for Java EE 6 Web Profile is 7; you can also use Java version 6.
The current version 2 of Java EE 6 Web Profile application runtime container (neo-javaee6-wp 2.x) provides
implementation for the following Java Specification Requests (JSRs):
Specification version

JSR

Java EE 6 (Web Profile)

JSR - 316

Servlet 3.0

JSR - 315

JavaServer Pages (JSP) 2.2

JSR - 245

Expression Language (EL) 2.2

JSR - 245

Debugging Support for Other Languages 1.0

JSR - 45

Standard Tag Library for JavaServer Pages (JSTL) 1.2

JSR - 52

Java API for WebSocket

JSR - 356

JavaServer Faces (JSF) 2.0

JSR - 314

Common Annotations for Java Platform 1.1

JSR - 250

Enterprise JavaBeans (EJB) Lite 3.1

JSR - 318

Java Transaction API (JTA) 1.1

JSR - 907

Java Persistence API (JPA) 2.0

JSR - 317

Dependency Injection for Java 1.0

JSR - 330

Contexts and Dependency Injection for Java EE platform 1.0

JSR - 299

Bean Validation 1.0

JSR - 303

Managed Beans 1.0

JSR - 316

Interceptors 1.1

JSR - 318

Source: JSR-316

(Web Profile), Chapter 2: Web Profile Definition

For more information about the differences between EJB 3.1 and EJB 3.1 Lite, see the Java EE 6 specification, JSR
318: Enterprise JavaBeans, section 21.1.

958

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Development Process
The Java EE 6 Web Profile enables you to easily create your applications for SAP HANA Cloud Platform.
For more information, see Using Java EE 6 Web Profile [page 966].

Related Information
Java EE at a Glance
Supported Java APIs [page 961]

1.5.2.1.2.4 Java Web Tomcat 8


Java Web Apache Tomcat 8 (Java Web Tomcat 8) is the next edition of the Java Web application runtime
container that has all characteristics and features of its predecessor Java Web Tomcat 7.
This container leverages Apache Tomcat 8 Web container without modifications and also adds the already
established set of SAP HANA Cloud Platform services client APIs. Applications running in the Apache Tomcat 8
are portable to Java Web Tomcat 8. Existing applications running on Java Web and Java Web Tomcat 7
application runtime containers can run unmodified on Java Web Tomcat 8 in case they share the same set of
enabled APIs.
The default supported Java version for Java Web Tomcat 8 is 8; you can also use Java version 7.
The current version of Java Web Tomcat 8 application runtime container (neo-java-web 3.x) provides
implementation for the following set of Java Specification Requests (JSRs) defined specifications:
Table 305:
Specification version

JSR

Servlet 3.1

JSR - 340

JavaServer Pages (JSP) 2.3

JSR - 245

Expression Language (EL) 3.0

JSR - 341

Debugging Support for Other Languages 1.0

JSR - 45

Java API for WebSocket

JSR - 356

The following subset of APIs of SAP HANA Cloud Platform services are available within Java Web Tomcat 8:
document service APIs, mail service APIs, connectivity service APIs (destination configuration and authentication
header provider), persistence service JDBC APIs, and security APIs.

1.5.2.1.3

Compute Units

A compute unit is the virtualized hardware resources used by an SAP HANA Cloud Platform application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

959

After being deployed to the cloud, the application is hosted on a compute unit with certain central processing unit
(CPU), main memory, disk space and an installed OS.

Compute Unit Sizes


SAP HANA Cloud Platform offers four standard sizes of compute units according to the provided resources.
Depending on their needs, customers can choose from the following compute unit configurations:
Table 306:
Compute Unit

Configuration

Size Parameter Value

Lite edition

1 CPU Core; 2048 MB Main memory

lite

Professional edition

2 CPU Cores; 4096 MB Main memory

pro

Premium edition

4 CPU Cores; 8192 MB Main memory

prem

Premium Plus edition

8 CPU Cores; 16384 MB Main memory

prem-plus

The third column in the table shows what value of the -z or --size parameter you need to use for a console
command.

Note
For developer accounts, only the Lite edition is available. So on the trial landscape, you can run only one
application at a time.
For customer accounts, all sizes of compute units are available. During deployment, customers can specify the
compute unit on which they want their application to run.
For more information, see deploy [page 141].

Related Information
Account Types [page 12]
Purchasing a Customer Account [page 16]
Managing Account Quota [page 21]

1.5.2.2

Development Environment

The basic tools of the SAP HANA Cloud Platform development environment, the SAP HANA Cloud Platform Tools,
comprise the SAP HANA Cloud Platform Tools for Java and the SAP HANA Cloud Platform SDK.
The focus of the SAP HANA Cloud Platform Tools for Java is on the development process and enabling the use of
the Eclipse IDE for all necessary tasks: creating development projects, deploying applications locally and in the

960

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

cloud, and local debugging. It makes development for the platform convenient and straightforward and allows
short development turn-around times.
The SDK, on the other hand, contains everything you need to work with the platform, including a local server
runtime and a set of command line tools. The command line capabilities enable development outside of the
Eclipse IDE and allow modern build tools, such as Apache Maven, to be used to professionally produce Web
applications for the cloud. The command line is particularly important for setting up and automating a headless
continuous build and test process.
A graphical overview of this tool environment is shown below:

Related Information
Installing Java Tools for Eclipse and SDK [page 33]
Eclipse Tools [page 86]

1.5.2.2.1

Supported Java APIs

When you develop applications that run on SAP HANA Cloud Platform, you can rely on certain Java EE standard
APIs. These APIs are provided with the runtime of the platform. They are based on standards and are backward
compatible as defined in the Java EE specifications. Currently, you can make use of the APIs listed below:
javax.activation
javax.annotation
javax.el
javax.mail
javax.persistence
javax.servlet
javax.servlet.jsp

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

961

javax.servlet.jsp.jstl
javax.websocket
You can also make use of the following third-party APIs:
org.slf4j.Logger
org.slf4j.LoggerFactory
If you are using the SAP HANA Cloud Platform SDK for Java EE 6 WebProfile, you can have access to the following
Java EE APIs as well:
javax.faces
javax.validation
javax.inject
javax.ejb
javax.interceptor
javax.transaction
javax.enterprise
javax.decorator
The table below summarizes the Java Request Specifications (JSRs) supported in the two SAP HANA Cloud
Platform SDKs for Java.
Table 307:
Supported Java EE 6 Specification

SAP HANA Cloud Platform SDK for


Java Web

SAP HANA Cloud Platform SDK for


Java EE 6 WebProfile

Servlet 3.0

yes

yes

JavaServer Pages (JSP) 2.2

yes

yes

Expression Language (EL) 2.2

yes

yes

Debugging Support for Other Languages yes


1.0

yes

Standard Tag Library for JavaServer Pa


ges (JSTL) 1.2

yes

yes

Common Annotations for Java Platform


1.1

yes

yes

Java API for WebSocket

yes

yes

JavaServer Faces (JSF) 2.0

no

yes

Enterprise JavaBeans (EJB) Lite 3.1

no

yes

Java Transaction API (JTA) 1.1

no

yes

Java Persistence API (JPA) 2.0

no

yes

Dependency Injection for Java 1.0

no

yes

Contexts and Dependency Injection for


Java EE platform 1.0

no

yes

Bean Validation 1.0

no

yes

Managed Beans 1.0

no

yes

Interceptors 1.1

no

yes

962

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The table below summarizes the Java Request Specifications (JSRs) supported in the SAP HANA Cloud Platform
SDK for Java Web Tomcat 8 .
Table 308:
Supported Java EE 7 Specification

SAP HANA Cloud Platform SDK for Java Web Tomcat 8

Servlet 3.1

yes

JavaServer Pages (JSP) 2.3

yes

Expression Language (EL) 3.0

yes

WebSocket 1.1

yes

Common Annotations for Java Platform 1.1

yes

Standard Tag Library for JavaServer Pages (JSTL) 1.2

yes

Debugging Support for Other Languages 1.0

yes

In addition to the standard APIs, SAP HANA Cloud Platform offers platform-specific services that define their own
APIs that can be used from the SAP HANA Cloud Platform SDK. The APIs of the platform-specific services are
listed in the table below
API

More Information

Security

Securing Java Applications [page 1211]

Connectivity

Connectivity and Destination APIs [page 272]

Document

Handling CMIS Metadata [page 564]

The SAP HANA Cloud Platform SDK contains a platform API folder for compiling your Web applications. It
contains the above content, that is, all standard and third-party API JARs (for legal reasons provided "as is", that
is, they also have non-API content on which you should not rely) and the platform APIs of the SAP HANA Cloud
Platform services.
You can add additional (pure Java) application programming frameworks or libraries and use them in your
applications. For example, you can include Spring Framework in the application (in its application archive) and use
it in the application. In such cases, the application should handle all dependencies to such additional frameworks
or libraries and you should take care for the whole assembly of such additional frameworks or libraries inside the
application itself.
SAP HANA Cloud Platform also provides numerous other capabilities and APIs that might be accessible for
applications. However, you should rely only on the APIs listed above.
For more information, see:
API Documentation [page 1060]
Javadoc for SAP HANA Cloud Platform

Related Information
Java Web [page 956]
Java EE 6 Web Profile [page 958]
Java Web Tomcat 7 [page 957]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

963

Java Web Tomcat 8 [page 959]

1.5.2.3

Developing Java Applications

You can develop applications for SAP HANA Cloud Platform just like for any application server. SAP HANA Cloud
Platform applications can be based on the Java EE Web application model. You can use programming logic that is
well-known to you, and benefit from the advantages of Java EE, which defines the application frontend. Inside, you
can embed the usage of the services provided by the platform.

Development Environment
SAP HANA Cloud Platform development environment is designed and built to optimize the process of
development and deployment.
It includes the SAP HANA Cloud Platform Tools for Java, which integrate the standard capabilities of Eclipse IDE
with some extended features that allow you to deploy on the cloud. You can choose between three types of SAP
HANA Cloud Platform SDK for Java applications:
SDK for Java Web - provides support for some of the standard Java EE 6 APIs (Servlet, JSP, EL, Websocket)
SDK for Java Web Tomcat 7 - provides support for some of the standard Java EE 6 APIs (Servlet, JSP, EL,
Websocket)
SDK for Java EE 6 Web Profile - certified to support Java EE 6 Web Profile APIs
SDK for Java Web Tomcat 8 - provides support for some of the standard Java EE 7 APIs (Servlet, JSP, EL,
Websocket)
For more information, see Development Environment [page 960]

Create a basic application


In the Eclipse IDE, create a simple HelloWorld application with basic functional logic wrapped in a Dynamic Web
Project and a Servlet. You can do this with both SDKs.
For more information, see Creating a HelloWorld Application [page 47] or watch the Creating a HelloWorld
application
video tutorial.
To learn how to enhance the HelloWorld application with role management, see the Managing Roles in SAP HANA
video tutorial.
Cloud

964

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Use Java EE 6 Web Profile


SAP HANA Cloud Platform is Java EE 6 Web Profile certified so you can extend the basic functionality of your
application with Java EE 6 Web Profile technologies. If you are working with the SDK for Java EE 6 Web Profile, you
can equip the basic application with additional Java EE features, such as EJB, CDI, JTA.
For more information, see Using Java EE 6 Web Profile [page 966]

Use services and utilities


Create a fully-fledged application benefiting from the capabilities and services provided by SAP HANA Cloud
Platform. In your application, you can choose to use:
Authentication [page 1211] - by default, SAP HANA Cloud Platform is configured to use SAP ID service as
identity provider (IdP), as specified in SAML 2.0. You can configure trust to your custom IdP, to provide
access to the cloud using your own user database.
UI development toolkit for HTML5 (SAPUI5) - use the platform's official UI framework.
Persistence Service [page 723] - provide relational persistence with JPA and JDBC via our persistence
service.
Connectivity Service [page 270] - use it to connect Web applications to Internet, make on-demand to onpremise connections to Java and ABAP on-premise systems and configure destinations to send and fetch email.
Document Service [page 548] - use the service to store unstructured or semistructured data in your
application.
Logging [page 1129]- implement a logging API if you want to have logs produced at runtime.
Cloud Environment Variables [page 970]- use system environment variables that identify the runtime
environment of the application.

Deploy
First, deploy and test the ready application on the local runtime and then make it available on SAP HANA Cloud
Platform.
For more information, see Deploying and Updating Applications [page 973]
You can speed up your development by applying and activating new changes on the already running application.
Use the hot-update command.
For more information, see hot-update [page 182]

Manage
Manage all applications deployed in your account from a single dedicated user interface - SAP HANA Cloud
Platform cockpit.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

965

For more information, see Cockpit [page 84]

Monitor
Configure checks and monitor the state of your applications.
For more information, see Monitoring Java Applications [page 1149]

1.5.2.3.1

Using Java EE 6 Web Profile

SAP HANA Cloud Platform is certified to support Java EE 6 Web Profile. If you want to use it in your applications,
you have to develop them using SAP HANA Cloud Platform SDK for Java EE 6 Web Profile.

Prerequisites
You have downloaded SAP HANA Cloud Platform Tools. Make sure you download the SDK for Java EE 6 Web
Profile. For more information, see Setting Up the Tools and SDK [page 33].
If you have a previously installed version of SAP HANA Cloud Platform Tools, make sure you update them to
the latest version. For more information, see Updating the Tools and SDK [page 43].
The SDK brings all required libraries. In case you get an error with the import of a library, for example,
javax.ejb.localbean, make sure you have set the SAP HANA Cloud Platform Tools and the Web Project
correctly.

Procedure
First, create a basic HelloWorld application:
Create a Dynamic Web Project [page 401]
Create a servlet [page 402]
Then, equip the simple application with additional Java EE functionalities:
Create a JSP [page 968]
Create an EJB business method [page 968]
Call the EJB from the Servlet [page 969]
Call the EJB from the JSP [page 969]

966

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Create a Dynamic Web Project


1. Open your Eclipse IDE for Java EE Developers.
2. From the Eclipse IDE main menu, choose

File

New

Dynamic Web Project .

3. In the Project name field, enter HelloWorld.


4. From the Target Runtime section, select Java EE 6 Web Profile.
5. For Web module version, choose 3.0.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

967

6. In the Configuration area, leave the default configuration. When you are working with the SDK for Java EE 6
Web Profile, your application is provisioned on Java 7 by default.
7. Choose Finish.
For more information, see Creating a HelloWorld Application [page 47] .

Create a servlet
1. On the HelloWorld project node, open the context menu and choose
Servlet opens.

New

Servlet . Window Create

2. Enter hello as the Java package and HelloWorldServlet as the class name. Choose Next.
3. In the URL mappings field, select /HelloWorldServlet and choose Edit.
4. In the Pattern field, replace the current value with just "/" and choose OK. In this way, the servlet will be
mapped as a welcome page for the application.

5. Choose Finish to generate the servlet. The Java Editor with the HelloWorldServlet opens.
6. Change the doGet() method so that it contains:
response.getWriter().println("Hello World!");
7. Save your changes.
For more information, see Creating a HelloWorld Application [page 47].

Create a JSP
1. On the HelloWorld project node, open the context menu and choose
opens.

New

JSP file . Window New JSP file

2. Enter the name of your JSP file and choose Finish.

Create an EJB business method


EJB components represent the business logic in a Java EE application.
1. On the HelloWorld project node, choose

File

New

Other

EJB

Session Bean . Choose Next.

2. In the Create EJB session bean wizard, nter test as the Java package and HelloWorldBean as the name of
your new class. Choose Finish.

968

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Implement a simple public method sayHello that returns a greeting string. Save the project.
package test;
import javax.ejb.LocalBean;
import javax.ejb.Stateless;
/**
* Session Bean implementation class HelloWorldBean
*/
@Stateless
@LocalBean
public class HelloWorldBean {
/**
* Default constructor.
*/
public HelloWorldBean() {
// TODO Auto-generated constructor stub
}

public String sayHello() {


return "Hello from session bean";
}

Call the EJB from the Servlet


1. Create a reference from the servlet to the session bean:
@EJB
private HelloWorldBean helloWorldBean;
2. Change the doGet method to call the business method:
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
response.getWriter().println(helloWorldBean.sayHello());

Call the EJB from the JSP


1. Create imports to the bean class and EJB API.
2. Look up the HelloWorldBean using JNDI.
3. Call the HelloWorldBean business method using a JNDI lookup.
Your modified JSP should look like this:
<%@page import="javax.naming.InitialContext"%>
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://
www.w3.org/TR/html4/loose.dtd">
<%@ page import = "test.HelloWorldBean" %>
<%@ page import = "javax.ejb.EJB" %>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Insert title here</title>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

969

</head>
<body>
</body>
</html>
<%
try {
InitialContext ic = new InitialContext();
HelloWorldBean h= (HelloWorldBean)ic.lookup("java:comp/env/
hello.HelloWorldServlet/helloWorldBean");
out.println(h.sayHello());
}
catch(Exception e) {
out.println("error at client");
}
%>
You can test the application on the local runtime and then deploy it on SAP HANA Cloud Platform.
For more information, see Deploying an Application on SAP HANA Cloud [page 973].
You can now use JPA together with EJB to persist data in your application
For more information, see Adding Container-Managed Persistence With JPA (Java EE 6 Web Profile SDK) [page
724]

1.5.2.3.2

Using Cloud Environment Variables

Overview
SAP HANA Cloud Platform runtime sets several system environment variables that identify the runtime
environment of the application. Using them, an application can get information about its application name,
account and URL, as well as information about the landscape it is deployed on and landscape specific parameters.
All SAP HANA Cloud Platform specific environment variables names start with the common prefix HC_.

List of Environment Variables


The following SAP HANA Cloud Platform environment variables are set to the runtime environment of the
application:
Table 309:
Key

Sample Value

Description

HC_HOST

hana.ondemand.com /
us1.hana.ondemand.com /
hanatrial.ondemand.com

Base URL of the SAP HANA Cloud Plat


form landscape where the application is
deployed

970

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Key

Sample Value

Description

HC_HOST_SVC

svc.hana.ondemand.com /
svc.us1.hana.ondemand.com /
svc.hanatrial.ondemand.com

URL of the SAP HANA Cloud Platform


landscape which provides access within
the same landscape; for direct commu
nication and not open on the Internet or
other networks

HC_HOST_CERT

cert.hana.ondemand.com /
cert.us1.hana.ondemand.com
/
cert.hanatrial.ondemand.com

URL of the SAP HANA Cloud Platform


landscape which enables client certifi
cate authentication

HC_REGION

EU_1 / US_1

Region of the data center where the ap


plication is deployed

HC_ACCOUNT

myaccount

Name of the account where the applica


tion is deployed

HC_APPLICATION

myapp

Application name

HC_APPLICATION_URL

https://
myapp.hana.ondemand.com

URL of the application

HC_LOCAL_HTTP_PORT

9001

HTTP port of the application bound to lo


calhost

HC_LANDSCAPE

production / trial

Type of the landscape where the appli


cation is deployed

HC_PROCESS_ID

8921b0a7cebc5538038b6b7b0c0
ea6a7127f0cd4

Process ID of the current application


process as returned by the status
command with parameter --show-

full-process-id.
HC_OP_HTTP_PROXY_HOST

localhost

Host of the HTTP Proxy for on-premise


connectivity

HC_OP_HTTP_PROXY_PORT

20003

Port of the HTTP Proxy for on-premise


connectivity

Using Cloud Environment Variables


SAP HANA Cloud Platform environment variables are accessed as standard system environment variables of the
Java process - for example via System.getenv("...").

Note
Environment variables are not set when deploying locally with the console client or Eclipse IDE.

Example
<html>
<head>
<title>Display SAP HANA Cloud Environment Platform variables</title>
</head>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

971

<body>

<p>Application Name: <%= System.getenv("HC_APPLICATION") %></p>


</body>
</html>

Related Information
status [page 238]
Landscape Hosts [page 32]
HTTP Proxy for On-Premise Connectivity [page 336]

1.5.2.3.2.1 Setting the Cloud Environment Variables Using


Eclipse IDE
Prerequisites
In the Eclipse IDE you have developed or imported a Java application that is running on a cloud server.

Context
In the Server editor of your local Eclipse IDE, you can use the Advanced tab and the Environment Variables table to
add, edit, select and remove environment variables for the cloud virtual machine.

Note
The Advanced tab is only available for cloud servers.

Procedure
1. In the Eclipse IDE go to the Servers view and select the cloud server you want to configure.
2. Double click on it to open the Server Editor.
3. Open the Advanced tab.
4. (Optional) Add an environment variable.
1. Press the Add

button.

2. Enter a name.
3. Enter a value.

972

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Choose OK to add the new environment variable.


5. Save the changes you made by choosing

File

Save

or with Ctrl + S .

5. (Optional) Select environment variables, to import environment variables that already exist on your local
machine.
1. Press the Select

button.

2. Choose one or more local environment variables you want to add.


3. Choose OK.
4. Save the changes you made by choosing

File

Save

or with Ctrl + S .

Save

or with Ctrl + S .

6. (Optional) Edit environment variables.


1. Select the environment variable you want to edit.
2. Press the Edit

button.

3. Edit one or both properties.


4. Choose OK to make your changes.
5. Save the changes you made by choosing

File

7. (Optional) Delete environment variables.


1. Select the environment variable you want to delete.
2. Press the Delete

button.

3. Save the changes you made by choosing

File

Save

or with Ctrl + S .

Note
The changes made by someone else will be loaded once you reopen the editor.

1.5.2.4

Deploying and Updating Applications

Table 310:
Content
Deploying Applications [page 973]
Updating Application Properties [page 974]
Updating During Development [page 974]
Updating Productive Applications [page 975]

Deploying Applications
After you have created your Java application, you need to deploy and run it on SAP HANA Cloud Platform. We
recommend that you first deploy and test your application on the local runtime before deploying it on the cloud.
Use the tool that best fits your scenario:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

973

Table 311:
Eclipse IDE

Deploying Locally from Eclipse IDE [page You have developed your application using SAP HANA Cloud
975]

Platform Tools in the Eclipse IDE.

Deploying on the Cloud from Eclipse IDE


[page 977]
Console Client

Deploying Locally with the Console Cli

You want to deploy an application in the form of one or more

ent [page 981]

WAR files.

Deploying on the Cloud with the Console

Command: deploy

Client [page 983]


Cockpit

Deploying on the Cloud with the Cockpit


[page 985]

You want to deploy an application in the form of a WAR file.

Updating Application Properties


Application properties are configured during deployment with a set of parameters. To update these properties,
use one of the following approaches:
Table 312:
Console Client

deploy [page 141]

Deploy the application with new WAR file(s) and make


changes to the configuration parameters.
Command: deploy

Console Client

set-application-property [page 229]

Change some of the application properties you defined during


deployment without redeploying the application binaries.
Command: set-application-property

Cockpit

Deploying on the Cloud with the Cockpit

Update the application with a new WAR file or make changes

[page 985]

to the configuration parameters.

Updating During Development


If you want to quickly see your changes while developing an application, use the following approaches:
Table 313:
Eclipse IDE

Console Client

Deploying on the Cloud from Eclipse IDE

Republish the application. The cloud server is not restarted,

[page 977]

and only the application binaries are updated.

hot-update [page 182]

Apply and activate changes. Use the command to speed up


development and not for updating productive applications.
Command: hot-update

974

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Console Client

Delta Deployment [page 984]


deploy [page 141]
hot-update [page 182]

Apply changes in a deployed application without uploading the


entire set of files.
Command: deploy or hot-update
Parameter: --delta

Updating Productive Applications


If you are an application operator and need to deploy a new version of a productive application or perform
maintenance, you can choose among several approaches:
Table 314:
Zero Downtime

Updating Applications with Zero Down

Use when the new application version is backward compatible

time [page 1121]

with the old version. Deploy a new version of the application

rolling-update [page 224]

and disable and enable processes in a rolling manner, or, do it


at one go with the rolling-update command.

Planned Down

Using Maintenance Mode for Planned

Use when the new application version is backward incompati

time

Downtimes [page 1123]

ble. Enable maintenance mode for the time of the planned


downtime.

(Maintenance
Mode)
Soft Shutdown

Soft Shutdown [page 1126]

Supports zero downtime and planned downtime scenarios.


Disable the application or individual processes in order to shut
down the application or processes gracefully.

Related Information
Product Prerequisites and Restrictions [page 8]

1.5.2.4.1

Deploying Locally from Eclipse IDE

Follow the steps below to deploy your application on a local SAP HANA Cloud Platform server.

Prerequisites
You have set up your runtime environment in Eclipse IDE. For more information, see Setting Up the Runtime
Environment [page 39].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

975

You have developed or imported a Java Web application in Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53]

Procedure
1. Open the servlet in the Java Editor and from the context menu, choose

Run As

Run on Server

2. Window Run On Server opens. Make sure that the Manually define a new server option is selected.
3. Expand the SAP node and, as a server type, choose between:
Java Web Server
Java Web Tomcat 7 Server
Java Web Tomcat 8 Server
Java EE 6 Web Profile Server
4. Choose Finish.
5. The local runtime starts up in the background and your application is installed, started and ready to serve
requests.

Note
If this is the first server you run in your IDE workspace, a folder Servers is created and appears in the
Project Explorer navigation tree. It contains configurable folders and files you can use, for example, to
change your HTTP or JMX port.
6. The Internal Web Browser opens in the editor area and shows the application output.
7. Optional: If you try to delete a server with an application running on it, a dialog appears allowing you to choose
whether to only undeploy the application, or to completely delete it together with its configuration.

Next Steps
After you have deployed your application, you can additionally check your server information. In the Servers view,
double-click on the local server and open the Overview tab. Depending on your local runtime, the following data is
available:
If you have run your application in Java Web or Java EE 6 Web Profile runtime, you see the standard
server data (General Info, Publishing, Timeouts, Ports).
If you have run your application in Java Web Tomcat 7 or Java Web Tomcat 8 runtime, you see some
additional Tomcat sections, default Tomcat ports, and an extra Modules page, which shows a list of all
applications deployed by you.

Related Information
Updating Applications [page 1119]
Application Runtime Container [page 955]

976

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.2.4.2

Deploying on the Cloud from Eclipse IDE

Follow the steps below to deploy an application on SAP HANA Cloud Platform.

Prerequisites
You have set up your runtime environment in the Eclipse IDE. For more information, see Setting Up the
Runtime Environment [page 39].
You have developed or imported a Java Web application in Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53]

Procedure
1. Open the servlet in the Java editor and from the context menu, choose

Run As

Run on Server .

2. The Run On Server dialog box appears. Make sure that the Manually define a new server option is selected.
3. As server type, select

SAP

SAP HANA Cloud Platform

4. For Server name, use the landscape host depending on your account type. For more information, see
Landscape Hosts [page 32]
5. Choose Next.
6. On the New Server wizard page, specify your application name (only lowercase Latin letters and digits are
allowed).
The application name should be unique enough so that your deployed application can be easily identified.
7. From the Runtime dropdown box, select a specific runtime. If you leave the Automatic option, the server will
load the target runtime of your application.
8. Enter your account name, e-mail or user name, and password.

Note
If you have previously entered an account and user name for your landscape host, these names will be
prompted to you in dropdown lists.
A dropdown list will be displayed as well for previously entered landscapes hosts.
If you select the Save password box, the entered password for a given user name will be remembered
and kept in the secure store.
9. Choose Finish. This triggers the publishing of the application on SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

977

10. After publishing has completed, the Internal Web Browser opens and shows the application.

Note
You cannot deploy multiple applications on the same application process. Deployment of a second
application on the same application process overwrites any previous deployments. If you want to deploy
several applications, deploy each of them on a separate application process.

Next Steps
If, during development, you need to redeploy your application, after choosing Run on Server or Publish, the
cloud server will not be restarted but only the binaries of the application will be updated.

978

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If you try to delete a server with an application running on it, a dialog appears allowing you to choose whether
to only undeploy the application, or to completely delete it together with its configuration.
If you have made changes in your deployed application, and you want them to be faster applied without
uploading the entire set of files t the cloud, proceed as follows:
1. In the Servers view, double-click on the cloud server.
2. Open the Overview tab.
3. In the Publishing section, select Publish changes only (delta deploy).

You can see all applications deployed in your account within the Eclipse Tools, or change the current runtime. For
more information, see Advanced Application Configurations [page 979].

Related Information
Updating Applications [page 1119]
Application Runtime Container [page 955]

1.5.2.4.2.1 Advanced Application Configurations


SAP HANA Cloud Platform Tools provide options for advanced server and application configurations from the
Eclipse IDE, as well as direct reference to the cockpit UI.

Prerequisites
You have developed or imported a Java Web application in the Eclipse IDE. For more, information, see Developing
Java Applications [page 964] or Importing Samples as Eclipse Projects [page 53].

Referring the Cockpit from the Eclipse IDE


1. In the Servers view, double-click on the cloud server.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

979

2. Open the Overview tab.


3. In panel Application Information, click the link Show in Cockpit. The internal Web browser opens the
cockpit in a new browser tab.
4. The Application URLs panel provides information about your deployed applications.
If the cloud server status is different from Started, a message tells you that the deployed applications
cannot be displayed. You have a UI option to directly start the server.
If the cloud server is started but no applications are deployed in this account, a relevant message is
displayed.
If the cloud server is started and there are deployed applications, the panel lists their URLs. When you
click a URL, the relevant application is opened in a new browser tab by the internal Web browser.
Alternatives
There are alternative ways to open the cockpit (1) and the application URLs (2).
1. In the Servers view, open the context menu and choose

Show In

Cockpit .

2. In the Servers view, expand the cloud server node and, from the context menu of the relevant application,
choose

Application URL

Open . It will be opened in a new browser tab.

Tip
If the application is published on the cloud server, besides the Open option you can also choose Copy to
Clipboard, which only copies the application URL.
If the application has not been published but only added to the server, Copy to Clipboard will be disabled.
The Open option though will display a dialog which allows you to publish and then open the application in a
browser.
If the cloud server is not in Started status, both Application URL options will be disabled.

Configuring the Server Runtime


After you have deployed your application, you can check and also change the server runtime. Proceed as follows:
1. In the Servers view, double-click on the cloud server.
2. Open the Overview tab.
3. In panel Application Information, , the following fields are displayed:
Runtime (Java Web, Java Web Tomcat 7, Java Web Tomcat 8, Java EE 6 Web Profile) - the
new runtime of the cloud server to which you can switch, if relevant. The default is Automatic, which is
the target runtime of the Web application during creation and deployment.
Runtime in use (Java Web, Java Web Tomcat 7, Java Web Tomcat 8, Java EE 6 Web Profile) the runtime of the cloud server set during server creation, depending on the landscape host. If you
change it via the Runtime option, then Runtime in use will show the new value.
Account name the account from which you have deployed your application.
Application name the name of the deployed application.

Note
When you change the Runtime value so that it differs from the one in Runtime in use, after saving your
change, a link appears prompting you to republish the server.

980

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Advanced Application Parameters


From the server editor, you can configure additional application parameters, such as compute unit size, JVM
arguments, and others.
1. In the Servers view, double-click on the cloud server.
2. Open the Advanced tab, the following panels are displayed:
The used Java version field is read-only. The JVM version can be changed by modifying the supported Java
version within the project facets properties.
Size and Processes you can change the compute unit size and modify the number of processes.
JVM the field showing currently used Java version is read-only. The JVM version can be changed by
modifying the supported Java version within the project facets properties.
Tomcat Connector Attributes you can modify Tomcat connection parameters and the URI encoding
type, as well as enable/disable the response compression.
Environment variables - you can add, select, edit and remove environment variables.
3. When ready, save your changes.

Note
If you make your configurations on a started server, the changes will take effect after server restart. You
can use the link Restart to apply changes.

Related Information
deploy [page 141]
Runtime for Java [page 953]
Choosing JRE Version [page 1103]
Configuring VM Arguments [page 1105]
Setting the Cloud Environment Variables Using Eclipse IDE [page 972]

1.5.2.4.3

Deploying Locally with the Console Client

The console client allows you to install a server runtime in a local folder and use it to deploy your application.

Procedure
1. Open the folder <SDK installation folder>/tools.
2. Open the command window, enter the following command, and press ENTER :
neo install-local

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

981

This installs a server runtime in the default local server directory <SDK installation folder>/server.
To use an alternative directory, enter the command together with the following optional command argument:
--location <local server directory>
3. To start the local server, enter the following command and press ENTER :
neo start-local
This starts a local server instance in the default local server directory <SDK installation folder>/
server. Again, use the following optional command argument to specify another directory:
--location <local server directory>
4. To deploy your application, enter the following command as shown in the example below and press ENTER :
neo deploy-local --source hello-world.war
This deploys the WAR file on the local server instance. If necessary, specify another directory as in step 3.
5. To check your application is running, open a browser and enter the URL, for example:
http://localhost:8080/hello-world

Note
The HTTP port is normally 8080. However, the exact port configurations used for your local server,
including the HTTP port, are displayed on the console screen when you install and start the local server.
6. To stop the local server instance, enter the following command from the <SDK installation folder>/
tools folder and press ENTER :
neo stop-local

Related Information
install-local [page 184]
start-local [page 242]
deploy-local [page 146]
stop-local [page 246]

982

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.2.4.4

Deploying on the Cloud with the Console Client

Deploying an application publishes it to SAP HANA Cloud Platform. During deploy, you can define various
specifics of the deployed application using the deploy command optional parameters.

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client [page 42]
Depending on your account type, deploy the application on the respective landscape. For more information,
see Landscape Hosts [page 32]

Procedure
1. In the opened command line console, execute neo deploy command with the appropriate parameters.
You can define the parameters of commands directly in the command line as in the example below, or in the
properties file. For more information, see Using the Console Client [page 89].
2. Enter your password if requested.
3. Press ENTER and deployment of your application will start. If deployment fails, check if you have defined the
parameters correctly.

Note
The size of an application deployed on SAP HANA Cloud Platform can be up to 1.5 GB. If the application is
packaged as a WAR file, the size of the unzipped content is taken into account.

Example
neo deploy --host <landscape_host> --account <account_name> --application
<application_name> --source samples/deploy_war/example.war --user <email_or_user>

Next Steps
To make your deployed application available for requests, you need to start it by executing the neo start
command.
Then, you can manage the application lifecycle (check the status; stop; restart; undeploy) using dedicated
console client commands.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

983

Related Information
deploy [page 141]
start [page 240]
restart [page 218]
stop [page 244]
status [page 238]
undeploy [page 254]
Delta Deployment [page 984]
Updating Applications [page 1119]
Updating Application Properties [page 1101]

1.5.2.4.4.1 Delta Deployment


By using the delta deployment option, you can apply changes in a deployed application faster without uploading
the entire set of files t SAP HANA Cloud Platform.

Context
The delta parameter allows you to deploy only the changes between the provided source and the previously
deployed content - new content is added; missing content is deleted; existing content is updated if there are
changes. The delta parameter is available in two commands deploy and hot-update.

Note
Use it to save time for development purposes only. For updating productive applications, deploy the whole
application.

Procedure
To upload only the changed files from the application WARs, use one of the two approaches:
Deploy the application specifying the --delta parameter:
neo deploy myapp.properties

--source <file_location> --delta

For the changes to take effect, restart the application.


Upload the delta and apply the changes on an already running application process with the hot-update
command:
neo hot-update myapp.properties
<update_strategy> --delta

984

--source <file_location> --strategy

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
With the source parameter, provide the whole set of files of your application, not only the changed ones.

Related Information
hot-update [page 182]
deploy [page 141]
Deploying on the Cloud with the Console Client [page 983]

1.5.2.4.5

Deploying on the Cloud with the Cockpit

The cockpit allows you to deploy Java applications as WAR files and supports a number of deployment options for
configuring the application.

Procedure
1. Log on to the cockpit and select an account.
2. Choose Java Applications in the navigation area.
3. Choose Deploy Application.
4. Select the WAR file that you want to deploy, for example, in directory <SDK_location>/samples/.
5. Use the application name that the cockpit proposes to you. It is the same name as for the WAR file.
Alternatively, enter an application name. Note that application names must start with a letter, can contain
lowercase letters and numbers only, and must not exceed 30 characters.
You can also assign a display name and a description to a Java application.
6. Optionally specify additional parameters to configure the application. If omitted, default values will be
assigned.
For more information about the deploy parameters, see the deploy [page 141] command documentation.
7. Choose Deploy to deploy the WAR file to the cloud platform.
The Deploy Application dialog box remains on the screen while the deployment is in progress. When the
deployment is over, a confirmation appears that the application has been successfully deployed. Note that at
this stage the application is not yet up and running.
8. In the dialog box, choose one of the following options:
Start: Start the application to activate its URL and make the application available to your end users.
Close: Simply close the dialog box if you do not want to start the application immediately.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

985

Results
Your newly deployed application appears in the list of Java Applications.
Updating a deployed application
You can update or redeploy the application whenever required. To do this, choose Update application to open the
same dialog box as in update mode. You can update the application with a new WAR file or change the
configuration parameters.
To change the name of a deployed application, deploy a new application under the desired name, and delete the
application whose name you want to change.

Related Information
deploy [page 141]
Cockpit [page 84]
Defining Application Details (Java Apps) [page 1109]

1.5.2.5

Debugging Applications

After you have created a Web application and tested it locally, you may want to inspect its runtime behavior and
state by debugging the application in SAP HANA Cloud Platform. The local and the cloud scenarios are analogical.

Context
The debugger enables you to detect and diagnose errors in your application. It allows you to control the execution
of your program by setting breakpoints, suspending threads, stepping through the code, and examining the
contents of the variables. You can debug a servlet or a JSP file on a SAP HANA Cloud Platform server without
losing the state of your application.

Note
Currently, it is only possible to debug Web applications in SAP HANA Cloud Platform that have exactly one
application process (node).

Tasks
Debugging Applications Locally [page 987]

986

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Debugging Applications on the Cloud [page 988]

Related Information
Profiling Applications [page 1141]

1.5.2.5.1

Debugging Applications Locally

In this section, you can learn how to debug a Web application on SAP HANA Cloud Platform local runtime in the
Eclipse IDE.

Prerequisites
You have developed a Web application using the Eclipse IDE. For more information, see Developing Java
Applications [page 964].

Procedure
1. In the Eclipse IDE, run your Web application on a local server.
2. Set breakpoints in the application.
3. From its context menu, choose

Debug As

Debug on Server .

4. In the Debug On Server window, either select the local server on which your application is running, or create a
new server.
5. Choose Finish.
If you are currently working in a perspective different than Debug, a dialog window appears asking you if
you want to switch to the Debug perspective.
Also, if your server is started, another dialog window appears, informing you that the server is not running
in debug mode. Choose Switch mode and then OK.
6. The Debug view for your server is displayed.

Related Information
Debugging Applications on the Cloud [page 988]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

987

1.5.2.5.2

Debugging Applications on the Cloud

In this section, you can learn how to debug a Web application on SAP HANA Cloud Platform depending on whether
you have deployed it in the Eclipse IDE or in the console client.

Prerequisites
You have developed a Web application using the Eclipse IDE. For more information, see Developing Java
Applications [page 964].
You have deployed your Web application either using the Eclipse IDE or via the console client. For more
information, see Deploying and Updating Applications [page 973].

Note
Debugging can be enabled if there is only one VM started for the requested account or application.

Procedure
Applications Deployed from the IDE
1. Deploy your Web application in the Eclipse IDE.
2. Run your Web application on SAP HANA Cloud Platform.
3. Set breakpoints in your applications.
4. From the application's context menu, choose

Debug As

Debug on Server .

5. The Debug perspective is opened.

Note
Since cloud servers are running on SAP JVM, switching modes does not require restart and happens in real
time.

Applications Deployed with the Console Client


1. Deploy your Web application in the console client and start it.
2. Go to the Eclipse IDE, open the Servers view and choose
3. Choose

SAP

New

Server .

SAP HANA Cloud Platform .

4. Enter the correct landscape host, according to your location. (For more information, see Landscape Hosts
[page 32].)

988

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Edit the server name, if necessary, and choose Next.

6. On page SAP HANA Cloud Platform Application in the wizard, provide the same application data which you
have previously entered in the console client.
7. Choose Finish.
8. A new server is created and attached to your application. It should be in Started mode if your application is
started.
9. From the server's context menu, choose Restart in Debug. (This should not restart the application.)
10. Request your application.
11. Open the Debug perspective for your server.
12. Set breakpoints in your application.

Note
If you have deployed an application on a running server, we recommend that you do not use Debug on
Server or Run on Server for this will republish (redeploy) your application.
Also, bear in mind that if you have deployed two or more WAR files, only the debugged one will remain after
that.
If the sources are not attached (Example: The application is deployed from CLI or you need to attach
additional sources), you may attach them as described here .

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

989

Related Information
Eclipse: Debugging a servlet on a server
Eclipse: Debugging a JSP file on a server

1.5.2.6

Multitenant Applications

With SAP HANA Cloud Platform you can develop and run multitenant (tenant-aware) applications, that is,
applications running on a shared compute unit that can be used by multiple consumers (tenants). Each consumer
accesses the application through a dedicated URL.
You can read about the specifics of each platform service with regards to multitenancy in the respective section
below:
Connectivity Service [page 992]
Persistence Service [page 992]
Document Service [page 992]
Keystore Service [page 993]
Identity and Access Management [page 993]
With tenant-aware applications, you can achieve the following:
Isolate data
Save resources by sharing them among tenants
Perform updates efficiently, that is, in one step
To be able to use a tenant-aware application, a consumer:
Must have an account for SAP HANA Cloud Platform
Must be subscribed to this application
Receives a dedicated URL where to access the application

990

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

A subscription means that there is a contract between an application provider and a tenant who authorizes the
tenant to use the provider's application.
Currently, you can trigger the subscription via the console client for testing purposes. For more information, see
Providing Multitenant Applications to Tenants for Testing [page 1162].
When an application is accessed via a consumer specific URL, the application environment is able to identify the
current consumer. The application developer can use the tenant context API to retrieve and distinguish the tenant
ID, which is the unique ID of the consumer. When developing tenant-aware applications, data isolation for different
consumers is essential. It can be achieved by distinguishing the requests based on the tenant ID. There are also
some specifics in the usage of different services when you develop your multitenant application.
For more information, see:
Tenant Context API [page 995]
https://help.hana.ondemand.com/javadoc/index.html

com.sap.cloud.account

TenantContext

General Programming Guidelines


When developing tenant-aware applications, keep in mind the following:
Shared in-memory data such as Java static fields will be available to all tenants
Avoid any possibility that an application user can execute custom code in the application JVM, as this may
give them access to other tenants' data
Avoid any possibility that an application user can access a file system, as this may give them access to other
tenants' data.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

991

Connectivity Service
For more information, see Multitenancy in the Connectivity Service [page 419].

Persistence Service
Multitenant applications on SAP HANA Cloud Platform have two approaches available to separate the data of the
different consumers:
Use a discriminator column in each table storing tenant data
With this approach, a single database schema is shared between all application consumers. The tenant ID can
be used as a value in the discriminator column. To ensure data separation in the application, each SQL
statement must include the tenant ID.
To apply data separation with a discriminator column, you can use the multitenancy annotations provided by
EclipseLink JPA. For more information, see the EclipseLink User Guide: http://wiki.eclipse.org/EclipseLink/
UserGuide/JPA/Advanced_JPA_Development/Single-Table_Multi-Tenancy .
The basic approach is as follows:
Annotate entities that are to be tenant-aware with the @Multitenant annotation.
Define the discriminator column using the @TenantDiscriminatorColumn annotation. As the length of
the tenant ID on SAP HANA Cloud Platform differs from the default length for the discriminator column in
EclipseLink, it is important to set the correct length of 36 characters.
Provide the tenant ID to the entity manager when accessing data for a multitenant entity.
Use a separate schema for each tenant
With this approach, you create a new schema for each tenant, bind it to the application, and the application
uses JNDI to dynamically look up the data source. The multitenant application must then use the appropriate
data source when accessing tenant data. For more information, see Using Dynamic Data Source Lookup
[page 835].

Document Service
The document service automatically separates the documents according to the current consumer of the
application. When an application connects to a document repository, the document service client automatically
propagates the current consumer of the application to the document service. The document service uses this
information to separate the documents within the repository. If an application wants to connect to the data of a
dedicated consumer instead of the current consumer (for example in a background process), the application can
specify the tenant ID of the corresponding consumer when connecting to the document repository.
For more information, see Data Isolation (Java) [page 553].

992

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Keystore Service
The Keystore Service provides a repository for cryptographic keys and certificates to tenant-aware applications
hosted on SAP HANA Cloud Platform. Because the tenant defines a specific configuration of an application, you
can configure an application to use different keys and certificates for different tenants.
For more information about the Keystore Service, see Keys and Certificates [page 1246].

Identity and Access Management


Access rights for tenant-aware application are usually maintained by the application consumer, not by the
application provider. An application provider may predefine roles in the web.xml when developing the application.
By default, predefined roles are shared with all application consumers, but could also be made visible only to the
provider account. Once a consumer is subscribed to this application, shared predefined roles become visible in
the cockpit of the application consumer. Then, the application consumer can assign users to these roles to give
them access to the provider application. In addition, application consumer accounts can add their own custom
roles to the subscribed application. Custom roles are visible only within the application consumer account where
they are created.
For more information about managing application roles, see Managing Roles [page 1282].
Trust configuration regarding authentication with SAML2.0 protocol is maintained by the application consumer.
For more information about configuring trust, see ID Federation with the Corporate Identity Provider [page 1292].

Related Information
Multitenancy Tutorials [page 998]
Viewing the Default Trace [page 1115]
Providing Multitenant Applications to Tenants for Testing [page 1162]

1.5.2.6.1

Multitenancy Roles

Context
The multitenancy concept concerns two main user roles:
Application Provider - an organizational unit that uses SAP HANA Cloud Platform to build, run and sell
applications to customers, that is, the application consumers.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

993

Application Consumer - an organizational unit, typically a customer or a department inside a customers


organization, which uses an SAP HANA Cloud Platform application for a certain purpose. Obviously, the
application is in fact used by end users, who might be employees of the organization (for instance, in the case
of an HR application) or just arbitrary users, internal or external (for instance, in the case of a collaborative
supplier application).

Accounts and Account Members


To use SAP HANA Cloud Platform, both the application provider and the application consumer need to have an
account. The account is the central organizational unit in SAP HANA Cloud Plaftorm. It is the central entry point to
SAP HANA Cloud Platform for both application providers and consumers. It may consist of a set of applications, a
set of account members and an account-specific configuration.
Account members are users who must be registered via the SAP ID service. Account members may have different
privileges regarding the operations which are possible for an account (for example, account administration,
deploy/start/stop applications). Note that the account belongs to an organization and not to an individual.
Nevertheless, the interaction with the account is performed by individuals, the members of the account. The
account-specific configuration allows application providers and application consumers to adapt their account to
their specific environment and needs.
An application resides in exactly one account, the hosting account. It is uniquely identified by the account name
and the application name. Applications consume SAP HANA Cloud Platform resources, for instance, compute
units, structured and unstructured storage and outgoing bandwidth. Costs for consumed resources are billed to
the owner of the hosting account, who can be an application provider, an application consumer, or both.

Deployment Application Models


Consumer-Managed Application Model
In the consumer-managed application model, a copy of the application is deployed into the consumer
account. The application consumer buys the application from the application provider via SAP Store. In
addition, the application consumer separately buys all required SAP HANA Cloud Platform resources (such as
compute units, storage or bandwidth) from the platform provider, that is SAP. All platform resources
consumed by the application are directly billed to the application consumer. The compute units hosting the
application are not shared between multiple application consumers. Instead, each application consumer runs
the application on dedicated compute units (VMs). In the consumer-managed application model, the
application consumer is responsible to operate the application.
Provider-Managed Application Model
In the provider-managed application model, the application is deployed into the provider account only. The
application provider may decide to start a dedicated compute unit for each consumer or to share one or
multiple compute units between them. The application is operated and maintained by the application
provider. Platform resources consumed by the application are billed to the application provider. The
application provider is responsible for passing the costs on to the consumers. Application providers can
define their own price model, which can be independent from the platform resources prices.
In the provider-managed deployment model, there is no deployment required into the consumer account.
Instead, consumers are "subscribed" to the provider application, once they have purchased the application.
As a result, a subscription for the purchased application is created in the consumer account. This subscription
enables consumers to launch the application, using a consumer specific URL, and configure it to their needs.

994

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Typically, the application consumer configures the used identity provider, the user roles for the application,
or, if required by the subscribed application, the connection parameters to another system.

Related Information
Providing Multitenant Applications to Tenants for Testing [page 1162]

1.5.2.6.2

Tenant Context API

Overview
In a provider-managed application scenario, each application consumer gets its own access URL for the provider
application. To be able to use an application with a consumer-specific URL, the consumer must be subscribed to
the provider application. When an application is launched via a consumer-specific URL, the tenant runtime is able
to identify the current consumer of the application. The tenant runtime provides an API to retrieve the current
application consumer. Each application consumer is identified by a unique ID which is called tenantId.
Since the information about the current consumer is extracted from the request URL, the tenant runtime can only
provide a tenant ID if the current thread has been started via an HTTP request. In case the current thread was not
started via an HTTP request (for example, a background process), the tenant context API only returns a tenant if
the current application instance has been started for a dedicated consumer. If the current application instance is
shared between multiple consumers and the thread was not started via an HTTP request, the tenant runtime
throws an exception.

Note
The tenant context API is of interest to application providers only.

Tenant Context API

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

995

Table 315:
API

Description

com.sap.cloud.account

The tenant context API provides the following methods:

getTenant - returns the tenant associated with the


current thread.

execute - executes callable.call() method on


behalf of the specified tenant and returns the result of a
called method.

getSubscribedTenants - returns all tenants sub


scribed to a calling application, or empty collection if
there are no subscribed tenants.

To find the tenant context API in your local SDK installation,


go to: <SDK_location>/javadoc/com/sap/cloud/

account
You can also access it at the following URL: https://
help.hana.ondemand.com/javadoc/index.html
com.sap.cloud.account

TenantContext

Tenant Context API via JNDI Lookup


To look up the TenantContext API via JNDI, follow the steps:
1. Add the following resource reference of type com.sap.cloud.account.TenantContext in your web.xml
file:
<resource-ref>
<res-ref-name>TenantContext</res-ref-name>
<res-type>com.sap.cloud.account.TenantContext</res-type>
</resource-ref>
2. Then, use the following code to look up:
Context ctx = new InitialContext();
TenantContext tenantctx = (TenantContext) ctx.lookup("java:comp/env/
TenantContext");

Tenant Context API via Resource Injection


To get an instance of the TenantContext API, use resource injection the following way:
@Resource
private TenantContext tenantContext;

Note
When you use WebSockets, the TenantId and AccountName parameters, provided by the TenantContext
API, are correct only during processing of WebSocket handshake request. This is because what follows after

996

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

the handshake does not conform to the HTTP protocol. In case TenantId and AccountName are needed
during next WebSocket requests, they should be stored into the HTTP session, and, if needed, you can use
TenantContext.execute(...) to operate on behalf of the relevant tenant.

Account API
The Account API provides methods to get account ID, account display name, and attributes. For more
information, see the Javadoc.
You can access the Account API in two ways.
Via looking up or injecting the TenantContext API:

Sample Code
Context ctx = new InitialContext();
TenantContext tenantctx = (TenantContext) ctx.lookup("java:comp/env/
TenantContext");
Account account = tenantctx.getTenant().getAccount();
Via the getSubscribedTenants method:

Sample Code
Context ctx = new InitialContext();
TenantContext tenantctx = (TenantContext) ctx.lookup("java:comp/env/
TenantContext");
Collection<Tenant> subscribedTenants = tenantctx.getSubscribedTenants();
foreach(Tenant tenant: subscribedTenants ) {
Account subscribedAccount = tenant.getAccount();
}

Related Information
Multitenant Applications [page 990]
Viewing the Default Trace [page 1115]
Providing Multitenant Applications to Tenants for Testing [page 1162]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

997

1.5.2.6.3

Multitenancy Tutorials

Below are listed tutorials describing end-to-end scenarios with multitenant demo applications:
Table 316:
If you want to

Tutorial

Create a general demo application (servlet)

Exemplary Provider Application (Servlet) [page 998]

Create a general demo application (JSP file)

Exemplary Provider Application (JSP) [page 1001]

Create a connectivity demo application

Creating a Multitenant Connectivity Application [page 1003]

Consume a connectivity demo application

Consuming a Multitenant Connectivity Application [page


1007]

1.5.2.6.3.1 Exemplary Provider Application (Servlet)


This tutorial explains how to create a sample application which makes use of the multitenancy concept. That is,
you can enable your application to be consumed by users, members of a tenant which is subscribed to this
application in a multitenant flavor.

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Tools for Java and SAP HANA SDK. For
more information, see Installing Java Tools for Eclipse and SDK [page 33].
You are an application provider. For more information, see Multitenancy Roles [page 993].

Procedure
1. Create a dynamic Web project
1. Open the Java EE perspective of the Eclipse IDE.
2. In the Project Explorer view, from the context menu, choose

New

Dynamic Web Project .

3. Enter TenantContextApp as the Project name.


4. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, we
choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

998

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Create a sample servlet


1. From the TenantContextApp context menu, choose

New

Servlet .

2. Enter tenantcontext.demo as the Java package and TenantContext as the Class name and choose Next.
3. In the URL mappings field, select /TenantContext and choose Edit.
4. In the Pattern field, replace the current value with just "/". In this way, the servlet will be mapped as a welcome
page for the application.

5. Choose Finish so that the TenantContext.java servlet is created and opened in the Java editor.
6. Go to /TenantContextApp/WebContent/WEB-INF and open the web.xml file.
7. Choose the Source tab page.
8. Add the following code block to the <web-app> element:
<resource-ref>
<res-ref-name>TenantContext</res-ref-name>
<res-type>com.sap.cloud.account.TenantContext</res-type>
</resource-ref>
9. Replace the entire servlet class with the following sample code:
package tenantcontext.demo;
import java.io.IOException;
import java.io.PrintWriter;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.cloud.account.TenantContext;
/**
* Servlet implementation class TenantContextServlet
*/
public class TenantContextServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* @see HttpServlet#HttpServlet()
*/
public TenantContextServlet() {
super();
}
/**
* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
response)
*/
protected void doGet(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
try {
InitialContext ctx = new InitialContext();
Context envCtx = (Context)ctx.lookup("java:comp/env");
TenantContext tenantContext = (TenantContext)
envCtx.lookup("TenantContext");

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

999

response.setContentType("text/html");
PrintWriter writer = response.getWriter();
writer.println("<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01
Transitional//EN\" \"http://www.w3.org/TR/html4/loose.dtd\">");
writer.println("<html>");
writer.println("<head>");
writer.println("<title>SAP HCP - Tenant Context Demo Application</
title>");
writer.println("</head>");
writer.println("<body>");
writer.println("<h2> Welcome to the SAP HANA Cloud Platform Tenant
Context demo application</h2>");
writer.println("<br></br>");
String currentTenantId = tenantContext.getTenant().getId();
writer.println("<p><font size=\"5\"> The application was accessed on
behalf of a tenant with an ID: <b>" + currentTenantId + "</b></font></p>");
writer.println("</body>");
writer.println("</html>");
} catch (Exception e) {
throw new ServletException(e.getCause());
}
}
/**
* @see HttpServlet#doPost(HttpServletRequest request, HttpServletResponse
response)
*/
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException {
doGet(req, resp);
}
}
10. Save the Java editor. The project compiles without errors.
You have successfully created a Web application containing a sample servlet and connectivity functionality.

3. Deploy the application


To learn how to deploy your application, see Deploying on the Cloud from Eclipse IDE [page 977].

Result
You have created a sample application that can be requested in a browser. Its output depends on the tenant
context.

Next Steps
To test the access to your multitenant application, go to a browser and request it on behalf of your account.
Use the following URL pattern: https://
<application_name><provider_account>.<landscape_host>/<application_path>

1000

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

If you want to test the access to your multitenant application on behalf of a consumer account, follow the
steps in page: Consuming a Multitenant Connectivity Application [page 1007]

Related Information
Developing Java Applications [page 964]
Multitenant Applications [page 990]

1.5.2.6.3.2 Exemplary Provider Application (JSP)


This tutorial explains how to create a sample application which makes use of the multitenancy concept. That is,
you can enable your application to be consumed by users, members of a tenant which is subscribed to this
application in a multitenant flavor.

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Tools for Java and SAP HANA SDK. For
more information, see Installing Java Tools for Eclipse and SDK [page 33].
You are an application provider. For more information, see Multitenancy Roles [page 993].

Procedure
1. Create a dynamic Web project
1. Open the Java EE perspective of the Eclipse IDE.
2. In the Project Explorer view, from the context menu, choose

New

Dynamic Web Project .

3. Enter TenantContextApp as the Project name.


4. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, we
choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1001

2. Add resource declaration in the Web deployment descriptor


1. Go to /TenantContextApp/WebContent/WEB-INF and open the web.xml file.
2. Choose the Source tab page.
3. Add the following code block to the <web-app> element:
<resource-ref>
<res-ref-name>TenantContext</res-ref-name>
<res-type>com.sap.cloud.account.TenantContext</res-type>
</resource-ref>

3. Create a sample JSP


1. Under the TenantContextApp project node, choose

New

JSP File

in the context menu.

2. Enter index.jsp as the File name and choose Finish.


3. Open the index.jsp file using the text editor.
4. Replace the entire JSP file content with the following sample code:
<%@page
import="javax.naming.InitialContext,javax.naming.Context,com.sap.cloud.account.Te
nantContext" %>
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://
www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>SAP HCP - Tenant Context Demo Application</title>
</head>
<body>
<h2> Welcome to the SAP HANA Cloud Platform Tenant Context demo application</h2>
<br></br>
<%
try {
InitialContext ctx = new InitialContext();
Context envCtx = (Context) ctx.lookup("java:comp/env");
TenantContext tenantContext = (TenantContext) envCtx
.lookup("TenantContext");
String currentTenantId = tenantContext.getTenant().getId();
out.println("<p><font size=\"5\"> The application was accessed on
behalf of a tenant with an ID: <b>"
+ currentTenantId + "</b></font></p>");
} catch (Exception e) {
out.println("error at client");
}
%>
</body>
</html>
5. Save the Java editor. The project compiles without errors.

1002

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Deploy the application


To learn how to deploy your application, see Deploying on the Cloud from Eclipse IDE [page 977].

Result
You have successfully created a Web application containing a JSP file and tenant context functionality.

Next Steps
To test the access to your multitenant application, go to a browser and request it on behalf of your account.
Use the following URL pattern: https://
<application_name><provider_account>.<landscape_host>/<application_path>
If you want to test the access to your multitenant application on behalf of a consumer account, follow the
steps in page: Consuming a Multitenant Connectivity Application [page 1007]

Related Information
Developing Java Applications [page 964]
Multitenant Applications [page 990]

1.5.2.6.3.3 Creating a Multitenant Connectivity Application

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Tools for Java and SAP HANA SDK. For
more information, see Installing Java Tools for Eclipse and SDK [page 33].
You are an application provider. For more information, see Multitenancy Roles [page 993].

Context
This tutorial explains how you can create a sample application which is based on the multitenancy concept, makes
use of the connectivity service, and can be later consumed by other users. That means, you can enable your

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1003

application to be consumed by users, members of a tenant which is subscribed for this application in a
multitenant flavor. The output of the application you are about to create, displays a welcome page showing the
URI of the tenant-specific destination configuration. This means that the administrator of the consumer account
may have been previously set a tenant-specific configuration for this application. However, in case such
configuration has not been set, the application would use the default one, set by the administrator of the provider
account.
The application code is the same as for a standard HelloWorld consuming the connectivity service as the latter
manages the multitenancy with no additional actions required by you. The users of the consumer account, which
is subscribed to this application, can access the application using a tenant-specific URL. This would lead the
application to use a tenant-specific destination configuration. For more information, see Multitenancy in the
Connectivity Service [page 419].

Note
As a provider, you can set your destination configuration on application and account level. They are the default
destination configurations in case a consumer has not configured tenant-specific destination configuration (on
subscription level).

Procedure
1. Create a dynamic Web project
1. Open the Java EE perspective of the Eclipse IDE.
2. In the Project Explorer view, from the context menu, choose

New

Dynamic Web Project .

3. Enter MultitenantConnectivity as the Project name.


4. In the Target Runtime pane, select the runtime you want to use to deploy the application. In this tutorial, we
choose Java Web.
5. In the Configuration pane, leave the default configuration.
6. Choose Finish to finalize the creation of your project.

2. Add resource declaration in file "Web deployment descriptor"


1. Go to /MultitenantConnectivity/WebContent/WEB-INF and open the web.xml file.
2. Choose the Source tab page.
3. Add the following code block to the <web-app> element:
<resource-ref>
<res-ref-name>search_engine_destination</res-ref-name>
<res-type>com.sap.core.connectivity.api.http.HttpDestination</res-type>
</resource-ref>

1004

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Create a sample JSP file


1. Under the MultitenantConnectivity project node, choose

New

JSP File

in the context menu.

2. Enter index.jsp as the File name and choose Finish.


3. Open the index.jsp file using the text editor.
4. Replace the entire JSP file content with the following sample code:
<%@page
import="javax.naming.InitialContext,javax.naming.Context,com.sap.core.connectivit
y.api.http.HttpDestination,java.util.Arrays"%>
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://
www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>SAP Hana Cloud Platform - Multitenant Connectivity Demo Application</
title>
</head>
<body>
<h2>Welcome to SAP Hana Cloud Platform - multitenant connectivity demo
application</h2>
<br></br>
<%
try {
Context context = (Context) new InitialContext()
.lookup("java:comp/env");
// In this case you don't need to explicitly use the TenantContext
API
// because the Connectivity service handles the tenancy by itself.
// The retrieved HttpDestination object will be tenant-specific.
String destinationName = "search_engine_destination";
HttpDestination destination = (HttpDestination) context
.lookup(destinationName);
out.println("<p><font size=\"5\"> Retreived destination with name
<i>"
+ destination.getName()
+ "</i> and URI <b>"
+ destination.getURI() + "</b></font></p>");
} catch (Exception e) {
out.println("<b>An exception has been thrown: <i>" + e.getMessage()
+ "</i></b>");
out.println(Arrays.toString(e.getStackTrace()));
}
%>
</body>
</html>
5. Save the JSP file.
The project compiles without errors.
You have successfully created a Web application containing a sample JSP file and consuming the connectivity
service via looking up a destination configuration.

4. Deploy the application


To learn how to deploy your application, see Deploying on the Cloud from Eclipse IDE [page 977].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1005

5. Define the destination configurations


You, as application provider, can configure a default destination, which is then used at runtime when the
application is requested in the context of the provider account. In this case, the URL used to access the
application is not tenant-specific.
Example:
Name=search_engine_destination
URL=https://www.google.com
Type=HTTP
ProxyType=Internet
Authentication=NoAuthentication
TrustAll=true
For more information on how to define a destination for provider account, see:
Configuring Destinations from the Console Client [page 283].
Configuring Destinations from the Cockpit [page 301]

Result
You have created a sample application which can be requested in a browser. Its output depends on the tenant
name.

Next Steps
To test the access to your multitenant application, go to a browser and request it on behalf of your account.
Use the following URL pattern: https://
<application_name><provider_account>.<landscape_host>/<application_path>
If you want to test the access to your multitenant application on behalf of a consumer account, follow the
steps in page: Consuming a Multitenant Connectivity Application [page 1007]

Related Information
Uploading Destinations [page 285]
Creating a HelloWorld Application [page 47]
Multitenant Applications [page 990]

1006

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.2.6.3.4 Consuming a Multitenant Connectivity Application

Prerequisites
Your SAP HANA Cloud Platform user is a member of an account.
You are subscribed to a provider application, hosted by a provider account. For more information, see
Multitenancy Roles [page 993] and Subscribing an Account to an Application [page 1162].

Note
This tutorial assumes that your account is subscribed to the following exemplary application (deployed in a
provider account): Creating a Multitenant Connectivity Application [page 1003]

Context
This tutorial explains how you can consume a sample connectivity application based on the multitenancy concept.
That is, you are a member of an account which is subscribed for applications provided by other accounts. The
output of the application you are about to consume, displays a welcome page showing the URI of the tenantspecific destination configuration. This means that the administrator of your consumer account may have been
previously set a tenant-specific configuration for this application. However, in case such configuration has not
been set, the application would use a default one, set by the administrator of the provider account.
Users of a consumer account, which is subscribed to an application, can access the application using a tenantspecific URL. This would lead the application to use a tenant-specific destination configuration. For more
information, see Multitenancy in the Connectivity Service [page 419].

Note
As a consumer, you can set a tenant-specific destination configuration on subscription level.

Procedure
1. Define destination configuration
You can consume a provider application if your account is subscribed to it. In this case, administrators of your
consumer account can configure a tenant-specific destination configuration, which can later be used by the
provider application.
To illustrate the tenant-specific consumption, the URL used in this example is diferent from the one in the
exemplary provider application tutorial.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1007

Example:
Name=search_engine_destination
URL=http://www.yahoo.com
Type=HTTP
ProxyType=Internet
Authentication=NoAuthentication
TrustAll=true

Tip
The destination name depends on the provider application.
For more information on how to configure a destination for provider account, see:
Configuring Destinations from the Console Client [page 283].
Configuring Destinations from the Cockpit [page 301]

2. Access the application


Go to a browser and request the application on behalf of your account. Use the following URL pattern:
https://<application_name><provider_account>-<consumer_account>.<landscape_host>/
<application_path>

Result
The application is requested in a browser. Its output is relevant to your tenant-specific destination configuration.

Related Information
Creating a Multitenant Connectivity Application [page 1003]
Configuring Destinations from the Console Client [page 283]
Configuring Destinations from the Eclipse IDE [page 290]
Configuring Destinations from the Cockpit [page 301]

1.5.3 SAP HANA: Development


With SAP HANA Cloud Platform, you can use the SAP HANA development tools to create comprehensive
analytical models and build applications with SAP HANA's programmatic interfaces and integrated development
environment.
Benefits and advantages

1008

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Automatic backups
Creation of SAP HANA schemas and repository packages. Your SAP HANA instances and XS applications are
visualized in the cockpit.
Eclipse-based tools for connecting to your SAP HANA instances on SAP HANA Cloud Platform
Eclipse-based tools for data modeling
Appropriate for
Implementing highly intensive calculation scenarios
Building analytic models
Implementing big data scenarios
Implementing Internet of Things scenarios
Building XS applications
Using SAP HANA embedded search capabilities
Leveraging SAP HANA functional libraries like SAP HANA Business Function Library (BFL) and the SAP HANA
Predictive Analytics Library (PAL)
Developing hybrid applications (native HANA, Java, HTML5, mobile)
Not appropriate for
Applications requiring OS-level access

Related Information
SAP HANA: Getting Started [page 57]
Using a Productive SAP HANA Database System [page 1010]

1.5.3.1

Launching SAP HANA XS Applications

You can open your SAP HANA XS applications in a Web browser directly from the cockpit.

Procedure
1. Log on to the cockpit, select an account and choose

Applications

HANA XS Applications .

2. In the HANA XS Applications table, click the application URL link to launch the application.

Note
If an HTTP status 404 (not found) error is shown, bear in mind that the cockpit displays only the root of an
applications URL path. This means that you might have to either:
Add the application name to the URL address in the browser, for example, hello.xsjs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1009

Use an index.html file, which is the default setting for the file displayed when the package is
accessed without specifying a file name in the URL.
Override the above default setting by specifying the default_file keyword in the .xsaccess file, for
example:
{
"exposed" : true,
"default_file": "hello.xsjs"
}

Related Information
Cockpit [page 84]

1.5.3.2

Using a Productive SAP HANA Database System

SAP HANA Cloud Platform provides SAP HANA database systems designed for developing with SAP HANA in a
productive environment.

Prerequisites
You have an account on the productive landscape. For more information, see Purchasing a Customer Account
[page 16].

Performance/Scalability Recommendation
Before going live with an application for which a significant number of users and/or significant load is expected,
you should do a performance load test. This is best practice in the industry and we strongly recommend it for
HANA XS applications.

Administrative Database Users


SAP HANA Cloud Platform creates four users that it requires to manage the database: SYSTEM, BKPMON,
CERTADM, and PSADBA. These users are reserved for use by SAP HANA Cloud Platform.

Caution
Do not delete or deactivate these users or change their passwords.

1010

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Technical Database User


Each productive SAP HANA database system has a technical database user NEO_<guid>, which is created
automatically when the database system is assigned to an account. A technical database user is not the same as a
normal database user and is provided purely as a mechanism for enabling schema access.

Caution
Take care not to delete or change the technical database user in any way (password, roles, permissions, and so
on).

Features
A productive SAP HANA database system provides you with a database system reserved for your exclusive use,
allowing you to work with SAP HANA as with an on-premise system. You have full control of user management
and can use a range of tools. There are some obvious restrictions, such as no access to the operating system. See
the overview below for details about available features:
Table 317:
Feature

Description

Database users

Specifics for SAP HANA Cloud Platform:

User management

Guidelines for Creating Database Users [page 1013]

Creating a Database Administrator User [page 1014]

You have full administration privileges to manage users


See:

Web-based tools

Managing SAP HANA Users

Setting Up Roles and Authorizations

SAP HANA User and Role Management

SAP HANA Web-based Development Workbench

SAP HANA XS Administration Tool

See:

Eclipse

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Supported SAP HANA Web-based Tools [page 1015]

Roles Required for Web-based Tools [page 1017]

Developing Applications in Web-based Environments

SAP HANA XS Administration Tools

Installing SAP HANA Tools for Eclipse [page 58]

Connecting to SAP HANA Databases via the Eclipse IDE [page 861]

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1011

Feature

Description

Security

Choice of authentication method


See:

Connectivity destinations

Monitoring

Configuring SAML 2.0 Authentication [page 1022]

SAP HANA XS Administration Tools

Connectivity for SAP HANA XS (Productive) [page 424]

Maintaining HTTP Destinations

Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page
1017]

Debugging

SAP HANA Web-based Development Workbench


See: Debugging with SAP HANA Web-based Development Workbench [page 1021]

Launch SAP HANA XS applica

Supported by the SAP HANA Tools plugin for Eclipse as of release 7.4.

Launching SAP HANA XS Applications [page 1009]

tions
Installing SAP HANA solutions
Java development

bind-hana-dbms [page 104]

Note
For security reasons, some of the configuration properties of the SAP HANA database systems running on the
productive landscape are forbidden for configuration.

Related Information
SAP HANA Developer Guide (PDF)
SAP HANA Administration Guide (PDF)
SAP HANA Security Guide (PDF)

1012

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.3.2.1

Guidelines for Creating Database Users

As an account administrator on SAP HANA Cloud Platform, you are able to create your own SAP HANA database
user and, following this, set up user accounts in SAP HANA for the members of your development team.

Create an SAP HANA Administrator User


Create your own SAP HANA database user using the database user feature in the cockpit. For more information,
see Creating a Database Administrator User [page 1014].
You will be assigned a database user with extensive rights, including system administration and monitoring. The
user ID is identical to your SCN user, and the password shown is an initial password and must be changed when
you log onto an SAP HANA system for the first time. You are responsible for choosing a strong password and
keeping it secure.
Your database user is initially assigned a minimal set of roles, which includes HCP_PUBLIC, HCP_SYSTEM, and
PUBLIC. The HCP_SYSTEM role contains the USER ADMIN and ROLE ADMIN system privileges, allowing you to
create database users and grant additional roles to your own and other database users.

Note
The initial set of roles also contains the sap.hana.xs.ide.roles::Developer role, allowing you to work with the SAP
HANA Web-based Development Workbench, but not the SAP HANA XS Administration tool.
To be able to work with the SAP HANA XS Administration Tool (https://
<schema><account>.<host>sap/hana/xs/admin/), you require the relevant sap.hana.xs.admin.roles.
These are not included in the initial set of roles, however. You can assign these roles to yourself as follows:
1. Log on in with your user to one of the following tools:
Use the Eclipse IDE and connect to your SAP HANA studio. For more information, see Connecting to
SAP HANA Databases via the Eclipse IDE [page 861].
Use the SAP HANA Web-based Development Workbench. For more information, see Supported SAP
HANA Web-based Tools [page 1015].
2. Assign the set of roles to yourself in the Security section.
For more information, see Roles Required for Web-based Tools [page 1017].

Note
There may be some roles that you cannot assign to your own database user. In this case, we recommend that
you create a second database user (for example, ROLE_GRANTOR) and assign it the HCP_SYSTEM role. Then
log onto the SAP HANA system with that user and grant your database user the roles you require.

Assign Members to Your Account


Open the cockpit on the productive landscape and assign the required development team members to your
account. For more information, see Managing Members [page 23].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1013

Set Up Database Users for Account Members


In the SAP HANA system, create database users for the members of your account and assign them the required
developer roles. For more information, see the following:
Managing SAP HANA Users
Setting Up Roles and Authorizations

Related Information
Roles Required for Web-based Tools [page 1017]

1.5.3.2.2

Creating a Database Administrator User

As an account administrator, you can use the database user feature provided in the cockpit to create your own
database user for your SAP HANA database.

Procedure
1. Log on to the cockpit on the productive landscape and select an account.
2. Choose

Persistence

Database Systems

in the navigation area.

All database systems available in the account are listed with their details, including the database type, version,
memory size, state, and the number of associated databases.
3. To select a database system, in the list, click the link on its name.
The overview of the database system shows details, including the database version and state, and the number
of associated databases.
4. Choose Databases in the navigation area.
5. To go to the overview for a database, click the link on its name.
6. In the Development Tools section, click Database User.
A message confirms that you do not yet have a database user.
7. Choose Create User.
Your user (identical to your SCN user) and initial password are displayed. Change the initial password when
you first log on to an SAP HANA system, for example the SAP HANA Web-based Development Workbench.

Note
Your database user is assigned a set of permissions for administering the HANA database system
including user and role administration. For security reasons, only the role that provides access to the SAP
HANA Web-based Development Workbench is assigned as default. To be able to use other HANA tools like

1014

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

HANA Cockpit or HANA XS Administration tool, you must assign yourself access to these before you can
start using them.
8. To log on to the SAP HANA Web-based Development Workbench and change your initial password now
(recommended), copy your initial password and then close the dialog box.
You do not have to change your initial password immediately. You can open the dialog box again later to
display both your database user and initial password. Since this poses a potential security risk, however, you
are strongly advised to change your password as soon as possible.
9. In the Development Tools section, click SAP HANA Web-based Development Workbench.
10. On the SAP HANA logon screen, enter your database user and initial password.
11. Change your password when prompted. You are responsible for choosing a strong password and keeping it
secure. SAP cannot provide forgotten passwords.

Next Steps
In the SAP HANA system, you can now create database users for the members of your account and assign them
the required developer roles.

Related Information
Roles Required for Web-based Tools [page 1017]
Managing SAP HANA Users
Setting Up Roles and Authorizations
Creating an SAP HANA Database from the Cockpit [page 757]

1.5.3.2.3

Supported SAP HANA Web-based Tools

SAP HANA Cloud Platform supports the following Web-based tools: SAP HANA Web-based Development
Workbench, and SAP HANA XS Administration Tool.

Prerequisites
You have a database user. See Guidelines for Creating Database Users [page 1013].
Your database user is assigned the roles required for the relevant tool. See Roles Required for Web-based
Tools [page 1017].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1015

Context
You can access the SAP HANA Web-based tools using the Cockpit or the tool URLs. The following table
summarizes what each supported tool does, and how to acess it.
Table 318: Supported Web-Based Tools for SAP HANA Development and Administration
Tool

Description

Where to Find It in the Cock

Tool URL

pit
SAP HANA Web-based Devel

Includes an all-purpose editor

Development Tools section:

https://<database

opment Workbench

tool that enables you to main

SAP HANA Web-based

instance><account>.<

tain and run design-time ob

Development Workbench

host>/sap/

jects in the SAP HANA reposi

hana/xs/ide/

tory. It does not support mod


eling activities.
See SAP HANA Developer
Guide: SAP HANA Web-Based
Development Workbench
SAP HANA XS Administration

Allows you, for example, to

Administration Tools section:

https://<database

Tool

configure security options

SAP HANA XS Administration

instance><account>.<

and HTTP destinations.

host>/sap/hana/xs/

See SAP HANA Administra

admin/

tion Guide

Remember
When using the tools, log on with your database user (not your SAP HANA Cloud Platform user). If this is your
initial logon, you will be prompted to change your password. You are responsible for choosing a strong
password and keeping it secure.

Related Information
Developing Applications in Web-based Environments
SAP HANA XS Administration Tools
Debugging with SAP HANA Web-based Development Workbench [page 1021]

1016

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.3.2.4

Roles Required for Web-based Tools

To use the SAP HANA Web-based tools, you require specific roles.
Table 319:
Role

Description
SAP HANA Web-based Development Workbench

sap.hana.xs.ide.roles::EditorDeveloper or parent
role sap.hana.xs.ide.roles::Developer

Use the Editor component of the SAP HANA Web-based Development


Workbench.

sap.hana.xs.debugger::Debugger

Debug server-side JavaScript code


SAP HANA XS Administration Tool

sap.hana.xs.admin.roles::HTTPDestViewer

View HTTP destinations.

sap.hana.xs.admin.roles::HTTPDestAdministrator

Full access to HTTP destination configurations (display and edit).

sap.hana.xs.admin.roles::TrustStoreViewer

Read-only access to the trust store, which contains the server's root cer
tificate or the certificate of the certification authority that signed the
servers certificate.

sap.hana.xs.admin.roles::TrustStoreAdministrator

Full access to the SAP HANA XS application trust store to manage the
certificates required to start SAP HANA XS applications.

Related Information
Supported SAP HANA Web-based Tools [page 1015]
SAP HANA Administration Guide

1.5.3.2.5

Configuring Availability Checks for SAP HANA XS


Applications from the Cockpit

In the cockpit, you can configure availability checks for the SAP HANA XS applications running on your productive
SAP HANA database system.

Procedure
1. In the cockpit, choose Applications HANA XS Applications in the navigation area of the account and
open the application list of the productive SAP HANA database system.
2. Select an application from the list and in the Application Details panel choose Create Availability Check.
3. In the dialog that appears, select the URL you want to monitor from the dropdown list and fill in values for
warning and critical thresholds if you want them to be different from the default ones. Choose Save.
Your availability check is created. You can view your application's latest HTTP response code and response
time as well as status icon showing whether your application is up or down. If you want to receive alerts when

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1017

your application is down, you need to configure alert recipients from the console client. For more information,
see the Subscribe recipients to notification alerts. step in Configuring Availability Checks for SAP HANA XS
Applications from the Console Client [page 1018].

Related Information
Browser Support [page 8]
Cockpit [page 84]
Availability Checks [page 1151]
Configuring Availability Checks for SAP HANA XS Applications from the Console Client [page 1018]

1.5.3.2.6

Configuring Availability Checks for SAP HANA XS


Applications from the Console Client

In the console client you can configure an availability check for your SAP HANA XS application and subscribe
recipients to receive alert e-mail notifications when it is down or responds slowly.

Prerequisites
You have a productive SAP HANA database on the platform.
For more information, see Using a Productive SAP HANA Database System [page 1010].
You have set up the console client.
For more information, see Setting Up the Console Client [page 42].

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Create the availability check.
Execute:
neo create-availability-check -a myaccount -b myhana:myhanaxsapp -u myuser -U /
heartbeat.xsjs -C 6 -W 4 --host hana.ondemand.com
Replace "myaccount", "myhana:myhanaxsapp" and "myuser" with the names of your account,
productive SAP HANA database name and application, and user respectively.
The availability URL (/heartbeat.xsjs in this case) is not provided by default by the platform. Replace it
with a suitable URL that is already exposed by your SAP HANA XS application or create it. Keep in mind
the limitations for availability URLs. For more information, see Availability Checks [page 1151].

1018

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Note
In case you want to create an availability check for a protected SAP HANA XS application, you need to
create a sub-package, in which to create an .xsaccess file with the following content:
{

"exposed": true,
"authentication": null,
"authorization": null

In the SAP HANA XS Administration Tool (https://<productive SAP HANA


name><account>.<host>/sap/hana/xs/admin/), find the sub-package and activate public access to
it. After this, you will be able to monitor the resources on and under the sub-package level, that is, you
will be able to create an availability check for your protected application. Note that in the availability
URL, you have to provide the path to the resource in the sub-package that you will be monitoring, for
example /heartbeat.xsjs.
The check will trigger warnings "-W 4" if the response time is above 4 seconds and critical alerts "-C 6" if
the response time is above 6 seconds or the application is not available.
Use the respective landscape host for your account type.
3. Subscribe recipients to notification alerts.
Execute:
neo set-alert-recipients -a myaccount -b myhana:myhanaxsapp -u myuser -e
alert_recipients@example.com --host hana.ondemand.com
Replace "myaccount", "myhana" and "myuser" with the names of your account, productive SAP HANA
database name, and user respectively.
Replace "alert-recipients@example.com" with the email addresses that you want to receive alerts.
Separate email addresses with commas. We recommend that you use distribution lists rather than
personal email addresses. Keep in mind that you will remain responsible for handling of personal email
addresses with respect to data privacy regulations applicable.
Use the respective landscape host for your account type.

Note
Setting an alert recipient for an application will trigger sending all alerts for this application to the
configured email(s). Once the recipients are subscribed, you do not need to subscribe them again after
every new check you configure. You can also set the recipients on account level if you skip the -b
parameter so that they receive alerts for all applications and for all the metrics you are monitoring.

Related Information
Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page 1017]
Landscape Hosts [page 32]
Availability Checks Commands
list-availability-check [page 186]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1019

create-availability-check [page 113]


delete-availability-check [page 126]
Alert Recipients Commands
list-alert-recipients [page 188]
set-alert-recipients [page 227]
clear-alert-recipients [page 107]

1.5.3.2.7

Viewing Monitoring Metrics of a Database System

In the cockpit, you can view the current metrics of a selected database system to get information about its health
state. You can also view the metrics history of a productive database to examine the performance trends of your
database over different intervals of time or investigate the reasons that have led to problems with it. You can view
the metrics for all types of databases.

Procedure
1. In the cockpit, navigate to the Database Systems page either by choosing Persistence from the navigation
area or from the Overview page.
All database systems available in the selected account are listed with their details, including the database
version and state, and the number of associated databases.
2. Select the entry for the relevant database system in the list.
3. Choose Monitoring from the navigation area to get detailed information about the current state and the
history of metrics for a selected productive database system.
The Current Metrics panel shows the current state of the metrics for the selected database system. When a
threshold is reached, the metric health status changes to warning or critical.
The Metrics History panel shows the metrics history of your database. You can view the graphics of the
different metrics and zoom in when you click and drag horizontally or vertically to get further details. If you
zoom in a graphic horizontally, all other graphics zoom in to the same level of details too. You can press
Shift and then drag to scroll all graphics simultaneously to the left or right. You can zoom out to the initial
state with a double-click.
You can select different time intervals for viewing the metrics. Depending on the selected interval, data is
aggregated as follows:
last 12 or 24 hours - data is collected each minute
last 7 days - data is aggregated from the average values for 10 minutes
last 30 days - data is aggregated from the average values for an hour
You can also select a custom time interval when you are viewing the history of metrics. Note that if you select
an interval in which the database has not been running, the graphics will not contain any data.

1020

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Browser Support [page 8]
Cockpit [page 84]

1.5.3.2.8

Debugging with SAP HANA Web-based


Development Workbench

You can only debug SAP HANA server-side JavaScript with the SAP HANA Tools plugin for Eclipse as of release
7.4. If you are working with lower plugin versions, use the SAP HANA Web-based Development Workbench to
perform your debugging tasks.

Prerequisites
Your database user is assigned the sap.hana.xs.debugger::Debugger role.
You have enabled debugging in the SAP HANA studio. Note that to do the following, you require the
sap.hana.xs.lm.roles::Administrator role:
1. Switch to the Administration Console perspective.
2. Double-click your system.
3. Switch to the Configuration tab.
4. Set the following parameter: xsengine.ini debugger enabled=true . If the debugger section is not
already present, create it and add the parameter enabled. Assign the value true to the enabled
parameter.

Procedure
1. Log onto the cockpit on the production landscape and choose

Applications

HANA XS Applications .

Note
We recommend that you use the Google Chrome browser.
2. In the HANA XS Applications table, select the application to display its details.
3. In the Application Details section, click Open in Web-based Development Workbench. Note that the SAP HANA
Web-based Development Workbench can also be opened directly at the following URL: https://<database
instance><account>.<host>/sap/hana/xs/ide/
4. Depending on whether you want to debug a .xsjs file or a more complex scenario (set a breakpoint in
a .xsjs file and run another file), do the following:
.xsjs file:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1021

1. Set the breakpoints and then choose the Run on server (F8) button.
Complex scenario:
1. Set the breakpoint in the .xsjs file you want to debug.
2. Open a new tab in the browser and then open the other file on this tab by entering its URL (https://
<database instance><account>.<host>/<package>/<file>).

Note
If you synchronously call the .xsjs file in which you have set a breakpoint and then open the other file
in the SAP HANA Web-based Development Workbench and execute it by choosing the Run on server
(F8) button, you will block your debugging session. You will then need to terminate the session by
closing the SAP HANA Web-based Development Workbench tab.

Note
If you leave your debugging session idle for some time once you have started debugging, your session will
time out. An error in the WebSocket connection to the backend will be reported and your WebSocket
connection for debugging will be closed. If this occurs, reopen the SAP HANA Web-based Development
Workbench and start another debugging session.

1.5.3.2.9

Configuring SAML 2.0 Authentication

Valid for SAP HANA instances running SP8 or lower only. Use this procedure to configure your HANA XS
applications to use Security Assertion Markup Language (SAML) 2.0 authentication. This is necessary if you want
to implement identity federation with your corporate identity providers.

Prerequisites
You have the SAP HANA Tools installed in your Eclipse IDE. See Installing SAP HANA Tools for Eclipse [page
58].
You have a user on the productive landscape of SAP HANA Cloud Platform. See Purchasing a Customer
Account [page 16]
You have a SAP HANA database user on the productive landscape of SAP HANA Cloud Platform. See Creating
a Database Administrator User [page 1014].
You have a corporate identity provider (IdP) configured with its own trust settings (key pair and certificates).
See the identity provider vendors documentation for more information.

Note
To establish successful trust with SAP HANA XS Engine on SAP HANA Cloud Platform, the identity
provider must have the following features:
Supports unsigned SAML requests
Sends its signing certificate when sending a SAML response

1022

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You have a SAP HANA XS engine configured with its key pair and certificates. See the SAP HANA
Administration Guide.

Context
Restriction
This procedure is valid for productive HANA instances running SAP HANA SP8 or lower. For SAP HANA SP9
instances, see:
Configure SSO with SAML Authentication for SAP HANA XS Applications section in the SAP HANA
Administration Guide.
Use SAML to enable SSO for your SAP HANA XS App (SPS 09 rev 92 or later)
Use this procedure to configure your HANA XS applications to use Security Assertion Markup Language (SAML)
2.0 authentication. This is necessary if you want to implement identity federation with your corporate identity
providers. See Identity and Access Management [page 1205].

1. Upload the Certificates


Procedure
1. Download the identity provider metadata. See the identity provider vendors documentation for more
information.
2. Store the IdP signing certificate in a valid PEM or DER file, enclosing the certificate content in -----BEGIN
CERTIFICATE----- and -----END CERTIFICATE-----.
3. Upload the PEM or DER file to SAP HANA Cloud Platform using the upload-hanaxs-certificates
command.
neo upload-hanaxs-certificates --host hana.ondemand.com --account myacc -application myapp --user mymail@example.com --location C:\Certificates\myCert.pem
See upload-hanaxs-certificates [page 258].

Tip
: If you get an error message while uploading the certificates, try to fix the problem using the reconcilehanaxs-certificates command. See reconcile-hanaxs-certificates [page 213]
4. Restart the SAP HANA XS service so the upload takes effect. This is done using the restart-hana console
command.
neo restart-hana --service-name xsengine --id myhanaid --account myaccount -host hana.ondemand.com --user mymail@example.com
See restart-hana [page 220].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1023

5. List the available HANA XS certificates to check if the certificates were uploaded successfully. This is done
using the list-hanaxs-certificates command.
neo list-hanaxs-certificates --host hana.ondemand.com --account myaccount -application myapp --user mymail@example.com --contained-strng John Doe
See list-hanaxs-certificates [page 196].

2. Configure Trust on SAP HANA Cloud Platform


Procedure
1. Open SAP HANA studio.
2. Connect to the SAP HANA instance.
3. Grant your database user the following roles:
sap.hana.xs.admin.roles::HTTPDestAdministrator
sap.hana.xs.admin.roles::HTTPDestViewer
sap.hana.xs.admin.roles::RuntimeConfAdministrator
sap.hana.xs.admin.roles::RuntimeConfViewer
sap.hana.xs.admin.roles::SAMLAdministrator
sap.hana.xs.admin.roles::SAMLViewer
4. Open the SQL Console and execute the following set of statements:
a. To create the SAML 2.0 identity provider:
CREATE SAML PROVIDER <idp name> WITH SUBJECT '<certificate subject>' ISSUER
'<certificate issuer>' ENABLE USER CREATION;

Tip
Get the certificate subject and issuer from the IdP certificate. If you dont have direct access to the
certificate, use a proper file viewer tool to view the certificate contents from the PEM or DER file.

Note
With this statement, you also enable the automatic user creation of a corresponding SAP HANA
database user at first login. Otherwise, you will have to do it manually if such does not exist. See the
SAP HANA Administration Guide.
b. To create a destination:
insert into _SYS_XS.HTTP_DESTINATIONS values('sap.hana.xs.samlProviders',
'<uppercase idp name>', '<idp description>', '<idp host>', <idp port>, '<path
prefix>', <use proxy>, '<proxy host>', <proxy port>, 0, <use SSL>, <timeout>,
'', '');

1024

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Parameter

Description and Values

<uppercase idp name>

Create a short name for this IdP in uppercase.

<idp description>

A free-text description.

<idp host>

The IdP host.

<idp port>

The IdP port.

<path prefix>

A path prefix to be used for all endpoint URLs.

<use proxy>

Values:

1 - Yes

0 - No

<proxy host>

The proxy host. Empty string if none.

<proxy port>

The proxy port.

<use SSL>

Defines if the communication will be over HTTP(S).


Values:

<timeout>

0 - use HTTP

1 - use HTTPS

The timeout in milliseconds. If the value is -1, then the


timeout is infinite.

insert into _SYS_XS.HTTP_DESTINATIONS values('sap.hana.xs.samlProviders',


'NOVO1', 'desc', 'idp4neo.dhcp.sofl.sap.corp', 443, '', 0, '', 0, 0, 1, -1,
'', '');
c. To configure the SAML 2.0 identity providers endpoints and bindings:
Configuration

SQL Statement

Example

SSO Redirect binding

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('<uppercase
idp name>', 0, 0,
'sap.hana.xs.samlProvider
s', '<uppercase idp
name>', '<SSO redirect
endpoint URL>');

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('NOVO1', 0, 0,
'sap.hana.xs.samlProvider
s', 'NOVO1', '/
saml2/idp/sso/novo');

SSO POST binding

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('<uppercase
idp name>', 0, 1,
'sap.hana.xs.samlProvider
s', '<uppercase idp
name>', '<SSO POST
endpoint URL>);

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('NOVO1', 0, 1,
'sap.hana.xs.samlProvider
s', 'NOVO1', '/
saml2/idp/sso/novo');

SLO Redirect binding

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('<uppercase
idp name>', 1, 0,

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('NOVO1', 1, 0,
'sap.hana.xs.samlProvider

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1025

Configuration

SLO POST binding

SQL Statement

Example

'sap.hana.xs.samlProvider
s', '<uppercase idp
name>', '<SLO redirect
endpoint URL>');

s', 'NOVO1', '/


saml2/idp/slo/novo');

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('<uppercase
idp name>', 1, 1,
'sap.hana.xs.samlProvider
s', '<uppercase idp
name>', '<SLO POST
endpoint URL>');

insert into
_SYS_XS.SAML_PROVIDER_CON
FIG values('NOVO1', 1, 1,
'sap.hana.xs.samlProvider
s', 'NOVO1', '/
saml2/idp/slo/novo');

Note
You need to configure all four endpoints, executing all four statements.

5. Open the SAP HANA XS Administation tool (see SAP HANA Administration Guide). For the required
applications, configure SAML authentication to be using this identity provider:
a. Select the application.
b. Go to the SAML section.
c. Choose Identity Provider and set this identity provider as value.

3. Configure Trust on the Identity Provider Side


Procedure
1. Download the SAP HANA service provider metadata from the following URL:
https://<SAP HANA url>/sap/hana/xs/saml/info.xscfunc

Tip
You can get the SAP HANA URL from the HANA XS Applications section in the cockpit.
2. Import the SAP HANA service provider metadata in the identity provider. See the identity provider vendors
documentation for more information.

1026

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Test
Open the required application and check if SAML authentication with the required identity provider works. You
should be redirected to the identity provider and prompted to log in. After successful login, you are shown the
application.

1.5.3.2.10 Assigning Trust Stores to HTTP Destinations


To be able to call SAP HANA Cloud Platform services from SAP HANA XS applications, you need to assign a
predefined trust store to the HTTP destination that defines the connection details for a specific service. The trust
store contains the certificate required to authenticate the calling application.

Prerequisites
In the SAP HANA repository, you have created the HTTP destination (.xshttpdest file) to the service to be
called. The file must have the .xshttpdest extension and be located in the same package as the application that
uses it or in one of the application's subpackages.

Procedure
1. Log on to the cockpit and choose

Applications

HANA XS Applications .

2. In the HANA XS Applications screen, select the relevant application.


The Application Details section lists all destinations created for the selected application, together with the
subpackage name if the destination file is contained in a subpackage.
3. Select the relevant destination and choose Assign Trust Store.
4. In the dialog box, select the DEFAULT trust store from the dropdown box and save your entry. Note that
DEFAULT specifies a predefined trust store containing the certificate required by SAP HANA XS applications.

Related Information
Maintaining HTTP Destinations

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1027

1.5.3.3

Using a Trial SAP HANA Instance

SAP HANA Cloud Platform provides the option to create and use SAP HANA databases in a trial environment.

SAP HANA Multitenant Database Containers (Beta)


You can use SAP HANA multitenant database containers (MDC, tenant database) on the trial landscape. Creating
trial SAP HANA instances is no longer possible because the support for the trial SAP HANA instances has ended.
You can continue to use the existing trial SAP HANA instances for a limited period of time.
For more information about using tenant databases in the trial landscape, see Databases and Database Systems
[page 770].

Note
You should not use SAP HANA Cloud Platform beta features in productive accounts, as any productive use of
the beta functionality is at the customer's own risk, and SAP shall not be liable for errors or damages caused by
the use of beta features.

Related Information
Databases and Database Systems [page 770]
Creating SAP HANA MDC Databases [page 784]

1.5.3.4

Working with SAP HANA Smart Data Streaming

SAP HANA Cloud Platform, smart data streaming is an SAP HANA service that provides the ability to build
applications that process streams of incoming event data in real time, and to collect and act on incoming
information.
Smart data streaming is ideally suited for situations where data arrives as events happen, and where there is value
in collecting, understanding, and acting on this data right away. Some examples of data sources that produce
streams of events in real time include:
Sensors
Smart devices
Web sites (click streams)
IT systems (logs)
Financial markets (prices)
Social media
You can actively monitor data arriving from various sources, and set alerts to be triggered when immediate
attention is warranted. For example, you can alert operations staff to imminent equipment failure, or target
marketing offers to customers based on context.

1028

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

This figure shows a typical smart data streaming deployment on the SAP HANA Cloud Platform. Continuous
queries, which you develop and test as projects using the SAP HANA smart data streaming plugin for SAP HANA
studio, are deployed to smart data streaming on the SAP HANA Cloud Platform. SAP HANA cockpit provides an
operations console for configuring smart data streaming.

Restrictions
Smart data streaming currently supports only single-tenant databases. You cannot use smart data streaming
with a multi-tenant SAP HANA database.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1029

You must have an SAP HANA instance with a minimum size of 256GB associated with your SAP HANA Cloud
Platform account. This SAP HANA instance, and any on-premise smart data streaming components, must be
5.1 SPS 10 revision 102.
Currently, you can only connect to smart data streaming on the SAP HANA Cloud Platform using one of two
methods: through the Streaming Web Service, and through the Web Services Provider (using REST
connections). Each one is responsible for different tasks. See Smart Data Streaming Service Connectivity
[page 1035].
The Streaming Web Service and the Web Services Provider are preconfigured for you during setup. You can
customize their configuration properties through the SAP HANA cockpit. However, you cannot change the
preconfigured port numbers, as connections to the SAP HANA Cloud Platform will no longer work.
The Web Services Provider uses REST connections. In this implementation, it does not accept SOAP
requests.
Only certain adapters can connect from an on-premise environment to the smart data streaming service. See
Adapters [page 1037] for more information.
The smart data streaming web server does not support guaranteed delivery. If a project stops or rejects a
message for any reason, the message is not delivered, and there is no indication that the message is lost.
Log stores are currently not backed up, and you cannot set a custom path for a log store. In the event of a disk
failure, all data in log stores is lost and cannot be recovered.

Process Flow
1. Create the SDSADMIN database user. [page 1031]
2. Enable the smart data streaming service. [page 1031]
3. Install smart data streaming components. [page 1032]
4. Set the STREAMING_HOME environment variable. [page 1033]
5. Grant permissions to any necessary users or roles. [page 1034]
6. Access the Streaming Web Service and the Web Services Provider. [page 1035]
7. Connect to the smart data streaming service from SAP HANA studio. [page 1036]

Related Information
SAP HANA Smart Data Streaming SPS 10 Documentation

1030

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.5.3.4.1

Creating the SDSADMIN User

Before you can enable smart data streaming on the SAP HANA Cloud Platform, you need to create an SDSADMIN
database user.

Procedure
1. Open the SAP HANA studio.
2. In the Systems View, choose

Security

Users .

3. From the context menu, choose New User.


4. Name the user SDSADMIN, then go through the wizard, keeping all of the default settings.

Note
Ensure that you name this user SDSADMIN only. If you do not create an SDSADMIN user, you cannot have
the smart data streaming service enabled on your account.

Next Steps
Next, enable [page 1031] SAP HANA Cloud Platform, smart data streaming.

1.5.3.4.2

Enabling the Smart Data Streaming Service

Prerequisites
You have created an SAP HANA Cloud Platform account. See SAP HANA: Getting Started.
You have installed and provisioned an SAP HANA instance with a minimum size of 256GB, and associated this
instance with your SAP HANA Cloud Platform account. This instance must be version 5.1 SPS 10 revision 102,
and cannot be a multi-tenant system.
Your account has the Administrator role.
You have created a database user named SDSADMIN.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1031

Context
SAP HANA Cloud Platform, smart data streaming is an SAP HANA component. You can install it directly through
the SAP HANA Cloud Platform cockpit. Go to Installing SAP HANA Components [page 776] for instructions on
installing any SAP HANA component.

Next Steps
Download and install [page 1032] smart data streaming for SAP HANA studio, and the smart data streaming
client package.

1.5.3.4.3

Downloading and Installing Smart Data Streaming


Components

Although the smart data streaming server is located on the SAP HANA Cloud Platform, you need to download and
install some on-premise components to connect to the server from the client side.

Prerequisites
You have created an SAP HANA Cloud Platform account. See SAP HANA: Getting Started.
You have enabled the smart data streaming service on your SAP HANA Cloud Platform account. See Enabling
the Smart Data Streaming Service [page 1031]

Context
To use the SAP HANA Cloud Platform smart data streaming service, you need to download two installation
packages:
The streaming client package, which contains the set of provided adapters for connecting to other data
sources, the SDK, the streaming ODBC driver and driver manager, and the streaming command-line tools.
The streaming studio plugin package, which contains the smart data streaming plugin for the SAP HANA
studio. This plugin lets you develop streaming projects visually, or through a CCL editor.
If you do not already have SAP HANA studio installed, you need to download that as well. All of these packages
must correspond to the SAP HANA instance version.

1032

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. From the SAP Service Marketplace: Support Packages and Patches

page, download:

The SAP HANA smart data streaming studio package


The SAP HANA smart data streaming client package
The SAP HANA studio package
The SAPCAR utility
Save all of these downloads in the same folder.
2. Unzip all packages using the SAPCAR utility:
a. From the command line, navigate to the location of the downloaded files.
b. Run the utility once for each package you are unzipping. For example, to unzip the streaming client
package:
<download-directory-filepath> sapcar xvf- streaming_client_1.0.120.00_winx64.sar
There are no futher steps for the client package; you only need to unzip it. For the studio packages, go on to
the next step.
3. Install the streaming studio plugin. This procedure may be different depending on whether or not you have
SAP HANA studio installed. See Installing the Streaming Studio Plugin for more information.

Next Steps
Next, set the STREAMING_HOME environment variable [page 1033].

1.5.3.4.4

Setting the STREAMING_HOME Environment


Variable

Set the STREAMING_HOME environment variable so that you can use smart data streaming utilities, and run
streaming projects from SAP HANA studio.

Prerequisites
You have downloaded and installed the smart data streaming client package.

Procedure
From a command prompt, run:
set STREAMING_HOME=<streaming-client-directory>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1033

Set the streaming client directory to the path where you saved the smart data streaming client files.

Next Steps
Create users and roles, and grant them permissions [page 1034].

1.5.3.4.5

Granting Permissions

Control a user's access to and control over smart data streaming by providing the permissions necessary to
complete specific tasks.

Prerequisites
You have created an SAP HANA Cloud Platform account. See SAP HANA: Getting Started.
You have installed the SAP HANA smart data streaming on-premise components. See Downloading and
Installing Smart Data Streaming Components [page 1032].
You have set the STREAMING_HOME environment variable.

Context
You need to grant permissions to users before they can connect to any web services, or use streaming in SAP
HANA studio.
When you enable the smart data streaming service, you create a database user named SDSADMIN. Use this
database user to perform policy administration functions, such as granting and revoking privileges.
Because the SDSADMIN user is intended to set up user authorization policies, the standard smart data streaming
user authorization commands do not work on SDSADMIN. For example, get users, which lists all users granted
authorization to use smart data streaming, will not list SDSADMIN because it was created at installation time with
a predefined set of permissions.

Procedure
1. Log in to the SAP HANA cockpit, and open the Assign Roles to Users tile.
2. Select the user SDSADMIN and click Edit.
3. Click Assign Roles, and select the following roles:
sap.hana.admin.roles::Monitoring

1034

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

sap.hana.streaming.monitoring.roles::Monitoring
sap.hana.uis.db::SITE_DESIGNER
4. Click OK, then Save.
5. Start streamingclusteradmin in interactive mode for your SAP HANA instance:
$STREAMING_HOME/bin/streamingclusteradmin --uri=https://<https://<hana-instancename>wsp<HCP-account-name>.<landscape-name>.hana.ondemand.com:443 -username=SDSADMIN --password=<password>
6. Execute the grant perm command for each of the permissions needed by the user. The only required
arguments are the privilege (action you want to permit), whether you are granting it to a user or a role, and the
name of that user or role, in the following format:
grant perm <priv> [<privtype>] [on [any]<resource-type> [<resource>]] to user|
role <name>
So, to grant permission to perform all actions, with no restrictions, to the user SDSADMIN, enter:
grant perm all on all to user SDSADMIN
For more information on granting permissions in smart data streaming, see Granting Permissions.

Next Steps
Access the Streaming Web Service and the Web Services Provider [page 1035] to begin administering smart data
streaming, and working with streaming projects.

1.5.3.4.6

Smart Data Streaming Service Connectivity

Smart data streaming provides two methods for connecting to the SAP HANA Cloud Platform: the Streaming Web
Service, and the Web Services Provider. Each of these methods is responsible for different tasks.
Use the Streaming Web Service to publish and subscribe to projects, and for connecting the Streaming Web
Output adapter to the smart data streaming service.
Use the Web Services Provider REST connections for administrative and lifecycle management tasks, such as
starting and stopping projects, for monitoring project metadata, and for connecting external adapters to the
smart data streaming service.

Note
The Web Services Provider does not accept SOAP requests.
When setting up your system, enable autostart on both the Streaming Web Service and the Web Services
Provider. This starts the services automatically with the cluster. All other properties are preconfigured. To enable
autostart, and also customize any service configuration properties, log in to the SAP HANA cockpit, and access
the Streaming Cluster Configuration tile. See the Streaming Web Service and Web Services Provider sections in
the SAP HANA Smart Data Streaming: Adapters Guide for more information.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1035

Note
Do not change the preconfigured port numbers for the Streaming Web Service or the Web Services Provider.
These ports are necessary for successful connections to the SAP HANA Cloud Platform.
You can access the Streaming Web Service through: https://<hana-instance-name>sws<HCP-accountname>.<landscape-name>.hana.ondemand.com. For example, with an instance name of SDSHANA, an SAP
HANA Cloud Platform account name of xyz123, and the landscape name US1, you would enter:
https://SDSHANAswsxyz123.US1.hana.ondemand.com
You can access the Web Services Provider through: https://<hana-instance-name>wsp<HCP-accountname>.<landscape-name>.hana.ondemand.com. For example, with an instance name of SDSHANA, an SAP
HANA Cloud Platform account name of xyz123, and the landscape name US1, you would enter:
https://SDSHANAwspxyz123.US1.hana.ondemand.com
Next, Connect to the Web Services Provider [page 1036] from SAP HANA studio.

Related Information
Streaming Web Service
Streaming REST Connections

1.5.3.4.6.1 Connecting to the Service from SAP HANA Studio


Connect to the smart data streaming service using the SAP HANA studio Streaming Run-Test perspective.

Prerequisites
You have installed SAP HANA studio with the smart data streaming option.
You have granted the necessary permissions to any required users or roles. See Granting Permissions [page
1034].

Context
You can use streaming perspectives in SAP HANA studio to connect to the SAP HANA smart data streaming
service in the cloud. From here, you can develop and test streaming projects using the visual editor, the CCL
editor, or both.

1036

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. In SAP HANA studio, open the Streaming Run-Test perspective.
2. From the server view toolbar, click New Server URL.
3. Fill out the Host Name and Port fields:
Host Name: <hana-instance-name>wsp<HCP-account-name>.<landscapename>.hana.ondemand.com
For example, with an instance name of SDSHANA, an SAP HANA Cloud Platform account named xyz123,
and the landscape US1, you would enter:
SDSHANAwspxyz123.US1.hana.ondemand.com
Port: 443
4. Select the Web Services protocol.
5. Check the SSL checkbox to enable SSL connections.
6. Click OK to save.
7. From the studio menu, go to

Window

Preferences

SAP HANA smart data streaming .

8. In the Default Server URL field, click Change and select the server from the dialog. Click OK.
9. In the Preferences dialog, click Apply, then OK.

1.5.3.4.6.2 Adapters
Streaming projects running on the SAP HANA Cloud Platform can use adapters to connect to the local SAP HANA
database.
You can use the following adapters with the streaming service:
SAP HANA Output adapter: use this adapter to direct the output from any stream or window into an SAP
HANA table.
Database Input adapter: use this adapter to pull data from the SAP HANA database into a streaming project.

Note
These adapters must be associated with the default SAP HANA data service; they cannot be used to connect to
other databases.
You can also use any toolkit adapter in unmanaged mode to connect from an on-premise environment to the
smart data streaming service on the SAP HANA Cloud Platform. Toolkit adapters are various preconfigured and
ready-to-use adapters that have been created using the adapter toolkit, which comes in the the smart data
streaming client package. See the Preconfigured Adapters Included with the Adapter Toolkit in the SAP HANA
Smart Data Streaming: Building Custom Adapters guide for a list of all toolkit adapters.
All toolkit adapters use the Web Services Provider URL to connect to the smart data streaming service. See Smart
Data Streaming Service Connectivity [page 1035].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1037

Streaming Lite
Streaming lite projects use a specialized adapter: the Streaming Web Output adapter. You can use this adapter to
connect from a streaming lite project to the smart data streaming service.
The Streaming Web Output adapter uses the Streaming Web Service URL to connect to the SAP HANA Cloud
Platform. See Smart Data Streaming Service Connectivity [page 1035].

Related Information
Streaming Data to SAP HANA
Database Adapter

1.5.3.4.7

Developing and Running Streaming Projects

You can create projects in SAP HANA studio, then deploy them to the cloud.
Once you have connected to the Web Services Provider through SAP HANA studio, you can follow the same
process for developing and running streaming projects as an on-premise installation.
You have a few options for getting yourself acquainted with smart data streaming projects:
Follow the hands-on tutorial in the SAP HANA Smart Data Streaming: Developer Guide, which teaches you
how to set up and run a simple project.
Load one of the sample projects provided with the smart data streaming plugin for SAP HANA studio, and
documented in the SAP HANA Smart Data Streaming: Developer Guide.
Look through the CCL examples in the SAP HANA Smart Data Streaming: Examples Guide.
Watch some video tutorials from the SAP HANA Smart Data Streaming playlist
YouTube channel.

1.5.3.4.8

on the SAP HANA Academy

Controlling Memory Resources

The SAP HANA database and SAP HANA smart data streaming are located on the same host, and share the host's
memory resources. Understanding how they use and manage memory resources is crucial to the understanding
of your own system setup.

Memory in SAP HANA


When you're setting up an SAP HANA system with smart data streaming, you need to allocate sufficient memory
resources, and set up various parameters to control memory consumption. SAP HANA provides multiple ways to
do this.

1038

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The SAP HANA database preallocates a pool of memory from the operating system over time, up to a predefined
global allocation limit. You can change this limit in the global.ini configuration file by editing the
global_allocation_limit parameter. This parameter limits the total amount of memory that can be used by
the database, and by all installed options.
At install time, SAP HANA removes 16GB of memory from the global allocation limit, and grants it to smart data
streaming. You can raise or lower the alloted memory by changing this parameter. When you're considering
memory allocation for both the SAP HANA database and smart data streaming, set this parameter first, before
handling any other memory settings. See Monitoring Memory Usage in the SAP HANA Administration Guide for
more information.

Memory in SAP HANA Smart Data Streaming


Smart data streaming controls memory on a per-project basis. You can customize memory consumption by
setting various project deployment options in SAP HANA studio. The parameters that affect memory use are:
memory
memory-reserve
java-max-heap
When running multiple projects, ensure that the total memory assigned to the individual the projects does not
exceed the total memory allocated for smart data streaming.
To learn more about these options, see Project Deployment Options in the SAP HANA Smart Data Streaming:
Configuration and Administration Guide.
If you are using the SAP HANA Output adapter in a streaming project, you should also be aware of its memory
consumption, and size it according to your project's needs. See Performance and Tuning Tips for the SAP HANA
Adapter in the SAP HANA Smart Data Streaming: Adapters Guide for the specific properties you need to set, both
within the adapter configuration, and within your system setup.

Note
Scaling your SAP HANA and smart data streaming systems is not currently supported.

Related Information
Monitor Project Memory Usage
Streaming Data to SAP HANA

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1039

1.5.3.4.9

Controlling CPU Resources

You can improve workload management by controlling CPU resources in SAP HANA and SAP HANA smart data
streaming.

SAP HANA CPU Usage


If the physical hardware on a host needs to be shared with other processes, it may be useful to assign a set of
cores to an SAP HANA process. To do this, you can assign affinities to logical cores of the hardware. See Bind
Processes to CPUs in the SAP HANA Troubleshooting and Performance Analysis Guide.

SAP HANA Smart Data Streaming CPU Usage


Smart data streaming controlls CPU resources on a per-project basis. You can assign CPU affinities in a project's
configuration (.ccr) file, which you can do directly through SAP HANA studio. See Processor Affinities in the SAP
HANA Smart Data Streaming: Configuration and Administration Guide.

Related Information
CPU Usage

1.5.4 HTML5: Development


SAP HANA Cloud Platform enables you to easily develop and run lightweight HTML5 applications in a cloud
environment.
HTML5 applications on SAP HANA Cloud Platform consist of static resources and can connect to any existing onpremise or on-demand REST services. Compared to a Java application, there is no need to start a dedicated
process for an HTML5 application. Instead the static resources and REST calls are served using a shared
dispatcher service provided by the SAP HANA Cloud Platform.
The static content of the HTML5 applications is stored and versioned in Git repositories. Each HTML5 application
has its own Git repository assigned. For offline editing, developers can directly interact with the Git service using a
Git client of their choice. They may use any Git client like EGit or a native Git implementation to perform Git
operations. A Git repository is created automatically when a new HTML5 application is created.
Lifecycle operations, for example, creating new HTML5 applications, creating new versions, activating, starting
and stopping or testing applications, can be performed using the SAP HANA Cloud Platform cockpit. As the static
resources are stored in a versioned Git repository, not only the latest version of an application can be tested, but
the complete version history of the application is always available for testing. The version that is delivered to the
end users of that application is called the "active version". Each application can have only one active version.

1040

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Figure 1: HTML5 Applications Overview

Related Information
HTML5: Getting Started [page 66]
HTML5: Application Operations [page 1171]
Securing HTML5 Applications [page 1323]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1041

1.5.4.1

Developer's Guide

The developers guide introduces the development environment for HTML5 applications, a procedure on how to
create applications, and supplies details on the descriptor file that specifies how dedicated application URLs are
handled by the platform.

Related Information
Development Environment [page 1042]
Creating an HTML5 Application [page 71]
Application Descriptor File [page 1046]

1.5.4.1.1

Development Environment

The development workflow is initiated from the SAP HANA Cloud Platform cockpit.
The cockpit provides access to all lifecycle operations for HTML5 applications, for example, creating new
applications, creating new versions, activating a version, and starting or stopping an application.

1.5.4.1.1.1 Working with Git


The SAP HANA Cloud Platform, Git service stores the sources of an HTML5 application in a Git repository.
For each HTML5 application there is one Git repository. You can use any Git client to connect to the Git service. On
your development machine you may, for example, use Native Git or Eclipse/EGit. The SAP Web IDE has a built-in
Git client.

Git URL
With this URL, you can access the Git repository using any Git client.
The URL of the Git repository is displayed under Source Location on the detail page of the repository. You can also
view this URL together with other detailed information on the Git repository, including the repository URL and the
latest commits, by choosing HTML5 Applications in the navigation area and then Versioning.

Authentication
Access to the Git service is only granted to authenticated users. Any user who is a member of the account that
contains the HTML5 application and who has the Administrator, Developer, or Support User role has access to the

1042

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Git repository. When sending requests, users have to authenticate themselves using their user name and
password of the identity provider.

Permissions
The permitted actions depend on the account member role of the user:
Any authenticated user with the Administrator, Developer, or Support User role can read the Git repository. They
have permission to:
Clone the repository.
Fetch commits and tags.
Write access is granted to users with the Administrator or Developer role. They have permission to:
Push commits if the branch pointer on the server is moved fast-forward.
Otherwise, the commits need to be rebased locally so that they are successors of the tip of the branch the
push is targeting.
Push tags, if no tag with the same name exists.
Pushing a tag defines a new version of the HTML5 application. The version name is the same as the tag name.
Create a new branch.
Currently, only commits in the master branch are visible in the SAP HANA Cloud Platform cockpit.
Push commits initiated by a different author (forge author identity).
Developers are not allowed to push commits committed by a different user (forge committer identity). The
committer e-mail address in the commits they push must match the e-mail address they registered in the
identity provider.
Developers cannot delete or move tags or delete branches.
Only users with the Administrator role have permission to:
Push commits committed by a different user (forge committer identity).
Forcefully push commits, for example, to rewrite the Git history of an HTML5 application.
Forcefully push tags, for example, to move the version of an HTML5 application to a different commit.
Delete tags or delete branches.

Related Information
Account Member Roles [page 27]
Git Service [page 928]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1043

1.5.4.1.2

Creating an HTML5 Application

You create new applications in the SAP HANA Cloud Platform cockpit.

Context
For each new application a new Git repository is created automatically. To view detailed information on the Git
repository, including the repository URL and the latest commits, choose
in the navigation area and then Versioning.

Applications

HTML5 Applications

Note
To create the HTML5 application in more than one landscape, create the application in each landscape
separately and copy the content to the new Git repository.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose

Applications

HTML5 Applications

in the navigation area.

If you have already created applications using this account, the list of HTML5 applications is displayed.
3. To create a new HTML5 application, choose New Application and enter an application name.

Note
Adhere to the naming convention for application names:
The name must contain no more than 30 characters.
The name must contain only lowercase alphanumeric characters.
The name must start with a letter.
4. Choose Save.
5. Clone the repository to your development environment.
a. To start SAP Web IDE and automatically clone the repository of your app, choose Edit Online (
end of the table row of your application.

) at the

b. On the Clone Repository screen, enter your user and password (SCN user and SCN password), and
choose OK.

Results
You created an application and a corresponding Git repository.

1044

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Cockpit [page 84]

1.5.4.1.3

Activating a Version

Since end users can only access the active version of an application, you must create and activate a version of
your application.

Context
The administrator can activate a single version of an application to make it available to end users.

Procedure
1. Choose HTML5 Applications in the navigation area.
2. Select the link to your application.
3. Choose Versioning in the navigation area.
4. Under History, choose Versions.
5. In the Versions table, select your version and choose the Activate this application version icon.
6. Confirm that you want to activate the application.

Results
You can now distribute the URL of your application to the end users.

Related Information
For more information about logging on, see the Logon section in Cockpit [page 84]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1045

1.5.4.1.4

Application Descriptor File

Using the application descriptor file you can configure the behavior of your HTML5 application.
This descriptor file is named neo-app.json. The file must be created in the root folder of the HTML5 application
repository and must have a valid JSON format.
With the descriptor file you can set the options listed under Related Links.
The application descriptor file must follow the following format. All settings are optional.
{

"authenticationMethod": "saml"|"none",
"welcomeFile": "<path to welcome file>",
"logoutPage": "<path to logout page>",
"sendWelcomeFileRedirect": true|false,
"routes": [
{
"path": "<application path to be mapped>",
"target": {
"type": "destination | service | application",
"name": "<name of the destination> | <name of the service> | <name
of the application or subscription>",
"entryPath": "<path prepended to the request path>",
"version": "<version to be referenced. Default is active version.>"
},
"description": "<description>"
}
],
"securityConstraints": [
{
"permission": "<permission name>",
"description": "<permission description>",
"protectedPaths": [
"<path to be secured>",
...
],
"excludedPaths": [
"<path to be excluded>",
...
]
}
],
"cacheControl": [
{
"path": "<optional path of resources to be cached>",
"directive": "none | public | private",
"maxAge": <lifetime in seconds>
}
],
"headerWhiteList": [
"<header1>",
"<header2>",
...
]
}

All paths in the neo-app.json must be specified as plain paths, that is, paths with blanks or other special
characters must include these characters literally. These special characters must be URI-encoded in HTTP
requests.

1046

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Information about: authenticationMethod [page 1047]
Information about: welcomeFile and sendWelcomeFileRedirect [page 1056]
Information about: routes with target type destination [page 1051]
Information about: routes to include SAPUI5 resources [page 1050]
Information about: routes to access the user API [page 1054]
Information about: securityConstraints [page 1048]
Information about: cacheControl [page 1057]
Information about: headerWhiteList [page 1058]
Accessing Application Resources [page 1053]

1.5.4.1.4.1 Authentication
Authentication is the process of establishing and verifying the identity of a user as a prerequisite for accessing an
application.
By default an HTML5 application is protected with SAML2 authentication, which authenticates the user against
the configured RDP. For more information, see ID Federation with the Corporate Identity Provider [page 1292].
For public applications the authentication can be switched off using the following syntax:
"authenticationMethod": "saml" | "none"

Example
An example configuration that switches off authentication looks like this:
"authenticationMethod": "none"

Note
Even if authentication is disabled, authentication is still required for accessing inactive application versions.
To protect only parts of your application, set the authenticationMethod to "none" and define a security
constraint for the paths you want to protect. If you want to enforce only authentication, but no additional
authorization, define a security constraint without a permission (see Authorization [page 1048]).

Handling Session Timeout


After 20 minutes of inactivity user sessions are invalidated. If the user tries to access an invalidated session, SAP
HANA Cloud Platform returns a logon page, where the user must log on again. If you are using SAML as a logon
method, you cannot rely on the response code to find out whether the session has expired because it is either 200

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1047

or 302. To check whether the response requires a new logon, get the com.sap.cloud.security.login HTTP
header and reload the page. For example:
jQuery(document).ajaxComplete(function(e, jqXHR) {
if(jqXHR.getResponseHeader("com.sap.cloud.security.login")) {
alert("Session is expired, page shall be reloaded.");
window.location.reload();
}
})

1.5.4.1.4.2 Authorization
To enforce authorization for an HTML5 application, permissions can be added to application paths.
In the cockpit, you can create custom roles and assign them to the defined permissions. If a user accesses an
application path that starts with a path defined for a permission, the system checks if the current user is a
member of the assigned role. If no role is assigned to a defined permission only account members with developer
permission or administrator permission have access to the protected resource.
Permissions are only effective for the active application version. To protect non-active application versions, the
default permission NonActiveApplicationPermission is defined by the system for every HTML5 application.
This default permission must not be defined in the neo-app.json file but is available automatically for each
HTML5 application.
If only authentication is required for a path, but no authorization, a security constraint can be added without a
permission.
A security constraint applies to the directory and its sub-directories defined in the protectedPaths field, except
for paths that are explicitly excluded in the excludedPaths field. The excludedPath field supports pattern
matching. If a path specified ends with a slash character (/) all resources in the given directory and its subdirectories are excluded. You can also specify the path to be excluded using wildcards, for example, the path
**.html excludes all resources ending with .html from the security constraint.
To define a security constraint, use the following format in the neo-app.json file:
...

...

1048

"securityConstraints": [
{
"permission": "<permission name>",
"description": "<permission description>",
"protectedPaths": [
"<path to be secured>"
],
"excludedPaths": [
"<path to be excluded>",
...
]
}
]

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
An example configuration that restricts a complete application to the accessUserData permission, with the
exception of all paths starting with "/logout", looks like this:
...

...

"securityConstraints": [
{
"permission": "accessUserData",
"description": "Access User Data",
"protectedPaths": [
"/"
],
"excludedPaths": [
"/logout/**"
]
}
]

Related Information
Managing Roles and Permissions [page 1177]

1.5.4.1.4.3 Protecting the Application Descriptor


By default end users can access the application descriptor file of an HTML5 application.
To do so, they enter the URL of the application followed by the filename of the application descriptor in the
browser.

Tip
For security reasons we recommend that you use a permission to protect the application descriptor from being
accessed by end users.
A permission for the application descriptor can be defined by adding the following security constraint into the
application descriptor
...

...

"securityConstraints": [
{
"permission": "AccessApplicationDescriptor",
"description": "Access application descriptor",
"protectedPaths": [
"/neo-app.json"
]
}
]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1049

After activating the application, a role can be assigned to the new permission in the cockpit to give users with that
role access to the application descriptor via the browser. For more information about how to define permissions
for an HTML5 application, see Authorization [page 1048].

1.5.4.1.4.4 Accessing SAPUI5 Resources


To access SAPUI5 resources in your HTML5 application, configure the SAPUI5 service routing in the application
descriptor file.

SAPUI5 Service Routing


To configure the SAPUI5 service routing for your application, map a URL path that your application uses to access
SAPUI5 resources to the SAPUI5 service:
...
"routes": [
{

...

"path": "<application path to be mapped>",


"target": {
"type": "service",
"name": "sapui5",
"version": "<version>",
"entryPath": "/resources"
},
"description": "<description>"
}

Example
This configuration example maps all paths starting with /resources to the /resources path of the SAPUI5
library.
...
"routes": [
{

...

"path": "/resources",
"target": {
"type": "service",
"name": "sapui5",
"entryPath": "/resources"
},
"description": "SAPUI5"
}

For more information about using SAPUI5 for your application, see SAPUI5: UI Development Toolkit for HTML5.

1050

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Determining the Current Active SAPUI5 Version


In the top right corner on https://sapui5-sapui5.dispatcher.hana.ondemand.com/, choose VERSION
INFO to display the latest versions of the individual libs.

Referencing a Specific SAPUI5 Version in Your HTML5 App


Example
This configuration example shows how to reference the SAPUI5 version 1.26.6 using the neo-app.json file.
...
"routes": [
{
"path": "/resources",
"target": {
"type": "service",
"name": "sapui5",
"version": "1.26.6",
"entryPath": "/resources"
},
"description": "SAPUI5"
}
}
...
To display the available SAPUI5 versions, open https://sapui5sapui5.dispatcher.hana.ondemand.com/neo-app.json file.

Related Information
VERSION INFO in SAPUI5 Release Notes
To view the SAPUI5 versions in the HTML5 App, open the neo-app.json file
Release Notes for SAP HANA Cloud Platform

1.5.4.1.4.5 Accessing REST Services


To connect your application to a REST service, configure routing to an HTTP destination in the application
descriptor file.
A route defines which requests to the application are forwarded to the destination. Routes are matched with the
path from a request. All requests with paths that start with the path from the route are forwarded to the
destination.
If you define multiple routes in the application descriptor file, the route for the first matching path is selected.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1051

The HTTP destination must be created in the account where the application is running. For more information on
HTTP destinations, see Creating HTTP Destinations [page 304] and Assigning Destinations for HTML5
Applications [page 1176].
...
"routes": [

"path": "<application path to be forwarded>",


"target": {
"type": "destination",
"name": "<name of the destination>"
},
"description": "<description>"

...

Example
With this configuration, all requests with paths starting with /gateway are forwarded to the gateway
destination.
...
"routes": [

}
]

...

"path": "/gateway",
"target": {
"type": "destination",
"name": "gateway"
},
"description": "Gateway System"

If the REST service does not respond in time, a gateway timeout response (HTTP status code 504) is
returned. In such cases, you can increase the timeout period with the following destination properties:
Table 320:
Property

Values

Comment

ConnectionTimeout

Default: 10000 (10 seconds)

Period of time in milliseconds until the HTML5 appli

Max. value: 120000 (120


seconds)
ClientReadTimeout

cation expects a response from the REST service


when establishing a connection.

Default: 30000 (30 seconds) Period of time in milliseconds until the HTML5 appli
Max. value: 300000 (300
seconds)

cation expects a response from the REST service


when forwarding a request.

For information on how to set destination properties, see You can enter additional properties (step 9) [page 304].

Note
For performance reasons, we recommend that you only increase the timeout value in exceptional cases.

1052

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Assigning Destinations for HTML5 Applications [page 1176]

1.5.4.1.4.6 Accessing Application Resources


To access resources from another HTML5 application or a subscription to an HTML5 application, you can map an
application path to the corresponding application or subscription.
If the given path matches a request path, the resource is loaded from the mapped application or subscription. This
feature may be used to separate re-usable resources in a dedicated application.

Note
If multiple routes are defined in the application descriptor, the route for the first matching path in the
application descriptor is selected.
...
"routes": [
{

"path": "<application path to be mapped>",


"target": {
"type": "application",
"name": "<name of the application or subscription>"
"version": "<version to be referenced. Default is active version>",
},
"description": "<description>"
}
]

...

Example
This configuration example maps all paths starting with /icons to the active version of the application named
iconlibrary.
...
"routes": [

...

{
"path": "/icons",
"target": {
"type": "application",
"name": "iconlibrary"
},
"description": "Icon Library"
}
]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1053

Related Information
Application Descriptor File [page 1046]

1.5.4.1.4.7 Accessing the User API


The user API service provides an API to query the details of the user that is currently logged on to the HTML5
application.
If you use a corporate identity provider (IdP), some features of the API do not work as described here. The
corporate IdP requires you to configure a mapping from your IdPs assertion attributes to the principal attributes
usable in SAP HANA Cloud Platform. See Configure User Attribute Mappings [page 1298].
To use the user API in your HTML5 application, add a route to your neo-app.json application descriptor file as
follows:
...
"routes": [
{
"path": "<application path to be forwarded>",
"target": {
"type": "service",
"name": "userapi"
}
}
]
...
The route defines which requests to the application are forwarded to the API. The route is matched with the path
from a request. All requests with paths that start with the path from the route are forwarded to the API.

Example
With the following configuration, all requests with paths starting with /services/userapi are forwarded to
the user API.
...
"routes": [
{
"path": "/services/userapi",
"target": {
"type": "service",
"name": "userapi"
}
}
]
...
The user API supports the following endpoints:
/currentUser
/attributes
The user API requires authentication. The user is logged on automatically even if the authentication property
is set to none in the neo-app.json file.

1054

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Current User Details


Calling the /currentUser endpoint returns a JSON object that provides the user ID and additional information of
the logged-on user. The table below describes the properties contained in the JSON object and specifies the
principal attribute used to compute this information.
Table 321:
Property Name

Description

Principal Attribute

name

The user ID that is used for logging on.

n.a.

firstName

The first name of the user.

firstname

lastName

The last name of the user.

lastname

email

The email address of the user.

email

displayName

Concatenated user name derived from

firstname + lastname + name

the first name, last name, and user ID. If


either the first or the last name does not
exist, the displayName consists solely
of the user ID.

The /currentUser endpoint maps a default set of attributes. To retrieve all attributes, use the /attributes
endpoint as described in User Attributes.

Example
A sample URL for the route defined above would look like this: /services/userapi/currentUser.
An example response could return the following user data:
{

"name": "p12345678",
"firstName": "John",
"lastName": "Doe",
"email": "john@doeenterprise.com",
"displayName": "John Doe (p12345678)"

User Attributes
The /attributes endpoint returns the principal attributes of the current user as a JSON object. These attributes
are received as SAML assertion attributes when the user logs on. To make them visible, define a mapping within
the trust settings of the SAP HANA Cloud Platform cockpit, see Configure User Attribute Mappings [page 1298].

Example
A sample URL for the route defined above would look like this: /services/userapi/attributes.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1055

If the principal attributes firstname, lastname, companyname, and organization are present, an example
response may return the following user data:
{

"firstname": "John",
"lastname": "Doe",
"companyname": "Doe Enterprise",
"organization": "Customer sales and marketing"

1.5.4.1.4.8 Welcome File


You can either display the default Welcome file or specify a different file as Welcome file.
If the application is accessed only with the domain name in the URL, that is without any additional path
information, then the index.html file that is located in the root folder of your repository is delivered by default. If
you want to deliver a different file, configure this file in the neo-app.json file using the WelcomeFile parameter.
With this additional parameter you specify whether a redirect is sent to the Welcome file or whether the Welcome
file is delivered without redirect. To configure the Welcome file, add a JSON string with the following format to the
neo-app.json file:
"welcomeFile": "<path to the welcome file>",
"sendWelcomeFileRedirect": true | false

Example
An example configuration, which forwards requests without any path information to an index.html file in
the /resources folder would look like this:
"welcomeFile": "/resources/index.html",
"sendWelcomeFileRedirect": true

1.5.4.1.4.9 Logout Page


To trigger a logout of the logged-in user, you can configure a logout page in the application descriptor.
When executing a request to the configured logout page, the server triggers a logout. This results in a response
containing a logout request that is send to the identity provider (IdP) to invalidate the user's session on the IdP.
After the user is logged out from the IdP, the configured logout page is called again. Now, the content of the logout
page is served. The logout page is always unprotected, independent of the authentication method of the
application and independent of additional security constraints. In case additional resources, for example, SAPUI5,
are referenced from the logout page, those resources have to be unprotected as well.
For information on how to configure certain paths as unprotected, see Authentication [page 1047] and
Authorization [page 1048].
Because non-active application versions always require authentication, a logout is only triggered for the active
application version. For non-active application versions the logout page is served without triggering a logout.

1056

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To configure a logout page for your application, use the following format in the neo-app.json file:
...
...

"logoutPage": "<path to logout page>"

Example
An example configuration of a logout page looks like this:
...
...

"logoutPage": "/logout.html"

1.5.4.1.4.10 Cache Control


To improve the performance of your application you can control the Cache-Control headers, which are returned
together with the static resource of your application.
You can configure caching for the complete application, for dedicated paths, or resources of the application. If the
path you specify ends with a slash character (/) all resources in the given directory and its sub-directories are
matched. You can also specify the path using wildcards, for example, the path **.html matches all resources
ending with .html. Only the first caching directive that matches an incoming request is applied. The path **.css
hides, for example, other paths such as /resources/custom.css.
With the directive property, you specify whether public proxies can cache the resources. The possible values
for the directive property are:
public
The resource can be cached regardless of your response headers.
private
Your resource is stored by end-user caches, for example, the browser's internal cache only.
none
This is the default value that does not send an additional directive
To configure caching, add a JSON string in the following format to the neo-app.json file:
...
"cacheControl": [

...

"path": "<optional path of resources to be cached>",


"directive": "none | public | private",
"maxAge": <lifetime in seconds>

Example
An example configuration that caches all static resources for 24 hours looks like this:
...
"cacheControl": [

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1057

{
]

...

"maxAge": 86400

1.5.4.1.4.11 Header Whitelisting


For security reasons not all HTTP headers are forwarded from the application to a backend or from the backend
to the application.

Default Header Whitelisting


The following HTTP headers are forwarded automatically without any additional configuration because they are
part of the HTTP standard:
Accept
Accept-Charset
Accept-Encoding
Accept-Language
Accept-Range
Age
Allow
Authorization
Cache-Control
Content-Language
Content-Location
Content-Range
Content-Type
Date
ETag
Expires
From
If-Match
If-Modified-Since
If-None-Match
If-Range
If-Unmodified-Since
Last-Modified
Link
Location

1058

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Max-Forwards
Pragma
Range
Referer
Retry-After
User-Agent
Vary
Via
Warning
WWW-Authenticate
Additionally the following HTTP headers are transferred automatically because they are frequently used by Web
applications and (SAP) servers:
Content-Disposition
Content-MD5
DataServiceVersion
DNT
MaxDataServiceVersion
Origin
RequestID
Sap-ContextId
Sap-Message
Sap-Metadata-Last-Modified
SAP-PASSPORT
X-CorrelationID
X-CSRF-TOKEN
X-Forwarded-For
X-Forwarded-Proto
X-HTTP-Method
X-Requested-With

Custom Header Whitelisting


If you need additional HTTP headers to be forwarded to or from a backend request or backend response, add the
header names in the following format to the neo-app.json file:
"headerWhiteList": [<header1> (, <header2>, ...)]

Example
An example configuration that forwards the additional headers X-Custom1 and X-Custom2 looks like this:
"headerWhiteList": ["X-Custom1 "," X-Custom2"]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1059

Excluded Headers
The following headers are never forwarded:
Cookie
Cookie2
Content-Length
Cookies are used for user session identification and therefore should not be shared. The system stores cookies
sent by a backend in the session and removes them from the response before forwarding to the user. With the
next request to the backend the stored cookies are added again.
The Content-Length header cannot be whitelisted as the value is re-calculated on demand matching the
content of the given request or response.

1.5.5 API Documentation


This document contains references to API documentation to be used for development with SAP HANA Cloud
Platform.
Javadoc for SAP HANA Cloud Platform
SAP HANA XS JavaScript Reference

REST APIs
Lifecycle management API
Authorization Management API
Monitoring API

1.6

Extend SAP Cloud Solutions

SAP HANA Cloud Platform is the extension platform for SAP. It enables developers to develop loosely coupled
extension applications securely, thus implementing additional workflows or modules on top of the existing SAP
cloud solution they already have.
SAP HANA Cloud Platform provides a secure application container which decouples the extension applications
from the extended SAP solution via a public API layer. This container ensures that extension applications have no
impact on the stability of the extended solutions. It also ensures that data access is governed through the same
roles and permission checks as those of any other SAP interface. SAP HANA Cloud Platform simplifies many of
the system integration challenges, handling aspects such as identity propagation, account onboarding, dynamic
theming and branding and installation automation and provisioning.

1060

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Technical aspects
Extensions and extended SAP cloud solutions co-located in the same data center, where possible
In most of the cases the extensions that are being developed are co-located in the same data center as the
SAP product that is being extended. The co-location ensures that the complete solution is using one
infrastructure and is operated by one and the same team on this infrastructure. It also improves the response
time for API calls.
Integration with SAP Cloud product toolset
This integration allows SAP solution administrators to have a consistent experience in managing extensions
as an integral part of the product they are responsible for, including but not limited to software lifecycle
management, administration of roles, permissions and visibility groups.
Dynamic UI branding and theming
The tight integration between the SAP product and SAP HANA Cloud Platform allows extension users to get
the same seamless user experience as the native product modules. It also allows the delivery of SAP solutionspecific artifacts, such as navigation exit points, tiles, widgets or external business objects.
Security integration
The integration between the SAP product and SAP HANA Cloud Platform also allows you to manage the
extension you are building by using all the authentication and authorization capabilities of the SAP product
you want to extend.

Development options
Custom development
As a customer of an SAP cloud solution, you can create your own extension applications using SAP HANA
Cloud Platform. SAP provides access to all the required integration and implementation materials describing
how SAP HANA Cloud Platform is connected to the corresponding SAP cloud solution. Furthermore, for some
of the SAP cloud solutions (for example SuccessFactors), SAP HANA Cloud Platform offers out-of-the box
and pre-integrated extension accounts. You can leverage all the SAP HANA Cloud Platform tools for the
implementation of those extension applications.
Certified partner applications
As a customer of an SAP cloud solution, you can also use an existing extension application provided by one of
the SAP certified partners. Depending on the extension, it can be provided free of charge or for a certain fee.
This option does not require own development. Depending on the delivery model of the partner extension, you
may require SAP HANA Cloud Platform resources for running the extension in your SAP HANA Cloud
Platform account or alternatively, you can consume the extension as a service for a monthly fee.
Extension customization
You can also have a mixed scenario where you first obtain and then further customize a partner extension
application to best meet your needs.

Extension concept
SAP HANA Cloud Platform serves as a dedicated and isolated secure application container (hosting Java or
HTML5 applications, or both). On one hand, it provides the API-level access to the extended SAP solution. On the

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1061

other hand, it takes care of the lifecycle management and the initial configuration of the extension applications.
There are several levels of extension integration:
Application customization
Usually, every SAP cloud solution comes with certain customization capabilities. Depending on the
technology stack, this might vary from a fully fledged customization for existing business objects, through
creating custom business objects, and up to generating native user interfaces based on the customized
objects. Some of the SAP technology stacks allow implementation teams to even do some simple coding,
which is then executed natively as part of the customized product. Regardless of how feature-rich the
extended solution is, SAP HANA Cloud Platform adds much more to the extension capabilities and enables
you to build a large number of extension scenarios and interact with on-premise and cloud systems.
Loosely coupled applications
As a minimum, extension application need a configured Single Sign-On (SSO) with the extended SAP solution.
All the SAP cloud solutions provide the means for such configuration - you can either leverage the solution
local integrated SAML 2.0-compliant identity provider, or by using the SAP Cloud Identity service as a central
trust point in the landscape. As a rule of thumb, if you want to integrate a number of different SAML 2.0compliant solutions in your landscape, a central trust management point such as SAP Cloud Identity service
will significantly simplify the management of additional trusts. Furthermore, SAP HANA Cloud Platform
comes pre-integrated with SAP Cloud Identity service.
Another aspect of the loosely coupled applications is that you have to ensure the end-to-end user identity
propagation going across all the extension application layers. This means that if, for example, a user has
logged on to an HTML5 application, it has to be the same user on behalf of which all the underlying backend
calls are performed. To achieve this, you leveraging the SAML 2.0 bearer assertion authentication flow, which
is the default way for accesing any SAP cloud solution API from SAP HANA Cloud Platform. You use the same
approach for Java applications.

Related Information
Basic Concepts [page 1062]
Extending SuccessFactors [page 1070]

1.6.1 Basic Concepts

Extension account
An extension account is a customer or partner SAP HANA Cloud Platform account which is configured to interact
with a particular SAP solution through standardized destinations, usually with identity propagation turned on.

Tip
For extension accounts, we recommend that you change the default SAP HANA Cloud Platform role provider to
the one of the extended SAP solution. Thus you channel all role assignment calls to the underlying extended

1062

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SAP system. For more information about changing the default role provider, see: Changing the Default Role
Provider [page 1290]

Extension application layers


An extension application consists of several layers. It usually has a front-end UI layer decoupled from the back end
by OData, REST, or JSON services.
To achieve smooth retheming and rebranding, you can use SAPUI5 for implementing the UI layer. However, you
can also use any HTML5 or JavaScript UI framework.
The extension application back end includes existing SAP solution services, or can expose custom services
delivered with the extension application on SAP HANA Cloud Platform.

Related Information
Extension Application Front End [page 1063]
Extension Application Back End [page 1065]

1.6.1.1

Extension Application Front End

An extension application usually consists of several layers. There is a front-end UI layer decoupled from the back
end by OData, REST, or JSON services.
To achieve smooth retheming and rebranding, you implement the front end UI layer using SAPUI5. You can also
use any HTML5 or JavaScript UI framework.
SAP HANA Cloud Platform offers various tools and capabilities to help you create, customize, and integrate your
extension front-end components.
The following artifacts are part of the UI package and delivered with the extension:
Content the actual business application wrapped as a widget or a tile
Structure navigation, pages, layout, templates, and themes, and other
Metadata metadata such as configuration information
Mobile client - either a native client wrapping an HTML5 UI or a truly native mobile client

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1063

The following graphic provides an overview of the building blocks of the extension application front end:

Extensions usually aggregate data from multiple different business systems by combining multiple application
widgets on one or multiple pages. If you have to combine data and need to apply additional security checks, then
you usually define a higher level back-end services in Java or XS, aggregating the required data and exposing it
with a new REST, JSON or OData API to the UI tier.
The extension application UI can be based on the solutions native UI technology (by leveraging solution-native
genarted UIs) or on HTML5. The latter can either be served out of the Java or XS layer or most commonly, can
leverage the SAP HANA Cloud Platform HTML5 application infrastructure, thus ensuring clear decoupling
between UI and back-end services.

Native customization
There are different native custumization options available with the SAP solutions. Most commonly, you can adjust
the user interface by changing the initial product configuration, by adjusting object metadata, by manipulating
field and operation visibility or by defining custom business objects. These customization options do not require
any coding on the frond-end tier since the resulting UI is generated natively in the extended solution.

1064

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SAPUI5 UI
To achieve smooth retheming and rebranding, you leverage SAPUI5 for the extension UI. SAPUI5 allows smooth
subsequent embedding of the custom UIs in the extended SAP solutions. The built-in extension and
customization mechanisms of SAPUI5 make it easy to replace standard views, to customize i18N resource texts,
to add new or to customize the existing navigation paths or even override existing code. Using SAPUI5 is a good
practice but you can also use other popular UI frameworks.

SAP HANA Cloud Portal


To achieve dynamic branding and retheming of extension UIs, we recommend that you use SAP HANA Cloud
Portal sites configured with a corresponding template to mimic the look and feel of the extended SAP solution.
Furthermore, SAP HANA Cloud Portal allows dynamic redesign of pages leveraging the portal authoring
environment.

SAP Web IDE


If you decide to go beyond pure configuration and customize the UI using SAPUI5, a natural choice would be SAP
Web IDE. SAP Web IDE helps you develop, test, and deploy SAPUI5 applications in your SAP HANA Cloud
Platform account, and expose your applications as widgets. It offers various extension templates such as SAPUI5
templates which you can use to start with. Based on the OData services of the extended solution and on their
metadata, you can start creating and adjusting the new user interface. SAP Web IDE comes with a source code
editor that helps you fine tune the generated HTML code on your own, leveraging code completion.

Related Information
UI development toolkit for HTML5 (SAPUI5)
HTML5: Development [page 1040]
SAP Web IDE [page 88]
SAP HANA Cloud Portal

1.6.1.2

Extension Application Back End

The extension application back end includes existing SAP solution services, or it can expose custom services
delivered with the extension application on SAP HANA Cloud Platform. Usually, the back end is decoupled from
the front end by OData, REST, or JSON services.
The extension application back end comprises the following artifacts:
Active business logic, including both the content content and the security checks

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1065

Persistency layer
Connectivity to one or more back-end systems

Business logic
The clearly decoupled business logic makes it easier to develop, test and operate extension applications on SAP
HANA Cloud Platform. It also enables the implementation of concepts such as zero-downtime updates, A/B
testing for UI, and other. It ensures that all security checks are performed on the right level, leaving no space for
error of putting business logic in the UI tier. Extension applications can leverage any available SAP HANA Cloud
Platform runtime. However, the level of integration of the different runtimes may vary. The list of features whose
support may vary depending on the runtime includes but is not limited to automatic application provisioning, roles
and identity propagation, auto-discovery of different application-bundled artifacts.
Extension applications benefit from the security model provided by both SAP HANA Cloud Platform and the
extended SAP solution. The security frame comprises automatic roles and permissions import, usage of SAP
solution-native admin tools, transparency on roles permission assignment, consistent administration experience.
By leveraging all the available platform services, extension applications will benefit from the account-levelhave
Single Sign-On with the extended solution. For some of the SAP solutions (for example, SuccessFactors), it is
possible to turn on native management of permissions and roles using the solution-native administration tools.
This is implemented by changing the default SAP HANA Cloud Platform role provider. Essentially, extension
applications use the available runtime-specific standard mechanisms to check for role assignment and SAP HANA
Cloud Platform transparently performs the assignment check in the underlying extended SAP solution.
In the scenario where the extended solution does not come with an embedded identity provider (IdP), we use the
SAP Cloud Identity service as a central point for managing trust and user authentication. By using the IdP-proxy
feature of SAP Cloud Identity service, you can define your own identity provider.
The following graphic provides an overview of the business logic of the extension application back end:

1066

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Persistency
The persistency layer is an essential aspect that needs to be considered when developing an extension
application. There are several options for storing data offered by SAP HANA Cloud Platform, including both
relational (for example, SAP HANA and Sybase ASE as offered by persistence service) and unstructured
(document service) data storage options. Thus, the various storage needs of the extension applications can be
covered.
It is also possible to store data in the extended SAP solution in the form of custom field or custom business
objects. This option varies for the different extended solutions. Custom business objects, however, are usually
limited both in volume and in number.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1067

The following graphic provides an overview of the persistency options for the extension applications:

Connectivity
One of the most critical layers for the SAP HANA Cloud Platform extension concept is the connectivity layer. It
connects an extension application to the extended SAP solution and to other required backend systems. The
connectivity is accomplished through a set of standardized destinations. All back-end calls are performed on
behalf of the user who is logged on to the extension front-end layer. To implement that, SAP HANA Cloud Platform
leverages SAML 2.0 bearer assertion authentication flow. The standardized destination names allow the
portability of partner applications - partner extension applications can expect to be installed in an environment
where the required destinations are in place and can be used. For more information about the standardized
destinations, see solution-specific section.
It is also possible to have destinations configured to use basic authentication or other authentication means.
However, we do not recommend the use of service users or a hard-coded user for back-end calls because the
back-end systems will not be able to perform user-based authorization checks. Furthermore, using service users
makes the end-to-end traceability very hard to achieve.
The following graphic provides an overview of the connectivity layer.

1068

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Caution
Extension applications work with your critical business data. Therefore, you must use only applications that
come from a trusted application provider. Always make sure that the extension application complies with the
common security best practices and fulfills data confidentiality and data protection requirements defined for
your organization. Do not deploy or allow access of untrusted applications to your mission-critical back-end
systems.

Related Information
Persistence Service [page 720]
Document Service [page 545]
Connectivity Service [page 267]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1069

1.6.2 Extending SuccessFactors


You can extend the scope of SuccessFactors HCM Suite using SAP HANA Cloud Platform extension applications.

Overview
SAP HANA Cloud Platform, extension package for SuccessFactors allows you to extend your SuccessFactors
scope with applications running on the platform. The extension package makes it quick and easy for companies to
adapt and integrate SuccessFactors cloud applications to their existing business processes, thus helping them
maintain competitive advantage, engage their workforce and improve their bottom line.
The extension package for SuccessFactors delivers the in-memory computing speed of SAP HANA Cloud and
includes capabilities from the SuccessFactors metadata framework (MDF) and SAP HANA Cloud Platform for
extension development. This combination of technologies makes it easier for SuccessFactors customers,
partners, and developers to extend cloud or on-premises applications, build entirely new cloud applications, and
enable new processes that meet unique business needs. Therefore, you can use the SAP HANA Cloud Platform,
extension package for both internal custom development based on the provided SuccessFactors APIs and for
running certified extension applications provided by SAP partner companies.

Extensibility layers
With SuccessFactors, you have the following extensibility layers:
Application Data Model
This layer constitutes a SuccessFactors extensibility solution which uses SuccessFactory to modify XML
abstraction layer. It allows you to extend delivered objects by configuring labels, required fields, pick lists, and
adding customer fields and so on.
MDF
This extensibility layer allows you to extend SuccessFactors applications from within the application or SAP
HANA Cloud Platform. You extend the applications using configuration and rules engine UI. You use delivered
objects to create extensions and logic. The extensions you create are tightly coupled with EC entities and
theres is no duplication of data. They can be consumed both from within EC and SAP HANA Cloud Platform.
SAP HANA Cloud Platform
The platform provides a complete Java-based development and hosting environment. It allows you to create
new applications, recreate your custom applications, and easily extend existing applications. You can leverage
MDF custom objects and share them across extensions, accessing them using OData APIs.

1070

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Integration between MDF and SAP HANA Cloud Platform


Using MDF, you can develop custom objects, automatically expose them to SAP HANA Cloud Platform, and
enable them for social media and mobile apps. This allows you to quickly define the data layer inside the
SuccessFactors HCM suite. You can then access that data layer and build on top of it by defining complex
application logic and creating a feature-rich user interface in SAP HANA Cloud Platform.
With MDF you can create the precise functionality needed to your company's unique business requirements. You
can easily maintain and update the functionality as needed throughout the application lifecycle. You can also
integrate changes into your existing business processes, since every MDF object comes ready with an OData API
that can both read and write data.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1071

Standard extension destinations


Developers can leverage the following HTTP connectivity destinations pointing to SuccessFactors:
Table 322: Destinations
Name

Protocol

Description

sap_hcmcloud_core_odata

OData

OData API of SuccessFactors HCM


Suite, exposing both standard and cus
tom business objects. This is the default
API to be used for interactive extension
applications.

sap_hcmcloud_core_soap

SOAP

Provides connectivity to the SF API of


SuccessFactors HCM Suite. It is mostly
used for system-to-system mass repli
cation of data.

Note
You create the destination manually.
You use the

ConnectivityConfiguration
API for accessing the destination
configuration. For more information,
see ConnectivityConfiguration API
[page 275]

Supported APIs
You can find a list and implementation details of the APIs supported by SuccessFactors HCM Suite on SAP Help
Portal, at http://help.sap.com/hr_api/.

Related Information
SAP HANA Cloud Platform, Extension Package for SuccessFactors (Implementation Guide)
Destinations [page 281]
Installing and Configuring Extension Applications (Beta) [page 1075]

1072

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.1

Creating an Integration Token

You create an integration token required for the automated configuration of SAP HANA Cloud Platform extension
package for SuccessFactors.

Prerequisites
Note
This functionality is available for SAP SuccessFactors HCM Suite Q2 2016 release and higher.
You have the Administrator role for any of the SAP HANA Cloud Platform accounts associated with the global
account to which the newly created extension account will be assigned during the automated configuration of SAP
HANA Cloud Platform extension package for SuccessFactors.

Context
To initiate the automated configuration of the SAP HANA Cloud Platform extension package for SuccessFactors,
the SuccessFactors administrators with Provisioning access need an integration token. The integration token
determines the SAP HANA Cloud Platform users who will be initially authorized to deploy and administer the
extension applications in the SAP HANA Cloud Platform extension account created during the automated
configuration. The token also determines the SAP HANA Cloud Platform landscape and the global account from
which the respective resources will be consumed.
As an SAP HANA Cloud Platform user with permissions for the respective global account, you create the
integration token using the SAP HANA Cloud Platform cockpit, and then pass it over to the SuccessFactors
administrator.

Procedure
1. In your Web browser, open the SAP HANA Cloud Platform cockpit using the URLs given below. Use the
relevant URL for the region with which your customer account is associated:
Europe: https://account.hana.ondemand.com/cockpit
United States: https://account.us1.hana.ondemand.com/cockpit (US East), and https://
account.us2.hana.ondemand.com/cockpit (US West)
Asia-Pacific (Australia): https://accounts.ap1.hana.ondemand.com/cokpit
2. Select the relevant global account, and then choose Integration Tokens in the navigation area.
3. In the Integration Tokens panel, choose Create Token.
The Create Integration Token dialog box opens.
4. Enter the SAP user IDs of the users whom you want to authorize to deploy and administer the extension
applications in the SAP HANA Cloud Platform extension account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1073

To separate the user IDs, use commas, spaces, semicolons, or line breaks.
Your user and the users you have entered will be assigned the Administrator role for the extension account
created during the automated configuration of the SAP HANA Cloud Platform extension package for
SuccessFactors.
5. Choose Create.
Your newly created token appears in the list of integration tokens and its status is ACTIVE. In the Integration
Tokens panel, you can view details such as the user who has created the token, the creation date and the
expiration date.

Note
The integration token can be used only once. Once the integration token is used, it is no longer valid.
6. (Optional) You can perform the following actions:
To view the integration token value and the SAP user IDs assigned to this token, choose View in the
Actions column on the row of the respective token.
To delete an integration token, choose Delete in the Actions column on the row of the respective token.

Results
You have created an integration token which you can use to initiate the automated configuration of the SAP HANA
Cloud Platform extension package for SuccessFactors.

Note
Make sure to use the integration token before its expiration date.

Next Steps
You can now pass over the value of the token to the SuccessFactors administrator who will be triggering the
automated configuration of the SAP HANA Cloud Platform, extension package for SuccessFactors. For more
information, see the Configuring Extension Package for SuccessFactors Automatically section in SAP HANA Cloud
Platform, Extension Package for SuccessFactors Implementation Guide .

Related Information
Accounts [page 11]

1074

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2

Installing and Configuring Extension Applications


(Beta)

As an implementation partner, you install and configure the extension applications that you want to make
available for customers.

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
You deploy your extension application, configure its connectivity to the SuccessFactors system and map the roles
defined in your extension application to the roles in the corresponding SuccessFactors system.

Prerequisites
You have an SAP HANA Cloud Platform extension account and the corresponding SuccessFactors customer
instance connected to it. Your account has been onboarded with the SAP HANA Cloud Platform Extension
Package for SuccessFactors. For more information, see the Configuring Extension Package for
SuccessFactors Automatically section in the SAP HANA Cloud Platform, Extension Package for
SuccessFactors Implementation Guide
You have the quota purchased for the corresponding global account assigned to the SAP HANA Cloud
Platform extension account. See Managing Accounts and Quota [page 17].
You are an administrator of the SAP HANA Cloud Platform extension account.
You have a SuccessFactors administrator user with one of the following permission sets assigned to it:
General Admin and System Admin permissions
or
Company System and Logo Settings permissions
You have the role-based permissions enabled for the SuccessFactors customer instance.
When creating the extension application, you have defined the required roles in the web.xml file of the
application.
In the SuccessFactors system, you have created or imported roles with the same names as those defined in
the application web.xml.
You have the required permissions grouped into SuccessFactors role definitions.
You have the WAR file of your application.

Process Flow
You deploy your extension application in your SAP HANA Cloud Platform extension account and create the
resource file with role definitions. You also need to configure the application connectivity to SuccessFactors and
to enable the use of the HCM Suite OData API. To ensure that only approved applications are using the
SuccessFactors IdP for authentication, you need to register the extension application as an authorized assertion
consumer service in SuccessFactors. Then you you register the extension application home page tiles and import
the extension application roles in the SuccessFactors customer instance connected to the extension account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1075

To finalize the configuration on SAP HANA Cloud Platform side, you change the default role provider to the
SuccessFactors one. To finalize the configuration on SuccessFactors side, you assign user groups to the
permission roles defined for your extension application.
Table 323:
Task

Description

1. Deploy Your Extension Application on the Cloud [page


1077]

Deploy the extension application in your extension account on


SAP HANA Cloud Platform.

2. Create the Resource File with Role Definitions [page 1078]

Ccreate the reosource file containing the SuccessFactors


HCM role definitions.

3. Register the Extension Application as an Authorized Asser


tion Consumer Service [page 1081]

Register the extension application as an authorized assertion


consumer service.

4. Configure the Extension Applications's Connectivity to Suc


cessFactors [page 1083]

Configure the connectivity between your Java extension appli


cation and the SuccessFactors system associated with your
SAP HANA Cloud Platform extension account.

Note
This task is relevant for Java extension applications only.
5. Register a Home Page Tile for the Extension Application
[page 1086]

Register a home page tile for the extension application in the


extended SuccessFactors system

6. Import the Extension Application Roles in the SuccessFac


tors System [page 1090]

Import the application-specific roles from the SAP HANA


Cloud Platform system repository into to the SuccessFactors
customer instance connected to your extension account.

7. Assign the Extension Application Roles to Users [page


1092]

Assign the extension application roles you have imported in


the SuccessFactors systems to the user to whom you want to
grant access to your application.

8. Enable SuccessFactors Role Provider [page 1093]

Change the default SAP HANA Cloud Platform role provider of


your Java application to the SuccessFactors role provider.

Note
This task is relevant for Java extension applications only.
9. Test the Role Assignments [page 1095]

1076

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Try to access the application with the users with different level
of granted access to test the role assignements.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2.1

Deploy Your Extension Application on the Cloud

You deploy the extension application in your extension account on SAP HANA Cloud Platform so that you can run
it and integrate it in SuccessFactors.

Prerequisites
You have the WAR file of the extension application you want to deploy.
The WAR file contains the ZIP archive of the application site, as well as the <application_name>.spec.xml
file describing the corresponding widgets. For an example of a site ZIP archive and structure, see the Get the
Source Code section in

https://github.com/SAP/cloud-sfsf-benefits-ext

You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client.

Context
You deploy the extension applications using the SAP HANA Cloud Platform console client. The applications are
deployed in the customer account on the same production landscape where the SAP HANA Cloud Portal is
deployed. The production landscape is available on a regional basis, where each region represents the location of
a data center. When deploying applications, bear in mind that a customer is associated with a particular region
and that this region is independent of your own location. You could be located in the United States, for example,
but operate your account in Europe (that is, use a data center that is situated in Europe). For more information
about the available landscape hosts, see Landscape Hosts [page 32].

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. To deploy the extension application, execute the following command:
neo deploy --host <landscape_host> --account <account_name> --application
<application_name> --source <WAR_file_location> --user <e-mail_or_user>
3. Enter your password if requested.
4. Press ENTER and the deployment of your application will start. If deployment fails, check if you have defined
the parameters correctly.

Results
You have deployed the extension application in you extension account on the SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1077

Related Information
Deploying Applications

1.6.2.2.2

Create the Resource File with Role Definitions

You create the resource file containing the SuccessFactors HCM role definitions.

Prerequisites
The corresponding SuccessFactors HCM Suite roles exist in the SuccessFactors system.
You have admin access to the SuccessFactors OData API and have a valid account with user name and
password. For more information, see http://help.sap.com/saphelpiis_cloud4hr/EN/
SF_HCMS_OData_API_User_en/frameset.htm?4006ecf7444e4bc4aaa18c2364519126.html.

Context
To create the resource file with the role definitions required for your application, you use the SuccessFactors
OData API to query the permissions defined for this role, and create a roles.json file containing the role
definitions. You use HTTP Basic Authentication for the OData API call.

Procedure
1. Call the OData API to query the permissions defined for the required role using the following URL:
https://<host_name>/odata/v2/RBPRole?$filter=roleName eq '<role_name>'&
$expand=permissions&$format=json
Where:
<host_name> is the fully qualified domain name of the OData API host depending on the data center
hosting your SuccessFactors instance. For more information about the OData API endpoints, see http://
help.sap.com/saphelpiis_cloud4hr/EN/SF_HCMS_OData_API_User_en/frameset.htm?
03e1fc3791684367a6a76a614a2916de.html.
<role_name> is the name of the role as defined in the SuccessFactors system.
The response is a JSON object containing the following properties for each of the permissions defined for the
specified role:

1078

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 324:
Property

Include in roles.json

Description

permissionID

No

(Key)Permission Id, the sequence id in permission table

permissionType

Yes

Permission_Type column

permissionStringValue

Yes

Permission_string_value column

permissionLongValue

Yes

Permission_long_value column

Example response
{

"d": {
"__metadata": {
"uri": "https://localhost:443/odata/v2/RBPRole(82L)",
"type": "SFOData.RBPRole"
},
"roleId": "82",
"roleDesc": "Testing role permissions",
"lastModifiedBy": "admin",
"lastModifiedDate": "\/Date(1404299328000)\/",
"roleName": "Test Role Permissions",
"userType": "null",
"permissions": {
"results": [{
"__metadata": {
"uri": "https://localhost:443/odata/v2/
RBPBasicPermission(60L)",
"type": "SFOData.RBPBasicPermission"
},
"permissionId": "60",
"permissionType": "user_admin",
"permissionStringValue": "change_info_user_admin",
"permissionLongValue": "-1"
},
{

"__metadata": {
"uri": "https://localhost:443/odata/v2/
RBPBasicPermission(4L)",
"type": "SFOData.RBPBasicPermission"
},
"permissionId": "4",
"permissionStringValue": "detail_report",
"permissionLongValue": "-1",
"permissionType": "report"
}]
]
}
}
}
2. Create a roles.json file using the following properties:
Table 325:
Property

Description

roleName

Name of the role as defined in the response to the OData API call

roleDesc

Role description as defined in the response to the OData API call

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1079

Property

Description

permissionType

Value of the permissionType property as defined in the response to the


OData API call

permissionStringValue

Value of the permissionStringValue property as defined in the response


to the OData API call

permissionLongValue

Value of the permissionLongValue property as defined in the response to


the OData API call

Target roles.json file


[{

}]

}]

"roleDesc": "Testing role permissions",


"roleName": "Test Role Permissions",
"permissions": [{
"permissionStringValue": "change_info_user_admin",
"permissionLongValue": "-1",
"permissionType": "user_admin"
},
{
"permissionStringValue": "detail_report",
"permissionLongValue": "-1",
"permissionType": "report"

3. Save the file locally.

Results
You have created the role definition resource file.

Next Steps
Import the role definition resource file in the SAP SuccessFactors system connected to your extension account.
For more information, see Import the Extension Application Roles in the SuccessFactors System [page 1090].

1080

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2.3

Register the Extension Application as an


Authorized Assertion Consumer Service

Register the extension application as an authorized assertion consumer service to configure its access to the
SuccessFactors system through the SuccessFactors identity provider (IdP).

Prerequisites
Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
You have made yourself familiar with the SAP HANA Cloud Platform console client. For more information, see
Console Client
The extension application is started. For more information about starting an application deployed in an SAP
HANA Cloud Platform account, see start
You have the SAP HANA Cloud Platform trust settings configured and the SuccessFactors IdP is registered as
a trusted IdP. For more information, see the Configuring SAP HANA Cloud Platform Trust Settings section in
the SAP HANA Cloud Platform, Extension Package for SuccessFactors Implementation Guide
The SAP HANA Cloud Platform account in which you configure the connectivity to the SuccessFactors
system is an extension account. For more information about extension accounts, see Basic Concepts

Context
Extension applications deployed in an SAP HANA Cloud Platform extension account are authenticated against the
SuccessFactors (IdP). To ensure that only approved applications are using the SuccessFactors IdP for
authentication, you need to register the extension application as an authorized assertion consumer service,
configure the application URL, the service provider audience URL and the service provider logout URL of the
extension application in SuccessFactors Provisioning. To do so you use the hcmcloud-enable-applicationaccess console client command.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. Register the extension application as an authorized assertion consumer service. In the console client
command line, execute: hcmcloud-enable-application-access, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1081

For example, to register a Java extension application running in your account in the US East data center,
execute:
neo hcmcloud-enable-application-access --application <my_application> -application-type java --account <my_extension_account> --user
<my_email@example.com> --host us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to register a Java extension application to which your account in the US East data center is
subscribed, execute:
neo hcmcloud-enable-application-access --application
<application_provider_account:my_application> --application-type java -account <my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
3. (Optional) Display the status of an application entry in the list of authorized assertion consumer services for
the SuccessFactors system associated with an extension account. In the console client command line,
execute hcmcloud-display-application-access, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to display the status of the authorized assertion consumer service entry for an application
deployed in your account in the US East data center, execute:
neo hcmcloud-display-application-access-status --application <my_application>
--account <my_extension_acc> --user <my_email@example.com> --host
us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to display the status of the authorized assertion consumer service entry for an application
to which your account in the US East data center is subscribed, execute:
neo hcmcloud-display-application-access-status --application
<application_provider_account>:<my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
4. (Optional) If your scenario requires it, remove the entry of the exetsnion application from the list of authorized
assertion consumer services for the SuccessFactors system associated with the extension account. In the
console client command line, execute hcmcloud-disable-application-access, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to remove the authorized assertion consumer service entry for a Java application deployed
in your account in the US East data center, execute:
neo hcmcloud-disable-application-access --application <my_application> -application-type java --account <my_extension_acc> --user
<my_email@example.com> --host us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.

1082

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For example, to remove the authorized assertion consumer service entry for a Java application to which
your account in the US East data center is subscribed, execute:
neo hcmcloud-disable-application-access --application
<application_provider_account>:<my_application> --application-type java -account <my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com

Related Information
hcmcloud-enable-application-access (Beta) [page 172]

1.6.2.2.4

Configure the Extension Applications's


Connectivity to SuccessFactors

Use this procedure to configure the connectivity between your Java extension application and the SuccessFactors
system associated with your SAP HANA Cloud Platform extension account.

Prerequisites

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
If you configure access to the HCM Suite OData API, you must have the OData API enabled for your
SuccessFactors company instance in Provisioning. For more information, see theOData API Programmer's
Guide, available on SAP Help Portal at http://help.sap.com/cloud4hr .
You have made yourself familiar with the SAP HANA Cloud Platform console client. For more information, see
Console Client
You have the SAP HANA Cloud Platform trust settings configured and the SuccessFactors IdP is registered as
a trusted IdP. For more information, see the Configuring SAP HANA Cloud Platform Trust Settings section in
the SAP HANA Cloud Platform, Extension Package for SuccessFactors Implementation Guide .
You have the role-based permissions enabled for the SuccessFactors company instance.
The SAP HANA Cloud Platform account in which you configure the connectivity to the SuccessFactors
system is an extension account. For more information about extension accounts, see Basic Concepts
Your application runtime supports destinations. For more information about the application runtimes
supported by SAP HANA Cloud Platform, see Application Runtime Container

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1083

Context
Note
This procedure is relevant only for Java extension applications.
The extension applications interact with the extended SuccessFactors system using the HCM Suite OData API.
The HCM Suite OData API is a RESTful API based on the OData protocol intended to enable access to data in the
SuccessFactors system. You have the following API access scenarios:
OData access with SAML2BearerAssertion authentication
This scenario is used for performing OData API calls with logged-in user propagation, thus enforcing
permission checks for accessing objects.
OData access with SAML2BearerAssertion authentication and a technical user
This scenario is used for performing OData API calls with a predefined technical user when the extension
application is performing scheduled jobs or data replication.
To enable the API access and configure the connectivity between the Java extension applications and the
SuccessFactors sytem associated with your extension account, you use the hcmcloud-create-connection
console client command. Using the command, you specify the connection details for the remote communication
of the extension application and create the HTTP destinations required for configuring the API access. The
command also creates and configures the corresponding OAuth clients in the SuccessFactors company instance.
The command uses the following predefined destination names for the different connection types:
Table 326:
Connection Type

Destination

OData

sap_hcmcloud_core_odata

OData with technical user

sap_hcmcloud_core_odata_service

If your scenario requires it, you can two connections for an extension application as long as the type of the
connections differs.
Depending on whether the extension application is deployed in your account or your account is subscribed to the
extension application, you configure the connectivity on an application level in the account where the application
is deployed, or on a subscription level in the account subscribed to the application.
You can optionally list the connections created for the extension application:

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. Configure the connectivity. In the console client command line, execute hcmcloud-create-connection, as
follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.

1084

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

For example, to create a connection of the OData type for an application deployed in your account in the
US East data center, execute:
neo hcmcloud-create-connection --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to configure a connection of the OData type for an application to which your account in the
US East data center is subscribed, execute:
neo hcmcloud-create-connection --application
<application_provider_account:my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
3. (Optional) List the connections created for the extension application. In the console client command line,
execute hcmcloud-list-connections, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to list the connections for an application deployed in your account in the US East data
center, execute:
neo hcmcloud-list-connections --application <my_application> --account
<my_extension_acc> --user <my_email@example.com> --host us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<app_provider_account>:<my_app>.
For example, to list the connections for an application to which your account in the US East data center is
subscribed, execute:
neo hcmcloud-list-connections --application
<application_provider_account>:<my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
4. (Optional) If your scenario requires it, remove the connectivity configured between your extension application
and the SuccessFactors systems associated with the extension account. In the console client command line,
execute hcmcloud-delete-connection, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to remove a connection of the OData type for an application deployed in your account in the
US East data center, execute:
neo hcmcloud-delete-connection --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com --name sap_hcmcloud_core_odata
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<app_provider_account>:<my_app>.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1085

For example, to remove a connection of type OData with technical user for an application to which your
account in the US East data center is subscribed, execute:
neo hcmcloud-delete-connection --application
<application_provider_account:my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com --name sap_hcmcloud_core_odata_technical_user

Related Information
hcmcloud-delete-connection (Beta) [page 167]
hcmcloud-create-connection (Beta) [page 166]

1.6.2.2.5

Register a Home Page Tile for the Extension


Application

You register a home page tile for the extension application in the extended SuccessFactors system so that you
can access the application directly from the SuccessFactors Employee Central (EC) home page.

Prerequisites
Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
You have deployed and started the extension application for which you are registering the home page tile
You have registered the extension application as an authorized assertion consumer service. For more
information, see Register the Extension Application as an Authorized Assertion Consumer Service [page
1081]
You have the home page tile provided as part of the application interface
You develop the content of the tile as a dedicated HTML page inside the application and size it according to
the desired tile size. You describe the tiles in a tiles.json descriptor and package them in a ZIP archive.
For more information about the structure of the tiles.json descriptor, see tiles.json [page 1089].
You have created the tiles.json descriptor.

Context
The SuccessFactors EC home page provides a framework that allows different modules to provide access to their
functionality using tiles. For the extension applications hosted in the SAP HANA Cloud Platform extension

1086

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

account, SAP HANA Cloud Platform allows you to register home page tiles in the extended SuccessFactors
system. To do so you use the hcmcloud-register-home-page-tiles console client command. Both Java and
HTML5 extension applications are supported.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. Register the SuccessFactors EC home page tiles in the SuccessFactors company instance linked to the
specified SAP HANA Cloud Platform account. In the console client command line, execute: hcmcloudregister-home-page-tiles, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to register a home page tile for a Java extension application running in your account in the
US East data center, execute:
neo hcmcloud-register-home-page-tiles --application <my_application> -application-type java --account <my_extension_account> --user
<my_email@example.com> --host us1.hana.ondemand.com --location <path to the
tiles.json file>
For an application to which your account is subscribed, specify the application provider account and the
name of the extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to register a home page tile for a Java extension application to which your account in the US
East data center is subscribed, execute:
neo hcmcloud-register-home-page-tiles --application
<application_provider_account:my_application> --application-type java -account <my_extension_account> --user <my_email@example.com> -- host
us1.hana.ondemand.com --location <path to the tiles.json file>

Note
The size of the tile descriptor file must not exceed 100 KB.
3. (Optional) List the extension application home page tiles registered in the SuccessFactors company instance
associated with the extension account. In the console client command line, execute hcmcloud-getregistered-home-page-tiles, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to list the tiles registered for a Java extension application deployed in your account in the US
East data center, execute:
neo hcmcloud-get-registered-home-page-tiles --application <my_application> -application-type java --account <my_extension_acc> --user
<my_email@example.com> --host us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of the extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1087

For example, to list the tiles registered for a Java extension application to which your account in the US
East data center is subscribed, execute:
neo hcmcloud-get-registered-home-page-tiles --application
<application_provider_account>:<my_application> --application-type java -account <my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com

Note
If you do not specify the application parameter, the command returns all the tiles registered in the
SuccessFactors EC home page of the SuccessFactors company instance linked to the extension account.
There is no lifecycle dependency between the tiles and the application, so the application may not be
started or may not be deployed anymore.
4. (Optional) If your scenario requires it, unregister the SuccessFactors EC home page tiles registered for the
extension application. In the console client command line, execute hcmcloud-unregister-home-pagetiles, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to unregister the SuccessFactors EC home page tiles for a Java application deployed in your
account in the US East data center, execute:
neo hcmcloud-unregister-home-page-tiles --application <my_application> -application-type java --account <my_extension_acc> --user
<my_email@example.com> --host us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to unregister the SuccessFactors EC home page tiles for a Java application to which your
account in the US East data center is subscribed, execute:
neo hcmcloud-unregister-home-page-tiles --application
<application_provider_account>:<my_application> --application-type java -account <my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com

Note
There is no lifecycle dependency between the tiles and the application, so the application may not be
started or may not be deployed anymore.

1088

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2.5.1 tiles.json
The tiles.json descriptor contains the definition of the home page tiles for the extension application.

Properties
Table 327:
Required

name

Internal name of the tile used to identify it

path

Relative path to the application resource containing tile contents

size

Size of the tile

Default: 1
Accepted values:

padding

1 - medium

2 - large

3 - extra large

Defines whether to add padding around the tile and the application tile content

Default: false
Accepted values: false, true
metadata

Defines the localized tile title and description. If you do not define this parameter, the
framework displays the value of the name parameter to the users.

title

Localized tile title

locale

The locale to which the tile metadata applies

Table 328:
Optional

description

Localized description of the tile

Note
The tiles.json descriptor file must use UTF-8 encoding and its size must not exceed 100 KB.

Example
[

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1089

},
{

"name" : "MyMediumTile",
"path" : "mediumTile.html",
"size" : 1,
"padding" : false,
"roles" : ["Recruiters", "Administrators"],
"metadata" : [{
"title" : "My medium home page tile",
"description" : "This is my medium home page tile",
"locale" : "en_US"
}, {
"title" : "Meine mittelgroe Homepage-Kachel",
"description" : "Das ist meine mittelgroe Homepage-Kachel",
"locale" : "de"
}]
"name" : "MyLargeTile",
"path" : "largeTile.html",
"size" : 2,
"padding" : false,
"roles" : ["Administrators"],
"metadata" : [{
"title" : "My large home page tile",
"description" : "This is my large home page tile",
"locale" : "en_US"
}, {
"title" : "Meine groe Homepage-Kachel",
"description" : "Das ist meine groe Homepage-Kachel",
"locale" : "de"
}]

1.6.2.2.6

Import the Extension Application Roles in the


SuccessFactors System

To complete the authorization configuration of your extension application, you import the application-specific
roles into to the SuccessFactors company instance connected to your extension account.

Prerequisites

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
You have created the resource file with the required role definitions. For more information, see Create the
Resource File with Role Definitions [page 1078].
You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client.

1090

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Using the hcmcloud-import-roles console client command, you import the required role definitions in the
SuccessFactors company instance connected to this account.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. Execute the following command:
neo hcmcloud-import-roles --account <account_name> --user <e-mail_or_user> -host <landscape_host> --location <path to the file containing role definitions>

Note
The size of the file containing the role definitions must not exceed 500 KB.
3. Enter your password if requested.
4. Press ENTER and the import of the role definitions starts.

Results
You have imported the application-specific roles in the SuccessFactors company instance connected to your
account. Now you need to assign users to these roles.

Related Information
Assign the Extension Application Roles to Users [page 1092]
hcmcloud-import-roles (Beta) [page 176]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1091

1.6.2.2.7

Assign the Extension Application Roles to Users

To complete the authorization configuration for your extension application, you assign the extension application
roles you have imported in the SuccessFactors systems to the user to whom you want to grant access to your
application.

Prerequisites
You have a role-based permission environment for your SuccessFactors company instance
Your have either a Super Administrator or a Security Admin user for SuccessFactors and have access to the
functionality on the SuccessFactors Admin page
You have deployed the extension application

Context
Use this procedure to assign the permission roles to users.

Procedure
1. Log on to SuccessFactors with the following URL:
https://<SuccessFactors_landscape>/login
Where <SuccessFactors_landscape> is the fully qualified domain name of the host on which the
SuccessFactors company is running.
2. Navigate to the Manage Permission Roles, as follows:
For Version 12 UI Framework (Revolution) not enabled: Navigate to:

Admin Center

Manage Security

Manage Permission Roles .


For Version 12 UI Framework (Revolution) enabled: Navigate to:
Set User Permissions

Admin Center

Manage Employees

Manage Permission Roles .

3. Locate the role you want to manage, and from the Take Action dropdown box next to the role, select Edit.
4. On the Permission Role Detail page, scroll down to the Grant this role to...section, and then choose Add. The
system opens the Grant this role to... page.
5. On the Grant this role to... page, define whom you want to grant this role to, and specify the target population
accordingly.
6. To navigate back to the Permission Role Detail page, choose Done.
7. Save your entries.

1092

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2.8

Enable SuccessFactors Role Provider

If you have SAP HANA Cloud Platform extension package for SuccessFactors configured for your account, you
can change the default SAP HANA Cloud Platform role provider of your Java application to the SuccessFactors
role provider.

Prerequisites

Note
This is a beta feature available for SAP HANA Cloud Platform extension accounts. For more information about
the beta features, see Using Beta Features in Accounts [page 22].
You have an SAP HANA Cloud Platform extension account. For more information about extension accounts,
see Basic Concepts
You are an administrator of your SAP HANA Cloud Platform account
You have configured the Java extension application's connectivity to the SuccessFactors sytem associated
with the extension account. For more information, see Configure the Extension Applications's Connectivity to
SuccessFactors [page 1083].
In the SuccessFactors system, you have created or imported roles with the required permissions and these
roles are with the same names as those defined in the web.xml file of the extension application.
For more information abou importing roles, see Import the Extension Application Roles in the SuccessFactors
System [page 1090].
For more information about creating permission roles in SuccessFactors, see the How do you create a
permission role? section in Role-Based Permissions Administration Guide.
In the SuccessFactors system, you have assigned the required roles to the corresponding users and groups.
For more information, see Assign the Extension Application Roles to Users [page 1092].
When creating the extension application, you have defined the required roles in the web.xml file of the
application and these roles are the same as the ones you have for the application in the SuccessFactors
system. For more information about how to define roles in the web.xml file of the application, see Enabling
Authentication.

Context
A role provider is the component that retrieves the roles for a particular user. By default, the role provider used for
SAP HANA Cloud Platform applications and services is the SAP HANA Cloud Platform role provider. For Java
extension applications, however, you have to change the default role provider to the provider of the corresponding
system. For Java extension applications for SuccessFactors you change the default role provider to the
SuccessFactors role provider. To change the role provider for a Java exetension application for SuccessFactors
automatically, use the hcmcloud-enable-role-provider console client command.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1093

Note
Currently, the automated change of the role provider is available only for Java extension applications for
SuccessFactors.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (SDK installation folder/tools).
2. Enable the SuccessFactors role provider for your Java extension application. Execute: hcmcloud-enablerole-provider, as follows:
For an application deployed in your account, specify the name of your extension application for the
application parameter.
For example, to enable the SuccessFactors role provider for a Java extension application running in your
account in the US East data center, execute:
neo hcmcloud-enable-role-provider --application <my_application> --account
<my_extension_account> --user <my_email@example.com> --host
us1.hana.ondemand.com
For an application to which your account is subscribed, specify the application provider account and the
name of your extension application for the application parameter in the following format:
<application_provider_account>:<my_application>.
For example, to enable the SuccessFactors role provider for a Java extension application to which your
account in the US East data center is subscribed, execute:
neo hcmcloud-enable-role-provider --application
<application_provider_account:my_application> --account
<my_extension_account> --user <my_email@example.com> -- host
us1.hana.ondemand.com

Related Information
hcmcloud-enable-role-provider (Beta) [page 173]
Changing the Default Role Provider [page 1290]

1094

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.6.2.2.9

Test the Role Assignments

To test the role assignments you first start the deployed extension application to make it available for requests,
and then try to access it with the users with different level of granted access to the application.

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client.
You have made yourself familiar with the SAP HANA Cloud Platform cockpit concepts. For more information,
see Cockpit

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Start the deployed application using the following command:
neo start --account <account_name> --application <application_name> --user <email_or_user> --host <landscape_host>
3. Access the application using users with different roles assigned to them.
To access the application, use the application URL. To get the login URL of an application deployed in your
extension account, open the SAP HANA Cloud Platform cockpit, and navigate to
<account_name>

Java Applications

Account

<name_of_your_extension_application>

Application

URLs .

1.7

Operate Applications

Table 329:
To learn about

See

How to configure and operate your deployed Java applications Java: Application Operations [page 1096]
How to monitor your SAP HANA applications

SAP HANA: Application Operations [page 1164]

How to monitor the current status of the HTML5 applications


in your account

HTML5: Application Operations [page 1171]

How to securely operate and monitor your cloud applications


connected to on-premise systems

Cloud Connector Operator's Guide [page 524]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1095

To learn about

See

How to change the default SAP HANA Cloud Platform applica

Configuring Application URLs [page 1182]

tion URL by configuring custom or platform domains.


How to enable transport of SAP HANA Cloud Platform appli

Change Management with CTS+ [page 1198]

cations via the CTS+.

1.7.1 Java: Application Operations


After you have developed and deployed your Java application on SAP HANA Cloud Platform, you can configure
and operate it using the cockpit, the console client, or the Eclipse IDE.
Table 330:
Content
Configuring Applications [page 1096]
Managing the Lifecycle of Deployed Applications [page 1097]
Monitoring [page 1098]
Profiling [page 1098]
Logging [page 1098]
Updating Productive Applications [page 1099]

Configuring Applications
Table 331:
Cockpit

Viewing Resource Consumption [page


1118]
Understanding the Runtime Information
[page 1117]

1096

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Console Client

Updating Application Properties [page

Specify various configurations using commands.

1101]
Choosing Application Runtime Version
[page 1101]
Choosing JRE Version [page 1103]
Enabling and Configuring Gzip Response
Compression [page 1104]
Configuring VM Arguments [page 1105]
Scaling Applications [page 1107]
Eclipse IDE

Advanced Application Configurations

Use the options for advanced server and application configu

[page 979]

rations as well as direct reference to the cockpit UI.

Managing the Lifecycle of Deployed Applications


Table 332:
Cockpit

Defining Application Details (Java Apps)

Start, stop, and undeploy applications, as well as start, stop,

[page 1109]

and disable individual application processes.

Starting and Stopping Applications


[page 1110]
Checking the Process Status [page
1112]
Viewing Resource Consumption [page
1118]
Console Client

start [page 240]; stop [page 244]; re

Manage the lifecycle of a deployed application or individual

start [page 218]

application processes by executing the respective command.

enable [page 158]; disable [page 147];


undeploy [page 254]
Eclipse IDE

Deploying Locally from Eclipse IDE [page Start, stop, republish and perform delta deploy of applica
975]

tions.

Deploying on the Cloud from Eclipse IDE


[page 977]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1097

Monitoring
Table 333:
Cockpit

Viewing Monitoring Metrics of Java Ap

View the current metrics of a selected process to check the

plications [page 1113]

runtime behavior of your applications.

Performance Statistics Service (Beta)

Get performance statistics metrics

[page 714]
Configuring Availability Checks for Java
Applications from the Cockpit [page

Configure availability checks


Subscribe an account to an application.

1153]
Managing Subscriptions [page 28]
Console Client

Configuring Availability Checks for Java

To monitor whether a deployed application is up and running,

Applications from the Console Client

register availability checks and JMX checks to receive notifica

[page 1154]

tions if the application goes down

Configuring a JMX Check to Monitor

Subscribe an account to an application.

Your Application [page 1157]


Subscribing an Account to an Applica
tion [page 1162]

Profiling
Table 334:
Eclipse IDE

Profiling Applications [page 1141]

Analyze resource related problems in your application.

Using Logs in the Cockpit [page 1137]

View the logs and change the log settings of any applications

Logging
Table 335:
Cockpit

deployed in your account.


Console Client

Eclipse IDE

1098

Using Logs in the Console Client [page

Manage some of the logging configurations of a started appli

1134]

cation.

Using Logs in the Eclipse IDE [page

View the logs and change the log settings of the applications

1131]

deployed in your account or on you local server.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Updating Productive Applications


Table 336:
Cockpit

Using Maintenance Mode for Planned

Supports zero downtime and planned downtime scenarios.

Downtimes [page 1123]

Disable the application or individual processes in order to shut

Soft Shutdown [page 1126]


Console Client

down the application or processes gracefully.

Updating Applications with Zero Down

Deploy a new version of a productive application or perform

time [page 1121]

maintenance.

Using Maintenance Mode for Planned


Downtimes [page 1123]
Soft Shutdown [page 1126]

1.7.1.1

Configuring Applications

As an operator, you can configure an SAP HANA Cloud Platform application according to your scenario.

Make specific application configurations during deploy


When you are deploying the application using SAP HANA Cloud Platform console client, you can specify various
configurations using the deploy command parameters:
Choosing Application Runtime Version [page 1101]
Enabling and Configuring Gzip Response Compression [page 1104]
Configuring VM Arguments [page 1105]
Choosing JRE Version [page 1103]

Update application properties


You can change the properties you specified during deployment.
Updating Application Properties [page 1101]

Scale your application


You can scale an application to ensure its ability to handle more requests.
Scaling Applications [page 1107]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1099

Configure identity and access management


Using the cockpit, you can perform the following identity and access management configuration tasks:
Managing Roles [page 1282]
ID Federation with the Corporate Identity Provider [page 1292]
Configuring OAuth 2.0 [page 1310]

Configure connectivity destinations


Using the cockpit and the console client, you can configure HTTP, Mail and RFC destinations to make use of them
in your applications:
Configuring Destinations from the Cockpit [page 301]
Configuring Destinations from the Console Client [page 283]

View and download log files


Using the cockpit and the console client, you can view and download log files of any applications deployed in your
account:
Using Logs in the Cockpit [page 1137]
Using Logs in the Console Client [page 1134]

Related Information
Cockpit [page 84]
Console Client [page 88]
Advanced Application Configurations [page 979]

1100

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.1.1

Updating Application Properties

You can update a property of an application running on SAP HANA Cloud Platform without redeploying it.

Context
Application properties are configured during deployment with a set of deploy parameters in the SAP HANA Cloud
Platrform console client. If you want to change any of these properties (Java version, runtime version,
compression, VM arguments, compute unit size, URI encoding, minumum and maximum application processes)
without the need to redeploy the application binaries, use the set-application-property command. Execute
the command separately for each property that you want to set.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation folder>/
tools).
2. Execute set-application-property specifying the new value of one property that you want to change.
For example, to change the compute unit size to premium, execute:
neo set-application-property myapp.properties --compute-unit prem
3. For the change to take effect, restart your application using the restart command.

Related Information
set-application-property [page 229]
deploy [page 141]
restart [page 218]
Deploying on the Cloud with the Cockpit [page 985]

1.7.1.1.2

Choosing Application Runtime Version

Applications deployed on SAP HANA Cloud Platform are always started on the latest version of the application
runtime container. This version contains all released fixes, critical patches and enhancements and is respectively
the recommended option for applications. In some special cases, you can choose the version of the runtime
container your application uses by specifying it with the parameter <--runtime-version> when deploying your
application. To change this version, you need to redeploy the application without specifying this parameter.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1101

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see Setting
Up the Console Client [page 42].

Context
If you want to choose the version of the application runtime container, follow the procedure.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation folder>/
tools).
2. In the console client command line, execute the <list-runtime-versions> command to display all
recommended versions. We recommend that you choose the latest available version.
3. Redeploy your application with parameter <--runtime-version> set to the selected version number.
neo deploy --account <account_name> --application <application_name> --source
<file_location> --user <email_or_user>
--runtime-version <your_chosen_version >
4. Restart your application using the <restart> command.
If you want to return the default behavior when the application is always started on the latest version of the
application runtime, redeploy your application without specifying the <--runtime-version> parameter.

Caution
By selecting an older version of the application runtime, you do not have the latest released fixes and
critical patches as well as enhancements, which may affect the smooth operation and supportability of
your application. Consider updating the selected version periodically. Plan the updates to the latest version
of the application runtime and apply in your test environment first. Older application runtime versions will
be deprecated and expire. Refer to the <list-runtime-versions> command for information.

Related Information
deploy [page 141]
start [page 240]
Understanding the Runtime Information [page 1117]

1102

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.1.3

Choosing JRE Version

You can choose the Java Runtime Environment (JRE) version used for an application.

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client.
For more information, see Setting Up the Console Client [page 42]

Context
The JRE version depends on the type of SAP HANA Cloud Platform SDK you are using. By default the version is:
SDK for Java Web (1.x) - JRE 6
SDK for Java EE 6 Web Profile (2.x) - JRE 7
SDK for Java Web Tomcat 7 (2.X) JRE 7
SDK for Java Web Tomcat 8 (3.x) JRE 8
If you want to change this default version, you need to specify the --java-version parameter when deploying the
application using the SAP HANA Cloud Platform console client. Only the version number of the JVM can be
specified.
You can use JRE 8 with the Java Web Tomcat 7 runtime (neo-java-web version 2.25 or higher) in productive
accounts.
For applications developed using the SDK for Java Web Tomcat 7 (2.X), the default JRE is 7. If you are developing
a JSP application using JRE 8, you need to add a configuration in the web.xml that sets the compiler target VM
and compiler source VM versions to 1.8.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Deploy the application specifying --java-version. For example, to use JRE 7, execute the following command:
neo deploy --account <account_name> --application <application_name> --source
<file_location>
--user <e-mail_or_user> --java-version 7

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1103

Related Information
deploy [page 141]
Managing Accounts and Quota [page 17]

1.7.1.1.4

Enabling and Configuring Gzip Response


Compression

Usage of gzip response compression can optimize the response time and improve interaction with an application
as it reduces the traffic between the Web server and browsers. Enabling compression configures the server to
return zipped content for the specified MIME type and size of the response.

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client.
For more information, see Setting Up the Console Client [page 42]

Context
You can enable and configure gzip using some optional parameters of the deploy command in the console client.
When deploying the application, specify the following parameters:

Procedure
1. To enable gzip compression, specify --compression on.
2. To configure response MIME types that will be compressed, use --compressible-mime-type.
3. To specify the size of responses which will be compressed, use --compression-min-size.
If you enable compression but do not specify values for --compressible-mime-type or --compression-min-size,
then the defaults are used: text/html, text/xml, text/plain and 2048 bytes, respectively.
If you specify values for --compressible-mime-type or --compression-min-size but do not enable compression,
then the operation passes, compression is not enabled and you get a warning message.
If you want to enable compression for all responses independently from MIME type and size, use only -compression force.

1104

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example
neo deploy myapp.properties --compression on --compressible-mime-type application/
javascript,application/json
--compression-min-size 1024

Next Steps
Once enabled, you can disable the compression by redeploying the application without the compression options
or with parameter --compression off.

Related Information
Console Client [page 88]
deploy [page 141]

1.7.1.1.5

Configuring VM Arguments

Using SAP HANA Cloud Platform console client, you can configure the JRE by specifying custom VM arguments.

Prerequisites
You have downloaded and configured the console client.
For more information, see Setting Up the Console Client [page 42]

Context
You can configure the following arguments:
System properties - they will be used when starting the application process. For example {{D<key>=<value>}}
Memory arguments - use them to define custom memory settings of your compute units. The supported
memory settings are:
-Xms<size> - set initial Java heap size
-Xmx<size> - set maximum Java heap size
-XX:PermSize - set initial Java Permanent Generation size
-XX:MaxPermSize - set maximum Java Permanent Generation size

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1105

Note
We recommend that you use the default memory settings. Change them only if necessary and note that this
may impact the application performance or its ability to start.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Deploy the application, specifying your desired configurations. For example, if you want to specify a currency
and maximum heap size 1 GiB, then execute the deploy with the following parameters:
neo deploy myapp.properties --vm-arguments "-Dcurrency=EUR -Xmx1024m"

Note
If you are deploying using the properties file, note that you have to use double quotation marks twice: vmarguments=""-Dcurrency=EUR -Xmx1024m"".
This will set the system properties -Dcurrency=EUR and the memory argument -Xmx1024m.
To specify a value that contains spaces (for example, -Dname=John Doe), note that you have to use single
quotation marks for this parameter when deploying.
neo deploy myapp.properties --vm-arguments "-Dcurrency=EUR '-Dname=John Doe' Xmx1024m"

Related Information
Console Client [page 88]
deploy [page 141]

1106

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.1.6

Scaling Applications

Each application is started on a dedicated SAP HANA Cloud Platform Runtime. One application can be started on
one or many application processes, according to the compute unit quota that you have.

Prerequisites
You have downloaded and configured SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client [page 42].
Your application can run on more than one application processes

Context
Scaling an application ensures its ability to handle more requests, if necessary. Scalability also provides failover
capabilities - if one application process crashes, the application will continue to work. First, when deploying the
application, you need to define the minimum and maximum number of application processes. Then, you can scale
the application up and down by starting and stopping additional application processes. In addition, you can also
choose the compute unti size, which provides a certain central processing unit (CPU), main memory and disk
space.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Deploy the application, specifying --minimum-processes and --maximum-processes. The --minimumprocesses parameter defines the number of processes on which the application is started initially. Make sure
it is at least 2.
neo deploy myapp.properties --minimum-processes 2 --maximum-processes 5
3. Start the application. It will be started on 2 application processes.
neo start myapp.properties
4. You can now scale the application up by executing the start command again. Each new start starts another
application process. You can repeat the start until you reach the maximum number of application process you
defined within the quota you have purchased.
neo start myapp.properties
5. If for some reason you need to scale the application down, you can stop individual application processes by
using soft shutdown. Each application process has a unique process ID that you can use to disable and stop
the process.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1107

a. List all application processes with their attributes (ID, status, last change date) by executing neo status
and identify the application process you want to stop.
neo status myapp.properties
b. Execute neo disable for the application process you want to stop.
neo disable myapp.properties --application-process-id <ID>
c. Wait for some time so that all working sessions finish.
d. Stop the application process by executing neo stop with the appropriate parameters.
neo stop myapp.properties --application-process-id <ID>

Next Steps
You can also scale your application vertically by choosing the compute unit size on which it will run after the
deploy. You can choose the compute unit size by specifying the --size parameter when deploying the
application.
For example, if you have a productive account and have purchased a package with Premium edition compute
units, then you can run your application on a Premium compute unit size, by executing
neo deploy --size prem myapp.properties

Related Information
Compute Units [page 959]
deploy [page 141]
status [page 238]
Soft Shutdown [page 1126]

1.7.1.2

Managing Deployed Applications

For an overview of the current status of the individual applications in your account, use the cockpit. It provides key
information in a summarized form and allows you to initiate actions, such as starting, stopping, and undeploying
applications.

Related Information
Defining Application Details (Java Apps) [page 1109]

1108

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Starting and Stopping Applications [page 1110]


Checking the Process Status [page 1112]
Viewing Monitoring Metrics of Java Applications [page 1113]
Viewing the Default Trace [page 1115]
Understanding the Runtime Information [page 1117]
Viewing Resource Consumption [page 1118]
Using Logs in the Cockpit [page 1137]
Cockpit [page 84]
Console Client Commands [page 96]

1.7.1.2.1

Defining Application Details (Java Apps)

You can view details about your currently selected Java application. By adding a suitable display name and a
description, you can identify the application more easily.

Context
In the overview of a Java application in the cockpit, you can add and edit the display name and description for the
Java application as needed.
The following details are available:
Display name - a human-readable name that you can specify for your Java application and change it later on, if
necessary.
Description - a short descriptive text about the Java application, typically stating what it does.

Procedure
1. Log on to the cockpit and select an account.
2. Choose Java Applications in the navigation area.
3. In the application list, select your application to go to the overview.
4. In the Application Details overview, choose Edit.
5. Specify or modify the display name or the description as needed and save your changes.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1109

1.7.1.2.2

Starting and Stopping Applications

You can directly start, stop, and undeploy applications, as well as start, stop, and disable individual application
processes.

Context
An application can run on one or more application processes. The use of multiple processes allows you to
distribute application load and provide failover capability. The number of processes that you can start depends on
the compute unit quota available to your account and how an individual application has been configured.
Note that while an application name is assigned manually and is unique within an account, an application process
ID is generated automatically whenever a new process is started and is unique across the cloud platform.

Procedure
Open the cockpit and proceed as follows. To switch from account to application level, select the relevant
application in the Java Applications panel:
Table 337:
Choose...

To...

(Start)

Start an application

Panels:

Java Applications panel

State panel in the application overview

The application transitions to the Started state.

Start an additional process

(Start Additional Process)


Panels:

Java Applications panel

State panel in the application overview

Processes panel in the application overview

The applications state continues to be shown as Started and an additional process ap


pears in the Processes panel.

1110

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To...

Choose...

Note
By default an application is started on one application process and is allowed to run on a maximum of one process. To use
multiple processes, an application must be deployed with the minimum-processes and maximum-processes pa
rameters set appropriately.

(Restart)

Restart a process

Panels:

Processes panel in the application overview

State panel in the process overview

The running process is stopped and a new process started. A new process ID is generated
automatically.
(Disable process)

Disable a process

Panels:

Processes panel in the application overview

State panel in the process overview

The process state changes to Started (disabled). The process continues to handle working
sessions, but does not accept new connections, which allows you to shut it down grace
fully.
(Enable process)

Enable a process

Panels:

Processes panel in the application overview

State panel in the process overview

The process state changes back to Started.


(Stop)

Stop a process

Panels:

Processes panel in the application overview

State panel in the process overview

The process is stopped and removed from the list. If the application has no further proc
esses, it transitions to the Stopped state.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1111

To...

Choose...
(Stop)

Stop an application

Panels:

Java Applications panel

State panel in the application overview

All running processes are stopped and the application transitions to the Stopped state.
(Delete)

Undeploy an application

Panels:

Java Applications panel

State panel in the application overview

The application is deleted from your account and disappears from the application list. This
also removes all data related to the application, such as configuration settings and logs.
Data source bindings are not deleted. To delete all data source bindings created for this ap
plication, select the checkbox.

Note
Bound databases/schemas will not be deleted. You can delete database and schema
bindings using the Databases & Schemas panel.

Related Information
Cockpit [page 84]
deploy [page 141]
Scaling Applications [page 1107]
Soft Shutdown [page 1126]
Managing Schemas [page 804]

1.7.1.2.3

Checking the Process Status

The status is an aggregate value, reflecting the state and monitoring metrics of an individual application process.

Procedure
1. In the cockpit, choose Java Applications in the navigation area and then select an application in the application
list.

1112

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The Processes panel shows an aggregate status value in the Status column as follows:

- OK

- Warning (also shown for intermediate states)

- Critical issues

2. Select the relevant process to go to the process overview to view the status summary and further details:
Table 338:
Panel

Description

Status Summary

Displays the current values of the two status categories and the runtime version. A short text
summarizes any problems that have been detected.

State

Indicates whether the process has been started or is transitioning between the Started and
Stopped states. The Error state indicates a fault, such as server unavailability, timeout, or VM
failure.

Runtime

Shows the runtime version on which the application process is running and its current status:

OK: Still within the first three months since it was released

No longer recommended: Has exceeded the initial three-month period

Expired: 15 months since its release date

To display the metrics, choose Monitoring in the navigation area.

Related Information
Cockpit [page 84]

1.7.1.2.4

Viewing Monitoring Metrics of Java Applications

In the cockpit, you can view the current metrics of a selected process to check the runtime behavior of your
applications. You can also view the metrics history of an application or a process to examine the performance
trends of your application over different intervals of time or investigate the reasons that have led to problems with
it.
Table 339: Default Metrics of a Java Application

All Java applications include these default metrics. Custom metrics can also be added.
Metric

Value

Used Disc Space

What percent of the whole disc space is currently used.

Requests per Minute

The number of HTTP requests processed by the Java applica


tion for the last minute.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1113

Metric

Value

CPU Load

What percent of the CPU is used on average over the last one
minute.

Disk I/O

How many bytes per second are currently read or written to


the disc.

OS Memory Usage

What percent of the operating system memory is currently


used.

Heap Memory Usage

What percent of the heap memory is currently used.

Average Response Time

The average response time in milliseconds of all requests


processed for the last minute.

Busy Threads

The current number of threads that are processing HTTP re


quests.

Procedure
1. To view the current metrics for a process, open
for the account.

Applications

Java Applications

in the navigation area

2. Choose an application in the application list.


3. Choose the relevant process in the panel to go to the process dashboard.
4. Choose Monitoring in the navigation area. Alternatively, choose the Metrics Details link in the Metrics tile of
Status Summary.
The Current Metrics panel shows the current state of the metrics for the selected process. Details about two
groups of metrics are shown those registered by the platform (default) like CPU usage or Average Response
Time and the custom ones registered by the user (user-defined). You can use the Metrics dropdown list to
select which group of metrics to be displayed in the panel.
5. To view the history of monitoring metrics, depending on whether you want to view them on an application or
process level, proceed as follows:
Application level - open the application whose history of metrics you want to see and choose
Monitoring Application Monitoring in the navigation area. All application processes, including those
that are currently stopped, are visualized on the same charts so you can compare them.
Process level - open an application and in the Processes section, choose a process and open Monitoring in
the navigation area. You can navigate to the metrics history of the whole application using the Display all
processes link.
When you open the metrics history for an application or process, you can view the graphics of the different
metrics and zoom in when you click and drag horizontally or vertically to get further details. If you zoom in a
graphic horizontally, all other graphics zoom in to the same level of details too. You can press Shift and then
drag to pan a graphic. You can zoom out to the initial state with a double-click.
You can select different time intervals for viewing the metrics. Depending on the selected interval, data is
aggregated as follows:

1114

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

last 12 or 24 hours - data is collected each minute


last 7 days - data is aggregated from the average values for 10 minutes
last 30 days - data is aggregated from the average values for an hour
You can also select a custom time interval when you are viewing history of metrics both on application and
process level. Note that if you select an interval in which the application has not been running, the graphics
will not contain any data.

Related Information
Cockpit [page 84]
Browser Support [page 8]
Monitoring Java Applications [page 1149]

1.7.1.2.5

Viewing the Default Trace

Context
This page describes the format of the Default Trace file. You can view this file for your Web applications via the
cockpit and the Eclipse IDE.
For more information, see Using the SQL Trace [page 846] and Using Logs in the Eclipse IDE [page 1131]

Default Trace Header


Parameter

Description

FILE_TYPE

The type of the Default Trace

FILE_ID

The identifier of the Default Trace

ENCODING

The encoding type used in the cloud database

RECORD_SEPARATOR

ASCII symbol for separating the log records. In our case, it is


"|" (ASCII code: 124)

COLUMN_SEPARATOR

ASCII symbol for separating the columns in the Default

Trace. In our case, it is "#" (ASCII code: 35)


ESC_CHARACTER

SAP HANA Cloud Platform


SAP HANA Cloud Platform

ASCII symbol for escape. In our case, it is "\" (ASCII code:


92)

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1115

Parameter

Description

COLUMNS

Each log record contains the following information in the


order displayed in the log file header: Time, TZone, Severity,
Logger, ACH, User, Thread, Bundle name, JPSpace,
JPAppliance, JPComponent, Tenant Alias, and Text.

SEVERITY_MAP

The severity map represents the following severity levels


order:
FINEST|Information|FINER|Information|FINE|Information|
CONFIG|Information|DEBUG|Information|PATH|
Information|INFO|Information|WARNING|Warning|ERROR|
Error|SEVERE|Error|FATAL|Error

HEADER_END
Besides the main log information, the Default Trace logs information about the tenant users that have
accessed a relevant Web application. This information is provided in the new Tenant Alias column parameter,
which is automatically logged by the runtime. The Tenant Alias is:
A human-readable string;
For new accounts, it is shorter than the tenant ID (8-30 characters);
Unique for the relevant SAP HANA Cloud Platform landscape;
Equal to the account name (for new accounts); might be equal to the tenant ID (for old accounts).

Note
The new Tenant Alias column is available in the jpaas_auditlog file as well.

Example
In this example, the application has been accessed on behalf of two tenants - with identifiers 42e00744bf57-40b1-b3b7-04d1ca585ee3 and 5c42eee4-d5ad-494e-9afb-2be7e55d0f9c.
FILE_TYPE:DAAA96DE-B0FB-4c6e-AF7B-A445F5BF9BE2
FILE_ID:1391169413918
ENCODING:[UTF8|NWCJS:ASCII]
RECORD_SEPARATOR:124
COLUMN_SEPARATOR:35
ESC_CHARACTER:92
COLUMNS:Time|TZone|Severity|Logger|ACH|User|Thread|Bundle name|JPSpace|JPAppliance|
JPComponent|Tenant Alias|Text|
SEVERITY_MAP:FINEST|Information|FINER|Information|FINE|Information|CONFIG|
Information|DEBUG|Information|PATH|Information|INFO|Information|WARNING|Warning|
ERROR|Error|SEVERE|Error|FATAL|Error
HEADER_END
2014 01 31 12:07:09#
+00#INFO#com.sap.demo.tenant.context.TenantContextServlet##anonymous#http-bio-8041exec-1##myaccount#myapplication#web#null#null#myaccount#The app was accessed on
behalf of tenant with ID: '42e00744-bf57-40b1-b3b7-04d1ca585ee3'|
2014 01 31 12:08:30#
+00#INFO#com.sap.demo.tenant.context.TenantContextServlet##anonymous#http-bio-8041exec-3##myaccount#myapplication#web#null#null#subscriberaccount#The app was
accessed on behalf of tenant with ID: '5c42eee4-d5ad-494e-9afb-2be7e55d0f9c'|

1116

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Logging in Applications [page 1129]
Multitenant Applications [page 990]

1.7.1.2.6

Understanding the Runtime Information

SAP HANA Cloud Platform provides two productive application runtimes based on the set of supported Java EE
APIs. These are Java Web and Java EE 6 Web Profile.

Context
The runtime is assigned either by default or explicitly set when an application is deployed. If a version is not
specified during deployment, the major runtime version is determined automatically based on the SDK that is
used to deploy the application. By default, applications are deployed with the latest minor version of the
respective major version.
You are strongly advised to use the default version, since this contains all released fixes and critical patches,
including security patches. Override this behavior only in exceptional cases by explicitly setting the version, but
note that this is not recommended practice.

Procedure
1. In the cockpit, choose Java Applications in the navigation area and then select the relevant application in the
application list.
The Runtime panel provides the following information:
The application runtime name and version
For user-defined runtimes:
The major and minor versions, for example, 1.35.
The date until when the specified runtime version is recommended for use, or whether it is no longer
recommended or has expired (also indicated by a runtime version status icon).
2. To view the actual runtime versions used by the individual processes (requires that the application is
running), select a process in the process list.
The Runtime panel at process level provides the following information:
The exact runtime version on which the process has been started (major, minor, micro, and nano
versions).
The date until when this runtime version is recommended for use, or whether it is no longer
recommended or has expired (also indicated by a runtime version status icon).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1117

Related Information
Choosing Application Runtime Version [page 1101]
Cockpit [page 84]

1.7.1.2.7

Viewing Resource Consumption

In the cockpit, information about the resources available to your account and their current and past usage is
provided at both account and application level. At account level, the values are aggregated for all applications in
the account.

Context
Resource consumption is presented in the form of aggregate values, which depend on the resource type:
Sum: The sum for the selected month.
Maximum: The maximum value recorded for the selected month. If the current month is selected, the latest
value recorded is also shown. Note that the frequency with which metrics are measured varies depending on
the resource type. For some it is only once per day.

Procedure
1. To view the resource consumption for the selected account, choose Resource Consumption in the navigation
area. By default, resource consumption is displayed for the current month. You can select an earlier month
from the dropdown box.
Each resource type is listed with the associated platform service and the measurements recorded for the
selected month, as well as the quota actually assigned to the account:
Table 340:
Service

Resource

Description

Runtime

Compute Unit Size

Maximum number of VMs used of the given size.


Sizes:

Network

1118

Data Transfer

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

Lite: 1 CPU Core; 2048 MB Main memory

Professional: 2 CPU Cores; 4096 MB Main memory

Premium: 4 CPU Cores; 8192 MB Memory

Premium Plus: 8 CPU Cores; 16384 MB Memory

Total size of outgoing HTTP traffic (egress bandwidth)

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Service

Resource

Description

Incoming Requests

Maximum number of incoming HTTP requests per day


There is no quota assigned.

Connectivity

Connections to non-SAP onpremise systems

Maximum number of connections to non-SAP on-premise sys


tems

Document

Transactions

Total number of HTTP requests to the document service

Storage Content Size

Maximum amount of user data for stored documents and ver


sions

Storage Metadata Size

Maximum amount of metadata for stored documents (for ex


ample, properties, folders, ACLs)
There is no quota assigned.

Persistence

DB Space (HANA DB)

Maximum schema size, including table data and indexes

DB Space (MaxDB)

Maximum schema size, including table data and indexes

2. To view the resource consumption for a specific application, select the application in the Java Applications
panel and then choose Resource Consumption in the navigation area. The same information is displayed as
above, except for the account quota.

Related Information
Cockpit [page 84]

1.7.1.3

Updating Applications

If you are an application operator and need to deploy a new version of a productive application or perform
maintenance, you can choose among several approaches.

Note
In all cases, first test your update in a non-productive environment. The newly deployed version of the
application overwrites the old one and you cannot revert to it automatically. You have to redeploy the old
version to revert the changes, if necessary.
SAP HANA Cloud Platform provides the following approaches for updating an application:

Zero Downtime
Description: Rolling update with soft shutdown

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1119

Use: When your new application version is backward compatible with the old version - that is, the new version of
the application can work in parallel with the already running old application version.
Steps: Deploy a new version of the application and disable and enable processes in a rolling manner. For an
automated execution of the same procedure, use the rolling-update command.
See Updating Applications with Zero Downtime [page 1121] and rolling-update [page 224].

Planned Downtime (Maintenance Mode)


Description: Shows a custom maintenance page to end users. The application is automatically disabled.
Use: When the new version is backward incompatible - that is, running the old and the new version in parallel may
lead to inconsistent data or erroneous output.
Steps: Enable maintenance mode to redirect new connections to the maintenance application. Deploy and start
the new application version and then disable maintenance mode.
See Using Maintenance Mode for Planned Downtimes [page 1123]

Soft Shutdown
Description: Supports zero downtime and planned downtime scenarios. Disabled applications/processes stop
accepting new connections from users, but continue to serve already running connections.
Use: As part of the zero downtime scenario or to gracefully shut down your application during a planned downtime
(without maintenance mode).
Steps: Disable the application (console client only) or individual processes (console client or cockpit) in order to
shut down the application or processes gracefully.
See Soft Shutdown [page 1126]

Related Information
Deploying and Updating Applications [page 973]

1120

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.3.1

Updating Applications with Zero Downtime

The platform allows you to update an application in a manner in which the application remains operable all the
time and your users do not experience downtime.

Prerequisites
You have application deployment permissions for the account.
You have at least one application process that is not in use, see your compute unit quota.
You have downloaded and configured the SAP HANA Cloud Platform console client. We recommend that you
use the latest SDK.
For more information, see Setting Up the Console Client [page 42].

Context
Each application runs on one or more dedicated application processes. You can start one or many application
processes at any given time, according to the compute unit quota that you have. Each process has a unique
process ID that you can use to stop it. To update an application non-disruptively for users, you handle individual
processes rather than the application as a whole. The procedure below describes the manual steps to execute a
zero downtime update. Use it if you want to have more control on the respective steps, for example to have a
different timeout for the different application processes before stopping them. For an automated execution of the
same procedure, use the rolling-update command. For more information, see rolling-update [page 224].

Note
Not applicable to hanatrial.ondemand.com.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. List the status of the application which shows all its processes with their attributes (ID, status, last change
date) by executing <neo status>. Identify and make a note of the application process IDs, which you will
need to stop in the following steps. Application processes are listed chronologically by their last change date.
neo status --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>
3. Deploy the new version of your application on SAP HANA Cloud Platform by executing <neo deploy> with
the appropriate parameters.
Note that to execute the update, you need to start one additional application process with the new version.
Therefore, make sure you have configured a high enough number of maximum processes for the application

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1121

(at least one higher than the number of old processes that are running). In case you have already reached the
quota for your account, stop one of the already running processes, before proceeding.
neo deploy --host <landscape_host> --account <account_name> --application
<application_name> --source <file_location>
--user <e-mail_or_user> --maximum-processes <number of maximum processes that
can be started for the application>
4. Start a new application process which is running the new version of the application by executing <neo
start>.
neo start --host <landscape_host> --account <account_name> --application
<application_name> --user <e-mail_or_user>
5. Use soft shutdown for the application process running the old version of the application:
a. Execute <neo disable> using the ID you identified in Step 2. This command stops the creation of new
connections to the application from new end users, but keeps the already running ones alive.
neo disable --host <landscape_host> --user <email_or_user> --applicationprocess-id <ID>
b. Wait for some time so that all working sessions finish. You can monitor user requests and used resources
by configuring JMX checks, or, you can just wait for a given time period that should be enough for most of
the sessions to finish.
c. Stop the application process by executing <neo stop> using the <application-process-id>
parameter.
neo stop --host <landscape_host> --user <email_or_user> --application-processid <ID>
6. (Optional) Make sure the application process is stopped by checking its status using the <applicationprocess-id> parameter.
neo status --host <landscape_host> --user <email_or_user> --application-processid <ID>
7. If the application is running on more than one application processes, repeat steps 4 and 5 until all the
processes running the old version are stopped and the corresponding number of processes running the new
version are started.

Example
For example, if your application runs on two application processes, you need to perform the following steps:
1. List the application processes running the old version:
application process(old); application process (old)
2. Deploy the new version of the application. As you will need to start one additional application process later,
make sure you have another available application process by specifying --maximum-processes 3. Since the
newly deployed version does not start automatically, the running application processes remain unchanged:
application process (old); application process (old)
3. Start a new application process that will use the newly deployed version:
application process (old); application process (old); application process (new)
4. Using soft shutdown, disable and stop one of the application processes running the old version so that you
have one application process with the old version and one with the new version:
application process (new); application process (old)

1122

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

5. Repeat steps 3 and 4 so that the remainng application process running the old version gets stopped and a
new application process with the new application version is started instead.
application process (new); application process (new)

Related Information
rolling-update [page 224]
Soft Shutdown [page 1126]
disable [page 147]
deploy [page 141]
start [page 240]
status [page 238]
JMX Checks [page 1156]

1.7.1.3.2

Using Maintenance Mode for Planned Downtimes

An operator can start and stop planned application downtime, during which a customized maintenance page for
that application is shown to end users.

Prerequisites
To redirect an application, you require a maintenance application. A maintenance application replaces your
application for a temporary period and can be as simple as a static page or have more complex logic. You need to
provide the maintenance application yourself and ensure that it meets the following conditions:
It is a Java application.
It is deployed in the same account as your application.
It has been started, that is, it is up and running.
It must not be in maintenance itself.

Context

Note
Not applicable to hanatrial.ondemand.com.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1123

Cockpit
Context
You can enable the maintenance mode for an application from the application dashboard. An application can be
put into maintenance mode only if it is not being used as a maintenance application itself and is running (Started
state).

Procedure
1. Log on to the cockpit, select an account and choose
area.

Applications

Java Applications

in the navigation

2. Click the applications name in the list to open the application dashboard and in the Application Maintenance
panel choose

(Start Maintenance).

3. In the dialog box, select the application that will serve as the maintenance application and choose Set
Selected Application. In the application list, the applications state is now shown as Started (In Maintenance).
From this point on, new connections will be redirected to the maintenance application. All active connections
will still be handled until the application is stopped.
4. Optional: To view the details in the State panel, select your application in the list.
The following details confirm that your application is in maintenance mode:

In Maintenance

A link to the assigned maintenance application: Click the link to open the application dashboard for this
application.

Results
The temporary redirect to the maintenance application remains effective until you take your application out of
maintenance. To disable the maintenance mode, choose
(Switch maintenance mode off). Before doing so,
you should ensure that your application is up and running to avoid end users experiencing HTTP errors.

Console Client
Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).

1124

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Start the planned application downtime by executing <neo start-maintenance> in the command line. This
stops traffic to the application and registers a maintenance page application. All active connections will be still
handled until the application is stopped.
neo start-maintenance --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user>
--maintenance-application <maintenance application name>
3. Perform the planned maintenance, update or configuration of your application:
a. Before stopping the application, wait for the working sessions to finish. You can wait for a given time
period that should be enough for most of the sessions to finish, or configure JMX checks to monitor user
requests and used resources. For more information, see Configuring a JMX Check to Monitor Your
Application [page 1157]
b. Stop the application by executing:
neo stop --host <landscape_host> --account <account_name> --application
<application_name> --user <email_or_user>
c. Deploy the new version of your application by executing:
neo deploy --host <landscape_host> --account <account_name> --application
<application_name> --source <file_location>
--user <e-mail_or_user>
d. Start the new version of the application by executing:
neo start --host <landscape_host> --account <account_name> --application
<application_name> --source <file_location>
--user <e-mail_or_user>
4. Stop the planned application downtime by executing <neo stop-maintenance> in the command line. This
resumes traffic to the application and the maintenance page application stops handling incoming requests.
neo stop-maintenance --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user>

Related Information
start-maintenance [page 243]
stop-maintenance [page 247]
deploy [page 141]
start [page 240]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1125

1.7.1.3.3

Soft Shutdown

Soft shutdown enables an operator to stop an application or application process in a way that no data is lost.
Using soft shutdown gives sufficient time to finish serving end user requests or background jobs.

Prerequisites
You have application deployment permissions for the account.

Context
Using soft shutdown, an operator can restart the application (for example, in order to update it) in a way that end
users are not disturbed. First, the application process is disabled. This means that requests by users that already
have open connections to this process will be processed, but new requests will not reach this application process
anymore. After the application process is disabled and remaining sessions processed, it can be stopped by the
operator.

Cockpit
Context
You can disable application processes in the Processes panel on the application dashboard or the State panel on
the process dashboard.

Procedure
1. Log on to the cockpit, select an account and choose
area.

Applications

Java Applications

in the navigation

2. Select an application in the application list.


3. In the Processes panel, choose
(disabled).

(Disable process) in the relevant row. The process state changes to Started

Note
You can also select the process and disable it from the process dashboard.
4. Wait for some time so that all working sessions finish and then stop the process.

1126

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Starting and Stopping Applications [page 1110]

Console Client
Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Disable processing of requests from new users to the application by executing <neo disable> with the
appropriate parameters. If you want to stop requests to a specific application process only and not to the
whole application, add the <--application-process-id> parameter.
neo disable --host <landscape_host> --user <e-mail_or_user> --applicationprocess-id <ID>
If you disable the entire application, or all processes of the application, then new users requesting the
application will not be able to access it and will get an error.
3. Wait for some time so that all working sessions finish.
You can monitor user requests and used resources by configuring JMX checks, or, you can just wait for a
given time period that should be enough for most of the sessions to finish.
4. Stop the application by executing <neo stop> with the appropriate parameters. If you want to terminate a
specific application process only and not the whole application, add the <--application-process-id
>parameter.
neo stop --host <landscape_host> --user <e-mail_or_user> --application-processid <ID>

Related Information
disable [page 147]
JMX Checks [page 1156]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1127

1.7.1.4

Handling Unplanned Downtime

In the event of unplanned downtime when there is no application process able to serve HTTP requests, a default
error is shown to users. To prevent this, an operator can configure a custom downtime page using a downtime
application, which takes over the HTTP traffic if an unplanned downtime occurs.

Prerequisites

Note
Not applicable to hanatrial.ondemand.com.
You have downloaded and configured the console client. We recommend that you use the latest SDK. For
more information, see Setting Up the Console Client [page 42]
You have deployed and started your own downtime application in the same SAP HANA Cloud Platform
account as the application itself.
The downtime application has to be developed in a way that it returns an HTTP 503 return code. That is
especially important if availability checks are configured for the original applications so that unplanned
downtimes are properly detected.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Configure the downtime application by executing neo set-downtime-app in the command line.
neo set-downtime-app --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user>
--downtime-application <downtime_application_name>
3. (optional) If the downtime page is no longer needed (for example, if the original application has been
undeployed), you can remove it by executing clear-downtime-app command.
neo clear-downtime-app --host <landscape_host> --account <account_name> -application <application_name> --user <e-mail_or_user>

Related Information
set-downtime-app [page 234]
clear-downtime-app [page 108]

1128

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.5

Logging in Applications

Overview
If you want to have logs produced at runtime, which you can use for analysis and troubleshooting, you have to use
a logging API in your cloud application.
For cloud applications, we support usage of Simple Logging Facade for Java (SLF4J). The API is built upon
using the Logger class. All logs are put in the default trace file of the server and are visualized at runtime in the
cockpit.

Prerequisites
You have created an application for SAP HANA Cloud Platform. For more information, see Creating a
HelloWorld Application [page 47].
You are assigned a Developer or Administrator role. For more information about the roles, see Account
Member Roles [page 27].

Implementation of SLF4J API in Applications


Follow the guidelines in the SLF4J User Manual

Note
Cloud applications can directly access SLF4J API without adding any references or packaging the library in the
application archive. For more information, see SLF4J API .

Note
SAP HANA Cloud Platform provides logging framework implementation that cannot be changed. Including
slf4j-api library into a WAR will cause conflicts. Exclude this library from your application and all its
dependencies recursively.
To construct a parameterized message, you can use one of the following ways:
Passing the parameter inside the message String
You also need to add a log level check here - this will help you avoid creating too many String objects which
could lead to performance issues of your application.
if (logger.isInfoEnabled()) {
logger.info("Message logged for name " + name + " with level info");
}
Passing the parameter as an argument to the respective methods (info, error, and so on):
logger.info("Message logged for name {} with level info", name);

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1129

For more tips and tricks, check SLF4J Logging Performance (FAQ)

Example
You can add an error log in your application with the following code:
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class YourClass {
public static void main(String[] args){
Logger logger = LoggerFactory.getLogger(YourClass.class);
logger.error("message");
}
}

Log Retention
Log records are only kept on the central log server for 7 days. To save a copy of them, you can download them
using any of the SAP HANA Cloud Platform tools (Eclipse IDE, console client, cockpit). This rule applies to all kind
of log files.

Note
After the logs have been written by the application runtime, they are transported to the central log server. If,
however, during this transfer the application is restarted, part of the logs can be lost.

Log Level Mapping


SLF4J uses the following log levels:
Level

Description

ALL

This level has the lowest possible rank and is intended to turn
on all logging.

TRACE

This level designates finer-grained informational events than


DEBUG.

DEBUG

This level designates fine-grained informational events that


are most useful to debug an application.

INFO

This level designates informational messages that highlight


the progress of the application at coarse-grained level.

WARN

1130

This level designates potentially harmful situations.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Level

Description

ERROR

This level designates error events that might still allow the
application to continue running.

OFF

This level has the highest possible rank and is intended to


turn off logging.

Related Information
Using Logs in the Eclipse IDE [page 1131]
Using Logs in the Console Client [page 1134]
Using Logs in the Cockpit [page 1137]

1.7.1.5.1

Using Logs in the Eclipse IDE

Context
After deploying your Web applications, you can check their logs as well as configure their loggers settings. This
section describes the following logging tasks you can perform in the Eclipse IDE:
Changing the effective level of a particular logger
Setting an effective level simultaneously for all the currently displayed loggers
Viewing logs and log files
Sorting loggers and log files
You can perform these operations both in the cloud and on a local server.
Also, persistence for loggers is enabled both on the cloud and on a local server level. Logger level settings are kept
and restored on a server restart, so you do not need to set them over again.

Prerequisites
You have downloaded and set up your Eclipse IDE, SAP HANA Cloud Platform Tools for Java, and SDK.
For more information, see Installing Java Tools for Eclipse and SDK [page 33].
You have created and deployed a Web application that uses logging functionality on SAP HANA Cloud
Platform.
For more information, see Logging in Applications [page 1129].
You are assigned a Developer or Administrator role. For more information about the roles, see Account
Member Roles [page 27].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1131

Setting Log Levels


1. After deploying an application in the Eclipse IDE on SAP HANA Cloud Platform or SAP HANA Cloud Platform
local runtime, open the Servers view and double-click the server.
2. Choose the Loggers tab.
3. When the server is in [Started] state, all the available loggers are listed in the Loggers table. If the server is
in [Starting], [Stopping], or [Stopped] state, the table is empty.
You can use the filter field to find particular loggers you need. You can filter by both the Name and the
Level columns.
You can also sort the loggers table by both the Name and the Level column. The Level column sorts the
fields by effective level, not alphabetically.

4. To change a logger level, go to the relevant row in the table and select the new log level from the Level column.
You can configure as many loggers as you need.
5. If you need to simultaneously set a log level for all the currently displayed loggers, go to Set the shown loggers
to level and select the desired one.
Besides for all available server loggers in the table, this feature is also applicable for a list of loggers displayed
after filtering.

1132

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Save your changes using the Save button from the main menu or by pressing Ctrl + S .
7. To refresh the loggers table, choose the
button.
If you try to refresh your loggers before saving your changes, a dialog appears warning you that your changes
will be lost.

Note
You can only set log levels when an application is running. Loggers are not listed if the relevant application
code has not been executed.
If you set a new log level for a parent logger, such as com.sap.core.js.admin.operations, the child
loggers, for example, com.sap.core.js.admin.operations.AdminOperations and
com.sap.core.js.admin.operations.internal.ErrorQueueHandler, automatically inherit the
same log level. Override this mechanism, if necessary, by explicitly assigning a new log level to the child
loggers.

Resetting Log Levels


If you have changed the effective level of some or all loggers of an application, running on a particular server, you
have the option to reset the logger levels.
1. Make sure you can restart your server without causing data loss.
2. Click the Reset all loggers link. A dialog box appears, warning you that the resetting operation requires server
restart.
3. Choose Reset and Restart.

Listing Available Log Files


1. In the Servers view, go to the context menu of your server and choose

Show In

Server Logs .

Note
If the server has never been started, no logs are available and the Server Logs view is empty.
2. When the server is started, the Server Logs view displays all available Default Trace and HTTP Access
logs of the applications that you are running on this server.

Note
You can also reach the Server Logs view if you expand the server and double-click on the Server Logs node.
3. If you have more than one running servers, from the Server dropdown box, select the one you need to view its
logs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1133

4. You can sort your log files by all columns.


5. To refresh the log files table, choose the

button.

6. Double-click on a log to see its details in the Console. You can then:
Open the log in an editor, choosing the

button.

Clear the log console, choosing the

button.

Close the log console, choosing the

button.

1.7.1.5.2

Using Logs in the Console Client

Context
After you have deployed and started an application on SAP HANA Cloud Platform, you can manage some of its
logging configurations using SAP HANA Cloud Platform console client. For easier troubleshooting, you can use the
commands from the logging group to:
List available log files;
Download a log file;
List available loggers;
Change the log level of a particular logger or several loggers at once;
Reset the log levels of your loggers to their initial state.
Persistence for loggers is enabled on both local and cloud level. Logger level settings are kept and restored on a
server restart, so you do not need to set them over again.

Prerequisites
You have created and deployed a Web application which uses logging functionality on SAP HANA Cloud
Platform. For more information, see Logging in Applications [page 1129].
You have downloaded and set up the SAP HANA Cloud Platform console client. For more information, see
Setting Up the Console Client [page 42]
You are assigned a Developer or Administrator role. For more information about the roles, see Account
Member Roles [page 27].

1134

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Open the Command Prompt.
2. Navigate to the bin folder of the SDK location.
3. Enter neo help to display all the commands of the console client or neo help <command_name> to display
the help information for a command.
For more information about argument values usage, see Console Client [page 88].

Listing Available Log Files


You can list all log files of your application sorted by date in a table format, starting with the latest modified.
To do that, execute the following command:
neo list-logs --account <account_name> --application <application_name> --user
<email_or_user> --host <landscape_host>

Downloading Log Files


To download a particular log file, execute the following command:
neo get-log --account <account_name> --application <application_name> --user <email_or_user> --host <landscape_host> --directory <local_folder_of_the_file> --file
<file_name>
You can also use the --overwrite command argument so that in case a file with the same name already exists, it
will be overwritten. If a file with the same name already exists and you do not explicitly include --overwrite, you
will be notified and asked if you want to overwrite it.
If the directory you have specified in the command line does not exist, it will be created.

Listing Loggers
To list available loggers and their log levels, execute the following command:
neo list-loggers --account <account_name> --application <application_name> --user
<email_or_user> --host <landscape_host>

Note
You can only list loggers when an application is running. Loggers are not listed if the relevant application code
has not been executed.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1135

Setting Log Levels


To set a log level for a single logger or for multiple loggers, execute the following command:
neo set-log-level --account <account_name> --application <application_name> --user
<email_or_user> --host <landscape_host> --loggers <logger_name1>,<logger_name2>,...
--level <log_level>

Note
You can only set log levels when an application is running.
If you set a new log level for a parent logger, such as com.sap.core.js.admin.operations, the child
loggers, for example, com.sap.core.js.admin.operations.AdminOperations and
com.sap.core.js.admin.operations.internal.ErrorQueueHandler, automatically inherit the
same log level. Override this mechanism, if necessary, by explicitly assigning a new log level to the child
loggers.

Resetting Log Levels


To reset all logger levels of your application to the their initial state, execute the following command:
reset-log-levels --account <account_name> --application <application_name> --user
<email_or_user> --host <landscape_host>

Note
In order for the changes to take effect, restart your running application.

Example
Setting Log Levels
You can deploy a WAR file on SAP HANA Cloud Platform and then change its loggers level to INFO.
1. Deploy the example.war file on SAP HANA Cloud Platform, using the example_war.properties file.
2. Then execute the following command:
neo set-log-level --account myaccount --application myapplication --user
p1234567890 --host hanatrial.ondemand.com --loggers
com.mycompany.superapp.ui.Utils --level INFO
3. Request the example application in the browser and then download and open the ljs_trace.log file.
As a result, a new info message is logged indicating that the logger level has been changed successfully.

1136

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
get-log [page 162]
list-logs [page 201]
list-loggers [page 200]
set-log-level [page 235]
reset-log-levels [page 217]

1.7.1.5.3

Using Logs in the Cockpit

You can view the logs and change the log settings of any applications deployed in your account. The cockpit
provides the following types of logs: default trace logs, HTTP access logs, and garbage collection logs.

Context
If you are interested in the latest logs only, view the logs in the Most Recent Logging panel in the application
overview.
To check the logs over the past few days, go to the
listing.

Monitoring

Logging

page for a more comprehensive

To debug applications, use the log level configuration option to switch the relevant loggers to debug mode.
For that operation, choose the Configure Loggers button.

View Logs
Procedure
1. Log on to the cockpit and go to the

Applications

Java Applications

page of the account.

2. Choose the relevant application to go to the overview.


The latest logs are listed in the Most Recent Logging panel with the following information: type; process ID;
date and time of the last modification; and size.
3. To view a more extensive list of logs, choose Monitoring Logging in the navigation area.
This page lists all log files by log file type with the following information: process ID; date and time of the last
modification; and size.
4. To display the contents of a particular log file, choose
by choosing

SAP HANA Cloud Platform


SAP HANA Cloud Platform

(Display). Note that you can also download the file

(Download).

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1137

Configure Logs
Set the log levels of the relevant loggers used by your application. Loggers include platform loggers and, if
configured, the application logger, named as follows: <package name>.<class name>, for example,
com.sap.cloud.sample.persistence.PersistenceWithJDBCServlet.

Prerequisites
You are assigned a Developer or Administrator role. For more information about the roles, see Account Member
Roles [page 27].

Procedure
1. In the cockpit, navigate to

Monitoring

Logging

as described above.

2. Choose Configure Loggers.

Note
You can only set log levels for the default trace.
In the logger configuration dialog, all loggers used since the application was started are listed with the log
levels that are currently applicable.

Note
You can only set log levels when an application is running. Loggers are only listed if the relevant application
code has been executed.
3. Optionally filter the list by logger name to select only the loggers in which you are interested.
4. To set the log level for a logger, locate the relevant logger and in that row select the new log level from the
dropdown list.
5. To change the log level for all loggers contained in the list, enter the new log level in the Set log level to all
loggers in the list to: field and choose Set.
The log settings take effect immediately. Since log settings are saved permanently, they do not revert to their
initial values when the application is restarted.

Note
If you set a new log level for a parent logger, such as com.sap.core.js.admin.operations, the child
loggers, for example, com.sap.core.js.admin.operations.AdminOperations and
com.sap.core.js.admin.operations.internal.ErrorQueueHandler, automatically inherit the
same log level. Override this mechanism, if necessary, by explicitly assigning a new log level to the child
loggers.

1138

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Cockpit [page 84]
Log Viewers [page 1139]
Using the SQL Trace [page 846]

1.7.1.5.3.1 Log Viewers


The cockpit provides dedicated log viewers for showing default trace and HTTP access logs.
The log viewer comprises a header section with filter and search options and a content area with a table that
enables you to filter and sort the data for some of the columns.

Header Section
You can filter log entries based on the values of certain log fields:
Default trace
Levels dropdown
Filters the log entries contained in the table according to log level.
Search text field
Filters by Logger, Tenant, and Text columns
HTTP access log
Method dropdown:
Filters the log entries based on the HTTP method (OPTIONS, GET, HEAD, POST, PUT, DELETE, TRACE).
Status dropdown
Filters the log entries based on the HTTP status code: 1xx informational, 2xx success, 3xx redirection, 4xx
client error, 5xx server error.
Search text field
Filters by Client, User, Method, Resource, Status, Size, and Duration columns.
The log entries are, by default, not filtered (all log entries are selected). For some of the columns in the table,
you can filter the data by selecting the column header and entering the filter value in the text field.

Log Traffic
This section provides a log traffic overview and a slider for adjusting the time range:
Log traffic
The log volume over the selected period is represented graphically, allowing you to identify time intervals with
high levels of activity. You can specify the time range after you choose Show Time Filter.
Time range slider

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1139

By default, the log table shows all log entries contained in the file, from the oldest to the newest. The time
range slider allows you to change the selected time range and therefore the selection of log entries shown in
the table by dragging the slider from both the left and right.

Default Trace Logs


Default trace logs have the following format:
Table 341:
Field

Description

Time

Date and time when the log entry was written

Level

Log level of the log entry

Logger

Logger name

Tenant

Tenant alias, if the application was accessed through a subscription

Text

Log message text

HTTP Access Logs


HTTP access logs have the following format:
Table 342:
Field

Description

Time

Date and time when the log entry was written

Client

IP address from which the request originated

User

User that triggered the request, if available

Method

HTTP method

Resource

REST resource path

Status

HTTP status code

Size

Size of the content returned by the response

Duration

Response time in milliseconds

Related Information
HTTP Method Definitions
HTTP Status Code Definitions

1140

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.6

Profiling Applications

The SAP JVM Profiler helps you analyze resource-related problems in your Java application regardless of whether
the JVM is running locally or on the cloud.
Typically, you first profile the application locally. Then you may continue and profile it also on the cloud. The basic
procedure is the following:
1. Attach the SAP JVM Profiler to the JVM to be analyzed.
2. Analyze the retrieved profiling data in statistics and graphs.

Features
SAP JVM Profiler provides the following traces:
Table 343:
Allocation Trace

Shows the number, size and type of the allocated objects and the
methods allocating them.

Performance Hotspot Trace

Shows the most time-consuming methods and execution paths

Garbage Collection Trace

Shows all details about the processed garbage collections

Method Parameter Trace

Shows the values of a selected method parameters

Synchronization Trace

Shows the most contended locks and the threads waiting for or holding
them

File I/O Trace

Shows the number of bytes transferred from or to files and the meth
ods transferring them

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1141

Network I/O Trace

Shows the number of bytes transferred from or to the network and the
methods transferring them

Additionally, the following operations are supported:


Table 344:
Heap Dump

Shows a complete snapshot of the Java Heap

Class Statistic

Shows the classes, the number and size of their objects currently res

Tasks
Profiling Applications Locally [page 1142]
Profiling Applications on the Cloud [page 1145]

Related Information
Debugging Applications [page 986]

1.7.1.6.1

Profiling Applications Locally

Overview
After you have created a Web application and verified that it is functionally correct, you may want to inspect its
runtime behavior by profiling the application. This helps you to:
Check and optimize memory usage
Identify frequently called operations (bottlenecks and hotspots)
Identify slow performance

1142

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Prerequisites
You have developed and deployed a Web application using the Eclipse IDE. For more information, see
Deploying and Updating Applications [page 973].
You have installed SAP JVM as the runtime for the local server. For more information, see Setting Up SAP
JVM in Eclipse IDE [page 41]

Procedure
1. Run your Web application on a local server.
2. From the server context menu, choose Profile. Cases:
If your server has been stopped, it will be switched to mode [Profiling].
If your server has been running, it will be restarted and switched to mode [Profiling].

Note
Since profiling only works with SAP JVM, if another VM is used, going to Profile will result in opening a
dialog that suggests two options - editing the configuration or canceling the operation.
3. The Profiling perspective is opened.
4. Choose the type of analysis to perform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1143

Note
If the server is in profile mode, and you choose Restart in Profile from the context menu, the profile session
will be restarted in [Profiling] state.
If the server is in profile mode, and you choose Restart or Restart in Debug from the context menu, the
profile session will be disconnected and the server will be restarted.

Result
You have successfully started a profiling run of a locally deployed Web application. You can now trigger your work
load, create snapshots of the profiling data and analyze the profiling results.

1144

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Next Steps
When you have finished with your profiling session, you can stop it either by disconnecting the profiling session
from the Profile view or by restarting the server.

Related Information
Refer to the SAP JVM Profiler documentation for details about the available analysis options. The documentation
is available as part of the SAP JVM Profiler plugin in the Eclipse IDE and can be found via

Help

Help Contents

SAP JVM Profiler .

1.7.1.6.2

Profiling Applications on the Cloud

After you have created a Web application and verified that it is functionally correct, you may want to inspect its
runtime behavior by profiling the application on the cloud. It is best if you first profile the Web application locally.

Prerequisites
You have developed and deployed a Web application using the Eclipse IDE. For more information, see
Deploying and Updating Applications [page 973]
Optional: You have profiled your Web application locally. For more information, see Profiling Applications
Locally [page 1142]

Note
Currently, it is only possible to profile Web applications on the cloud that have exactly one application process
(node).

Procedure
1. Run your Web application on SAP HANA Cloud Platform.
2. You can start the profiling in two ways:
From the server context menu, choose Profile (if the server is stopped) or Restart in Profile (if the server is
running).
Go to the application source code and from its context menu, choose

Profile As

Profile on Server .

3. Open the Profiling perspective.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1145

Note
Currently, the Profiling perspective cannot be automatically switched but you need to open it manually.
4. Start a profiling analysis.

Results
You have successfully initiated a profiling run of a Web application on the cloud. Now, you can trigger your
workload, create snapshots of the profiling data and analyze the profiling results.

1146

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Next Steps
When you have finished with your profiling session, you can stop it either by disconnecting the profiling session
from the Profile view or by restarting the server.
Refer to the SAP JVM Profiler documentation for details about the available analysis options. The documentation
is available as part of the SAP JVM Profiler plugin in the Eclipse IDE and you can find it via

Help

Help Contents

SAP JVM Profiler .

1.7.1.7

Viewing the Default Trace

Context
This page describes the format of the Default Trace file. You can view this file for your Web applications via the
cockpit and the Eclipse IDE.
For more information, see Using the SQL Trace [page 846] and Using Logs in the Eclipse IDE [page 1131]

Default Trace Header


Parameter

Description

FILE_TYPE

The type of the Default Trace

FILE_ID

The identifier of the Default Trace

ENCODING

The encoding type used in the cloud database

RECORD_SEPARATOR

ASCII symbol for separating the log records. In our case, it is


"|" (ASCII code: 124)

COLUMN_SEPARATOR

ASCII symbol for separating the columns in the Default

Trace. In our case, it is "#" (ASCII code: 35)


ESC_CHARACTER

ASCII symbol for escape. In our case, it is "\" (ASCII code:


92)

COLUMNS

Each log record contains the following information in the


order displayed in the log file header: Time, TZone, Severity,
Logger, ACH, User, Thread, Bundle name, JPSpace,
JPAppliance, JPComponent, Tenant Alias, and Text.

SEVERITY_MAP

The severity map represents the following severity levels


order:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1147

Parameter

Description

FINEST|Information|FINER|Information|FINE|Information|
CONFIG|Information|DEBUG|Information|PATH|
Information|INFO|Information|WARNING|Warning|ERROR|
Error|SEVERE|Error|FATAL|Error

HEADER_END
Besides the main log information, the Default Trace logs information about the tenant users that have
accessed a relevant Web application. This information is provided in the new Tenant Alias column parameter,
which is automatically logged by the runtime. The Tenant Alias is:
A human-readable string;
For new accounts, it is shorter than the tenant ID (8-30 characters);
Unique for the relevant SAP HANA Cloud Platform landscape;
Equal to the account name (for new accounts); might be equal to the tenant ID (for old accounts).

Note
The new Tenant Alias column is available in the jpaas_auditlog file as well.

Example
In this example, the application has been accessed on behalf of two tenants - with identifiers 42e00744bf57-40b1-b3b7-04d1ca585ee3 and 5c42eee4-d5ad-494e-9afb-2be7e55d0f9c.
FILE_TYPE:DAAA96DE-B0FB-4c6e-AF7B-A445F5BF9BE2
FILE_ID:1391169413918
ENCODING:[UTF8|NWCJS:ASCII]
RECORD_SEPARATOR:124
COLUMN_SEPARATOR:35
ESC_CHARACTER:92
COLUMNS:Time|TZone|Severity|Logger|ACH|User|Thread|Bundle name|JPSpace|JPAppliance|
JPComponent|Tenant Alias|Text|
SEVERITY_MAP:FINEST|Information|FINER|Information|FINE|Information|CONFIG|
Information|DEBUG|Information|PATH|Information|INFO|Information|WARNING|Warning|
ERROR|Error|SEVERE|Error|FATAL|Error
HEADER_END
2014 01 31 12:07:09#
+00#INFO#com.sap.demo.tenant.context.TenantContextServlet##anonymous#http-bio-8041exec-1##myaccount#myapplication#web#null#null#myaccount#The app was accessed on
behalf of tenant with ID: '42e00744-bf57-40b1-b3b7-04d1ca585ee3'|
2014 01 31 12:08:30#
+00#INFO#com.sap.demo.tenant.context.TenantContextServlet##anonymous#http-bio-8041exec-3##myaccount#myapplication#web#null#null#subscriberaccount#The app was
accessed on behalf of tenant with ID: '5c42eee4-d5ad-494e-9afb-2be7e55d0f9c'|

Related Information
Logging in Applications [page 1129]

1148

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Multitenant Applications [page 990]

1.7.1.8

Monitoring Java Applications

To monitor whether your deployed application is up and running, you can register an availability check and JMX
checks for it and configure email recipients who will receive notification if the application goes down. For the email
recipients configuration, you use the SAP HANA Cloud Platform console client. You can also generate a report of
metrics that shows performance statistics of the CPU, DB, and response times.
Table 345:
Content
Default Monitoring Metrics [page 1149]
JMX Checks for Custom Metrics [page 1149]
Availability Checks [page 1150]
Alert Recipients Commands [page 1150]
Monitoring Service [page 1150]
Performance Statistics Service (beta) [page 1151]

Default Monitoring Metrics


Table 346:
Cockpit

Viewing Monitoring Metrics of Java Applications [page 1113]

JMX Checks for Custom Metrics


Table 347:
Concept

JMX Checks [page 1156]

Configuration

Configuring a JMX Check to Monitor Your Application [page 1157]

JMX Console

Using the JMX Console [page 1159]

JMX Checks Com

list-jmx-checks [page 197]

mands

create-jmx-check [page 120]


delete-jmx-check [page 135]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1149

Availability Checks
Table 348:
Concept

Availability Checks [page 1151]

Cockpit

Configuring Availability Checks for Java Applications from the Cockpit [page 1153]

Console Client

Configuring Availability Checks for Java Applications from the Console Client [page 1154]

Commands

list-availability-check [page 186]


create-availability-check [page 113]
delete-availability-check [page 126]

Alert Recipients Commands


Table 349:
Console Client

list-alert-recipients [page 188]


set-alert-recipients [page 227]
clear-alert-recipients [page 107]

Monitoring Service
Table 350:
Concept

Monitoring Service [page 703]

JSON Response

Structure of a Monitoring Service Response [page 705]

Sample Scenarios

Elastic Scaling on HCP - How to create a simple Automatic Application Scaler on HANA Cloud Plat
form

Tutorials

1150

Use the Monitoring Service to Retrieve Metrics from Different HCP Applications

Use the Monitoring Service for User Notifications and Self-Healing of HCP Java Applications

Tutorial: Implementing a Dashboard Application [page 708]

Tutorial: Implementing a Notification Application [page 712]

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Performance Statistics Service (Beta)


Table 351:
Concept

Performance Statistics Service (Beta) [page 714]

Performance Sta

Metrics of a Performance Statistics Report [page 715]

tistics Report
Configuration

Enabling Performance Statistics Collection [page 719]

Related Information
Monitoring Database Systems [page 1164]

1.7.1.8.1

Availability Checks

The availability check is one per Java or SAP HANA XS application and is executed every minute. You can
configure an availability check for an application either from the cockpit or from the console client. If your
application is not available or its response time is too high, you will receive an e-mail notification. If you stop the
application by yourself, you will not receive a notification as in this case alerting is suppressed and enabled once
again when you start the application. However, this is not valid for productive SAP HANA databases as you cannot
stop them. In this case, the availability check will start running at the moment you create it and will not stop until
you delete it. E-mail alert is triggered if the application is not in state OK for two consecutive checks. There are five
types of notifications:
Table 352:
Notification

Description

CRITICAL

Your application is not available or the response time is above


the CRITICAL threshold.

WARNING

The response time of your application is above the WARNING


threshold.

OK

Your application has recovered from CRITICAL/WARNING


state.

UNSTABLE

Your application does not behave consistently. For example,


the response time is OK upon check n, then is CRITICAL upon
check n+1, then is again OK on check n+2, and so on.

STABLE

Your application behaves consistently again.

You may also set your availability check for Java applications on account level using a relative URL. This means
that each application started in your account will immediately receive an availability check requesting
application_url/configured_relative_url. This option is useful in case you start multiple instances of
the same application (applications with the same relative health check URL) in your account and allows you to

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1151

configure this check only once for all of them. You can configure availability checks on account level only from the
console client. If there is a check configured on account level and a check configured on application level, the one
on the application level has higher priority. For example, if you have in your account ten applications with the /
health_check relative URL and one multitenant application with the /myapp/health_check relative URL, you
can configure an availability check on account level for all applications and one availability check for the
multitenant application to override the one on account level.

Limitations
Availability monitoring in SAP HANA Cloud Platform is done by running HTTP GET requests against URL provided
by the application operator. The http/https ping is not parsing the response body, but it is relying only on the
HTTP response code.
Currently there are two limitations that need to be considered when designing your availability URL:
The monitoring infrastructure does not support authorization for the checks. This means that you cannot
pass user and password or client certificate when configuring the availability check. Therefore, you must
design the availability URL without authentication or authorization. This will make sure that your application
can be accessed in any case, the correct response code is returned (for example 200, 404, 500 and so on)
and the response time is only from your application. If your application responds with 302, the ping will follow
the redirect.

Caution
If you design the availability URL as a protected resource, the check will consider 401 and 403 response
codes as 200 OK. Note that these response codes may come from SAP Cloud Identity service and not from
your application, in case of an authenticated application.
Currently, the response codes accepted by the 'http/https ping' are 200, 302, 401 and 403. This is done to
cover all the different types of URLs that can be monitored. You need to make sure that if something does not
work as expected, your application is not returning some of the above 4 codes as you will not get an alert.
The monitoring infrastructure supports only one availability check per Java or SAP HANA XS application. This
means that if you have multiple web applications deployed together as one application in your account or
application with multiple end points you want to check, you need to design one common availability URL to be
able to monitor them all together. If one of the applications fails, you will get an alert and then you will have to
check which one exactly is failing by opening the availability URL.

Recommendation
We recommend that the response is a simple, plain HTML, just stating which web application is OK and
which is not. It depends on the implementation of the availability URL whether it will just inform that a web
application is available or it will also check whether it is working as expected. If you plan to develop and
operate multiple applications in your account, it is a good idea to have identical availability URLs for the
different applications (for example /availability). This will allow you to configure the availability check only
once on account level.
Sample output of application which is OK:
HTTP RETURN CODE 200 OK
Purchasing - OK

1152

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Sales - OK
Registration - OK
IDP - OK
Sample output of application that has problems:
HTTP RETURN CODE 500 INTERNAL SERVER ERROR
Purchasing - OK
Sales - no connectivity to backend
Registration - OK
IDP - OK

Caution
Note that the availability URL designed according to the above recommendations is unprotected and can be
accessed by everyone. We recommend not putting sensitive information about your application there (for
example error stack traces).

Related Information
Configuring Availability Checks for Java Applications from the Cockpit [page 1153]
Configuring Availability Checks for Java Applications from the Console Client [page 1154]
Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page 1017]
Configuring Availability Checks for SAP HANA XS Applications from the Console Client [page 1018]
Availability Checks Commands
list-availability-check [page 186]
create-availability-check [page 113]
delete-availability-check [page 126]
JMX Checks [page 1156]

1.7.1.8.1.1 Configuring Availability Checks for Java Applications


from the Cockpit
In the cockpit, you can configure availability checks for the applications deployed in your account. If you have
configured an availability check on account level, you can override it by creating one on application level. You can
manage the checks on account level from the console client only.

Prerequisites
You have deployed and started an application in your account.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1153

Procedure
1. In the cockpit, choose Applications Java Applications
choose an application in the application list.

in the navigation area for the account and then

2. In the Availability panel, choose Create Availability Check.


3. Select the URL you want to monitor from the dropdown list and fill in values for warning and critical thresholds
if you want them to be different from the default ones. Choose Save.
Your availability check is created. You can view your application's latest HTTP response code and response
time as well as status icon showing whether your application is up or down. If you want to receive alerts when
your application is down, you need to configure alert recipients from the console client. For more information,
see Subscribe recipients to notification alerts step in Configuring Availability Checks for Java Applications
from the Console Client [page 1154].

Related Information
Browser Support [page 8]
Cockpit [page 84]
Availability Checks [page 1151]

1.7.1.8.1.2 Configuring Availability Checks for Java


Applications from the Console Client
This topic shows how you can configure an availability check for your application and subscribe recipients to
receive alert e-mail notifications when your application is down or responds slowly.

Prerequisites
You have deployed and started an application on the platform.
You have set up the console client.
For more information, see Setting Up the Console Client [page 42].

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat and neo.sh (<SDK
installation folder>/tools).
2. Create the availability check.

1154

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Execute:
neo create-availability-check -a myaccount -b myapp -u myuser -U /heartbeat -C 6 -W
4 --host hana.ondemand.com
Replace "myapp", "myaccount" and "myuser" with the names of your account, application, and user
respectively.
The availability URL (/heartbeat in this case) is not provided by default by the platform. Replace it with a
suitable URL that is already exposed by your application or create it for your application. Keep in mind the
limitations for availability URLs, described in "Availability Checks" document (see Related Links below).
The check will trigger warnings "-W 4" if the response time is above 4 seconds and critical alerts "-C 6" if
the response time is above 6 seconds or the application is not available.
Use the respective landscape host for your account type. For more information, see Related Links section
below.

Note
The availability check will be visible in the SAP HANA Cloud Platform cockpit in around 2 minutes.
3. Subscribe recipients to notification alerts.
Execute:
neo set-alert-recipients -a myaccount -b myapp -u myuser -e
alert_recipients@example.com --host hana.ondemand.com
Replace "myapp", "myaccount" and "myuser" with the names of your account, application, and user
respectively.
Replace "alert-recipients@example.com" with the email addresses that you want to receive alerts.
Separate email addresses with commas. We recommend that you use distribution lists rather than
personal email addresses. Keep in mind that you will remain responsible for handling of personal email
addresses with respect to data privacy regulations applicable.
Use the respective landscape host for your account type.

Note
Setting an alert recipient for an application will trigger sending all alerts for this application to the
configured email(s). Once the recipients are subscribed, you do not need to subscribe them again after
every new check you configure. You can also set the recipients on account level if you skip the -b
parameter so that they receive alerts for all applications and for all the metrics you are monitoring.

Caution
If you stop the application by yourself, you will not receive a notification alert. Alerting is suppressed with
the manual stop of an application. Alerting is automatically enabled once again when you start the
application.

Related Information
Landscape Hosts [page 32]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1155

Availability Checks [page 1151]


Availability Checks Commands
list-availability-check [page 186]
create-availability-check [page 113]
delete-availability-check [page 126]
Alert Recipients Commands
list-alert-recipients [page 188]
set-alert-recipients [page 227]
clear-alert-recipients [page 107]
JMX Checks [page 1156]

1.7.1.8.2

JMX Checks

Registering JMX checks allows alerting on any metric that is based on JMX MBean attribute.
The checks support attributes that are java.lang.String or java.lang.Number or CompositeDataSupport. In case it
is CompositeDataSupport, the objects that are mapped to the keys again should be java.lang.String or
java.lang.Number, otherwise error will be thrown. For more information, see CompositeDataSupport .
The MBean can be registered either by the application runtime (for example, standard JVM MBeans like
java.lang:type=Memory) or by the application itself (application specific). The MBeans registered by the
application runtime can be checked using jconsole and connecting to the local server from the SDK.
You can set multiple JMX checks per application. They will be executed each minute. In case the JMX check fails
due to an error in the MBean execution like, for example, wrong ObjectName, Attribute, MBean not registered,
and so on, or due to exceeded threshold, you will receive e-mail notification if you have configured an e-mail
recipient. The e-mail notification is triggered only after two consecutive failures of a JMX check. There are 5 types
of notifications:
Table 353:
Notification

Description

CRITICAL

The JMX check fails due to an error in the MBean execution or the attribute value is not within the de
fined CRITICAL threshold.

WARNING

Attribute value is not within the defined WARNING threshold.

OK

The attribute has recovered from CRITICAL/WARNING state.

UNSTABLE

Your application does not behave consistently. For example, the attribute is OK upon check n, then is
CRITICAL upon check n+1, then is again OK on check n+2, and so on.

STABLE

Your application behaves consistently again.

You may also set JMX checks on account level. This means that each application started in your account will
immediately receive all the JMX checks configured on account level in addition to the checks configured on the
application level. If there is a check configured on account level and a check configured on application level with
one and the same name, the one on the application level has higher priority and only it will be assigned to the
started application.

1156

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Configuring a JMX Check to Monitor Your Application [page 1157]
JMX Checks Commands
list-jmx-checks [page 197]
create-jmx-check [page 120]
delete-jmx-check [page 135]
Availability Checks [page 1151]

1.7.1.8.2.1 Configuring a JMX Check to Monitor Your


Application
This topic shows how you can configure a JMX check for your application and subscribe recipients to receive alert
e-mail notifications when your application is down or responds slowly.

Prerequisites
You have deployed and started an application on the platform.
You have set up the console client.
For more information, see Setting Up the Console Client [page 42].

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Create the JMX check.
Execute:
neo create-jmx-check -a myaccount -b myapp -u myuser -O myMBeanObjectName -A
myMBeanAttribute -n myCheckName -C myCriticalThreshold -W myWarningThreshold -U
unit --host hana.ondemand.com
Replace "myapp", "myaccount" and "myuser" with the names of your account, application, and user
respectively.
Replace "myMBeanObjectName" and "myMBeanAttributeName" with the attribute and object name of
the MBean that you want to monitor. You can use existing standard MBean from the runtime (for
example, standard JDK MBean like Catalina:type=ThreadPool,name=\"http-bio-8041\" and attribute like
currentThreadsBusy) or your own MBean which should be part of your application and your application
should register it in the MBean server. For more information about the attribute command, see "JMX
Checks Commands" document in the Related Links section below.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1157

Replace "myCheckName" with the name you want to see the check with in the cockpit.
Replace "myWarningThreshold" and "myCriticalThreshold" with a suitable threshold for the attribute
you want to check. If the actual value is above the threshold, is out of the threshold range in case you use
a range, or is a different string in case your metric has a string value, you will receive a warning,
respectively critical, notification. For more details how to set a threshold, see "JMX Check Commands"
document.
Replace "unit" with the unit you want to be displayed next to the value of your MBean attribute, for
example MBs or ms.
Use the respective landscape host for your account type. For more information, see Related Links section
below.
3. Subscribe recipients to notification alerts.
Execute:
neo set-alert-recipients -a myaccount -b myapp -u myuser -e
alert_recipients@example.com --host hana.ondemand.com
Replace "myapp", "myaccount" and "myuser" with the names of your account, application, and user
respectively.
Replace "alert-recipients@example.com" with the email addresses that you want to receive alerts.
Separate email addresses with commas. We recommend that you use distribution lists rather than
personal email addresses. Keep in mind that you will remain responsible for handling of personal email
addresses with respect to data privacy regulations applicable.
Use the respective landscape host for your account type.

Note
Setting an alert recipient for an application will trigger sending all alerts for this application to the
configured emails. Once the recipients are subscribed, you do not need to subscribe them again after every
new check you configure. You can also set the recipients on account level if you skip the -b parameter, so
that they receive alerts for all applications and for all the metrics you are monitoring.

Related Information
Landscape Hosts [page 32]
JMX Checks [page 1156]
JMX Checks Commands
list-jmx-checks [page 197]
create-jmx-check [page 120]
delete-jmx-check [page 135]
Alert Recipients Commands
list-alert-recipients [page 188]
set-alert-recipients [page 227]
clear-alert-recipients [page 107]
Availability Checks [page 1151]

1158

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.1.8.2.2 Using the JMX Console


The JMX console available in the cockpit enables you to monitor and manage the performance of the JVM and
your Java applications running on the platform.

Prerequisites
You have started a Java application in your account.

Context
The JMX console in the cockpit is based on the Java Management Extensions (JMX) specification. It exposes all
the MBeans registered in the platform runtime and allows you to execute operations on them and view their
attributes to monitor and manage the performance of the JVM and your applications. The MBeans visible in the
JMX console are standard JVM MBeans, SAP-specific MBeans and MBeans registered by your application
runtime. The usage of few specific MBeans that can be dangerous in cloud environment is restricted.

Procedure
1. In the cockpit, navigate to the Java application you want to monitor.
You can do this by choosing the Java application under
from the Overview page.
2. Open

Monitoring

JMX Console

Applications

Java Applications

or by navigating

in the navigation.

3. In the JMX Console, select a process whose performance you want to check.
4. Browse for the MBean you want to monitor using the filter.
5. Expand the tree until you reach the MBean and choose it.
The MBean attributes and operations are populated in the respective fields.
6. Depending on your needs, you can do the following:
Check the value of an attribute in the Value field.
Execute an MBean operation using

(Execute) and check the results in the Operation Results section.

Related Information
Browser Support [page 8]
Cockpit [page 84]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1159

1.7.1.9

Using Multiple Accounts for Staged Application


Development

SAP HANA Cloud Platform allows you to achieve isolation between the different application life cycle stages
(development, testing, productive) by using multiple accounts.

Prerequisites
You have developed an application. For more information, see Developing Java Applications [page 964].
You have a customer or partner account. For more information, see Account Types [page 12].

Context
Using multiple accounts ensures better stability as in the productive account, you only deploy tested versions of
the application. Also, you can achieve better security for productive applications because permissions are given
per account.
For example, you can create three different accounts for one application and assign the necessary amount of
compute unit quota to them::
dev - use for development purposes and for testing the increments in the cloud, you can grant permissions to
all application developers
test- use for testing the developed application and its critical configurations to ensure quality delivery
(integration testing and testing in productive-like environment prior to making it publicly available)
prod - use to run productive applications, give permissions only to operators.
You can create multiple accounts and assign quota to them either using the console client or the cockpit.

Creating Multiple Accounts from the Cockpit


Procedure
1. Open the cockpit and navigate to Account.
2. In the Manage Accounts section, choose New Account... and specify a display name.
3. Use the "+" and "-" buttons next to quota types to set the desired amount of quota and choose the Save
button.
Next, you can deploy your application in the newly created account using the Eclipse IDE or the console client.
Then, you can test your application and make it ready for productive use.
You can transfer the application from one account to another by redeploying it in the respective account.

1160

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Creating Multiple Accounts with the Console Client


Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Create a new account.
Execute:
neo create-account -a <account> -u <user who is member of that account> -h
<landscape host> -n <display name of the new account>
3. Assign the necessary amount of quota to the account.
Execute:
neo set-quota -a <account> -u <user name or email> -h <landscape host> -m <type of
the quota lite, pro, prem or prem-plus>:<integer amount of the quota>
Next, you can deploy your application in the newly created account by executing neo deploy -a
<account> -h <landscape host> -b <application name> -s <file location> -u <user
name or email>. Then, you can test your application and make it ready for productive use.
You can transfer the application from one account to another by redeploying it in the respective account.

Related Information
Managing Accounts and Quota [page 17]
Deploying and Updating Applications [page 973]
create-account [page 110]
delete-account [page 125]
list-accounts [page 187]
set-quota [page 237]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1161

1.7.1.10 Providing Multitenant Applications to Tenants for


Testing
Using the console client, you can create accounts and subscribe them to applications to test how applications can
be provided to multiple consumers.

Prerequisites
You have set up the console client. For more information, see Setting Up the Console Client [page 42].
You have developed and deployed an application that will be used by multiple consumers. For more
information, see Multitenant Applications [page 990].
You have a customer or partner account. For more information, see Account Types [page 12].
You are a member of both accounts - the one where the multitenant application is deployed and the one that
you want to subscribe to the application.

Related Information
Subscribing an Account to an Application [page 1162]
Cleaning Up Your Environment [page 1163]

1.7.1.10.1 Subscribing an Account to an Application


Using the console client, you can subscribe an account to an application.

Context
Note
You can subscribe an account to an application that is running in another account only if both accounts
(provider and consumer account) belong to the same landscape.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).

1162

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Create an account for a given consumer.


Execute neo create-account -a <account> -u <user name or email> -h <landscape host>
-n <display name of the new account>
3. Subscribe the account you created to the application.
Execute neo subscribe -a <account> -b <account:application> -u <user name or email>
-h <landscape host>
Note that you must specify the parameter -b in the format <account name>:<application>.
4. Access the application through the dedicated URL, for example https://<application name><provider
account>-<consumer account>.<landscape host>.
You can see the list of subscriptions and the corresponding application URLs to access them in the
Subscriptions pane in the cockpit.
5. (Optional) You can also check the list of your test accounts and subscriptions as follows:
Option

Description

List all applications to which a given ac


count is subscribed

Execute neo list-subscribed-applications -a <account>


-u <user name or email> -h <landscape host>

List accounts you have created

Execute neo list-accounts -a <account> -u <user name


or email> -h <landscape host>

List all accounts subscribed to a given


application

Execute neo list-subscribed-accounts -a <account> -b


<application> -u <user name or email> -h <landscape
host>

Related Information
Managing Subscriptions [page 28]
create-account [page 110]
list-accounts [page 187]
subscribe [page 248]
list-subscribed-accounts [page 208]
list-subscribed-applications [page 209]

1.7.1.10.2 Cleaning Up Your Environment

Procedure
1. Unsubscribe the account of the consumer from the application.
Execute neo unsubscribe -a <account> -b <application> -u <user name or email>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1163

2. Delete the account of the consumer.


Execute neo delete-account -a <account> -h <landscape host> -u <user name or email>

Related Information
Managing Subscriptions [page 28]
delete-account [page 125]
unsubscribe [page 255]

1.7.2 SAP HANA: Application Operations


After you have developed and deployed your SAP HANA application, you can then monitor it.

Monitoring HANA XS Applications


Table 354:
Cockpit

Monitoring Database Systems [page 1164]

Console Client

1.7.2.1

Monitoring Database Systems

To monitor whether your deployed SAP HANA XS application is up and running, you can register an availability
check for it and configure email recipients who will receive notification if the application goes down. For the email
recipients configuration, you use the SAP HANA Cloud Platform console client. Furthermore, you can just view the
metrics of a database system of any type.
Table 355:
Content
Availability Checks [page 1165]
Alert Recipients Commands [page 1165]
Monitoring Metrics [page 1165]

1164

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Availability Checks
Table 356:
Concept

Availability Checks [page 1165]

Cockpit

Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page 1017]

Console Client

Configuring Availability Checks for SAP HANA XS Applications from the Console Client [page 1018]

Commands

list-availability-check [page 186]


create-availability-check [page 113]
delete-availability-check [page 126]

Alert Recipients Commands


Table 357:
Console Client

list-alert-recipients [page 188]


set-alert-recipients [page 227]
clear-alert-recipients [page 107]

Monitoring Metrics
Table 358:
Cockpit

Viewing Monitoring Metrics of a Database System [page 1020]

Related Information
Monitoring Java Applications [page 1149]

1.7.2.1.1

Availability Checks

The availability check is one per Java or SAP HANA XS application and is executed every minute. You can
configure an availability check for an application either from the cockpit or from the console client. If your
application is not available or its response time is too high, you will receive an e-mail notification. If you stop the
application by yourself, you will not receive a notification as in this case alerting is suppressed and enabled once

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1165

again when you start the application. However, this is not valid for productive SAP HANA databases as you cannot
stop them. In this case, the availability check will start running at the moment you create it and will not stop until
you delete it. E-mail alert is triggered if the application is not in state OK for two consecutive checks. There are five
types of notifications:
Table 359:
Notification

Description

CRITICAL

Your application is not available or the response time is above


the CRITICAL threshold.

WARNING

The response time of your application is above the WARNING


threshold.

OK

Your application has recovered from CRITICAL/WARNING


state.

UNSTABLE

Your application does not behave consistently. For example,


the response time is OK upon check n, then is CRITICAL upon
check n+1, then is again OK on check n+2, and so on.

STABLE

Your application behaves consistently again.

You may also set your availability check for Java applications on account level using a relative URL. This means
that each application started in your account will immediately receive an availability check requesting
application_url/configured_relative_url. This option is useful in case you start multiple instances of
the same application (applications with the same relative health check URL) in your account and allows you to
configure this check only once for all of them. You can configure availability checks on account level only from the
console client. If there is a check configured on account level and a check configured on application level, the one
on the application level has higher priority. For example, if you have in your account ten applications with the /
health_check relative URL and one multitenant application with the /myapp/health_check relative URL, you
can configure an availability check on account level for all applications and one availability check for the
multitenant application to override the one on account level.

Limitations
Availability monitoring in SAP HANA Cloud Platform is done by running HTTP GET requests against URL provided
by the application operator. The http/https ping is not parsing the response body, but it is relying only on the
HTTP response code.
Currently there are two limitations that need to be considered when designing your availability URL:
The monitoring infrastructure does not support authorization for the checks. This means that you cannot
pass user and password or client certificate when configuring the availability check. Therefore, you must
design the availability URL without authentication or authorization. This will make sure that your application
can be accessed in any case, the correct response code is returned (for example 200, 404, 500 and so on)
and the response time is only from your application. If your application responds with 302, the ping will follow
the redirect.

Caution
If you design the availability URL as a protected resource, the check will consider 401 and 403 response
codes as 200 OK. Note that these response codes may come from SAP Cloud Identity service and not from
your application, in case of an authenticated application.

1166

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Currently, the response codes accepted by the 'http/https ping' are 200, 302, 401 and 403. This is done to
cover all the different types of URLs that can be monitored. You need to make sure that if something does not
work as expected, your application is not returning some of the above 4 codes as you will not get an alert.
The monitoring infrastructure supports only one availability check per Java or SAP HANA XS application. This
means that if you have multiple web applications deployed together as one application in your account or
application with multiple end points you want to check, you need to design one common availability URL to be
able to monitor them all together. If one of the applications fails, you will get an alert and then you will have to
check which one exactly is failing by opening the availability URL.

Recommendation
We recommend that the response is a simple, plain HTML, just stating which web application is OK and
which is not. It depends on the implementation of the availability URL whether it will just inform that a web
application is available or it will also check whether it is working as expected. If you plan to develop and
operate multiple applications in your account, it is a good idea to have identical availability URLs for the
different applications (for example /availability). This will allow you to configure the availability check only
once on account level.
Sample output of application which is OK:
HTTP RETURN CODE 200 OK
Purchasing - OK
Sales - OK
Registration - OK
IDP - OK
Sample output of application that has problems:
HTTP RETURN CODE 500 INTERNAL SERVER ERROR
Purchasing - OK
Sales - no connectivity to backend
Registration - OK
IDP - OK

Caution
Note that the availability URL designed according to the above recommendations is unprotected and can be
accessed by everyone. We recommend not putting sensitive information about your application there (for
example error stack traces).

Related Information
Configuring Availability Checks for Java Applications from the Cockpit [page 1153]
Configuring Availability Checks for Java Applications from the Console Client [page 1154]
Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page 1017]
Configuring Availability Checks for SAP HANA XS Applications from the Console Client [page 1018]
Availability Checks Commands
list-availability-check [page 186]
create-availability-check [page 113]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1167

delete-availability-check [page 126]


JMX Checks [page 1156]

1.7.2.1.1.1 Configuring Availability Checks for SAP HANA XS


Applications from the Cockpit
In the cockpit, you can configure availability checks for the SAP HANA XS applications running on your productive
SAP HANA database system.

Procedure
1. In the cockpit, choose Applications HANA XS Applications in the navigation area of the account and
open the application list of the productive SAP HANA database system.
2. Select an application from the list and in the Application Details panel choose Create Availability Check.
3. In the dialog that appears, select the URL you want to monitor from the dropdown list and fill in values for
warning and critical thresholds if you want them to be different from the default ones. Choose Save.
Your availability check is created. You can view your application's latest HTTP response code and response
time as well as status icon showing whether your application is up or down. If you want to receive alerts when
your application is down, you need to configure alert recipients from the console client. For more information,
see the Subscribe recipients to notification alerts. step in Configuring Availability Checks for SAP HANA XS
Applications from the Console Client [page 1018].

Related Information
Browser Support [page 8]
Cockpit [page 84]
Availability Checks [page 1151]
Configuring Availability Checks for SAP HANA XS Applications from the Console Client [page 1018]

1168

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.2.1.1.2 Configuring Availability Checks for SAP HANA XS


Applications from the Console Client
In the console client you can configure an availability check for your SAP HANA XS application and subscribe
recipients to receive alert e-mail notifications when it is down or responds slowly.

Prerequisites
You have a productive SAP HANA database on the platform.
For more information, see Using a Productive SAP HANA Database System [page 1010].
You have set up the console client.
For more information, see Setting Up the Console Client [page 42].

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/sh (<SDK installation
folder>/tools).
2. Create the availability check.
Execute:
neo create-availability-check -a myaccount -b myhana:myhanaxsapp -u myuser -U /
heartbeat.xsjs -C 6 -W 4 --host hana.ondemand.com
Replace "myaccount", "myhana:myhanaxsapp" and "myuser" with the names of your account,
productive SAP HANA database name and application, and user respectively.
The availability URL (/heartbeat.xsjs in this case) is not provided by default by the platform. Replace it
with a suitable URL that is already exposed by your SAP HANA XS application or create it. Keep in mind
the limitations for availability URLs. For more information, see Availability Checks [page 1151].

Note
In case you want to create an availability check for a protected SAP HANA XS application, you need to
create a sub-package, in which to create an .xsaccess file with the following content:
{

"exposed": true,
"authentication": null,
"authorization": null

In the SAP HANA XS Administration Tool (https://<productive SAP HANA


name><account>.<host>/sap/hana/xs/admin/), find the sub-package and activate public access to
it. After this, you will be able to monitor the resources on and under the sub-package level, that is, you
will be able to create an availability check for your protected application. Note that in the availability
URL, you have to provide the path to the resource in the sub-package that you will be monitoring, for
example /heartbeat.xsjs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1169

The check will trigger warnings "-W 4" if the response time is above 4 seconds and critical alerts "-C 6" if
the response time is above 6 seconds or the application is not available.
Use the respective landscape host for your account type.
3. Subscribe recipients to notification alerts.
Execute:
neo set-alert-recipients -a myaccount -b myhana:myhanaxsapp -u myuser -e
alert_recipients@example.com --host hana.ondemand.com
Replace "myaccount", "myhana" and "myuser" with the names of your account, productive SAP HANA
database name, and user respectively.
Replace "alert-recipients@example.com" with the email addresses that you want to receive alerts.
Separate email addresses with commas. We recommend that you use distribution lists rather than
personal email addresses. Keep in mind that you will remain responsible for handling of personal email
addresses with respect to data privacy regulations applicable.
Use the respective landscape host for your account type.

Note
Setting an alert recipient for an application will trigger sending all alerts for this application to the
configured email(s). Once the recipients are subscribed, you do not need to subscribe them again after
every new check you configure. You can also set the recipients on account level if you skip the -b
parameter so that they receive alerts for all applications and for all the metrics you are monitoring.

Related Information
Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page 1017]
Landscape Hosts [page 32]
Availability Checks Commands
list-availability-check [page 186]
create-availability-check [page 113]
delete-availability-check [page 126]
Alert Recipients Commands
list-alert-recipients [page 188]
set-alert-recipients [page 227]
clear-alert-recipients [page 107]

1.7.2.1.2

Viewing Monitoring Metrics of a Database System

In the cockpit, you can view the current metrics of a selected database system to get information about its health
state. You can also view the metrics history of a productive database to examine the performance trends of your
database over different intervals of time or investigate the reasons that have led to problems with it. You can view
the metrics for all types of databases.

1170

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. In the cockpit, navigate to the Database Systems page either by choosing Persistence from the navigation
area or from the Overview page.
All database systems available in the selected account are listed with their details, including the database
version and state, and the number of associated databases.
2. Select the entry for the relevant database system in the list.
3. Choose Monitoring from the navigation area to get detailed information about the current state and the
history of metrics for a selected productive database system.
The Current Metrics panel shows the current state of the metrics for the selected database system. When a
threshold is reached, the metric health status changes to warning or critical.
The Metrics History panel shows the metrics history of your database. You can view the graphics of the
different metrics and zoom in when you click and drag horizontally or vertically to get further details. If you
zoom in a graphic horizontally, all other graphics zoom in to the same level of details too. You can press
Shift and then drag to scroll all graphics simultaneously to the left or right. You can zoom out to the initial
state with a double-click.
You can select different time intervals for viewing the metrics. Depending on the selected interval, data is
aggregated as follows:
last 12 or 24 hours - data is collected each minute
last 7 days - data is aggregated from the average values for 10 minutes
last 30 days - data is aggregated from the average values for an hour
You can also select a custom time interval when you are viewing the history of metrics. Note that if you select
an interval in which the database has not been running, the graphics will not contain any data.

Related Information
Browser Support [page 8]
Cockpit [page 84]

1.7.3 HTML5: Application Operations


For an overview of the current status of the individual HTML5 applications in your account, use the SAP HANA
Cloud Platform cockpit.
It provides key information in a summarized form and allows you to initiate actions, such as starting or stopping.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1171

Managing Application Versions


Table 360:
Cockpit

Managing Application Versions [page 1175]

Managing Destinations
Table 361:
Cockpit

Assigning Destinations for HTML5 Applications [page 1176]

Starting and Stopping Applications


Table 362:
Cockpit

Starting and Stopping HTML5 Applications [page 1177]

Managing Roles and Permissions


Table 363:
Cockpit

Managing Roles and Permissions [page 1177]

Logging
Table 364:
Cockpit

Logging HTML5 Applications [page 1182]

Related Information
Managing HTML5 Subscriptions [page 30]

1172

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.3.1

Exporting an HTML5 Application

You can export HTML5 applications either with their active version or with an inactive version.

Exporting the Active Version


Procedure
1. Choose Applications
want to export.

HTML5 Applications

in the navigation area, and then the link to the application you

2. Under Actions in the Overview section, choose the export icon (

).

3. Save the zip file.

Exporting an Arbitrary Version


Procedure
1. Choose Applications
want to export.

HTML5 Applications

in the navigation area, and then the link to the application you

2. Choose Versioning in the navigation area, and then choose Versions under History.
3. In the table row of the version you want to export, choose the export icon (

).

4. Save the zip file.

1.7.3.2

Importing an HTML5 Application

You can import HTML5 applications either creating a new application or creating a new version for an existing
application.

Note
When you import an application or a version, the version is not imported into master branch of the repository.
Therefore, the version is not visible in the history of the master branch. You have to switch to Versions in the
navigation area.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1173

Creating a New Application


Procedure
1. To upload a zip file, choose
from File (

Applications

HTML5 Applications

in the navigation area, and then Import

).

2. In the Import from File dialog, browse to the zip file you want to upload.
3. Enter an application name and a version name.
4. Choose Import.
The new application you created by importing the zip file is displayed in the HTML5 Applications section.
5. To activate this version, see Activating a Version [page 1045].

Creating a New Version of an Existing Application


Procedure
1. Choose Applications HTML5 Applications
want to create a new version.

in the navigation area, and then the application for which you

2. Choose Versioning in the navigation area.


3. To upload a zip file, choose Versions under History and then Import from File (

).

4. In the Import from File dialog, browse to the zip file you want to upload.
5. Enter a version name.
6. Choose Import.
The new version you created by importing the zip file is displayed in the History table.
7. To activate this version, select the Activate this application version icon (

) in the table row for this version.

8. Confirm that you want to activate the application.

1.7.3.3

Defining Application Details (HTML5 Apps)

On the Application Details panel, you can add or change a display name and a description to the selected HTML5
application.

Context
If a display name is maintained, this display name is also shown in the list of HTML5 applications and in the list of
HTML5 subscriptions instead of the application name.

1174

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose Applications HTML5 Applications in the navigation area, and select the application for which to
add or change a display name and description.
3. Under Application Details of the Overview section, choose Edit.
4. Enter a display name and a description for the HTML5 application.
Table 365:
Field

Comment

Display Name

Human-readable name that you can specify for your HTML5 application.

Description

Short descriptive text about the HTML5 application, typically stating what it
does.

1.7.3.4

Managing Application Versions

An HTML5 application can have multiple versions, but only one of these can be active. This active version is then
available to end-users of the application.
However, developers can access all versions of an application using unique URLs for testing purposes.
The Versioning view in the cockpit displays the list of available versions of an HTML5 application. Each version is
marked either as active or inactive. You can activate an inactive version using the activation button.
For every version, the required destinations are displayed in a details table. To assign a destination from your
account global destinations to a required destination, choose Edit in the details table. By default, the destination
with the same name as the name you defined for the route in the application descriptor is assigned. If this
destination does not exist, you can either create the destination or assign another one.
When you activate a version, the destinations that are currently assigned to this version are copied to the active
application version.

Related Information
Creating a Version [page 74]
Activating a Version [page 75]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1175

1.7.3.5

Assigning Destinations for HTML5 Applications

If an HTML5 application requires connectivity to one or more back-end systems, destinations must be created or
assigned.

Prerequisites
A destination to the back-end system exists.

Context
For the active application version the referenced destinations are displayed in the HTML5 Application section of
the cockpit. For a non-active application version the referenced destinations are displayed in the details table in
the Versioning section. HTML5 applications use HTTP destinations, which can be defined on the account level of
your account.
By default, the destination with the same name as the name you defined for the route in the application descriptor
is assigned. If this destination does not exist, you can create the destination with the same name as described in
Configuring Destinations from the Cockpit [page 301]. Then you can assign this newly created destination.
Alternatively, you can assign another destination that already exists in your account. To assign a destination,
follow the steps below.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose Applications HTML5 Applications in the navigation area, and choose the application for which
you want to assign a different destination (than the default one) from your account global destinations.
3. Choose Edit in the Required Destinations table.
4. In the Mapped Account Destinations column, choose an existing destination from the dropdown list.

1176

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.3.6

Starting and Stopping HTML5 Applications

End users can only access an application if the application is started. As long as an application is stopped, its end
user URL does not work.

Context
The first start of the application usually occurs when you activate a version of the application. For more
information, see Activating a Version.

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose

Applications

HTML5 Applications

in the navigation area.

3. To start your application, select it and choose the

(Start) icon.

The end user URL for the application is displayed under Active Version.
4. To stop your application, select it and choose the

(Stop) icon.

Related Information
Cockpit [page 84]

1.7.3.7

Managing Roles and Permissions

Resources of an HTML5 application can be protected by permissions. The application developer defines the
permissions in the application descriptor file.
To grant a user the permission to access a protected resource, you can either assign a custom role or one of the
predefined virtual roles to such a permission. The following predefined virtual roles are available:
AccountAdministrator is equivalent to the list of account members with administrator permission.
AccountDeveloper is equivalent to the list of account members with developer permission.
Everyone is equivalent to all authenticated users of the configured Identity Provider.
AccountDeveloper and AccountAdministrator require SAP IdP to be configured as identity provider. If you
want to use the AccountDeveloper or AccountAdministrator role together with a custom IDP, create those
roles as custom roles and assign the corresponding user manually.
The role assignments are only effective for the active application version. To protect non-active application
versions, the default permission NonActiveApplicationPermission is defined by the system for every

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1177

HTML5 application. You can assign a role to this default permission to restrict access to the non-active version of
the application.
As long as no other role is assigned to a permission, only account members with developer or administrator
permission have access to the protected resource. This is also true for the default permission
NonActiveApplicationPermission.
You can create roles in the cockpit using either of these panels:
HTML5 Applications: Using the HTML5 Applications Panel [page 1178]
Subscriptions: Using the Subscriptions Panel [page 1180]

Related Information
Authorization [page 1048]

1.7.3.7.1

Using the HTML5 Applications Panel

You can manage roles and permissions for the HTML5 applications or subscriptions using the HTML5 Applications
panel.
The role management comprises the following steps:
1. Creating Roles (HTML5 Applications) [page 1178]
2. Mapping Users or Groups to Roles (HTML5 Applications) [page 1179]
3. Assigning Roles to Permissions (HTML5 Applications) [page 1179]

1.7.3.7.1.1 Creating Roles (HTML5 Applications)


You create roles that are assigned to HTML5 applications or HTML5 applications subscriptions. The roles are
available for all HTML5 applications and all subscriptions to HTML5 applications.

Procedure
1. In the cockpit, choose

Applications

HTML5 Applications

in the navigation area.

2. Select any HTML5 application.


3. Choose Roles in the navigation area.
4. Choose New Role.
5. Enter the role name, and choose Save.

1178

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.3.7.1.2 Mapping Users or Groups to Roles (HTML5


Applications)
You assign a role to users or a group of users.

Prerequisites
If you want to use groups, you have configured the groups for your identity provider as described in ID
Federation with the Corporate Identity Provider [page 1292].

Context
Since all HTML5 applications and all HTML5 application subscriptions use the same roles, changing a role affects
all applications that use this role.

Procedure
1. In the cockpit, choose

Applications

HTML5 Applications

in the navigation area.

2. Select any HTML5 application.


3. Choose Roles in the navigation area.
4. Select the role for which you want to manage assignments.
5. To assign a new user or group, choose Assign from the users or groups section respectively.
6. Enter the name of the user or group, and choose Assign.

1.7.3.7.1.3 Assigning Roles to Permissions (HTML5


Applications)
Once you have created the required roles, you can assign the roles to the permissions of your HTML5 application
or of your HTML5 application subscription to an HTML5 application.

Procedure
1. In the cockpit, choose

Applications

HTML5 Applications

in the navigation area.

2. Select the HTML5 application to which you want to assign the roles.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1179

3. The Application Permissions section lists all permissions defined for the selected application.
4. Choose Edit.
5. To assign the role to the corresponding permission, select a role from the dropdown listbox.
6. Save your entries.

1.7.3.7.2

Using the Subscriptions Panel

You can manage roles and permissions for the HTML5 applications or subscriptions using the Subscriptions
panel.
The role management comprises the following steps:
1. Creating Roles (Subscriptions) [page 1180]
2. Mapping Users or Groups to Roles (Subscriptions) [page 1180]
3. Assigning Roles to Permissions (Subscriptions) [page 1181]

1.7.3.7.2.1 Creating Roles (Subscriptions)


You create roles that are assigned to HTML5 applications or HTML5 applications subscriptions. The roles are
available for all HTML5 applications and all subscriptions to HTML5 applications.

Procedure
1. In the cockpit, choose

Applications

Subscriptions

in the navigation area.

2. From the list of subscribed HMTL5 applications, select any subscription.


3. Choose Roles in the navigation area.
4. Choose New Role.
5. Enter the role name, and choose Save.

1.7.3.7.2.2 Mapping Users or Groups to Roles (Subscriptions)


You assign a role to users or a group of users.

Prerequisites
If you want to use groups, you have configured the groups for your identity provider as described in ID
Federation with the Corporate Identity Provider [page 1292].

1180

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Since all HTML5 applications and all HTML5 application subscriptions use the same roles, changing a role affects
all applications that use this role.

Procedure
1. In the cockpit, choose

Applications

Subscriptions

in the navigation area.

2. From the list of subscribed HMTL5 applications, select any subscription.


3. Choose Roles in the navigation area.
4. Select the role for which you want to manage assignments.
5. To assign a new user or group, choose Assign from the users or groups section respectively.
6. Enter the name of the user or group, and choose Assign.

1.7.3.7.2.3 Assigning Roles to Permissions (Subscriptions)


Once you have created the required roles, you can assign the roles to the permissions of your HTML5 application
or of your HTML5 application subscription to an HTML5 application.

Procedure
1. In the cockpit, choose

Applications

Subscriptions

in the navigation area.

2. Choose the HMTL5 applications subscription to which you want to assign the roles.
3. The Application Permissions section lists all permissions defined for the selected application.
4. Choose Edit.
5. To assign the role to the corresponding permission, select a role from the dropdown listbox.
6. Save your entries.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1181

1.7.3.8

Logging HTML5 Applications

You can view logs on any HTML5 application running in your account or subscriptions to these apps. Currently,
only the default trace log file is written. The file contains error messages caused by missing back-end connectivity,
for example, a missing destination, or logon errors caused by your account configuration.

Context
There is one file a day. The logs are kept for 7 days before they are deleted. If the application is deleted, the logs
are deleted as well. A log is a virtual file consisting of the aggregated logs of all processes. Currently, the following
data is logged:
The time stamp (date, time in milliseconds, time zone) of when the error occurred
A unique request ID
The log level (currently only ERROR is available)
The actual error message text

Procedure
1. Log on with a user (who is an account member) to the SAP HANA Cloud Platform cockpit.
2. Choose

Applications

HTML5 Applications

in the navigation area.

3. Choose the application for which you want to display the log.
4. Choose Logging in the navigation area.
5. To view the log file in the log viewer, choose Show (
6. To download the log as a text file, choose Download (

).
).

Related Information
Log Viewers [page 1139]

1.7.4 Configuring Application URLs


By default, all applications running on SAP HANA Cloud Platform are accessed on the hana.ondemand.com
domain.
The URL of an application deployed on SAP HANA Cloud Platform is https://
<application><account>.<domain>. For example, if you deploy application 'demo' in account 'myshop', the
application URL will be: https://demomyshop.hana.ondemand.com .

1182

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

According to your needs, you can change the default application URL by configuring application domains different
from the default one: custom or platform domains.
You can configure application domains using SAP HANA Cloud Platform console client.
Note that you can use either platform domains or custom domains.

Custom Domains
Use custom domains if you want to make your applications accessible on your own domain different from
hana.ondemand.com - for example, www.myshop.com. When a custom domain is used, the domain name as well
as the server certificate for this domain are owned by the customer.

Platform Domains
Caution
You can configure different platform domains only for Java applications.
By default, applications accessible on hana.ondemand.com are available on the Internet. Platform domains enable
you to use additional features by using a platform URL different from the default one.
For example, you can use svc.hana.ondemand.com to hide the application from the Internet and access it only
from other applications running on SAP HANA Cloud Platform, or, cert.hana.ondemand.com if you want an
application to use client-certificate authentication with the relevant SSL connection settings. The application
URLs will be https://demomyshop.svc.hana.ondemand.com or, https://
demomyshop.cert.hana.ondemand.com, respectively.

Related Information
Custom Domains [page 1184]
Platform Domains [page 1196]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1183

1.7.4.1

Custom Domains

SAP HANA Cloud Platform allows account owners to make their SAP HANA Cloud Platform applications
accessible via a custom domain that is different from the default one (hana.ondemand.com) - for example
www.myshop.com.

Prerequisites
To use a custom domain for your application, you need to fulfil a number of preliminary steps.
For more information, see Prerequisites [page 1185].

Scenario
After fulfilling the prerequisite, you can configure the custom domain on your own using SAP HANA Cloud
Platform console client commands.
First, set up secure SSL communication to ensure that your domain is trusted and all application data is
protected. Then, route the traffic to your application:
1. Create an SSL Host [page 1187] - the host holds the mapping between your chosen custom domain and the
application on SAP HANA Cloud Platform as well as the SSL configuration for secure communication through
this custom domain.
2. Upload a Certificate [page 1188] - it will be used as a server certificate on the SSL host.
3. Bind the Certificate to the SSL Host [page 1189].
4. Add the Custom Domain [page 1190] - this maps the custom domain to the application URL.
5. Configure DNS [page 1191]- you can create a CNAME mapping.
6. Configure Single Sign-On [page 1191] - if you have a custom trust configuration in your account, you need to
enable single logout..
The configuration of custom domains has different setups related to the subscriptions of your account. For more
information about custom domains for applications that are part of a subscription, see Custom Domains for
Multitenant Applications [page 1194].

1184

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.4.1.1

Prerequisites

Before configuring SAP HANA Cloud Platform custom domains, you need to make some preliminary steps and
fulfil a number of prerequisites.

1. Buy a custom domain quota


You need to have a quota for domains configured for your account. One domain corresponds to one SSL host that
you can use. For more information, see Purchasing a Customer Account [page 16].
The following two steps involve external service providers - domain name registrar and certificate authority.

Note
The domain name and the server certificate for this domain are issued by external authorities and owned by the
customer.

2. Choose and buy the domain names to be used by your applications


You need to come up with a list of custom domains and applications that you want to be served through them. For
example, you may decide to have three custom domains: test.myshop.com, preview.myshop.com,
www.myshop.com - for test, preview and productive versions of your SAP HANA Cloud Platform application.
The domain names are owned by the customer, not by SAP HANA Cloud Platform. Therefore, you will need to buy
the custom domain names that you have chosen from a registrar selling domain names.

3. Choose a CA to issue the certificate for your domain


To ensure your domain is trusted and all your application data is protected, you have to get an appropriate SSL
certificate from a Certificate Authority (CA). To sign and issue this certificate, you need a certificate signing
request (CSR), which you will create in the following procedure. Note that we do not support uploading of existing
certificates that are not generated using our generate-csr command.
Before buying a certificate from a provider, you need to decide on the number and type of domains you want to be
protected by this certificate. One certificate can be valid for a number of domains.
There are various types of domains, the basic ones being:
Single domain - protects one domain (for example, www.myshop.com)
Single domain with unlimited subdomains (wildcard) - secures a domain with unlimited subdomains (for
example, *.myshop.com - this covers any subdomains of myshop.com - for example, test.myshop.com;
preview.myshop.com, www.myshop.com, etc.).

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1185

Caution
Choosing the wildcard subdomain certificate ensures protection of all subdomains in your custom domain
(*.myshop.com), but not the domain itself (myshop.com cannot be used).
Multiple domain - secures multiple domain names with a single certificate. This type allows you to use any
number of different domain names or common names. For example, one certificate can support:
www.myshop.com, *.test.myshop.com, *.myshop.eu, www.myshop.de.

Note
Choose as specific domain names as possible. Also, host all domains in the certificate in one single place (SAP
HANA Cloud Platform).

Caution
The CSR is valid only for the landscape host on which it was generated and cannot be moved and downloaded.
The host represents a regional data center: hana.ondemand.com for Europe; us1.hana.ondemand.com for the
United States; ap1.hana.ondemand.com for Asia-Pacific.
The certificate has to be in Privacy-enhanced Electronic Mail (PEM) format (128 or 256 bits) with private key
(2048-4096 bits).

Related Information
Configuring Custom Domains [page 1186]

1.7.4.1.2

Configuring Custom Domains

To make sure your domain is trusted and all application data is protected, you need to first set up secure SSL
communication. The next step will then be to make your application accessible via the custom domain and route
traffic to it.

Context
Perform the following steps:
Create an SSL Host [page 1187]
Upload a Certificate [page 1188]
Bind the Certificate to the SSL Host [page 1189]
Add the Custom Domain [page 1190]
Configure DNS [page 1191]

1186

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Configure Single Logout [page 1192]


Test the Custom Domain [page 1191]

1.7.4.1.2.1 Create an SSL Host


You have to create an SSL host that will serve your custom domain. This host holds the mapping between your
chosen custom domain and the application on SAP HANA Cloud Platform as well as the SSL configuration for
secure communication through this custom domain.

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/neo.sh (<SDK installation
folder>/tools).
2. Create an SSL host. In the console client command line, execute neo create-ssl-host. For example:
neo create-ssl-host --account myaccount --user mymail@example.com --host
hana.ondemand.com --name mysslhost

Note
In the command output, you get the SSL host. For example, "A new SSL host [mysslhost] was
created and is now accessible on 123456.ssl.ondemand.com". Write this SSL host down as
you will need it in the following steps.
For more information, see create-ssl-host [page 124].
3. Optional: Check all the SSL hosts created for your account using the list-ssl-hosts command.
neo list-ssl-hosts --account myaccount --user mymail@example.com --host
hana.ondemand.com
For more information, see list-ssl-hosts [page 207].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1187

1.7.4.1.2.2 Upload a Certificate


You need an SSL certificate to allow secure communication with your application. Once installed, the SSL
certificate is used to identify the client/individual and to authenticate the owner of the site.

Context
The certificate generation process starts with certificate signing request (CSR) generation. A CSR is an encoded
file containing your public key and specific information that identifies your company and domain name.
The next step is to use the CSR to get a server certificate signed by a certificate authority (CA) chosen by you.
Before buying, carefully consider the appropriate type of SSL certificate you need. For more information, see
Prerequisites [page 1185].

Procedure
1. Generate a CSR.
The --name parameter is the unique identifier of the certificate within your account on SAP HANA Cloud
Platform and will be used later. It can contain alphanumeric symbols, '.', '-' and '_'.
The --certificate-distinguished-name contains the attributes of the CSR formatted as
type0=value0,type1=value1,type2=..., characters may be escaped by \ (backslash), no spaces are skipped.
Here you need to provide the following information:
CN = Common Name the domain name(s) for which you are requesting the certificate - for example
example.com
C = Country - two-digit code - for example, GB
ST = State - state or province name - for example, Hampshire
L = Locality city full name - for example Portsmouth
O = Organization company name
OU = Organizational Unit for example IT Department
In the console client command line, execute neo generate-csr:
neo generate-csr --account myaccount --user mymail@example.com --host
hana.ondemand.com
--name myfirstcert --certificate-distinguished-name
"C=GB,O=MyCompany,CN=example.com"
For more information, see generate-csr [page 161].

Note
For security reasons, you can only upload certificates that are generated using the generate-csr
command.
In the command line output, you get the generated CSR.

1188

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Send the CSR to a CA. Copy and send the CSR you got in the previous step to your trusted CA who will sign
the certificate.

Note
When sending the CSR to be signed by a CA, keep the following requirements in mind:
For server type, choose F5 BigIP.
The certificate must be in Privacy-enhanced Electronic Mail (PEM) format (128 or 256 bits) with private key
(2048-4096 bits).
3. Upload the SSL certificate you received from the CA to SAP HANA Cloud Platform:
neo upload-domain-certificate --account myaccount --user mymail@example.com -host hana.ondemand.com --name myfirstcert --location ./certificate.pub

Note
Note that some CAs issue chained root certificates that contain an intermediate certificate. In such cases,
put all certificates in the file for upload starting with the signed SSL certificate.

Caution
Once uploaded, the domain certificate (including the private key) is securely stored on SAP HANA Cloud
Platform and cannot be downloaded for security reasons.
For more information, see upload-domain-certificate [page 256].
Note that when the certificate expires, you will receive a notification from your CA. You need to take care of
the certificate update. For more information, see Updating an Expired Certificate [page 1194]

1.7.4.1.2.3 Bind the Certificate to the SSL Host


You need to bind the uploaded certificate to the created SSL host so that it can be used as SSL certificate for
requests to this SSL host.

Procedure
1. Bind the certificate by executing neo bind-domain-certificate :
neo bind-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --ssl-host mysslhostname --certificate myfirstcert
For more information, see bind-domain-certificate [page 103].
2. Optional: If you want to list your custom domain certificates, execute: neo list-domain-certificates .
neo list-domain-certificates --account myaccount --user mymail@example.com -host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1189

For more information, see list-domain-certificates [page 193].

1.7.4.1.2.4 Add the Custom Domain


To make your application on the SAP HANA Cloud Platform accessible via the custom domain, you need to map
the custom domain to the application URL.

Context
Note
After you configure an application to be accessed over a custom domain, its default URL hana.ondemand.com
will no longer be accessible. It will only remain accessible for applications that are part of a subscription https://<application_name><provider_account>-<consumer_account>.<domain>.

Procedure
1. In the console client command line, execute neo add-custom-domain with the appropriate parameters.
Note that you can only do this for a started application.
neo add-custom-domain --account myacc --user mymail@example.com --host
hana.ondemand.com
--custom-domain www.example.com --applicationurl myaccountmyapp.hana.ondemand.com --ssl-host mysslhostname
For more information, see add-custom-domain [page 99]
2. Optional: If you want to list all custom domains configured as access points for applications in your account,
execute neo list-custom-domain-mappings.
For more information, see list-custom-domain-mappings [page 190]

1190

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.7.4.1.2.5 Configure DNS


To route the traffic for your custom domain to your application on SAP HANA Cloud Platform, you also need to
configure it in the Domain Name System (DNS) that you use.

Context
You need to make a CNAME mapping from your custom domain to the created SSL host for each custom domain
you want to use. This mapping is specific for the domain name provider you are using. Usually, you can modify
CNAME records using the administration tools available from your domain name registrar.

Procedure
1. Sign in to the domain name registrar's administrative tool and find the place where you can update the
domain DNS records.
2. Locate and update the CNAME records for your domain to point to the DNS entry you received from us
(*.ssl.ondemand.com) - the one that you got as a result when you created the SSL host using the createssl-host command. For example, 123456.ssl.ondemand.com. You can check the SSL host by executing the
list-ssl-hosts command.
For example, if you have two DNS records : myhost.com and www.myhost.com, you need to configure them
both to point to the SSL host 123456.ssl.ondemand.com.
It may take some time for the configuration to take effect.
For further details, consult your domain name registrar documentation.

1.7.4.1.2.6 Test the Custom Domain


After you configure the custom domain, make sure that the setup is correct and your application is accessible on
the new domain.

Procedure
1. Log on to the cockpit, select an account and go to your Application Dashboard. In Application URLs, check if
the new custom URL has replaced the default one.
2. Open the new application URL in a browser. Make sure that your application responds as expected.
3. Check that there are no security warnings in the browser. View the certificate in the browser. Check the
Subject and Subject Alternative Name fields - the domain names there must match the custom domain.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1191

4. Perform a small load test - request the application from different browser sessions making at least 15
different requests.

Results
After this procedure, your application will be accessible on the custom domain, and you will be able to log on
(single sign-on) successfully. Single logout, however, may not work yet. If you have a custom trust configuration in
your account, you will need to perform an additional configuration to enable single logout.

Next Steps
Configure single logout. For more information, see Configure Single Logout [page 1192]

1.7.4.1.2.7 Configure Single Logout


To enable single logout, you need to configure the Custom Domain URLs, and, optionally, the Central Redirect URL
for the SAML single sign-on flow. Even if single sign-on works successfully with your application at the custom
domain, you will need to follow the current procedure to enable single logout.

Prerequisites
You are logged on with a user with administrator role. See Account Member Roles.
You are aware of the productive landscape that hosts your account. See Landscape Hosts.
You are using a custom trust configuration for your account. See Configure SAP HANA Cloud Platform as a
Local Service Provider [page 1293].
You have configured the required trust settings for your account. See Configure Trust to the SAML Identity
Provider [page 1295].

Context
Central Redirect URL is the central node that facilitates assertion consumer service (ACS) and single logout (SLO)
service. By default, this node provided by SAP HANA Cloud Platform, and has the authn.<productive
landscape host>.com URL (for example, authn.hana.ondemand.com). If you want to use your applications
root URL as the ACS, instead of the central node, you will need to maintain the Central Redirect URL.
For Java applications, you can follow the procedure described in the current document. For HANA XS
applications, create an incident in component BC-IAM-IDS.

1192

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. In your Web browser, open the SAP HANA Cloud Platform cockpit and choose
navigation area.

Security

Trust

in the

2. Choose the Custom Application Domains Settings subtab.


3. Choose Edit. The custom domains properties become editable.
4. Select the Use Custom Application Domains option.
5. In Central Redirect URL, enter the URL of your application process that will serve as the central node.

Tip
The Central Redirect URL value has to be the same as the ACS endpoint value in the metadata of the
service provider.

Note
Make sure you do not stop the application VM specified as the Central Redirect URL. Otherwise, SAML
authentication will fail for all applications in your account.
6. The values in Custom Domain URLs are used for SLO. Enter the required values (all custom domain URLs) in
Custom Domain URLs.
7. Save your changes. The system generates the respective SLO endpoints. Test them in your Web browser and
make sure they are accessible from there.

Tip
The system will accept URL values with or without https://. Either way, the system will generate the
correct ACS and SLO endpoint URLs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1193

1.7.4.1.3

Custom Domains for Multitenant Applications

Configuration of custom domains has different setups related to the subscriptions of your account. Subscriptions
represent applications that your account has purchased for use from an application provider.
A subscription means that there is a contract between an application provider and a tenant that authorizes the
tenant to use the provider's application. As the consumer account, you do not own, deploy, or operate these
applications yourself. Subscriptions allow you to configure certain features of the applications and launch them
through consumer-specific URLs.
The default URL of a multitenant application is: https://<application_name><provider_account><consumer_account>.<domain>.
When you configure custom domains for such applications that are part of a subscription, the following scenarios
are possible:
The custom domain is owned by the application provider who uses an SSL host from their account quota. The
provider also does the configuration and assignment of the custom domain. The provider can assign a
subdomain of its own custom domain to a particular subscription URL. To do this, the provider needs to have
rights in both the provider and consumer account.
The customer (consumer) uses an SSL host from the consumer account quota. In this case, the customer
(consumer) owns the custom domain and the SSL host and is therefore able do the necessary configuration
on their own.

Related Information
Multitenant Applications [page 990]

1.7.4.1.4

Updating an Expired Certificate

When the SSL certificate you configured for the custom domain expires, you have to perform the same procedure
with the new certificate and remove the old one.

Context
If you had configured the certificate using the console client commands, follow the steps:

1194

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Procedure
1. Generate a new CSR by executing the neo generate-csr command with the appropriate parameters:
neo generate-csr --account myaccount --user mymail@example.com --host
hana.ondemand.com
--name mynewcert --certificate-distinguished-name
"C=GB,O=MyCompany,CN=example.com"
2. In the command line output, you get the generated new CSR. To sign your certificate, copy and send the text
to your trusted CA.
3. When you receive a signed SSL certificate from the CA, upload it to SAP HANA Cloud Platform by executing:
neo upload-domain-certificate --account myaccount --user mymail@example.com -host hana.ondemand.com --name mynewcert --location ./certificate.pub
4. Remove the expired certificate by executing neo unbind-domain-certificate.
neo unbind-domain-certificate --account myaccount --user mymail@example.com -host hana.ondemand.com --ssl-host mysslhostname
5. Assign the new certificate to your existing SSL host by executing neo bind-domain-certificate with the
appropriate parameters.
neo bind-domain-certificate --account myaccount --user mymail@example.com --host
hana.ondemand.com --ssl-host mysslhostname --certificate mynewcert
6. If you want to list your custom domain certificates, execute: neo list-domain-certificates.

Related Information
Configuring Custom Domains [page 1186]
bind-domain-certificate [page 103]
unbind-domain-certificate [page 251]
list-domain-certificates [page 193]

1.7.4.1.5

Removing the Custom Domain

If you do not want to use the custom domain any longer, you can remove using the console client commands. As a
result, your application will only be accessible only on its default hana.ondemand.com domain.

Procedure
1. In the console client command line, execute neo remove-custom-domain.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1195

Note that you will need the SSL host name defined when configuring the custom domain. You can view it by
executing list-ssl-hosts.
neo remove-custom-domain --account myacc --user mymail@example.com --host
hana.ondemand.com
--custom-domain www.example.com --ssl-host mysslhostname
2. Unbind the certificate.
neo unbind-domain-certificate --account myaccount --user mymail@example.com -host hana.ondemand.com --ssl-host mysslhostname
3. Delete the certificate.
Note that you will need the certificate name defined when configuring the custom domain.
neo delete-domain-certificate --account myaccount --user mymail@example.com -host hana.ondemand.com --name myfirstcert
4. Delete the SSL host.
neo delete-ssl-host --account myaccount --user mymail@example.com --host
hana.ondemand.com --name mysslhostname

Related Information
remove-custom-domain [page 214]
unbind-domain-certificate [page 251]
delete-domain-certificate [page 133]
delete-ssl-host [page 138]
list-ssl-hosts [page 207]

1.7.4.2

Platform Domains

Using platform domains, you can configure the application network availability or authentication policy. You can
achieve that by configuring the appropriate platform domain which will change the URL on which your application
will be accessible.

Prerequisites
You have installed and configured SAP HANA Cloud Platform console client. For more information, see Setting Up
the Console Client.

1196

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
The available platform domains are:
hana.ondemand.com - any application is accessible on this default domain after being deployed on SAP HANA
Cloud Platform
cert.hana.ondemand.com - enables client certificate authentication
svc.hana.ondemand.com - provides access within the same landscape; for internal communication and not
open on the Internet or other networks
You can configure the platform domains using the application-domains group of console client commands:
Add a Platform Domain [page 1197]
Check Configured Domains [page 1197]
Remove Platform Domains [page 1198]

1.7.4.2.1

Add a Platform Domain

Procedure
1. Open the command prompt and navigate to the folder containing neo.bat/neo.sh(<SDK installation
folder>/tools).
2. Configure the platform domain you have chosen by executing the add-platform-domain command.
add-platform-domain --account myacc --application myapp --user myuser -- host
hana.ondemand.com --platform-domain cert.hana.ondemand.com
As a result, the specified application will be accessible on cert.hana.ondemand.com and on the default
hana.ondemand.com domain.

1.7.4.2.2

Check Configured Domains

Procedure
1. To make sure the new platform domain is configured, execute the list-application-domains command:
list-application-domains --account myacc --application myapp --user myuser -host hana.ondemand.com

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1197

2. Check if the returned list of domains contains the platform domain you set.

1.7.4.2.3

Remove Platform Domains

Procedure
1. When you no longer want the application to be accessible on the configured platform domain, remove it by
executing the remove-platform-domain command:
remove-platform-domain --account myacc --application myapp --user myuser -- host
hana.ondemand.com --platform-domain cert.hana.ondemand.com
2. Repeat the step for each platform domain you want to remove.

Related Information
add-platform-domain [page 101]
list-application-domains [page 189]
remove-platform-domain [page 215]

1.7.5 Change Management with CTS+


You can enable transport of SAP HANA Cloud Platform applications using the enhanced Change and Transport
System (CTS+) tool.

Context
Using CTS+, you configure transport systems corresponding to your SAP HANA Cloud Platform accounts to
include applications in a change management process. You can use CTS+ to transport and promote your
applications, for example, from development to test or production environment. For more information about
setting up different environments, see Using Multiple Accounts for Staged Application Development [page 1160].

Caution
SAP HANA Cloud Platform applications cannot be exported to CTS+ and need to be added manually to a
transport request.

1198

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

To be transported, an application has to be packaged in a Multi-Target Appllication (MTA) archive. For more
information, see Multi-Target Applications [page 1199].
To trigger an import of an SAP HANA Cloud Platform application, configure the transport systems in CTS+
specifying the following parameters:
Application Type: HCP
Method: HTTP-based Deployment
For more information, see Connecting Further Applications with the Change and Transport System.
To configure the corresponding HTTP destinations, use the following format:
Target Host: slservice.<HCP_landscape_host>
Path Prefix: /slservice/slp/basic/<account>/slp
For more information, see Establishing a Connection Using a Destination (SM59).

1.7.5.1

Multi-Target Applications

A multi-target application (MTA) comprises of multiple parts (modules) created with different technologies and
deployed to different target runtimes but with a single common lifecycle.
The following is described in a deployment descriptor using YAML:
MTA modules
resources, which are not part of an MTA, but are required by the modules at runtime or at deployment time
dependencies between modules and resources
The MTA deployment descriptor (mtad.yaml) together with the modules is then packaged in a single archive
(MTA archive) that can be deployed on SAP HANA Cloud Platform. There could be more than one module of the
same type in an MTA archive.

MTA Deployment Descriptor


The MTA deployment descriptor defines the prerequisites and dependencies for the deployment of a multi-target
application. It contains three sections:
Global - schema version, application name and version, deployer version (currently 1.0)
Modules - a list of the application modules contained in the MTA deployment archive
Resources -a list of the resources that the modules require
For each module and for each resource, the following attributes are mandatory:
name: unique identifier of the module (or resource).
type: determines the runtime to which the specified module is deployed or specifies the required resource.
The following values are currently supported as module types:
com.sap.hcp.html5: used for deploying HTML5 modules
com.sap.java: used for deploying modules in the Java EE Web Profile and Java Web runtimes
java.tomcat: used for deploying modules in the Java Web Tomcat runtime

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1199

com.sap.fiori: used for deploying modules containing SAP Fiori configuration


com.sap.fiori.app: used for deploying modules containing SAP Fiori applications
com.sap.fiori.role: used for deploying custom SAP Fiori roles
The following value is currently supported as a resource type:
com.sap.hcp.persistence: used for binding a database with a specified identifier to a Java application
Depending on the type of the module or the resource, additional parameters may be specified in the parameters
subsection.
Modules support the following parameters:
Table 366:
Module type

Parameter

Description

Mandatory

com.sap.hcp.html5

name

HTML5 application name

yes

com.sap.hcp.html5

version

Application version to be used in the HTML5 runtime

yes

Note
HTML5 modules in the same version can be deployed
only once. In the version parameter, the usage of a
<timestamp> read-only variable is supported. Thus, a
new version string is generated with every deploy. For
example, version: '0.1.0-${timestamp}'

com.sap.java

name

Java application name

yes

com.sap.java

runtime

One of the following values:

yes

neo-java-web

neo-javaee6-web
depending on the runtime to be used

com.sap.java

runtime-version

If a specific runtime version needs to be pinned, for exam


ple 1.88 or 2.70

no

com.sap.java

java-version

The JVM major version, for example JRE 8

no

com.sap.java

jvm-arguments

The JVM arguments to be used

no

java.tomcat

name

Java application name

yes

java.tomcat

runtime-version

If a specific runtime version needs to be pinned, for exam

no

ple 2.35
com.sap.fiori.app

1200

html5-app-name

SAP Fiori application name

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

yes

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Module type

Parameter

Description

Mandatory

com.sap.fiori.app

html5-app-

SAP Fiori application version

no

version

Note
The same rules apply as for the

sap.com.hcp.html5 version parameter with


the difference that this parameter is optional.
Default value: '${timestamp}'

com.sap.fiori.role

name

SAP Fiori custom role name

yes

Note
Existing SAP Fiori custom role will be skipped during de
ployment.

Resources support the following parameters:


Table 367:
Resource type

Parameter

Description

Mandatory

com.sap.hcp.persis

id

Identifier of the database that will be bound to a deployed

yes

tence

Java application

Note
For a proper binding, the standard data source jdbc/
DefaultDB has to be set up for the Java application.

Note
Whenever a database is bound to a Java application, a
new empty schema is created. That is, the Java applica
tion can no longer access the data that was previously
stored.

Additionally, the following attributes can be used:


requires: used to define a dependency within the MTA. Starts an optional section that contains a list of
required resources, or required parts of other modules. The latter also have to be listed in the provided
sections of the corresponding modules.
provides: used to define a dependency within the MTA. Starts an optional section that contains configuration
data, which can be required by other modules within the same MTA.

Note
Always wrap any version value in single quotes so that it is not confused with a numeric value.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1201

Sample Content of the mtad.yaml file


The following is a sample deployment descriptor for an MTA consisting of one Java and one HTML5 module. In
this example, the HTML5 module has a dependency towards the Java module which at deploy time will result in
first deploying the Java application and then the HTML5 application.
The Java application itself requires a persistence resource.
_schema-version: '2.1'
ID: com.sap.example
version: 0.1.0
parameters:
hcp-deployer-version: '1.0.0'
modules:
- name: html5-module
type: com.sap.hcp.html5
requires:
- name: example-service
parameters:
name: example
version: 'version2'
- name: java-module
type: com.sap.java
provides:
- name: example-service
requires:
- name: example-database
parameters:
name: example
runtime: neo-java-web
runtime-version: '1'
java-version: JRE 7
jvm-arguments: -server
resources:
- name: example-database
type: com.sap.hcp.persistence
parameters:
id: databaseid

MTA Archive Structure


MTA archives are created in a way compatible with the JAR specification. This allows reusing common tools (for
creating, manipulating, signing and handling such archives). As the deployment descriptor does not contain any
information concerning the location of modules within the archive, this aspect is added by an archive manifest.
The archive descriptor (MANIFEST.MF) must be located within the META-INF folder of the archive.
The file MANIFEST.MF must contain a name section for each MTA module contained in the archive. In the name
section the following information must be added:
Name: the path within the MTA archive, where the corresponding module can be found
Content-Type: the type of the file that is used to deploy the corresponding module
MTA-module: the name of the module as it has been defined in the deployment descriptor

1202

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Sample content of the META-INF/MANIFEST.MF file:


Manifest-Version: 1.0
Name: examplejava.war
Content-Type: application/zip
MTA-Module: java-module
Name: examplehtml5.zip
Content-Type: application/zip
MTA-Module: html5-module

Related Information
JAR File Specification

1.7.5.2

Troubleshooting

While transporting SAP HANA Cloud Platform applications using the CTS+ tool, you might encounter some
issues. This section provides some troubleshooting information.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1203

Table 368: SL Service Troubleshooting


Message Text

Troubleshooting

Technical error [Invalid MTA archive


This error may occur when the MTA archive is not consistent.
[<mtar archive>]. MTA deployment
There are several different reasons for it:
descriptor (META-INF/mtad.yaml) could not
be parsed. Check the troubleshooting guide The MTA descriptor META-IND/mtad.yaml cannot be
parsed because it is syntactically incorrect according to
for guidelines on how to resolve
the YAML specification. For more information see http://
descriptor errors. Technical details: <>
yaml.org/spec

Make sure that the descriptor is compliant with the speci


fication. To validate the descriptor, you may use an online
YAML parser.

Note
Make sure you do not submit any confidential informa
tion to the online YAML parser.

The MTA descriptor may contain information that is not


suitable for SAP HANA Cloud Platform. Make sure the
MTA descriptor complies with the specification at MultiTarget Applications [page 1199].

The archive may not be suitable for deployment to SAP


HANA Cloud Platform. This might happen if, for example,
you attempt to deploy to SAP HANA Cloud Platform an
archive built for XSA. The technical details may contain a
text as the following:

"Unsupported module type "<module


type>" for platform type "HCPCLASSIC""
Technical error [Invalid MTA archive [<MTA The archive is inconsistent, for example, a module that is ref
name>]: Missing MTA manifest entry for
erenced in the META-INF/mtad.yaml is not present in the
module [<module name>]]

MTA archive or is not referenced correctly. Make sure that the


archive is compliant with the MTA specification available at
The Multi-Target Application Model

1.8

Security

This section describes how to secure your applications for SAP HANA Cloud Platform.
Table 369: Security in SAP HANA Cloud Platform
Technology

See

Java

Securing Java Applications [page 1211]

1204

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Technology

See

SAP HANA

Securing SAP HANA Applications [page 1211]

SAPUI5

Securing SAPUI5 Applications

HTML5

Securing HTML5 Applications [page 1323]

Related Information
Identity and Access Management [page 1205]

1.8.1 Identity and Access Management


SAP HANA Cloud Platform supports identity federation and single sign-on with external identity providers. The
current section provides an overview of the supported scenarios.

Contents
Overview [page 1205]
Identity Federation with a Corporate Identity Provider [page 1206]
Identity Federation with an SAP Cloud Identity Tenant [page 1207]
Default Identity Federation with SAP ID Service [page 1208]
Managing Roles [page 1209]
Protecting Applications with OAuth 2.0 [page 1210]

Overview
To enable you to seamlessly integrate SAP HANA Cloud Platform applications with existing on-premise identity
management infrastructures, SAP HANA Cloud Platform introduces single sign-on (SSO) and identity federation
features. In SAP HANA Cloud Platform, identity information is provided by identity providers (IdP), and not stored
on SAP HANA Cloud Platform itself. You can have a different IdP for each account you own, and this is
configurable using the Cockpit.
The following graphic illustrates the high-level architecture of identity management in SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1205

If you don't have a corporate identity management infrastructure, you can use SAP ID Service. It is the default
identity provider for SAP HANA Cloud Platform, and you can use it out of the box, without having to configure SSO
and identity federation.
SAP HANA Cloud Platform also allows you to implement applications protected with the OAuth protocol.

Identity Federation with a Corporate Identity Provider


SAP HANA Cloud Platform applications can delegate authentication and identity management to an existing
corporate IdP that can, for example, authenticate your company's employees. It aims at providing a simple and
flexible solution: your employees (or customers, partners, and so on) can single sign-on with their corporate user
credentials, without a separate user store and account in SAP HANA Cloud Platform. All information required by
SAP HANA Cloud Platform about the employee can be passed securely with the logon process, based on a proven
and standardized security protocol. There is no need to manage additional systems that take care for complex
user account synchronization or provisioning between the corporate network and SAP HANA Cloud Platform.
Only the configuration of already existing components on both sides is needed, which simplifies administration
and lowers total cost of ownership significantly. Even existing applications can be "federation-enabled" without
changing a single line of code.
The following graphic illustrates this scenario.

1206

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You need to configure trust at several levels:


At the service provider of your account in SAP HANA Cloud Platform
Configuring trust on SAP HANA Cloud Platform to the corporate IdP
Configuring trust on the corporate IdP to SAP HANA Cloud Platform
See ID Federation with the Corporate Identity Provider [page 1292].

Identity Federation with an SAP Cloud Identity Tenant


You can use SAP Cloud Identity service as an identity provider for your applications. SAP Cloud Identity is a cloud
solution for identity lifecycle management. Using it, you can benefit from features such as user base, user
provisioning, corporate branding or logo, and social IdP integration. See SAP Cloud Identity Service.
SAP Cloud Identity service provides an easy way for your applications to delegate authentication and identity
management and keep developers focused on the business logic. It allows authentication decisions to be removed
from the application and handled in a central service.
SAP HANA Cloud Platform offers solid integration with SAP Cloud Identity service. When you request an SAP
Cloud Identity tenant for your SAP HANA Cloud Platform account, you can automatically use it as a trusted IdP.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1207

See ID Federation with a SAP Cloud Identity Tenant [page 1301].

Default Identity Federation with SAP ID Service


SAP ID service is the place where you have to register to get initial access to SAP HANA Cloud Platform. If you are
a new user, you can use the self-service registration page . SAP ID Service manages the SAP Community
Network users, SAP Service Marketplace users and the users of several other SAP sites. If you already have such
a user, then you are already registered with SAP ID Service.
In addition, you can use SAP ID Service as an identity provider for your identity federation scenario, or if you do
not want to use identity federation. Trust to SAP ID Service is pre-configured on SAP HANA Cloud Platform by
default, so you can start using it without further configuration. Optionally, on SAP HANA Cloud Platform you can
configure additional trust settings, such as service provider registration, role assignments to users and groups,
and so on.
SAP ID service consists of the following main components:
A central user store for all your identities that require access to protected resources of your application(s)
A standards-based Single Sign-On (SSO) service that enables users to log on only once and get seamless
access to all your applications deployed using SAP HANA Cloud Platform
The following graphic illustrates the identity federation with SAP ID Service scenario.

1208

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Managing Roles
Roles allow you to control the access to application resources in SAP HANA Cloud Platform, as specified in Java
EE. In SAP HANA Cloud platform, you can assign groups or individual users to a role. Groups are collections of
roles that allow the definition of business-level functions within your account. They are similar to the actual
business roles existing in an organization.
The following graphic illustrates a sample scenario for role, user and group management in SAP HANA Cloud
Platform. It shows a person, John Doe, with corporate role: sales representative. On SAP HANA Cloud Platform, all
sales representatives belong to group Sales, which has two roles: CRM User and Account Owner. On SAP HANA
Cloud, John Doe inherits all roles of the Sales group, and has an additional role: Administrator.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1209

See Managing Roles [page 1282].

Protecting Applications with OAuth 2.0


OAuth 2.0 is a widely adopted security protocol for protection of resources over the Internet. It is used by many
social network providers and by corporate networks. It allows an application to request authentication on behalf of
users with third-party user accounts, without the user having to grant its credentials to the application. SAP HANA
Cloud Platform provides an API for developing OAuth-protected applications. You can configure the required
scopes and clients using the Cockpit.
The following graphic illustrates protecting applications with OAuth on SAP HANA Cloud Platform.

SAP HANA Cloud Platform supports two basic OAuth 2.0 flows:
Authorization code grant - there is a human user who authorizes a mobile application to access resources on
his or her behalf. See Protecting Applications with OAuth 2.0 [page 1227]
Client credentials grant - there is no human user but a device instead. In such case, the access token is
granted on the basis of client credentials only. See Enabling OAuth 2.0 Client Credentials Grant [page 1234]

1210

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Using an On-Premise User Store


You can use a user store from an on-premise system for user authentication scenarios. SAP HANA Cloud
Platform supports two types of on-premise user stores:
SAP Single Sign-On
Microsoft Active Directory
See Using an On-Premise User Store [page 1303].

1.8.2 Securing SAP HANA Applications


In this section, you can find information relevant for securing SAP HANA applications running on SAP HANA Cloud
Platform.
Table 370: Security Information
Info Type

See

General security concepts for SAP HANA applications

SAP HANA Security Guide

Specific security concepts for SAP HANA applications running Configuring SAML 2.0 Authentication [page 1022]
on SAP HANA Cloud Platform
Setting up SAML authentication for SAP HANA XS applica
tions

How to Set Up SAML Authentication For Your SAP HANA


Cloud Platform Trial Instance

1.8.3 Securing Java Applications


SAML 2.0 Authentication
SAP HANA Cloud uses the Security Assertion Markup Language (SAML) 2.0 protocol for authentication and
single sign-on.
By default, SAP HANA Cloud Platform is configured to use SAP ID service as identity provider (IdP), as specified in
SAML 2.0. You can configure trust to your custom IdP, to provide access to the cloud using your own user
database.

Java EE Identity and Access Management


SAP ID Service provides Identity and Access Management for Java EE Web applications hosted on SAP HANA
Cloud Platform through the mechanisms described in Java EE Servlet specification and through dedicated APIs.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1211

Protecting Applications from Cross-Site Scripting (XSS)


Cross-site Scripting (XSS) is one of the most common types of malicious attacks to Web applications. In order to
help protecting against this type of attacks, SAP HANA Cloud Platform provides a common output encoding
library to be used from applications.

Protecting from Cross-Site Request Forgery (CSRF)


Cross-Site Request Forgery (CSRF) is another common type of attack to Web applications. You can protect
applications running on SAP HANA Cloud Platform from CSRF, based on the Tomcat Prevention Filter.

Related Information
ID Federation with the Corporate Identity Provider [page 1292]
Security Testing on the Cloud (with a Local Identity Provider) [page 1273]
Managing Roles [page 1282]
Enabling Authentication [page 1213]
Protecting from Cross-Site Scripting (XSS) [page 1243]
Using the Apache Tomcat CSRF Prevention Filter [page 1237]

1.8.3.1

Security Development

This section describes how you can implement security in your applications.
SAP HANA Cloud Platform provides the following APIs for user management and authentication:
Package

Description

User Management API

com.sap.security.um

The user management API can be used to create and delete


users or update user information.

com.sap.security.um.user
com.sap.security.um.service
Authentication API

com.sap.security.auth.login

1212

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

The authentication API provides basic login modules and


callback handlers implementations and a custom
LoginContext implemenatation. It relies on the user
management API to provide user information required during
the authentication process.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Package

Description

Password Storage API

com.sap.cloud.security.password

The password storage API allows users to securely persist


passwords and key phrases, such as passwords for keystore
files.

Related Information
Enabling Authentication [page 1213]
Enforcing Authorizations [page 1220]
Working with User Profile Attributes [page 1223]
Enabling Logout [page 1224]
Protecting Applications with OAuth 2.0 [page 1227]
Cryptography [page 1246]
Storing Passwords [page 1267]
Protecting from Cross-Site Request Forgery [page 1235]
Protecting from Cross-Site Scripting (XSS) [page 1243]

1.8.3.1.1

Enabling Authentication

Prerequisites
You have installed the SAP HANA Cloud Platform Tools for Java. See Installing Java Tools for Eclipse and SDK
[page 33].
You have created a simple HelloWorld application. See Creating a HelloWorld Application [page 47].
If you want to use Java EE 6 Web Profile features in your application, you have downloaded the SAP HANA
Cloud SDK for Java EE 6 Web Profile. See Using Java EE 6 Web Profile [page 966]

Context
Using Declarative Authentication in a Web Application [page 1214]
Using Programmatic Authentication in a Web Application [page 1217]
Handling Session Timeout [page 1218]
Troubleshooting [page 1219]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1213

1.8.3.1.1.1 Using Declarative Authentication in a Web


Application
Context
The Java EE servlet specification allows the security mechanisms for an application to be declared in the web.xml
deployment descriptor.
SAP HANA Cloud Platform supports the following default authentication methods:
Table 371: Authentication Methods
Authentication Method

Default Options

Description

Sample Usecase

FORM

Trusted SAML 2.0 identity


provider

FORM authentication imple

Application-to-Application

sertion Markup Language

You want to delegate authen


tication to your corporate
identity provider.

SSO

(SAML) 2.0 protocol. Authen

mented over the Security As

tication is delegated to SAP ID


service or custom identity
provider.
(Optional) If you configure a
connection with an on-prem
ise user store, the existence
of the user is also verified in
the on-premise SAP NetWea
ver AS Java system. See Us
ing an SAP System as an OnPremise User Store [page
1305].
BASIC

User name and password

HTTP BASIC authentication


delegated to SAP ID service
or an on-premise SAP Net
Weaver AS Java system. Web
browsers prompt users to en
ter a user name and pass
word.

Example 1: You want to dele


gate authentication to SAP ID
service. Users will log in with
their SCN user name and
password.

By default, SAP ID service is

Java system used as a user

used. (Optional) If you config

store. You want users to log in

ure a connection with an on-

using the user name and

premise user store, the au

password stored in AS Java.

Example 2: You have an onpremise SAP NetWeaver AS

thentication is delegated to an
on-premise SAP NetWeaver
AS Java system. See Using an
SAP System as an On-Prem
ise User Store [page 1305].

1214

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Authentication Method

Default Options

Description

Sample Usecase

CERT

Client certificate

Used for authentication only


with client certificate. See En
abling Client Certificate Au
thentication [page 1256].

Users log in using their corpo


rate client certificates.

BASICCERT

User name and password

Used for authentication either


with client certificate or with
user name and password. See
Enabling Client Certificate Au
thentication [page 1256].

Within the corporate network,


users log in using their client
certificates. Outside that net
work, users log in using user
name and password.

Client certificate

OAUTH

OAuth 2.0 token

Authentication according to
the OAuth 2.0 protocol with
an OAuth access token. See
Protecting Applications with
OAuth 2.0 [page 1227]

You have a mobile application


consuming REST APIs using
the OAuth 2.0 protocol. Users
log in using an OAuth access
token.

SAML2

Trusted SAML 2.0 identity


provider

See FORM.

See FORM.

Application-to-Application
SSO

If you need to configure the default options of an authentication method, or define new methods, see Configuring
Authentication for Your Application [page 1280]

Tip
We recommend using FORM authentication method.

Note
By default, any other methods (DIGEST, CLIENT-CERT, or custom) that you specify in the web.xml are
executed as FORM. You can configure those methods using the Authentication Configuration section at Java
application level in the Cockpit. See Configuring Authentication for Your Application [page 1280].

Results
When FORM authentication is used, you are redirected to SAP ID service or another identity provider, where
you are authenticated with your user name and password. The servlet content is then displayed.
When BASIC authentication is used, you see a popup window and are prompted to enter your credentials. The
servlet content is then displayed.

Example
Example 1: Using FORM Authentication

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1215

The following example illustrates using FORM authentication. It requires all users to authenticate before
accessing the protected resource. It does not, however, manage authorizations according to the user roles - it
authorizes all authenticated users.
<login-config>
<auth-method>FORM</auth-method>
</login-config>
<security-constraint>
<web-resource-collection>
<web-resource-name>Protected Area</web-resource-name>
<url-pattern>/index.jsp</url-pattern>
<url-pattern>/a2asso.jsp</url-pattern>
</web-resource-collection>
<auth-constraint>
<!-- Role Everyone will not be assignable -->
<role-name>Everyone</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>All SAP HANA Cloud Platform users</description>
<role-name>Everyone</role-name>
</security-role>

Note
All authenticated users implicitly have the Everyone role. You cannot remove or edit this role. In the SAP
HANA Cloud Platform Cockipt, the Everyone role is not listed in role mapping (see Managing Roles [page
1282] ).
Example 2: Using FORM Authentication with Roles
If you want to manage authorizations according to user roles, you should define the corresponding constraints
in the web.xml. The following example defines a resource available for users with role Developer, and another
resource for users with role Manager:
<security-constraint>
<web-resource-collection>
<web-resource-name>Developer Page</web-resource-name>
<url-pattern>/developer.jsp</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Developer</role-name>
</auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Manager Page</web-resource-name>
<url-pattern>/manager.jsp</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Manager</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
</login-config>

1216

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Remember
If you define roles in the web.xml, you need to manage the role assignments of users after you deploy your
application on SAP HANA Cloud Platform. See Managing Roles [page 1282]

1.8.3.1.1.2 Using Programmatic Authentication in a Web


Application
Context
With programmatic authentication, you do not need to declare constrained resources in the web.xml file of your
application. Instead, you declare the resources as public, and you decide in the application logic when to trigger
authentication. In this case, you have to invoke the authentication API explicitly before executing any application
code that should be protected. You also need to check whether the user is already authenticated, and should not
trigger authentication if the user is logged on, except for certain scenarios where explicit re-authentication is
required.
If you trigger authentication in an SAP HANA Cloud Platform application protected with FORM, the user is
redirected to SAP ID service or custom identity provider for authentication, and is then returned to the original
application that triggered authentication.
If you trigger authentication in an SAP HANA Cloud Platform application protected with BASIC, the Web browser
displays a popup window to the user, prompting him or her to provide a user name and password.
package hello;
import java.io.IOException;
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.security.auth.login.LoginContextFactory;
public class HelloWorldServlet extends HttpServlet {
...
protected void doGet(HttpServletRequest request,
HttpServletResponse response) throws ServletException, IOException {
String user = request.getRemoteUser();
if (user != null) {
response.getWriter().println("Hello, " + user);
} else {
LoginContext loginContext;
try {
loginContext = LoginContextFactory.createLoginContext("FORM");
loginContext.login();
response.getWriter().println("Hello, " + request.getRemoteUser());
} catch (LoginException e) {
e.printStackTrace();
}
}
...
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1217

protected void doPost(HttpServletRequest request,


HttpServletResponse response) throws ServletException, IOException {
doGet(request, response);
}
...

In the example above, you create LoginContext and call its login() method.

Note
All the steps below are described using the FORM authentication method, but they can also be applied to
BASIC.

Procedure
1. Open the source code of your HelloWorldServlet class. Add the code for programmatic authentication to the
doGet() method.
2. Make the doPost() method invoke programmatic authentication. This is necessary because the SAP ID
service always returns the SAML2 response over an HTTP POST binding, and in order to be processed
correctly, the LoginContext login must be called during the doPost() method. The authentication framework
is responsible for restoring the original request using GET after successful authentication. Another alternative
is that your doPost() method simply calls your doGet() method.
3. Test your application on the local server. It does not need to be connected to the SAP ID service, and
authentication is done against local users. For more information, see Testing User Authentication on the Local
Server.
4. Deploy the application to SAP HANA Cloud Platform. You are redirected to the SAP ID service or another
identity provider, where you are authenticated with your user account. The servlet content is then displayed
and you should be able to see the content returned by the hello servlet.
When BASIC authentication is used, you should see a popup window prompting you to provide credentials to
authenticate. Once these are entered successfully, the servlet content is displayed.

1.8.3.1.1.3 Handling Session Timeout


You can configure session timeout using the web.xml. Default value: 20 minutes. For example:
<session-config>
<session-timeout>15</session-timeout> <!-- in minutes -->
</session-config>
After the specified timeout, user sessions are invalidated. If the user tries to access an invalidated session, SAP
HANA Cloud Platform will return a login page in its response, so the user can enter credentials again. . If you are
using SAML as login protocol, you cannot rely on the response code to find out the your session is expired
because it will be 200 or 302. To check whether the response is for triggering new login, get the
com.sap.cloud.security.login HTTP header, and reload the page. For example:
jQuery(document).ajaxComplete(function(e, jqXHR){

1218

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

if(jqXHR.getResponseHeader("com.sap.cloud.security.login")){
alert("Session is expired, page
shall be reloaded.");
window.location.reload();
}
}

1.8.3.1.1.4 Troubleshooting
When testing in the local scenario, and your application has Web-ContextPath: /, you might experience the
following problem with Microsoft Internet Explorer:
After authentication you see:

Output Code
HTTP Status 405 - HTTP method POST is not supported by this URL

If you see such issues, you will have to add the following code into your protected resource:
@Override
protected void doPost(HttpServletRequest req, HttpServletResponse resp)
throws ServletException, IOException { doGet(req, resp); }

Next Steps
You can now test the application locally. See Security Testing Locally [page 1269].
After testing, you can proceed with deploying the application to SAP HANA Cloud Platform. See Deploying and
Updating Applications [page 973].
After deploying on SAP HANA Cloud Platform, you need to configure the role assignments users and groups will
have for this application. See Managing Roles [page 1282].
Optionally, you can configure the authentication options applied in the authentication method that you defined in
the web.xml or programmatically. See Configuring Authentication for Your Application [page 1280].

Example
To see the end-to-end scenario of managing roles on SAP HANA Cloud Platform, watch the complete video
tutorial Managing Roles in SAP HANA Cloud Platform .

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1219

1.8.3.1.2

Enforcing Authorizations

Use the isUserInRole method of the servlet request (javax.servlet.HttpServletRequest) to manage


authorizations for users. The following example returns a 403 error if the user accessing this servlet does not have
role Developer:
protected void doGet(HttpServletRequest request, HttpServletResponse response)
throws ServletException, IOException {
PrintWriter out = response.getWriter();

if(!request.isUserInRole("Developer")){
response.sendError(403, "Logged in user does not have role Developer");
return;
} else {
out.println("Hello developer");
}

Next Steps
You can now test the application locally. For more information, see Security Testing Locally [page 1269].
After testing, you can proceed with deploying the application to SAP HANA Cloud Platform. For more information,
see Deploying and Updating Applications [page 973].
After deploying on SAP HANA Cloud Platform, you need to configure the role assignments users and groups will
have for this application. For more information, see Managing Roles [page 1282].

1.8.3.1.3

Using the Authorization Management REST API

The Authorization Management API is a REST API that allows you to manage role and group assignments of users
for Java and HTML5 applications and subscriptions.

Context
The Authorization Management API is protected with the OAuth 2.0 Client Credentials flow.
For detailed description of the available methods, see the Authorization Management API.

Note
HTML5 applications are using a more feature-rich authorization model, which allows to assign permissions on
various URI paths. Those permissions are then mapped to SAP HANA Cloud Platform custom roles. Since all
HTML5 applications are run via a central app called dispatcher from the services account all of them share
the same custom roles and mappings. This the reason why when you are managing roles of HTML5
applications, , in the API calls you need to use dispatcher for appName and services for providerAccount name.

1220

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1. Create an OAuth Client


Context
To obtain an OAuth access token via the OAuth Client Credentials flow, you first need to create an OAuth client in
the Cockpit. The OAuth client is identified by a client ID and protected with a client secret. In a later step, those are
used to obtain the OAuth API access token from the OAuth access token endpoint.

Procedure
1. In your Web browser, open the Cockpit. See Cockpit [page 84].
2. (If not done already) Enable beta features for your account. See Using Beta Features in Accounts [page 22].
3. Go to the

Security

OAuth

section.

4. Enter the Platform APIs (Beta) tab.


5. Choose Create New Client for the Authorization Management API.
6. Copy the generated client ID and client secret, and save them locally.

Caution
Make sure you save the generated client credentials. Once you close the confirmation dialog, you cannot
retrieve the generated client credentials from SAP HANA Cloud Platform.

Restriction
Currently, you cannot manage the generated clients. This means you cannot delete or disable them, or
change their secret.

2. Get an OAuth Access Token


Context
Once you have the client credentials, you need to send an HTTP POST request to the OAuth access token endpoint
and use the client ID and client secret as user and password for HTTP Basic Authentication. You will receive the
access token as a response. By default, the access token received in this way is valid 1500 seconds (25 minutes).
You can configure its validity length.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1221

Procedure
1. Send a POST request to the OAuth access token endpoint. The URL is landscape specific, and looks like this:
https://api.<landscape_ host>/oauth2/apitoken/v1?grant_type=client_credentials
See Landscape Hosts [page 32].
The parameter grant_type=client_credentials notifies the endpoint that the Client Credentials flow is used.
2. Get and save the access token from the received response from the endpoint.
The response is a JSON object, whose access_token parameter is the access token. It is valid for the specified
time (in seconds) in the expires_in parameter. (default value: 1500 seconds).

Example
Retrieving an access token on the trial landscape will look like this:
POST https://api.hanatrial.ondemand.com/oauth2/apitoken/v1?
grant_type=client_credentials
Headers:
Authorization: Basic eW91ckNsaWVudElEOnlvdXJDbGllbnRTZWNyZXQ
The eW91ckNsaWVudElEOnlvdXJDbGllbnRTZWNyZXQ String in the above request is the Base-64 encoded
<clientID>:<ClientSecret>.
You receive a response like this:

Output Code
{

"access_token": "51ddd94b15ec85b4d54315b5546abf93",
"token_type": "Bearer",
"expires_in": 1500,
"scopes": [
"hcp.manageAuthorizationSettings",
"hcp.readAuthorizationSettings"
]

3. Request an API Method


Procedure
In the requests to this API, include the access token as a header with name Authorization and value Bearer <token
value>.

Example
GET https://api.hanatrial.ondemand.com/authorization/v1/accounts/p1234567trial/
users/roles/?userId=myUser

1222

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Headers:
Authorization: Bearer 51ddd94b15ec85b4d54315b5546abf93

Related Information
Authorization Management API

1.8.3.1.4

Working with User Profile Attributes

The user management API provides access to users via the user interface. It can be used to get and create users
or to read and update their information.
To access user information, you need to get to com.sap.security.um.user.UserProvider.
To get UserProvider, first, declare a resource reference in the web.xml. For example:
<resource-ref>
<res-ref-name>user/Provider</res-ref-name>
<res-type>com.sap.security.um.user.UserProvider</res-type>
</resource-ref>
Then look up UserProvider via JNDI in the source code of your application. For example:
InitialContext ctx = new InitialContext();
UserProvider userProvider = (UserProvider) ctx.lookup("java:comp/env/user/
Provider");
User user = null;
if (request.getUserPrincipal() != null) {
user = userProvider.getUser(request.getUserPrincipal().getName());
}

Note
If you are using the SDK for Java EE 6 Web Profile, you can look up UserProvider via annotation (instead of
embedding JNDI lookup in the code). For example:
@Resource
private UserProvider userProvider;
try {
// Read the currently logged in user from the user storage
return userProvider.getUser(request.getRemoteUser());
} catch (PersistenceException e) {
throw new ServletException(e);
}
Alternatively, you can access UserProvider using com.sap.security.um.user.UserManagementAccessor. For
example:
import com.sap.security.um.user.User;
import com.sap.security.um.user.UserProvider;
import com.sap.security.um.service.UserManagementAccessor;

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1223

...
// Check for a logged in user
if (request.getUserPrincipal() != null) {
try {
// UserProvider provides access to the user storage
UserProvider users = UserManagementAccessor.getUserProvider();
// Read the currently logged in user from the user storage
User user = users.getUser(request.getUserPrincipal().getName());
// Print the user name and email
response.getWriter().println("User name: " + user.getAttribute("firstname") + "
" + user.getAttribute("lastname"));
response.getWriter().println("Email: " + user.getAttribute("email"));
} catch (Exception e) {
// Handle errors
}
}

Next Steps
You can now test the application locally. For more information, see Security Testing Locally [page 1269].
After testing, you can proceed with deploying the application to SAP HANA Cloud Platform. For more information,
see Deploying and Updating Applications [page 973].

1.8.3.1.5

Enabling Logout

This topic describes how to enable users to log out from your applications.

Context
You can provide a logout operation for your application by adding a logout button or logout link.
When logout is triggered in a SAP HANA Cloud Platform application, the user is redirected to the identity provider
to be logged out there, and is then returned to the original application URL that triggered the logout request.
The following code provides a sample servlet that handles logout operations. When loginContext.logout() is
used, the system automatically redirects the logout request to the identity provider, and then returns the user to
the logout servlet again.
import javax.security.auth.login.LoginContext;
import javax.security.auth.login.LoginException;
import com.sap.security.auth.login.LoginContextFactory;
...
public class LogoutServlet extends HttpServlet {
. . .
//Call logout if the user is logged in
LoginContext loginContext = null;
if (request.getRemoteUser() != null) {
try {
loginContext = LoginContextFactory.createLoginContext();
loginContext.logout();

1224

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

} catch (LoginException e) {
// Servlet container handles the login exception
// It throws it to the application for its information
response.getWriter().println("Logout failed. Reason: " + e.getMessage());
}
} else {
response.getWriter().println("You have successfully logged out.");
}
. . .
}
We add a logout link to the HelloWorld servlet, which references this logout servlet:
response.getWriter().println("<a href=\"LogoutServlet\">Logout</a>");

(Optional) Protecting Logout from Cross-Site Request Forgery (CSRF)


(nonCSRF is a common Web hacking attack. For more information, see Cross-Site Request Forgery (CSRF)
SAP link). You might consider protecting the logout operations for your applications from CSRF to prevent your
users from potential CSRF attack related problems (for example, XSRF denial of service on single logout).

Note
Although SAP HANA Cloud Platform provides ready-to-use support for CSRF filtering, with logout operations
you cannot use it. The reason is users are sent to the logout servlet twice: first, when they trigger logout by
clicking a button/link, and second, when the identity provider has logged them out and redirected them back to
the application. You cannot specify the system to apply the CSRF filter first time, and skip it the second time.
The following example provides XSRF-protected logout.

Source Code
LoginContext loginContext = null;
if (request.getRemoteUser() != null) {
Object csrfTokenFromSession = request.getSession().getAttribute("csrflogout");
String csrfTokenFromRequest = request.getParameter("csrf-logout");
if (request.getSession(false) != null && csrfTokenFromRequest != null &&
csrfTokenFromSession != null
&& csrfTokenFromSession.toString().equals(csrfTokenFromRequest)) {
try {
loginContext = LoginContextFactory.createLoginContext();
loginContext.logout();
} catch (LoginException e) {
// Servlet container handles the login exception
// It throws it to the application for its information
response.getWriter().println("Logout failed. Reason: " +
e.getMessage());
}
} else {
response.sendError(403, "No valid csrf token found in request. No logout
will be performed.");
}
} else {
response.getWriter().println("You have successfully logged out.");
}

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1225

We add a logout link to the HelloWorld servlet, which references this logout servlet:

Source Code
try {

HttpSession session = request.getSession(false);


if(session != null){
long tokenValue = 0L;
if(session.getAttribute("csrf-logout") != null){
tokenValue = (Long) session.getAttribute("csrf-logout");
} else {
SecureRandom instance =
java.security.SecureRandom.getInstance("SHA1PRNG");
instance.setSeed(instance.generateSeed(5));
tokenValue = instance.nextLong();
session.setAttribute("csrf-logout", tokenValue);
}
response.getWriter().println("<a href=\"LogoutServlet?csrflogout="+tokenValue+"\">Logout</a>");
}
} catch (NoSuchAlgorithmException e) {
throw new ServletException(e);
}

Preventing Common Logout Problems


Unprotect the Logout Servlet
For efficient logout to work, the servlet handling logout must not be protected in the web.xml. Otherwise,
requesting logout will result in a login request. The following example illustrates how to unprotect successfully a
logout servlet. The additional <security-constraint>...</security-constraint> section explicitly enables access to
the logout servlet.
<security-constraint>
<web-resource-collection>
<web-resource-name>Start Page</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>Everyone</role-name>
</ auth-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Logout</web-resource-name>
<url-pattern>/LogoutServlet</url-pattern>
</web-resource-collection>
</security-constraint>
Avoid Mapping Servlet Resources to /* in the web.xml
Avoid mapping a servlet to resources using wildcard (<url-pattern>/*</url-pattern> in the web.xml). This may
lead to an infinite loop. Instead, map the servlet to particular resources, as in the following example:
<servlet-mapping>
<servlet-name>Logout Servlet</servlet-name>

1226

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

<url-pattern>/LogoutServlet</url-pattern>
<servlet-class>test.LogoutServlet</servlet-class>
</servlet-mapping>

Next Steps
You can now test the application locally. For more information, see Security Testing Locally [page 1269].
After testing, you can proceed with deploying the application to SAP HANA Cloud Platform. For more information,
see Deploying and Updating Applications [page 973].

1.8.3.1.6

Handling Commmon Errors with Basic


Authentication in SAP ID Service

This section describes the error messages you may encounter when using BASIC authentication with SAP ID
Service as an identity provider.
For more information about using BASIC authentication, see Enabling Authentication [page 1213].
Table 372: Error Messages
Description

Error Message

Your account is temporarily locked. It will be automatically un SAP ID Service has registered five unsuccessful login at
locked in 60 minutes.
tempts for this account in a short time. For security reasons,
your account is disabled for 60 minutes.
Password authentication is disabled for your account. Log in
with a certificate.

The owner of this account has disabled password authentica


tion using their user profile settings in SAP ID service.

Inactive account. Activate it via your account creation confir


mation email

This is a new account and you havent activated it yet. You will
receive an e-mail confirming your account creating, and con
taining an account activation link.

Login failed. Contact your administrator.

You cannot log in for a reason different from all others listed
here.

1.8.3.1.7

Protecting Applications with OAuth 2.0

SAP HANA Cloud Platform supports the OAuth 2.0 protocol as a reliable way to protect application resources.
The current document describes the specifics of implementing an OAuth-protected application (resource server)
for SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1227

Overview
OAuth 2.0
OAuth has taken off as a standard way and a best practice for applications and websites to handle authorization.
OAuth defines an open protocol for allowing secure API authorization of desktop, mobile and web applications
through a simple and standard method.
OAuth is based on granting access without explicit credentials sharing. OAuth:
Avoids storing credentials at the third-party location
Limits the access permissions granted to third parties
Enables easy access right revocation without the need to change credentials
In this way, OAuth mitigates some of the common concerns with authorization scenarios.
The following table shows the roles defined by OAuth, and their respective entities in SAP HANA Cloud Platform:
Role

Entity in SAP HANA Cloud Platform

Description

Resource owner

User

An entity that holds protected assets.


This entity is capable of granting access
to those assets under its control.

Resource server

Application

The server that hosts the resource


owner's protected assets.

Client

Third-party application

The third party entity that needs to


access the protected assets on behalf of
the resource owner.

Authorization server

SAP HANA Cloud Platform


infrastructure

The server that manages the


authentication and authorization of the
different entities involved.

For more information, see the OAuth 2.0 Specification

Using OAuth in SAP HANA Cloud Platform


If you want your application on SAP HANA Cloud Platform to be accessible from mobile native clients, we
recommend using the OAuth 2.0 protection filter inside your Java EE application as described in the current
document.
For more information, see Enabling Authentication [page 1213]

Protecting Resources Declaratively


If you want to implement a login based on credentials in the form of an OAuth token, you can do that by using
OAuth as a login method in your application web.xml. For example:
<login-config>
<auth-method>OAUTH</auth-method>

1228

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

</login-config>
<security-constraint>
<web-resource-collection>
<web-resource-name>Protected Area</web-resource-name>
<url-pattern>/rest/get-photos</url-pattern>
</web-resource-collection>
<auth-constraint>
<!-- Role Everyone will not be assignable -->
<role-name>Everyone</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>All SAP HANA Cloud Platform users</description>
<role-name>Everyone</role-name>
</security-role>
Working with User Attributes
In your protected application you can acquire the user ID and attributes as described in Working with User Profile
Attributes [page 1223].
There are two additional user attributes you can use to retrieve token specific information:
com.sap.security.oauth2.clientId - holds information about the OAuth client ID
com.sap.security.oauth2.grantedScopes - holds information about the granted scopes.
Handling Sessions
The Java EE specification requires session support on the client side. Sessions are maintained with a cookie which
the client receives during the authentication and then passes it along to the server on every request. The OAuth
specification, however, does not necessarily require the client to support such a session mechanism. That is, the
support of cookies is not mandatory. On every request, the client passes along to the server only the token
instead of passing cookies. Using the OAuth login module described in the Protecting Resources Declaratively
section, you can implement a user login based on an access token. The login, however, occurs on every request,
and thus it implies the risk of creating too many sessions in the Web container.
To use requests that do not hold a Web container session, use a filter with the proper configuration, as described
in the following example:
<filter>
<display-name>OAuth scope definition for viewing a photo album</display-name>
<filter-name>OAuthViewPhotosScopeFilter</filter-name>
<filter-class>
com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
</filter-class>
<init-param>
<param-name>scope</param-name>
<param-value>view-photos_upload-photos</param-value>
</init-param>
<init-param>
<param-name>no-session</param-name>
<param-value>false</param-value>
</init-param>
</filter>
Checking Scopes Declaratively
One of the ways to enforce scope checks for resources is to declare the resource protection in the web.xml. This is
done by specifying the following elements:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1229

Element

Description

Servlet filter class

Enter as value

com.sap.cloud.security.oauth2.OAuthAuthori
zationFilter. See OAuthAuthorizationFilter.
On request it checks if the request contains a valid OAuth
token to access the resources mapped to the configured
scope.
Protected resources

Could be given as URL pattern or servlet.

Initial parameters

With these, you specify the scope, user principal and HTTP
method:

scope

http-method

user-principal - if set to "yes", you will get the user


ID

no-session - if you set this to "true", the session will


be destroyed when you finish using the filter. This means
that each time the filter is used, a new session will be
created. Default value: false.

The following example shows a sample web.xml for defining and configuring OAuth resource protection for the
application.
<filter>
<display-name>OAuth scope definition for viewing a photo album</display-name>
<filter-name>OAuthViewPhotosScopeFilter</filter-name>
<filter-class>
com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
</filter-class>
<init-param>
<param-name>scope</param-name>
<param-value>view-photos</param-value>
</init-param>
<init-param>
<param-name>http-method</param-name>
<param-value>get post</param-value>
</init-param>
</filter>

Declaring resource-to-scope Filter Mapping


In this code snippet you can observe how the PhotoAlbumServlet is mapped to the previously specified OAuth
scope filter:
<filter-mapping>
<filter-name>OAuthViewPhotosScopeFilter</filter-name>
<servlet-name>PhotoAlbumServlet</servlet-name>
</filter-mapping>
If you would like to use URL pattern instead, simply specify the pattern that should apply here:
<filter-mapping>
<filter-name>OAuthViewPhotosScopeFilter</filter-name>
<url-pattern>/photos/*.jpg</url-pattern>
</filter-mapping>

1230

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

In the second case, all files with the *.jpg extension that are served from the /photos directory will be protected
by the OAuth filter.
For more information regarding possible mappings, see the filter-mapping element specification.

Protecting Resources Programmatically


You can use the OAuth 2.0 API in SAP HANA Cloud Platform to manage OAuth resource protection
programmatically. Use the isAuthorized methods of OAuthAuthorization to check whether the HTTP request is
authorized to access the protected resource.

Example
The following example illustrates checking whether the current HTTP request is authorized with the given
scope ("scope1") using the isAuthorized method of OAuthAuthorization.
OAuthAuthorization authAuthorization =
OAuthAuthorization.getOAuthAuthorizationService();
if(!authAuthorization.isAuthorized(request, "scope1")){
response.sendError("403", "You have no permissions to execute this call");
}

Creating Protected Resource Requests


When a resource protected by OAuth is requested, your application must pass the access token using the HTTP
"Authorization" request header field. The value of this header must be the token type and access token value. The
currently supported token type is "bearer".

Possible Responses to Requests for Protected Resources


When the protected resource access check is performed the filter calls the API and the API calls the authorization
server to check the validity of the access token and retrieve tokens scopes.
In the table below the result handling between the authorization server and resource server, resource server and
the API, and resource server and filter is presented.
Table 373: Responses to requests for protected resources
Authorization server to resource
server

Resource server to the API

Resource server to the filter

Code

Return value / Ex
ception

Code

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Description

Description

Description

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1231

Authorization server to resource


server

Resource server to the API

200

True

access_token
is valid

Resource server to the filter

attribute

Access is allowed.

"user_id" in the

attribute

request

"client_id" in
the request

attribute
"client_id" in

attribute

the request

"user_id" in the
request
If user-

principal=tru
e ->
request.getUs
erPrincipal()
. getName()
returns user_id
200

access_token

False

attribute

403

"reason" in the

is valid

Access is forbid
den

request describing
the reason for the
result

reason =
"access_forbi
dden"
400

access_token

False

parameter is null,

Attribute
"reason" in the

401

request describing
the reason for the
result

empty string, miss


ing or it is given
more than once

reason =
"missing_acce
ss_token

401

access_token

False

does not exist

Attribute
"reason" in the

401

request describing
the reason for the
result

reason =
"missing_acce
ss_token

1232

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Authorization server to resource


server

Resource server to the API

401

False

access_token
has expired

Resource server to the filter

Attribute
"reason" in the

401

request describing
the reason for the
result

reason =
"missing_acce
ss_token
401

access_token

False

is not issued for

Attribute
"reason" in the

401

request describing
the reason for the
result

the current sub


scription

reason =
"missing_acce
ss_token
500

Unexpected error

OAuthSystemEx Inherit message

(no connection to

ception

the database)

(extends

500

from the original


exception

Exception)
OAuthSystemEx HTTP request to
ception
(extends

the authorization
server fails

Exception)
OAuthSystemEx OAuth destination
ception
(extends

Exception)

is not found or
cant get destina
tion HTTP client

Next Steps
1. You can now deploy the application on SAP HANA Cloud Platform. For more information, see Deploying and
Updating Applications [page 973]
2. After you deploy, you need to configure clients and scopes for the application. For more information, see
Configuring OAuth 2.0 [page 1310].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1233

1.8.3.1.7.1 Enabling OAuth 2.0 Client Credentials Grant


SAP HANA Cloud Platform supports the client credentials grant flow from the OAuth 2.0 specfication. This flow
enables grant of an OAuth access token based on the client credentials only, without user interaction. You can use
this flow for enabling system-to-system communication (with a service user), for example, in device
communication in an Internet of things scenario.

Context
The current procedure is for application developers that need their SAP HANA Cloud Platform applications to be
enabled for OAuth 2.0 client credentials grant.

Procedure
1. Register a new OAuth client of type Confidential. See Registering an OAuth Client [page 1310].
2. Using that client, you can get an access token using a REST call to the endpoints shown in
Security

OAuth

cockpit

Branding .

Create a REST call containing grant_type: client credentials, client ID and password.
See the OAuth 2.0 client credentials grant specification

The HTTP response contains the access token.


3. In the SAP HANA Cloud Platform application:
Protect your application declaratively with the OAuth login method in the web.xml. See Protecting
Applications with OAuth 2.0 [page 1227].
Use the getRemoteUser() method of the HTTP request
(javax.servlet.http.HttpServletRequest) to get the client ID.
The getRemoteUser() method returns the client ID prefixed by oauth_client_ as follows:
oauth_client_<client ID>

Tip
You can use the client ID returned as remote user to assign Java EE roles to clients, and use them for
role-based authorizations. See:
Managing Roles [page 1282]
Enforcing Authorizations [page 1220]
Do not use the OAuth protection filter.
Deprecated: Protecting the SAP HANA Cloud Platform Using the OAuth Filter

Caution
The procedure that follows is being deprecated.

1234

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Alternatively to using the OAuth login method, you can use the OAuth filter without init parameters to protect
the application resources. For example:

Source Code
<filter>
<display-name>OAuth scope definition for viewing a photo album</displayname>
<filter-name>OAuthViewPhotosScopeFilter</filter-name>
<filter-class>
com.sap.cloud.security.oauth2.OAuthAuthorizationFilter
</filter-class>
</filter>
To get the client ID, use the client_id request attribute. For example:

Source Code
request.getAttribute("client_id")
In this deprecated case, do not use a login method in the web.xml.

1.8.3.1.8

Protecting from Cross-Site Request Forgery

What is Cross-Site Request Forgery (CSRF)


Cross-site request forgery (CSRF or XSRF) is also known as one-click attack or session riding. The key step of the
attack is that a malicious user tricks the victims browser into executing an HTTP request on behalf of the valid
user. As a result, a security sensitive action is performed on the server side. If the victim has already logged in the
attacked site, the browser has valid session cookies and sends them automatically with subsequent requests. The
server trusts these requests based on the valid cookies sent by the browser and confirms that the action has been
initiated by the victim.
The predictability of the HTTP request is a prerequisite for the attacker to be able to insert a request in advance in
order to make the browser execute it. Therefore, the common prevention to this attack is to embed a secret
unpredictable token into the request, unique for each session or request.
The diagram that follows illustrates the CSRF process.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1235

How to Protect from CSRF


SAP HANA Cloud Platform provides two CSRF protection approaches:
Table 374:
CSRF Protection Mechanism Description
URL encoding approach

1236

When to Use

How to Use

This is the most common


See Using the Apache Tomcat
CSRF protection. Use it for
provided by
tion Filter
CSRF Prevention Filter [page
protecting resources that are
Apache Tomcat 7. The pre
1237]
supposed to be accessed via
vention mechanism is based
some sort of navigation. For
on a token (a nonce value)
example, if there is a refer
generated on each request
and stored in the session. The ence to them in an entry point
page (included in links/post
token is used to encode all
URLs on the entry point sites. forms, and so on).
Upon request to a protected
URL, the existence and value
of the token is checked. The
request is allowed to proceed
only if the nonce from the to
ken equals the one stored in
the session. The prevention
mechanism is applied for all
URLs mapped to the filter ex
cept for specially defined en
try points.
Based on the CSRF Preven

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

CSRF Protection Mechanism Description

When to Use

How to Use

Custom header approach

Based on a secret token (a


nonce value) generated on
server side and stored in the
session, but unlike the first
approach, here the token is
transported as a custom
header of the HTTP requests.

Use it when URL encoding is


See Using Custom Header
not suitable. For example,
Protection [page 1239]
when protecting resources
that are requested only as
REST APIs (one time requests
that should be served inde
pendently from previous re
quests and are not included in
links and HTML forms). The
same approach is imple
mented in other SAP web ap
plication servers like AS ABAP
and HANA XS, and is sup
ported by SAP UI5. Common
scenarios that can benefit
from this approach are those
using ODATA services, REST,
AJAX, etc.

Custom CSRF filtering imple


mentation

If you cannot use URL encod

Use it when implementing sin Enabling Logout [page 1224]

ing or custom header protec

gle logout (SLO) for SAP

tion, you can implement your

HANA Cloud Platform appli

custom CSRF filtering

cations. Due to redirects to


the SAML 2.0 identity pro
vider, you cannot use the outof-the-box approaches listed
here (custom header protec
tion or URL encoding.

Note
These approaches cannot be applied together to protect one and the same web resource.

1.8.3.1.8.1 Using the Apache Tomcat CSRF Prevention Filter


Prerequisites
You have created a working Web application and have enforced authentication for it. See Enabling Authentication
[page 1213]
For the purposes of this tutorial, an example application consisting of the following URLs will be used:
/home - displays home page, and has links to /doActionA and /doActionB
/doActionA - executes a security sensitive action A, and also has a link to /doActionB
/doActionB - executes a security sensitive action B

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1237

Adding CSRF Prevention to a Web Application


1. Choose entry point URLs
Entry points are URLs used as a starting point for the navigation across the application. They are not protected
against CSRF as requests to them will not be tested for the presence of a valid nonce. Entry points should meet
the following criteria:
Entry points are protected resources .
Entry points should not trigger any security sensitive actions.
Using the full set of entry points as navigation starting points, it should be possible to reach any link in the
application that is being protected against CSRF.
Considering the example application, /doActionA and /doActionB are not plausible for entry points since they
are state changing URLs. They should be protected against CSRF. Following the rules above, you could easily
conclude that /home is best suited to be the entry point.
2. Define the filter in the application's web.xml
The CSRF Prevention Filter should be defined in the web.xml configuration file. Important init parameters are
entryPoints and nonceCacheSize. The first parameter's value is a comma separated list of the entry points,
identified in the previous step. In this case /home.
The second parameter, nonceCacheSize, should be used in case of parallel requests that might cause a new
nonce to be generated, before the validation of an encoded URL. The nonceCacheSize parameters defines the
number of previous values stored. The default number is 5.
The definition below will protect all URLs except for the entry point /home.
<filter>
<filter-name>CsrfFilter</filter-name>
<filter-class>org.apache.catalina.filters.CsrfPreventionFilter</filter-class>
<init-param>
<param-name>entryPoints</param-name>
<param-value>/home</param-value>
</init-param>
</filter>
3. Define the filter mapping in the web.xml
The general recommendation is to enable the filter for all URLs using the pattern /*:
<filter-mapping>
<filter-name>CsrfFilter</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
4. Encode all URL links
In the example application the URLs that should be encoded are /protected/doActionA and /protected/
doActionB in /protected/home, and the /protected/doActionB URL in /protected/doActionA. To
encode the URLs use HttpServletResponse#encodeRedirectURL(String) or
HttpServletResponse#encodeURL(String).
Here is the source for the home.jsp, mapped to /protected/home.
<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
pageEncoding="ISO-8859-1"%>

1238

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://


www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Home</title>
</head>
<body>
This is a home page and I am an entry point.
<br/>
<%
String urlActionA = "doActionA";
String urlActionAEncoded = response.encodeURL(urlActionA);
%>
<form action="<%=urlActionAEncoded %>" method="POST">
<input type="text" name="arg" value="A"/>
<input type="submit" value="Do Action A"/>
</form>
<br/>
<%
// Encode URL for action B
String urlActionB = "doActionB";
String urlActionBEncoded = response.encodeURL(urlActionB);
%>
<form action="<%=urlActionBEncoded %>" method="POST">
<input type="text" name="arg" value="B"/>
<input type="submit" value="Do Action B"/>
</form>
<br/>
</body>
</html>
5. Adding new URLs to a CSRF protected application
In case a new URL needs to be added to the application later, for example, /newlink, then you should evaluate its
need of CSRF protection. For example, if it executes a state changing action, it certainly should be protected.
Depending on the case there are two possibilities:
No CSRF protection is needed
The URL should be defined as entry point. This is done by editing the web.xml and adding the new URL to the
value of the init parameter entryPoints of the CsrfPreventionFilter from step 2. The new value should
be separated with a comma.
CSRF protection is needed.
The /newlink URL should be encoded in all pages that use it as described in step 4.
All CSRF protected links that are used in the new page should be encoded, as described in step 4.

1.8.3.1.8.2 Using Custom Header Protection

Context
Custom header protection is one of the possible approaches for CSRF protection. It is based on adding a servlet
filter that inspects state modifying requests for the presence of valid CSRF token. The CSRF token is transferred
as a custom header and is valid during the user session. This kind of protection specifically addresses the

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1239

protection of REST APIs, which are normally not accessed from entry point pages. Note that the CSRF protection
is performed only for modifying HTTP requests (different from GET|HEAD or OPTIONS).
In a nutshell, the REST CSRF protection mechanism consists of the following communication steps:
1. The REST CLIENT obtains a valid CSRF token with an initial non-modifying "Fetch" request to the application.
2. The SERVER responds with the valid CSRF token mapped to the current user session.
3. The REST CLIENT includes the valid CSRF token in the subsequent modifying REST requests in the frame of
the same user session.
4. The SERVER rejects all modifying requests to protected resources that do not contain the valid CSRF token.
Custom header CSRF protection mechanism requires adoption both in the client (JavaScript) and server (REST)
parts of the Web applications.
To better illustrate the mechanism well use an example web application exposing the following REST APIs. Well
use the same example application throughout the document.
Table 375:
Number

Exposed with HTTP


methods

REST API

Description

Type

GET

/services/list

Prints customers list in


the output.

non-modifying

POST

/services/customers/
removeCustomer

Removes the first item


from the customers
list.

modifying

POST

/services/customers/
addCustomer

Adds a customer to the


customers list.

modifying

1. In the REST Service


Prerequisites
You have created a working Web application and have enforced authentication for it, as described in Enabling
Authentication [page 1213]. All CSRF protected resources should be protected with an authentication mechanism.

Procedure
In the application's web.xml, protect all REST APIs using the out-of-the-box CSRF filter available with the SAP
HANA Cloud Platform SDK.

Note
You must have at least one non-modifying REST operation listed.
Identify all web application resources that have to be CSRF protected and map them to
org.apache.catalina.filters.RestCsrfPreventionFilter (this class represents the out-of-the-box

1240

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

CSRF filter available with the SAP HANA Cloud Platform SDK, so you do not need to instantiate/implement it) in
the web.xml.

Note
If you are using an older version of the SAP HANA Cloud Platform rutime for Java, use the
com.sap.core.js.csrf.RestCsrfPreventionFilter class instead. It delivers the same implementation
as the other one. Namely, use that class with the following runtime versions:
Java Web 1.x lower than 1.98.22
Java EE Web Profile lower than 2.80.14
Java Web Tomcat 7 lower than 2.45.16
As a result, all modifying HTTP requests matching the given url-pattern would be CSRF validated, i.e. checked
for the presence of the valid CSRF token.
Applications should expose at least one non-modifying REST operation to enable CSRF token fetch mechanism. In
order to obtain the valid CSRF token, the clients need to make an initial fetch requests. That is why the nonmodifying REST API is necessary. Requirements for the non-modifying REST API:
Any GET/HEAD/OPTIONS requests to the URL shall not cause state modification.
The URL should be mapped to the RestCsrfPreventionFilter
The URL should be protected with authentication mechanism.

Example
The following example illustrates mapping a set of modifying REST APIs and one non-modifying REST API to
the CSRF protection filter in the applications web.xml deployment descriptor:
<filter>
<filter-name>RestCSRF</filter-name>
<filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filterclass>
</filter>
<filter-mapping>
<filter-name>RestCSRF</filter-name>
<! modifying REST APIs-->
<url-pattern>/services/customers/removeCustomer</url-pattern>
<url-pattern>/services/customers/addCustomer</url-pattern>
<url-pattern>/services/customers/initCustomers</url-pattern>
<! non-modifying REST API-->
<url-pattern>/services/customers/list</url-pattern>
</filter-mapping>

2. In REST Clients
Procedure
1. Make a fetch request.
As a first step, the REST client should obtain the valid CSRF token for the current session. For this it makes a
non-modifying request and includes a custom header "X-CSRF-Token: Fetch". The returned [sessionid

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1241

csrf token] pair should be cached and used in subsequent REST requests by the client. Another option
is to send Fetch request before every REST request and thus to use the [sessionid csrf token] pair
only once.
Example HTTP Request-Response flow:
Client Request:
GET /restDemo/services/customers/list HTTP/1.1
X-CSRF-Token: Fetch
Authorization: Basic dG9tY2F0OnRvbWNhdA==
Host: localhost:8080
Server Response:
HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=4BA3D75B73B8C4591F1D915BA9C2B660; Path=/restDemo/;
HttpOnly
X-CSRF-Token: 5A44B387B75E54417F6C64FF3D485141
..
2. Use the cached [sessionid csrf token] pair for subsequent REST requests.
Subsequent modifying REST requests to the same application should include the valid jsessionid cookie and
the valid X-CSRF-Token header.
Example HTTP Request -Response flow:
Client Request:
POST /restDemo/services/customers/removeCustomer HTTP/1.1
Cookie: JSESSIONID=4BA3D75B73B8C4591F1D915BA9C2B660
X-CSRF-Token: 5A44B387B75E54417F6C64FF3D485141
Authorization: Basic dG9tY2F0OnRvbWNhdA==
Host: localhost:8080
Server Response:
HTTP/1.1 200 OK
..
3. Handling error server responses
The client should be prepared for the following server response:
403 Forbidden
X-CSRF-Token: Required
It may occur in one of these cases:
Invalid or missing CSRF token in the request.
Expired session - after session expiration the [sessionid csrf token] pair is no longer valid and it
should be reinitialized by the client.
There are cases when the sessionid is changed by the server and the client should take into account such
changes.

Exceptional Cases
Context
In small number of use cases the client is not able to insert custom headers in its calls to a REST API. For example
file uploads via POST HTML FORM consuming a REST API. Only for such use-cases there is an additional

1242

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

capability to configure REST APIs for which the valid CSRF token will be accepted as request parameter (not only
header). If there is a X-CSRF-Token header, it will be taken with preference over any parameter with the same
name in the request.

Tip
For security reasons we strongly recommend the following:
Use this approach only when the header approach cannot be applied.
Use only hidden post parameter with name X-CSRF-Token, and not query parameters.
Example configuration in the web.xml deployment descriptor:
<filter>
<filter-name>CSRF</filter-name>
<filter-class>org.apache.catalina.filters.RestCsrfPreventionFilter</filterclass>
<init-param>
<param-name>pathsAcceptingParams</param-name>
<param-value>/services/customers/acceptedPath1.jsp,/services/customers/
acceptedPath2.jsp
</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>CSRF</filter-name>
<url-pattern>/services/customers/*</url-pattern>
</filter-mapping>

1.8.3.1.9

Protecting from Cross-Site Scripting (XSS)

This document describes how to protect SAP HANA Cloud Platform applications from XSS attacks.

What is Cross-Site Scripting (XSS)


Cross-site Scripting (XSS) is the name of a class of security vulnerabilities that can occur in Web applications. It
summarizes all vulnerabilities that allow an attacker to inject HTML Markup and/or JavaScript into the affected
Web application's front-end.
XSS can occur whenever the application dynamically creates its HTML/JavaScript/CSS content, which is passed
to the user's Web browser, and attacker-controlled values are used in this process. In case these values are
included into the generated HTML/JavaScript/CSS without proper validation and encoding, the attacker is able to
include arbitrary HTML/JavaScript/CSS into the application's frontend, which in turn is rendered by the victim's
Web browser and, thus, interpreted in the victim's current authentication context.

Protecting Applications Using SAPUI5


For SAPUI5 applications, XSS vulnerabilities can exist at different levels:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1243

Within the HTML page or custom data transports sent to the browser by the server
Within the JavaScript Code of the application processing server responses
Within the HTML renderers of SAPUI5 controls
For more information about the security measures implemented by SAPUI5, see Securing SAPUI5 Applications.

Protecting Applications Using the XSS Output Encoding Library

Note
Using the XSS output encoding library is given as an option that you can use for your applications. You can
successfully use your custom or third-party XSS protection libraries that you have available.
SAP HANA Cloud Platform provides an output encoding library that helps protecting from XSS vulnerabilities. It is
a central library that implements several encoding methods for the different contexts.
In the application node, first retrieve the com.sap.security.core.server.csi.IXSSEncoder interface using
com.sap.security.core.server.csi.XSSEncoder.getInstance().
The interface provides methods for retrieving parameters or attributes, and for encoding and decoding data.
It also has various methods for different data types that should be encoded:
Data Type

Code Sample for Encoding

HTML / XML:

out = XSSEncoder.encodeHTML( in ); /
XSSEncoder.encodeXML( val );

JavaScript:

out = XSSEncoder.encodeJavaScript( val );

URL:

out = XSSEncoder.encodeURL( val );

CSS:

out = XSSEncoder.encodeCSS( val );

Installing the XSS Output Encoding Library


o use XSS output encoding API, you need to add it as library to the Dynamic Web Project. This is done with the
following steps:
1. In the Project Explorer view, select the persistence-with-jpa/WebContent/WEB-INF/lib node.
2. From the context menu, choose

Import

General

File System

and choose Next.

3. Browse to your local directory where you downloaded and unpacked the SAP HANA Cloud Platform SDK,
select the repository/plugins directory (/impl directory if you are using the Tomcat 7 runtime), and choose
OK.
4. Select the archive com.sap.security.core.server.csi_1.x.y.jar and choose Finish.

1244

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Using the XSS Output Encoding Library


In the following example, we demonstrate the use of the XSS Output Encoding API. The example has one HTML
form that retrieves user input, which can contain malicious code:
<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://
www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Login Page</title>
<link rel="stylesheet" href="resources/login.css" />
<meta http-equiv="cache-control" content="no-cache"/>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
</head>
<body>
<div class="fields">
<form method="post" action="checkedInput.jsp">
<span class="header">Enter your names:</span><br/>
<table border="0">
<tr>
<td>First name: </td>
<td><input name="firstname"/></td>
</tr>
<tr>
<td>Last name: </td>
<td><input name="lastname"/></td>
</tr>
<tr>
<td></td>
<td><input type="submit" value="Submit"/></td>
</tr>
</table>
</form>
</div>
</body>
</html>
his form sends parameters to a second JSP:
<%@ page language="java" contentType="text/html; charset=UTF-8"
pageEncoding="UTF-8"%>
<%@ page import="com.sap.security.core.server.csi.IXSSEncoder" %>
<%@ page import="com.sap.security.core.server.csi.XSSEncoder" %>
<%@ page import="java.io.UnsupportedEncodingException" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://
www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Welcome</title>
<link rel="stylesheet" href="resources/login.css" />
<meta http-equiv="cache-control" content="no-cache"/> <meta http-equiv="ContentType" content="text/html; charset=UTF-8"/>
</head>
<body>
<div class="fields">
<form>
<%
String encodedName = validateInput(request.getParameter("firstname"));
out.println("<br>Hello, " + encodedName);
String lastName = request.getParameter("lastname");
out.println("<br> Hacked: " + lastName);
%>
</form>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1245

</div>
<%!
private String validateInput(String firstName) {
String encodedInput = null;
IXSSEncoder xssEncoder = XSSEncoder.getInstance();
try {
encodedInput = xssEncoder.encodeHTML(firstName).toString();
} catch (UnsupportedEncodingException e) {
e.printStackTrace();
} return encodedInput;
}
%>
</body>
</html>
Even though the attacker might attempt to inject malicious code in both parameters - firstname and lastname, the
firstname is protected, since it uses the output encoding library to neutralize all special symbols. However, the
attack attempt will be successful for the lastname parameter since it is printed directly to the output. This is
unsafe behavior and should be avoided.

1.8.3.1.10 Cryptography
The Keystore Service provides a repository for cryptographic keys and certificates to the applications hosted on
SAP HANA Cloud Platform.
Keys and Certificates [page 1246]
If you want to use cryptography with unlimited strength in an SAP HANA Cloud Platform application, you need to
enable it via installing the necessary Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy
Files on SAP JVM.
Using Strong Encryption in Applications [page 1266]

1.8.3.1.10.1 Keys and Certificates


Overview
The Keystore Service provides a repository for cryptographic keys and certificates to the applications hosted on
SAP HANA Cloud Platform. By using the Keystore Service, the applications could easily retrieve keystores and use
them in various cryptographic operations such as signing and verifying of digital signatures, encrypting and
decrypting messages, and performing SSL communication.

1246

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Features
The SAP HANA Keystore Service stores and provides keystores encoded in the following formats:
Java Keystore (JKS)
It supports password-based integrity validation for its content. Key entries are protected with passwordbased encryption. Password has to be specified in order to retrieve a key entry.
Extended Java Keystore (JCEKS)
It provides the same functionality as the JKS format with stronger protection for private keys.
PKCS #12 file (P12)
This format supports password-based integrity validation for its content. Key entries are protected with
password-based symmetric encryption. A password has to be specified in order to retrieve a key entry.
Privacy Enhanced Mail Certificate (PEM)
It does not support integrity validation. Key entries are not protected with password.

Configuring Keystores
Local Server Configuration
You can manage the keystores directly on the file system of the local server. Place the keystore files
with .jks, .pem, .jceks, or .p12 extension in the following folder: <local server>/config_master/
com.sap.cloud.crypto.keystore.
Cloud Configuration
You can manage the keystores via the SAP HANA Cloud Platform console client. For more information, see
Keystore Console Commands [page 1248].

Keystore Search Order


The keystore service works with keystores available on the following levels:
Subscription level
Keystores available for a certain application provided by another account.
Application level
Keystores available for a certain application in a particular consumer account.
Account level
Keystores available for all applications in a particular consumer account.
When searching for a keystore with a certain name, the keystore service will search on the different levels in
following order:

Subscription level

Application level

Account level .

Once a keystore with the specified name has been found at a certain location, further locations will no more be
searched for.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1247

Consuming the Keystore Service


To consume the Keystore Service, you need to add the following reference to your web.xml file:
<resource-ref>
<res-ref-name>KeyStoreService</res-ref-name>
<res-type>com.sap.cloud.crypto.keystore.api.KeyStoreService</res-type>
</resource-ref>
Then, in the code you can look up Keystore Service API via JNDI:
import com.sap.cloud.crypto.keystore.api.KeyStoreService;
...
KeyStoreService keystoreService = (KeyStoreService) new
InitialContext().lookup("java:comp/env/KeyStoreService");
A keystore can be obtained by using the getKeyStore() method.
KeyStore keyStore = keystoreService.getKeyStore(keystoreName, keystorePassword);
For more information, see Tutorial: Using the Keystore Service for Client Side HTTPS Connections.

Related Information
Keystore Console Commands [page 1248]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]

1.8.3.1.10.1.1 Keystore Console Commands


The keystore console commands are called from the SAP HANA Cloud Console Platform Client and allow users to
list, upload, download, and delete keystores. To be able to use them, the user must have administrative rights for
that account. The console supports the following keystore commands: list-keystores, upload-keystore,
download-keystore, and delete-keystore.

Related Information
Keys and Certificates [page 1246]
list-keystores [page 199]
upload-keystore [page 259]
download-keystore [page 154]
delete-keystore [page 139]

1248

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.1.10.1.2 Trusted Certificate Authorities for Outbound SSL


Connections
SAP JVM, used by SAP HANA Cloud Platform, trusts the below-listed certificate authorities (CAs) by default. This
means that the external HTTPS services which use X.509 server certificates (which are issued by those CAs), are
trusted by default on SAP HANA Cloud Platform and no trust needs to be configured manually.
For SSL connections to services which use different certificate issuers, you need to configure trust to use the
keystore service of the platform. For more information, see Tutorial: Using the Keystore Service for Client Side
HTTPS Connections [page 1251].

Properties
The following CAs are available in SAP JVM 7.
Table 376:
Certificate Alias

Certificate Name

Certificate SHA1

baltimorecybertrustca

Baltimore CyberTrust Root

D4:DE:20:D0:5E:66:FC:53:FE:1A:
50:88:2C:78:DB:28:52:CA:E4:74

digicerthighassuranceevroot
ca

DigiCert High Assurance EV Root CA

5F:B7:EE:06:33:E2:59:DB:AD:0C:4C:
9A:E6:D3:8F:1A:61:C7:DC:25

entrust2048

Entrust.net Certification Authority


(2048)

50:30:06:09:1D:97:D4:F5:AE:
39:F7:CB:E7:92:7D:7D:65:2D:34:31

entrustpersonalserverca

Entrust.net Client Certification Authority

DA:79:C1:71:11:50:C2:34:39:AA:2B:0B:
0C:62:FD:55:B2:F9:F5:80

entrustserverca

Entrust.net Secure Server Certification


Authority

99:A6:9B:E6:1A:FE:88:6B:4D:2B:
82:00:7C:B8:54:FC:31:7E:15:39

equifax_secure_certificate_
authority

Equifax Secure Certificate Authority

D2:32:09:AD:23:D3:14:23:21:74:E4:0D:
7F:9D:62:13:97:86:63:3A

gte_global_root

GTE CyberTrust Global Root

97:81:79:50:D8:1C:96:70:CC:
34:D8:09:CF:79:44:31:36:7E:F4:74

sappassportca

SAP Passport CA

8D:71:8C:B5:F4:21:9D:5D:39:0C:
79:04:8A:EA:21:85:54:37:F4:57

tc_trust_center_ssl_ca_1

TC TrustCenter SSL CA I

19:84:90:0F:
64:21:0B:CD:C2:64:D3:77:9C:B8:E6:4E:
CA:07:B2:AB

tc_trust_class_2_ii

TC TrustCenter Class 2 CA II

AE:50:83:ED:7C:F4:5C:BC:8F:
61:C6:21:FE:68:5D:79:42:21:15:6E

tc_trust_class_2_l1_ca_xi

TC TrustCenter Class 2 L1 CA XI

4C:37:58:79:7A:AE:
43:74:25:FC:D8:D9:CA:7D:
1A:B4:64:0D:CE:37

tctrustcenterclass1

TC TrustCenter Class 1 CA

72:0F:C1:5D:DC:27:D4:56:D0:98:FA:BF:
3C:DD:78:D3:1E:F5:A8:DA

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1249

Certificate Alias

Certificate Name

Certificate SHA1

tctrustcenterclass2

TC TrustCenter Class 2 CA

83:8E:30:F7:7F:DD:14:AA:
38:5E:D1:45:00:9C:0E:22:36:49:4F:AA

telekomonlinepass

Deutsche Telekom Root CA 1

9E:6C:EB:
17:91:85:A2:9E:C6:06:0C:A5:3E:
19:74:AF:94:AF:59:D4

thawteserverbasic

Thawte Server CA

23:E5:94:94:51:95:F2:41:48:03:B4:D5:6
4:D2:A3:A3:F5:D8:8B:8C

verisignclass1_g1

VeriSign Class 1 Public Primary Certifica 90:AE:A2:69:85:FF:14:80:4C:


tion Authority
43:49:52:EC:E9:60:84:77:AF:55:6F

verisignclass1_g2

VeriSign Class 1 Public Primary Certifica 27:3E:E1:24:57:FD:C4:F9:0C:55:E8:2B:


tion Authority - G2
56:16:7F:62:F5:32:E5:47

verisignclass1_g3

VeriSign Class 1 Public Primary Certifica 20:42:85:DC:F7:EB:76:41:95:57:8E:


tion Authority - G3
13:6B:D4:B7:D1:E9:8E:46:A5

verisignclass2_g1

VeriSign Class 2 Public Primary Certifi


cation Authority

67:82:AA:E0:ED:EE:E2:1A:
58:39:D3:C0:CD:14:68:0A:4F:60:14:2A

verisignclass2_g2

VeriSign Class 2 Public Primary Certifi


cation Authority - G2

B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:
95:B6:CC:A0:08:1B:67:EC:9D

verisignclass2_g3

VeriSign Class 2 Public Primary Certifi


cation Authority - G3

61:EF:43:D7:7F:CA:D4:61:51:BC:
98:E0:C3:59:12:AF:9F:EB:63:11

verisignclass3_g1

VeriSign Class 3 Public Primary Certifi


cation Authority

74:2C:31:92:E6:07:E4:24:EB:
45:49:54:2B:E1:BB:C5:3E:61:74:E2

verisignclass3_g2

VeriSign Class 3 Public Primary Certifi


cation Authority - G2

85:37:1C:A6:E5:50:14:3D:CE:
28:03:47:1B:DE:3A:09:E8:F8:77:0F

verisignclass3_g3

VeriSign Class 3 Public Primary Certifi


cation Authority - G3

13:2D:0D:45:53:4B:
69:97:CD:B2:D5:C3:39:E2:55:76:60:9B:
5C:C6

verisignclass4_g2

VeriSign Class 4 Public Primary Certifi


cation Authority - G2

0B:77:BE:BB:CB:7A:A2:47:05:DE:CC:
0F:BD:6A:02:FC:7A:BD:9B:52

verisignclass4_g3

VeriSign Class 4 Public Primary Certifi


cation Authority - G3

C8:EC:8C:87:92:69:CB:4B:AB:39:E9:8D:
7E:57:67:F3:14:95:73:9D

workplaceca

mySAP.com Workplace CA (dsa)

A1:7D:8B:51:8A:8F:BB:DE:A5:00:C8:1E:
96:12:26:16:32:4A:34:C0

thawteprimaryrootcag2

Thawte Primary Root CA - G2

AA:DB:BC:22:23:8F:C4:01:A1:27:BB:
38:DD:F4:1D:DB:08:9E:F0:12

verisignclass3_g4

VeriSign Class 3 Public Primary Certifi


cation Authority - G4

22:D5:D8:DF:8F:
02:31:D1:8D:F7:9D:B7:CF:8A:2D:
64:C9:3F:6C:3A

Related Information
Server Certificate Authentication [page 323]
Using Certificates Signed by Trusted Certificate Authority [page 454]

1250

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.1.10.1.3 Tutorial: Using the Keystore Service for Client


Side HTTPS Connections
Prerequisites
You have downloaded and configured the SAP Eclipse platform. For more information, see Installing Java
Tools for Eclipse and SDK [page 33].
You have created a HelloWorld Web application as described in the Creating a HelloWorld Application tutorial.
For more information, see Creating a HelloWorld Application [page 47].
You have an HTTPS server hosting a resource which you would like to access in your application.
You have prepared the required key material as .jks files in the local file system.

Note
File client.jks contains a client identity key pair trusted by the HTTPS server, and cacerts.jks
contains all issuer certificates for the HTTPS server. The files are created with the keytool from the
standard JDK distribution. For more information, see Key and Certificate Management Tool .

Context
This tutorial describes how to extend the HelloWorld Web application to use SAP HANA Cloud Platform Keystore
Service. It tells you how to make an SSL connection to an external HTTPS server by using the JDK and Apache
HTTP Client. For more information about the HelloWorld Web application, see Creating a HelloWorld Application
[page 47].
You test and run the application on your local server and on SAP HANA Cloud Platform.

Using javax.net.ssl Framework


Procedure
1. Declare a Keystore Service Resource Reference.
To enable the look-up of the Keystore Service through JNDI, you need to add a resource reference entry to
the web.xml descriptor.
a. In the Project Explorer view, select the HelloWorld/WebContent/WEB-INF node.
b. Open the web.xml file in the text editor and insert the following content:
<resource-ref>
<res-ref-name>KeyStoreService</res-ref-name>
<res-type>com.sap.cloud.crypto.keystore.api.KeyStoreService</res-type>
</resource-ref>

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1251

c. Save the file.


2. Create a new Servlet
a. To add a servlet to the HelloWorld project, select the HelloWorld node in the Project Explorer view.
b. From the Eclipse main menu, choose

File

New

Servlet .

c. Enter the Java package com.sap.cloud.sample.keystoreservice and the class name SSLExampleServlet.
d. Choose the Finish button to generate the servlet.
e. Replace the entire servlet class with the code below.
package com.sap.cloud.sample.keystoreservice;
import java.io.BufferedReader;
import java.io.BufferedWriter;
import java.io.IOException;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.io.PrintWriter;
import java.security.KeyStore;
import javax.naming.Context;
import javax.naming.InitialContext;
import javax.naming.NamingException;
import javax.net.ssl.KeyManager;
import javax.net.ssl.KeyManagerFactory;
import javax.net.ssl.SSLContext;
import javax.net.ssl.SSLSocket;
import javax.net.ssl.SSLSocketFactory;
import javax.net.ssl.TrustManager;
import javax.net.ssl.TrustManagerFactory;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.sap.cloud.crypto.keystore.api.KeyStoreService;
public class SSLExampleServlet extends HttpServlet {
private static final long serialVersionUID = 1L;
/**
* @see HttpServlet#doGet(HttpServletRequest request, HttpServletResponse
response)
*/
protected void doGet(HttpServletRequest request, HttpServletResponse
response) throws ServletException, IOException {
// get Keystore Service
KeyStoreService keystoreService;
try {
Context context = new InitialContext();
keystoreService = (KeyStoreService) context.lookup("java:comp/env/
KeyStoreService");
} catch (NamingException e) {
response.getWriter().println("Error:<br><pre>");
e.printStackTrace(response.getWriter());
response.getWriter().println("</pre>");
throw new ServletException(e);
}
String host = request.getParameter("host");
if (host == null || (host = host.trim()).isEmpty()) {
response.getWriter().println("Host is not specified");
return;
}
String port = request.getParameter("port");
if (port == null || (port = port.trim()).isEmpty()) {
port = "443";
}
String path = request.getParameter("path");
if (path == null || (path = path.trim()).isEmpty()) {
path = "/";
}

1252

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

String clientKeystoreName = "client";


String clientKeystorePassword =
request.getParameter("client.keystore.password");
if (clientKeystorePassword == null || (clientKeystorePassword =
clientKeystorePassword.trim()).isEmpty()) {
response.getWriter().println("Password for client keystore is not
specified");
return;
}
String trustedCAKeystoreName = "cacerts";
// get a named keystores with password for integrity check
KeyStore clientKeystore;
try {
clientKeystore = keystoreService.getKeyStore(clientKeystoreName,
clientKeystorePassword.toCharArray());
} catch (Exception e) {
response.getWriter().println("Client keystore is not available: " + e);
return;
}
// get a named keystore without integrity check
KeyStore trustedCAKeystore;
try {
trustedCAKeystore = keystoreService.getKeyStore(trustedCAKeystoreName,
null);
} catch (Exception e) {
response.getWriter().println("Trusted CAs keystore is not available" +
e);
return;
}
callHTTPSServer(response, host, port, path, clientKeystorePassword,
clientKeystore, trustedCAKeystore);
}
private void callHTTPSServer(HttpServletResponse response,
String host,
String port,
String path,
String clientKeystorePassword,
KeyStore clientKeystore,
KeyStore trustedCAKeystore) throws IOException {
try {
KeyManagerFactory kmf =
KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
kmf.init(clientKeystore, clientKeystorePassword.toCharArray());
KeyManager[] keyManagers = kmf.getKeyManagers();
TrustManagerFactory tmf =
TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustedCAKeystore);
TrustManager[] trustManagers = tmf.getTrustManagers();
SSLContext sslContext = SSLContext.getInstance("TLS");
sslContext.init(keyManagers, trustManagers, null);
SSLSocketFactory factory = sslContext.getSocketFactory();
SSLSocket socket = (SSLSocket)factory.createSocket(host,
Integer.parseInt(port));
socket.startHandshake();
PrintWriter out = new PrintWriter(new BufferedWriter(new
OutputStreamWriter(socket.getOutputStream())));
out.println("GET " + path + " HTTP/1.0");
out.println();
out.flush();
if (out.checkError()) {
response.getWriter().println("Error durring request sending");
}
BufferedReader in = new BufferedReader(new
InputStreamReader(socket.getInputStream()));
String inputLine;
while ((inputLine = in.readLine()) != null) {

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1253

}
}

response.getWriter().println(inputLine);
}
in.close();
out.close();
socket.close();
} catch (Exception e) {
response.getWriter().println("Error:<br><pre>");
e.printStackTrace(response.getWriter());
response.getWriter().println("</pre>");
} finally {
response.getWriter();
}

f. Save the Java editor and make sure that the project compiles without errors.
3. Deploy and Test the Web Application
Local Server Configuration of the Keystore
Cloud Configuration of the Keystore

Using Apache HTTP Client


Procedure
1. Add the required .jar files of the Apache HTTP Client (version 4.2 or higher) to the build path of your project.
2. Add the following imports:
import
import
import
import
import
import
import
import

org.apache.http.HttpEntity;
org.apache.http.HttpResponse;
org.apache.http.client.methods.HttpGet;
org.apache.http.conn.scheme.Scheme;
org.apache.http.conn.scheme.SchemeSocketFactory;
org.apache.http.conn.ssl.SSLSocketFactory;
org.apache.http.impl.client.DefaultHttpClient;
org.apache.http.util.EntityUtils;

3. Replace callHTTPSServer() method with the one using Apache HTTP client.
private void callHTTPSServer(HttpServletResponse response,
String host,
String port,
String path,
String clientKeystorePassword,
KeyStore clientKeystore,
KeyStore trustedCAKeystore) throws IOException,
ServletException {
try {
SchemeSocketFactory socketFactory = new SSLSocketFactory(clientKeystore,
clientKeystorePassword, trustedCAKeystore);
Scheme sch = new Scheme("https", Integer.parseInt(port), socketFactory);
DefaultHttpClient httpclient = new DefaultHttpClient();
httpclient.getConnectionManager().getSchemeRegistry().register(sch);
HttpGet httpget = new HttpGet("https://" + host + path);
HttpResponse resp = httpclient.execute(httpget);
HttpEntity entity = resp.getEntity();
BufferedReader in = new BufferedReader(new
InputStreamReader(entity.getContent()));
String inputLine;

1254

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

while ((inputLine = in.readLine()) != null) {


response.getWriter().println(inputLine);
}
EntityUtils.consume(entity);
} catch (Exception e) {
response.getWriter().println("error: " + e);
throw new ServletException(e);
} finally {
response.getWriter().flush();
}

Related Information
Creating a HelloWorld Application [page 47]
Local Server Configuration of the Keystore [page 1255]
Cloud Configuration of the Keystore [page 1255]

1.8.3.1.10.1.3.1 Local Server Configuration of the Keystore


Procedure
1. To deploy your Web application on the local server, follow the steps for deploying a Web application locally as
described in Deploying Locally from Eclipse IDE [page 975].
2. To upload the required keystores, copy the prepared client.jks and cacerts.jks files into <local
server root>\config_master\com.sap.cloud.crypto.keystore subfolder.
3. To test the functionality, open the following URL in your Web browser: http://localhost:<local server
HTTP port>/HelloWorld/SSLExampleServlet?host=<remote HTTPS server host
name>&port=<remote HTTPS server port number>&path=<remote HTTPS server
resource>&client.keystore.password=<client identity keystore password>.

Related Information
Deploying Locally from Eclipse IDE [page 975]

1.8.3.1.10.1.3.2 Cloud Configuration of the Keystore


Procedure
1. To deploy your Web application on the cloud, follow the steps for deploying a Web application to SAP HANA
Cloud Platform as described in Deploying on the Cloud with the Console Client [page 983].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1255

2. To upload the required keystores, execute upload-keystore console command with the prepared .jks files.
For more information, see the Cloud Configuration section in Keys and Certificates [page 1246].

Example
Assuming you have myAccount account, myApplication application, myUser user, and the keystore files in
folder C:\Keystores, you need to execute the following commands in your local <SDK root>\tools
folder:
neo upload-keystore --account myAccount --user myUser --location C:\Keystores
\client.jks --host hana.ondemand.com
neo upload-keystore --account myAccount --user myUser --location C:\Keystores
\cacerts.jks
--host hana.ondemand.com
For more information about the keystore console commands, see Keystore Console Commands [page
1248].
3. To test the functionality, open the application URL shown by SAP HANA Cloud Platform cockpit with the
following options:<SAP HANA Cloud Platform Application URL>/SSLExampleServlet?
host=<remote HTTPS server host name>&port=<remote HTTPS server port
number>&path=<remote HTTPS server resource>& client.keystore.password=<client
identity keystore password>.
For more information, see Starting and Stopping Applications [page 1110].

Related Information
Deploying on the Cloud with the Console Client [page 983]
Keys and Certificates [page 1246]
Keystore Console Commands [page 1248]
Starting and Stopping Applications [page 1110]

1.8.3.1.10.2 Enabling Client Certificate Authentication


You can enable the users for your Web application to authenticate using client certificates. This corresponds to
the CERT and BASICCERT authentication methods supported in Java EE.

Overview
Prerequisites
(For the mapping modes requiring certificate authorities) You have a keystore defined. See Keys and Certificates
[page 1246].

1256

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context
Using information in the client certificate, SAP HANA Cloud Platform will map the certificate to a user name using
the mapping mode you specify.

1. Configure Reverse Proxy to Request a Client Certificate


Context
By default, SAP HANA Cloud Platform supports SSL communication for Web applications through a reverse proxy
that does not request a client certificate. To enable client certificate authentication, you need to configure the
reverse proxy to request a client certificate.
Add cert.hana.ondemand.com as a platform domain. See Platform Domains [page 1196].
For more information about the trusted certificate authorities (CAs) for SAP HANA Cloud Platform, see Trusted
Certificate Authorities for Inbound SSL Connections [page 1262].

2. Protect Application Resources


In your Web application, use declarative or programmatic authentication to protect application resources.
Use one of the following two methods for client certificate authentication:
CERT - Users can authenticate only with client certificate.
BASICCERT - Users can authenticate either with client certificate or with user name and password.
If you use the declarative approach, you need to specify the authentication method in the application web.xml file.
See Using Declarative Authentication in a Web Application [page 1214].
If you use the programmatic approach, specify the authentication method as a parameter for the login context
creation. For more information, see Using Programmatic Authentication in a Web Application [page 1217].

3. Define User Mapping


The user mapping defines how the user name is derived from the received client certificate. You configure user
mapping using Java system properties.
Use the following system properties to define user mapping:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1257

Table 377: System Properties for User Mappings


System Property

Description

com.sap.cloud.crypto.clientcert.mapping_mo (Mandatory) Defines how the received client certificate is in


terpreted.
de
com.sap.cloud.crypto.clientcert.keystore_n Defines the name of the keystore used during the user map
ping process, and it is mandatory for the mapping modes that
ame
use the keystore.

Note
Use a keystore that is available in the Keystore Service.
See Keys and Certificates [page 1246].

Note
Use the keystore name without the keystore file extension
(jks for example).

Note
Depending on the value of the

com.sap.cloud.crypto.clientcert.mapping
_mode property,using the
com.sap.cloud.crypto.clientcert.keystor
e_name property may be mandatory.

For more information how to set the value of the system property, see Configuring VM Arguments [page 1105].
For more information about the particular values you need to set, see the table below.

1258

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 378:
Mapping Mode

Description

How to Set

Example

CN

The user name equals the

Set the

A client certificate with

common name (CN) of the

com.sap.cloud.crypto cn=myuser,ou=security as a

certificates subject.

.clientcert.mapping_ subject is mapped to a


mode property with value CN. myuser user name.
In addition, if you want to ac
cept certificates from trusted
certificate authorities (CAs)
only, set the

com.sap.cloud.crypto
.clientcert.keystore
_name with a value the key
store name containing the
trusted issuers.

Note
The client certificate is not
accepted if its issuer is not
in the keystore or is not in
a chain trusted by this key
store, and then the au
thentication fails. For more
information about the Key
store Service, see Keys
and Certificates [page
1246].
If you want to accept certifi
cates from any issuer, skip
setting the

com.sap.cloud.crypto
.clientcert.keystore
_name property.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1259

Mapping Mode

Description

How to Set

Example

CN@issuer

For this mapping mode, the

To use this mapping mode,

A client certificate with

user name is defined as <CN

you have to set the following

CN=john, C=DE, O=SAP,

of the certificates

system properties:

OU=Development as a subject

subject>@<keystore alias of
the certificates issuer>. Use

com.sap.cloud.cry and CN=SSO CA, O=SAP as


pto.clientcert.ma an issuer is received. The
specified keystore with
pping_mode with a

com.sap.cloud.cry same issuer, CN=SSO CA,


pto.clientcert.ke O=SAP, that has an sso_ca
alias. Then the user name is
ystore_name with a

this mapping mode when you


have certificates with identi
cal CNs.

value CN@Issuer

value the keystore name


containing the trusted is
suers

trusted issuers contains the

defined as john@sso_ca.

The issuer is trusted if it


is in the keystore or is
part of a trusted certifi
cate chain. A certificate
chain is trusted if at least
one of its issuers exists in
the keystore.

Note
The client certificate is not
accepted if its issuer is not
in the keystore or is not in
a chain trusted by this key
store, and then the au
thentication fails. For more
information about setting
the Keystore Service, see
Keys and Certificates
[page 1246].

1260

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Mapping Mode

Description

How to Set

Example

wholeCert

For this mapping mode, the

To use this mapping mode,

The following client certificate

whole client certificate is

you have to set the following

is received:

compared with each entry in

system properties:

the specified keystore, and


then the user name is defined

as the alias of the matching


entry.

Subject: CN=john.miller,
com.sap.cloud.cry C=DE, O=SAP,
pto.clientcert.ma OU=Development
pping_mode with a
Validity Start Date:
value wholeCert

com.sap.cloud.cry March 19 09:04:32 2013 GMT


pto.clientcert.ke
Validity End Date:
ystore_name with a

March 19 09:04:32 2018 GMT


value the keystore name
containing the respective
user certificates
The specified keystore con

Note
The client certificate is not
accepted if no exact match

tains the same certificate with


an alias john. Then the user
name is defined as john.

is found in the specified


keystore, and then the au
thentication fails. For more
information about the Key
store Service, see Keys
and Certificates [page
1246].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1261

Mapping Mode

Description

How to Set

Example

subjectAndIssuer

For this mapping mode, only

To use this mapping mode,

A certificate with

the subject and issuer fields

you have to set the following

CN=john.miller, C=DE,

of the received client certifi

system properties:

O=SAP, OU=Development as

cate are compared with the


ones of each keystore entry,

com.sap.cloud.cry a subject and CN=SSO CA,


pto.clientcert.ma O=SAP as an issuer is re
ceived. The specified keystore
pping_mode with a

com.sap.cloud.cry alias john that has the same


pto.clientcert.ke subject and issuer fields.
Then the user name is defined
ystore_name with a

and then the user name is de


fined as the alias of the
matching entry.
Use this mapping mode when
you want authentication by
validating only the certifi
cates subject and issuer.

value subjectAndIssuer

contains a certificate with

value the keystore name as john.


containing the respective
user certificates

Note
The client certificate is not
accepted if an entry with
the same subject and is
suer is missing in the
specified keystore, and
then the authentication
fails. For more information
about the Keystore Serv
ice, see Keys and Certifi
cates [page 1246].

1.8.3.1.10.2.1 Trusted Certificate Authorities for Inbound SSL


Connections

Properties
The following trusted certificate authorities (CAs) are available for inbound SSL connections. If the certificate is
self-signed, the subject and issuer DNs are the same.
Table 379: Trusted CAs
Subject DN

Issuer DN

SHA1

CN=Baltimore CyberTrust Root, OU=Cy CN=Baltimore CyberTrust Root, OU=Cy D4:DE:20:D0:5E:66:FC:53:FE:1A:


berTrust, O=Baltimore, C=IE
berTrust, O=Baltimore, C=IE
50:88:2C:78:DB:28:52:CA:E4:74

1262

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Subject DN

Issuer DN

SHA1

CN=Deutsche Telekom Root CA 1,


OU=T-TeleSec Trust Center, O=Deut
sche Telekom AG, C=DE

CN=Deutsche Telekom Root CA 1,


OU=T-TeleSec Trust Center, O=Deut
sche Telekom AG, C=DE

9E:6C:EB:
17:91:85:A2:9E:C6:06:0C:A5:3E:
19:74:AF:94:AF:59:D4

CN=DigiCert High Assurance EV Root


CA, OU=www.digicert.com, O=DigiCert
Inc, C=US

CN=DigiCert High Assurance EV Root


CA, OU=www.digicert.com, O=DigiCert
Inc, C=US

5F:B7:EE:06:33:E2:59:DB:AD:0C:4C:
9A:E6:D3:8F:1A:61:C7:DC:25

CN=Entrust.net Certification Authority


(2048), OU=(c) 1999 Entrust.net Lim
ited, OU=www.entrust.net/CPS_2048
incorp. by ref. (limits liab.), O=En
trust.net

CN=Entrust.net Certification Authority


(2048), OU=(c) 1999 Entrust.net Lim
ited, OU=www.entrust.net/CPS_2048
incorp. by ref. (limits liab.), O=En
trust.net

50:30:06:09:1D:97:D4:F5:AE:
39:F7:CB:E7:92:7D:7D:65:2D:34:31

CN=Entrust.net Client Certification Au


thority, OU=(c) 1999 Entrust.net Lim
ited, OU=www.entrust.net/
Client_CA_Info/CPS incorp. by ref. limits
liab., O=Entrust.net, C=US

CN=Entrust.net Client Certification Au


DA:79:C1:71:11:50:C2:34:39:AA:2B:0B:
thority, OU=(c) 1999 Entrust.net Lim
0C:62:FD:55:B2:F9:F5:80
ited, OU=www.entrust.net/
Client_CA_Info/CPS incorp. by ref. limits
liab., O=Entrust.net, C=US

CN=Entrust.net Secure Server Certifica


tion Authority, OU=(c) 1999 Entrust.net
Limited, OU=www.entrust.net/CPS in
corp. by ref. (limits liab.), O=Entrust.net,
C=US

CN=Entrust.net Secure Server Certifica


tion Authority, OU=(c) 1999 Entrust.net
Limited, OU=www.entrust.net/CPS in
corp. by ref. (limits liab.), O=Entrust.net,
C=US

99:A6:9B:E6:1A:FE:88:6B:4D:2B:
82:00:7C:B8:54:FC:31:7E:15:39

CN=Go Daddy Root Certificate Authority CN=Go Daddy Root Certificate Authority 47:BE:AB:C9:22:EA:E8:0E:
- G2, O="GoDaddy.com, Inc.", L=Scotts - G2, O="GoDaddy.com, Inc.", L=Scotts 78:78:34:62:A7:9F:45:C2:54:FD:E6:8B
dale, ST=Arizona, C=US
dale, ST=Arizona, C=US
CN=GTE CyberTrust Global Root,
OU="GTE CyberTrust Solutions, Inc.",
O=GTE Corporation, C=US

CN=GTE CyberTrust Global Root,


OU="GTE CyberTrust Solutions, Inc.",
O=GTE Corporation, C=US

97:81:79:50:D8:1C:96:70:CC:
34:D8:09:CF:79:44:31:36:7E:F4:74

CN=mySAP.com Workplace CA (dsa),


O=mySAP.com Workplace, C=DE

CN=mySAP.com Workplace CA (dsa),


O=mySAP.com Workplace, C=DE

A1:7D:8B:51:8A:8F:BB:DE:A5:00:C8:1E:
96:12:26:16:32:4A:34:C0

CN=SAP Passport CA, O=SAP Trust


Community, C=DE

CN=SAP Passport CA, O=SAP Trust


Community, C=DE

8D:71:8C:B5:F4:21:9D:5D:39:0C:
79:04:8A:EA:21:85:54:37:F4:57

CN=SSO_CA, O=SAP-AG, C=DE

CN=SSO_CA, O=SAP-AG, C=DE

4D:11:61:08:30:D7:B3:1C:62:87:19:8E:
95:D5:5F:3E:8F:05:E4:0B

CN=TC TrustCenter Class 2 CA II,


OU=TC TrustCenter Class 2 CA, O=TC
TrustCenter GmbH, C=DE

CN=TC TrustCenter Class 2 CA II,


OU=TC TrustCenter Class 2 CA, O=TC
TrustCenter GmbH, C=DE

AE:50:83:ED:7C:F4:5C:BC:8F:
61:C6:21:FE:68:5D:79:42:21:15:6E

CN=TC TrustCenter Class 2 L1 CA XI,


OU=TC TrustCenter Class 2 L1 CA,
O=TC TrustCenter GmbH, C=DE

CN=TC TrustCenter Class 2 CA II,


OU=TC TrustCenter Class 2 CA, O=TC
TrustCenter GmbH, C=DE

4C:37:58:79:7A:AE:
43:74:25:FC:D8:D9:CA:7D:
1A:B4:64:0D:CE:37

CN=TC TrustCenter SSL CA I, OU=TC


TrustCenter SSL CA, O=TC TrustCenter
GmbH, C=DE

OU=Equifax Secure Certificate Author


ity, O=Equifax, C=US

19:84:90:0F:
64:21:0B:CD:C2:64:D3:77:9C:B8:E6:4E:
CA:07:B2:AB

CN=thawte Primary Root CA - G2,


OU="(c) 2007 thawte, Inc. - For author
ized use only", O="thawte, Inc.", C=US

CN=thawte Primary Root CA - G2,


OU="(c) 2007 thawte, Inc. - For author
ized use only", O="thawte, Inc.", C=US

AA:DB:BC:22:23:8F:C4:01:A1:27:BB:
38:DD:F4:1D:DB:08:9E:F0:12

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1263

Subject DN

Issuer DN

SHA1

CN=thawte Primary Root CA, OU="(c)


2006 thawte, Inc. - For authorized use
only", OU=Certification Services Divi
sion, O="thawte, Inc.", C=US

CN=thawte Primary Root CA, OU="(c)


2006 thawte, Inc. - For authorized use
only", OU=Certification Services Divi
sion, O="thawte, Inc.", C=US

91:C6:D6:EE:3E:
8A:C8:63:84:E5:48:C2:99:29:5C:75:6C:
81:7B:81

CN=VeriSign Class 1 Public Primary Cer


tification Authority - G3, OU="(c) 1999
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 1 Public Primary Cer 20:42:85:DC:F7:EB:76:41:95:57:8E:


tification Authority - G3, OU="(c) 1999
13:6B:D4:B7:D1:E9:8E:46:A5
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 2 Public Primary Cer


tification Authority - G3, OU="(c) 1999
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 2 Public Primary Cer 61:EF:43:D7:7F:CA:D4:61:51:BC:


tification Authority - G3, OU="(c) 1999
98:E0:C3:59:12:AF:9F:EB:63:11
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer


tification Authority - G3, OU="(c) 1999
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer 13:2D:0D:45:53:4B:


tification Authority - G3, OU="(c) 1999
69:97:CD:B2:D5:C3:39:E2:55:76:60:9B:
VeriSign, Inc. - For authorized use only", 5C:C6
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer


tification Authority - G4, OU="(c) 2007
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer 22:D5:D8:DF:8F:


tification Authority - G4, OU="(c) 2007
02:31:D1:8D:F7:9D:B7:CF:8A:2D:
VeriSign, Inc. - For authorized use only", 64:C9:3F:6C:3A
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer


tification Authority - G5, OU="(c) 2006
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 3 Public Primary Cer 4E:B6:D5:78:49:9B:1C:CF:5F:58:1E:AD:


tification Authority - G5, OU="(c) 2006
56:BE:3D:9B:67:44:A5:E5
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 4 Public Primary Cer


tification Authority - G3, OU="(c) 1999
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Class 4 Public Primary Cer C8:EC:8C:87:92:69:CB:4B:AB:39:E9:8D:


tification Authority - G3, OU="(c) 1999
7E:57:67:F3:14:95:73:9D
VeriSign, Inc. - For authorized use only",
OU=VeriSign Trust Network, O="Veri
Sign, Inc.", C=US

CN=VeriSign Universal Root Certifica


tion Authority, OU="(c) 2008 VeriSign,
Inc. - For authorized use only", OU=Veri
Sign Trust Network, O="VeriSign, Inc.",
C=US

CN=VeriSign Universal Root Certifica


tion Authority, OU="(c) 2008 VeriSign,
Inc. - For authorized use only", OU=Veri
Sign Trust Network, O="VeriSign, Inc.",
C=US

EMAILADDRESS=certificate@trustcen
ter.de, OU=TC TrustCenter Class 1 CA,
O=TC TrustCenter for Security in Data
Networks GmbH, L=Hamburg, ST=Ham
burg, C=DE

EMAILADDRESS=certificate@trustcen 72:0F:C1:5D:DC:27:D4:56:D0:98:FA:BF:
ter.de, OU=TC TrustCenter Class 1 CA,
3C:DD:78:D3:1E:F5:A8:DA
O=TC TrustCenter for Security in Data
Networks GmbH, L=Hamburg, ST=Ham
burg, C=DE

EMAILADDRESS=certificate@trustcen
ter.de, OU=TC TrustCenter Class 2 CA,
O=TC TrustCenter for Security in Data
Networks GmbH, L=Hamburg, ST=Ham
burg, C=DE

EMAILADDRESS=certificate@trustcen 83:8E:30:F7:7F:DD:14:AA:
ter.de, OU=TC TrustCenter Class 2 CA,
38:5E:D1:45:00:9C:0E:22:36:49:4F:AA
O=TC TrustCenter for Security in Data
Networks GmbH, L=Hamburg, ST=Ham
burg, C=DE

1264

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

36:79:CA:35:66:87:72:30:4D:30:A5:FB:
87:3B:0F:A7:7B:B7:0D:54

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Subject DN

Issuer DN

SHA1

EMAILADDRESS=personal-free
mail@thawte.com, CN=Thawte Personal
Freemail CA, OU=Certification Services
Division, O=Thawte Consulting, L=Cape
Town, ST=Western Cape, C=ZA

EMAILADDRESS=personal-free
mail@thawte.com, CN=Thawte Personal
Freemail CA, OU=Certification Services
Division, O=Thawte Consulting, L=Cape
Town, ST=Western Cape, C=ZA

E6:18:83:AE:84:CA:C1:C1:CD:
52:AD:E8:E9:25:2B:45:A6:4F:B7:E2

EMAILADDRESS=premiumserver@thawte.com, CN=Thawte Pre


mium Server CA, OU=Certification Serv
ices Division, O=Thawte Consulting cc,
L=Cape Town, ST=Western Cape, C=ZA

EMAILADDRESS=premiumserver@thawte.com, CN=Thawte Pre


mium Server CA, OU=Certification Serv
ices Division, O=Thawte Consulting cc,
L=Cape Town, ST=Western Cape, C=ZA

E0:AB:
05:94:20:72:54:93:05:60:62:02:36:70:F
7:CD:2E:FC:66:66

EMAILADDRESS=servercerts@thawte.com, CN=Thawte Server


CA, OU=Certification Services Division,
O=Thawte Consulting cc, L=Cape Town,
ST=Western Cape, C=ZA

EMAILADDRESS=servercerts@thawte.com, CN=Thawte Server


CA, OU=Certification Services Division,
O=Thawte Consulting cc, L=Cape Town,
ST=Western Cape, C=ZA

9F:AD:91:A6:CE:
6A:C6:C5:00:47:C4:4E:C9:D4:A5:0D:
92:D8:49:79

OU=Class 1 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

OU=Class 1 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

90:AE:A2:69:85:FF:14:80:4C:
43:49:52:EC:E9:60:84:77:AF:55:6F

OU=Class 2 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

OU=Class 2 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

67:82:AA:E0:ED:EE:E2:1A:
58:39:D3:C0:CD:14:68:0A:4F:60:14:2A

OU=Class 3 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

OU=Class 3 Public Primary Certification


Authority, O="VeriSign, Inc.", C=US

A1:DB:63:93:91:6F:
17:E4:18:55:09:40:04:15:C7:02:40:B0:A
E:6B

OU=Equifax Secure Certificate Author


ity, O=Equifax, C=US

OU=Equifax Secure Certificate Author


ity, O=Equifax, C=US

D2:32:09:AD:23:D3:14:23:21:74:E4:0D:
7F:9D:62:13:97:86:63:3A

OU=Go Daddy Class 2 Certification Au


thority, O="The Go Daddy Group, Inc.",
C=US

OU=Go Daddy Class 2 Certification Au


thority, O="The Go Daddy Group, Inc.",
C=US

27:96:BA:E6:3F:
18:01:E2:77:26:1B:A0:D7:77:70:02:8F:
20:EE:E4

OU=VeriSign Trust Network, OU="(c)


1998 VeriSign, Inc. - For authorized use
only", OU=Class 1 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


1998 VeriSign, Inc. - For authorized use
only", OU=Class 1 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

27:3E:E1:24:57:FD:C4:F9:0C:55:E8:2B:
56:16:7F:62:F5:32:E5:47

OU=VeriSign Trust Network, OU="(c)


1998 VeriSign, Inc. - For authorized use
only", OU=Class 2 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:
1998 VeriSign, Inc. - For authorized use
95:B6:CC:A0:08:1B:67:EC:9D
only", OU=Class 2 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


1998 VeriSign, Inc. - For authorized use
only", OU=Class 3 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


85:37:1C:A6:E5:50:14:3D:CE:
1998 VeriSign, Inc. - For authorized use
28:03:47:1B:DE:3A:09:E8:F8:77:0F
only", OU=Class 3 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


1998 VeriSign, Inc. - For authorized use
only", OU=Class 4 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

OU=VeriSign Trust Network, OU="(c)


0B:77:BE:BB:CB:7A:A2:47:05:DE:CC:
1998 VeriSign, Inc. - For authorized use
0F:BD:6A:02:FC:7A:BD:9B:52
only", OU=Class 4 Public Primary Certifi
cation Authority - G2, O="VeriSign, Inc.",
C=US

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1265

Subject DN

Issuer DN

SHA1

SERIALNUMBER=07969287, CN=Go
Daddy Secure Certification Authority,
OU=http://certificates.godaddy.com/
repository, O="GoDaddy.com, Inc.",
L=Scottsdale, ST=Arizona, C=US

OU=Go Daddy Class 2 Certification Au


thority, O="The Go Daddy Group, Inc.",
C=US

7C:46:56:C3:06:1F:7F:4C:0D:
67:B3:19:A8:55:F6:0E:BC:11:FC:44

1.8.3.1.10.3 Using Strong Encryption in Applications


By default, SAP JVM provides Java Cryptography Extension (JCE) with limited cryptography strength. If you want
to use cryptography with unlimited strength in an SAP HANA Cloud Platform application, you need to enable it via
installing the necessary Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files on SAP
JVM. To do that, follow the procedure below.

Prerequisites
You have the appropriate Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files enabling
cryptography with unlimited strength.

Procedure
1. Pack the encryption policy files (JCE Unlimited Strength Jurisdiction Policy Files) in the following folder of the
Web application:
META-INF/ext_security/jre7 - for applications, running on JDK 1.7
2. If the application consists of multiple WAR files, pack the encryption policy files in one of them.
3. Deploy the application on SAP HANA Cloud Platform.

Results
The encryption policy files (Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files) will
be installed on the JVM of the application prior to start. As a result, the application can use unlimited strength
encryption.

Example
The WAR file of the application must have the following file entries:
META-INF/ext_security/jre7/local_policy.jar
META-INF/ext_security/jre7/US_export_policy.jar

1266

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Deploying and Updating Applications [page 973]

1.8.3.1.10.4 Storing Passwords

Context
Using the password storage API, you can securely persist passwords and key phrases such as passwords for
keystore files. Once persisted in the password storage, they:
Can be accessed from different application computing units;
Survive application restarts and updates;
Are a subject of automatic backup;
Stay persisted unless you explicitly delete them via the API, or you undeploy your application.
Before transportation and persistence, passwords are encrypted with an encryption key which is specific for the
application that owns the password.

Note
Each password is identified by an alias. To check the rules and constraints about passwords aliases, permitted
characters and length, see the security javadoc.

Adding Resource Reference


To use the password storage API, you need to add a resource reference to PasswordStorage in the web.xml file
of your application, which is located in the \WebContent\WEB-INF folder as shown below:
<resource-ref>
<res-ref-name>PasswordStorage</res-ref-name>
<res-type>com.sap.cloud.security.password.PasswordStorage</res-type>
</resource-ref>

Looking Up the JNDI

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1267

An initial JNDI context can be obtained by creating a javax.naming.InitialContext object. You can then
consume the resource by looking up the naming environment through the InitialContext class as follows:
InitialContext ctx = new InitialContext();
PasswordStorage passwordStorage = (PasswordStorage) ctx.lookup("java:comp/env/
PasswordStorage");
Note that according to the Java EE Specification, the prefix java:comp/env should be added to the JNDI resource
name (as specified in the web.xml file) to form the lookup name.

Using the Password Storage API


Below is a code example of how to use the API to set, get or delete passwords. These methods provide the option
of assigning an alias to the password.
import javax.naming.InitialContext;
import javax.naming.NamingException;
import com.sap.cloud.security.password.PasswordStorage;
import com.sap.cloud.security.password.PasswordStorageException;
.......
private PasswordStorage getPasswordStorage() throws NamingException {
InitialContext ctx = new InitialContext();
PasswordStorage passwordStorage = (PasswordStorage) ctx.lookup("java:comp/env/
PasswordStorage");
return passwordStorage;
}
private void setPassword(String alias, char[] password) throws
PasswordStorageException, NamingException {
PasswordStorage passwordStorage = getPasswordStorage();
passwordStorage.setPassword(alias, password);
}
private char[] getPassword(String alias) throws PasswordStorageException,
NamingException {
PasswordStorage passwordStorage = getPasswordStorage();
return passwordStorage.getPassword(alias);
}
private void deletePassword(String alias) throws PasswordStorageException,
NamingException {
PasswordStorage passwordStorage = getPasswordStorage();
return passwordStorage.deletePassword(alias);
}

Local Testing
When you run applications on SAP HANA Cloud Platform local runtime, you can use a local implementation of the
password storage API, but keep in mind that the passwords are not encrypted and stored in a local file. Therefore,
for local testing, use only test passwords.

1268

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Related Information
Security Development [page 1212]

1.8.3.2

Security Testing

This section describes how you can test the security you have implemented in your Java applications.
First, you need to test your application on your local runtime. If you use the Eclipse Tools, you can easily test with
local users. This is useful if you are implementing role-based identity management in your application.
Then, if everything goes well on the local runtime, you can deploy your application on SAP HANA Cloud Platform,
and test how the application works on the Cloud with your local SAML 2.0 identity provider. This makes use if you
are implementing SAML 2.0 identity federation.

Related Information
Security Testing Locally [page 1269]
Security Testing on the Cloud (with a Local Identity Provider) [page 1273]

1.8.3.2.1

Security Testing Locally

When you add user authentication to your application, you can test it first on the local server before uploading it to
SAP HANA Cloud Platform.

Note
On the local server, authentication is handled locally, that is, not by the SAP ID service. When you try to access
a protected resource on the local server, you will see a local login page (not SAP ID service's or another identity
provider's login page). User access is then either granted or denied based on a local JSON (JavaScript Object
Notation ) file (<local_server_dir>/config_master/com.sap.security.um.provider.neo.local/neousers.json),
which defines the local set of user accounts, along with their roles and attributes. This is just for testing
purposes. When you deploy to the cloud, user authentication is still handled by the SAP ID service.
Using SAP HANA Cloud Platform Tools (Eclipse Tools), you can easily manage local users. You can use the
visual editor for configuring the users, or edit the JSON file directly.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1269

Opening the Editor


1. In the Eclipse IDE, open the Servers view.
2. Select the local server and double-click it. The local server editor opens.
3. Open the Users tab page.

Creating and Managing Users


1. In the All Users pane, choose button

to add a new user.

2. Specify the user ID and password, and optionally, email, first name and last name.
3. Choose OK.
4. Save the changes in the editor.

Managing User Attributes


User attributes provide additional information about a user account. Applications can use attributes to distinguish
between users or customization according to users. To add a new attribute, proceed as follows:
1. In the Attributes pane, choose button

to add a new attribute.

2. Specify the name-value pair, and choose OK.

1270

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Save the changes in the editor.

Managing User Roles


Roles are used by applications to define access rights. By default, each user is assigned the User.Everyone role. It
is read-only, which means you cannot remove it. To add a new role, proceed as follows:
1. In the Roles pane, choose button

to add a new role.

2. Specify the role name and choose OK.


3. Save the changes in the editor.

Importing Users and Roles


1. Choose button

(Import users and roles).

2. Browse to a valid JSON file and choose OK.


3. The JSON file is imported within the Users editor.

Exporting Users and Roles


1. From the list of JSON files, select the user you want to export.
2. Choose button

(Export all users and roles).

3. Browse to the directory you want to export your JSON file.

Tip
The default name of the exported file is localusers.json. You can rename it to something more
meaningful to you.

Local Testing with the Console Client


If you prefer using the console client instead of the Eclipse IDE, you have to find and edit manually the JSON file
configuring local test users. It is located at <local_server_dir>/config_master/
com.sap.security.um.provider.neo.local/neousers.json.
The following example shows a sample configuration of a JSON file with two users, along with their attributes and
roles:
{

"Users": [
{

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1271

},
{

"UID": "P000001",
"Password": "{SSHA}OA5IKcTJplwLLaXCjmbcV+d3LQVKey+bEXU\u003d",
"Roles": [
"Employee",
"Manager"
],
"Attributes": [
{
"attributeName": "firstname",
"attributeValue": "John"
},
{
"attributeName": "lastname",
"attributeValue": "Doe"
},
{
"attributeName": "email",
"attributeValue": "john.doe@yourcompany.com"
}
]
"UID": "P000002",
"Password": "{SSHA}OA5IKcTJplwLLaXCjmbcV+d3LQVKey+bEXU\u003d",
"Roles": [
"SomeRole"
],
"Attributes": [
{
"attributeName": "firstname",
"attributeValue": "Boris"
},
{
"attributeName": "lastname",
"attributeValue": "Boykov"
},
{
"attributeName": "email",
"attributeValue": "b.boykov@anothercompany.com"
}
]

Troubleshooting
When stopping your local server, you might see the following error logs:
#ERROR#org.apache.catalina.core.ContainerBase##anonymous#System Bundle
Shutdown###ContainerBase.removeChild: stop:
org.apache.catalina.LifecycleException: Failed to stop component
[StandardEngine[Catalina].StandardHost[localhost].StandardContext[/idelogin]]
This error causes no harm and you don't need to take any measures.

1272

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Next Steps
After testing, you can proceed with deploying the application to SAP HANA Cloud Platform. For more
information, see Deploying and Updating Applications [page 973].
After deploying on the cloud, you may need to perform configuration steps using the cockpit. For more
information, see Security Configuration [page 1280].

1.8.3.2.2

Security Testing on the Cloud (with a Local Identity


Provider)

You can use a local test identity provider (IdP) to test single sign on (SSO) and identity federation of an SAP HANA
Cloud Platform application end-to-end.
This scenario offers simplified testing in which developers establish trust to an application deployed in the cloud
with an easy-to-use local test identity provider .
For more information about the identity provider concept in SAP HANA Cloud Platform, see ID Federation with the
Corporate Identity Provider [page 1292].
Contents:
Prerequisites [page 1273]
Procedure [page 1274]
1. Set up the local test IdP [page 1274]
2. Configure the service provider of your account in SAP HANA Cloud Platform [page 1275]
3. (Optional ) Configure the local IdP name [page 1275]
4. Configure trust on SAP HANA Cloud Platform to the local test IdP [page 1276]
5. Generate self sign-key pair and certificate for the local test IdP (optional) [page 1278]
6. Configure trust on the local test IdP to SAP HANA Cloud Platform [page 1279]

Prerequisites
You have set up and configured the Eclipse IDE for Java EE Developers and SAP HANA Cloud Platform Tools
for Java. For more information, see Setting Up the Tools and SDK [page 33].
You have developed and deployed your application on SAP HANA Cloud Platform. For more information, see
Creating an SAP HANA Cloud Platform Application [page 966].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1273

Procedure
The usage of the local test identity provider involves the following steps:

1. Set up the local test IdP


1. Open the Eclipse IDE.
2. Go to the Servers view.
3. From the context menu, choose

New

Server .

4. In the Define a new server wizard, select Java Web Server, Java Web Tomcat 7 Server, or Java EE 6 Web Profile
Server (depending on the SDK you use).
5. Start the server. The local test IdP is packaged within the SDK, so when you start the server, it will start as
well.
6. Double-click the server and open the Users tab page.
7. Define local test IdP users and their attributes. Exemplary data:

For more information about the Users editor, see Testing User Authentication on the Local Server [page 1213].

1274

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

2. Configure the service provider of your account in SAP HANA Cloud Platform
1. In a Web browser, open the cockpit and navigate to

Security

Trust

Local Service Provider .

2. Choose Edit.
3. For Configuration Type, choose Custom.
4. Choose Generate Key Pair to generate a new signing key and self-signed certificate.
5. For the rest of the fields, leave the default values.
6. Choose Save.
7. Choose Get Metadata to download and save the SAML 2.0 metadata identifying your SAP HANA Cloud
Platform account as a service provider. You will have to import this metadata into the local test IdP to
configure trust to SAP HANA Cloud Platform in the procedure that follows.

3. (Optional ) Configure the local IdP name


You need to configure your local IdP name if you want to use more than one local IdP. Default local IdP name:
localidp.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1275

1. In the Eclipse IDE, go to the already set up local server that will be used as local IdP.
2. In the config_master/com.sap.core.jpaas.security.saml2.cfg/ folder, create a file named
local_idp.cfg.
3. In the file, add a property:
localidp_name=<idpname you want to use>
4. Restart the local server.

4. Configure trust on SAP HANA Cloud Platform to the local test IdP
The trust settings on SAP HANA Cloud Platform for the local test IdP are configured in the same way as with any
other productive IdP.
1. During the configuration, use the local test IdP metadata that can be requested under the following link:
http://<idp_host>:<idp_port>/saml2/localidp/metadata,
where <idp_host> and <idp_port> are the local server host and port.
To find the <idp_port>, go to Servers, double click on the local server and choose

Overview

Ports

Configuration .

2. Configure trust on the cloud to the local test IdP.


1. Open the cockpit in a Web browser, navigate to
then click Add Trusted Identity Provider.

Security

Trust

Trusted Identity Providers , and

2. In General tab page, use the Metadata File Browse button to add the local test IdP metadata.
All the needed values are filled in automatically.

1276

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

3. Choose Save & Close.

For more information, see ID Federation with the Corporate Identity Provider [page 1292]
3. Configure the User Attributes.
Assertion-based attributes are used to define a mapping between attributes in the SAML assertion issued by the
local test IdP and user attributes on the Cloud.
This allows you to essentially pass any attribute exposed by the local test IdP to an attribute used in your
application in the cloud.
Define user attributes in the local test IdP by using the Eclipse IDE Users editor for SAP HANA Cloud Platform as is
described in Setting up the local test IdP.
To add an assertion-based attribute, proceed as follows:
1. Open the cockpit in a Web browser, navigate to

Security

Trust

Trusted Identity Providers .

2. From the table, choose the entry localidp, open the Attributes tab page, and click on Add Assertion-Based
Attribute.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1277

3. In Assertion Attribute, enter the name of the attribute contained in the SAML 2.0 assertion issued by the local
test IdP. These are the same user attributes you defined in the Eclipse IDE Users editor when setting the local
test IdP.
4. In Principal Attribute, enter the name of the user attribute as referred in the tested application.

5. Choose Save & Close.

5. Generate self sign-key pair and certificate for the local test IdP (optional)
If an error occurs while requesting the IdP metadata and the metadata cannot be generated, you can do the
following:
1. Generate a localidp.jks keyfile manually. The key and certificate are needed for signing the information that
the local test IdP will exchange with SAP HANA Cloud Platform.
2. Open the directory <JAVA_HOME>/jre/bin/keytool
3. Open a command line and execute the following command:
keytool -genkeypair -dname "CN=localidp" -keyalg "RSA" -validity 3650 -alias
localidp -storepass localidp -keypass localidp -keystore <fullpath_dir_name>
\localidp.jks
where <fullpath_dir_name> is the directory path where the jks will be saved after the creation.
4. Under the Server directory, go to config_master\com.sap.core.jpaas.security.saml2.cfg and
create a directory with name localidp.
5. Copy the localidp.jks file under localidp directory.

1278

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

6. Configure trust on the local test IdP to SAP HANA Cloud Platform
1. In the Eclipse IDE, go to the already set up local test IdP Server.
2. Copy the file with the metadata describing SAP HANA Cloud Platform as a service provider under the local
server directory config_master/com.sap.core.jpaas.security.saml2.cfg/localidp. To get this
metadata, in the cockpit, choose

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Security

Trust

Local Service Provider

Get Metadata .

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1279

Result
You can now access your application, deployed on the cloud, and test it against the local test IdP and its defined
users and attributes.

1.8.3.3

Security Configuration

When you have implemented security in your application, you need to perform a few configuration tasks using the
Cockpit to enable the scenario to work successfully on SAP HANA Cloud Platform.

Related Information
Managing Roles [page 1282]
ID Federation with the Corporate Identity Provider [page 1292]

1.8.3.3.1

Configuring Authentication for Your Application

This is an optional procedure that you can perform to configure the options for the authentication methods you
defined for your application.

Prerequisites
You have an application with authentication defined in its web.xml or source code. See Enabling
Authentication [page 1213] .

Context
The following table describes the available authentication options. For each authentication method, you can select
a custom combination of options. You may need to select more than one option if you want to enable more than
one way for users to authenticate for this application.
If you select more than one option, SAP HANA Cloud Platform will delegate authentication to the relevant login
modules consecutively in a stack. When a login module succeeds to authenticate the user, authentication ends
with success. If no login module succeeds, authentication fails.

1280

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Table 380: Authentication Options


Authentication Options

Descrption

Trusted SAML 2.0 identity provider

Authentication is implemented over the Security Assertion


Markup Language (SAML) 2.0 protocol, and delegated to SAP
ID service or custom identity provider (IdP). The credentials
users need to present depend on the IdP settings. See ID Fed
eration with the Corporate Identity Provider [page 1292].

User name and password

HTTP BASIC authentication with user name and password.


The user name and password are validated either by SAP ID
service (default) or by an on-premise SAP NetWeaver AS
Java. See Using an SAP System as an On-Premise User Store
[page 1305]

Client certificate

Users authenticate with a client certificate installed in an onpremise SAP NetWeaver Application Server for Java system.
See Enabling Client Certificate Authentication [page 1256]

Application-to-Application SSO

Used for AppToAppSSO destinations. See Application-to-Ap


plication SSO Authentication [page 332].

Note
When you select Trusted SAML 2.0 identity provider,
Application-to-Application SSO becomes enabled automat
ically.
OAuth 2.0 token

Authentication is implemented over the OAuth 2.0 protocol.


Users need to present an OAuth access token as credential.
See Protecting Applications with OAuth 2.0 [page 1227].

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
Make sure that you have selected the relevant global account to be able to select the right account.
2. Enter the

Applications

Java Applications

section.

3. Click the application you want to configure.


4. Enter the Authentication Configuration section.
5. To configure the default settings, choose Custom, and then choose Edit.
You can configure existing authentication methods or create new ones. If you need to restore the default state
of all default methods, choose the Restore button for the entire panel. If you need to restore the default state
of a particular method, choose the Restore button for that method (not available for custom methods you
defined).
6. Save the changes to the authentication configuration.
7. Restart the application so the changes can take effect.

Example
You have a Web application that users access using a Web browser. You want users to log in using a SAML
identity provider. Hence, you define the FORM authentication method in the web.xml of the application.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1281

However, later you decide to provide mobile access to your application using the OAuth protocol (SAML is not
optimized for mobile access). You do this by adding the OAuth 2.0 token option for the FORM method for your
application. In this way, desktop users will continue to log in using a SAML identity provider, and mobile users
will use an OAuth 2.0 access token.

Related Information
Enabling Authentication [page 1213]
Specifying Authentication Mechanisms (general information)

1.8.3.3.2

Managing Roles

In SAP HANA Cloud Platform, you can use Java EE roles to define access to the application resources.

Context
This tutorial shows the end-to-end scenario for defining and using roles for tuning access to application resources.
Table 381: Terms
Term

Description

Role

Roles allow you to diversify user access to application resources (role-based authorizations).

Note
Role names are case sensitive.

1282

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Term

Description

Predefined roles

Predefined roles are ones defined in the web.xml of an application.


See Enabling Authentication [page 1213].
After you deploy the application to SAP HANA Cloud Platform, the role becomes visible in the Cockpit,
and you can assign groups or individual users to that role. If you undeploy your application, these roles
are removed.
Predefined roles can be:

Shared - they are shared by default. A shared role is visible and accessible within all accounts sub
scribed to this application.

Restricted - an application administrator could restrict a shared role. A restricted role is visible
and accessible only within the account that deployed the application, and not to accounts subscri
bed to the application.

Note
If you restrict a shared role, you hide it from visibility for new assignments from subscribed ac
counts but all existing assignments will continue to take effect.
Custom roles

Custom roles are ones defined using the Cockpit. Custom roles are interpreted in the same way as pre
defined roles at SAP HANA Cloud Platform: they differ only in the way they are created, and in their
scope.
You can add custom roles to an application to configure additional access permissions to it without
modifying the application's source code.
Custom roles are visible and accessible only within the account where they are created. Thats why dif
ferent accounts subscribed to the same application could have different custom roles.

User

Users are principals managed by identity providers (SAP ID service or others).

Note
SAP HANA Cloud Platform does not have a user database on its own. It cares to map the users au
thorized by identity providers to groups, and groups to roles.

Note
When a user logs in, its roles are stored in the user's current browser session. They are not updated
dynamically, and removed from there only if the session is terminated or invalidated. This means if
you change the set of roles for a user currently logged, they will take effect only after logout or ses
sion invalidation.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1283

Term

Description

Group

Groups are collections of roles that allow the definition of business-level functions within your account.
They are similar to the actual business roles existing in an organization, such as "manager", "em
ployee", "external" and so on. They help you to get better alignment between technical Java EE roles
and organizational roles.

Note
Group names are case insensitive.
For each identity provider (IdP) for your account, you define a set of rules specifying the groups a user
for this IdP belongs to.
See Using a Custom Identity Provider [page 1292].

1. Define the Roles


Context
This can be done in two ways: using predefined roles in the web.xml at development time, or using custom roles in
the UI.

Procedure
Predefined Roles
a. In the web.xml of the required application, define the roles authorized to access the application resources.
See Enabling Authentication [page 1213].
b. Deploy the application to SAP HANA Cloud Platform.
See Deploying and Updating Applications [page 973].
c. Optionally, if you want to restrict the roles to the current application only, deselect the Share option for
them in the Cockpit.

1284

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Custom roles with applications from the same account


a. In the cockpit, go to the

Applications

Java Applications

section.

b. Click the required application link.


c. Enter the Roles section.
d. Choose New Role.
e. Type the role name and choose OK.
Custom roles with applications subscribed from other accounts
a. In the cockpit, go to the

Applications

Subscriptions

section.

b. In the list of subscribed aplications, click the required application link.


c. Enter the Roles section.
d. Choose New Role.
e. Type the role name and choose OK.

2. (Optional) Create Groups


Context
Groups allow you to easily manage the role assignments to collections of users instead of individual users.

Procedure
1. In the cockpit, go to the

Security

Authorizations

section for the account.

2. Enter the Groups tab.


3. Choose New Group.
4. Enter the group name and choose Save.

3. Assign Users or Groups to the Roles


Context
You can assign individual users to the roles or, more conveniently, assign groups for collective role management.
You can do it in either of the two ways: using the
Security

Authorizations

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Security

Roles

section for the application, or using the

section for the account.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1285

Procedure
Using the Roles section
a. In the cockpit, go to the

Applications

Java Applications

section.

b. Click the required application link.


c. Enter the

Security

Roles

section.

d. Select the role you want to manage assignments for.


e. To assign a new user or group, choose Assign for the Users or Groups section respectively.
f. Enter the user or group name.

g. Save the changes.

1286

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Alternatively, you can do it using the Authorizations section for the account.
a. In the cockpit, go to the

Security

Authorizations

section for the account.

b. Enter the Users or Groups tab respectively.


c. In the User or Group field respectively, enter the name of the required user or group. If you want to create
a new user or group, simply assign the required roles from here.
d. Choose Show Assignments. The table below shows all roles that are already assigned to this user or
group.

e. If you are adding an individual user, choose the required application and the role the user will have. If you
are adding a group, select the existing group from the list.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1287

Tip
You can use regular expressions to narrow the groups found.
f. Save the changes.

4. (If Using an Identity Provider) Define the Group-to-Role


Mapping
Context
For each different IdP, you then define a set of rules specifying to which groups a user logged by this IdP belongs.

Note
You must have defined groups in advance before you define default or assertion-based groups for this IdP.
Default groups are the groups all users logged by this IdP will have. For example, all users logged by the company
IdP can belong to the group "Internal".
Assertion-based groups are groups determined by values of attributes in the SAML 2.0 assertion. For example, if
the assertion contains the attribute "contract=temporary", you may want all such users to be added to the
group "TEMPORARY".

Procedure
Defining Default Groups
a. In the cockpit, navigate to

Security

Authorizations

Groups , and choose Add Default Group.

b. From the dropdown list that appears, choose the required group.
Defining Assertion-Based Groups

1288

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

a. In the cockpit, navigate to Security Authorizations Groups , and choose Add Assertion-Based
Group. A new row appears and a new mapping rule is now being created.
b. Enter the name of the group to which users will be mapped. Then define the rule for this mapping.
c. In the first field of the Mapping Rules section, enter the SAML 2.0 assertion attribute name to be used as
the mapping source. In other words, the value of this attribute will be compared with the value you specify
(in the last field of Mapping Rules).
d. Choose the comparison operator.
Table 382:
Equals

Choose Equals if you want the value of the SAML 2.0 as


sertion attribute to match exactly the string you specify.
Note that if you want to use more sophisticated relations,
such as "starts with" or "contains", you need to use the
Regular expression option.

Regular expression

Choose Regular expression if you want to specify more


sophisticated matching rules. You can use all regular ex
pression rules described in the Java RegEx API

Example 1: You want to add authenticated SAP employ


ees to group Employees. And SAP employees are users
with e-mail address ending with sap.com. Hence, you
choose the mapping rule to be email, matched using the
following regular expression:
.*@sap.com$
Example 2: You want all users with name starting with
admin to be added to group Administrators. Hence, you
choose the mapping rule to be userid, matched using the
following regular expression:
^(admin).*

e. In the last field of Mapping Rules, enter the value with which you compare the specified SAML 2.0
assertion attribute.
f. You can specify more than one mapping rule for a specific group. Use the plus button to add as many
rules as required. In this case, mapping is based on a logical OR operation for all rules, that is, if one of
your rules applies, the user is added to the group
In the image below, all users logged by this IdP are added to the group Government. The users that have
an arrtibute corresponding to their department name will also be assigned to the respective department
groups.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1289

When you open the Groups tab page of the Authorizations section, you can see the identity provider
mappings for this group.

5. Test
Try to access the required application logging on with users with and without the required roles respectively.

1.8.3.3.3

Changing the Default Role Provider

If you have SAP HANA Cloud Platform extension package for SuccessFactors configured for your account, you
can change the default SAP HANA Cloud Platform role provider to another one.

Prerequisites
You have an SAP HANA Cloud Platform partner or customer account. For more information about account
types, see Account Types [page 12]
You have an SAP HANA Cloud Platform extension package for SuccessFactors and the extension package is
configured for your SAP HANA Cloud Platform account. For more information, see the Configuring Extension
Package for SuccessFactors Automatically section in the SAP HANA Cloud Platform, Extension Package for
SuccessFactors: Implementation Guide
You are an administrator of your SAP HANA Cloud Platform account.
Your application runtime supports destinations. For more information about the application runtimes
supported by SAP HANA Cloud Platform, see Application Runtime Container
You have configured the HTTP destination required to ensure your application's connectivity to
SuccessFactors. For more information, see the Configuring Destinations for Extension Applications section in
SAP HANA Cloud Platform, Extension Package for SuccessFactors: Implementation Guide .

1290

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

In the SuccessFactors system, you have roles with the required permissions and these roles are with the
same names as those defined in the web.xml file of the extension application. For more information about
creating permission roles in SuccessFactors, see the How do you create a permission role? section in RoleBased Permissions Administration Guide.
In the SuccessFactors system, you have assigned the required roles to the corresponding users and groups.
For more information, see the How can you grant permission roles? section in the Role-Based Permissions
Administration Guide.
When creating the extension application, you have defined the required roles in the web.xml file of the
application and these roles are the same as the ones you have for the application in the SuccessFactors
system. For more information about how to define roles in the web.xml file of the application, see Enabling
Authentication [page 1213]

Context
A role provider is the component that retrieves the roles for a particular user. By default, the role provider used for
SAP HANA Cloud Platform applications and services is the SAP HANA Cloud Platform role provider. For extension
applications, however, you can change the default role provider to another one, for example, a SuccessFactors
role provider. Depending on whether the application is running in your account or your account is subscribed to
the extension application, you configure the role provider from either the Roles section for your application, or the
Subscription section for your account. In addition, you can view the role provider for each enabled SAP HANA
Cloud Platform service in the Services section of the SAP HANA Cloud Platform cockpit.

Procedure
1. Log on to the cockpit and select the required account.
Make sure that you have selected the relevant global account to be able to select the right account.
2. Navigate to the application for which you want to change the role provider. To do so, proceed as follows:
For a Java application running in your account, choose
choose the link of the application.

Applications

For a Java application to which your account is subscribed, choose


then choose the link of the application.
3. Choose

Security

Java Applications , and then

Applications

Subscriptions , and

Roles .

4. In the Role Provider panel, select the required role provider from the Provider dropdown box.
5. (Optional) To view the role provider for an SAP HANA Cloud Platform service, in the cockpit navigate to
Services

<service_name> , and then choose Configure Roles.

The system displays the role provider in the Role Provider panel in a read-only mode.

Note
For an account with SAP HANA Cloud Platform extension package for SuccessFactors, the role provider for
SAP HANA Cloud Portal is SuccessFactors.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1291

Results
The changes take effect after 5 minutes. If you want the changes to take effect immediately, you restart the
application (valid only for applications running in your account).

1.8.3.3.4

ID Federation with the Corporate Identity Provider

You can delegate user authentication for your applications to your corporate identity provider. This is called
identity federation. SAP HANA Cloud Platform supports Security Assertion Markup Language (SAML) 2.0 for
identity federation.

Contents
Prerequisites [page 1292]
Configure SAP HANA Cloud Platform as a Local Service Provider [page 1293]
Configure Trust to the SAML Identity Provider [page 1295]
Using an IdP Different from the Default [page 1301]

Prerequisites
You have a key pair and certificate for signing the information you exchange with the IdP on behalf of SAP
HANA Cloud Platform. This ensures the privacy and integrity of the data exchanged. Optionally, you can
generate a key pair and certificate with SAP HANA Cloud Platform. However, this key pair should not be used
in a productive environment since its certificate is only self-signed. A key pair and certificate signed by a
trusted Certificate Authority (CA)
are strongly recommended for use in a productive environment. You
create these using external certificate and key generation tools.
You have provided the IdP with the above certificate. This allows the IdP administrator to configure its trust
settings.
You have the IdP signing certificate to enable you to configure the cloud trust settings.
You have negotiated with the IdP administrator which information the SAML 2.0 assertion will contain for
each user. For example, this could be a first name, last name, company, position, or an e-mail.
You know the authorizations and attributes the users logged by this IdP need to have on SAP HANA Cloud
Platform.

1292

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.4.1 Configure SAP HANA Cloud Platform as a Local


Service Provider

Context
In the SAML 2.0 communication, each SAP HANA Cloud Platform account acts as a service provider. For more
information, see Security Assertion Markup Language (SAML) 2.0
protocol specification.

Tip
Each SAP HANA Cloud Platform account is a separate service provider. If you need each of your applications to
be represented by its own service provider, you must create and use a separate account for each application.
See Creating Accounts [page 18].

Note
In this documentation and SAP HANA Cloud Platform user interface, we use the term local service provider to
describe the SAP HANA Cloud Platform account as a service provider in the SAML 2.0 communication.
You need to configure how the local service provider communicates with the identity provider. This includes, for
example, setting a signing key and certificate to verify the service providers identity and encrypt data. You can
use the configuration settings described in the table that follows.
Table 383:
Local Service Provider Configuration

Description

When to Use

Default

The local provider's own trust settings

For testing and exploring the scenario

will inherit the SAP HANA Cloud Plat


form default configuration (which is
trust to SAP ID service).
None

The local provider will have no trust set

For disabling identity federation for your

tings, and it will not participate in any

account

identity federation scenario.


Custom

The local provider settings will have a

For identity federation with a corporate

specific configuration, different from the

identity provider or SAP Cloud Identity

default configuration for SAP HANA

tenant

Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1293

In addition, you can configure the following local service provider settings:
Table 384:
Local Service Provider Configuration (Additional)

Description

Principal Propagation

If you set it to Enabled, you enable applications to propagate


principal information to each other. Choose this value if you
want to enable application-to-application single sign-on. Oth
erwise, set this option to Disabled.

Force authentication

. If you set it to Enabled, you enable force authentication for


your application (despite SSO, users will have to re-authenti
cate each time they access it). Otherwise, set this option to
Disabled.

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
Make sure that you have selected the relevant global account to be able to select the right account.
2. Choose the

Security

Trust

section.

3. Choose the Local Service Provider tab.


4. Choose Edit.
5. Choose Custom as Configuration Type.
6. Enter the local provider name.
7. In Signing Key, copy the Base64-encoded signing key of SAP HANA Cloud Platform (you should have a key
generated from an external key generation application).
8. In Signing Certificate, copy the textual content of the certificate identifying SAP HANA Cloud Platform (you
should have a certificate generated from an external application and signed by a trusted CA).

Note
Optionally, you can choose Generate Key Pair to generate a new signing key and self-signed certificate.
These should not be used in a productive environment. Instead, use a key pair and certificate signed by a
trusted CA.
9. Choose the required value of the Principal Propagation and Force authentication option.
10. Save the changes.
11. Choose Get Metadata to download the SAML 2.0 metadata describing SAP HANA Cloud Platform as a service
provider. You will have to import this metadata into the IdP to configure trust to SAP HANA Cloud Platform.

1294

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.4.2 Configure Trust to the SAML Identity Provider

Context
Note
To benefit from fully-featured identity federation with SAML identity providers, you need to have chosen the
Custom configuration type in the Local Service Provider section.
For Default configuration type, you have non-editable trust to SAP ID Service as default identity provider. You
can add other identity providers but they can be used for IdP-initiated single sign-on (SSO) only.
For None, you don't have any trust settings.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1295

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
Make sure that you have selected the relevant global account to be able to select the right account.
2. Enter the

Security

Trust

Trusted Identity Providers

section.

3. Click Add Trusted Identity Provider.


4. In the General tab, upload the IdP metadata xml file or manually enter he communication settings negotiated
between SAP HANA Cloud Platform and the IdP. On IdP metadata upload, the fields are populated with the
parsed data from the XML file. The minimum configuration is to complete all required fields.

1296

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Field

Description

Metadata File

The metadata XML file of the identity provider .

Name

The entity ID of the IdP, also known as the issuer.

Description

A short description of the IdP.

Assertion Consumer Service

The SAP HANA Cloud Platform endpoint type (application


root or assertion consumer service). The IdP will send the
SAML assertion to that endpoint.
In the common case, select Application Root as value.
If you have an identity provider that would not send the
SAML assertion to unknown URLs to them, select the
Assertion Consumer Service option. This is the case with
Microsoft ADFS, for example.

Single Sign-on URL

The IdP's endpoint (URL) to which the SP's authentication


request will be sent.

Single Sign-on Binding

The SAML-specified HTTP binding used by the SP to send


the authentication request.

Single Logout URL

The IdP's endpoint (URL) to which the SP's logout request


will be sent.

Signature Algorithm

The cryptographic algorithm used to compute the digest of


the digital signatures in the SAML protocol messages.

Signing Certificate

The X.509 certificate used by the IdP to digitally sign the


SAML protocol messages.

User ID Source

Location in the SAML assertion from where the user's


unique name (ID) is taken when logging into the Cloud. If
you choose subject, this is taken from the name identifier
in the assertions's subject (<saml:Subject>) element. If
you choose attribute, the user's name is taken from an
SAML attribute in the assertion.

Source Value

Name of the SAML attribute that defines the user ID on the


cloud.

User ID Prefix

An optional prefix added to the user ID on the cloud.

User ID Suffix

An optional suffix appended to the user ID on the cloud.

Enabled

If an IdP is enabled, it can be used for authentication by the


applications in this account. Otherwise, it cannot be used.
Only the SAML assertions coming from it will be validated
by SAP HANA Cloud Platform.

Note
If nothing else is specified, the default IdP is used for
authentication. Alternatively, you can use a different IdP
using a URL parameter. See Using an IdP Different from
the Default [page 1301].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1297

Field

Description

Only for IDP-initiated SSO

If this checkbox is marked, this identity provider can be


used only for IdP-initiated single sign-on scenarios. The
applications deployed at SAP HANA Cloud Platform cannot
use it for user authentication from their login pages, for
example. Only users coming from links to the application at
the IdP side will be able to authenticate.

Note
This checkbox is always marked if you have selected
Default configuration type in the Local Service Provider
section.

5. In the Attributes tab, configure the user attribute mappings for this identity provider.
User attributes can contain any other information in addition to the user ID.
Default attributes are user attributes that all users logged by this IdP will have. For example, if we know that
"My IdP" is used to authenticate users from MyCompany, we can set a default user attribute for that IdP
"company=MyCompany".
To add a default attribute, proceed as follows:
1. On the Attributes tab page, choose Add Default Attribute.
2. Enter the attribute name and attribute value in the respective fields.
Assertion-based attributes define a mapping between user attributes sent by the identity provider (in the
SAML assertion) and user attributes consumed by applications on SAP HANA Cloud Platform (principal
attributes). This allows you to easily map the user information sent by the IdP to the format required by your
application without having to change your application code. For example, the IdP sends the first name and last
name user information in attributes named first_name and last_name. You, on the other hand, have a
cloud application that retrieves user attributes named firstName and lastName. You need to define the
relevant mapping in the Assertion-Based Attributes section so the application uses the information from that
identity provider properly.

Note
There are no default mappings of assertion attributes to principal attributes. You need to define those
if you need them.
The attributes are case sensitive.
To add an assertion-based attribute, proceed as follows:
1. On the Attributes tab page, choose Add Assertion-Based Attribute.
2. In Assertion Attribute, enter the name of the attribute contained in the SAML 2.0 assertion issued by the
IdP. When this IdP logs a user on SAP HANA Cloud Platform, the value of this attribute is mapped as the
value for the specified user attribute (Principal Attribute).
3. In Principal Attribute, enter the name of the user attribute on SAP HANA Cloud Platform.

1298

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

In the screenshot above, all users authenticated by this IdP will have an attribute company="ITelO Corp.". In
addition, several attributes from the SAML assertion will also be added to authenticated users. For some of
these, the attribute name on the cloud is the same as the name provided by the IdP. Others are mapped to a
different name.
For more information about using user attributes in your application, see Enabling Authentication [page 1213].
6. In the Groups tab, configure the groups associated with this IdP's users.
Groups that you define on the cloud are later mapped to Java EE application roles. As specified in Java EE, in
the web.xml, you define the roles authorized to access a protected resource in your application. You therefore
define the groups that exist there and the roles to which each group is mapped via the Groups tab in the
cockpit. For each different IdP, you then define a set of rules specifying to which groups a user logged by this
IdP belongs.
For more information about configuring groups, see Managing Groups and Roles [page 1282].

Note
You must have defined groups in advance before you define default or assertion-based groups for this IdP.
Default groups are the groups all users logged by this IdP will have. For example, all users logged by the
company IdP can belong to the group "Internal".
To add a default group, proceed as follows:
1. On the Groups tab page, choose Add Default Group.
2. From the dropdown list that appears, choose the required group.
Assertion-based groups are groups determined by values of attributes in the SAML 2.0 assertion. For
example, if the assertion contains the attribute "contract=temporary", you may want all such users to be
added to the group "TEMPORARY".
To add an assertion-based group, proceed as follows:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1299

1. On the GROUPS tab page, choose Add Assertion-Based Group. A new row appears and a new mapping
rule is now being created.
2. Enter the name of the group to which users will be mapped. Then define the rule for this mapping.
3. In the first field of the Mapping Rules section, enter the SAML 2.0 assertion attribute name to be used as
the mapping source. In other words, the value of this attribute will be compared with the value you specify
(in the last field of Mapping Rules).
4. Choose the comparison operator.
Choose Equals if you want the value of the SAML 2.0 assertion attribute to match exactly the string
you specify. Note that if you want to use more sophisticated relations, such as "starts with" or
"contains", you need to use the Regular expression option.
Choose Regular expression if you want to specify more sophisticated matching rules. You can use all
regular expression rules described in the Java RegEx API .
Example 1: You want to add authenticated SAP employees to group Employees. And SAP employees
are users with e-mail address ending with sap.com. Hence, you choose the mapping rule to be email,
matched using the following regular expression:
.*@sap.com$
Example 2: You want all users with name starting with admin to be added to group Administrators.
Hence, you choose the mapping rule to be userid, matched using the following regular expression:
^(admin).*
5. In the last field of Mapping Rules, enter the value with which you compare the specified SAML 2.0
assertion attribute.
6. You can specify more than one mapping rule for a specific group. Use the plus button to add as many
rules as required. In this case, mapping is based on a logical AND operation for all rules, that is, if one of
your rules applies, the user is added to the group.

In the image above, all users logged by this IdP are added to the group Government. The users that have an
arrtibute corresponding to their department name will also be assigned to the respective department groups.

1300

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.4.3 Using an IdP Different from the Default

Context
You can define more than one identity provider for your account. There is always the default IdP. Initially, SAP ID
service is the default IdP but you can change that after you add another IdP.
If you want to use an IdP different from the default one, you can do so by requesting your application with a
special request parameter saml2idp with value the desired IdP name. For example:
https://<app name>.hana.ondemand.com/index.jsp?saml2idp=<idp name>

1.8.3.3.5

ID Federation with a SAP Cloud Identity Tenant

You can register an SAP Cloud Identity tenant as an identity provider for your account.

Prerequisites
You have defined service provider settings for the SAP HANA Cloud Platform account. See
You have chosen a custom local provider configuration type for this account (using
Service Provider

Configuration Type

Cockpit

Trust

Local

Custom )

Context
SAP Cloud Identity provides identity management for SAP HANA Cloud Platform applications. You can register an
SAP Cloud Identity tenant as an identity provider for the applications in your SAP HANA Cloud Platform account.

Note
If you add an SAP Cloud Identity tenant already configured for trust with the same service provider name, the
existing trust configuration on the SAP Cloud Identity tenant side will be updated. If you add an SAP Cloud
Identity tenant configured for trust with SAP HANA Cloud Platform with a different service provider name, a
new trust configuration will be created on the SAP Cloud Identity tenant side.

Note
When you remove an SAP Cloud Identity tenant as trusted identity provider, the relevant service provider
configuration in the SAP Cloud Identity tenant is preserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1301

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
Make sure that you have selected the relevant global account to be able to select the right account.
2. Choose the

Security

Trust

section.

3. Choose the Trusted Identity Provider tab page. Proceed here depending on one of the following cases:
You have an SAP Cloud Identity tenant registered for your current SAP customer user (s-user). You want
to add the tenant as an identity provider.
1. Click Add SAP Cloud Identity Tenant.
2. Choose the required SAP Cloud Identity tenant and save the changes.

In this case, the trust will be established automatically upon registration on both the SAP HANA Cloud
Platform and SAP Cloud Identity tenant side. See Getting Started with SAP Cloud Identity
You want to add an SAP Cloud Identity tenant not related to your SAP user.
In this case, you need to register the SAP Cloud Identity tenant as any other type of identity provider. This
means you need to set up trust settings on both the SAP HANA Cloud Platform and the SAP Cloud
Identity tenant side. See Integration.

Results
The SAP Cloud Identity tenant appears in the list of SAML identity providers. You can now administrate further the
SAP Cloud Identity tenant by opening SAP Cloud Identity Admin Console (hover over the registered SAP Cloud
Identity tenant and click SAP Cloud Identity Admin Console). You can manage the registered SAP Cloud Identity
tenant as any other registered identity provider.

Note
It will take about 2 minutes for the trust configuration with the SAP Cloud Identity tenant to become active.

Note
Each SAP HANA Cloud Platform account is a separate service provider in the SAP Cloud Identity tenant.

1302

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Tip
If you need each of your SAP HANA Cloud Platform applications to be represented by its own service provider,
you must create and use a separate account for each application. See Creating Accounts [page 18].

Related Information
SAP Cloud Identity Service
ID Federation with the Corporate Identity Provider [page 1292]
SAP Cloud Identity service Onboarding Kit for SAP HANA Cloud Platform Customers and Partners (SAP
Community Network)

1.8.3.3.6

Using an On-Premise User Store

If you already have an existing on-premise system with a populated user store, you can configure SAP HANA
Cloud Platform applications to use that on-premise user store. This approach is similar to implementing identity
federation with a corporate identity provider. In that way, applications do not need to keep the whole user
database, but request the necessary information from the on-premise system.

Context
Applications can use the on-premise system to:
check credentials
search for users
retrieve user details
retrieve information about the groups a specific user is a member of. You can use this information for user
authorizations. See Managing Roles [page 1282].
You can use two types of on-premise user store:
SAP Single Sign-On with a SAP NetWeaver Application Server for Java System - the applications on SAP
HANA Cloud Platform connect to the SAP on-premise system using Destination API (and, if necessary, SAP
HANA Cloud Connector), and make use of the user store there.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1303

Microsoft Active Directory - this is an LDAP server that can serve as an on-premise user store. The
applications on SAP HANA Cloud Platform connect to the LDAP server using SAP HANA cloud connector, and
make use of the user store there.

1304

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Alternatively to the above scenarios, you can implement identity federation with a SAP Cloud Identity tenant,
where the tenant is configured to use an on-premise user store. See:
ID Federation with a SAP Cloud Identity Tenant [page 1301]
SAP Cloud Identity Service documentation: Configure Connection to a Corporate User Store

Related Information
Using an SAP System as an On-Premise User Store [page 1305]
Using Microsoft Active Directory as an On-Premise User Store [page 1308]

1.8.3.3.6.1 Using an SAP System as an On-Premise User Store


Overview
You can configure applications running on SAP HANA Cloud Platform to use a user store of an SAP NetWeaver
(7.2 or higher) Application Server for Java system and a SAP Single Sign-On system. That way SAP HANA Cloud
Platform does not need to keep the whole user database, but requests the necessary information from an onpremise system.

Prerequisites
You have installed the SDK.
You have set up the SDK location and landscape host.
You have set up the console client.
For more information, see Installing the SDK [page 34].
You have a SAP NetWeaver 7.2 or higher Application Server for Java system
You have installed and deployed federation software component archive (SCA) from SAP Single Sign-On
(SSO) 2.0.
For more information, see Downloading and Installing the Federation Software.

1. Deploy the Application


When deploying the application, you have to set system properties of the application VM. For more information,
see Configuring VM Arguments [page 1105].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1305

The properties are the following:


Table 385:
System Property

Value

Description

com.sap.cloud.security.um.u
ser_provider_name

onpremise

This property specifies what user pro


vider the application VM uses.

com.sap.cloud.security.um.d
estination_name

<on-premise_destination_name>

This property specifies the destination


used by the on-premise user provider for
the connection to the on-premise sys
tem. For more information about the
destination, see Destinations [page 281].

Note
The WAR file that you are using as a source during the deployment has to be protected declaratively or
programmatically. For more information, see Enabling Authentication [page 1213].

Example
neo deploy --host hana.ondemand.com --account myacc --application myapp --source
samples/deploy_war/example.war --user mymail@example.com
--vm-arguments "-Dcom.sap.cloud.security.um.user_provider_name=onpremise Dcom.sap.cloud.security.um.destination_name=mydestination"

Note
The VM arguments passed using this command will have effect only until you re-deploy the application.

2. Configure the On-Premise System


Context
The on-premise system is an AS Java with a deployed SCA from SAP Single Sign-On (SSO) 2.0. For the
configuration of the on-premise AS Java system, proceed as follows:

Procedure
1. Configure a service user with SCIM_READONLY role.
For more information about the role assignment process, see Assigning Principals to Roles or Groups.
2. If necessary, set the policy configuration to use the appropriate authentication method.

1306

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You can use the following methods of authentication:


Basic authentication
The on-premise AS Java system is configured to use basic authentication by default. That means the
sap.com/tc~sec~scim~server*scim_v1 policy configuration is set to use basic Web template by
default.
Client certificate authentication
For client certificate authentication, you need to update the sap.com/tc~sec~scim~server*scim_v1
policy configuration to use client_cert Web template. In addition, you have to configure the on-premise
system to use the client certificate properly. For more information about the on-premise system
configuration, see Using X.509 Client Certificates on the AS Java.
For more information about the policy configuration, see Editing the Authentication Policy of AS Java
Components.
3. If your user does not exist in the on-premise system, create a technical user.
For more information, see Creating a Technical User.

3. Configure the Destination to the On-Premise System


For the proper communication with the on-premise AS Java system, you need to configure the destination of the
Java application on SAP HANA Cloud Platform. For more information, see Configuring Destinations from the
Cockpit [page 301].
You have to set the following properties for the destination of the cloud application:
Table 386:
Destination Property

Value

Description

Name

<on-premise_destination_name>

The name of the destination must match


with the value of system property

com.sap.cloud.security.um.d
estination_name.
Type

HTTP

For more information, see HTTP Desti


nations [page 322].

URL

https:// < AS Java Host>:<AS Java


HTTPS Port>/scim/v1/ Or http://
<Virtual host configured in Cloud
Connector>:<virtual Port>/scim/v1/

The URL to the on-premise AS Java sys


tem if it is exposed via reverse proxy. Or
in case the on-premise systems is ex
posed via HANA Cloud Connector the
virtual URL configured in Cloud Connec
tor. In this case, the configured protocol
should be http as the connectivity serv
ice is using secure tunneling to the onpremise system.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1307

Destination Property

Value

Proxy Type

Internet or OnPremise

Description

Internet
If you use an internet proxy, you
have to make sure that the onpremise system is accessible from
the application VM.

OnPremise
If you use an on-premise proxy, you
have to install SAP HANA cloud
connector and configure a tunnel
from the destination URL to the onpremise system. For more informa
tion about SAP HANA cloud con
nector, see SAP HANA Cloud Con
nector [page 434].

Authentication

BasicAuthentication or
ClientCertificateAuthentication

For the configuration of such an authen


tication, you need to specify the creden
tials of the service user from the onpremise system. For more information
about the destination configuration, see
HTTP Destinations [page 322].

User

<user name>

This property is used for basic authenti


cation only, and it specifies the name of
the service user in the on-premise AS
Java system.

Password

<password>

This property is used for basic authenti


cation only, and it specifies the service
user's password.

1.8.3.3.6.2 Using Microsoft Active Directory as an On-Premise


User Store
You can use Microsoft Active Directory as an on-premise LDAP server providing a user store for your SAP HANA
Cloud Platform applications.

Prerequisites
You have installed the SDK.
You have set up the SDK location and landscape host.
You have set up the console client.
For more information, see Installing the SDK [page 34].
You have installed and deployed SAP HANA cloud connector. See Installing the Cloud Connector [page 436]

1308

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Context

1. Deploy the Application


When deploying the application, you have to set system properties of the application VM. For more information,
see Configuring VM Arguments [page 1105].
The properties are the following:
Table 387:
System Property

Value

Description

com.sap.cloud.security.um.u
ser_provider_name

onpremise

This property specifies what user pro


vider the application VM uses.

com.sap.cloud.security.um.d
estination_name

<on-premise_destination_name>

This property specifies the destination


used by the on-premise user provider for
the connection to the on-premise sys
tem. For more information about the
destination, see Destinations [page 281].

Note
The WAR file that you are using as a source during the deployment has to be protected declaratively or
programmatically. For more information, see Enabling Authentication [page 1213].

Example
neo deploy --host hana.ondemand.com --account myacc --application myapp --source
samples/deploy_war/example.war --user mymail@example.com
--vm-arguments "-Dcom.sap.cloud.security.um.user_provider_name=onpremise Dcom.sap.cloud.security.um.destination_name=mydestination"

Note
The VM arguments passed using this command will have effect only until you re-deploy the application.

2. Install and Configure SAP HANA Cloud Connector


Create the required destination and configure SAP HANA clolud connector as described in Configuring User Store
in the Cloud Connector [page 499]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1309

1.8.3.3.7

Configuring OAuth 2.0

Register clients, manage access tokens, configure scopes and perform other OAuth configuration tasks.
Prerequisites
You have an account with administrator role in SAP HANA Cloud Platform. See Account Member Roles [page
27].
You have developed an OAuth-protected application (resource server). See Protecting Applications with
OAuth 2.0 [page 1227].
You have deployed the application on SAP HANA Cloud Platform. See Deploying and Updating Applications
[page 973].

Contents:
Registering an OAuth Client [page 1310]
Defining OAuth Scopes [page 1313]
Revoking OAuth Access Tokens [page 1314]
Using a QR Code for Mobile Access [page 1315]
Customizing Corporate Branding [page 1317]

1.8.3.3.7.1 Registering an OAuth Client


To authorize a device to access an OAuth-protected application, you need to register it as a client.

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
2. In the

Security

OAuth

section, go to the Clients tab.

3. Choose Register new Client.

1310

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

4. Enter the client data as required (see the table below).


Field

Description

Name

The client name.

Description

A free-text description of the client.

Application

The application for which you are registering this client. To


be able to register for a particular application, this account

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1311

Field

Description

must be subscribed to it. For more information, see


Managing Subscriptions [page 28]
ID

Required. The ID of the client authorized to access the


resource server running on SAP HANA Cloud Platform. If
you already have a client with a defined ID at the client
device, enter its value here. Otherwise, you can choose
Generate ID and Secret to use a system-generated ID, or
enter a custom value. In that case, you must provide that
value to the user of the client device.

Note
The client ID must be globally unique within the entire
SAP HANA Cloud Platform.
Confidential

If you mark this box, the client ID will be protected with a


password. You will need to supply the password here, and
provide it to the client.

Secret

A secret (password) that allows the authorization server to


authenticate before the client on behalf of the resource
owner (user).
It will also be needed by the client.

Redirect URI

The application URI to which the authorization server will


connect the client with the authorization code.

Token Lifetime

The token lifetime.This value applies to the access token


and authorization code.

Refresh Token Lifetime

The refresh token lifetime.

Translations

Optionally, you can provide translations of the client name


and description for localization purposes. Choose the
Translations button and enter the required language
translation there.

5. Save the new client.

Results
The device with the defined ID will be recognized as a registered client.

1312

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.7.2 Defining OAuth Scopes


Define scopes for your OAuth-protected application to fine-grain the access rights to it.

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
2. In the

Applications

Java Applications

3. For the application, go to the

Security

section, select the OAuth-protected application.


OAuth Scopes

section.

4. Choose New Scope.

5. Enter the scope ID and description.


6. Optionally, if you want to provide localization for different languages, choose Translations and enter the
required data.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1313

7. Save the new scope.

1.8.3.3.7.3 Revoking OAuth Access Tokens


With revoking access tokens, you can immediately reject access rights you have previously granted. You may wish
to revoke an access token if you believe the token is be stolen, for example.
You may wish to revoke an access token if you believe the token is be stolen, for example. With revoking access
tokens, you can immediately reject access rights you have previously granted.
There are two UIs for revoking access tokens:
The Cockpit - an administrator user may use the Cockpit to revoke tokens on behalf of different end users
The end user UI - an end user may access its tokens (and no other user's) and revoke the required using that
UI
Using the Cockpit (for administrators):
1. In your Web browser, open the Cockpit.
2. Go to the

Security

Authorizations

Token

section.

3. Search for access tokens either by client ID or by user ID.


4. Choose Revoke for the required tokens.

Using the End User UI:


1. In the Cockpit, choose the

Security

OAuth

section, and go to the Branding tab.

2. Click the End User UI link.You are now opening the end user UI in a new browser window. You can see all
access tokens issued for the current user.
3. Choose the Revoke button for the tokens to revoke.

1314

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.7.4 Using a QR Code for Mobile Access


Use a QR code for easier copying of the OAuth authorization code on mobile devices.

Context
When your account is configured for trust with a corporate identity provider (IdP), it is often impossible to connect
to the IdP directly using a personal mobile device. The corporate IdP is often part of a protected corporate
network, which does not allow personal devices to access it. To facilitate OAuth authentication on mobile devices,
you can use the end user UI's QR code generation option. It provides as a scannable QR code the authorization
code sent by the OAuth authorization server.

Procedure
1. In the Cockpit, choose the

Security

OAuth

Branding

section.

2. Click the End User UI link.You are now opening the end user UI in a new browser window.
3. Choose Code.
4. Select the client from the list of registered clients for this user.
5. Select the required scopes.
6. Choose Generate QR Code.
7. Use your mobile device to scan this QR code (prerequisite: you have QR code scanning software installed),
and copy it to your device's clipboard.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1315

8. Paste the code from the clipboard to your mobile application (prerequisite: your mobile application allows you
to paste the authorization code from the clipboard and will send in this case the access token request directly
to the OAuth authorization server).

1316

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.3.3.7.5 Customizing Corporate Branding


You can customize the lookandfeel of the authorization page displayed to end users with your corporate branding.
This will make it easier for them to recognize your organization.

Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
2. Go to the

Security

OAuth

Branding

section.

3. Choose Custom theme and specify the required colors.


4. Upload your custom icon.
5. Save the settings.

Results
The authorization page that end users see contains the company logo and colors you specify. The following image
shows an example of a customized authorization page.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1317

1.8.3.3.8

Principal Propagation to OAuth-Protected


Applications

Propagate users from external applications with SAML identity federation to OAuth-protected applications
running on SAP HANA Cloud Platform. Exchange the user ID and attributes from a SAML assertion for an OAuth
access token, and use the access token to access the OAuth-protected application.

Prerequisites
You have an application external to SAP HANA Cloud Platform. The application is integrated with a third-party
library or system functioning as a SAML identity provider. That application has a SAML assertion for each
authenticated user.

Note
How the external application and its SAML identity provider work together and communicate is outside the
scope of this documentation. They can be separate applications, or the external application may be using a
library integrated in it.

Note
If you are using a separate third-party identity provider system for this scenario, make sure you have
configured correctly trust between the external application and the identity provider system. Refer to the
identity provider vendor's documentation for details.

1318

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

You have configured SAP HANA Cloud Platform for identity federation. See Configure SAP HANA Cloud
Platform as a Local Service Provider [page 1293].
You have developed an OAuth-protected application. See Protecting Applications with OAuth 2.0 [page 1227].
You have deployed the OAuth-protected application at SAP HANA Cloud Platform. See Deploying and
Updating Applications [page 973].

Context
This scenario follows the SAML 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants
specification. The scenario is based on exchanging the SAML (bearer) assertion from the third-party identity
provider for an OAuth access token from the SAP HANA Cloud Platform authorization server. Using the access
token, the external application can access the OAuth-protected application.
The graphic below illustrates the scenario implemented in terms of SAP HANA Cloud Platform.

1. An external application has a SAML assertion on behalf of a successfully logged user. The application needs to
proparate that user and its relevant information (attributes, privileges, and so on) to the OAuth-protected
application running at SAP HANA Cloud Platform.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1319

2. The external application passes the SAML assertion to SAP HANA Cloud Platform.
To access the OAuth-protected application at SAP HANA Cloud Platform, however, the external application
needs an OAuth 2.0 access token, not a SAML assertion.
3. If the SAML assertion contains all required information (see the procedure below) SAP HANA Cloud Platform
generates the corresponding access token. In this way, the external application can act on behalf of the user
authenticated by the identity provider, within its granted privileges at SAP HANA Cloud Platform, and within
the time limits of the access token.
4. The external application passes the received access token to the OAuth-protected application at SAP HANA
Cloud Platform.
5. If the access token is correct and the user has the required privileges, the OAuth-protected application
returns the requested resources.

Procedure
1. Configure SAP HANA Cloud Platform for trust with the SAML identity provider. See Configure Trust to the
SAML Identity Provider [page 1295].
2. Register the external application as an OAuth client in SAP HANA Cloud Platform. See Registering an OAuth
Client [page 1310].
3. Make sure the SAML (bearer) assertion that the external application presents contains the following
information:
Table 388:
SAML Assertion Element

Value Description

Name ID

The authenticated user ID.

Example

<saml:NameID
Format="urn:oasis:names:
tc:SAML:1.1:nameid
format:unspecified"
xmlns:saml="urn:oasis:na
mes:tc:SAML:
2.0:assertion">p12356789
</saml:NameID>

1320

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

SAML Assertion Element

Value Description

Example

Audience

The local service provider name for


your SAP HANA Cloud Platform ac
count (in
Trust

Cockpit

Security

Local Service Provider

Provider Name

Local

).

If you are using the default identity pro


vider configuration for your account,
take the audience value from the table

<saml:Audience>myLocalPr
ovider</saml:Audience>
<saml:Audience>https://
us1.hana.ondemand.com/</
saml:Audience>
<saml:Audience>ap1.hana.
ondemand.com</
saml:Audience>

below.
Table 389:
Landscape Descrip

Required

Host

Audience

tion

Value
hana.on

Productive

https://

HNR

landscape,

netwea

mand.com

data cen

H\r I6:|B

ter Europe

mand.com

ap1.hana.o

Productive

ap1.hana.o

nde

landscape,

nde

mand.com

data cen

mand.com

ter AsiaPasific
(Australia)
https://

Productive

https://

us1.hana.o

landscape,

us1.hana.o

nde

data cen

nde

mand.com

ter United

mand.com

States (US

East)
hana

Trial land

https://

H^roJ6z|biw

scape

nwtrial.on

mand.com

HNR
mand.com

See Landscape Hosts [page 32].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1321

SAML Assertion Element

Value Description

Example

Issuer ID

The issuer must have as value the


OAuth client ID registered at SAP
HANA Cloud Platform (in
Security
client>

Issuer Certificate

OAuth
Client ID

Cockpit

Clients

<your

<saml:Issuer
Format="urn:oasis:names:
tc:SAML:2.0:nameidformat:entity"
xmlns:saml="urn:oasis:na
mes:tc:SAML:
2.0:assertion">myClientI
D
</saml:Issuer>

).

The identity provider signing certificate

Sample Code

stored in the trust configuration of HCP


for this identity provider (in
Security
Provider
General
(Optional) User Attributes

Trust

Cockpit

Trusted Identity

<ds:X509Certificate>
</
ds:X509Certificate>

<your identity provider


Signing Certificate

).

The attributes that will be assigned to


the SAP HANA Cloud Platform user.

<Attribute Name="mail">
<AttributeValue
xmlns:xs="http://
www.w3.org/2001/
XMLSchema"
xmlns:xsi="http://
www.w3.org/2001/
XMLSchema-instance"
xsi:type="xs:string">tes
t@sap.com
</AttributeValue>
</Attribute>
<Attribute
Name="first_name">
<AttributeValue
xmlns:xs="http://
www.w3.org/2001/
XMLSchema"
xmlns:xsi="http://
www.w3.org/2001/
XMLSchema-instance"
xsi:type="xs:string">Jon
</AttributeValue>
</Attribute>

See the SAML Assertion Format

specification for more information.

4. In the code of the OAuth-protected application, you can retrieve the user attributes using the relevant SAP
HANA Cloud Platform API. See Working with User Profile Attributes [page 1223].

1322

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.8.4 Securing HTML5 Applications


The security guide provides an overview of the security-relevant information that applies to HTML5 applications.

Related Information
Authentication [page 1323]
Authorization [page 1323]
Accessing REST Services [page 1324]
Accessing On-Premise Systems [page 1324]
Protecting Applications from Cross-Site Scripting (XSS) [page 1324]
Protecting from Cross-Site Request Forgery (CSRF) [page 1325]

1.8.4.1

Authentication

SAP HANA Cloud Platform uses the Security Assertion Markup Language (SAML) 2.0 protocol for authentication
and single sign-on.
By default, the SAP HANA Cloud Platform is configured to use the SAP ID service as identity provider (IdP), as
specified in SAML 2.0. You can configure a trust relationship to your custom IdP to provide access to the cloud
using your own user database.
HTML5 applications are protected with SAML2 authentication by default. For publicly accessible applications, the
authentication can be switched off. For information about how to switch off authentication, see Authentication
[page 1047].

1.8.4.2

Authorization

HTML5 applications may be protected by permissions.


Permissions for an HTML5 application are defined in the application descriptor file. For more information about
how to define permissions for an HTML5 application, see Authorization [page 1048].
Permissions defined in the application descriptor are only effective for the active application version. To protect
non-active application versions, the default permission NonActiveApplicationPermission is defined by the
system for every HTML5 application.
To assign users to a permission of an HTML5 application, a role must be assigned to the corresponding
permission. As a result, all users who are assigned to the role get the corresponding permission. Roles are not
application-specific but can be reused across multiple HTML5 applications. For more information about creating
roles and assigning roles to permissions, see Managing Roles and Permissions [page 1177].

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1323

Note
Keep in mind that permissions defined for an HTML5 application can only protect the static resources of that
application. Each REST service, which is connected to this application must implement its own authentication
and authorization concept.

1.8.4.3

Accessing REST Services

When accessing a REST service from an HTML5 application, a new connection is initiated by the HTML5
dispatcher to the service that is defined in the corresponding HTTP destination.
To prevent that security-relevant headers or cookies are returned from the REST service to the client, only
whitelisted headers are returned to the client. While some headers are whitelisted per default, additional headers
can be whitelisted in the application descriptor file. For more information about how to whitelist additional
headers, see Header Whitelisting [page 1058].
Cookies that are retrieved from a REST service response are stored by the HTML5 dispatcher in an HTTP session
that is bound to the client request. The cookies are not returned to the client. If a subsequent request is initiated
to the same back-end, the cookies are added by the dispatcher to the subsequent request. Only those cookies are
added that are valid for the request in the sense of correct domain and expiration date. When the client session is
terminated, all associated cookies are removed from the HTML5 dispatcher.

1.8.4.4

Accessing On-Premise Systems

To access a system that is running in an on-premise network, you can set up an SSL tunnel from your on-premise
network to the SAP HANA Cloud Platform using the SAP HANA Cloud Connector.
For more information about setting up the Cloud connector, see the Cloud Connector Operator's Guide.

Related Information
Cloud Connector Operator's Guide [page 524]

1.8.4.5

Protecting Applications from Cross-Site Scripting


(XSS)

Cross-site scripting (XSS) is one of the most common types of malicious attacks on web applications.
If an HTML5 application is connected to a REST service, the corresponding REST service must take measures to
protect the application against this type of vulnerabilities. For REST services implemented on the SAP HANA
Cloud Platform a common output encoding library may be used to protect applications. For more information

1324

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

about XSS protection on the SAP HANA Cloud Platform, see Protecting from Cross-Site Scripting (XSS) [page
1243].

1.8.4.6

Protecting from Cross-Site Request Forgery (CSRF)

Cross-Site Request Forgery (CSRF) is another common type of attack on web applications.
If an application connects to a REST service, the corresponding REST service must take measures to protect
against CSRF. For REST services implemented on the SAP HANA Cloud Platform a CSRF prevention filter may be
used in the corresponding REST service. For more information about CSRF protection on the SAP HANA Cloud
Platform,see Protecting from Cross-Site Request Forgery [page 1235].

Related Information
ID Federation with the Corporate Identity Provider [page 1292]
Security Testing on the Cloud (with a Local Identity Provider) [page 1273]

1.9

Get Support

If you have questions or encounter an issue while working with SAP HANA Cloud Platform, you can address them
as described below.
Depending on your account, you can use the following support media:
Table 390:
Customer and Partner Accounts

Developer Accounts
Developer Community

Developer Community

SAP Support Portal


and file an incident.)

(An S-user is required to log in

To report an incident (issue), follow the steps below.

1. Log into the SAP Support Portal


1. Open SAP Support Portal

2. Choose Report an Incident.


The SAP ONE Support Launchpad opens.
3. Perform a search to check whether a similar incident was already reported.
4. If you still need to report an incident, choose Contact SAP Support.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1325

5. In the Customer Number field, enter the number related to your SAP HANA Cloud Platform contract.
6. In the S-User ID field, enter your S-user (example: s1234567890). A form opens where you fill in details about
the incident.

2. Provide Incident Details


1. Select language, set priority of the incident and enter a subject. Note that if you set a high or very high priority,
you have to also describe the business impact of the incident.
2. To help the support staff process your issue as fast as possible, please provide the following information in
the Description field:
Landscape and account name. In the cockpit, open the affected account, and copy the URL.
Java application name and URL (only when the problem is related to Java applications). In the cockpit,
open the respective Java applications Overview page.
Database or schema ID (only when the problem is related to a database system or schema). In the
cockpit, see the ID column by navigating to

Persistence

Databases & Schemas .

3. From the Installation dropdown list, select HANA CLOUD.

Note
You need to select the correct installation type, that is, HANA CLOUD, so that the correct support SLA is
applied to your case.
4. From the System dropdown list, select the affected system.
5. From the Component dropdown list, select the component name of the area which fits best to your issue.
Selecting the right component will direct your issue to the corresponding support team. To check the
complete list of components, see SAP Note 1888290 .
6. Enter the steps to reproduce the issue and if necessary, add some attachments.
7. Optionally, define contact(s) apart from the reporter, who is filled in automatically.
8. When ready, choose Submit to create the incident.

Note
If you have problems creating and sending an incident, or your ticket is not processed as fast as you need,
contact the 24/7 phone hotlines. See SAP Note 560499 .

Additional Resources
Support Information (Eclipse IDE) [page 1327]
Platform Updates and Notifications [page 1327]

1326

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

1.9.1 Support Information (Eclipse IDE)


The Eclipse tools come with a wizard for gathering support information in case you need help with a feature or
operation (during deploying/debugging applications, logging, configurations, and so on).

Context
The wizard collects the information in a ZIP file, which can be later sent to SAP support. This way, SAP support
developers can get better understanding of your environment and process the issue faster.

Procedure
1. From the Eclipse IDE, choose

Help

Collect Support Information .

2. The launched wizard lists the default components to be collected, depending on the tools you have installed. If
you need SAP support to take a look at specific resources, expand the Additional Data section and select the
relevant items.

Note
If you select Screenshot, your currently open Eclipse windows and views will be snapped as a picture and
added to the ZIP file . Make sure you don't reveal sensitive information.
3. In the File Name field, specify the ZIP file name and location.
4. Choose Finish.

Next Steps
You can create a support ticket, attach the ZIP file to it and send it to the relevant OSS component. For more
information, see Get Support [page 1325].

1.9.2 Platform Updates and Notifications


SAP HANA Cloud Platform is a dynamic product, which has production releases (updates) every second
regularly.
Thursday. To be aware of the new features delivered every takt, check the Release Notes

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1327

Reasons for Landscape Updates


SAP HANA Cloud Platform landscapes are updated in three cases:
Bi-weekly updates (standard) - each second Thursday, aligned with the contractual obligations of SAP HANA
Cloud Platform to customers and partners. Such updates normally do not affect productive applications but
most often affect the ability to deploy to the platform. Exact details are sent as notification in advance,
together with a notification on completion of the update. During the update, a new platform release is
deployed.
Immediate updates - in case of fixes required for bugs that affect productive application operations, or due to
urgent security fixes. In some cases, this might lead to downtime or application restart, for which the
application groups will receive a notification.
Major upgrades - they happen rarely, in a bigger maintenance window - up to 4 times per year, usually in
Saturdays from 8:00 to 14:00 CET. When such an upgrade is needed, it is communicated one week in
advance.

Subscriptions & Announcements


To receive regular information about landscape downtimes and news, you need to subscribe to the following
mailing list: https://listserv.sap.com/mailman/listinfo/hanacloud-announce

Examples
Example for a notification mail announcing updated EU1 landscape:

1328

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Example for a notification mail announcing network upgrade:

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1329

1.10 Our Response to Your Feedback


This page summarizes how we changed SAP HANA Cloud Platform after receiving your comments from our
feedback form.
The other important changes in the software and documentation are described in the Release Notes

1330

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

July 28, 2016


Table 391:
Documentation
Compute Units [page 959]

Description

Added an additional column describing the values for the -z or --size


console client parameter.

July 14, 2016


Table 392:
Documentation
Compute Units [page 959]

Description

Added links to topics describing how to request additional resources


and how to manage them.

A note is added explaining that for trial accounts only the Lite edition is
available.

May 12, 2016


Table 393:
Documentation
ID Federation with the Corporate Identity Pro
vider [page 1292]

Description

A missing step added in section Configure Trust to the SAML Identity


Provider [page 1295]

Improved the description of assertion-based attributes

Managing Roles [page 1282]

Improved the description of custom roles.

tiles.json [page 1089]

Corrected the sample.

April 28, 2016


Table 394:
Documentation

Description

Deleting a Repository (Cockpit) [page 594]

This topic now includes a link to the reset-ecm-key command with which
you can request a new repository key. This helps avoid deleting a repository
just because you forgot the key.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1331

April 21, 2016


Table 395:
Documentation

Description

HTML5: Getting Started [page 66]

The link to Setting up SAP Web IDE now directly points to the SAP Web IDE
documentation. The link to Installing Eclipse IDE now directly points to the
Eclipse topic.

April 7, 2016
Table 396:
Function

Description

Connecting to SAP HANA Schemas via the

Added a note that you must have created a schema previously to be able to

Eclipse IDE [page 864]

select it in this step.

Table 397:
Documentation

Description

Get Support [page 1325]

Added SAP Note 560499

. You can use it when you need to contact the

24/7 phone hotlines.

March 24, 2016


Table 398:
Function

Description

Monitoring and Logging in the cockpit

A filter in the Configure Loggers dialog box in Java applications allows you to
filter the list by logger name and thereby only show only the loggers that you
are interested in. For more information see Using Logs in the Cockpit [page
1137]

Table 399:
Documentation

Description

Creating an SAP HANA Database from the

Added examples for both productive and trial multitenant database contain

Cockpit [page 757]

ers (MDC).

Connecting to SAP HANA Databases via the

Added a screenshot for the step where you enter your database user name

Eclipse IDE [page 861]

and password.

1332

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Documentation

Description

Connecting to the Remote SAP MaxDB Data

Added the prerequisite that you need the connection details, which you ob

base [page 865]

tained when you opened the database tunnel, to perform the procedure.

Creating an SAP HANA XS Application [page

Added a note that newly created SAP HANA XS applications are only visible

59]

in the cockpit once you have activated them.

(Optional) Installing SAP JVM [page 35]

Updated information on the Visual C++ Runtime. If you use Microsoft Win
dows as your operating system, you need to install the Visual C++ 2010 Run
time before you can use SAP JVM.

Installing SAP Development Tools for Eclipse

Added the field name where you have to enter the URL when you install new

[page 37]

software in Eclipse.

Creating a Project [page 68]

The procedure now reflects the changed behavior of the SAP Web IDE.

Using Custom Header Protection [page 1239]

Added an improved explanation about where to find the XSRF protection fil
ter class and how to use it (no need to instantiate or extend).

February 25, 2016


Table 400:
Function

Description

Connectivity Service

We now display the error code and the reason for connection failure when
you use the Check Connection button in the connectivity destination editor
(in the Cockpit). For more information, see Checking the Availability of a Des
tination (Cockpit) [page 306].

Table 401:
Documentation

Description

Business Services with YaaS [page 942]

Added information about YaaS and SAP HANA Cloud Platform and where
business services reside in the whole picture. There is also an illustration
showing how the different components interact.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1333

February 4, 2016
Table 402:
Documentation

Description

Data Isolation (Java) [page 553]

Added information about multitenancy.

Performance Tips (Java) [page 587]


Testing the Application [page 74]

Added two possible reasons for the error message.

Assigning Destinations for HTML5 Applications

Reorganized topic to contain prerequisites and provide step-by-step instruc

[page 1176]

tions.

Using Java EE 6 Web Profile [page 966]

A new prerequisite has been added to ensure the correct setup of the SAP
HANA Cloud Platform Tools.

Installing the SDK [page 34]

Explained how to proceed after the SDK archive file is downloaded and ex
tracted in more detail.

January 28, 2016


Table 403:
Documentation

Description

Managing Members [page 23]

Added information about new features in the member list:


The names of members are now displayed in addition to their user IDs.

Note
The name of a member is displayed only after the member visits the ac
count for the first time.
Administrators can now send e-mails to members of the account.

Note
The e-mail option is displayed only after this member visits the account
for the first time.
Sending e-mails to members is only possible after the recipient has logged
on to the account.

1334

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

December 3, 2015
Table 404:
Documentation

Description

Adding Container-Managed Persistence With

A section about deploying applications using persistence on the cloud from

JPA (Java EE 6 Web Profile SDK) [page 724]

Eclipse IDE was included.

Adding Application-Managed Persistence With


JPA (Java Web SDK) [page 735]
Adding Persistence With JDBC (Java Web
SDK) [page 746]
Enabling Logout [page 1224]

A new section dedicated to protecting logout resources from cross-site re


quest forgery (CSRF) was added. A confusing section about JavaScript re
source protection was removed.

November 19, 2015


Table 405:
Documentation

Description

Adding Container-Managed Persistence With

A section was added for configuring the persistence.xml file.

JPA (Java EE 6 Web Profile SDK) [page 724]

October 22, 2015


Table 406:
Documentation

Description

ID Federation with the Corporate Identity Pro

The entire content is reworked in several ways:

vider [page 1292]

It is clearer now what a local service provider is and what it is required to


configure it

The separate parts of the content are accessible from the tree

Using the Authorization Management REST API The scope parameters are removed from the example. Scopes are redun
[page 1220]

dant for this scenario and are ignored (based on the OAuth 2.0 client creden
tials flow).

Using Java EE 6 Web Profile [page 966]

SAP HANA Cloud Platform


SAP HANA Cloud Platform

The code sample in section Call the EJB from the JSP was improved.

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1335

Documentation

Description

Installing Java Tools for Eclipse and SDK [page

Links to Updating Java Tools for Eclipse and SDK [page 43] and SAP Devel

33]

opment Tools for Eclipse have been included.

Setting Up SDK Location and Landscape Host

A new step was added to the procedure describing that you need to select

in Eclipse [page 38]

the directory where you have downloaded the JVM.

Adding Container-Managed Persistence With

A new step was added to the Create a Dynamic Web Project and Servlet pro

JPA (Java EE 6 Web Profile SDK) [page 724]

cedure describing that you need to select the Generate web.xml deployment

Adding Application-Managed Persistence With

descriptor checkbox in the Web Module configuration settings.

JPA (Java Web SDK) [page 735]


Adding Persistence With JDBC (Java Web
SDK) [page 746]
Configuring Service Channels [page 470]

A note was added stating that this procedure requires a production SAP
HANA instance and cannot be performed using a trial instance.

1336

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

SAP HANA Cloud Platform


SAP HANA Cloud Platform

Important Disclaimers and Legal Information

Coding Samples
Any software coding and/or code lines / strings ("Code") included in this documentation are only examples and are not intended to be used in a productive system
environment. The Code is only intended to better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and
completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, unless damages were caused by SAP
intentionally or by SAP's gross negligence.

Accessibility
The information contained in the SAP documentation represents SAP's current view of accessibility criteria as of the date of publication; it is in no way intended to be a
binding guideline on how to ensure accessibility of software products. SAP in particular disclaims any liability in relation to this document. This disclaimer, however, does
not apply in cases of wilful misconduct or gross negligence of SAP. Furthermore, this document does not result in any direct or indirect contractual obligations of SAP.

Gender-Neutral Language
As far as possible, SAP documentation is gender neutral. Depending on the context, the reader is addressed directly with "you", or a gender-neutral noun (such as "sales
person" or "working days") is used. If when referring to members of both sexes, however, the third-person singular cannot be avoided or a gender-neutral noun does not
exist, SAP reserves the right to use the masculine form of the noun and pronoun. This is to ensure that the documentation remains comprehensible.

Internet Hyperlinks
The SAP documentation may contain hyperlinks to the Internet. These hyperlinks are intended to serve as a hint about where to find related information. SAP does not
warrant the availability and correctness of this related information or the ability of this information to serve a particular purpose. SAP shall not be liable for any damages
caused by the use of related information unless damages have been caused by SAP's gross negligence or willful misconduct. All links are categorized for transparency
(see: http://help.sap.com/disclaimer).

SAP HANA Cloud Platform


Important Disclaimers and Legal Information

PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.

1337

go.sap.com/registration/
contact.html

2016 SAP SE or an SAP affiliate company. All rights reserved.


No part of this publication may be reproduced or transmitted in any
form or for any purpose without the express permission of SAP SE
or an SAP affiliate company. The information contained herein may
be changed without prior notice.
Some software products marketed by SAP SE and its distributors
contain proprietary software components of other software
vendors. National product specifications may vary.
These materials are provided by SAP SE or an SAP affiliate company
for informational purposes only, without representation or warranty
of any kind, and SAP or its affiliated companies shall not be liable for
errors or omissions with respect to the materials. The only
warranties for SAP or SAP affiliate company products and services
are those that are set forth in the express warranty statements
accompanying such products and services, if any. Nothing herein
should be construed as constituting an additional warranty.
SAP and other SAP products and services mentioned herein as well
as their respective logos are trademarks or registered trademarks
of SAP SE (or an SAP affiliate company) in Germany and other
countries. All other product and service names mentioned are the
trademarks of their respective companies.
Please see http://www.sap.com/corporate-en/legal/copyright/
index.epx for additional trademark information and notices.
Material Number: No external material number

*No external material nu

Você também pode gostar