01. Setting up the environment

Introduction

This exercise will guide you through an end-to-end setup of the incidents management sample with the sandbox enabled and a local multitenancy environment. This exercise assumes you use either BAS or VS.code The initial parts are a fast-tracked summary of the reCAP Extensibility workshop from 2024, which can be found here, so if you get stuck or need additional explanations, you can also utilize this resource.

The Development Environment

This tutorial works with any suitable environment of your choice. If you already have VSCode installed, you are good to go. If you prefer to use a plain text editor, ensure you have the tools installed for cloning a Git repository and running commands in a shell. If you're not sure how to proceed, please visit the Tools Guide on Capire.

If you want to use BAS for the workshop, we have prepared something for you:

Optional: A Dev Space in the SAP Business Application Studio

For re>≡CAP 2025 we have prepared a BTP Subaccount you can use. If you work through this on your own, you can use a BTP trial account.

Login to BAS: https://capworkshop-2c236002-84a3-57ec-94ee-67921d010585.eu10cf.applicationstudio.cloud.sap/

Select aoykcp1ee.accounts.ondemand.com on the Login screen:

User: [email protected] (001 ... 040 is the range)
Password: *** (shared in Workshop)

Incognito mode is your friend. In case you get logged in using your regular user, use incognito mode or clear your browser cookies.

Create a BAS Dev Space

Choosing the "Full Stack Cloud Application" brings in some predefined extensions, as you can see from the screenshot, including a CDS Graphical Modeler and the CAP Tools.

You may need to stop existing Dev Spaces to use this one, depending on your subscription access.

Set up incidents management

Create a new instance of the incidents management sample by cloning from https://github.com/cap-js/incidents-app.git and switching to the recap25 branch

Note

The reCAP25branch contains a minor fix to workaround an issue in the incidents app regarding req.subject in srv/processor-service.js

Enable Multitenancy

In a terminal, run

cds add mtx --for development` 

to enable the MTX sidecar with extensibility turned on. To add the CDS-OYSTER plugin, add the following line to your dependencies in package.json of both, the root project and the mtx/sidecar project

"@sap/cds-oyster": "^0.1.0"

please run

npm i

in the root folder of the project to get all dependencies up and running.

Please inspect your package.json - if the multitenancy parameter is embedded within a [production] bracket, please remove that, so that local testing works as planned.

Please also verify that the modules cds-oyster, oyster-runtime and oyster-runtime-specific-to-your-hardware are present in your node_modules/@sap/ folder.

Enable Sandbox

Modify the package.json of the project root to enable the code sandbox and add the required roles (cds.ExtensionDeveloper and cds.Subscriber) to alice

"cds": {
    "requires": {
      "code-extensibility": {
        "runtime": "oyster",
        "maxTime": 1000,
        "maxMemory": 4
      },
      "auth": {
        "[development]": {
          "users": {
            "alice": {
              "roles": [
                "support",
                "admin",
                "cds.ExtensionDeveloper",
                "cds.Subscriber"
              ]
            },
  ...          

You can test the setup using three distinct terminal windows. In VS Code we suggest using the split window feature to have all terminals visible simultaneously

• Terminal 1
  Run

  cds watch

  on project root level. It should report running on port 4004.

• Terminal 2
  Is needed to run the MTX sidecar using

  cds watch mtx/sidecar

  This should report for port 4005. Please keep these two terminals running while testing the setup.

• In Terminal 3
  You can subscribe a new tenant t1 for alice using

  cds subscribe t1 --to http://localhost:4005 -u alice:

  and test it by using the link in Terminal 1 or go directly to http://localhost:4004/incidents/webapp/index.html

Note

We have mock authorization enabled for this project. When prompted for a user, please use alice with an empty password

In the Second exercise — Creating the extension, we will start with creating the extension project.