Upgrading QBeeQ Plugins – QBeeQ

This document provides a step-by-step guide to:

Upgrading existing QBeeQ plugins to new versions

Troubleshooting upgrades

‼️

Customers are generally responsible for upgrading their plugins to the latest version. If you are interested in having QBeeQ maintain and upgrade plugins on your behalf, please reach out to info@qbeeq.io

Before you start

👤 To upgrade the QBeeQFramework or plugins, the user must be in an Admin role.

🛑

If you have made any changes/customizations to any plugin files (as instructed by documentation or QBeeQ), please review Retaining customizations when upgrading before proceeding.

Considering new Sisense versions

QBeeQ plugins are built with backwards compatibility in mind. There is no specific order that must be adhered to when considering upgrading the Sisense version or QBeeQ plugins.

As best practice, it’s recommended to utilize a Dev (or equivalent) environment to run upgrades first, before upgrading to a production environment.

However, it is up to each customer, based on how they execute, test and monitor upgrades, in which order upgrades happen.

Checking for new versions

QBeeQ will notify customers when new versions of plugins are available using the notification indicator. New versions are also communicated through our QBeeQ Connect newsletter.

We recommend checking for new versions each time you access the QBeeQ Framework to ensure that you are seeing the most up-to-date information.

To check for new versions:

Navigate to the QBeeQ Framework Tab

Click Check for Updates on the QBeeQ Framework dashboard

Any plugins with new versions will have an active, blue link, displaying the version number. The current version, and when it was last updated is also displayed.

Retaining customizations when upgrading

⚠️

Failure to complete these steps may result in the loss of custom settings

Most QBeeQ plugins include advanced features and settings that are stored directly within the plugin files, most commonly in config.js. Any changes made to these files are specific to an individual customer’s environment.

Because QBeeQ does not have access to customer environments, we cannot provide upgrade files tailored to each customer’s customizations.

ℹ️

All plugin files provided by QBeeQ are generic, intended for all customers, and include only the default configuration.

Before Upgrading Plug-ins (Required)

Before upgrading any plug-ins, customers must:

Identify which plug-ins have been customized

This ensures that anyone performing the upgrade is aware of existing changes that could be overwritten

Export and save copies of any modified files

This preserves a record of all customizations and allows them to be restored after the upgrade

💡

When making customizations for the first time or ongoing, it is recommended to version your changes by commenting your code (format will change based on code language). This allows you to track changes and identify which files are the most recent.

Folders and files can be exported directly from the File Management page.

Maintaining compatibility with new functionality

As we continue to develop functionality, depending on the use case, we may add features directly into (usually) the config.js or add additional settings to the config.js to support features available in the design panel or widget.

Review the Release Notes to identify if we have made any changes to the code files.

Preserving customizations when upgrading

Customers can retain their custom configurations using one of the following two methods:

Option 1: Replace the Generic File Before Upload

After extracting the updated plugin files, replace the generic file (for example, config.js) with your current customized version

Do not change the file name

Follow the steps in Upgrading plugins

Option 2: Manually Reapply Customizations After Upload

Follow the steps in Upgrading plugins

Open the new file and manually copy and paste the customized settings from the previous version

Save the changes

Using Option 2 will require the add-on to recompile, since the files are being modified directly within the File Manager.

⚠️

Failure to complete these steps may result in the loss of custom settings.

Upgrading plugins

💡

We recommend upgrading the QBeeQ Framework first, before upgrading plugins.

To upgrade a plugin to a newer version:

Click the download link

Unzip/extract the files

⚠️

Sometimes, unzipping/extracting creates a nested file structure. Verify that you are selecting the root folder that contains the files directory.

The folder structure should look like:

plugins/<PluginName>/files and NOT plugins/<PluginName>/<PluginName>/files

Double-check that there is only one folder inside plugins before proceeding.

Open two browser tabs or windows:

Add-ons

File Management

🛑

If you have made changes/customizations to any plugin files (ex. config.js), please refer to the Retaining customizations and changes when upgrading section before taking the next step.

On the File Management page, drag and drop the extracted plugin folder into the top level of the /plugins/, not inside another plugin folder

💡

You should be prompted to replace existing files. If not, you're likely copying it to the wrong location.

Confirm the file replacement

🛑

Do not refresh or close the File Management page until the compilation process is complete

Switch back to the tab or window with the Add-ons page

Adding new files to the /plugins/ folder should trigger the compilation (build) process to start automatically, or the system will prompt you to refresh. The process should take 1-2 minutes.

💡

If the compilation doesn't start automatically or the system does not prompt you to refresh, manually trigger the process by disabling and enabling any plugin.

🛑

Do not refresh or close the Add-ons page until you receive a confirmation message

Once the upgrade of the new version is complete, the download link will no longer be active. If you need to rollback to a previous version for any reason, reach out to support@qbeeq.io

ℹ️

If you encounter bugs or issues post-upgrade, please contact support@qbeeq.io and provide the following information:

Sisense version

Plugin name

Plugin version

Details about the issue

Providing screenshots and videos can also help to expedite a resolution.

Troubleshooting

Below are some troubleshooting steps for common, but not frequent, issues that can occur when upgrading. If after troubleshooting the issue persists, contact support@qbeeq.io and provide the following information:

Sisense version

Details about the issue

Reproduction steps

Providing screenshots and videos can help expedite a resolution.

Verify the add-on compilation (build)

Go to the .bin folder inside the plugins directory.

The files should show a recent modified date. The compilation did not run successfully if the file dates haven’t changed.

Plugin not displaying

Following installation, if plugins are not displaying in the Add-ons as expected, follow the troubleshooting steps below.

Follow the Previous Steps

Ensure that you have installed the QBeeQFramework plugin using the installation steps above

Ensure that you have installed any additional plugins using the installation steps above

Verify the QBeeQFramework has been installed successfully

Return to the Add-ons and verify the QBeeQ Framework is set to enabled

Navigate to the QBeeQ Framework tab

Verify the dashboard and plugins is visible

Click on one of the icons in the dashboard (ex. Info icon)

Navigate to another tab or close the QBeeQ Framework tab

Clear Browser Cache

Open Developer Tools (Press F12 in Google Chrome)

Right-click the browser’s page reload icon and select "Empty Cache and Hard Reload"

Check if the Plugin Appears on the Add-ons Page

If the plugin is listed, proceed to the next step

If the plugin is missing, verify that:

The uploaded folder matches the one inside the zipped file and is not nested

The folder name does not contain a date reference (e.g., avoid qbeeqExpandablePivot_exp_09-09-2022)

If necessary, delete the previously uploaded folder and re-upload the correct one—renaming alone won’t work

Check the .bin folder

If you see files with a timestamp longer than a few seconds/minutes ago, the build may have failed.

Disable and Re-enable the Plugin

Go to the Add-ons page, disable the plugin, then enable it again.

Wait for the build process to complete before exiting or refreshing the page

Contact Support If the Issue Persists

Email support@qbeeq.io for assistance

Include your Sisense version in the email to help our support team troubleshoot effectively

Plugin showing expired

Sometimes, license information needs to be refreshed or the plugin will show as “Expired”. If you see an expiration message for the plugin, follow these steps to refresh your licensing information.

Check Licensing Status

Click the Check Licensing button

After the page refreshes, go to the QBeeQ Framework tab again

If the list is still empty, there may be an issue retrieving licensing details

Manually Refresh Licensing Data

Go to Admin > REST API > 1.0

Find the GET /custom_data/query endpoint

Click the Try it out button

In the query parameter field, enter {"isQBeeQFramework": true}

Click Execute and check the response

Clear and Refresh Licensing Data

Go to DELETE /custom_data/query

In the query field, enter {"isQBeeQFramework": true}

Click Execute to delete outdated licensing records

Reload the Add-ons Page

Open the Add-ons page

Upon loading, the system will retrieve updated license details and restart the QBeeQ licensing service

Test the Plugin

Navigate to the QBeeQ Framework tab

Verify the dashboard and plugins is visible

Click on one of the icons in the dashboard (ex. Info icon)

Navigate to another tab or close the QBeeQ Framework tab

ℹ️

If the issue persists, please contact support@qbeeq.io and provide the following information:

Sisense version

Details about the issue

Reproduction steps

Providing screenshots and videos can help expedite a resolution.