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

Migrating Applications from XSJS to Async-XSJS

Context:

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.

Sample

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) { 
         conn.commit(); 
         conn.close(); 
      } 
   } 
}

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(); 
         conn.close(); 
      } 
   } 
} 
export default {select};

 

Risk

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.

Links:

@sap/async-xsjs

async-Migrator

Business Transaction Platform: Cloud Foundry Documentation

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

 

Assigned Tags

      5 Comments
      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.

      Regards,

      Suchen.

       

       

      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.

      BR

       

      Volker

      Author's profile photo Suchen Oguri
      Suchen Oguri

      Hi Volker Saggau

      We are still migrating lot of applications from xsjs to async-xsjs and some of which may not meet the deadline i.e., April 30.

      Could you help me to know what exactly would be the impact? Whether application will suddenly stop working as nodejs-v14 will be removed from BTP? Or will it continue to work and we would not be able to deploy any changes unless we migrate?

      Thanks in advance.

      Regards,

      Suchen

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

      Hi Suchen,

      you will loose the official support from the Node.js side with this date. We will be graceful on our side but do not expect too much more time here. You can approach me directly for further discussion.

      It is the support that will become the problem.

      BR

       

      Volker

      Author's profile photo Sahil Sawal
      Sahil Sawal

      Hi Volker Saggau,

      we are currently have a application where we are using 100s of xsjs and xsjslib. i have few questions.

      1. Do have to do all the changes manually ?
      2. we have multiple function in our xsjs, how can i export multiple function at a time, can you please help me with syntax.

       

      thank you

      Sahil Sawal