Creating a CAP-Based Service

Create and Initialize the Project.

1. In the Business Application Studio, click on Terminal → New Terminal.

   A new terminal opens in the lower right part of the Business Application Studio screen.

   

2. Enter the following commands to clone the starter template from GitHub and press Enter after each command.

   Code snippet

   Copy code

   mkdir ~/projects/risk-management
   cd ~/projects/risk-management/ 
   git clone https://github.com/SAP-samples/btp-side-by-side-extension-learning-journey ./

   Copy code

   The output in the terminal should then look similar to the following. (Currently there are 23 files in the repository. In the future this could differ).

   

   So the template from GitHub has been cloned successfully. Next, open it in the project explorer.

3. On the Welcome page, click on Files & Folders.

   

4. Now select the risk-management folder in the projects folder and click on Open. The SAP Business Application Studio will now reload to open the folder.

   

5. On the left side you will now see the content of the risk-management folder:

   

6. In Business Application Studio choose Terminal → New Terminal from its menu.

   A new terminal opens in the lower right part of the Business Application Studio screen.

7. In the terminal, run the command:

   Code snippet

   Copy code

   npm ci

   Copy code

   This might take a while. It installs all the dependencies of your project, which are listed in the package.json and package-lock.jsonfile, into a new folder called node_modules within the root of your project. If you encounter messages about Deprecateddependencies ignore them for now, as long as there are no errors in the log.

8. In the terminal, start a CAP server by typing:

   Code snippet

   Copy code

   cds watch

   Copy code

   The CAP server serves all the CAP sources from your project. It also "watches" all the files in your projects and conveniently restarts the server whenever you save a file. Changes you've made will immediately be served without you having to do anything.

9. The terminal now looks like this:

   

   cds watch tells you that there’s no model yet that it can serve. You add one in the next steps.

   In general, you can keep cds watch running in a terminal for the whole exercise. There is no need to restart it or try to add a second instance of it (in fact, if you do this, you get an error, described here). In the follow-up steps, you will open a new browser tab to see the results of cds watch. You can just keep this open and refresh it each time there is a change. cds watch notices any file change and makes sure you get the new results after a refresh in the browser.

Add a Data Model to the Project.

1. In the project, go to folder db, representing the data model on the database. In the context menu, select New File.

2. Enter schema.cds as a name.

3. Click on the new file in the explorer.

   An editor opens.

4. Enter the following lines into the editor

   Code snippet

   Copy code

   namespace riskmanagement;
    using { managed } from '@sap/cds/common';
   
    entity Risks : managed {
    key ID : UUID @(Core.Computed : true);
    title : String(100);
    owner : String;
    prio : String(5);
    descr : String;
    miti : Association to Mitigations;
    impact : Integer;
    //bp : Association to BusinessPartners;
    // You will need this definition in a later step
    criticality : Integer;
    }
   
    entity Mitigations : managed {
    key ID : UUID @(Core.Computed : true);
    descr : String;
    owner : String;
    timeline : String;
    risks : Association to many Risks on risks.miti = $self;
    }

   Copy code

5. Save the file.

   You are using the namespace¹riskmanagement. A namespace is optional. It is helpful to use short unique names without bloating the code with fully qualified names. Essentially, namespaces are just prefixes that are applied to all relevant names in a file automatically.

   The code creates 2 entities in the namespace riskmanagement, Risks, and Mitigations. Each of them has a key called ID and several other properties. A Risk has a mitigation and therefore, the property miti has an association to exactly one Mitigation. A Mitigation in turn can be used for many Risks, so it has a "to many" association. The key is automatically filled by CAP, which is exposed to the user of the service with the annotation @(Core.Computed : true).

   At this point, you can ignore the commented property bp (as well as the other commented lines further down in the file and in subsequent files and steps). You will use the commented lines at a later stage of the project.

   The screen now looks like this:

   

   Notice how cds watch reacted to dropping the file. It now tells you that it has a model but there are no service definitions yet and thus it still can’t serve anything. So, in the next step you will add a service definition.

Add a Service to the Project.

1. In the project, go to folder srv/, representing the service. In the context menu, select New File.

2. Enter risk-service.cds as a name.

3. Click on the new file in the explorer.

   An editor opens.

4. Enter the following lines into the editor:

   Code snippet

   Copy code

   using { riskmanagement as rm } from '../db/schema';
   
    @path: 'service/risk'
    service RiskService {
    entity Risks as projection on rm.Risks;
        annotate Risks with @odata.draft.enabled;
    entity Mitigations as projection on rm.Mitigations;
        annotate Mitigations with @odata.draft.enabled;
    //@readonly entity BusinessPartners as projection on rm.BusinessPartners;
    }

   Copy code

   This creates a new service RiskService in the namespace riskmanagement. The annotation @path: 'service/risk' tells the CAP framework to expose the RiskService at URL path service/risk. The service exposes two entities (again, just ignore the commented part for the business partner), Risks and Mitigations, which are both just exposing the entities of the database schema you’ve created in the step before. The @odata.draft.enabled annotation enables edit sessions with draft states² stored on the server for the UI, that will be added in a later step.

   If you again look at the terminal, you see that cds watch has noticed the new file and now tells us that it serves something:

   

5. Press the Open in New Tab button in the lower right corner.

   

6. If you are asked to enter a name - just press return.

   You now see this screen:

   

7. Click the $metadata link.

   The service already exposes a full-blown OData metadata document.

8. Go back and click on the Risks link.

   This exposes the data for the Risks entity. Since there are already files in the db/datadirectory containing mock data for the database, you will already see data here.

   

   Don't close the window, you will need it again.

   Note

   To see the JSON data in a structured way as shown in the screenshot, you require a browser extension. Without such an extension, the data will just be displayed as plain text without indentations etc.

   Note

   There are a few additional fields like createdAt or modifiedBy which you did not actively define in the entity itself. These were added by CAP, because you added the managed aspect in the entity definition:

   Code snippet

   Copy code

   entity Risks : managed{
       ...
   }

   Copy code

Provide Mock Data for the Service.

1. In the project, go to folder db/ and then into the data/  folder

2. There is already one file called riskmanagement-Risks.csv:

   Code snippet

   Copy code

   ID;createdAt;createdBy;title;owner;prio;descr;miti_id;impact; 
   20466922-7d57-4e76-b14c-e53fd97dcb11;2019-10-24;SYSTEM;CFR non-compliance;Fred Fish;3;Recent restructuring might violate CFR code 71;20466921-7d57-4e76-b14c-e53fd97dcb11;10000;
   20466922-7d57-4e76-b14c-e53fd97dcb12;2019-10-24;SYSTEM;SLA violation with possible termination cause;George Gung;2;Repeated SAL violation on service delivery for two successive quarters;20466921-7d57-4e76-b14c-e53fd97dcb12;90000; 
   20466922-7d57-4e76-b14c-e53fd97dcb13;2019-10-24;SYSTEM;Shipment violating export control;Herbert Hunter;1;Violation of export and trade control with unauthorized downloads;20466921-7d57-4e76-b14c-e53fd97dcb13;200000;

   Copy code

   In a table format, the header and one line of the file content look like the following:

   ID	createdAt	createdBy	title	owner	prio	descr	miti_id	impact
   20466922-7d57-4e76-b14c-e53fd97dcb11	2019-10-24	SYSTEM	CFR non-compliance	Fred Fish	3	Recent restructuring might violate CFR code 71	20466921-7d57-4e76-b14c-e53fd97dcb11	10000

3. There is also another file for the Mitigations entity called riskmanagement-Mitigations.csv.

4. Click on the file in the explorer:

   Code snippet

   Copy code

   ID;createdAt;createdBy;descr;owner;timeline
    20466921-7d57-4e76-b14c-e53fd97dcb11;2019-10-24;SYSTEM;SLA violation: authorize account manager to offer service credits for recent delivery issues;suitable BuPa;Q2 2020
    20466921-7d57-4e76-b14c-e53fd97dcb12;2019-10-24;SYSTEM;"SLA violation: review third party contractors to ease service delivery challenges; trigger budget review";suitable BuPa;Q3 2020 20466921-7d57-4e76-b14c-e53fd97dcb13;2019-10-24;SYSTEM;Embargo violation: investigate source of shipment request, revoke authorization;SFSF Employee with link possible?;29.03.2020
    20466921-7d57-4e76-b14c-e53fd97dcb14;2019-10-24;SYSTEM;Embargo violation: review shipment proceedure and stop delivery until further notice;SFSF Employee with link possible?;01.03.2020

   Copy code

   The files have the name of the namespace of the entities in the data model (for example: riskmanagement), followed by a '-' and the name of the entity (for example: Risks). When adhering to this naming convention, CAP recognizes the file as data for the data model and automatically adds it to the built-in SQLite database. Looking at the contents of the file riskmanagement-Risks.csv, the first line contains all the properties from your Risks entity. While the other ones are straightforward, consider the miti_id property. In your entity, you only have a miti property, so where does this come from? miti is an association to Mitigations, as Mitigations could have several key properties, the association on the database needs to point to all of these. Therefore, CAP creates a property <AssociationProperty>_<AssociatedEntityKey> for each key.

   As always, cds watch has noticed that there are files containing the mock data.

   Other fields like HasDraftEntity were added because you added the @odata.draft.enabled annotation in the service definition (risk-service.cds).

   You’ve now got a full-blown OData service, which complies to the OData standard and supports the respective queries without having to code anything but the data model and exposing the service itself.

   Note

   The service is completely exposed without any authentication or authorization check. You will extend the service later with such checks.

Platform Simulation

Click on the Start button below to open a simulation of the platform. Then follow the step-by-step instructions to create a CAP-based Service.

ExerciseStart Exercise