All eazyBI for Jira eazyBI for Confluence Private eazyBI
All eazyBI for Jira eazyBI for Confluence Private eazyBI

Installation on Confluence
eazyBI for Confluence

On this page:

Checklist before installation

Supported versions

The latest eazyBI version supports Confluence versions from 6.0 to 7.13. In addition, you will need MySQL 5.5 - 5.7 (MySQL 8 is supported starting from the eazyBI version 6.2), PostgreSQL 9.x - 11.x, MS SQL Server 2008 or later, or Oracle 10g or later database. Linux, Windows, and macOS operating systems are supported. Please contact eazyBI support if you have questions about supported versions or if you have any issues with your specific environment.

Possible issue with NFSv3 mounts

eazyBI is relying on command flock and this command may ‘freeze’ when accessing files on the NFSv3 mount if this mount and file locking infrastructure are not properly configured. We recommend using NFSv4 instead of v3 for Jira Shared Home mounts. In case when NFSv3 is the only available option for Jira Shared Home mounts please validate if the flock is working correctly.

On all Jira nodes please execute these two commands (please update the path to Jira shared home folder)

touch <JIRA_SHARED_HOME>/test_file
flock <JIRA_SHARED_HOME>/test_file -c 'sleep 1'

If the flock command will run as expected it will finish after a few seconds. If it ‘hangs’ (more than 10 seconds) then it is not working properly. The most common reason for that is a firewall blocking ports used for file locking.

Java versions

Java 8 is supported for the Confluence versions 6.x and 7.x as well as Java 11 is supported starting from the Confluence version 7.1. Only Oracle or OpenJDK JVMs are supported.

Confluence memory settings

Please review your current Confluence memory settings before installing eazyBI. If your Confluence server will not have enough available memory then eazyBI might fail to start as well as overall Confluence performance could be affected.

To ensure better performance of eazyBI it is recommended to set Confluence Java VM available memory to 2 GB or more. See Confluence documentation for more information.

It is recommended to enable the Child process option to run eazyBI report queries in a separate JVM process.

UTF-8 encoding

It is recommended to use UTF-8 encoding for Confluence.

Installation

Download the eazyBI app and install it in Confluence Administration / Manage apps.

Initial setup

After the eazyBI app installation, click the Get started link to navigate to the eazyBI getting started page. After reloading the page you should also see the eazyBI link in the top navigation bar.

It might take about half a minute while eazyBI is loading for the first time. If you selected the eazyBI link then you should see the eazyBI welcome page. You should be logged in as a Confluence user with system administration rights to set-up eazyBI. Click Set up eazyBI to continue.

Database connection

eazyBI will store data in an additional MySQL, PostgreSQL, Microsoft SQL Server, or Oracle database. You can use the same database server which is used by Confluence or you can also use a different database server. It is recommended that you create a separate database user for eazyBI needs (by default with the name eazybi_confluence) which will then create additional databases in a specified database server.

Please make regular backups of the additional eazyBI database in the production environment. eazyBI database contents will not be included in the standard Confluence XML backup or in the Confluence database schema backup.

The following are database server-specific instructions for the eazyBI database setup.

MySQL

As a MySQL administrator create a MySQL user eazybi_confluence with access rights to all databases which start with eazybi_confluence:

GRANT ALL PRIVILEGES ON `eazybi_confluence%`.* TO 'eazybi_confluence'@'%' IDENTIFIED BY 'secret'; 

(Replace secret with a chosen password). When you will save eazyBI settings then a database connection will be established and a database will be created. Later when additional eazyBI accounts will be created then each account data will be stored in separate databases with names eazybi_confluence_dwh_N where N is the account ID number.

You should add the MySQL JDBC driver to your application server. If you have done it already for the Confluence main database then you don’t need to do anything, eazyBI will use the same installed MySQL JDBC driver.

If you have a large number of Confluence pages then for faster eazyBI Confluence data import it is recommended to tune MySQL memory settings. The following my.cnf settings are recommended:

innodb_buffer_pool_size = 1024M
innodb_log_file_size = 256M
query_cache_size= 16M
query_cache_type = 1
max_connections = 200

innodb_buffer_pool_size will specify how much database data MySQL can store in memory – adjust it to your available server memory (the more data MySQL will store in memory the less disk input/output operations will be performed). If you will change innodb_log_file_size then it will require that you delete existing MySQL log files before starting the MySQL server.

Please adjust max_connections as needed based on MySQL usage by all applications. eazyBI connection pool will use up to 50 database connections.

Please ensure that MySQL eazybi_confluence  database tables are using the InnoDB storage engine (which is a default starting from MySQL 5.5) and not the old MyISAM storage engine.

If the installation of eazyBI fails with the Packet for query is too large  error then you need to increase the database server parameter max_allowed_packet . See more details.

PostgreSQL

Create a PostgreSQL database user with

CREATE ROLE eazybi_confluence PASSWORD 'secret' LOGIN CREATEDB;

After saving eazyBI plugin settings, a new eazybi_confluence database will be created and each new eazyBI account will store data in a new dwh_N schema (where N is the account ID number) in the same database.

If you have a large number of Confluence pages then for faster eazyBI Confluence data import it is recommended to tune PostgreSQL memory settings. The following postgresql.conf settings are recommended:

shared_buffers = 512MB
wal_buffers = 16MB
max_connections = 200

shared_buffers will specify how much database data PostgreSQL can store in memory – adjust it to your available server memory (the more data PostgreSQL will store in memory the less disk input/output operations will be performed). wal_buffers affects the performance of writing transaction logs to disk.

Please adjust max_connections as needed based on PostgreSQL usage by all applications. eazyBI connection pool will use up to 50 database connections.

Microsoft SQL Server

Create an MS SQL Server user eazybi_confluence – if you will use SQL Server Management Studio then select SQL Server authentication and uncheck Enforce password policy. In addition, from Server Roles select dbcreator (to allow the creation of a new eazybi_confluence database). If you do not want to grant the dbcreator role to this user then create the eazybi_confluence database manually and use the eazybi_confluence user as the owner of this database.

In database connection settings, provide the hostname, leave the port blank (if default 1433 is used) and leave the instance blank (if the default should be used) and enter a database, username, and password. After saving the settings, a new database will be created (if not yet present) and each new eazyBI account will store data in a new dwh_N schema (where N is the account ID number) in the same database.

By default, eazyBI uses a bundled jTDS JDBC driver to connect to Microsoft SQL Server. The jTDS driver does not support an SSL connection to SQL Server. If SSL is required for your SQL Server connection, then you can use the Microsoft JDBC driver which supports SSL connections.

Oracle

Create an Oracle database user eazybi_confluence. For example, create from sqlplus with the Oracle system user:

CREATE USER eazybi_confluence IDENTIFIED BY secret DEFAULT TABLESPACE users;
GRANT CONNECT, RESOURCE TO eazybi_confluence;

(Replace secret with a chosen password). Please make sure the eazybi_confluence user has no TABLESPACE quota or it is large enough. In the database connection settings, provide a hostname, database name (instance or SID name of database), username, and password. You can use the same database instance that is used by Confluence, all eazyBI data will be stored in a separate eazybi_confluence user schema.

eazyBI will use the Oracle JDBC driver ojdbc8.jar from the Confluence installation. Please add it to the Confluence installation if it is not added yet.

If you would like to specify in database connection settings the Oracle service name instead of SID name, then please prefix it with /. So in the Database field use either SID_NAME or /SERVICE_NAME.

You can also specify the Oracle database connection's TNS alias (when using the tnsnames.ora file) or a full TNS connection string. In this case, do not specify a Host name in the eazyBI database connection parameters, just specify the TNS alias or a connection string in the Database name:

  • When using a TNS alias then please ensure that oracle.net.tns_admin Java property is set to the TNS admin directory.
  • When using a TNS full connection string then you do not need to set this Java property, you can enter in the Database name the full connection string, for example:
    (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=ORCL)))

It is recommended to set the OPEN_CURSORS system parameter to 1000. eazyBI keeps open prepared statements for frequently used SELECT, INSERT and UPDATE statements and calls them with different bind variable values.

If there will be any issues with establishing the database connection or with the database creation then you will see the corresponding error messages after clicking the Update button.

Increase database max pool size

Each eazyBI processes, like displaying report results or performing the import, requires a connection to the database. By default, eazyBI is allowed to use 20 concurrent connections to the database. If you see errors in log files like

ActiveRecord::ConnectionTimeoutError (could not obtain a database connection. The max pool size is currently 20; consider increasing it.)

Increase eazyBI connection pool size in eazyBI general settings tab under "Edit database advanced settings" link, as for example the following settings will increase max pool size to 40

pool = 40

Child process

Please read more about the Child process option which is recommended for larger Confluence Server and Confluence Data Center instances.

License key

Select license type Atlassian Marketplace (if you created a trial license key there) or eazybi.com (if you have received a partner license key)..

Enter the corresponding license key (and also the organization name in case of eazybi.com license type). If there will be any issues with the entered license name or key then you will see the corresponding error message.

After you have entered the license information click Update license settings to continue.

If you need to return back to the eazyBI Settings screen then log in as a Confluence user with system administration rights and in any eazyBI page click on the System Admin link on the top right corner and then select Settings.

Perform the first Confluence data import

If database connection and license information were correct, then the eazyBI database will be created as well as the first eazyBI account (with the default name “Confluence reports”). In one eazyBI account, you can import one or several Confluence spaces, create reports, charts and dashboards and give access to selected Confluence users and groups. If in your Confluence server you have many different spaces that are used by different user groups then most probably you will need to create several eazyBI accounts and in each account import related subset of Confluence spaces.

After clicking Create, a new Confluence source application will be created and you can

  • select which Confluence spaces you would like to import in the first eazyBI account;
  • select if you would like to search queries;
  • how frequently a regular issue import should be scheduled (by default once per day);
  • select if page create, update, view events should be processed (necessary for importing page views).

Click Import to start the data import.

Check import results

After the import is completed, go to the Analyze tab and try to open sample reports.

Export to PDF

If you would like to export dashboard pages to PDF or send regular emails with eazyBI dashboards as PDF attachments then please install the headless Google Chrome browser and Microsoft's Core Fonts on your Confluence server.

Troubleshooting

If the initial eazyBI page does not open or opens with an error message, then check in the Confluence installation directory logs subdirectory log files with the name catalina.*.log. Please provide these log files to eazyBI support.

After eazyBI has started it will create its own log files.

Sometimes after reinstalling apps, Confluence is not releasing all memory and it might cause a slowdown. In this case, try restarting the Confluence server process.

Please contact eazyBI support if you have any issues with the eazyBI installation and setup.