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

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 runs 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

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