Changes to the JavaScript code in RoomOS macros

We have updated the machinery running the macros on RoomOS, and as a result of these updates some JavaScript conventions and functions will no longer be available to the macros. In particular, CommonJS related functions are no longer available. Some common examples of code needing rewriting are:

  1. require(), including:
    • require('xapi') - needs rewriting to the standard ECMAScript import. E.g., const xapi = require('xapi') changed to import xapi from 'xapi'
    • require.main
  2. module, including:
    • module.exports - needs rewriting to the standard ECMAScript export
    • module.name - should be replaced with _main_module_name()

How is this turned on and off?

These changes take effect once xConfiguration Macros EvaluateTranspiled is toggled from True to False. This setting has been present for a long time and the change is rolled out by changing the default value in new releases from True to False.

If macros break on this change, explicitly setting the toggle back (xConfiguration Macros EvaluateTranspiled: True) is a short-term fix to make them work as before. Note, however, that this is only a temporary solution: This toggle will go away after a transition period.

Similarly, on older RoomOS versions this change can be tested without upgrading by setting the toggle to False.

Note: If a macro is saved on the device while the toggle is False and you later decide to turn the toggle back to True, resaving those macros in the macro editor may be necessary.

When will these changes take effect?

The default value of the EvaluateTranspiled toggle was changed to False starting with RoomOS May 2025 (11.28), which means devices will switch by default when upgraded. In the same version the transpilation step when saving macros through XAPI is switched off by default. If transpilation is required through XAPI the transpile command option must be explicitly set to true.

Starting with RoomOS July 2025 (11.30) a diagnostic will be shown on when the toggle is set to True. It will still work as before.

Going forward the toggle will be removed altogether and the device will behave as if it was set to False. We aim to roll out this change in November 2025. This date can change as we see how many of our customers are able to update their macros, but the timeline is measured in months, not years. The exact dates will be published here and in the release notes of the relevant RoomOS releases.

Any customers who, despite our best efforts in trying to notify and inform about the changes, see their macros fail when the changes are permanently in place in RoomOS may still use the (up to) 6-month delayed software update that is provided through Control Hub for cloud-registered devices to delay the change.

Why is this necessary? Technical details

The main driver for this change is that we have updated our JavaScript engine to use QuickJS, which serves as a modern, updated JavaScript runtime for embedded systems. After that, since it's no longer needed with a modern JavaScript engine, we are now removing the support for transpilation of JavaScript. Removing the extra step of transpiling all code reduces load time when deploying and executing code as well as reducing complexity in the platform.

The JavaScript engine switch is controlled by xConfiguration Macros QuickJSEngine: Off changed to On. This change was rolled out in RoomOS December 2023 (11.11), and we plan to remove this configuration toggle on the same timeline as EvaluateTranspiled.

We are doing these changes to ensure RoomOS performs to the maximum, and that we can help you to scale the deployment of JavaScript extensions in an efficient and secure manner.

Read more about macros on roomos.cisco.com.