Skip to Content
Technical Articles
Author's profile photo Volker Saggau

Migrating Applications from XSJS to Async-XSJS


SAP HANA XSJS applications are based on synchronous API. On the other hand, Node.js is an asynchronous runtime. Thus, for XSJS applications that run on Node.js there is a certain code incompatibility. Up until Node.js 14, this incompatibility has been handled by an NPM package called @sap/fibers (forked from laverdet/node-fibers). Unfortunately, @sap/fibers is not compatible with Node.js version 16 and higher.

Also, Node.js supports two kinds of scripts:

  • CommonJS – it’s synchronous and does not support top-level await. In XSJS, all files are loaded as common Java scripts.

  • ECMAScript – it’s fully asynchronous and supports top-level await

The only possible way for your XSJS applications to be up and running on latest Node.js versions is to modify their codes – by migrating them to a new XSJS layer with asynchronous API. See the migration process below to learn what you need to do.

Who needs to act:

  1. SAP HANA 2 extended services advanced (XSA) that are using xsjs libraries and want to upgrade to Node.js 16 or 18
  2. SAP HANA Service with CF Node.js modules that are using xsjs libraries and want to upgrade to Node.js 16 or 18


Migration Process:

  1. Open your package.json file, and in the dependencies section, add the @sap/async-xsjs package

  2. In all your .xsjs and .xsjslib files, for every asynchronous function call, add an await statement.

  3. Every function that uses an await statement must be declared as async.

  4. XSJS files should be loaded as ECMAScript. To do this, in the end of every function in an .xsjslib file, add an export statement.


This is a very simplified sample just to show you the very basic concept.

SAP_SAMPLE will provide you with a tool that can scan your code and help you to modify the need code. However this will needs a manual review and respective testing.


Original Code

$.import('lib', 'converters'); 
function select(tableName){ 
   let conn; 
   try { 
      conn = $.hdb.getConnection(); 
      let resultSet = conn.executeQuery('SELECT * FROM "' + tableName + '"'); 
   return $.lib.converters.resultSet_to_Entities(resultSet, ["id", "name"]); 
   } finally { 
      if (conn) { 

Modified Code

await $.import('lib', 'converters'); 
async function select(tableName){ let conn; 
try { 
   conn = await $.hdb.getConnection(); 
   let resultSet = await conn.executeQuery('SELECT * FROM "' + tableName + '"'); 
   return $.lib.converters.resultSet_to_Entities(resultSet, ["id", "name"]); 
   } finally { 
      if (conn) { 
         await conn.commit(); 
export default {select};



The node.js version 14 will remain in your XSA environment and you could continue to work as of today. Anyhow this version is going out of support by the owner of this component by End of April 2023 

We recommend to move to Node.js version18 as the next major release with LTS (long term support) by End of April 2025

The use of asynchronous code is most likely also an improvement in performance.

All this will modification will only work in HANA 2 XSA or HANA Service Cloud Foudry. If you plan to migrate to SAP HANA Cloud you have to migrate your anyhow since the XSJS library is not supported with SAP HANA Cloud.

Alternative: Make your code asynchronous by migrating to SAP Cloud Application Programming model (CAP). This is the base of BTP code development.




Business Transaction Platform: Cloud Foundry Documentation

Note 3301467 – Migrating SAP HANA XS Classic Applications from XSJS to Async-XSJS


Assigned Tags

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

      Hi Volker Saggau

      Thanks for the nice blog.

      We have applications running on HANA Cloud having nodejs modules with XSJS compatibility. We are making steps to migrate to CAP, However temporarily some are migrating from xsjs to async-xsjs for short term.

      We have 100+ MTA applications with .xsjob artifact (inside nodejs module with xsjs compatibility) to be able to manage jobs on Cloud foundry job scheduler.

      Could you suggest a best solution for our scenario to continue our operations with .xsjob?

      1. Do we need to migrate to async-xsjs or existing xsjs package would continue to work for .xsjob even on higher node versions like node v18?
      2. If yes, Does this async-xsjs package also work for .xsjob artifact?

      Thanks in advance.





      Author's profile photo Volker Saggau
      Volker Saggau
      Blog Post Author

      XSJOBS are supported in async-xsjs. That is just a JSON document, which describes a reference to a remote scheduler job. Job Interface in async-xsjs is semantically slightly different than the job interface in xsjs, but it should work as expected.