Skip to Content
Author's profile photo Christian Rommel

Getting started with XSJS – Challenges, Learnings, Impressions

The following blog entry shall mirror first experiences made with XSJS in SPS9. XSJS is the server-side JavaScript that is used to create powerful services in the HANA backend. In the use-cases shown down below, the focus will be on database communication, service calls via AJAX and some useful hints for beginners. The service will be consumed by an OpenUI5 application.

For this tutorial I’ll be using the Web-based Development Workbench v1.91.1 of HDB. The payload of the requests will be delivered in the JSON format. You can find a more formal introduction on Software Development on SAP HANA at

First steps

Once you have created a database model and inserted some data with an ODATA-service for instance (See the following links for help on that:


(Useful introduction on ODATA create/update/delete requests by Thomas Jung),

(Tutorial on how to create an ODATA UI5 application by Ranjit Rao)),

you may do something like creating an Email out of the data modified or manipulate the data in some kind of way ODATA won’t provide you with. That’s when XSJS becomes useful. Let’s say we have a button in our app that shall trigger an XSJS call which will insert the data provided with the service call into our db. Based on that it will request some other data to create a mail with data-specific content.

The first thing you will have to do is creating a new XSJS file by adding the .xsjs suffix to a new file. This will do the trick so that it’s interpreted as a server-side JavaScript file.

Calling a service from the UI5 controller

Our model’s data will be sent in the JSON format. A local “model.json” file stores all the data – also the specific object we want to send (in this case a repository object which has attributes like a name, Descriptions, LicenseType, and a creation Date). The object can be easily accessed with the model we are using so that all we need to do is creating an AJAX request which looks as follows:


The “$” identifier starts the jQuery command. An AJAX call gives us the opportunity to call any service we want with more settings available than you’ll ever need (See the following link for the jQuery.ajax() documentation: ).

All you’ll need to know for the beginning is that you need the URL of the service which ends with “.xsjs”, the data to be delivered and the contentType being “application/json” to make sure it transmits the data in the right manner. The data is accessed through the JSONModel which links to the “localModel.json”. It’s then stringified with a predefined JSON method. If you need the application to do something after the request has finished successfully, you can add a callback-method “.done(function(odata){ //what shall be done }))” and there is also one for error-handling.

Now that you know how to call the service, let’s have a look on what it actually does:

Creating the service logic

Due to the fact that it’s basically just JavaScript we are going to write there’s not much to say about any specific syntax. Of course it makes sense to wrap a lot of our coding into functions that we’re just going to invoke afterwards.

The first function will get us the data of the body that we sent with the request and call a HDB procedure which will insert the new repository into the database.


Again, the jQuery library gives us some nice features. The documentation of XSJS contains all the useful classes and their methods which you’ll probably need. Keep in mind that two different versions of the API exist

($.hdb.html$.db.html ).

As the second API is outdated and lacks some useful classes and methods which the new one ($.hdb) provides, you should probably go for the latest one.

The first line initializes the function just as you know from JavaScript, after that the body of our request is taken as a String and parsed to a JSON object via “JSON.parse($.request.body.asString))”. The next line gets us a connection to the database. After that a procedure call is created which will insert the new object into the database. The procedure itself is not a part of this blog. Pay attention to the syntax of the schema and procedure description because it’s easy to get irritated at the beginning. The question marks at the end are the input parameters which will be filled with our JSON data. Unfortunately it’s not possible to hand a complete JSON object to procedures as a row and single values as an output at the same time with the old API. This might not have been implemented so far. As a workaround, splitting the JSON object and giving the procedure multiple inputs with simple data types, did the trick. After the request is executed it’s possible to fetch the output parameters (in that case an integer). Next, the procedure call is closed and the changes are committed to the connection. It’s not going to be closed yet, because there is still some work left to do for it. The “getMailData()” method selects all the values being connected to the repository object by calling prepared select statements which is also part of the documentation.


The “sendMail()” function which is invoked after the mail data has been collected has several JSON objects as input parameters and creates a new mail. Fortunately, it is fairly easy to create a mail in XSJS. We just need to create a mail by template and fill the settings. A funny security issue here is the possibility to enter any address for the sender and the mail is going to look like it’s been created by him/her. The neat thing here is that the content of the mail is made up of “parts”. As we want to create a pretty HTML mail we’ll use the contentType “text/html”. After that the mail’s first part’s text is filled with all the data we want to be shown in the mail. You can also add value to the look of the mail by using in-line CSS. Last of all, the mail is send via “mail.send()”. An interesting security gap is the opportunity to type in whatever you want for the sender and the received mail displays this sender. The result of the mail looks something like the following:


Issues and Conclusion

XSJS services are easy to use if you know how to code JavaScript and the functions regarding the db connection become clear very fast. You just have to keep in mind that for simple use cases ODATA services might be more efficient because you don’t need to define the service logic for them. If you need to modify data in some way before it reaches the database level, XSJS might be very useful to you because it gives you all the opportunities of JavaScript to modify JSON objects, arrays and invoke functions. Furthermore, it lets you send mails and helps you get as much logic in the backend as possible, so you do not have to worry about API-keys or credentials within frontend controllers. Dealing with authentication (which many applications need) is a lot easier with serverside XSJS than within the frontend. An issue I faced was the lack of opportunity to include multiple HTML parts in one mail. The mail would not be rendered correctly and there was no workaround except for creating one big HTML mail part. The procedure which creates the new repository entry had to be modified a lot in order to work correctly. The procedure call in XSJS didn’t allow to pass a complete row as an input parameter, but via ODATA this was always the case. The documentation is still pretty helpful, even if it is short and needs to grow and include more classes in the future. How was your first experience with XSJS? Which problems did you face? Feel free to express your thoughts in the comments section!

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Thomas Jung
      Thomas Jung

      >Unfortunately it’s not possible to hand a complete JSON object to procedures as a row and single values as an output at the same time. 

      You are using the old $.db interface.  If you use the new (since SPS 09) database interface instead ($.hdb) you will find procedures easier to call as they take JSON as the input and output parameters. It no longer requires the calls to getter or setters for interacting with the parameters.

      >Keep in mind that two different versions of the API documentation exist

      There aren't two different versions of the documentation. There really are two different APIs. $.db is the older API still there for backwards compatibility and $.hdb is the newer version of the API. The newer version has some significant usability and performance improvements.

      >The following blog entry shall mirror first experiences made with XSJS in SPS11.

      SPS 11?  I think perhaps you are mistaken.  SPS 11 isn't released yet. In fact SPS 10 was just released the other week. SPS 11 isn't due out until the end of this year.

      >For this tutorial I’ll be using the Web-based Development Workbench v1.91.1 of HDB

      Based upon this statement it would seem you are using SPS 09 (revision 91) since the version of the Workbench should match your base HANA version.

      Author's profile photo Christian Rommel
      Christian Rommel
      Blog Post Author

      Hey Thomas,

      thanks for the reply. There were indeed some mistakes in there. Much appreciated your comment as I didn't know procedure calls were easier to implement with the new db interface.

      Author's profile photo Sergio Guerrero
      Sergio Guerrero

      just wanted to concur w Thomas on SP09 you could have used the new $.hdb API. for people who worked with the older $.db API, it is much better now and there are a lot of benefits (accessing columns by name, iterating thru the output as JSON, etc) please check out Thomas blogs on SP09 as well. They are always great. thanks for sharing this as well

      Author's profile photo Timothy Muchena
      Timothy Muchena


      Just adding a comment to gain more insight from you and others.

      Much appreciated though

      Author's profile photo Javier Andrés Cáceres Moreno
      Javier Andrés Cáceres Moreno

      Good text

      Author's profile photo Trond Stroemme
      Trond Stroemme

      Nice blog, however I get a 404 error when I try to invoke my xsjs service. I'm using HCP, productive instance, and duly create my URL using the "destinations" folder of my HCP instance. Something like this:

      var aUrl = 'destinations.../services/write_to_table.xsjs';

      This is where I get the 404. If I replace the URL with the complete url, meaning

      var aUrl = 'https://[myAccountname]', I can retrieve the service file, but get another error:

      "No 'Access-Control-Allow-Origin' header is present on the requested resource".

      This seems to be related to cross-domain issues, which is why I'd prefer to use the "destination" in the first place. I would imagine using destinations is the right way to go, not fully qualified URL's?

      (The destination to the underlying HANA system has been defined in our HCP destinations settings, by the way, and is working elsewhere.)

      Finally, when using the POST method, I keep getting 405's. This is something described by Thomas in a post from 2013, where the GET method is recommended - POST seems to be on the "experimental" stage and not yet supported. Has this changed? If so, is there a particular reason for the 405 error?

      I'm trying to connect the dots here; any info would be appreciated.

      And, yes, one last thing: in your xsjs service, you define a function. I guess this is not really needed? The EPM democontent xsjs service files just contain then necessary Javascript code, no "function" defined to encapsulate it. Should not be an issue?



      Author's profile photo Gary King
      Gary King

      I have been scanning everywhere for a single example of XSJS code to connect to Google Analytics and retrieve some dimension/metric data.
      Having a few issues myself, but I would have thought that someone would have done this before, surely.

      really surprise there’s no articles or examples on this.