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