Upgrading QBeeQ Plugins

‼️

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

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

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.

Before you start

Checking for new plugin 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.

To check for new versions:

Navigate to the QBeeQ Framework

Click the Check for Updates button

Download the latest versions

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.

Unzip/extract the files from your local Downloads folder

Verify the correct folder structure

⚠️

Unzipping sometimes creates a nested folder 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.

Backup your plugin folder(s)

Always back up your existing plugin folder(s) before making any changes. You can do this by exporting the plugin folder(s) from within Admin > File Management

💡

The file manager will let you select multiple folders using Ctrl or Cmd

Preserve your customizations

🛑

If you have made any changes/customizations to any plugin files (as instructed by documentation or QBeeQ), please review the upgrade steps carefully. If you have questions or need help, send an email to support@qbeeq.io

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.

Edit the `config.js` locally

⚠️

Failure to complete this step may result in the loss of custom settings

After extracting the newest version of the plugin files, replace the generic config.js file with your customized version. Do not change the file name.

💡

Open the config.js directly from the local download folder, and copy/paste from the previous version to the current version

As we continue to develop functionality, depending on the use case, we may add features directly into 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.

Replacing plugin folders

Open File Management and Add-ons

Open two browser tabs or browser windows:

Admin > App Configuration > File Management

Admin > Server & Hardware > Add-ons

Bulk delete the existing plugin folders

Make sure you are in the /plugins folder

Select the folders for the plugins you are planning to upgrade

Use cmd or ctrl to select multiple folders

Use the delete icon in the toolbar and confirm the deletion

This action will trigger a build.

Monitor the build on the Add-ons page

Once it has completed, you will be prompted to refresh the page

🛑

Do not refresh or close the Add-ons or File Management pages. Wait for the build triggered by the deletions to complete before proceeding.

Bulk upload the new folders

Once the first build is complete and the page has been refreshed, on the File Management page

💡

Using the upload button ensures that you don't accidentally drop a folder in the wrong location or into another plugin's folder.

Make sure you are still in the /plugins folder

Click the upload icon from the toolbar

Select all of the newly configured folders

Confirm the upload

This action will trigger a build.

Monitor the build on the Add-ons page

Once it has completed, you will be prompted to refresh the page

Monitor the final build

🛑

Do not refresh or close the Add-ons or File Management pages until the compilation process is complete.

Once completed, the system will prompt you to refresh your screen. 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.

ℹ️

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.

Best practices for plugins with customizations

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 config.js file

As customizations are made, it is recommended to:

Identify which plug-ins have been customized and communicate this process to any users who may be performing upgrades, so that customizations do not get overwritten

Export, save and version copies of any modified files. You can version your changes easily by commenting your code (format will change based on code language). This preserves a record of all customizations, allows you to identify which files are most recent and allows them to be restored after the upgrade

🛑

Do not change the config.js file name