Introduction
In the quest to understand Cloud Application Programming (CAP) model and Core Data & Services (CDS), I started reading blogs and trying some very good missions available in SAP tutorials. Coming from SAP Commerce background, many things were kind of new and completely different for me to start the journey in CAP and CDS.
Thanks to the great documentation provided by SAP on this topic and great developer community for sharing experiences through blogs.
When I was doing the hands on, lot of questions came to my mind and I read related material along the way. So I have provided references at various places which will help you to navigate quickly to the reference material.
Quick Recap -
What is CAP - Cloud Application Programming?
- It is a collection of tools, languages and libraries to efficiently develop cloud services and applications to help enterprises scale. Link
What is CDS - Core Data & Service?
- CDS is a foundation for CAP. It is a declarative approach towards programming. Link
What is BAS - Business Application Studio and how it is different from SAP Web IDE?
- We think it is same but it is not. This blog will help you understand it.
The above links are best source of information, if you want to deep dive into CAP and CDS.
To get a flavor of how easy is to set up the BTP services, I tried to give an example of SAP HANA and SAP XSUAA, both of which are available as a service on SAP BTP. Most likely, you will surely need these two services in most of the projects as these are two pillars of enterprise applications -
Persistence and Authorization.
At the end of this hands on exercise, you will accomplish below 5 tasks -
- Create CAP Java REST Services to create user and assign roles.
- Integrate with HANA database (HANA HDI on SAP BTP).
- Deploy the project on SAP BTP Cloud Foundry environment.
- Enable authentication and authorization using SAP BTP XSUAA service.
- Test REST APIs through REST client (POSTMAN).
Let us get started!
Task - 1 : Create a CAP JAVA REST Service
Quick Project Set Up
- Open BAS from your sub account.
- Go inside your project directory (/home/user/projects) and execute the below maven command
mvn -B archetype:generate -DarchetypeArtifactId=cds-services-archetype -DarchetypeGroupId=com.sap.cds \ -DarchetypeVersion=RELEASE \
-DgroupId=com.sap.cap -DartifactId=task-manager -Dpackage=com.sap.cap.taskmanager
- This will initialize maven archetype and create a new project with name - task-manager with standard folder structure.
Define Data Model
- The db folder contains data-model.cds where you define database entities/artifacts.
- In this I have defined two entities (Roles and Users) with columns.
namespace sap.capire.taskmanager;
using {
cuid,
managed
} from '@sap/cds/common';
entity Roles : cuid, managed {
name : String(50);
active : Boolean;
}
entity Users : cuid, managed {
firstName : String;
lastName : String;
email : String;
phone : String;
password : String;
active : Boolean;
userRole : Association to one Roles @assert.target;
}
- I have demonstrated to reuse some aspects (cuid, managed) exposed by cds/common. Quick look
- In this I have tried to defined relationship between entities using Association.
- Relationships can be of 2 types
- Associations - This relationship is loosely coupled. By this, I mean, if parent is deleted, it will not affect children.
- Compositions - This relationship is tightly coupled. By this, I mean, parent is a container for all children. If parent is deleted, it will delete all the children.
There is lot to understand and learn in the CDS Definition Language (CDL). The best source of truth is
here. But to get started, above 4 points are sufficient.
Define Admin Service
- In this section, we will define a service to expose the data model we created in above step.
- Think of this as a wrapper/abstraction on top of your entities.
- In the srv/src folder, create a file with name - admin-service.cds.
using { sap.capire.taskmanager as db } from '../db/data-model';
service AdminService {
entity Role as projection on db.Roles;
entity User as projection on db.Users;
}
We completed Task 1 here!
Task - 2 : Integrate with HANA (HANA HDI on SAP BTP)
- Open your dev space. Go to Cloud Foundry Environment and get the API Endpoint. This is the CF environment where you will create your HANA database service.
- Open terminal, set API and login to your cf environment. Best place to learn cloud foundry CLI is here
- Add below dependency in pom.xml to enable HANA database integration through CDS.
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-feature-hana</artifactId>
</dependency>
- Open the file .cdsrc.json and add the deployment format as shown below
{
"hana" : {
"deploy-format": "hdbtable"
}
}
- As part of this project we will be relying on shared HANA instance which is HDI container. Very obvious question - What is the difference and what is HDI. Very nicely explained here
- Create HANA service and push database artifacts which will create tables in database schema by executing the below command in your project root directory.
cds deploy --to hana:taskmanager-hana --store-credentials
- Refer the default-env.json file in your root project directory for details about the HANA service created by above command.
Task - 3 : Deploy the project on SAP BTP Cloud Foundry environment.
- Create manifest.yml file in your project root directory which describes the application It will also define the services which binds to your application once deployed on cloud.
---
applications:
- name: task-manager
path: srv/target/task-manager-exec.jar
random-route: true
services:
- taskmanager-hana
- In pom.xml and add cds cloud foundry dependency as shown below
<dependency>
<groupId>com.sap.cds</groupId>
<artifactId>cds-starter-cloudfoundry</artifactId>
<version>${cds.services.version}</version>
</dependency>
- Build the application mvn clean install and push to cloud foundry with cf push command.
Task - 4 : Enable authentication and authorization using SAP BTP XSUAA service.
- Create file xs-security.json in your project root directory with the help of following command which will create file with a skeleton and sample values
cds compile srv/ --to xsuaa > xs-security.json
- Give name of your application in the xsappname and give a name to the role_collections in the xs-security.json
{
"xsappname": "task-manager",
"tenant-mode": "dedicated",
"scopes": [
{
"name": "$XSAPPNAME.Administrators",
"description": "Administrators"
}
],
"attributes": [],
"role-templates": [
{
"name": "Administrators",
"description": "generated",
"scope-references": [
"$XSAPPNAME.Administrators"
],
"attribute-references": []
}
],
"role-collections": [
{
"name": "task-manager_Administrators",
"description": "Task Manager Administrators",
"role-template-references": ["$XSAPPNAME.Administrators"]
}
]
}
- Do not forget to add your user id in this role collection from BTP portal security section.
- Add XSUAA service in manifest.yml
---
applications:
- name: task-manager
path: srv/target/task-manager-exec.jar
random-route: true
services:
- taskmanager-hana
- taskmanager-xsuaa
- Create instance of XSUAA service on BTP CF environment
cf create-service xsuaa application taskmanager-xsuaa -c xs-security.json
- Build and push the application on CF environment.
- To get the details of the application execute the below command
cf app task-manager
Task - 5 : Test your REST APIs with POSTMAN
- Open terminal and execute the below command
cf env task-manager
- The above command provides the service binding details for your application.
- Look for the service xsuaa → credentials. Grab the attributes -
- url
- clientId
- clientSecret
- Open POSTMAN and create collection with name - SAP BTP
- In the Authorization tab of the collection, enter the below details -
- Callback URL - <Your application url>
- Auth URL - Authorization url taken from point 3 appended with /oauth/authorize
- Access Token URL - Authorization url taken from point 3 appended with /oauth/token
- Client ID - clientId from point 3
- Client Secret - clientSecret from point 3
- Client Authentication - Select option - Send client credentials in body
- After entering all the above details, click on "Get Access Token". Do not forget to save the token in the collection
- Now create a new post man request under the collection and set the authorization type as "Inherit auth from parent"
Conclusion
I hope, this quick 5 minutes blog will help you to jump start your journey in CAP and BTP. Stay curious! Keep learning!
