Tell us what you think

We want to create the best possible experience for our learners. Your feedback helps us to improve the experience for everyone.

Project Structure

Objective

After completing this lesson, you will be able to explain the structure of a project

Workspace, Projects, Modules, and Folders

A workspace in SAP Business Application Studio is a file structure where you can work on one or several projects. Each user has their own workspace, and can create additional ones if needed.

The workspace of a user can contain as many projects as needed, but each project must have a different name. Practically, this is done by storing the content of different projects into different root folders. It's possible to open a single project/folder at a time, or to create a multiroot workspace.

Relationship of Workspace, Projects, and Modules. A user's workspace contains projects. A project contains modules with folders and objects.

When you create a new project, the creation wizard will ask you to choose a project template. SAP Business Application Studio comes with several templates and you choose the one most suitable for the type of application you want to create. Depending on the template you choose, you will be prompted for various settings, which are then used to create the basic project shell.

We'll focus on the project template SAP HANA Database as this is the most straightforward for developing calculation views and other modeling artifacts.

Modules

Within a project there are modules. There are different types of modules. For example, there's a module for Java, a module for HTML, and a module for database objects.

The first step is to create a module of the type you require and then begin developing the source code in that module. You can create as many modules as you need for your project even of the same type. Typically, for a database module, you probably only need one. You should provide a meaningful name for the module so that it's easy to identify the module type and what it contains. Don't create empty modules that you won't use.

Within a module, we have folders. Folders are used to subdivide your source files into meaningful groups. For example, you may choose to create two folders: one for tables and one for calculation views.

HANA Database Modules

A HANA Database module, also know as an HDB module, contains all the design-time files that define the various database objects that must be deployed together with the application. From a project structure perspective, it consists of a folder to which you give a name when creating the HDB module, for example, db or dbmodule.

This folder contains, among others, a folder src, generated by default, which is where you store modeling content, but also additional content related to the HDI deployment (.env file, node_module folder containing the node.js HDI Deployer and its dependencies).

Note

The HDB module is referenced by the project descriptor file, mta.yaml, which also contains some settings about the module, such as the database id or schema name (not all of them are mandatory).

Main Database Artifacts Defined in an HDB Module

Tables
Calculation views
Functions
Procedures
Analytic privileges
Synonyms

Persistence Layer: Inside the HDB Module or Outside?

Depending on the type of application, the main data managed by the application can be stored in different places.

A major design option for an application is to decide whether this data is stored in a persistence layer defined by the application itself, or if it's stored in another location, such as a classical database schema. Let’s consider the two following examples to illustrate these approaches:

Internal or External Persistence Layer

Objects Identifier and Namespace

In the SAP HANA Cloud database, each runtime object has an object identifier, which is used to reference this object within the container or schema. By default, the runtime name is the same as the design-time (source) file name. That keeps things simple.

A runtime name can also have an optional namespace as a prefix to provide even more meaning.

So the structure of a complete runtime object is as follows:

Code Snippet

1
<Namespace>::<Runtime Object Name>

The Runtime Object Name is mandatory.
The Namespace is an optional part of the object identifier, and is mainly used to organize logically the runtime objects within the container.

Note

In this course, the namespace convention we've chosen for the main application is to have a prefix HC, applied uniformly to all objects, regardless of the folder location of design-time objects. In other words, the namespace is the same for all the runtime objects defined in all folders of our HDB module. So, these objects all have the identifier pattern HC::<Runtime Object Name>.

Runtime Objects Identifiers

The object identifiers (including the namespace) are always specified in the design-time objects. That is, the design-time objects must define how the runtime objects will be identified.

Let’s take an example of a modeling object, a calculation view CVC_SalesOrders, with its design-time version in the SAP Business Application Studio workspace, and its runtime version (created during deployment) in the container schema.

The figure, runtime Objects Identifiers, explains how folders are used to organize the design-time files in the HDB module of your application, and shows what the runtime object identifier could be. In this scenario, the calculation view identifier has a namespace. Let’s now discuss the main rules and possible options to define the namespace.

Namespace

The following rules apply to the namespace:

The namespace is optional. Some objects can be defined with a namespace in their identifier, and others without.
An HDB module can have no namespace defined at all, or can specify any number of different namespaces.
The namespace is always identical for all the design-time objects stored in the same folder.
The namespace must always be explicitly mentioned inside the design-time files, and must correspond to the namespace defined explicitly in the containing folder, or implicitly cascaded from the parent folders.

The .hdinamespace File

The definition of a namespace is possible in the src folder of an HDB module, and also in any of its subfolders. This is done with a file called .hdinamespace.

When you create an HDB module, a .hdinamespace file is created automatically in the folder <hdbmodulename> → src and contains a default value "<application_name>.<HDB_module_name>". You can modify this file to apply different rules than the default to your project’s namespaces.

Note

It's recommended to make such a change at the beginning of the project to avoid breaking dependencies. Similarly, you must decide early on whether a single namespace should be used for all your modeling artifacts' runtime objects, or if you want to use several ones.

A .hdinamespace file within the structure of a project, showing the content of the file, namely the name and subfolder keys used to define the namespace rule. The corresponding values are MyApp1.db for the name key, and append for the subfolder key.

Elements Of .hdinamespace File

The content of any .hdinamespace file is always comprised of two elements, name and subfolder.

Element	Possible values	Default Value
"name"	`"<Any syntactically correct namespace of your choice>"` "" [no namespace specified]	`"<application_name>.<HDB_module_name>"`
"subfolder"	`"append"` `"ignore"`	`"append"`

To structure your runtime modeling content in a way that suits your needs, you can add a .hdinamespace file to any subfolder of the src folder. The "subfolder" setting determines whether the subfolder names should be added implicitly to the namespace for objects located in subfolders (append) or not (ignore).

As a consequence, your runtime modeling objects can be referencing several namespaces. For example, in your HDB module, you could decide the following convention:

Tables are prefixed with db.data.table, and
Calculation are be prefixed with db.models.dim and db.models.cube.

Caution

When you modify the specifications of the .hdinamespace file (or create a new .hdinamespace file in a folder), this change has an immediate effect on the identifiers assigned to your design-time objects.

However, when it comes to deploying these objects, the new namespace rules are considered only after the .hdinamespace file has been deployed. Before the deployment of the new .hdinamespace file, deploying these objects, for example, a calculation view with the new namespace specification, will fail because, on the HDI container's side, the former rules are still used to validate the runtime object identifier.

As a general recommendation, the namespace rules should be defined before you create modeling content. Indeed, if you modify these rules after creating modeling content, you have to adjust the object identifiers (which includes the namespace) before you can deploy your models. And this is even more complicated if dependencies exist between models.

Object Name

The way to define a runtime object name in design-time files is governed by one of the two following rules, depending on the object type.

Defining the Runtime Object Names

Type of modeling object	Number of objects per design-time files	Naming rule
Calculation views, table functions, procedures, analytic privileges	Each design-time file defines only one runtime object (*)	The runtime object name is defined inside the object content and should match the design-time file name (without file extension).
Synonyms, table data import definition, roles	Each design-time file can define one or several runtime object(s)	The runtime object name is defined only in the object content and is not linked to the design-time file name.

(*) Here, we mean, only one core runtime object. As you might have observed, even a simple calculation view generates a core column view, plus other child column views for the attributes, hierarchies, and so on.

Note

In this table, we aren't covering the entire typology of models, but only the main ones that are discussed in this course.

Let’s take two examples, one for each of the two approaches.

Object Name Example: Calculation View

Screen capture of the object name in the code of the design-time file and in the database explorer. both places show the namespace and the object name. The object name and the file name should match to find more easily a design-time file from the runtime object name.

Technically, the design-time file name for a calculation view can be different from the runtime object name.

However, we recommend that you always keep these names in sync to make it easier to find a design-time object based on the runtime object name.

Object Name Example: Synonyms

Screen capture of a .hdbsynonyms file which is used to define references that comply with the namespace rules applicable to the folder where the synonym definition file is located.

This second configuration example shows that a design-time file for synonyms can define several synonyms. In that case, there's no specific rule or recommendation for the design-time file name.

Next lesson