Introduction
This is the second post in a series. The previous post is available here: Building hana-opensap-cloud-2020 Part 1: Introduction
After a longer break than intended, thanks to SAP TechEd and nice end of year vacation; I finally return to the Building hana-opensap-cloud-2020 Project blog series. In the first part we laid out the background and history of SAP HANA native development building up to the reasons for a new source code sample. In this part, we will begin development by preparing our development space in the SAP Business Application Studio and create a Cloud Application Programming Model project.
To catch up, remember this is a source code sample available here: hana-opensap-cloud-2020 GitHub Sample Repository
And there is a video series where we've gone through the process of creating this sample using HANA Cloud and Business Application Studio: Building hana-opensap-cloud-2020 Playlist
Specifically the content of this blog post will correspond with the video here: Building hana-opensap-cloud-2020 Part 2: Designing the Data Model
HANA Cloud
This source sample is all designed to run on the latest available version of HANA - HANA Cloud. It was developed and tested to run on HANA Cloud trial.
The prerequisites before attempting to build along with this source would be as follows:
- Get a Free Trial Account on SAP Cloud Platform (if you don't already have one):
- Set Up SAP Business Application Studio for development (if you've never used Business Application Studio):
- Create an instance of the SAP HANA Cloud in your trial account (if you don't already have an instance):
Important reminder: In the trial landscape the HANA instance stops each night. Therefore the first thing we need to do each day is make sure your HANA instance is running. Video For Restarting HANA Cloud Trial
Starting HANA Cloud trial
Starting Business Application Studio
We will be doing all of our development in the SAP Business Application Studio. The above linked tutorial will walk you through the process to perform a general setup on the Business Application Studio in the trial landscape. Therefore we can focus on getting ready for development.
The first thing to understand is that all development projects must live in a Dev Space. Think of the Dev Space as a preconfigured set of tools, wizards, and other components of the development experience. If you want to learn more about SAP Business Application Studio Dev Spaces in general, I'd recommend this blog post: Dev Spaces in SAP Business Application Studio
So you are probably faced with creating a new Dev Space and might be wondering which of the choices of starting space types you should use. One of the choices is SAP HANA Native Application and you might assume that is the obvious choice. That choice is perfect for pure HANA DB only applications, but that dev space won't currently work for combination projects that contain SAP Cloud Application Programming Model and HANA Native Development. That's the approach we want to use in this project.
For that option you should choose SAP Cloud Business Application as the Dev Space type. Then in the Additional SAP Extensions you can choose to manually add in the various additional SAP HANA tooling.
Create a New Dev Space
This approach will provide us with a single Dev Space that supports both CAP and HANA development but as you will see later it will require some additional workarounds. These are temporary workarounds until more permanent improvements for the combination of these two aspects. For much of the background on these workarounds see this blog post here: SAP Business Application Studio – Using SAP HANA Tools with SAP Cloud Application Programming Model ...
Business Application Studio Terminal
Before we even begin development I want to point out one of the best parts of of the development environment in the Business Application Studio - the terminal / cloud shell. This is a fully interactive session on a Linux environment running the cloud. It can be used to locally test/debug as you code but it can also be used to install and run additional development tools or to manipulate your project contents.
Embedded Terminal
And you can customize this shell environment as well. For instance I like the ll alias from my Unix days. I can set that alias interactively or edit the home .bashrc and have the setting persisted for me.
Personalized Alias Commands
I also take advantage of this feature to run and install additional tools. For instance you can run the CDS development kit or Yeoman from the terminal. When working with HANA I also install the HANA developer command line tool.
Install hana-cli
Create Project
Now that we have our development space customized to our liking, we can start by creating a project. If you've watched the original video for this example step; you'd see I used the cds init command from the terminal. However you can also use the graphical/interactive templates built into the SAP Business Application Studio.
CAP Project template selection
They will walk you through the project creation process nicely. Remember we still want to create a CAP project here and combine that later with HANA native content.
CAP Project Details
As the screenshot above shows, you will have a few additional options to choose from when you create your project. However if you want to combine HANA native artifacts within your CAP project the two most important aspects are the highlighted ones - Configure for SAP HANA Deployment and MTA based SAP Cloud Platform Deployment. The first of those two is probably obviously needed for HANA native. The second, MTA based, is also necessary because it adds an mta.yaml to your project root. Even if you don't plan to deploy your application as an MTA, this is needed as the HANA tooling in the Business Application Studio rely upon the mta.yaml for basic configuration of where to find the database modules and their folder structure. Without the mta.yaml, the new HANA tooling in the Business Application Studio won't be available or work correctly.
Adjust mta.yaml
Upon finishing the project wizard and loading the content into the workspace, you should see both the project contents and the SAP HANA Projects views with the Database Connections. Right away we see our first problem. The configuration for the database module is pointing to /gen/db.
Initial Project structure and configuration
This is due to the way that the CAP project wizard is structured. It is designed to have root folders for /db and /srv that are design time only content. When you perform a CDS Build it copies all the "generated" and deployable/runnable artifacts into a /gen folder. But this folder structure is currently incompatible with what the HANA tooling expects and supports. All the new HANA tooling expects to run and deploy directly from the root /db folder. Before we can really start development we are going to have to adjust the generated project configuration and structure in several places.
Let's start with the mta.yaml itself. In each module there is a path configuration that controls which folder structure the module is running from. We can adjust each of these away from the /gen folder. As soon as you change the mta.yaml and save the change you should already see the SAP HANA Projects view change to reflect the new module target. Both the target folder structure and the Database Connections (and connection names) are all driven by whatever content is maintained in the mta.yaml.
Changing the mta.yaml
But this one change isn't enough to solve the issue. While the SAP HANA Projects uses the mta.yaml for its configuration, CAP/CDS Build doesn't use it at all. Instead we will have to make a similar change in the package.json in the root of the project. This is the configuration file which impacts the way that CAP works overall.
Adjust Package.json
This is probably what your initial package.json generated by the CAP project wizard looks like.
package.json generated default values
We are going to have to make several changes to both adjust the folder structure to accommodate HANA Tooling, but also to add support for HANA Cloud. Adding the build.target section is the primary change. This is going to have the matching effect of removing the /gen from the folder targets per module in the mta.yaml. Now when you build with CAP the built content will target back into the same folder as its source and in doing so make the HANA tooling happy.
The other two changes are less specific to the HANA Tooling itself. First changing the requires.db.kind from sql to hana actually tells CAP to use HANA instead of SQLite when running or deploying locally.
Finally adding the hana.deploy-format is necessary if you target HANA Cloud (as opposed to HANA As A Service or HANA on premise). This is actually a newer option that will cause CAP to generate HDBTABLE and HDBVIEW SQL DDL artifacts as opposed to building to HDBCDS. This feature can be used on HANA As A Service or HANA on premise but is required in HANA Cloud because this newest version of HANA no longer even supports the HDBCDS artifacts.
package.json edits
Adjust db module folder
Now that our CAP project folder structure is aligned with what the HANA tooling wants, you might expect that we are OK to start using the HANA tooling to deploy to the database. Unfortunately there is one last, little issue we need to deal with. There is one more difference between a project created by the HANA specific wizard and the CAP wizard - the content of the /db folder itself.
CAP, when it builds into the /gen/db folder, doesn't build a separate package.json and HDI deployer installation. Instead it has the command cds deploy --to hana. This command includes the HDI deployer internally.
But HANA projects expect the HDI deployer and a separate package.json to be part of the content in the /db folder as well. If we had used the HANA project wizard instead of the CAP one, it would have generated this content. But then again if we had used that wizard then our CAP dependent content wouldn't be right either.
If you try to deploy to HANA using the SAP HANA Projects without this additional content in the /db folder you will receive this cryptic error:
HANA Deploy Error when missing HDI deployer
So you can follow the workaround instructions from the blog post we linked to earlier to manually add the package.json to the /db folder. However there is a short cut command in the hana-cli developer tool which will do this for you. Just run hana-cli createModule from the terminal (assuming you installed the hana-cli tool into your development space) and it will take care of adding the necessary features left out by the CAP wizard.
hana-cli createModule
First CDS Build
It took a few steps, but our project structure and configuration files are now all aligned to support both HANA and CAP development from this single project and dev space. If we go ahead and run the command cds build from the terminal, we see it "compiling" the project sample content into the /db/src/gen and /srv/gen folders instead of the default /gen/db and /gen/srv. This folders structure for /db allows you to add your own HANA native development artifacts into /db/src and they can live alongside CAP generated content since it will all be separated out into /db/src/gen.
CDS build now targets root folder structure
We are getting ahead of what we have done in this project so far, but just to demonstrate this means you can now have a CAP project and create Calculation Views within that same project. From the single CAP development space you have both the CAP project tooling and you can use things like the HANA graphical Calculation View editor. You perform a single deploy via the HANA Projects view and content from CAP (via the cds build command) and any HANA native content will all be sent into the database together.
Calculation View in CAP Project
HANA Projects View
Now that we are nearly ready to send our sample project content into the HANA database its worth looking deeper at the HANA Projects view. This is another way to look at any projects in your workspace but with focus only on the HANA specific parts. This means we only see the /db folder and the sub folders within /db/src in this view. More importantly we have several key actions we can perform from this view.
We can use this view to open the Database Explorer, to deploy into the HANA database, or we can use it to bind our database module to a Database Connection and a particular HDI container. Choosing the Bind button as shown in the screenshot below we are given the choice to create a new service instance or to bind to an existing service instance. This is where I think the HANA Tooling in the Business Application Studio is superior to the older Web IDE implementation. In the Web IDE it would only "build" to whatever was setup in the mta.yaml. Here we as the developer have more control and visibility to the database connections and how we bind them. We can more easily reuse existing HDI containers. This same feature can be used to both create and reuse User Provided Services for secondary connections as well. We will look at that in greater details in a future blog post in this series.
Create new service instance
First HANA Deploy
This feels like a lengthy journey but now you hopefully have a better understanding of the inner project workings and how to satisfy the requirements for both CAP and HANA tooling within a single project. With all this one time per project work out of the way we can finally deploy for the first time into the HANA Database.
If you have done all the previous steps correctly just pressing the Deploy button in the SAP HANA Projects view should connect to the HANA Database and correct HDI container instance and deploy any new or changed content into the database.
Deploy to HANA
Unlike the Web IDE it is no longer necessary to install and then run the deployer itself from Cloud Foundry - a process that could take more than a few seconds. Instead we install the deployer into the cloud shell within the Business Application Studio and run the deploy directly from there. This greatly cuts down on the deployment wait time and requires no application runtime entitlement at the Cloud Foundry space level. Overall I think you will find the HANA deployment experience much improved using the Business Application Studio.
And once the deployment is successful, it's also a single click away to Open HDI container. This option will open the Database Explorer in a new browser tab and select and expand the HDI container for this project. You are ready to inspect the DB content you just created.
Open HDI Container
Push Project to Git
You might be feeling like "job well done" and be ready to call it a day. But I want to point out one final very important point. When you create and save content in the Business Application Studio (or even SAP Web IDE as well), it of course is persisted in the development space. But this shouldn't be considered the permanent persistence. Anything saved in the development space is temporary at best. It can be used to bridge work when you need to quickly leave the office mid-development.
However any permanent persistence should always be done in a Git based repository. Only once you use the built in source control interface in the Business Application Studio and push/merge the content to an external Git based repository will you have your version management, ability to share with other developers, and most importantly reliable, permanent persistence.
So ALWAYS plan on include a Git repository in your development flow immediately. Commit often to avoid heartbreak. 😉
Git Integration
Closing
We covered a lot of concepts in this post about the basics of getting started and using the tooling of the SAP Business Application Studio. But we've not really created any content yet. We've only gone through the mechanics using the sample content generated by the project wizard. In the next post in this blog series, we will look at the concepts and syntax of CDS modeling in CAP and really start building some database content using the capabilities of Cloud Application Programming Model.
- SAP Managed Tags:
10 Comments
