Technical Articles
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 1 – SAP API Business Hub
2. In the search bar type ECEmployeeProfile and press Enter:
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 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 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 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 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 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 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 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 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 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 12 – Instances and Subscriptions
2. Fill-in the service instance information like in the screenshot below and click Create.
Figure 13 – Destination Service instance
3. On Instances and Subscriptions click the Create button at the top-right corner again
Figure 14 – Instances and Subscriptions
4. Fill-in the service instance information like in the screenshot below and click Create.
Figure 15 – XSUAA Service instance
5. In the search bar type “sfsf-” and press Enter to easily find your recently created service instances
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 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 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 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 20 – Service Key for XSUAA Service instance
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 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 22 – View Service Key
4. On the dialog, click on Copy JSON and then on Close
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 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