Getting Started in a Nutshell ​

Using a minimal setup

This guide is a step-by-step walkthrough to build a CAP application, using a minimal setup with Node.js and SQLite.

⓪ Preliminaries ​

1. Prerequisite: The following steps assume you've installed Node.js, Visual Studio Code, and @sap/cds-dk as described in the Setup section of the Jumpstart guide.

2. Hands-On Walkthrough: The sections below describe a hands-on walkthrough, in which you'd create a new project and fill it with content step by step.

3. Option: Download from GitHub – Instead of going for this hand-on step-by-step experience, you can get the final sample content from GitHub. If you choose to do so clone the repo as follows:

git clone https://github.com/sap-samples/cloud-cap-samples samples
cd samples
npm install

git clone https://github.com/sap-samples/cloud-cap-samples-java bookshop

Just keep in mind that the sample code on GitHub is an already complete application showcasing a lot of features. So you might find more code in the app than in the code that is created in this step-by-step guide.

① Jumpstart a Project ​

1. Create a new project using cds init

cds init bookshop

cds init bookshop --add java

2. Open the project in VS Code

code bookshop

3. Run cds watch in an Integrated Terminal

cds watch

cd srv && mvn cds:watch

[dev] cds w

cds serve all --with-mocks --in-memory?
live reload enabled for browsers

      ___________________________

   No models found in db/,srv/,app/,schema,services. 
   Waiting for some to arrive... 

② Capture Domain Models ​

Let's feed our project by adding a simple domain model. Start by creating a file named db/schema.cds (also indicated in the code box's label) and copy the following definitions into it:

using { Currency, managed, sap } from '@sap/cds/common';
namespace sap.capire.bookshop; 

entity Books : managed { 
  key ID : Integer;
  title  : localized String(111);
  descr  : localized String(1111);
  author : Association to Authors;
  genre  : Association to Genres;
  stock  : Integer;
  price  : Decimal(9,2);
  currency : Currency;
}

entity Authors : managed { 
  key ID : Integer;
  name   : String(111);
  books  : Association to many Books on books.author = $self;
}

/** Hierarchically organized Code List for Genres */
entity Genres : sap.common.CodeList { 
  key ID   : Integer;
  parent   : Association to Genres;
  children : Composition of many Genres on children.parent = $self;
}

Find this source also in cap/samples for Node.js, and for JavaLearn more about Domain Modeling.Learn more about CDS Modeling Languages.

Deployed to Databases Automatically ​

[cds] - connect to db { database: ':memory:' }
/> successfully deployed to in-memory database.

Compiling Models (Optional) ​

We can also test-compile models individually to check for validity and produce a parsed output in CSN format. For example, run this command in a new terminal:

cds db/schema.cds

This dumps the compiled CSN model as a plain JavaScript object to stdout.
Add --to <target> (shortcut -2) to produce other outputs, for example:

cds db/schema.cds -2 json
cds db/schema.cds -2 yml
cds db/schema.cds -2 sql

Learn more about the command line interface by executing cds help.

③ Providing Services ​

No service definitions found in loaded models.
Waiting for some to arrive...

So, let's go on feeding it with two service definitions for different use cases:

• An AdminService for administrators to maintain Books and Authors
• A CatalogService for end users to browse and order Books

Create the following two files in folder ./srv and fill them wih this content:

using { sap.capire.bookshop as my } from '../db/schema';
service AdminService @(requires:'authenticated-user') { 
  entity Books as projection on my.Books;
  entity Authors as projection on my.Authors;
}

using { sap.capire.bookshop as my } from '../db/schema';
service CatalogService @(path:'/browse') { 

  @readonly entity Books as SELECT from my.Books {*,
    author.name as author
  } excluding { createdBy, modifiedBy };

  @requires: 'authenticated-user'
  action submitOrder (book: Books:ID, quantity: Integer);
}

Find this source also on GitHub for Node.js, and for JavaLearn more about Defining Services.

Served to OData out of the box ​

[cds] - serving AdminService { at: '/admin' }
[cds] - serving CatalogService { at: '/browse', impl: 'bookshop/srv/cat-service.js' }

[cds] - server listening on { url: 'http://localhost:4004' }

c.s.c.services.impl.ServiceCatalogImpl : Registered service AdminService
c.s.c.services.impl.ServiceCatalogImpl : Registered service CatalogService

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-security</artifactId>
</dependency>

Compiling APIs (Optional) ​

You can also compile service definitions explicitly, for example to an OData model:

cds srv/cat-service.cds -2 edmx

Essentially, using a CLI, this invokes what happened automatically behind the scenes in the previous steps. While we don't really need such explicit compile steps, you can do this to test correctness on the model level, for example.

④ Using Databases ​

Using sqlite In-Memory Database ​

As previously shown, cds watch automatically bootstraps an SQLite in-process and in-memory database by default — that is, unless told otherwise. While this isn't meant for productive use, it drastically speeds up development turn-around times, essentially by mocking your target database, for example, SAP HANA.

Learn more about mocking options in Grow as you go.

Using H2 In-Memory Database ​

As previously shown, mvn cds:watch automatically bootstraps an H2 in-process and in-memory database by default — that is, unless told otherwise. While this isn't meant for productive use, it drastically speeds up turn-around times in local development and furthermore allows self-contained testing.

Adding Initial Data in .csv Files ​

Now, let's fill your database with initial data by adding a few plain CSV files under db/data like this:

ID,title,author_ID,stock
201,Wuthering Heights,101,12
207,Jane Eyre,107,11
251,The Raven,150,333
252,Eleonora,150,555
271,Catweazle,170,22

ID,name
101,Emily Brontë
107,Charlotte Brontë
150,Edgar Allen Poe
170,Richard Carpenter

Find a full set of .csv files in cap/samples.

[cds] - connect to db { database: ':memory:' }
 > filling sap.capire.bookshop.Authors from bookshop/db/data/sap.capire.bookshop-Authors.csv
 > filling sap.capire.bookshop.Books from bookshop/db/data/sap.capire.bookshop-Books.csv
 > filling sap.capire.bookshop.Books_texts from bookshop/db/data/sap.capire.bookshop-Books_texts.csv
 > filling sap.capire.bookshop.Genres from bookshop/db/data/sap.capire.bookshop-Genres.csv
 > filling sap.common.Currencies from common/data/sap.common-Currencies.csv
 > filling sap.common.Currencies_texts from common/data/sap.common-Currencies_texts.csv
/> successfully deployed to in-memory database.

c.s.c.s.impl.persistence.CsvDataLoader   : Filling sap.capire.bookshop.Books from db/data/sap.capire.bookshop-Authors.csv
c.s.c.s.impl.persistence.CsvDataLoader   : Filling sap.capire.bookshop.Books from db/data/sap.capire.bookshop-Books.csv

Learn more about Using Databases.

Querying Through OData Out of the Box ​

Now that we've a connected, fully capable SQL database, filled with some initial data, we can send complex OData queries, served by the built-in generic providers:

• …/Books?$select=ID,title
• …/Authors?$search=Bro
• …/Authors?$expand=books($select=ID,title)
• …/Books?$select=ID,title
• …/Authors?$search=Bro
• …/Authors?$expand=books($select=ID,title)

Use alice as user to query the admin service. You don't need to enter a password.

Use authenticated to query the admin service. You don't need to enter a password.

Learn more about Generic Providers.Learn more about OData's Query Options.

npm add sqlite3 -D
cds deploy --to sqlite:my.sqlite

sqlite3 my.sqlite .dump
sqlite3 my.sqlite .tables

cds deploy --to hana

Learn more about deploying to SAP HANA.

⑤ Adding/Serving UIs ​

You can consume the provided services, for example, from UI frontends, using standard AJAX requests. Simply add an index.html file into the app/ folder, to replace the generic index page.

Vue.js UIs ​

For example, you can find a simple Vue.js app in cap/samples, which demonstrates browsing and ordering books using OData requests to the CatalogService API we defined above.

SAP Fiori UIs ​

Besides, being usable from any UI frontends using standard AJAX requests, CAP provides out-of-the-box support for SAP Fiori UIs, for example, with respect to SAP Fiori annotations and advanced features such as search, value helps and SAP Fiori draft.

Learn more about Serving Fiori UIs.

Using OData Protocol ​

As CAP-based services are full-fledged OData services out of the box, you can use advanced query options, such as $select, $expand, $search, and many more.

Learn more about Serving OData Protocol.

⑥ Adding Custom Logic ​

While the generic providers serve most CRUD requests out of the box, you can add custom code to deal with the specific domain logic of your application.

Providing Service Implementations ​

In Node.js, the easiest way to provide implementations for services is through equally named .js files placed next to a service definition's .cds file:

./srv
  - cat-service.cds  # service definitions
  - cat-service.js   # service implementation
...

@Component
@ServiceName(CatalogService_.CDS_NAME)
public class CatalogHandler implements EventHandler {
  // your custom code will go here
}

Adding Custom Event Handlers ​

Service implementations essentially consist of one or more event handlers.

const cds = require('@sap/cds')
module.exports = function (){
  // Register your event handlers in here, for example, ...
  this.after ('READ','Books', each => {
    if (each.stock > 111) {
      each.title += ` -- 11% discount!`
    }
  })
}

@After(event = CqnService.EVENT_READ, entity = Books_.CDS_NAME)
public void addDiscountIfApplicable(List<Books> books) {
	for (Books book : books) {
		if (book.getStock() > 111) {
			book.setTitle(book.getTitle() + " -- 11% discount!");
		}
	}
}

Consuming Other Services ​

Quite frequently, event handler implementations consume other services, sending requests and queries, as in the completed example below.

const cds = require('@sap/cds')
module.exports = async function (){

  const db = await cds.connect.to('db') // connect to database service
  const { Books } = db.entities         // get reflected definitions

  // Reduce stock of ordered books if available stock suffices
  this.on ('submitOrder', async req => {
    const {book,quantity} = req.data
    const n = await UPDATE (Books, book)
      .with ({ stock: {'-=': quantity }})
      .where ({ stock: {'>=': quantity }})
    n > 0 || req.error (409,`${quantity} exceeds stock for book #${book}`)
  })

  // Add some discount for overstocked books
  this.after ('READ','Books', each => {
    if (each.stock > 111)  each.title += ` -- 11% discount!`
  })
}

@Component
@ServiceName(CatalogService_.CDS_NAME)
public class SubmitOrderHandler implements EventHandler {

	private final PersistenceService persistenceService;

	public SubmitOrderHandler(PersistenceService persistenceService) {
		this.persistenceService = persistenceService;
	}

	@On()
	public void onSubmitOrder(SubmitOrderContext context) {
		Select<Books_> byId = Select.from(cds.gen.catalogservice.Books_.class).byId(context.getBook());
		Books book = persistenceService.run(byId).single().as(Books.class);
		book.setStock(book.getStock() - context.getQuantity());

		persistenceService.run(Update.entity(Books_.CDS_NAME).data(book));

		context.setCompleted();
	}
}

Find this source also in cap/samples.Find this source also in cap/samples.Learn more about connecting to services using cds.connect.Learn more about connecting to services using @Autowired, com.sap.cds.ql, etc.Learn more about reading and writing data using cds.ql.Learn more about reading and writing data using cds.ql.Learn more about using reflection APIs using <srv>.entities.Learn more about typed access to data using the CAP Java SDK.

Test this implementation, for example using the Vue.js app, and see how discounts are displayed in some book titles.

Or submit orders until you see the error messages.

Summary and Next Steps ​

With this getting started guide we introduced many of the basics of CAP, such as:

• Jump-Starting Projects and Grow-as-you-go
• Domain Modeling
• Defining Services and APIs
• Providing Services
• Consuming Services
• Using Databases
• Adding/Serving UIs
• Adding Custom Logic

Visit our Cookbook to find more task-oriented guides. For example, you can find guides about potential next steps such as adding Authentication and Authorization or Deploying to SAP BTP.

Also see the reference sections to find detailed documentation about CDS, as well as Node.js and Java Service SDKs and runtimes.