How to create your own web application using SAP HANA UI Toolkit for Information Access

A few months ago I started developing the content for a new workshop called Get your Hands-on IT for SAP HANA™. This is a two days guided workshop providing you with everything you need to improve your practical development skills, like system access to a SAP HANA™ system in Amazon Web Services prepared with rich sample data and exercises that will expose you to more complex challenges than traditional training classes can provide. When we started thinking about which topics we wanted to cover in the workshop we decided to expose SAP HANA™ functionality that is usually not covered in standard trainings, so the UI Toolkit for Information Access was a perfect match.

The UI Toolkit for INA is basically a set of widgets that can be used in Web Applications to provide real time access to information stored in a SAP HANA™ database. You can also use the widgets to provide faceted search features for structured and unstructured text data. For those not familiar with this term (like I was until recently), faceted search means returning results grouped by attribute values instead of a flat list. These groups (facets) enable navigation, filtering, refining and visualization of the dimensions of the result set.

The toolkit is based on HTML5 and JavaScript libraries such as JQuery/JQueryUI, d3 (Data Driven Documents), Tempo and FancyBox (in case this means something for you). The widgets consume “search enabled” Attribute Views. Every time you create a “search enabled” Attribute View, the SAP HANA™ REST service automatically creates an Entity Set, so to be more precise, the widgets consume Entity Sets thru the SAP HANA™ REST service whose responses are provided in JSON format.

Enough with the theory, let’s get our hands dirty. To implement the UI Toolkit in your own site we will need to complete the following steps:

1. Install the UI Toolkit
2. Prepare Your Source Data
3. Set up a Development Environment
4. Create Your Own Site

Install the UI Toolkit

1. Download the Delivery Unit from SAP Service Marketplace
2. Import the Delivery Unit
   1. Open SAP HANA™ Studio Modeler
   2. On the Quick Launch tab page, choose Content -> Import
   3. Select HANA Content -> Delivery Unit and choose Next
   4. Select Client and browse the DVD or the download folder for the REPO_INA_UITOOLKIT.tgz delivery unit
   5. Select both Actions and choose Finish
   6. Perform the same import procedure for the REPO_INA_SERVICE.tgz delivery unit
   7. Check the Packages were imported correctly
3. Register and Activate the Service
   1. Switch to the SAP HANA™ Studio Administration Console and select your database instance
   2. Choose the Configuration tab page and expand xsengine.ini -> application_container
   3. Double-click the application_list line and, in the System column, add the entry SearchServer
   4. To restart the XSEngine, choose the Landscape tab page
   5. From the context menu of the xsengine service, choose Kill. The service stops completely and restarts automatically

4. Download the Demo Data from SAP Code Exchange and import it to your database. This step is optional, it is not necessary to get the UI Toolkit running, only if you want to check out the demo site. In our case, we won’t be working with the demo site so you can skip it for now

To test the service was successfully installed you can open the demo site, in case you didn’t installed the demo data you should still be able to log into the site,  but of course no data will be displayed:

Revision 33 or lower:

http://<HANAhost>:80<instance>/sap.bc.ina.demos.epm/search.html

Revision 34 or higher

http://<HANAhost>:80<instance>/sap/bc/ina/demos/epm/search.html

Prepare Your Source Data

The first thing we need to do is create a full-text index in each table column that contains human readable text data. To create a full-text index in SAP HANA™ Studio, execute the following SQL command:

CREATE FULLTEXT INDEX <index_name> ON <table_name>(<column_name>)

To create a “search enabled” Attribute View the first thing you need to do is change the configuration of you SAP HANA™ Studio:

1. Log on to the SAP HANA™ studio with user SYSTEM
2. In the menu bar, choose Window -> Preferences -> Modeler -> Search Options
3. Select the “Enable Search Attributes” option and choose OK

Once this is complete, you can go ahead and create the Attribute View that will be consumed by the widgets. For each attribute in the Attribute View, make sure you follow the steps below:

1. In the Output pane, select the attribute.
   Note: The searchable attributes must not be calculated attributes nor have lower case letters in their names.
2. In the lower area of the Properties pane, select the Information Access category.
3. Set the Freestyle Search property to True.

In the Information Access category, you can make search-specific settings. The Weights for Ranking setting (between 0.0 and 1.0, default 0.0) influences the ranking of items in the results list. The higher the weight of the attribute, the higher up in the list an item with a hit in this attribute is positioned. The Fuzziness Threshold setting is not in operation yet.

To make sure you will be able to connect the widgets to your newly created Attribute View, open the following URL in a Web Browser:

Revision 33 or lower:

http://<HANAhost>:80<instance>/sap.bc.ina.service.v1

Revision 34 or higher:

http://<HANAhost>:80<instance>/sap/bc/ina/service/v1

You should see a list of Entity Sets that are exposed thru the SAP HANA™ REST Service, the entity set name contains the name of the SAP HANA™ package, the name of the view, and the string “Collection”:

<package_name>/<view_name>Collection

To test the entity set, open the following URL:

Revision 33 or lower:
http://<HANAhost>:80<instance>/sap.bc.ina.service.v1/<entityset>

Revision 34 or higher:

http://<HANAhost>:80<instance>/sap/bc/ina/service/v1/<entityset>

Set Up a Development Environment

To be able to create our own site we will need to set up a development environment:

1. Make sure the SAP HANA™ Client is installed on your machine
2. Add the path to the hdbclient folder to the following environment variables: PATH on Windows and LD_LIBRARY_PATH on Linux. This step is necessary to be able to execute SAP HANA™ Client commands from any folder
3. Create a new folder on your local machine and make it a SAP HANA™ development workspace by executing the following command inside this folder:

   Revision 33 or lower:
   regi create workspace –user=<HANAuser> –host=<HANAhost>:<SQLport>
   Revision 34 or higher:
   hdbuserstore SET <mykey> <HANAhost>:<SQLport> <HANAuser> <password>
   regi create workspace –key=<mykey>

4. Mark the UI toolkit packages as relevant for development by execute the following command:
   regi track sap.bc.ina
5. Copy the UI toolkit packages and files to your local workspace by executing the regi checkout command.
6. In your workspace, the package structure is represented as folders containing the HTML, CSS, JS files, and graphics

Create Your Own Site

To create your own site, go to the demos folder, copy the epm folder, rename it, for example to myapp, and work in the new folder only. Now you can start manipulating the site or the toolkit using a Web development editor of your choice. We will focus on the search.html file under the myapp folder and the HTML files under the templates folder.

Search.html

This is the home page of your site. Inside you will find the implementation of the widgets, so let’s start reviewing the code for each one and how to customize them.

Work Area Widget

The Work Area widget will allow you to connect you site to your Source Data by specifying your entity set in the data-entityset parameter.

Search Box Widget

Chart Widget

The most important thing here is to update the data-dimension parameter to the column from your entity set to be displayed

Result List Widget

Here you will need to change the data-responseattributes parameter to specify all the columns from your entity set that you want to display in the Result List

Now that we are done with the search.html file, let’s move forward with the HTML files under the templates folder

Templates.html

The HTML files under the templates folder will be used by the Result List Widget to display the data in your site. You will need to update the html files that are listed in the search.hmtl file in the templates section

In this case, updating the products.html, products_small.html and product_detail.html files will be enough. In these files you will need to specify the attributes that you want to display in the results list and in which way do you want them displayed. Make sure that every attribute you use in these files was specified in the data-responseattributes parameter of the Result List Widget.

Once you are done making all the modifications, execute the regi commit command to commit the changes back to the SAP HANA™ server and then the regi activate command. The URL to open your new UI in a browser is the following:

Revision 33 or lower:

http://<HANAhost>:80<instance>/sap.bc.ina.demos.myapp/search.html

Revision 34 or higher:

http://<HANAhost>:80<instance>/sap/bc/ina/demos/myapp/search.html

Below you can see a screenshot of the site that I created. My page is showing Airports by Country, State and City.

Have Fun!

Follow me on Twitter: @LukiSpa