Escolar Documentos
Profissional Documentos
Cultura Documentos
PUBLIC
Content
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1.6
1.7
1.8
Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1204
Identity and Access Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205
Securing SAP HANA Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Securing Java Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211
Securing HTML5 Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1323
1.9
1.10
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Table 1:
Get Started
Get Productive
Develop
[page 10]
Operations
Configure [page 1099] | Update [page
1119] | Log [page 1129] | Debug [page
986] | Monitor [page 1149] ...
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
Release Notes
Our Response to Your Feedback [page
1330]
84]
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Scenarios
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.
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.
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
11
Mozilla Firefox
Google Chrome
Latest version
Safari
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
To learn about
See
SAPUI5: Read Me First
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
Java
Table 4:
Eclipse IDE
Hello World!
Import
10
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
HTML5
Table 5:
Web IDE
Hello World Tutorial Using SAP Web IDE (recommended) [page 66]
Eclipse IDE
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
11
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.
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
Benefits
Free of charge
Self-service registration
tions
Unlimited period
Restriction
Store
cations
HANA Cloud Portal, SAP Mo
bile Platform, and Gateway as
a Service
Services availa Productive and beta services
ble
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
13
Developer Account
Limitations
Customer Account
Partner Account
1 GB of database storage
tract
1 GB of document storage
base
Registration
For more information, see https:// To join the partner program, sign
hcp.sap.com/pricing.html
representative.
Landscape
hanatrial.ondemand.com
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.
1.2.2.1.2
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.
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.
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
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
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.
1.2.2.2
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]
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
19
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
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.
1.2.2.2.3
Deleting Accounts
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
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
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
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.
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.
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.
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.
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
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.
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.
1.2.2.5
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.
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
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
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.
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
Procedure
1. Open the account in the cockpit and choose Applications Subscriptions
subscriptions to Java 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 Application URLs panel.
To create connectivity destinations, choose Destinations in the navigation area.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
29
1.2.2.6.2
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.
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 .
Roles .
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
Europe
hana.ondemand.com
155.56.128.0/17
us1.hana.ondemand.com
65.221.12.0/24
us2.hana.ondemand.com
206.112.73.0/24
Asia-Pacific (Australia)
ap1.hana.ondemand.com
210.80.140.0/24
hanatrial.ondemand.com
155.56.128.0/17
Tip
Developer accounts have a suffix trial. For example: P1234567890trial.
32
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Account Types [page 12]
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
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]
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
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.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
35
Related Information
Setting Up SAP JVM in Eclipse IDE [page 41]
Updating SAP JVM [page 45]
1.2.3.1.3
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.
1.2.3.1.4
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 .
Help
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.
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
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 .
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.
9. Choose OK.
1.2.3.1.6
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 .
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.
Server
Window
Preferences .
Runtime Environments .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
39
4. Select
SAP
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.
Server
Window
Preferences .
Runtime Environments .
SAP
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.
Server
Window
Preferences .
Runtime Environments .
SAP
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.
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
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
41
Related Information
(Optional) Installing SAP JVM [page 35]
Updating SAP JVM [page 45]
1.2.3.1.8
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.
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
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>
Related Information
Console Client [page 88]
1.2.3.2
If you have already installed and used the SAP HANA Cloud Platform Tools, SDK and SAP JVM, you only need to
update them.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
43
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
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 .
44
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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
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
Help
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.
Related Information
Installing SAP Development Tools for Eclipse [page 37]
46
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1.2.3.3
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.
File
New
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).
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.
7. Choose Finish.
New
Servlet
. Window Create
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.
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
explore-ui5
SAPUI5 controls
authentication
connectivity
persistence-with-ejb
persistence-with-jpa
persistence-with-jdbc
document-store
Sending e-mails
websocket
SAP_Jam_OData_HCP
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
51
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.
1.2.3.4.1
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
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.
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
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].
Help
Eclipse Marketplace .
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 .
File
Import
Maven
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.
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
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
55
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.
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]
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
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
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.
Note
In case you need to develop with SAPUI5, install also
UI development
Next Steps
Creating an SAP HANA XS Application [page 59]
1.2.4.2
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.
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.
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.
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.
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
61
5. Create an XS Project
Procedure
1. In the Project Explorer view, choose
Project
File
New
Project
SAP HANA
Application Development
XS
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.
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
Other
UTF-8
context menu
File
New
File .
File
New
File .
File
New
File .
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 .
File
New
File .
Team
Activate .
The application is now running on the XS engine.
64
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
65
Hello World Tutorial Using SAP Web IDE (recommended) [page 66]
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
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.
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
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
67
) 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
Entry
View Type
Select JavaScript.
View Name
6. Choose Finish.
68
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1.2.5.1.3
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
).
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
69
Deploy
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
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.
1.2.5.2.1
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
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.
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
Related Information
EGit/User Guide
1.2.5.2.3
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.
New
File .
1.2.5.2.4
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
73
1.2.5.2.5
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
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
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.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
75
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
76
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
To learn about
See
Multitenancy scenarios
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
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]
Application
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.
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.
The virtualized hardware resources used by an SAP HANA Cloud Platform application.
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.
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.
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.
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.
78
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Database type
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
Global account
I-R
Table 17:
Infrastructure as a Service (IaaS)
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
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.
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.
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).
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
79
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 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.
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.
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 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.
A markup language which provides a wide-spread protocol for secure authentication and
SSO. SAML is implemented by SAP ID service.
Service provider
Single Sign-On
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's own implementation of a Java Virtual Machine on which the SAP HANA Cloud
Platform infrastructure runs.
Identifier of the consumer account for the current application context. The tenant ID can
be used to distinguish data of different application consumer accounts.
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.
1.3
Tools
Table 19:
Tool
Description
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.
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
javadoc
repository
samples
server
tools
licenses.txt
readme.txt
sdk.version
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.
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]
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.
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.
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]
86
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
87
Related Information
https://help.hana.ondemand.com/webide/frameset.htm
Related Information
Building Java Web Applications with Maven
Working with the "Neo" Maven Plugin
88
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Table 20:
To learn more about
See
Opening the tool and working with the commands and param
eters
1.3.6.1
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>
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
91
1.3.6.2
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.
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
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.
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.
Type
Description
command
String
argLine
String
pid
Name
exitCode
Name
errorMsg
String
com.sap.jpaas.infrastructur
e.console.exception.Command
Exception
commandOutput
String
commandErrorOutput
String
result
Object
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.
"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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
95
1.3.6.4
Table 22:
Group
Commands
Local Server
Deployment
Logging
Monitoring
Keystore
Connectivity
96
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Group
Commands
Persistence
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]
Subscription Management
HANA XS SAML2
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
System
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
97
Group
Commands
Extensions
1.3.6.4.1
add-ecm-tenant
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
-n, --name
Type: string
-t, --tenant
Tenant alias
Type: string
-k, --key
Type: string
98
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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
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
Type: string
-e, --custom-domain
-i, --application-url
The access point of the application on SAP HANA Cloud Platform default domains
(hana.ondemand.com, etc.)
-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.
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
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
Type: string
-m, --platform-domain
Acceptable values:
svc.hana.ondemand.com
cert.hana.ondemand.com
Example
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
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
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.
Required
Use your e-mail, SAP ID, or user name
-u, --user
Type: string
--db-password
--db-user
Table 28:
Optional
-s, --data-source
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
Parameters
To list all parameters available for this command, execute neo help bind-domain-certificate in the
command line.
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
-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.
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
Note
The host must be on the productive landscape.
-i, --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
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
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
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.
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
Example
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
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.
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
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
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.
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.
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
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
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
111
Description
all
Caution
The list of cloned configurations might be extended in the
future.
trust
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.
Cloning Option
Description
destinations
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
Type: string
-U, --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
Type: URL. For acceptable values see Landscape Hosts [page 32]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
113
Optional
-W, --warning
Default: 50
Type: string
-C , --critical
Default: 60
Type: string
-w, --overwrite
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.
Parameters
Table 42:
Required
-a, --account
Account name
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
Type: string
--db-user
Password of the database user used to access the ASE database (op
tional, queried at the command prompt if omitted)
--db-size
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
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
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.
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
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
117
Required
-i, --id
ASE database ID
Type: string
--db-user
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
118
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Required
-n, --name
Type: string
-k, --key
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.
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
Type: string
-n, --name
Type: string
-O, --object-name
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.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
121
Optional
-w, --overwrite
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.
Related Information
JMX Checks [page 1156]
Monitoring Java Applications [page 1149]
122
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
123
Required
-i, --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
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.
Table 51:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
Type: string
Table 52:
Optional
-n, --name
Unique identifier of the SSL host. If not specified, 'default' value is set.
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
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].
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
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
Example
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.
Parameters
Table 54:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user
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
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>
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
--silent
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.
Parameters
Table 58:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
--silent
Example
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>
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
Table 61:
Optional
--silent
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.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
--name
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
131
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
-n, --name
Type: string
132
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Required
-k, --key
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.
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
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
Type: string
-n, --name
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.
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
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
135
Parameters
Table 67:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user
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
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.
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
Type: string
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
Type: string
Table 70:
Optional
-s, --silent
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
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
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
Type: string
-n, --name
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.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-n,--name
Type: string
-u, --user
Type: string
Table 73:
Optional
-b, --application
Application name
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
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
-i, --id
Type: string
140
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Type: string
Table 75:
Optional
-f, --force
Default: off
Type: switch, takes no value
--silent
Default: off
Type: switch, takes no value
Example
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>
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: 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
Type: string
Table 77:
Optional
Command-specific parameters
142
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Optional
--connections
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.
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.
-j, --java-version
-m, --minimum-processes
Default: 1
-M, --maximum-processes
Default: 1
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
143
Optional
-V, --vm-arguments
-z, --size
--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.
Optional
--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
--compression-min-size
Defines the number of milliseconds to wait for the request URI line to be presented after
accepting a connection.
Default: 20000
--max-threads
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
145
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.
Parameters
Table 78:
Required
-s, --source
Source for deployment (comma separated list of WAR files or folders containing one or
more WAR files)
-l, --location
Example
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.
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
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
Type: string
Table 81:
Optional
-i, --applicationprocess-id
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.
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
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
Type: string
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
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
Type: string
-n, --name
150
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Table 84:
Optional
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>
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
151
Required
-n, --name
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.
Parameters
Table 87:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
153
Required
-h, --host
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
Type: string
Example
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.
Table 89:
Required
-a, --account
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-n,--name
Type: string
-u, --user
Type: string
Table 90:
Optional
-b, --application
Application name
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
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
156
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Required
-k, --key
Type: string
-n, --name
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
Type: string
-q, --newkey
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
157
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
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
Type: string
158
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Table 94:
Optional
-i, --applicationprocess-id
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
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>
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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.
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
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
Type: string
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
161
Required
-n, --name
Type: string (It can contain alphanumerics, '.', '-' and '_')
-d,--certificatedistinguished-name
Allowed attributes:
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.
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
Type: string
-h, --host
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
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
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.
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
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
165
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].
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
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
166
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Type: string
--technical-user-id
-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>
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].
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
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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.
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
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
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
169
Required
-u, --user
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.
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].
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.
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
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
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
171
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
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
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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.
Required
-u, --user
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.
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].
Parameters
To list all parameters available for this command, execute neo help hcmcloud-enable-role-provider in
the command line.
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
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
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
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.
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
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
175
Required
-h, --host
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
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.
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.
Table 109:
Required
-l, --location
Type: string
Note
The file size must not exceed 500 KB.
-a, --account
-h, --host
-p, --password
Type: string
-u, --user
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
177
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
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
Type: string
178
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
Type: string
Note
The file size must not exceed 100 KB.
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
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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.
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
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
181
Required
-h, --host
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
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.
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
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
Type: string
-s, --source
A comma-separated list of file locations, pointing to WAR files, or folders containing them.
Acceptable values:
replace-binaries
restart-runtime
reprovision-runtime
Table 114:
Optional
--connections
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.
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
Default: 8009
--http-non-proxy-hosts
--http-port
Default: 8080
--http-proxy-host
--http-proxy-port
--https-port
Default: 8443
--https-proxy-host
--https-proxy-port
--jmx-port
com.sun.management.jmxremote.port)
Default: 1717
-l, --location
Related Information
Deploying Locally with the Console Client [page 981]
184
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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]
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
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
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.
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
Type: string
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
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
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
188
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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>
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
Type: string
Example
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.
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
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
Type: string
Example
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>
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
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
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.
Parameters
Table 125:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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.
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
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
Type: string
Example
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.
Parameters
Table 128:
Optional
(Optional) Database ID
-i, --id
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)
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.
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
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
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>
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
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
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.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
Type: string
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
199
Table 137:
Optional
-b, --application
Application name
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.
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
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
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>
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
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
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.
Parameters
To list all parameters available for this command, execute neo help list-runtimes in the command line.
Table 140:
Required
-u, --user
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
203
Table 141:
Required
-u, --user
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
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
Example
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.
Parameters
Table 143:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
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>
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
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
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.
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
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
Type: string
Example
Related Information
create-ssl-host [page 124]
Create an SSL Host [page 1187]
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
Type: string
-h, --host
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.
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
Type: string
-h, --host
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
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --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
Type: string
210
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Table 151:
Optional
--background
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.
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,
--application
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h,
--host
Type: URL, for acceptable values see Landscape Hosts [page 32]
--localpath
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,
--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.
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].
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
213
Required
-u, --user
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
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
Type: string
-e, --custom-domain
214
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
215
Required
-h, --host
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
Type: string
-m, platform-domain
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.
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
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
Type: string
-n, --name
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>
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
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
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.
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
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
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
Default: none
Type: string (hexadecimal sequence of 2 to 40 characters)
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.
Table 160:
Required
-a, --account
Account name
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-i, --id
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
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
Type: string
--service-name
--system
The SAP HANA service to be restarted. You can choose between the following values:
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
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
Type: string
--silent
Type: boolean
Table 162:
Optional
--output
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.
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
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
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]
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: URL. For acceptable values see Landscape Hosts [page 32]
224
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Type: string
Table 165:
Optional
--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
--compression-min-size
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
225
Optional
-j, --java-version
JRE version
--timeout
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
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.
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.
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
Type: string
-e, --email
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
-w--overwrite
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.
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
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
Type: string
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.
-j, --java-version
-m, --minimum-processes
Default: 1
-M, --maximum-processes
Default: 1
-V, --vm-arguments
-z, --size
230
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
--compression-min-size
Defines the number of milliseconds to wait for the request URI line to be presented after
accepting a connection.
Default: 20000
--max-threads
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
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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.
Required
-i, --id
ASE database ID
Type: string
--db-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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
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
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
Type: string
234
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Required
--downtime-application
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>
Description
ALL
This level has the lowest possible rank and is intended to turn
on all logging.
TRACE
DEBUG
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
235
Level
Description
INFO
WARN
ERROR
This level designates error events that might still allow the
application to continue running.
OFF
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
Type: string
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-l, --level
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
Type: string
236
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
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.
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
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
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
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
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
Type: string
240
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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)
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
241
Required
-h, --host
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
--shutdown-port
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.
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
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
Type: string
--maintenanceapplication
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.
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
Type: URL. For acceptable values see Landscape Hosts [page 32]
244
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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]
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
Type: URL, for acceptable values see Landscape Hosts [page 32]
-u, --user
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
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.
Parameters
Table 186:
Optional
--shutdown-port
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
247
Required
-u, --user
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.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user
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
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]
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
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
Type: string
Table 190:
Optional
-s, --data-source
Example
250
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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]
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
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
Type: string
Table 193:
Optional
-s, --data-source
Example
252
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
Type: string
Table 195:
Optional
-s, --data-source
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
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.
Required
-u, --user
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.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-u, --user
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
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.
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
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
Type: string
-n, --name
-l, --location
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]
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
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
Type: string
-l, --localpath
Default: none
Type: string
258
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Type: string (up to 30 characters; lowercase letters and numbers, starting with a letter)
-h, --host
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
Type: string
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
259
Table 201:
Optional
-b, --application
Application name
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.
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
-j, --jars
-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>
Example
To show the SDK version and the runtime, execute:
neo version
To list all available commands and their versions, execute:
neo version -c
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.
Table 204:
Error Type
Start Number
End Number
Count
No error
Common errors
Missing parameters
10
39
30
40
109
70
126
17
127
165
39
Command-specific errors:
frontend
166
209
44
Command-specific errors:
backend
210
254
45
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
Network error
5-9
Common errors
10
Missing parameters
11
Missing parameters
12
Missing parameters
13
Missing parameters
14
Missing parameters
15-19
Missing parameters
20-39
Missing parameters
40
Validation errors
Type/Reason
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
263
Code
Meaning
Type/Reason
41
42
Validation errors
43
Validation errors
44-49
Validation errors
50-109
Validation errors
110
111
112-114
115-126
127-165
System-dependent errors
166
Frontend
167 - 209
Frontend
210
Backend
211 - 254
Backend
255
System-dependent errors
Related Information
Console Client [page 88]
1.4
Services
Description
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.
Service
Description
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.
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.
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.
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
265
Service
Description
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.
The lifecycle REST API provides functionality for application lifecycle management.
The monitoring service REST API enables you to fetch the overall monitoring status
and detailed metric values for your Java applications.
Performance statistics enable you to monitor the resources used by your applica
[page 714]
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.
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.
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
technology.
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 is a solution for generating print and interactive forms us
ing Adobe Document Services running on SAP HANA Cloud Platform.
SAP HANA Cloud Platform is an open, standard-based cloud platform that enables
ices
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.
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 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]
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
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.
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.
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]
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
271
1.4.1.1.1
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.
Package
Description
com.sap.core.connectivity.api
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]
Procedure
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.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
275
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.
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
277
Procedure
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.
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.
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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
279
com.sap.core.connectivity.api.authentication
AuthenticationHeaderProvider
Related Information
HTTP Proxy for On-Premise Connectivity [page 336]
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
281
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.
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".
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.
Tasks
Uploading Destinations [page 285]
Downloading Destinations [page 286]
Deleting Destinations [page 288]
Related Information
Examples (Console) [page 289]
284
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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>
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]
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.
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>
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
287
Related Information
Examples (Console) [page 289]
put-destination [page 211]
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
289
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.
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]
Related Information
Examples (IDE) [page 298]
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
291
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.
Related Information
Examples (IDE) [page 298]
Destinations [page 281]
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.
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
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.
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
button.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
293
Related Information
Examples (IDE) [page 298]
Destinations [page 281]
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.
Deleting Certificates
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]
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.
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).
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]
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).
296
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
297
298
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
299
300
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
301
Related Information
Examples (Cockpit) [page 313]
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
Connectivity
Destinations .
302
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Java Applications
Configuration
Destinations .
Related Information
Creating Destinations (Cockpit) [page 303]
Importing Destinations (Cockpit) [page 311]
Editing and Deleting Destinations (Cockpit) [page 309]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
303
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Examples (Cockpit) [page 313]
HTTP Destinations [page 322]
Editing and Deleting Destinations (Cockpit) [page 309]
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
Related Information
Examples (Cockpit) [page 313]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
305
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
Related Information
Examples (Cockpit) [page 313]
Mail Destinations [page 410]
Editing and Deleting Destinations (Cockpit) [page 309]
306
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
307
Table 208:
Error Message
Reason
Action
than 2.7.1.
connector.
is not reachable.
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.
Related Information
Examples (Cockpit) [page 313]
Exporting Destinations (Cockpit) [page 312]
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
Related Information
Examples (Cockpit) [page 313]
Exporting Destinations (Cockpit) [page 312]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
309
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.
310
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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.
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]
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
313
314
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
315
316
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
317
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.
318
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
319
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]
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
321
Overview
The HTTP destinations provide data communication via HTTP protocol and is used for both Internet and onpremise connections.
Description
DestinationProvider
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
322
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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.
The relative path to the JKS file. The root path is the server's location on the file
system.
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
324
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Property
Description
HostnameVerifier
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
325
Related Information
Client Authentication Types for HTTP Destinations [page 334]
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.
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
Type
URL
Authentication
IssuerSID
IssuerClient
RecipientSID
RecipientClient
Certificate
SigningKey
SystemUser
Optional property.
ProxyType
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\=
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.
Properties
The following credentials need to be specified:
Property
Description
Name
Type
URL
Authentication
ProxyType
Example
Name=OnPremiseDestination
Type=HTTP
URL= http://virtualhost:80
Authentication=PrincipalPropagation
ProxyType=OnPremise
Related Information
Principal Propagation [page 318]
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.
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
Type
URL
ProxyType
Authentication
audience
clientKey
tokenServiceURL
330
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Property
Description
tokenServiceUser
tokenServicePassword
Additional
SystemUser
nameQualifier
companyId
Company identifier
assertionIssuer
authnContextClassRef
nameIdFormat
userIdSource
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
331
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
Type
Authentication
URL
332
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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:
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
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]
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.
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.
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.
a remote server.
1.
The relative path to the JKS file. The root path is the server's location on the file
system.
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.
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]
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.
Related Information
Connectivity and Destination APIs [page 272]
Principal Propagation Using HTTP Proxy [page 338]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
337
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
338
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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]
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.
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]
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.
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.
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.
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.)
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
347
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.
File
New
348
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
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.
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
"
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.
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.
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.
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.
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.
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].
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
355
File
New
356
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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;
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
358
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
+ 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));
}
{
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
359
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.
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.
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
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].
362
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
364
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
File
New
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
365
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.
5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to
ConnectivityHelloWorld
WebContent
WEB-INF
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;
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.
}
} 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
"
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
369
370
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
371
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].
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.
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]
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
373
Note
You need to install SDK for Java Web Tomcat 7.
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.
File
New
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
375
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.
5. Choose Finish so that the ConnectivityServlet.java servlet is created and opened in the Java editor.
6. Go to
ConnectivityHelloWorld
WebContent
WEB-INF
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>
*/
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
377
378
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
379
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].
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
381
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
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.
Related Information
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
1.4.1.1.5
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 .
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]
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.
jco.client.passwd=<password>
jco.client.ashost=sales-system.cloud
jco.client.sysnr=42
jco.destination.pool_capacity=5
jco.destination.peak_limit=10
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
jco.client.lang
jco.client.user
jco.client.passwd
Note
When working with the Destinations editor in the cockpit,
enter this password in the Password field. Do not enter it as
additional property.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
385
Property
Description
jco.destination.auth_type
Optional property.
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.
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
jco.destination.peak_limit
386
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Property
Description
jco.destination.max_get_client_time
jco.destination.expiration_time
jco.destination.expiration_check_period
jco.destination.pool_check_connection
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
387
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
jco.destination.repository.user
jco.destination.repository.passwd
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.
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.
Table 222:
Property
Description
jco.client.ashost
jco.client.sysnr
Note
The virtual port in the above access control entry needs to
be named sapgw<##>, where <##> is the value of sysnr.
Table 223:
Property
Description
jco.client.mshost
jco.client.group
jco.client.r3name
Note
The virtual port in the above access control entry needs to
be named sapms<###>, where <###> is the value of
r3name.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
389
Property
Description
jco.client.msserv
Description
jco.client.trace
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
jco.client.cloud_connector_version
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.
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]
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
3. Enter the corresponding values in the fields Library Name, My Name and Quality of Protection (QoP)
4. Press Save and Close.
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]
392
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
397
398
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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
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.
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.
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].
New
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
401
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
403
always
5. Save the Java editor and make sure that the project compiles without errors.
404
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
405
Procedure
1. Optional: In the cloud connector administration UI, you can check under
has been denied:
Monitor
Audit
whether access
406
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Procedure
1. Optional: In the cloud connector administration UI, you can check under
has been denied:
Monitor
Audit
whether access
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
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.
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]
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.
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]
410
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Description
Mandatory
Name
Yes
Type
Yes
mail.*
mail.password
(mail.smtp.auth=true and
javax.mail property).
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
411
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.
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 .
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
413
Sample Application
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].
File
New
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.
414
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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>");
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
415
416
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
417
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
mail.password
Value
mail.transport.protocol
smtps
mail.smtps.host
smtp.gmail.com
mail.smtps.auth
true
mail.smtps.port
465
mail.user
mail.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.
1.4.1.1.7
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.
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.
Related Information
Multitenant Applications [page 990]
Creating a Multitenant Connectivity Application [page 1003]
1.4.1.2
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
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.
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.
File
New
File .
422
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
File
New
File .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
423
Related Information
XS Destination Properties [page 432]
1.4.1.2.2
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.
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]
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.
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.
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.
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.
File
New
File .
File
New
File .
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".
Security
Users
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.
Consuming Internet Services (Java Web or Java EE 6 Web Profile) [page 348]
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.
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.
File
New
File .
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.
File
New
File .
430
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
Security
Users
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
431
Persistence
Related Information
XS Destination Properties [page 432]
Consuming Back-End Systems (Java Web or Java EE 6 Web Profile) [page 362]
Description
Value
host
URL (string)
port
8443
pathPrefix
useProxy
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
XS Property
Description
Value
For ap1.hana.ondemand.com:
proxyHost
proxyPort
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
useSSL
true, false
timeout
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
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
435
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
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.
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".
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
2.x
2.x
438
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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)
Asia-Pacific (Australia)
(ap1.hana.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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
439
Table 233:
Operating System Version
Architecture
x86_64
2.x
x86_64
2.x
x86_64
2.x
x86_64
x86_64
Windows 10
x86_64
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]
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
441
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.
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.
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.
Related Information
Recommendations for Secure Setup [page 446]
Recommended: Replacing the Default SSL Certificate [page 452]
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.
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]
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
453
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
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.
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"
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
455
Related Information
For more information about configuring SSL, see http://tomcat.apache.org/tomcat-7.0-doc/sslhowto.html#SSL_and_Tomcat .
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
457
1.4.1.3.2
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.
458
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
459
460
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
2. You can configure again the password for the Administrator user from the Settings menu:
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.
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.
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.
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
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.
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.
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
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.
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
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]
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.
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.
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
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.
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].
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.
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.
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
477
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.
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.
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".
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]
480
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
481
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.
482
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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:
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.
Related Information
Principal Propagation [page 318]
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.
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.
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.
If a CA certificate is no longer required, you can delete it. To do this, use the respective button and confirm
deletion.
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.
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]
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
489
Related Information
Rule-based Mapping of Certificates [page 490]
Configuring Subject Pattern for Principal Propagation [page 494]
Setting Up Trust [page 480]
490
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
491
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
493
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.
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.
Related Information
Server Certificate Authentication [page 323]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
495
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.
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
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
497
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
Certificate Configuration
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
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
498
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1. Import the Root CA certificate of SLS into the systems trust store
AS ABAP: transaction STRUST
AS Java:
NWA
Configuration
SSL
2. (...)
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.
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.
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.
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
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.
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]
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.
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.
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.
504
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
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.
506
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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:
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.
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.
508
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
511
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.
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]
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.
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.
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.
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.
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.
Related Information
Get Support [page 1325]
1.4.1.3.18 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.
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.
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.
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.
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
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.
https://<scc_host>:<scc_port>/exposed?
200
action=ping
520
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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).
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
521
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.
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.
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.
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]
See
524
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
https://help.hana.ondemand.com/
https://help.hana.ondemand.com/help/frameset.htm?
e54cc8fbbb571014beb5caaf6aa31280.html
526
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Resource
Link
https://help.hana.ondemand.com/help/frameset.htm?
e6c7616abb5710148cfcf3e75d96d596.html
http://scn.sap.com/docs/DOC-28833
http://scn.sap.com/community/developer-center/cloudplatform
SAP security
https://service.sap.com/security
https://service.sap.com/securityguide
https://open.sap.com/course/hanacloud1
Videos of openSAP course "Introduction to SAP HANA Cloud
Platform"
https://account.hanatrial.ondemand.com/
Hardware Requirements
Table 238:
Minimum
Recommended
CPU
Memory (RAM)
1 GB
4 GB
1 GB
20 GB
Software Requirements
Table 239:
Operating System
Architecture
x86_64
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
527
Operating System
Architecture
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
528
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
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.
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]
530
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Uninstallation
Detailed documentation on how to uninstall the cloud connector on Microsoft Windows can be found here:
Uninstalling the Cloud Connector [page 523]
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]
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]
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]
532
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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]
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]
534
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
535
536
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
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]
Activity
Recommendation
Cloud connector
administrator should change
the initial password manage
538
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Activity
Recommendation
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
11
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
539
Activity
Recommendation
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
541
john@acme.com
CA Dev2
marry@acme.com
pete@acme.com
greg@acme.com
CA Test
CA Prod
cloud connector Dev1 + X
Dev2
X
X
X
X
X
X
542
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Distribution List
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.
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.
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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
545
546
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
547
1.4.2.1
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
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.
548
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Apache Chemistry Project
ecm.api
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.
Related Information
Creating a Repository Programmatically (Java) [page 550]
Connecting to a Repository (Java) [page 550]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
549
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]
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.
Once you are connected to the repository, you get an OpenCMIS session object to manage documents and
folders in the connected repository.
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.
552
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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/
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
553
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.
1.4.2.1.2
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;
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.
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
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.
1.4.2.1.3
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
Related Information
Creating a Sample Application (Java) [page 555]
1.4.2.1.4
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.
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]
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.
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()
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
563
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.
Related Information
http://chemistry.apache.org/java/download.html
http://docs.oasis-open.org/cmis/CMIS/v1.1
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
565
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
567
Note
The CMIS query language CMISSQL is similar to SQL.
cmis:name
sap:owner
cmis:objectId
john
john
<ID>
john
Hi Document
john
<ID>
john
Hello Document
john
<ID>
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
568
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
http://chemistry.apache.org/java/0.13.0/maven/apidocs/
http://chemistry.apache.org/java/examples/index.html
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
569
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
571
Related Information
OASIS page
572
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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) {
}
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
573
574
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
575
576
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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) {
}
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
577
578
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
return DecimalPrecision.BITS64;
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;
}
}
580
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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;
}
}
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);
582
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
583
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.
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";
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]
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
585
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.
586
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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.
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.
588
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
1.4.2.1.7
1.4.2.2
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
591
1.4.2.3
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
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
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.
Field
Entry
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
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
593
1.4.2.3.3
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
3. Choose Delete.
4. On the dialog that appears, enter the repository key.
5. Choose Delete.
1.4.2.3.4
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.
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
Related Information
Tenant Context API [page 995]
1.4.2.4
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]
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.
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.
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
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.
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
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
599
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
ratings.rX.value
integer
context
object
context.page
string
2038
context.view
string
64
context.lang
string
[1-5]
en
- English.
600
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Attribute
Type
Dimension
Description
context.attrX
string
64
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
601
Content Type
error.code
error.message
Feedback quota ex
ceeded
403
application/json
30
quota exceeded
400
application/json
40
<error
description>
application/json
41
400
application/json
42
<error
description>
404
Incorrect or misisng
Content-Type header
415
Examples:
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.
},
"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
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
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
603
604
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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].
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
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.
"UTF-8"));
File
New
HTML File .
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>
608
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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
610
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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.
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.
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]
612
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Note
No matter what filter is applied, the list always displays responses (if any) that are not classified by type or
sentiment.
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]
614
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
SAP HANA Developer Guide
Feedback Service Client API [page 599]
Feedback Service Administration [page 610]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
615
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.
1.4.5.1.1
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.
1.4.5.1.2
Prerequisites
You have logged on to the SAP HANA Cloud Platform cockpit with your SCN user and password.
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.
Related Information
Managing Roles [page 1282]
618
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Services
Gamification Service
Go to Service .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
619
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.
Services
Gamification Service
Go to Service .
Note
It may take up to five minutes until the destinations are available for the service.
Related Information
HTTP Destinations [page 322]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
621
1.4.5.1.4
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.
1.4.5.1.5
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
Prerequisites
You have the role helpdesk.
HelpDesk demo content is created.
The destinations gsdest and gswidgetdest are available.
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.
6. Process a ticket.
624
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
625
1.4.5.2
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.
1.4.5.2.1
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
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 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,
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
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
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.
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 .
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
Analytics
Administration
Players
1.4.5.3.1
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.
Table 249:
Role
GamificationDesigner
Workbench Level
Game Mechanics
Analytics
Description
GamificationReviewer
Analytics
TenantOperator
Administration
Configure tenant
Players
AppStandard
API Terminal)
For more information about assigning roles to a user, see Security [page 632].
1.4.5.3.2
Prerequisites
You have logged on to the gamification workbench.
At least one gamification service role is assigned to your user.
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.
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
GamificationReviewer
User
only)
Analytics
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
633
Role
Type
TenantOperator
User
Access Level
Game Mechanics
Administration
Players
Description
Configure tenant
AppStandard
Technical
reading achievements is
avoided
Send player-related
events
AppAdmin
Technical
634
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Role
Type
Access Level
Player (automatically as
signed)
Description
Send player-related
events (only works for
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
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]
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.
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).
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
639
1.4.5.6
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.
1.4.5.6.1
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
641
Type
Description
AUXILIARY
OTHER
Points can be configured in the Points subtab of the Game Mechanics 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.
642
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
643
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.
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.
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.
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.
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.
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.
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:
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);
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.
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.
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.
Procedure
1. Select the mission in the list to be deleted.
2. Press Delete.
3. Confirm deletion by pressing Confirm in the popup dialog.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
649
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.
User-accepted Missions
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
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
652
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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).
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.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.
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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
655
656
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
657
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.
Related Links:
The Rules Language [jboss Droosl]: http://docs.jboss.org/drools/release/5.6.0.Final/drools-expert-docs/
html/ch05.html
$loginCounter: GenericFact(key=='LoginCounter')
Declaration of a generic fact loginCounter.
$daysOfWeek: GenericFact(key=='DaysOfWeek')
Declaration of a generic fact daysOfWeek.
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.
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
660
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
661
662
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
$p : Player($playerid == uid)
not GenericFact(key==$playerid,data['chapterId']==$chapter)
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
663
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.
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
665
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.
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
667
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:
668
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
669
1.4.5.6.7
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.
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.
Context
The API Terminal allows you to execute all methods for retrieving the user achievements data.
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
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.
Note
The maximum retention time for the event log is 7 days, but not exceeding 500,000 log entries.
1.4.5.7
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
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.
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
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.
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
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 .
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
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.
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>&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
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.
Related Information
Application-to-Application SSO Authentication [page 332]
Protecting from Cross-Site Request Forgery [page 1235]
1.4.5.7.6
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
679
680
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1.4.5.8
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
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.
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
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.
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
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].
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.
1.4.5.9.1
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
685
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]
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.
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.
Related Information
Managing Roles [page 1282]
1.4.5.9.2
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
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
688
Maven
File
Import .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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.
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
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
The following sections describe how the gamification design is implemented in the gamification workbench.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
691
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
693
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.
Results
You should now see all three levels (Novice, Competent, and Expert) in the list for Levels.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
695
696
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Results
You should now see all badges (Troubleshooting Champion) in the list for Badges.
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.
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]
Procedure
1. Go to Game Mechanics in the navigation menu and select Rules.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
699
700
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
701
1.4.5.9.5.6.6 Result
You should now see the created rules in the list for Rules.
Results
All rules are shown as active without any issue warnings.
702
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Value
CPU Load
Disk I/O
OS Memory Usage
Busy Threads
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.
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
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
application
state
processes
process
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
705
Parameter
Value
metrics
name
value
unit
warningThreshold
errorThreshold
timestamp
output
min
max
metricType
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.
"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,
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
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.
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";
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
709
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
711
1.4.6.3
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.
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:
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
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.
1.4.7.1
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
Value
URL
action
Start Time
startTime
Memory (bytes)
allocMem
CPU (ms)
cpuTime
sentBytes
Response (bytes)
receivedBytes
Response (ms)
respTime
DB Calls (count)
dbCalls
Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.
DB Calls (bytes)
dbIO
Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
715
Value
DB Calls (ms)
dbTime
Note
This metric is not supported for Java
Web Tomcat 7 and Java Web Tomcat
8 application runtime container.
External Calls (ms)
extTime
ID
transId
User
userId
Not displayed
actionType
Not displayed
addInfo
Not displayed
externalCalls
Not displayed
externalRecords
Not displayed
serviceType
Not displayed
sessionSize
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.
"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",
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.
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
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
719
(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]
720
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
1.4.8.1
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
Familiarize yourself with the JPA and JDBC technologies on SAP HANA Cloud Platform by com
pleting the tutorials.
Particular aspects about working with JPA and JDBC that were introduced in the tutorials are
explained in more detail.
Activate the SQL trace to include SQL details in the standard trace files.
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
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
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]
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.
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.
File
New
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
727
File
New
Other
Class
728
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Open With
File
New
Other
EJB
and choose
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
729
Import
General
File System
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
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.
Open With
Java Editor .
730
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
@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\">"
+ " Last name:<input type=\"text\" name=
\"LastName\">"
+ " <input type=\"submit\" value=\"Add
Person\">"
+ "</form></p>");
}
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
731
4. Save the servlet. The project should compile without any errors.
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.
732
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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.
3. On the Servers view, open the context menu for the server you just created and choose
Show In
Persistence
<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
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
Note
The tutorial is based on the SDK for Java Web.
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.
File
New
736
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
738
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
File
New
Other
Class
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
739
Open With
Import
General
File System
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
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
740
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
<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.
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;
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.
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\">"
+ " Last name:<input type=\"text\" name=\"LastName
\">"
+ " <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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
743
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.
SAP
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.
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.
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
Persistence
<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
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.
Steps
Sample Application
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.
File
New
File
New
Web
Servlet
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.
748
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
/**
* 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;
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();
}
Import
General
File System
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.
Open With
Text Editor
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.
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;
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.
tr>" +
tr>"));
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.
SAP
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.
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.
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
Persistence
<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
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.
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
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.
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]
2. Create a Database User with Permissions for Working with Web IDE [page 760]
Maven
Console client, SDK
SAP HANA Cloud Platform cockpit
Browser
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.
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.
Persistence
Value
Database ID
Example: tutorial
Database System
mdc1 (HANAMDC)
Note
mdc1 corresponds to the database system on which you create the data
base.
Example: Trial SAP HANA tenant 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.
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.
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.
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.
Persistence
in the navigation
Note
Use the Logout button in the header to log on with a different user.
6. To create a new package, choose
New
Package
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
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
Applications
Java Applications
762
Navigation Links
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Catalog .
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
763
Tools
Maven
Console client, SDK
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.
764
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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'.
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
767
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
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'
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.
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
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
769
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
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.
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.
Description
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 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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
771
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.
Table 265:
Use Case
Description
You can use a tenant database reserved for you in productive mode. However, some restric
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
773
Use Case
Description
You can try out working with a 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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
775
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
777
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
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
779
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
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.
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.
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.
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]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
783
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
785
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.
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]
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.
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.
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.
2. Choose
Configuration Data Source Bindings in the navigation area.
The overview shows the bindings available for the specific application.
3.
4.
5.
6.
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.
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]
Security
Users .
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]
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.
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
SELECT
CREATE
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);
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.
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:
Security
Users .
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.
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]
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.
Persistence
Database Systems
system. Choose Databases in the navigation area at the database system level. In
the list, select the relevant SAP HANA database.
Persistence
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.
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
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.
1.
Choose
Applications
Java Applications
Configuration
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
795
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]
796
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
SELECT
CREATE
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();
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
797
Database
bind-hana-dbms
bind-db
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.
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]
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
799
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]
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.
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
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
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]
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.
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]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
803
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.
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.
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).
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.
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.
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]
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
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.
To create bindings...
By application
Do the following
1.
Choose
Applications
Java Applications
Configuration
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
809
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
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.
Related Information
Creating and Binding Schemas [page 811]
Using Multiple Schemas [page 813]
Migrating Auto-Bound Schemas [page 815]
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
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.
Related Information
Landscape Hosts [page 32]
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)
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.
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]
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)
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
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
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.
Related Information
Landscape Hosts [page 32]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
817
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.
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]
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
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]
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.
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]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
821
1.4.8.4
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
Container-managed persistence
Not supported
JTA transactions
Entity manager injection using the
@PersistenceContext annotation
Application-managed persistence
Resource-local transactions
Not supported
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
Application-managed persistence
Java Web
eclipselink\jlib\eclipselink.jar
eclipselink\jlib\jpa
\javax.persistence_2.*.jar
822
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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].
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
823
1.4.8.4.1
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
<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
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.
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>
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
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.
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
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>
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
827
Related Information
Managing Schemas [page 804]
Configuring Data Sources As Connection Properties [page 867]
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.
Related Information
Configuring Data Sources As Connection Properties [page 867]
1.4.8.4.4
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
829
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]
830
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
831
Related Information
Managing Schemas [page 804]
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.
Related Information
Java EE Specification
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
833
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]
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.
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
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">
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.
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
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
839
840
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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.
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
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.
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>
844
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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))";
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
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.
Applications
Java Applications
Monitoring
Logging
846
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Monitoring
Logging
in the navigation
Procedure
To display the contents of a particular log file, choose
choosing
(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
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.
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
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
849
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.
1.4.8.7.1
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.
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]
Responsible
More Information
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.
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.
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]
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
855
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
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.
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.
user=mymail@example.com
account=myaccount
dbSchema=myschema
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]
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
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
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
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
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
859
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.
1.4.8.7.4
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 .
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
863
1.4.8.7.5
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.
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.
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
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.
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.
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
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
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.
1.4.8.8.2
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
869
1.4.8.9
Answers to some of the most commonly asked questions about the persistence service.
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.
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 ).
Persistence
Database Systems
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.
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.
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.
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
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
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.
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
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-
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.
Next Steps
Developing Client-Initiated Synchronization [page 877]
1.4.9.3
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
profile.
3. Choose Connect.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
877
New
MobiLink User .
878
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
879
New
Subscription .
880
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
New
Synchronization Profile .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
881
882
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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
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.
886
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
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
.
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
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.
Related Information
SQL Anywhere Monitor
MobiLink Profiler
1.4.9.6.1
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.
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
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
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.
Next Steps
To learn more about the UI of the MobiLink Profiler, see MobiLink Profiler Interface
1.4.9.7
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.
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
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.
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.
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
895
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
897
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]
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.
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.
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.
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.
Error Handling
Table 278: Error Codes
Error
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
901
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
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.
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
Always in response
"domains":[
{
},
{
},
{
"id":"FI",
"name":"Financial Accounting"
"id":"FS",
"name":"Financial Services"
"id":"FB",
"name":"Financials Basis"
Usage
Returns a list of the languages that SAP Translation Hub supports.
Request
URL: <base URL of SAP Translation Hub>/translationhub/api/v1/languages
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
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.
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
Always in response
904
"languages":[
{
"id":"bg",
"name":"Bulgarian"
}
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Building Base URL of SAP Translation Hub [page 897]
Testing the Services [page 918]
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.
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
Mandatory
language
Optional
domain
Optional
texttype
Optional
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
Always in response
value
Always in response
domainId
Depends on request
domainName
Depends on request
texttypeId
Depends on request
texttypeName
The name of the text type assigned to the text entered in the
request.
Depends on request
englishValue
Always in response
906
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Parameter
Description
Part of Response?
availableLanguages
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
Always in response
textSpace Parameter
Description
Part of Response?
inputChars
Always in response
minRecChars
Always in response
minRecEm
Always in response
Table 285:
"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
}
}
]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
907
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.
To check whether a specific text type is available, you can add the following parameter to the URL:
Table 286:
Parameter
Description
Type
search
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.
Response
The result is a JSON object, and contains the following key-value pairs:
Table 287:
Key
Description
Part of Response?
id
Always in response
name
Always in response
"texttypes":[
{
"id":"MSAG",
"name":"Message Classes"
},
{
"id":"XMSG",
"name":"Message text"
}
]
}
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
909
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
Root Key
Description
Type
enableTranslationQualityEsti
mation
Optional
bundles
Mandatory
Bundles Key
Description
Type
domain
Optional
Table 289:
Note
It is not possible to enter multiple domains.
units
Mandatory
Units Key
Description
Type
value
Mandatory
textType
Optional
Table 290:
Note
It is not possible to enter multiple text types.
key
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).
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
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
Depends on request
units
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
Always in response
textType
Depends on request
key
Depends on request
translations
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.
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
Depends on request
value
Depends on request
translationQualityEstimation
Depends on request
Related Information
Building Base URL of SAP Translation Hub [page 897]
Language Service [page 903]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
913
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.
Table 295:
Data Key
Description
Type
domain
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
Optional
objectName
Mandatory
Entries Key
Description
Type
key
Mandatory
value
Mandatory
Table 296:
"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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
915
Table 297:
Data Key
Description
Part of Response?
objectName
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
Depends on request
value
Always in response
language
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.
"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]
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
917
Related Information
Building Base URL of SAP Translation Hub [page 897]
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.
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
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.
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
921
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.
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:
additional folders>
For example,
i18n
/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.
922
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
923
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
925
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.
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.
Mail Us
If you prefer more direct communication, drop us a line at mailto:translationhub@sap.com.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
927
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.
928
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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]
Prerequisites
You are an administrator of the account.
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
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.
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.
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]
Prerequisites
You are an administrator of the account.
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.
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.
Procedure
1. Log on to the SAP HANA Cloud Platform cockpit, and select the appropriate account.
2. Choose the
Repositories
Git Repositories
3. In the list of Git repositories, locate the repository you want to delete.
4. Choose the delete icon (
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
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.
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.
Related Information
Using Source Control (Git) in SAP Web IDE
Best Practices [page 939]
Troubleshooting [page 940]
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.
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
935
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
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
937
2. Choose the
Repositories
Git Repositories
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.
Related Information
Account Member Roles [page 27]
Creating a Version [page 74]
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.
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]
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.
942
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
943
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.
944
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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].
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.
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
947
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.
<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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
949
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
950
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
To learn about
See
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.
1.5.2.1
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
SAP HANA Cloud infrastructure runs on SAP's own implementation of a Java Virtual Machine - SAP Java Virtual
Machine (JVM).
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).
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.
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
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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
955
Table 302:
Profile
Java Web
6 (default); 7
7 (default); 8
Java Web
Tomcat 7
socket)
Java EE 6
7 (default); 6
Web Profile
Java Web
Tomcat 8
8 (default); 7
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]
JSR
Servlet 3.0
JSR - 315
JSR - 245
956
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Specification version
JSR
JSR - 245
JSR - 45
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]
JSR
Servlet 3.0
JSR - 315
JSR - 245
JSR - 245
JSR - 45
JSR - 356
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.
JSR
JSR - 316
Servlet 3.0
JSR - 315
JSR - 245
JSR - 245
JSR - 45
JSR - 52
JSR - 356
JSR - 314
JSR - 250
JSR - 318
JSR - 907
JSR - 317
JSR - 330
JSR - 299
JSR - 303
JSR - 316
Interceptors 1.1
JSR - 318
Source: JSR-316
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.
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]
JSR
Servlet 3.1
JSR - 340
JSR - 245
JSR - 341
JSR - 45
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.
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.
Configuration
Lite edition
lite
Professional edition
pro
Premium edition
prem
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.
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
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
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
Servlet 3.0
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
yes
no
yes
no
yes
no
yes
no
yes
no
yes
no
yes
no
yes
no
yes
Interceptors 1.1
no
yes
962
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Servlet 3.1
yes
yes
yes
WebSocket 1.1
yes
yes
yes
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
Connectivity
Document
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
963
1.5.2.3
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]
964
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
965
Monitor
Configure checks and monitor the state of your applications.
For more information, see Monitoring Java Applications [page 1149]
1.5.2.3.1
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.
File
New
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
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
File
New
Other
EJB
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.
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
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
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_.
Sample Value
Description
HC_HOST
hana.ondemand.com /
us1.hana.ondemand.com /
hanatrial.ondemand.com
970
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Key
Sample Value
Description
HC_HOST_SVC
svc.hana.ondemand.com /
svc.us1.hana.ondemand.com /
svc.hanatrial.ondemand.com
HC_HOST_CERT
cert.hana.ondemand.com /
cert.us1.hana.ondemand.com
/
cert.hanatrial.ondemand.com
HC_REGION
EU_1 / US_1
HC_ACCOUNT
myaccount
HC_APPLICATION
myapp
Application name
HC_APPLICATION_URL
https://
myapp.hana.ondemand.com
HC_LOCAL_HTTP_PORT
9001
HC_LANDSCAPE
production / trial
HC_PROCESS_ID
8921b0a7cebc5538038b6b7b0c0
ea6a7127f0cd4
full-process-id.
HC_OP_HTTP_PROXY_HOST
localhost
HC_OP_HTTP_PROXY_PORT
20003
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>
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
971
<body>
Related Information
status [page 238]
Landscape Hosts [page 32]
HTTP Proxy for On-Premise Connectivity [page 336]
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.
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.
File
Save
or with Ctrl + S .
Save
or with Ctrl + S .
button.
File
button.
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
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:
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]
WAR files.
Command: deploy
Console Client
Cockpit
[page 985]
Console Client
[page 977]
974
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Console Client
Planned Down
time
(Maintenance
Mode)
Soft Shutdown
Related Information
Product Prerequisites and Restrictions [page 8]
1.5.2.4.1
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].
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.
1.5.2.4.2
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
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.
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.
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]
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
979
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
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.
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.
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
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
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.
1.5.2.4.4
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.
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]
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
984
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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.
Related Information
Profiling Applications [page 1141]
1.5.2.5.1
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
987
1.5.2.5.2
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 .
Note
Since cloud servers are running on SAP JVM, switching modes does not require restart and happens in real
time.
SAP
New
Server .
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.
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 .
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.
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
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.
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].
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
993
994
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
995
Table 315:
API
Description
com.sap.cloud.account
account
You can also access it at the following URL: https://
help.hana.ondemand.com/javadoc/index.html
com.sap.cloud.account
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.
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]
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
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
998
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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");
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.
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.
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]
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1001
New
JSP File
1002
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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
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
1004
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
New
JSP File
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1005
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.
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.
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]
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]
1008
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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.
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
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.
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.
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
User management
Web-based tools
See:
Eclipse
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
Connectivity destinations
Monitoring
Configuring Availability Checks for SAP HANA XS Applications from the Cockpit [page
1017]
Debugging
Supported by the SAP HANA Tools plugin for Eclipse as of release 7.4.
tions
Installing SAP HANA solutions
Java development
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.
1.5.3.2.1
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1013
Related Information
Roles Required for Web-based Tools [page 1017]
1.5.3.2.2
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
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.
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
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].
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
Tool URL
pit
SAP HANA Web-based Devel
https://<database
opment Workbench
instance><account>.<
Development Workbench
host>/sap/
hana/xs/ide/
https://<database
Tool
instance><account>.<
host>/sap/hana/xs/
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.
1.5.3.2.4
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
sap.hana.xs.debugger::Debugger
sap.hana.xs.admin.roles::HTTPDestViewer
sap.hana.xs.admin.roles::HTTPDestAdministrator
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
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
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
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.
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1019
1.5.3.2.7
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.
Related Information
Browser Support [page 8]
Cockpit [page 84]
1.5.3.2.8
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:
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
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.
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].
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].
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].
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.
Parameter
<idp description>
A free-text description.
<idp host>
<idp port>
<path prefix>
<use proxy>
Values:
1 - Yes
0 - No
<proxy host>
<proxy port>
<use SSL>
<timeout>
0 - use HTTP
1 - use HTTPS
SQL Statement
Example
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');
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');
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1025
Configuration
SQL Statement
Example
'sap.hana.xs.samlProvider
s', '<uppercase idp
name>', '<SLO redirect
endpoint URL>');
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.
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.
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.
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 .
Related Information
Maintaining HTTP Destinations
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1027
1.5.3.3
SAP HANA Cloud Platform provides the option to create and use SAP HANA databases in a trial environment.
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
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.
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.
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.
1.5.3.4.1
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 .
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
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.
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
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.
Procedure
1. From the SAP Service Marketplace: Support Packages and Patches
page, download:
Next Steps
Next, set the STREAMING_HOME environment variable [page 1033].
1.5.3.4.4
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>
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.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 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.
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
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.
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
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].
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
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
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.
1038
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1039
1.5.3.4.9
You can improve workload management by controlling CPU resources in SAP HANA and SAP HANA smart data
streaming.
Related Information
CPU Usage
1040
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
HTML5: Getting Started [page 66]
HTML5: Application Operations [page 1171]
Securing HTML5 Applications [page 1323]
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1043
1.5.4.1.2
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1045
1.5.4.1.4
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.
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]).
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.
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]
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"
]
}
]
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].
...
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.
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
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": [
...
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: 30000 (30 seconds) Period of time in milliseconds until the HTML5 appli
Max. value: 300000 (300
seconds)
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.
Related Information
Assigning Destinations for HTML5 Applications [page 1176]
Note
If multiple routes are defined in the application descriptor, the route for the first matching path in the
application descriptor is selected.
...
"routes": [
{
...
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"
}
]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1053
Related Information
Application Descriptor File [page 1046]
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.
Description
Principal Attribute
name
n.a.
firstName
firstname
lastName
lastname
displayName
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.
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"
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
1056
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
To configure a logout page for your application, use the following format in the neo-app.json file:
...
...
Example
An example configuration of a logout page looks like this:
...
...
"logoutPage": "/logout.html"
...
Example
An example configuration that caches all static resources for 24 hours looks like this:
...
"cacheControl": [
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1057
{
]
...
"maxAge": 86400
1058
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Example
An example configuration that forwards the additional headers X-Custom1 and X-Custom2 looks like this:
"headerWhiteList": ["X-Custom1 "," X-Custom2"]
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.
REST APIs
Lifecycle management API
Authorization Management API
Monitoring API
1.6
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.
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
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]
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 system. For more information about changing the default role provider, see: Changing the Default Role
Provider [page 1290]
Related Information
Extension Application Front End [page 1063]
Extension Application Back End [page 1065]
1.6.1.1
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
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.
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.
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
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
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.
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.
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1069
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1071
Protocol
Description
sap_hcmcloud_core_odata
OData
sap_hcmcloud_core_soap
SOAP
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.
1.6.2.1
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.
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.
1.6.2.2
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.
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
Note
This task is relevant for Java extension applications only.
5. Register a Home Page Tile for the Extension Application
[page 1086]
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.
1.6.2.2.1
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1077
Related Information
Deploying Applications
1.6.2.2.2
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.
Table 324:
Property
Include in roles.json
Description
permissionID
No
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1079
Property
Description
permissionType
permissionStringValue
permissionLongValue
}]
}]
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.
1.6.2.2.3
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.
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.
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
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
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
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.
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>.
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
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.
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>.
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.
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
path
size
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
locale
Table 328:
Optional
description
Note
The tiles.json descriptor file must use UTF-8 encoding and its size must not exceed 100 KB.
Example
[
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1091
1.6.2.2.7
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
Admin Center
Manage Employees
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.
1.6.2.2.8
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.
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.
1.6.2.2.9
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1095
To learn about
See
Configuring Applications
Table 331:
Cockpit
1096
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Console Client
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
[page 979]
[page 1109]
Deploying Locally from Eclipse IDE [page Start, stop, republish and perform delta deploy of applica
975]
tions.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1097
Monitoring
Table 333:
Cockpit
[page 714]
Configuring Availability Checks for Java
Applications from the Cockpit [page
1153]
Managing Subscriptions [page 28]
Console Client
[page 1154]
Profiling
Table 334:
Eclipse IDE
View the logs and change the log settings of any applications
Logging
Table 335:
Cockpit
Eclipse IDE
1098
1134]
cation.
View the logs and change the log settings of the applications
1131]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
maintenance.
1.7.1.1
Configuring Applications
As an operator, you can configure an SAP HANA Cloud Platform application according to your scenario.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1099
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.
1.7.1.1.1
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
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.
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.
1.7.1.1.3
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
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
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.
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
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.
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.
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
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.
1.7.1.2.1
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1109
1.7.1.2.2
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:
1110
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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:
The running process is stopped and a new process started. A new process ID is generated
automatically.
(Disable process)
Disable a process
Panels:
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:
Stop a process
Panels:
The process is stopped and removed from the list. If the application has no further proc
esses, it transitions to the Stopped state.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1111
To...
Choose...
(Stop)
Stop an application
Panels:
All running processes are stopped and the application transitions to the Stopped state.
(Delete)
Undeploy an application
Panels:
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
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.
The Processes panel shows an aggregate status value in the Status column as follows:
- OK
- 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
Related Information
Cockpit [page 84]
1.7.1.2.4
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
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
OS Memory Usage
Busy Threads
Procedure
1. To view the current metrics for a process, open
for the account.
Applications
Java Applications
1114
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Related Information
Cockpit [page 84]
Browser Support [page 8]
Monitoring Java Applications [page 1149]
1.7.1.2.5
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]
Description
FILE_TYPE
FILE_ID
ENCODING
RECORD_SEPARATOR
COLUMN_SEPARATOR
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1115
Parameter
Description
COLUMNS
SEVERITY_MAP
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.
Related Information
Logging in Applications [page 1129]
Multitenant Applications [page 990]
1.7.1.2.6
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).
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
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
Network
1118
Data Transfer
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Service
Resource
Description
Incoming Requests
Connectivity
Document
Transactions
Persistence
DB Space (MaxDB)
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
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].
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.
1.7.1.3.1
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
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.
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
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.
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.
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]
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
(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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1127
1.7.1.4
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.
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].
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);
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.
Description
ALL
This level has the lowest possible rank and is intended to turn
on all logging.
TRACE
DEBUG
INFO
WARN
1130
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Level
Description
ERROR
This level designates error events that might still allow the
application to continue running.
OFF
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
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1131
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1133
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.
button.
button.
1.7.1.5.2
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.
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 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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1135
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.
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.
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
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
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
(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.
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.
Related Information
Cockpit [page 84]
Log Viewers [page 1139]
Using the SQL Trace [page 846]
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
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.
Description
Time
Level
Logger
Logger name
Tenant
Text
Description
Time
Client
User
Method
HTTP method
Resource
Status
Size
Duration
Related Information
HTTP Method Definitions
HTTP Status Code Definitions
1140
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
Synchronization Trace
Shows the most contended locks and the threads waiting for or holding
them
Shows the number of bytes transferred from or to files and the meth
ods transferring them
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1141
Shows the number of bytes transferred from or to the network and the
methods transferring them
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
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.
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.
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.
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
1.7.1.6.2
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 .
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.
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
1.7.1.7
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]
Description
FILE_TYPE
FILE_ID
ENCODING
RECORD_SEPARATOR
COLUMN_SEPARATOR
COLUMNS
SEVERITY_MAP
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.
1.7.1.8
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]
Configuration
JMX Console
mands
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1149
Availability Checks
Table 348:
Concept
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
Monitoring Service
Table 350:
Concept
JSON Response
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Performance Sta
tistics Report
Configuration
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
WARNING
OK
UNSTABLE
STABLE
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
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.
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]
Prerequisites
You have deployed and started an application in your account.
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.
Related Information
Browser Support [page 8]
Cockpit [page 84]
Availability Checks [page 1151]
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1155
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
OK
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
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.
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]
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.
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.
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
Related Information
Browser Support [page 8]
Cockpit [page 84]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1159
1.7.1.9
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.
1160
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1161
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]
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.
Description
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]
Procedure
1. Unsubscribe the account of the consumer from the application.
Execute neo unsubscribe -a <account> -b <application> -u <user name or email>
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1163
Related Information
Managing Subscriptions [page 28]
delete-account [page 125]
unsubscribe [page 255]
Console Client
1.7.2.1
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.
Availability Checks
Table 356:
Concept
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
Monitoring Metrics
Table 358:
Cockpit
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
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
WARNING
OK
UNSTABLE
STABLE
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1167
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.
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
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1171
Managing Destinations
Table 361:
Cockpit
Logging
Table 364:
Cockpit
Related Information
Managing HTML5 Subscriptions [page 30]
1172
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1.7.3.1
You can export HTML5 applications either with their active version or with an inactive version.
HTML5 Applications
in the navigation area, and then the link to the application you
).
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 (
).
1.7.3.2
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1173
Applications
HTML5 Applications
).
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].
in the navigation area, and then the application for which you
).
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 (
1.7.3.3
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.
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
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1175
1.7.3.5
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.
1.7.3.6
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
(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
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
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
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]
Procedure
1. In the cockpit, choose
Applications
HTML5 Applications
1178
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
Procedure
1. In the cockpit, choose
Applications
HTML5 Applications
2. Select the HTML5 application to which you want to assign the roles.
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
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]
Procedure
1. In the cockpit, choose
Applications
Subscriptions
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.
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
Procedure
1. In the cockpit, choose
Applications
Subscriptions
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1181
1.7.3.8
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
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]
1182
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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]
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.
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.
Note
The domain name and the server certificate for this domain are issued by external authorities and owned by the
customer.
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
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.
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1187
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.
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]
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1189
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.
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.
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.
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]
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.
Procedure
1. In your Web browser, open the SAP HANA Cloud Platform cockpit and choose
navigation area.
Security
Trust
in the
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1193
1.7.4.1.3
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
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.
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
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.
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.
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
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
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
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
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]
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1199
Parameter
Description
Mandatory
com.sap.hcp.html5
name
yes
com.sap.hcp.html5
version
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
yes
com.sap.java
runtime
yes
neo-java-web
neo-javaee6-web
depending on the runtime to be used
com.sap.java
runtime-version
no
com.sap.java
java-version
no
com.sap.java
jvm-arguments
no
java.tomcat
name
yes
java.tomcat
runtime-version
no
ple 2.35
com.sap.fiori.app
1200
html5-app-name
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
yes
Module type
Parameter
Description
Mandatory
com.sap.fiori.app
html5-app-
no
version
Note
The same rules apply as for the
com.sap.fiori.role
name
yes
Note
Existing SAP Fiori custom role will be skipped during de
ployment.
Parameter
Description
Mandatory
com.sap.hcp.persis
id
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.
Note
Always wrap any version value in single quotes so that it is not confused with a numeric value.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1201
1202
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1203
Troubleshooting
Note
Make sure you do not submit any confidential informa
tion to the online YAML parser.
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
1204
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Technology
See
SAP HANA
SAPUI5
HTML5
Related Information
Identity and Access Management [page 1205]
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.
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.
1206
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1207
1208
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1209
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.
See
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1211
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
com.sap.security.um
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.
Package
Description
com.sap.cloud.security.password
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1213
Default Options
Description
Sample Usecase
FORM
Application-to-Application
SSO
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.
Authentication Method
Default Options
Description
Sample Usecase
CERT
Client certificate
BASICCERT
Client certificate
OAUTH
Authentication according to
the OAuth 2.0 protocol with
an OAuth access token. See
Protecting Applications with
OAuth 2.0 [page 1227]
SAML2
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
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.
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]
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1217
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.
1218
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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 .
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1219
1.8.3.1.2
Enforcing Authorizations
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
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.
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.
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.
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"
]
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.
Headers:
Authorization: Bearer 51ddd94b15ec85b4d54315b5546abf93
Related Information
Authorization Management API
1.8.3.1.4
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;
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.
} 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>");
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.");
}
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 {
1226
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
<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
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.
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.
You cannot log in for a reason different from all others listed
here.
1.8.3.1.7
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.
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
Description
Resource owner
User
Resource server
Application
Client
Third-party application
Authorization server
1228
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
</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:
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1229
Element
Description
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
Initial parameters
With these, you specify the scope, user principal and HTTP
method:
scope
http-method
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>
1230
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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.
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");
}
Code
Return value / Ex
ception
Code
Description
Description
Description
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1231
200
True
access_token
is valid
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
reason =
"missing_acce
ss_token
401
access_token
False
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.
401
False
access_token
has expired
Attribute
"reason" in the
401
request describing
the reason for the
result
reason =
"missing_acce
ss_token
401
access_token
False
Attribute
"reason" in the
401
request describing
the reason for the
result
reason =
"missing_acce
ss_token
500
Unexpected error
(no connection to
ception
the database)
(extends
500
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1233
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
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.
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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1235
1236
When to Use
How to Use
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
When to Use
How to Use
Note
These approaches cannot be applied together to protect one and the same web resource.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1237
1238
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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
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
REST API
Description
Type
GET
/services/list
non-modifying
POST
/services/customers/
removeCustomer
modifying
POST
/services/customers/
addCustomer
modifying
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.
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
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.
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
This document describes how to protect SAP HANA Cloud Platform applications from XSS attacks.
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.
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
HTML / XML:
out = XSSEncoder.encodeHTML( in ); /
XSSEncoder.encodeXML( val );
JavaScript:
URL:
CSS:
Import
General
File System
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.
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]
1246
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
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].
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1247
Related Information
Keystore Console Commands [page 1248]
Tutorial: Using the Keystore Service for Client Side HTTPS Connections [page 1251]
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.
Properties
The following CAs are available in SAP JVM 7.
Table 376:
Certificate Alias
Certificate Name
Certificate SHA1
baltimorecybertrustca
D4:DE:20:D0:5E:66:FC:53:FE:1A:
50:88:2C:78:DB:28:52:CA:E4:74
digicerthighassuranceevroot
ca
5F:B7:EE:06:33:E2:59:DB:AD:0C:4C:
9A:E6:D3:8F:1A:61:C7:DC:25
entrust2048
50:30:06:09:1D:97:D4:F5:AE:
39:F7:CB:E7:92:7D:7D:65:2D:34:31
entrustpersonalserverca
DA:79:C1:71:11:50:C2:34:39:AA:2B:0B:
0C:62:FD:55:B2:F9:F5:80
entrustserverca
99:A6:9B:E6:1A:FE:88:6B:4D:2B:
82:00:7C:B8:54:FC:31:7E:15:39
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
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
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
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
verisignclass1_g2
verisignclass1_g3
verisignclass2_g1
67:82:AA:E0:ED:EE:E2:1A:
58:39:D3:C0:CD:14:68:0A:4F:60:14:2A
verisignclass2_g2
B3:EA:C4:47:76:C9:C8:1C:EA:F2:9D:
95:B6:CC:A0:08:1B:67:EC:9D
verisignclass2_g3
61:EF:43:D7:7F:CA:D4:61:51:BC:
98:E0:C3:59:12:AF:9F:EB:63:11
verisignclass3_g1
74:2C:31:92:E6:07:E4:24:EB:
45:49:54:2B:E1:BB:C5:3E:61:74:E2
verisignclass3_g2
85:37:1C:A6:E5:50:14:3D:CE:
28:03:47:1B:DE:3A:09:E8:F8:77:0F
verisignclass3_g3
13:2D:0D:45:53:4B:
69:97:CD:B2:D5:C3:39:E2:55:76:60:9B:
5C:C6
verisignclass4_g2
0B:77:BE:BB:CB:7A:A2:47:05:DE:CC:
0F:BD:6A:02:FC:7A:BD:9B:52
verisignclass4_g3
C8:EC:8C:87:92:69:CB:4B:AB:39:E9:8D:
7E:57:67:F3:14:95:73:9D
workplaceca
A1:7D:8B:51:8A:8F:BB:DE:A5:00:C8:1E:
96:12:26:16:32:4A:34:C0
thawteprimaryrootcag2
AA:DB:BC:22:23:8F:C4:01:A1:27:BB:
38:DD:F4:1D:DB:08:9E:F0:12
verisignclass3_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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1251
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.
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
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.
Related Information
Creating a HelloWorld Application [page 47]
Local Server Configuration of the Keystore [page 1255]
Cloud Configuration of the Keystore [page 1255]
Related Information
Deploying Locally from Eclipse IDE [page 975]
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]
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1257
Description
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.
Table 378:
Mapping Mode
Description
How to Set
Example
CN
Set the
com.sap.cloud.crypto cn=myuser,ou=security as a
certificates subject.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1259
Mapping Mode
Description
How to Set
Example
CN@issuer
of the certificates
system properties:
OU=Development as a subject
subject>@<keystore alias of
the certificates issuer>. Use
value CN@Issuer
defined as john@sso_ca.
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.
Mapping Mode
Description
How to Set
Example
wholeCert
is received:
system properties:
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
Note
The client certificate is not
accepted if no exact match
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1261
Mapping Mode
Description
How to Set
Example
subjectAndIssuer
A certificate with
CN=john.miller, C=DE,
system properties:
O=SAP, OU=Development as
value subjectAndIssuer
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].
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
1262
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Subject DN
Issuer DN
SHA1
9E:6C:EB:
17:91:85:A2:9E:C6:06:0C:A5:3E:
19:74:AF:94:AF:59:D4
5F:B7:EE:06:33:E2:59:DB:AD:0C:4C:
9A:E6:D3:8F:1A:61:C7:DC:25
50:30:06:09:1D:97:D4:F5:AE:
39:F7:CB:E7:92:7D:7D:65:2D:34:31
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
97:81:79:50:D8:1C:96:70:CC:
34:D8:09:CF:79:44:31:36:7E:F4:74
A1:7D:8B:51:8A:8F:BB:DE:A5:00:C8:1E:
96:12:26:16:32:4A:34:C0
8D:71:8C:B5:F4:21:9D:5D:39:0C:
79:04:8A:EA:21:85:54:37:F4:57
4D:11:61:08:30:D7:B3:1C:62:87:19:8E:
95:D5:5F:3E:8F:05:E4:0B
AE:50:83:ED:7C:F4:5C:BC:8F:
61:C6:21:FE:68:5D:79:42:21:15:6E
4C:37:58:79:7A:AE:
43:74:25:FC:D8:D9:CA:7D:
1A:B4:64:0D:CE:37
19:84:90:0F:
64:21:0B:CD:C2:64:D3:77:9C:B8:E6:4E:
CA:07:B2:AB
AA:DB:BC:22:23:8F:C4:01:A1:27:BB:
38:DD:F4:1D:DB:08:9E:F0:12
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1263
Subject DN
Issuer DN
SHA1
91:C6:D6:EE:3E:
8A:C8:63:84:E5:48:C2:99:29:5C:75:6C:
81:7B:81
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
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
E0:AB:
05:94:20:72:54:93:05:60:62:02:36:70:F
7:CD:2E:FC:66:66
9F:AD:91:A6:CE:
6A:C6:C5:00:47:C4:4E:C9:D4:A5:0D:
92:D8:49:79
90:AE:A2:69:85:FF:14:80:4C:
43:49:52:EC:E9:60:84:77:AF:55:6F
67:82:AA:E0:ED:EE:E2:1A:
58:39:D3:C0:CD:14:68:0A:4F:60:14:2A
A1:DB:63:93:91:6F:
17:E4:18:55:09:40:04:15:C7:02:40:B0:A
E:6B
D2:32:09:AD:23:D3:14:23:21:74:E4:0D:
7F:9D:62:13:97:86:63:3A
27:96:BA:E6:3F:
18:01:E2:77:26:1B:A0:D7:77:70:02:8F:
20:EE:E4
27:3E:E1:24:57:FD:C4:F9:0C:55:E8:2B:
56:16:7F:62:F5:32:E5:47
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
7C:46:56:C3:06:1F:7F:4C:0D:
67:B3:19:A8:55:F6:0E:BC:11:FC:44
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.
Related Information
Deploying and Updating Applications [page 973]
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.
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.
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.
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1269
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.
1270
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Tip
The default name of the exported file is localusers.json. You can rename it to something more
meaningful to you.
"Users": [
{
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.
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
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].
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:
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.
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
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.
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 .
Security
Trust
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.
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
2. From the table, choose the entry localidp, open the Attributes tab page, and click on Add Assertion-Based
Attribute.
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. 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.
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
Security
Trust
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
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.
Descrption
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
Note
When you select Trusted SAML 2.0 identity provider,
Application-to-Application SSO becomes enabled automat
ically.
OAuth 2.0 token
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.
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.
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.
Term
Description
Predefined roles
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
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.
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].
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.
Applications
Java Applications
section.
Applications
Subscriptions
section.
Procedure
1. In the cockpit, go to the
Security
Authorizations
Authorizations
Security
Roles
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.
Security
Roles
section.
1286
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Alternatively, you can do it using the Authorizations section for the account.
a. In the cockpit, go to the
Security
Authorizations
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.
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.
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
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.
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
Regular expression
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.
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
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.
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
Security
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
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.
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
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.
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
account
tenant
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
Force authentication
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.
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.
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.
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
section.
1296
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Field
Description
Metadata File
Name
Description
Signature Algorithm
Signing Certificate
User ID Source
Source Value
User ID Prefix
User ID Suffix
Enabled
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1297
Field
Description
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.
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:
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.
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
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.
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.
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
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.
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.
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]
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1305
Value
Description
com.sap.cloud.security.um.u
ser_provider_name
onpremise
com.sap.cloud.security.um.d
estination_name
<on-premise_destination_name>
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.
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.
Value
Description
Name
<on-premise_destination_name>
com.sap.cloud.security.um.d
estination_name.
Type
HTTP
URL
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
User
<user name>
Password
<password>
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.
Context
Value
Description
com.sap.cloud.security.um.u
ser_provider_name
onpremise
com.sap.cloud.security.um.d
estination_name
<on-premise_destination_name>
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1309
1.8.3.3.7
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]
Procedure
1. In your Web browser, log on to the cockpit, and select an account. See Cockpit [page 84].
2. In the
Security
OAuth
1310
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Description
Name
Description
Application
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1311
Field
Description
Note
The client ID must be globally unique within the entire
SAP HANA Cloud Platform.
Confidential
Secret
Redirect URI
Token Lifetime
Translations
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.
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
Security
section.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1313
Security
Authorizations
Token
section.
Security
OAuth
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.
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.
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.
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.
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1317
1.8.3.3.8
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.
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.
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
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.
Value Description
Example
Audience
Cockpit
Security
Provider Name
Local
).
<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
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1321
Value Description
Example
Issuer ID
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>
).
Sample Code
Trust
Cockpit
Trusted Identity
<ds:X509Certificate>
</
ds:X509Certificate>
).
<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>
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.
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
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
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
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
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.
about XSS protection on the SAP HANA Cloud Platform, see Protecting from Cross-Site Scripting (XSS) [page
1243].
1.8.4.6
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
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.
Persistence
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.
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
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].
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1327
Examples
Example for a notification mail announcing updated EU1 landscape:
1328
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1329
1330
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Description
Description
A note is added explaining that for trial accounts only the Lite edition is
available.
Description
Description
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1331
Description
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
Added a note that you must have created a schema previously to be able to
Table 397:
Documentation
Description
Description
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
Added examples for both productive and trial multitenant database contain
ers (MDC).
Added a screenshot for the step where you enter your database user name
and password.
1332
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
Documentation
Description
Added the prerequisite that you need the connection details, which you ob
tained when you opened the database tunnel, to perform the procedure.
Added a note that newly created SAP HANA XS applications are only visible
59]
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.
Added the field name where you have to enter the URL when you install new
[page 37]
software in Eclipse.
The procedure now reflects the changed behavior of the SAP Web IDE.
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).
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
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.
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1333
February 4, 2016
Table 402:
Documentation
Description
[page 1176]
tions.
A new prerequisite has been added to ensure the correct setup of the SAP
HANA Cloud Platform Tools.
Explained how to proceed after the SDK archive file is downloaded and ex
tracted in more detail.
Description
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.
December 3, 2015
Table 404:
Documentation
Description
Description
Description
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).
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
Links to Updating Java Tools for Eclipse and SDK [page 43] and SAP Devel
33]
A new step was added to the procedure describing that you need to select
A new step was added to the Create a Dynamic Web Project and Servlet pro
cedure describing that you need to select the Generate web.xml deployment
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.
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).
PUBLIC
2016 SAP SE or an SAP affiliate company. All rights reserved.
1337
go.sap.com/registration/
contact.html