Extend SAP SuccessFactors on SAP BTP with CAP – Import SAP SuccessFactors OData Services definitions


Prerequisites

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

Get Services Metadata

The first thing we need to do is to get the XML files (EDM XML – Entity Data Model XML – in short EDMX) which define the entities that compose the OData services to be consumed in the application. We can get such files from SAP API Business Hub.

1. Access https://api.sap.com:

Figure%201%20-%20SAP%20API%20Business%20Hub

Figure 1 – SAP API Business Hub

2. In the search bar type ECEmployeeProfile  and press Enter:

Figure%202%20-%20Find%20the%20ECEmployeeProfile%20OData%20service

Figure 2 – Find the ECEmployeeProfile OData service

3. Click on the item from the search result and in the API Specification at the bottom of the page click on the down arrow next to the EDMX option:

Figure%203%20-%20Download%20EDMX%20file

Figure 3 – Download EDMX file

4. Save the ECEmployeeProfile.edmx file (keep that file name) to a folder in your local computer.

5.  Click on the SAP logo at the top left corner of the page to return to the home page and repeat the exact same procedure from steps 2 to 4, but now searching for the PLTUserManagement OData service to save the PLTUserManagement.edmx file to your local computer.

Import files to the CAP project

Now that we’ve got both EDMX files in our local computer, it’s time to import them to our CAP project in order for CDS to generate the corresponding definitions using the so-called Core Schema Notation (CSN) which is described in JSON format.

1. Simply drag & drop the two EDMX files to the srv folder of your CAP project in Business Application Studio

Figure%204%20-%20EMDX%20files%20copied%20to%20the%20CAP%20project

Figure 4 – EDMX files copied to the CAP project

2. In the terminal window type cds import srv/ECEmployeeProfile.edmx and press Enter. This should be the expected output:

Figure%205%20-%20CDS%20import%20outcome

Figure 5 – CDS import outcome

3. Repeat the same procedure from step 2, but this time type cds import srv/PLTUserManagement.edmx to import the second service definition. In the left-hand pane you’ll notice that an external folder has been created under srv. Expand it to see the generated csn files:

Figure%206%20-%20CSN%20files%20with%20service%20definitions

Figure 6 – CSN files with service definitions

4. Now you can delete the EDMX files from the srv folder. Just right click each one and select delete.

Checkout the Import Results

Let’s now inspect what happened after executing those command lines. First, click on the ECEmployeeProfile.csn file in the srv/external folder:

Figure%207%20-%20CSN%20of%20the%20ECEmployeeProfile%20service

Figure 7 – CSN of the ECEmployeeProfile service

You can see the content is nothing else than a JSON representation of the service metadata with the description of the entities contained in it. This JSON is used by the CDS framework to let you make type-safe OData calls to the service in the form of simple queries via the easy-to-use low-code CDS Query Language (CQL).

Press CTRL+F to open the find bar and search for Background_SpecialAssign:

Figure%208%20-%20The%20Background_SpecialAssign%20entity

Figure 8 – The Background_SpecialAssign entity

You’ll find the definition for the Background_SpecialAssign entity. We’ll use that entity to insert the project participation info into the Employee Profile as part of the historical professional background. So, whenever an employee is assigned to a project with a certain role, that information is stored in his/her professional background.

Now, open the PLTUserManagement.csn file and search for PLTUserManagement.User:

Figure%209%20-%20The%20User%20entity

Figure 9 – The User entity

That’s the entity we are going to use to fetch the relevant employee data (we won’t use all of its elements) to assign to the projects teams.

Let’s now look at the package.json file to see how CAP is referencing those OData services. Open that file and scroll down to the bottom:

Figure%2010%20-%20Services%20reference

Figure 10 – Services reference

In the cds.requires section you’ll notice how CAP is referencing both services. But how does it know where in the cloud those services exist? Well, remember that destination we created in the preparation section of the introductory blog post of this series? Now it’s come the time to point those service references to it as credentials! To do so, add the following lines to the cds.requires section:

Figure%2011%20-%20Credentials%20for%20the%20OData%20services

Figure 11 – Credentials for the OData services

With that, we are simply setting the destination name and the path where the service is hosted within the destination URL.

Destination and XSUAA services

In order to use that destination for testing our application during development, we need to bind our project to two service instances in BTP: one for the destination service and another for the XSUAA service. So, let’s start by creating those service instances and a service key (credentials) for each one in BTP.

1. In the BTP cockpit of your trial account, on the left-hand pane click on Instances and Subscriptions then on the Create button at the top-right corner

Figure%2012%20-%20Instances%20and%20Subscriptions

Figure 12 – Instances and Subscriptions

2. Fill-in the service instance information like in the screenshot below and click Create.

Figure%2013%20-%20Destination%20Service%20instance

Figure 13 – Destination Service instance

3. On Instances and Subscriptions click the Create button at the top-right corner again

Figure%2014%20-%20Instances%20and%20Subscriptions

Figure 14 – Instances and Subscriptions

4. Fill-in the service instance information like in the screenshot below and click Create.

Figure%2014%20-%20XSUAA%20Service%20instance

Figure 15 – XSUAA Service instance

5. In the search bar type “sfsf-” and press Enter to easily find your recently created service instances

Figure%2016%20-%20Find%20instances

Figure 16 – Find instances

6. In the line corresponding to the sfsf-dest service instance click on the three dots at the far right and select Create Service Key

Figure%2017%20-%20Create%20Service%20Key

Figure 17 – Create Service Key for Destination Service instance

7. On the dialog, type sfsf-dest-sk in the Service Key Name and click on Create

Figure%2018%20-%20Service%20Key%20for%20Destination%20Service%20instance

Figure 18 – Service Key for Destination Service instance

8 Click on the line corresponding to the sfsf-xsuaa service instance. Then, on the top right corner click on the three dots and select Create Service Key

Figure%2019%20-%20Create%20Service%20Key%20for%20XSUAA%20Service%20instance

Figure 19 – Create Service Key for XSUAA Service instance

9. On the dialog, type sfsf-xsuaa-sk in the Service Key Name and click on Create

Figure%2020%20-%20Service%20Key%20for%20XSUAA%20Service%20instance

Figure 20 – Service Key for XSUAA Service instance

Done! You have successfully created both service instances and their corresponding service keys. Now it’s time to bind those service instances to your CAP project using their service keys.

Bind Service Instances to the CAP Project

To be able to use the service instances we created in the previous topic during development, we need to bind them to the CAP Project. This is done by creating a file named default-env.json. In the file we define the so-called VCAP_SERVICES object, which is actually an environment variable that holds all the binding information of an application.

Whenever you deploy an application to Cloud Foundry, that variable is automatically created in the application space. In our case, we will create it manually into the default-env.json file.

1. In the root folder of your project on the Terminal, type touch default-env.json and press Enter

Figure%2021%20-%20Create%20default-env.json%20file

Figure 21 – Create default-env.json file

2. On the left-hand pane, click on the default-env.json file to open it. Then, copy & paste the following code snippet:

{ "VCAP_SERVICES": { "destination": [ { "label": "destination", "provider": null, "plan": "lite", "name": "sfsf-dest", "tags": [ "destination", "conn", "connsvc" ], "credentials": { } } ], "xsuaa": [ { "label": "xsuaa", "provider": null, "plan": "application", "name": "sfsf-xsuaa", "tags": [ "xsuaa" ], "credentials": { } } ] }
}

3. Back in the cockpit, click on the line corresponding to the sfsf-dest service instance, then on the Service Keys tab on the right, then on the three dots next to the service key and finally select View

Figure%2022%20-%20View%20Service%20Key

Figure 22 – View Service Key

4. On the dialog, click on Copy JSON and then on Close

Figure%2023%20-%20Copy%20Service%20Key

Figure 23 – Copy Service Key

5. Replace both curly brackets right after the “credentials” attribute of the destination service with the copied JSON. The resulting text should look similar to the screenshot below:

Figure%2024%20-%20Destination%20service%20credentials%20in%20default-env.json

Figure 24 – Destination service credentials in default-env.json

6. Finally, repeat steps 3 to 5 for the sfsf-uaa service key (name it sfsf-uaa-sk) of the xsuaa service instance

With that, you’re done binding the project to the destination and XSUAA service instances.

Conclusion

Congratulations! You have successfully imported the SuccessFactors OData Services definitions to your project, created the destination and XSUAA service instances and bound them to your development environment. Now, you’re ready to move forward to the next step: define the CDS data model.

NOTE: all the instructions provided in this blog post apply exactly the same to any OData Service from any application (SAP S/4HANA Cloud, SAP Ariba, SAP CX, and other third-party) you would need to import to and consume in a CAP project, as long as you have the corresponding EDMX file containing the service metadata and a destination to the service host properly configured on BTP.

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

  • Define the CDS Data Model