Working with Modeling Content in a Project

Data lineage shows all the calculation views and source tables on which a given calculation view depends.

The purpose of impact analysis is to show all the chain of calculation views that depend on a given calculation view.

Hint

In the Data Lineage or Impact Analysis view, you can directly open a calculation view from the dependency tree by double-clicking it.

Column lineage is very useful when columns are renamed within the calculation scenario, or when you want to see quickly where a calculated or restricted column originates from.

It also helps you to avoid mixing up columns with the same name, but not necessarily the same data that are present in several nodes of a calculation view.

For example, the NODE_KEY column in an SAP ERP system is used in many tables to join the master data-defining attributes.

You might want to make sure that the NODE_KEY column in the output of a dimension calculation view originates from the correct table (for example, the table SNWD_BP containing business partners) and not from another table, also used in the calculation view, in which a NODE_KEY column is present but does not identify business partners (for example, the NODE_KEY in the table SNWD_AD containing Contact addresses).

Note

The Show Lineage feature stays active until you exit the Show Column Lineagemode by choosing Exit.

Watch this video to learn about the Outline View.

Note

Make sure you do not mix up the Outline feature of the calculation view editor with the general Outline view of SAP Business Application Studio, which displays structured code into a hierarchy.

The source code for your application is stored inside various modules of your project.

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, for example, you may choose to create two database modules: one for tables and one for views, if that helps with better organization of source code. You should provide a helpful name for the module so that it is easy to identify the module type and what it contains. Do not create empty modules that you will not use.

For graphical modeling, the focus is exclusively on the HDB module.

Note

The other types of modules are introduced in another course, HC450 – Application Development for SAP HANA Cloud.

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 is stored in another location, such as a classical database schema. Let’s consider the two following examples to illustrate these approaches:

The object identifiers (including the namespace) are always specified in the design-time objects. That is, the design-time objects must define without ambiguity 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 Web IDE 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.

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.

• A 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 folder(s).

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 namespace(s).

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

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

Caution

When you modify the specifications of the .hdinamespace file (or create a new .hdinamespace file in a folder), the new namespace rules are taken into consideration only after the .hdinamespace file has been deployed.

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.

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.

(*) 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 are not 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.

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.

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

Within each HDB module of a project you will find a very important and mandatory file that exists under the src folder with the suffix: .hdiconfig. This is the HDI container configuration file that is used to bind the design-time files of your project to the corresponding installed build plug-in.

Without the build plug-in it is not possible to build the run-time objects from the design-time files. This configuration file directs each source file in your project to the correct build plug-in.

Usually there is only one .hdiconfig file in a HDB module, and this must be located in the src folder of the HDB module. This file contains a list of all bindings for all source file types.

The minimum_feature_version entry of this file is there to prevent building your HDB module objects with a version of HANA Cloud that is lower than what is specified and/or what your code requires. For example, if you have designed and tested your HDB module with version 1004 of the build plug-ins, this will not deploy on an SAP HANA Cloud instance where version 1002 is in place.

Inside the container configuration file you will find, for each source file type, two entries:

• suffix name, for example, "hdbcalculationview"

• plug-in name, for example, "com.sap.hana.di.calculationview"

It’s very important to remember that when you import a project into your landscape, it brings with it its own .hdiconfig file that refers to the feature version that was used when it was first developed. If you then plan to update the source file using newer features of SAP HANA (for example, you want to add a new feature to a calculation view that just became available with the newer version of SAP HANA) you will not see the new feature in the source editor if the .hdiconfig file has not been adjusted to use the later feature version.

Caution

The HDI container configuration file is an unnamed file and must only consist of the suffix .hdiconfig. If you try to add a name, the build of the .hdiconfig file will fail. Leave it as it is.

In SAP Business Application Studio, when a project includes an SAP HANA DB module, a dedicated view SAP HANA PROJECTS in available (alongside the Explorer view.

The SAP HANA Projects view/panel is the materialization of the HDB module(s) defined in your projects. The upper part represents the folder structure of the HDB module. The root element corresponds to the path to the HDB module in the project. To create the runtime objects inside the connected HDI container schema, you can execute a deployment. This deployment can be triggered at different levels: a single file, a folder, or the entire HDB module.

Note

You cannot manipulate (move, copy, delete, etc) your design-time files from the SAP HANA PROJECTS view, but you can open them in their respective editor.

In the file structure, the mention Pending Deployment identifies where a deployment is required for new or modified files. For deleted design-time files, you need to "activate" the deletion by deploying the folder that contained them.

The lower part represents the Database Connections between the HDB module and the HDI containers or services providing access to external resources.

A project with an SAP HANA Database module needs at least a corresponding HDI Container to deploy its runtime objects. This is what is shown in the image, The SAP HANA PROJECTS View.

In the connection part, you can bind an existing HDB module to a new or existing HDI container. You can also add new connections (for example to another container), and

From SAP Business Application Studio, you can launch the Database Explorer application to view the database artifacts (tables, views, procedures, column views) of one or several containers.

When you do this, even if you are logged on to the SAP Web IDE with your usual SAP Web IDE user, access to the container is done by a technical SBSS (Service Broker Security Support) user that is created transparently when you add the container to the Database Explorer. This technical user interacts with the database objects on your behalf, for example, to view the content of a table or preview the data of a calculation view.

If your container consumes data from an external schema, the technical user must also be granted authorizations to the external schema objects, for example, to view the data of an external table referenced by a synonym. You will learn more about this in the unit, Security in SAP HANA Modeling.

Note

The Database Explorer also allows you to connect to classic database schemas, not managed by the HANA Deployment Infrastructure, to show the database objects and the content of tables, execute queries in a SQL console, and so on.

A deploy operation can be executed at the following levels of a project structure:

• An entire HDB module

• A sub-folder of the HDB module

• One or several individual objects

Note

The deploy operation describe above should not be confused with what is also called Deployin Cloud Foundry. In Cloud Foundry, the deploy command (cf deploy) applies to an entire application (for example an entire MTA, including potentially more than just the HDB module). It is used mainly when you want to transport and deploy/activate your project to another environment. For example from the DEV to the QA or PROD environment.

Regardless of what you deploy (HDB module, sub-folder, or single object), there is always an end-to-end dependency check applied to each object that is part of the build scope. So, even if you build a single object, there will be a recursive check of all the objects it references to make sure these objects already exist as runtime objects or are defined in a design-time object and built at the same time.

When you deploy models defined in a HDB module, you might come across different issues which are described in the log that you can consult in the console. Some are related to the dependency checks we have just discussed, others have to do with the consistency of design-time objects (for example, the namespace settings of design-time folders). Another classical build error is when two different design-time files provide a definition for the same runtime object.

Here is a list of frequent root causes for deploy errors.

An export of modeling content can be executed at different levels of a project structure, and applied to either a single file or a folder. After selecting a file or folder, you use the File → Download feature. You can also right-click the file or folder and choose Download in the context menu.

• A single design-time file is exported/downloaded as is, with the source file name and extension.

• A folder within the project structure (up to the project folder itself) is exported/downloaded as a .tar archive.

  To export an entire project opened as a workspace, you can right-click the blank area below the file structure and choose Download. You can also choose all the files and folders under the root of the project and choose File → Download.

• Several files and/or folders can be selected and exported/downloaded as a single .tar archive

Corresponding to the export, you can either import an individual file or a .zip or .tar archive. Three features are available for that:

• Drag and drop from your file system into the Explorer view. Archives such as .zip and .tar files are not extracted. This can be done in command line in a Terminal window.
• Upload Files (from the File menu) and Explorer view context menu. Archives are not extracted.
• Import files (from the Welcome page). Archives will be extracted.
  Note

  If the content you import is an entire project, for example a proj1.tar archive, you need to open the projects folder first, so that the imported project becomes a child of that folder: projects/proj1

After importing a project, you need to open its root folder as a workspace, or to add to a multi-root workspace. Please refer to the lesson, Creating a Project in SAP Business Application Studio.

When you copy/paste a design-time file within the same folder, you must provide a different name for the copy. This is not the case if you copy/paste a file to a different folder where there is not a file with the same name.

However, in any case, the content of the design-time file is not modified at all. Which means you have in your HDB module two design-time files with identical content.

At least, you must ensure that you rename all the runtime objects defined in the design-time file to make these objects unique in the whole HDB module. And, if needed, you must also change the namespace according to the target folder namespace settings.

Note

If you copy a design-time file that was already opened in a code or graphical editor, keep in mind that copy/pasting does not open the new file (the copy). The file visible in the editor is still the original one, when - in many circumstances - you might want to actually modify the copy. This especially true if the File → Auto Save feature is not active.

When moving modeling content, one key rule that you must think about is the namespace setting of the target folder.

• If the namespace settings for source and target folder are the same, moving the file has no particular impact on objects that reference the moved object.

  However, a deployment of the moved object can be successful only if the deploy scope includes the source folder, in order to execute/acknowledge the "deletion" of the moved file in its source folder. If not, the deployment will fail.

• If the namespace settings for source and target folder are different, you must at least adapt the namespace. In this case, you must first perform an impact analysis to check whether some existing objects reference the one you are about to move.

For the HDI deployer, renaming a design-time file is like deleting a design-time file and creating a new one with the same content. You must be aware of the following rules and recommendations:

• A design-time file that creates only one "core" runtime object (for example, a calculation view or a table function) should always have the same name as the runtime object it defines. For example, after renaming the design-time of a calculation view, it is recommended to also change its ID in the code by opening the ID of the runtime object.

  This is not a technical requirement, but rather a best practice to keep your design-time content readable.

• You must check if database objects reference the object you plan to rename. Generally speaking, renaming objects that have dependencies requires modification to the references to this object in other objects. Ideally, you should do this only on exception, because it is error-prone, or limit this practice to test objects, typically when you copy —and rename— an existing object in order to test changes you make to this object while keeping the source object.

• You must be particularly careful with partial deployments. If you rename an object that was already built and had dependencies, the renamed file is seen by the HDI deployer as a new design-time. The original design-time file will be seen as deleted by the HDI deployer only when you deploy either the entire HDB module, or any of it sub-folders that contains the renamed file.

Caution

If you rename a source file but choose not to rename the run-time view (which is bad practice), when you build this individual source file you will have a build error. This is because the builder considers the renamed source file as a new design item and so does not delete the original run-time. This means the new source file tries to deploy a run-time view using an already used name, and this is the error. To overcome this issue, you must build at the folder level so that the original run-time view is first deleted and then a new run-time view (with the same name) can be deployed.

Deleting modeling content can have surprising effects, especially in case of partial deployments. Indeed, the deleted design-time file is only seen as actually deleted by the HDI deployer when you deploy the entire HDB module, or any of the sub-folders that contained the deleted file.

In other words, the smallest deploy scope you can think of, in order to validate the deletion of a design-time file, is the folder in which the deleted file was located. So, even if it is empty, this folder is extremely precious.

Indeed, if you delete this folder as well, you can only validate the deletion of the design-time files it contained by deploying a parent folder. Suppose this parent folder is the src folder and it contains one (or several) models that you know cannot be built at the moment (for whatever reason).

Therefore, when deleting modeling content, you should apply the following best practices:

• Before deleting a design-time file, always perform an impact analysis.

• Before deleting a folder, always perform a partial deployment at this folder level. If the deployment is successful, it means that all the runtime objects that were defined in design-time files from this folder have actually been (successfully) deleted.

Caution

As already mentioned, you should NEVER delete a database object located in an HDI container with a plain SQL statement.

SAP Business Application Studio offers several find/search and replace features that are useful to manage the renaming of objects and the code adjustments that must be performed manually.

• Within the Code Editor, you can use Edit → Find (Ctrl+F) or Edit → Replace (Ctrl+H) to locate easily (and replace if needed) the ID of an object.

• You can also use the Search view to look for a particular text string within the content of the design-time files. You can directly open a design-time time from the search results (not from the file name, but from one of the search hits within the file content).

  The Toggle search details button (…) allows you to define file/folder patterns to include and/or exclude.

• From the Explorer view, you can also right-click a folder and choose Find in folder. This will invoke the same Search view, but this time the folder you choose is defined as the "root" for the search.
• Another useful search feature is available for the file names inside the Explorer view. Just select an element (folder, file) in the workspace, or the blank area below, and start typing a string to search. A fuzzy search tool shows up, allowing you to highlight or filter matching file names.