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 https://open.sap.com/courses/hana3/
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:
(https://www.youtube.com/watch?v=c41anxrDleg
(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: http://api.jquery.com/jquery.ajax ).
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
(http://help.sap.com/hana/SAP_HANA_XS_JavaScript_API_Reference_en/$.hdb.html
http://help.sap.com/hana/sap_hana_xs_javascript_reference_en/$.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!
- SAP Managed Tags:
7 Comments
