Getting Started in a Nutshell

Using a minimalistic setup

Get started in a minimalistic setup with Node.js, express and SQLite.
See also: Java-based variant of this guide.

You will learn, step-by-step, how to do the following:

• Jumpstarting Projects
  • Download from cap/samples
  • Launch cds watch
• Defining Domain Models
  • Deployed to Databases Automatically
  • Compiling Models (Optional)
• Defining Services
  • One for admins to maintain Books and Authors
  • One for end users to browse and order Books
  • Served to OData out-of-the-box
  • Compiling APIs (optional)
• Using Databases
  • Using sqlite In-Memory Database
  • Adding Initial Data in .csv Files
  • Querying through OData out-of-the-box
  • Deploying Persistent Databases
• Adding/Serving UIs
  • For example, Vue.js UIs
  • For example, Fiori UIs
  • Using OData protocol
• Adding Custom Logic
  • Providing Service Implementations
  • Adding Custom Event Handlers
  • Consuming Other Services
• Summary and Next Steps…

Jumpstarting Projects

After installing @sap/cds-dk globally, create a project with minimal defaults as follows:

cds init bookshop

To copy code snippets, click the icon in the upper-right corner of the code snippet.

Download from cap/samples

Instead of going for a manual step-by-step experience, you can also get the cap/samples from GitHub:

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

Launch cds watch

For a completely automated jumpstart, you can just tell cds to watch out for things to arrive:

cds watch bookshop

Use cds watch to start a cds server, even in a newly created and yet empty project. Whenever you feed your project with new content, for example, by adding or modifying .cds, .json, or .js files, the server automatically restarts to serve the new content. Because there isn’t any content in your project yet, it just keeps waiting with a message like this:

[cds] - running nodemon...
--ext cds,csn,csv,ts,mjs,cjs,js,json,properties,edmx,xml

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

Defining 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:

db/schema.cds

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 Learn more about Domain Modeling Learn more about CDS Modeling Languages

Deployed to Databases Automatically

As soon as you save your file, the still running cds watch will react immediately with new output like this:

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

This means that cds watch detected the changes in db/schema.cds and automatically bootstrapped an in-memory SQLite database when restarting the server process.

Learn more about using databases below

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

Defining Services

After the recent changes, cds watch also printed this message:

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

So, let’s go on feeding it with service definitions. Following the best practice of single-purposed services, we define two services for different use cases.

One for admins to maintain Books and Authors

srv/admin-service.cds

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;
}

Find this source also in cap/samples

One for end users to browse and order Books

srv/cat-service.cds

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, amount: Integer);
}

Find this source also in cap/samples Learn more about Defining Services

Served to OData out-of-the-box

This time cds watch reacted with additional output like that:

[cds] - serving AdminService { at: '/admin' }
[cds] - serving CatalogService { at: '/browse', impl: 'bookshop/srv/cat-service.js' }
[cds] - launched in: 744.291ms
[cds] - server listening on { url: 'http://localhost:4004' }

As can be read from the log output, the two service definitions have been compiled and generic service providers have been constructed to serve requests on the listed endpoints /admin and /browse.

Open http://localhost:4004 in your browser and see the generically provided index.html page:

Compiling APIs (optional)

As above, you can also compile service definitions explicitly, for example to an OData model:

cds srv/cat-service.cds -2 edmx

Essentially, this invokes through CLI what happened automatically behind the scenes in the steps before. While we don’t need such explicit compile steps, you can do that, for example to test correctness on model level.

Using Databases

Using sqlite In-Memory Database

As previously shown, cds watch automatically bootstraps a 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 the Grow as you go guide

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 so:

db/data/sap.capire.bookshop-Books.csv

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

db/data/sap.capire.bookshop-Authors.csv

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

After you added these files, cds watch restarts the server with an output, telling us the files have been detected and their content been loaded into the database automatically:

[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 sqlite in-memory db

This is the output when you’re using the samples. It’s less if you’ve followed the manual steps here.

Learn more about Using Databases

Querying through OData out-of-the-box

As we now have a fully capable SQL database connected filled with some initial data, we can send complex OData queries, served by the built-in generic providers:

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

Learn more about Generic Providers Learn more about OData’s Query Options

Deploying Persistent Databases

Instead of using in-memory, we can also use persistent databases. For example, still with SQLite:

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

The difference to the automatically provided in-memory database is that we now get a persistent database stored in the local file ./my.db. This is also recorded in the package.json.

To see what that did, use the sqlite3 cli with the newly created database:

sqlite3 my.db .dump
sqlite3 my.db .tables

Similarly, you could deploy to a provisioned SAP HANA database using this variant:

cds deploy --to hana

Adding/Serving UIs

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

For example, Vue.js UIs

For example, 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.

For example, Fiori UIs

Besides being usable from any UI frontends using standard AJAX requests, CAP provides out-of-the-box support for Fiori UIs, for example, with respect to Fiori Annotations and advanced features like Search, Value Helps and 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, like $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 would add custom code to care for the specific domain logic of your application.

Providing Service Implementations

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

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

See these files also in cap/samples/bookshop/srv folder Learn more about providing service implementations, such as using @impl Learn also how to do that in Java using Event Handler Classes

Adding Custom Event Handlers

Service implementations essentially consist of one or more event handlers. Copy this into srv/cat-service.js to add custom event handlers:

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

Learn more about adding event handlers using <srv>.on/before/after Learn also how to do that in Java using Event Handler Methods

Consuming Other Services

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

srv/cat-service.js

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,amount} = req.data
    const n = await UPDATE (Books, book)
      .with ({ stock: {'-=': amount }})
      .where ({ stock: {'>=': amount }})
    n > 0 || req.error (409,`${amount} exceeds stock for book #${book}`)
  })

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

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

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…

• Jumpstart, Grow-as-you-go and Airplane Mode
• Domain Modeling
• Defining Services and APIs
• Using Generic Providers
• Consuming Services
• Using Databases
• Adding Custom Logic
• Adding/Serving UIs

Visit our Cookbook to find more task-oriented guides, including the ones listed above. For example, find there guides about potential next steps such as adding Authentication and Authorization or Deploying to Cloud.

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