Export to Excel is the usual “must have” feature for an analytical platform. It isn’t different for Oracle Analytics, and that’s why the platform supported it for over 10 years. This was true before Data Visualization (DV) was added because DV from day 1 never had an export to Excel.

Obviously, users kept requesting it, and that’s why in the Oracle Analytics Cloud (OAC) release of November 2022 this feature has been added as a preview. It then turned into a default feature, enabled by default, in the January 2024 OAC release.
It isn’t a full Excel export, it only supports the export into a formatted Excel file of table and pivot visualization in a DV workbook.

OAS 2024 is the first OAS with a formatted Excel export in DV

In Oracle Analytics Server (OAS) the feature was introduced first in the 2024 release. Preview features of OAC are generally never released in OAS (the code is maybe there, but they are disabled and can’t be enabled), and that’s why it was first released only in OAS 2024 (released in April 2024) after being official in the OAC January 2024 release.

The surprise is how it is achieved!
It is an extremely different architecture compared to everything else in OAS. It isn’t a WebLogic deployment, it isn’t a server component, it is achieved by a piece of code running in Node.js.

Official documentation

The installation, configuration, and how to enable the feature are covered in the official documentation. There isn’t much else available for now.
https://docs.oracle.com/en/middleware/bi/analytics-server/administer-oas/enable-users-export-excel.html

Installation: it’s new, it’s different, it’s … deprecated

Being a Node.js piece of code, you are required to have Node.js installed on your OAS server. In most Linux distributions it is available on your preferred package manager. It must be Node.js 18.18.0 or newer. In Oracle Linux 8 the easy way to install Node.js is by using one of the available modules providing a given version of the Node.js runtime.

The first version of the documentation assumed that you knew Node.js and how it works, they simply provided the name and version of the packages you had to install, and it was up to you to figure out how.
Now it has been improved by providing a sample package.json which you can just create in a folder and in that same folder you can then execute npm install and the job is done. The packages and versions defined in the file will be installed.

Pay attention to defining the environment variable NODE_PATH correctly, that’s the one that could easily prevent the piece of code from working.

When installing, you will see some “not very reassuring” messages. This is because for some of the Node.js packages the version to install is strictly defined. It isn’t the latest, and some of those have been deprecated for a while already… At this point in time, you can’t safely just install newer versions: Oracle provides that list of packages and versions, and you must stick to it.
At the time of this blog post, when installing those packages you will see a message about “10 vulnerabilities (7 high, 3 critical)”.

“deprecated”, “critical security issues”, “known to be problematic”: are some of the messages you will see when installing the Node.js package required by Oracle.

Execution: take this sample and guess the rest

Once installed you then need to start that “thing”. You need to start it because this piece of code doing the DV export to formatted Excel does run a small webserver listening for requests on port 3001 by default (which can be changed with an environment variable). The documentation provides some example scripts to start and stop it.

The piece of code installed with OAS doesn’t provide any feature to define it as a process or a daemon and make sure it will automatically start with OAS and stop with OAS or that it is up and running and restart in case it crashes.
All that is up to you: you are in charge of everything, and Oracle only gives you the JavaScript code that has to be executed.

For the feature to work, the process node ${ORACLE_HOME}/bi/modules/oracle.bi.tech/obitech-serverside-exportexcel-bundle.js must be running.

One thing that bothers me is that we are executing something directly from the location where the binaries of OAS are installed. For many years now you generally never execute commands there directly. You execute commands from the domain folder, commands that are often only setting the environment details before calling a command or script from the ORACLE_HOME folder.

If that process crashes, there is no Excel export in DV anymore. And in my tests, I managed to crash it several times at the beginning when playing with it.

My way of running it in Linux? PM2

I’m not a Node.js developer, I only mess around with it for some basic needs.

While not being a Node.js expert, running a process directly and hoping it will stay up, in a production environment, is something that sounds wrong. The sample script provided in the documentation is at best usable for a PoC on your laptop I would say.

I did google a bit about how to execute that kind of script more robustly. Docker and Kubernetes seem to be the common answer to this need from the Node.js community. The issue is that there is no information on whether JavaScript file is fully standalone or not, how works, and how well it could handle networking (virtual or not) to interact with OAS.

In the end, I found PM2, a Node.js daemon process manager that will help you manage and keep your application online. I don’t really need to understand more than the bare minimum about how to use it, and it’s very straightforward.

Install PM2 by executing npm install pm2@latest -g (the -g installs this package globally, not just in the current folder, this is mostly to not have to handle paths pointing to it and just make it available globally).

Once PM2 is installed, starting the script is a single line: pm2 start ${ORACLE_HOME}/bi/modules/oracle.bi.tech/obitech-serverside-exportexcel-bundle.js

PM2 starts the Node.js scripts and makes sure it stays up and running.

PM2 will make sure it stays up. If for whatever reason it dies, PM2 will restart it, making the feature always available. If you want to stop it fully it is, once again, extremely simple: pm2 stop obitech-serverside-exportexcel-bundle

I still don’t know much about PM2, I don’t need to, it just makes me feel safe enough knowing that there is “something” looking after the obitech-serverside-exportexcel-bundle.js script and making sure it’s up and running.

The only missing step is to remember to start and stop it when you start and stop OAS because the start.sh and stop.sh scripts provided by OAS don’t look at all for that Node.js piece of script.

You can see my usage of PM2 in my OAS docker release: https://github.com/gianniceresa/docker-images/tree/master/OracleAnalyticsServer/7.6.0

What could be improved?

In the beginning, the documentation was very minimalistic, I’m pleased to see that a sample package.json file has been provided (I can’t say it’s because of my request, but I definitely asked Oracle if they really couldn’t improve it a bit). I would expect the installation of OAS to write that file somewhere, and ideally to have a “proxy” script in the domain folder of OAS instead of having to call directly something in the ORACLE_HOME folder.

I also would like an official comment about versions of the Node.js packages: some of them are defined with a strict version, but those versions are marked as deprecated and Node.js will tell you that they are deprecated and could include vulnerabilities (I didn’t check if there are known issues with them, but to be deprecated and not just old versions, there are good chances some issues exist).

This feature of exporting from DV formatted Excel files is very much not enterprise-ready. It looks and feels more like a PoC that was running on somebody’s laptop, and somehow it made it into the product.

In a next post, I will dive a bit more into how it works, because there are interesting things, including what could be a new way to impersonate users without needing Act As…

Share This