Extend SAP SuccessFactors on SAP BTP with CAP – Define the CDS Data Model

Prerequisites

To follow-up with this blog post you must have read and completed the following previous blog posts in this series:

• Series introduction and preparation
• Jumpstart the CAP Project
• Import SAP SuccessFactors OData Services definitions

Data Model Review

Before we move on with the coding, let’s just quickly review the conceptual data model of our solution:

Figure 1 – Data Model Diagram

The logical model depicted in the diagram above has been conceived to comply with the following business rules:

1. Each project is composed by members (team) and activities;
2. The project team (members) is made of SuccessFactors employees;
3. Each project member has an specific role in the project;
4. Each project activity is assigned to a specific project member;
5. Projects and activities have one status each (i.e. not started, in progress, overdue, completed etc.);
6. And last, but not least, whenever a team member is assigned to a project, a special assignment is registered to the employee’s background to signal that such employee has participated in the project, acting in a specific role, as part of the employee’s professional experience.

Now, having that model in mind, let’s make its definition into the CAP project.

Create CDS Data Model File

1. On the left-hand pane of SAP Business Application Studio, select the db folder, then click on the three dots to the right of the project name and select New File

Figure 2 – Create New File

2. On the dialog name the file projman-model.cds and click OK

Figure 3 – Set File Name

Model Coding

Copy and paste the code snippet below into the recently created file:

using {
    cuid,
    sap
} from '@sap/cds/common';

namespace sfsf.projman.model.db;

entity Project : cuid {
    name        : String(128);
    description : String(1024);
    startDate   : Date;
    endDate     : Date;
    status      : Association to one Status;
    team        : Composition of many Member
                      on team.parent = $self;
    activities  : Composition of many Activity
                      on activities.parent = $self;
}

entity Member : cuid {
    parent        : Association to one Project;
    member        : Association to one Employee;
    role          : Association to one Role;
    hasAssignment : Boolean default false;
}

entity Activity : cuid {
    parent      : Association to one Project;
    assignedTo  : Association to one Member;
    name        : String(128);
    description : String(1024);
    dueDate     : Date;
    status      : Association to one Status;
}

@readonly
@cds.autoexpose
entity Employee {
    key userId          : String(100);
        username        : String(100);
        defaultFullName : String;
        email           : String;
        division        : String(128);
        department      : String(128);
        title           : String(255);
}

@readonly
@cds.autoexpose
entity Role : sap.common.CodeList {
    key ID : Integer;
}

@readonly
@cds.autoexpose
entity Status : sap.common.CodeList {
    key ID          : Integer;
        criticality : Integer;
}

Let’s quickly analyze the model code:

First we import some ready-to-use common aspects from the CAP framework: cuid (common universal unique id) and sap (from where we get the Codelist aspect). To learn more about the common types and aspects you can read this section from the CAP official documentation. The cuid aspect automatically defines a UID primary key for entities Project, Member and Activity.

Then we define a namespace to contain the data model (sfsf.projman.model.db) and through which we will refer to it in the future.

Finally, we define each entity with its corresponding attributes and associations according to the model diagram. You’ll notice that the Project entity is “composed” by a team made of members who are employees and activities assigned to the team members, exactly as depicted in the diagram.

We specify that the entities Employee (the “bridge” between SuccessFactors users and our local model), Role and Status are “read-only” via the @readonly annotation. We also want those entities to be automatically exposed in our CAP service without having to explicitly do it in the service definition (the next step of the development), so we annotate them with the @cds.autoexpose annotation as well.

Initial Test Data

Now, let’s populate our data model with some initial test data. This can be done by creating some files in CSV format into a subfolder of the db folder named “data” with the specific naming convention of <namespace>-<entity name>.csv.

1. In the root folder of your project on the Terminal, type cd db and press Enter

Figure 4 – Change to db directory

2. Type mkdir data and press Enter

Figure 5 – Create data directory

3. Type cd data and press Enter

Figure 6 – Change to data directory

4. Type the sequence of commands below pressing Enter after each one:

• touch sfsf.projman.model.db-Role.csv
• touch sfsf.projman.model.db-Status.csv
• touch sfsf.projman.model.db-Employee.csv
• touch sfsf.projman.model.db-Project.csv
• touch sfsf.projman.model.db-Member.csv
• touch sfsf.projman.model.db-Activity.csv

Figure 7 – Create CSV files for initial test data

5. On the left-hand pane, expand the data folder to view the recently created files, then click on the sfsf.projman.model.db-Role.csv file to open it

Figure 8 – Open sfsf.projman.db-Role.csv file

7. Copy & paste the content below into the sfsf.projman.model.db-Role.csv file

ID;name;descr
1;Project Manager;Project Manager Role
2;Project Lead;Project Lead Role
3;Business Owner;Business Owner Role
4;Product Owner;Product Owner Role
5;SCRUM Master;SCRUM Master Role
6;Solution Architect;Solution Architect Role
7;Software Engineer;Software Engineer Role
8;UX Designer;UX Designer Role
9;Program Designer;Program Designer Role
10;Content Designer;Content Designer Role
11;Content Expert;Content Expert Role

8. On the left-hand pane, click on the sfsf.projman.model.db-Status.csv file to open it, then copy & paste the content below

ID;name;descr;criticality
1;Not Started;Activity has not been started yet;2
2;In Progress;Activity is in progress;5
3;Overdue;Activity is overdue;1
4;Blocked;Activity is blocked;2
5;Paused;Activity is paused;2
6;Canceled;Activity is canceled;1
7;Completed;Activity is completed;3

9. On the left-hand pane, click on the sfsf.projman.model.db-Employee.csv file to open it, then copy & paste the content below

userId;username;defaultFullName;email;division;department;title
100093;rsmolla;Rick Smolla;Rick.Smolla@bestrunsap.com;Corporate Services (CORP_SVCS);Employee Development (50012007);Development Analyst
100095;kholliston;Kay Holliston;Kay.Holliston@bestrunsap.com;Corporate Services (CORP_SVCS);Human Resources US (50150001);Program Manager
100096;smoultone;Sarah Lynn Moultone;Sarah.Moultone@bestrunsap.com;Manufacturing (MANU);Quality Assurance US (50150013);Inspector
100097;swang;Scott C Wang;Scott.Wang@bestrunsap.com;Manufacturing (MANU);Operations CN (50100010);Quality Assurance Manager
100112;jwilliams;John Williams;John.Williams@bestrunsap.com;Manufacturing (MANU);Operations US (50007753);SVP Operations & Maintenance
100115;mcooper;Mya Cooper;Mya.Cooper@bestrunsap.com;Manufacturing (MANU);Operations US (50007753);VP Operations

IMPORTANT NOTE: the above employees have been taken from an SAP SuccessFactors demo tenant as they must match the data that’s coming from it. Those users usually exist at SuccessFactors demo tenants, so if you are using a demo tenant for your project that content should be fine, otherwise you must search for users in your SAP SuccessFactors tenant and adjust the content of this CSV accordingly.

10. On the left-hand pane, click on the sfsf.projman.model.db-Project.csv file to open it, then copy & paste the content below

ID;name;description;startDate;endDate;status_ID
3ca47b3e-eff3-430e-9ae0-1937dd094212;S/4HANA Cloud implementation;Global implementation of the S/4HANA Cloud ERP in the organization;2022-01-02;2022-09-30;1
b85cf0b8-2ff3-40a7-af20-52fa024fbce6;Resource allocation app development;Development of a cloud application to manage presales resources allocation;2022-08-02;2022-11-30;2
b5c6bc42-6f95-4876-9658-13aaecb28008;BTP enablement program development;Development of the plan and content for the global BTP enablement program;2022-05-01;2022-10-31;3

11. On the left-hand pane, click on the sfsf.projman.model.db-Member.csv file to open it, then copy & paste the content below

ID;parent_ID;member_userId;role_ID;hasAssignment
df87d8d4-16df-48da-a8bf-5b2218f62602;3ca47b3e-eff3-430e-9ae0-1937dd094212;100093;1;true
3470cf57-b0b9-49ce-b568-52f44df3b09c;3ca47b3e-eff3-430e-9ae0-1937dd094212;100095;2;true
81e89fd2-b2d8-4af3-a4b2-2cadfc69e6de;b85cf0b8-2ff3-40a7-af20-52fa024fbce6;100096;1;true
79da3255-627f-4782-af10-beb8d1c796b6;b85cf0b8-2ff3-40a7-af20-52fa024fbce6;100097;2;true
33c8e150-561a-4228-899f-faabe41094aa;b5c6bc42-6f95-4876-9658-13aaecb28008;100112;1;true
d2696b36-3413-4522-a73b-f00560dc3fe5;b5c6bc42-6f95-4876-9658-13aaecb28008;100115;2;true

IMPORTANT NOTE: the member_useId values must match the values in the userId column from the sfsf.projman.model.db-Employee.csv file.

12. On the left-hand pane, click on the sfsf.projman.model.db-Activity.csv file to open it, then copy & paste the content below

ID;parent_ID;assignedTo_ID;name;description;dueDate;status_ID
4dae162a-56ea-4e99-8061-70ec3f30a2fd;3ca47b3e-eff3-430e-9ae0-1937dd094212;df87d8d4-16df-48da-a8bf-5b2218f62602;Do project planning;Plan the whole project;2022-01-05;7
fcba3d35-013a-4ab6-9ab9-9fb938eff8a4;3ca47b3e-eff3-430e-9ae0-1937dd094212;3470cf57-b0b9-49ce-b568-52f44df3b09c;Assign team to project;Look for the appropriate experts to work on project;2022-01-05;3
3fd253a8-4951-47d0-9946-58d97ac21b95;b85cf0b8-2ff3-40a7-af20-52fa024fbce6;81e89fd2-b2d8-4af3-a4b2-2cadfc69e6de;Do project planning;Plan the whole project;2022-05-04;7
91d18efa-3173-4f7e-86f0-74332c69c8cd;b85cf0b8-2ff3-40a7-af20-52fa024fbce6;79da3255-627f-4782-af10-beb8d1c796b6;Assign team to project;Look for the appropriate experts to work on project;2022-05-04;3
341a6fa0-6ecf-4eb4-8638-426eed4584f7;b5c6bc42-6f95-4876-9658-13aaecb28008;33c8e150-561a-4228-899f-faabe41094aa;Do project planning;Plan the whole project;2022-08-05;7
0194b2b8-b9f7-4c6f-8677-18ae7fd627b7;b5c6bc42-6f95-4876-9658-13aaecb28008;d2696b36-3413-4522-a73b-f00560dc3fe5;Assign team to project;Look for the appropriate experts to work on project;2022-08-05;3

Initial Testing

Now it has come the time to test the project as it is so far. We will start by installing the required project dependencies, so let’s do it!

1. In the Terminal, change back to the project root folder: type cd ../.. and press Enter

Figure 9 – Change back to project root folder

2. Type npm install and press Enter

Figure 10 – Installing project dependencies

3. When the installation is completed you should see the following message in the Terminal

Figure 11 – Installation completed

4. Type cds watch and press Enter to run the project and watch for changes in real time. You should see the following result in the Terminal

Figure 12 – Project first run

Notice that CDS has automatically set the database to an in-memory sqlite db and filled it with the CSV files. It also says that it could not find any service definitions from the loaded models: that’s because we really haven’t defined any yet (we will do it in the next blog post from this series).

5. CTRL+Click on the http://localhost:4004 link that is displayed in the terminal to open the project home page in a new browser tab

Figure 13 – Project initial home page

You can see that there are no web applications, and most importantly, no service endpoints yet.

You might be wondering: “what about the Employee, Role and Status entities that I annotated with @cds.autoexpose? why are they not showing up here?”. Well, as we have not defined any service endpoints to expose the entities, CDS cannot expose them even though we explicitly asked to do it automatically.

But don’t worry! They will show up in this page as soon as we complete the next blog post in this series!

Conclusion

Congratulations! You have successfully created the CDS data model, populated it with some initial test data, installed the project dependencies and run it for the first time!

NOTE: all the instructions provided in this blog post apply exactly the same to any CAP project that extends other applications (SAP S/4HANA Cloud, SAP Ariba, SAP CX, and other third-party), if you would like to try it in the future.

Please, do not hesitate to submit your questions in SAP Community through the Q&A tag link: https://answers.sap.com/index.html

Next blog post in this series

• Create the CAP Service