The Sisense Advanced Configuration FAQ is a collection of informational content, best practices, and frequently asked questions for Sisense customers. This article is broken down into the following categories: Embedding, Rebranding, Automation, Administration, Security, Architecture, and Best Practices
Embedding
Sisense offers three methods to embed dashboards and widgets into other sites or applications: iFrame, Embed SDK and SisenseJS.
iFrame
You can embed Sisense dashboards and widgets in non-Sisense environments, such as in your own websites or applications by concatenating parameters to the URL of your dashboard or widget.
The simplest way to see how your dashboard or widget will look like embedded is to add ?embed=true to the end of the dashboard or widget URL.
For example: mysite.com/app/main#/dashboards/5541dc7a80a4e2181e00011a?embed=true
To find more details about embedding via iFrame please take a look at our documentation here.
Embedding Tips:
- In case your end users are designers and you want them to be able to edit the dashboard in embed mode just omit the ?embed=true part from the URL.
- If you want to pass over filters from the URL, follow this documentation.
- Use iframes Sparingly - iframes provide an easy way to embed content from one web site into another, but they should be used cautiously. They are 1-2 orders of magnitude more expensive to create than any other element. You can find more information here.
Resources:
- Documentation (including embedding URL parameters)
- Mozilla iFrame Documentation
Embed SDK
The new Sisense Embed SDK is a Javascript library that allows you to drastically reduce the amount of code and effort required to embed Sisense Dashboards in your application while providing your users with a seamless, well integrated experience.
The Sisense Embed SDK removes the hassle normally associated with iFrame-based embedding, especially when it comes to implementing interactions between the host page and the embedded dashboard. You can find more information here.
SisenseJS
SisenseJS is a JavaScript library that enables you to embed Sisense components in web pages without the use of iFrames.
By embedding the SisenseJS library, you can:
- Load Sisense runtime anywhere, without iFrames
- Load dashboards in runtime
- Render all/part/new widgets in any DOM container
- Embed Sisense visualizations into your mobile applications
To find out more about SisenseJS read our documentation here.
iFrame versus SisenseJS Embedding
| iFrame | EmbedSDK | SisenseJS | |
|
Time to deployment |
5 - 10 Hours | 10 - 15 Hours | 50 - 150 Hours |
| Ability to embed Dashboard? | Yes | Yes |
No |
| Ability to embed individual Widgets? | Yes | Yes | Yes |
| Ability to use SSO? | Yes | Yes | Yes |
| Customization | Based on Sisense Capabilities and Styles | Ability to pass parameters from parent application | Full ability to customize styles, UI components; Can create one's own filters |
| Library Collisions | None | None | Potentially Cause collisions with AngularJS and JQuery* |
| Export Functionality | Yes | Yes | Needs to be recreated |
*SisenseJS uses AngularJS (version 1.4.6) and JQuery (version 2.0.3)
Resources:
Best Practices for Authenticating Users when Embedding Sisense
Implementing Single Sign-On (SSO) to automatically authenticate users to Sisense for embedded dashboard/widgets greatly improves your user's experience. SSO is a mechanism that allows a system to authenticate users and subsequently tell Sisense that the user has been authenticated. The user is then allowed to access Sisense without being prompted to enter separate login credentials.
Sisense SSO supports two SSO protocols for securing the exchange of user authentication data JSON Web Token (JWT) and SSO via SAML 2.0 (Security Assertion Markup Language).
For more information, see these pages:
SSO via SAML 2.0 documentation
Release Notes (for breaking changes on updates)
How do I apply scope dynamically to embedded dashboards?
Sisense allows the passing of Dashboard Filters by URL Parameters. Keep in mind that once you pass Dashboard Filters by URL Parameters, the default Dashboard Filters applied to the dashboard will be overwritten by the ones passed via URL. You can find more details on how to pass dashboard filters by URL here.
Rebranding
Sisense enables you to rebrand (white label) the Sisense Web Application into your native application or site by using the Sisense REST API to replace existing icons and images with your own. You can find more details on white labeling Sisense here.
In order to change Sisense style color from yellow to your brand's color, follow this article.
In addition, you can rebrand the automated emails Sisense sends to match your company's branding. You can find more details for rebranding automated emails here.
Can I choose which automated emails are sent by Sisense?
There is no native supported way to disable individual emails, but you can achieve the effect by following the steps in this article.
How do I change the Sisense sender email address?
Sisense automatically sends emails when certain actions occur, such as a new user being added, a dashboard being shared with a user. or a Pulse alert being fired. As an OEM who has re-branded Sisense as your own application, it is important to change the sender email address to something your customers will recognize. Email reports are sent by default from sisense-admin@sisense.com. To find out how to change the sender email address please follow the steps in the following article.
How do I change the dashboard links in my Sisense emails?
Update the Alias property (and potentially SSL property) in System Configuration:
Localization
Sisense natively supports localization of the web application and ElastiCube metadata. Localization of ElastiCube data can be configured via the data model.
Resources:
Internationalization and Localization
Automation
Many aspects of Sisense can be automated: user creation, group creation, data security application, and even ElastiCube creation. These tasks can be achieved by leveraging the Sisense REST API and Sisense Shell (PSM.EXE)
Example 1 - Scheduling ElastiCube builds using Windows Task Scheduler
Utilizing Sisense Shell we can schedule and execute ElastiCube builds based on a trigger or more robust schedule. To find out how to do this please read this article.
Example 2 - Automatically Backup Sisense Web Data
Sisense uses MongoDB for storing your Sisense web environment information. This information includes how dashboard and widgets are configured, your system's users and groups, and many other configurations. Since the web environment can regularly change, and may need to be restored, it's useful to keep regular backups of this data. To find out how to do this please read this article.
Backup of the ElastiCubes and Dashboards is recommended prior to any Upgrade.
Administration
How do I implement a Development to Production workflow for Dashboards and ElastiCubes?
Establishing a proper development to production process is important for managing the release of changes and updates to existing Dashboards and Elasticubes. As a Best Practice, we recommend before changing anything in your production environment that you set aside some possible downtime and let your users know that dashboards will be changing.
How you implement this process depends on your Sisense implementation:
Single Stack implementation (You only have one installation of Sisense in your organization)
How do I promote my development ElastiCube to Production?
- Back up the production ElastiCube by exporting the ElastiCube to an .ecdata file
- Wondering how to export an ElastiCube, click here.
- Open the development Elasticube's Schema file (.ecube) in the ElastiCube Manager
- Rename the development ElastiCube's schema file to the same name as the Production ElastiCube.
- Build the renamed development ElastiCube. The build will replace the production ElastiCube with the development ElastiCube.
If you would like to revert back to the previous state of the ElastiCube, import the backup of production you created during the first step in this process.
How do I promote my development Dashboard to Production? (Replace my production dashboard)
As a best practice we recommend setting aside a designer or admin user that will hold all the production dashboards. This prevents a user from accidentally making changes to a dashboard in production.
- After a Designer has completed a dashboard they will make the designated production dashboard account owner of their dashboard. The Designer can also export the dashboard and share it with the owner of the Production dashboard account.
- Wondering how to export a dashboard, click here.
- However the dashboard was given to the Production account, the production account will need to edit the .dash of the dashboard. Open the new dashboard's .dash file in your favorite text editor.
- In the .dash file, change the dashboard ID of the New Dashboard to the dashboard ID of the Original Dashboard you are replacing.
- You can find the Dashboard ID of the original from the dashboard's URL:
- Import the Dashboard into Sisense. Sisense will prompt you that a dashboard with that name already exists. Select to overwrite the original dashboard.
Two or more Sisense Servers implementation (Separate development and production environments)
ElastiCube - The process does not change much from a Single Stack environment. The only difference is that the development and production are not the same server. You will need to export the development Elasticube from the development environment and move it over to the production server. If the development ElastiCube has the same name as the Production ElastiCube:
- Back up the production ElastiCube by exporting the ElastiCube to an .ecdata file
- Wondering how to export an ElastiCube, click here.
- Import the ElastiCube from the development environment. Remember that this overwrite the production Elasticube.
If the development ElastiCube name is not the same, please follow the same process for a single stack implementation after migrating the ElastiCube.
Dashboards - In version 6.6 of Sisense, we introduced a feature to enable dashboard migration across servers. You can find additional details on our dashboard migration feature here. If you do not want to use the dashboard migration feature you can follow the same process as above, but remember to export the Dashboard from the development environment and move it over to the Production environment.
How do I limit the dashboard and Pulse sharing autocomplete to only that user's current group?
When a user with a Designer license shares a dashboard or Pulse alert by default they can share it with any user in your Sisense environment. To limit the list to only users in that users group, Sisense has created a supported plugin. You can find more details about the plugin and how to install it here.
Exports (Email, PDFs)
Sisense lets users generate CSV, PNG, PDF, and Excel exports (from pivot tables) from the web application.
Generally CSV and PNG exports work seamlessly in complex deployments, but PDF and Excel exports may require additional configuration to work correctly.
PDF Reports
Please refer to this elaborated documentation: Error Exporting To PDF
There are three primary errors encountered in complex deployments. These errors and solutions pertain to Sisense 7.1 and lower.
Issue: PDF report and emails aren't generated when you are accessing the web application over HTTPS/SSL, typically with a fixed host name in IIS (web server) but succeed locally on the server over HTTP.
Fix: Open C:\Program Files\Sisense\PrismWeb\vnext\config\default.yaml and navigate to the exporting section. Default text:
exporting:
host: "localhost"
port: "default"
protocol: "http"
Change it as follows:
exporting:
host: "mysubdomain.mydomain.com" <-- Update to your IIS-defined host name
port: "443" <-- Update to the port you're accessing your site over
protocol: "https" <-- Update to the protocol you're accessing your site over
Save the file and restart IIS (run 'iisreset' in the Command Prompt as an administrator).
-----
Issue: "This shouldn't have happened error" at the end of the export process with a JavaScript snippet (typically after the export is successfully generated)
Fix: Typically caused by JavaScript errors from plugins or scripts. Review scripts or plugins for JavaScript errors (for example, by opening Developer Tools
-----
Issue: PDF export times out on complex dashboards/widgets after 2 minutes with a blank screen and no export generated
Fix: Open C:\Program Files\Sisense\PrismWeb\vnext\config\default.yaml and navigate to the exporting section. Default text:
exporting:
host: "localhost"
port: "default"
protocol: "http"
DPI: 95
exportPath: '\sisense\exports\'
store_days: 2
requestTimeout: 120
resourceTimeout: 120
Update requestTimeout and resourceTimeout to 300 (or whatever value in seconds desired). Save the file and restart IIS (run 'iisreset' in the Command Prompt as an administrator).
For more general PDF/email issue troubleshooting, please see this page.
Exports logs are at C:\Program Files\Sisense\PrismWeb\vnext\iisnode.
Excel Exports
Sisense introduced Excel exports for pivot tables in Sisense 6.7. Please see Troubleshooting Export to Excel Issues for troubleshooting problems with these exports.
The most common issue is the error "File could not be generated" in situations with defined host names in IIS, load balancers, or reverse proxies. Please see Step 6 of Setting Up SSL to the required configuration settings.
Limiting Exports
Sisense administrators can use the REST API to control exporting capabilities at the role level. They can also use a plugin to do the same with finer control.
Embedded Exports
Customers using SisenseJS will need to recreate Sisense's exporting options using the REST API.
Upgrades and Migrations
Best Practices
- Back up your environment before upgrading
- Update your development or production environment first (if you do not have a development environment, please contact your Customer Success Manager)
- Test plugins and scripts in the newest version
- After testing, then upgrade your production environment
- Review Update and Migration FAQ page for other tips
- See Migrating a Sisense Installation for migration steps
Backups
We recommend customers take regular backups of their Sisense environment. Many customers accomplish this by taking and storing images of the server (this is often included in hosting packages such as AWS). Our hosted cloud customers automatically receive daily, weekly, and monthly backups of the server. For other customers, please see:
- Backup documentation
- Community post to back up Sisense via batch script
- Backup files list
Security
In Sisense Administrator page you can define users, groups and user’s roles one by one.
In order to load a big amount of users or groups, we recommend using Sisense REST API.
Through Sisense REST API you can also define data security rules for all users at once.
In case you are already managing security using a file, you can load this file using a script to define your Sisense Data Security.
Architecture
There are alternatives to the default single stack implementation of Sisense. Please note that some features of Sisense might not work in alternative implementations.
An overview of the supported deployment architectures on Windows is outlined here.
Split Server (Build Node and Query Node) - In some cases you might want to separate the ElastiCube server (Build Node) and Web Server (Query Node). This requirement usually comes up in cases where you want the Build Node to be behind an internal firewall while the Query Node is available externally. This can be set up using the Multi-Node Deployment Wizard starting on Sisense Version 7.4.
The Pulse feature requires an additional configuration when using a split server implementation.
The required change:
Open the ElastiCubeConfiguration.xml file on the Build Node - (C:\ProgramData\PrismServer).
Update the RabbitMQServer with the IP address of the Query Node.
High Availability - Sisense provides flexible design choices for supporting high availability (HA) and scalability for your Sisense configuration. To configure Sisense for high availability or optimized performance by scaling out Sisense servers, you must build in redundancy, thus reducing potential downtime or bottlenecks.
This requires a minimum of three servers ("nodes"): a build node to run ElastiCube builds and distribute built cubes to other nodes via the Sisense Orchestrator service, and two query nodes with the web application and as part of a MongoDB replica set. A load balancer is responsible for routing users to a query node, and ElastiCube Sets route queries to available ElastiCubes.
For more information:
Multinode Overview (including Sisense Orchestrator)
MongoDB Replica Set Documentation
Note: High availability must be enabled in your license. For more information please contact your Customer Success Manager.
SSL, Bindings and HTTPS Redirect
For general information about making the Sisense web application publicly accessible, domain names (DNS), and certificates, see Share Sisense Web Application Externally.
Customers can configure the ports and protocols that their Sisense application uses in Microsoft IIS (web server).
OEM customers typically serve Sisense over HTTPS and port 443.
For information on setting up SSL in Sisense, please see Setting Up SSL
After making the changes, also change the System Configuration Alias to use HTTPS (steps here). Depending on the configuration, you may need to update the default.yaml file in the email steps above.
To redirect HTTP requests to the HTTPS version of the site, see here.
Plugins, Scripts, and Customization
Only the plugins listed in Sisense Add-Ons are supported, meaning that they are tested with each Sisense release and promptly fixed when issues are identified.
All other plugins and scripts, whether developed in-house or posted in our community, are not supported. Please test plugins and scripts when upgrading Sisense, as functionality can change between versions.
For assistance or issues with unsupported plugins or scripts, please post a comment on relevant community page. The plugin's creator and our consultants review these posts.
Custom Scripts
As a web-based dashboarding tool, Sisense offers a JavaScript API for customizing visualizations, creating new plugins, and generally extending front-end functionality.
For resources on extending Sisense, please see the following pages:
JavaScript API Community Forum
For specific questions or issues in the development process, please post to the relevant page in our community.
Sisense's Professional Services team of field engineers creates custom scripts and plugins for customers on the basis of a paid engagement. Please contact your Customer Success Manager to learn more or request a quote.
Usage Analytics
Sisense supports usage analytics in version 7.3+. Documentation on this feature can be found here.
Alternative methods to track usage data:
Use Google Analytics to track usage
Import web request logs from the MongoDB
- Accessing the Sisense Application Database
- Sisense MongoDB Driver
- Data is stored in the monitor database, trace collection
Best Practices
Should I create an ElastiCube per customer or one consolidated ElastiCube will all my Customer's data?
This is a popular question when wanting to support multi-tenancy via your Sisense application.
There are three options when tackling this problem:
- One Consolidated ElastiCube
- ElastiCube per Customer
- Hybrid Approach
One consolidated ElastiCube with all your Customer's data is usually the most efficient option.
- One ElastiCube will allow easier management and build scheduling.
- Our Data Security feature can then be used to limit your customer to their data.
Reasons not to choose the consolidated model
- Combing your customer's data demands table sizes exceeding 1 Billion records
- Customer's data is required to be seperated
- Customer's KPI requirements are diverse enough that having everything consolidated will result in an overall complex data model
If you choose that an ElastiCube per customer is the right approach, please review the following Best Practices.
- No more than 2 concurrent ElastiCube builds on a single stack implementation
- When working with many ElastiCubes we recommend staggering Elasitcube builds. If you would like to find out how to do this please reference this article.
- No more than 40 ElastiCubes per server
A Hybrid approach takes the strengths of the previous two options. Your configuration will contain an ElastiCube that serves multiple Customers and a mix of ElastiCubes that serve customers individually. The customers who have their own Elasitcube will need their own versions of the Dashboard.
Are there any best practices for upgrading to a new version of Sisense?
Every new release of Sisense comes with a slew of new features and bug fixes. With how fast Sisense is adding new features, some old functionality might break. You can review any breaking changes in the release notes here.
Before upgrading to the latest version of Sisense, it is recommended that you upgrade a copy of production or development environment. Test the latest upgrade and ensure that all your dashboards and plugins are functioning as expected. After everything has been verified upgrade your production environment.
If you do not have a development environment please contact your Customer Success Manager.
For additional details on upgrading please review the following FAQ