Step-by-step guide: Create a custom plugin in Sisense
Summary: Vicki786 provides a comprehensive guide on creating custom plugins in Sisense to extend its capabilities. The discussion covers the purposes of custom plugins, such as adding interactive controls, managing filters, and integrating REST APIs. It also explains how to structure the plugin files, including JavaScript, configuration, and optional CSS for styling, as well as where to place these files within the Sisense directory on Linux. Instructions on testing the plugin and troubleshooting issues are included, along with references to additional resources for plugin development.
Purpose of custom plugins
Custom plugins in Sisense empower users to extend and tailor the platform's capabilities by integrating custom JavaScript code directly into dashboards. These plugins enable:
Interactive Controls: Add buttons, menus, or other UI elements to enhance user interaction.
Dynamic Filter Management: Programmatically read, set, or clear dashboard filters based on specific conditions.
REST API Integration: Interact with Sisense's REST APIs to perform actions like exporting data or retrieving dashboard information.
UI Customization: Modify the dashboard's appearance or behavior to meet specific user requirements.
Advanced Functionality: Implement features beyond standard widgets, such as rotating filter values or custom data visualizations.
Plugins are stored on the Sisense server and execute automatically upon dashboard loading, ensuring consistent behavior across user sessions.
When to use custom plugins
Consider developing a custom plugin when:
Scenario
Example
Automated Business Logic
Automatically apply filters based on user roles or current dates upon dashboard load.
Enhanced User Interaction
Introduce custom UI elements like "Reset Filters" buttons or dynamic dropdown menus.
External System Integration
Fetch data from or send data to external systems via RESTful APIs.
Dashboard Behavior Modification
Implement features like auto-rotating filter values or custom navigation between dashboards.
Limitations of Native Widgets
Achieve functionalities not supported by standard Sisense widgets or scripts.
Where Sisense Linux expects plugins
Sisense on Linux looks for custom plugins here:
/opt/sisense/storage/plugins/
Sisense automatically reads any plugin folder here and injects it into the dashboard UI. Any .js, .json, or .css files placed inside a plugin directory here will be loaded automatically by the Sisense web application.
What goes into a Sisense plugin?
Every Sisense plugin usually contains:
FilePurpose
plugin.json
Defines the plugin's metadata, including its name, version, and included files.
main.6.js
Contains the primary JavaScript code that dictates the plugin's behavior.
Configuration file (optional)
Such as config. 6.js for storing configurable parameters.
style.css (optional)
The plugin introduces custom UI components for styling.
Step-by-step plugin with explanations
Let’s walk through each file.
plugin.json — The Plugin Manifest
{
"name": "MyCustomPlugin",
"pluginInfraVersion": 2,
"isEnabled": true,
"source": ["main.6.js"],
"style": []
}What Each Line Means:
LineMeaning
"name"
Friendly name of the plugin. Used internally.
"pluginInfraVersion"
Always set to 2 for modern plugin support.
"isEnabled"
Controls if the plugin is active. Set to false to disable.
"source"
JavaScript file(s) to load. Here it's just main.6.js.
"style"
Optional list of CSS files to apply (e.g., ["style.css"]).
main.6.js — The plugin logic
What this code does:
CodeWhat it means
console.log(...)
Prints to the browser's console (for testing).
prism.on('dashboardloaded')
Sisense triggers this when a dashboard loads.
args.dashboard.title
Displays the title of the loaded dashboard.
Add CSS (Optional)
You can also style elements on the dashboard.
style.css
Update plugin.json to:
{
"name": "MyCustomPlugin",
"pluginInfraVersion": 2,
"isEnabled": true,
"source": ["main.6.js"],
"style": ["style.css"]
}Reload the dashboard to see the background color change.
How to test if the plugin works (not using the optional files)
Open a Sisense dashboard in your browser.
Right-click → Inspect → Console tab.
Reload the dashboard.
You should see this (in the above code example):
MyCustomPlugin loaded!
Dashboard loaded: [Your Dashboard Name]
This confirms:
Sisense recognized the plugin.
Your main.6.js was loaded.
The dashboard events are being detected correctly.
If you see nothing…
Here’s what to check:
What to check
Fix
Plugin files are not saved in the right path
Make sure the files are in /opt/sisense/storage/plugins/MyCustomPlugin/
plugin.json syntax error
Validate with a JSON linter
Browser cache is showing the old version
Do a hard refresh (Ctrl+Shift+R)
Sisense Web App didn’t pick it up
Restart Sisense web (or refresh UI with Ctrl + F5)
Example: config.6.js — Optional plugin configuration file
This file stores settings you might want to change without editing the core main.6.js code. For example, default filter values, color codes, or feature toggles.
// Configuration file for MyCustomPlugin
var MyCustomPluginConfig = {
defaultFilterName: "Filter One", // Default name of the filter to modify
defaultFilterValues: ["Value A"], // Default values to apply to that filter
enableButton: true, // Toggle to show/hide custom button
apiBaseUrl: "https://api.example.com"// Optional: URL to an external system
};CodeWhat it means
var MyCustomPluginConfig = {...}
Defines a global config object accessible from your main plugin script.
defaultFilterName
A string value that your plugin can use to target a specific dashboard filter.
defaultFilterValues
A list of default values to set for the filter.
enableButton
A Boolean switch that you can use in your code to optionally show or hide a UI button.
apiBaseUrl
A base URL to an external REST API—useful if your plugin makes external calls.
Example: style.css — Optional custom CSS file
This file applies custom styling to elements added by your plugin, such as buttons, messages, or popups.
/* Custom style for MyCustomPlugin */
.my-custom-plugin-button {
background-color: #007bff; /* Blue background */
color: white; /* White text */
padding: 8px 12px; /* Spacing inside the button */
border: none; /* No border */
border-radius: 4px; /* Rounded corners */
cursor: pointer; /* Hand cursor on hover */
font-size: 14px; /* Font size */
}
.my-custom-plugin-button:hover {
background-color: #0056b3; /* Darker blue on hover */
}
.my-custom-message {
font-style: italic;
color: #999999;
margin-top: 10px;
}CodeWhat it means
.my-custom-plugin-button
A styled button you could insert via JavaScript.
.my-custom-plugin-button:hover
A hover effect to improve interactivity.
.my-custom-message
Custom message text style, like a "No data available" notice.
References/related content
These links cover everything from hello-world plugins to advanced UI hacks and Linux-specific deployment tips.
Topic
What you’ll find
Step-by-step basics for creating, structuring, and testing a new plugin. Sisense Community
JavaScript Plugins Guide (sisense.dev)
Full client-side API reference (events, prism object, etc.) and environment setup. Sisense Developers
How to modify the UI, listen to events, and run JAQL/REST calls in a plugin. Sisense Developers
Building New Visualizations (Widgets)
Guide for adding entirely new widget types via a plugin. Sisense Developers
Minimal working sample you can copy as a starting point. Sisense Community
Framework for global CSS overrides and theming. Great Linux-friendly example. Sisense Community
JumpToDashboard Plugin (How to Use & Customize)
Shows config options for cross-dashboard navigation. Sisense Community
Metadata Plugin – Grouping Provider Example
Example of extending the metadata layer with multiple language/group mappings. Sisense Community
Working with Sisense Add-ons (Linux Docs)
Official instructions for installing, enabling, and managing add-ons on Linux servers. Sisense Documentation
Troubleshooting checklist (restart plugin service, logs, memory limits). Sisense Community.
Disclaimer: This post outlines a potential custom workaround for a specific use case or provides instructions regarding a specific task. The solution may not work in all scenarios or Sisense versions, so we strongly recommend testing it in your environment before deployment. If you need further assistance with this, please let us know.
