Install Semarchy xDI Production Analytics

This document details how to install Semarchy xDI Production Analytics

Installation Process

Before the installation, make sure to understand the architecture and review carefully the system requirements.

Semarchy xDI Production Analytics is a web application that must be deployed on a Java Web Application Server and that requires a database to store its data.

The Semarchy xDI Production Analytics installation process is as follows:

  1. Download Semarchy xDI Production Analytics

  2. Prepare the Infrastructure

  3. Create the Database Schema

  4. Configure the Environment

  5. Configure the Database Connection

  6. Configure the Users

  7. Deploy Analytics

Depending on the Java Web Application Server you are using the steps to install Semarchy xDI Production Analytics will be slightly different. The procedure presented below should however be similar in all applications, with only locations and details changing.
After the deployment, the configuration will take place directly in the Web interface of Analytics.

Download Semarchy xDI Production Analytics

Semarchy xDI Production Analytics is shipped as an archive file, containing a Web Application Archive.

Prepare the Infrastructure

You will need an account with administrative rights on the application server to deploy the Analytics application and configure the application.

You will also need a database user account used by Semarchy xDI Production Analytics to store its data in a database schema.

Create the Database Schema

Before installing Semarchy xDI Production Analytics, you must create the database storage for its data, which includes session reports, configurations, delivery projects, preferences, etc.

You can create it manually or use your database administration interface for this purpose. In this section, we provide sample scripts for creating this storage. Make sure to adapt this script to your database configuration.

Example 1. Create the storage schema (Oracle)
CREATE USER <analytics_db_user> IDENTIFIED BY <analytics_db_password>
 DEFAULT TABLESPACE USERS TEMPORARY TABLESPACE TEMP;
GRANT CONNECT, RESOURCE TO <analytics_db_user>;

-- The following command should be used for Oracle 12c and above
GRANT UNLIMITED TABLESPACE TO <analytics_db_user>;
Example 2. Create a database and the storage schema (PostgreSQL)
/* Create a database */

CREATE DATABASE <postgresql_database_name> WITH ENCODING 'UTF8';

/*
 * Disconnect and then reconnect using:
 *  the JDBC URL:  jdbc:postgresql://<host>:<port>/<postgresql_database_name>
 *  or using psql with the following command: psql -U postgres <postgresql_database_name>
 */

CREATE SCHEMA extensions;
GRANT USAGE ON SCHEMA extensions TO PUBLIC;
ALTER DEFAULT PRIVILEGES IN SCHEMA extensions GRANT EXECUTE ON FUNCTIONS TO PUBLIC;
ALTER DATABASE <postgresql_database_name> SET SEARCH_PATH TO "$user",public,extensions;

/* Create the user and schema */

CREATE USER <analytics_db_user> WITH PASSWORD '<analytics_db_password>';

/* Use the following syntax for PostgreSQL 9 */
-- CREATE USER <analytics_db_user> WITH UNENCRYPTED PASSWORD '<analytics_db_password>';

/*
 * The following command is required only for PostgreSQL running on Amazon RDS.
 * It grants access to the storage to the RDS superuser.
 */
-- GRANT <analytics_db_user> TO <rds_superuser_name>

CREATE SCHEMA <analytics_db_user> AUTHORIZATION <analytics_db_user>;
Example 3. Create a database, login, and user (SQL Server)
/* Create a database */

CREATE DATABASE <analytics_db_database_name>
GO

/* Configure the database */

ALTER DATABASE <analytics_db_database_name> SET READ_COMMITTED_SNAPSHOT ON;
GO

ALTER DATABASE <analytics_db_database_name> SET QUOTED_IDENTIFIER ON;
GO

/* Create a login to connect the database */

CREATE LOGIN <analytics_db_user> WITH PASSWORD='<analytics_db_password>', DEFAULT_DATABASE=<analytics_db_database_name>
GO

/* Add a user for that login in the database */

USE <analytics_db_database_name>
GO

CREATE USER <analytics_db_user> FOR LOGIN <analytics_db_user>
GO

/* Make this user database owner */

ALTER ROLE db_owner ADD MEMBER <analytics_db_user>
GO
Store the values of the <analytics_db_user>, <analytics_db_password>, and the <analytics_db_database_name> (for SQL Server), as you will need them later to configure the datasource.

Configure the Environment

Semarchy xDI Production Analytics stores configuration files, temporary data such as logs, as well as additional drivers required to connect to Runtime Log Databases in a folder located in the server. This folder is identified by the XDI_ANALYTICS_WEBAPP_HOME environment variable.

The user running the application server process must have read and write permissions on the folder defined in the XDI_ANALYTICS_WEBAPP_HOME variable. The application server log will give the information in the case of permission errors.
It is recommended to use for XDI_ANALYTICS_WEBAPP_HOME a folder separated from the application server folder, in order to preserve your Semarchy xDI Production Analytics configuration independently from the application server setup.

The following examples illustrate how to set this variable in the environment.

Example 4. Set a configuration property with an environment variable (Linux/UNIX)
# Set environment variable: Unix/Linux
export XDI_ANALYTICS_WEBAPP_HOME=/usr/analytics/
# See the variable value
# echo $XDI_ANALYTICS_WEBAPP_HOME
Example 5. Set a configuration property with an environment variable (Windows)
rem Set environment variable: Windows
set XDI_ANALYTICS_WEBAPP_HOME=C:/analytics/
rem See the variable value
rem echo %XDI_ANALYTICS_WEBAPP_HOME%

When running Tomcat as a service on Windows, it is recommended to set the startup configuration using environment variables. It can be achieved either:

  • From the Windows Control Panel.

    Environment variables set in the Control Panel must be set as System Variables when Tomcat runs as a service.

  • By configuring the service using the Tomcat tooling.

    Example 6. Add an environment variable for Tomcat running as a service (Windows)
    tomcat9 //US//Tomcat9 ++Environment XDI_ANALYTICS_WEBAPP_HOME=/usr/analytics/
For Apache Tomcat, make sure to define this environment variable. Otherwise, the folder will be created into Tomcat’s temporary work folder, which may be removed in the normal course of operations of the application server.

Configure the Database Connection

Semarchy xDI Production Analytics connects to the database schema via a datasource managed by the application server.

Install the Database JDBC Driver

Prior to configuring this datasource, install in the application server the JDBC driver corresponding to the database used for the storage.

Install Drivers in Apache Tomcat

To install the JDBC drivers in Apache Tomcat, copy the appropriate database driver file to the <tomcat>/lib directory.

Depending on the application server, this may require some additional configuration for making this driver visible by the application server or the datasource.

Configure the Datasource

You must define a JNDI datasource in the application server, which configures the connection to the storage database and schema.

The process to configure a datasource depends on the application server. Refer to your application server documentation for more details.
The datasource must be named jdbc/sta_datasource. For Apache Tomcat, it must be named jdbc/sta_datasource_tomcat.
Configure the datasource in Apache Tomcat.

You configure the datasource in Tomcat by adding a resource to your Apache Tomcat Context configuration file (context.xml). The resource name must be jdbc/sta_datasource_tomcat.

As an example, for a MySQL database named analytics_db on the localhost server and port 3306:

<Context>
  ...
    <Resource name="jdbc/sta_datasource_tomcat"  (1)
    auth="Container" type="javax.sql.DataSource"
        driverClassName="com.mysql.jdbc.Driver" (2)
        url="jdbc:mysql://localhost:3306/documentation" (3)
        username="<analytics_db_user>" (4)
        password="<analytics_db_password>" (4)
        maxTotal="100" (5)
        maxIdle="30" (6)
        maxWaitMillis="10000" (7)
    />
  ...
</Context>
1 Datasource Name.
2 JDBC Driver classname.
3 JDBC URL to connect the database.
4 Username and password defined when you created the database schema
5 Maximum number of database connections in pool. Make this value large enough to handle all of your connections. Set to -1 for no limit.
6 Maximum number of idle connections kept in the pool at all times. Set to -1 for no limit.
7 Maximum time to wait for a database connection to become available in ms. Set to -1 to wait indefinitely.
See the Apache Tomcat documentation for a full list of datasources configuration properties.

Configure the Users

Users accessing Semarchy xDI Production Analytics connect using the application authentication and receive a set of roles that give them access to certain features in Analytics.

You must configure the users who will access Analytics with the relevant roles in the application server.

The configuration steps depend on the application server. Refer to your application server’s documentation for detailed instructions.
Configure users and roles in Apache Tomcat.

To add users and roles, edit the tomcat-users.xml` file and add/modify the users as shown in the template below.

<tomcat-users>
  <user
    name="youruser"
    password="yourpassword"
    roles="admin-gui, manager-gui, analyticsAdmin, analyticsConnect" (1)
  />
</tomcat-users>
1 The user has the two Analytics roles analyticsAdmin and analyticsConnect, in addition to the admin-gui and manager-gui Tomcat roles.

The roles for xDM Dashboard users, with their associated privileges, are listed below.

Table 1. Semarchy xDI Production Analytics Roles

Role

Description

analyticsConnect

This role must be granted for a user to log in. It should be granted by default to all users connecting to Semarchy xDI Production Analytics

analyticsAdmin

This role has full access to all the features with no restrictions. This role overloads the other roles.

analyticsParameterConsult

This role allows viewing the parameters (Administration menu).

analyticsParameterAdmin

This role allows modifying the parameters (Administration menu).

analyticsSessionConsult

This role allows viewing the sessions.

analyticsSessionAdmin

This role allows administering the sessions (session views creation).

analyticsSessionAction

This role allows managing the sessions (start, stop, restart, delete).

analyticsRuntimeConsult

This role allows viewing the runtimes.

analyticsRuntimeAdmin

This role allows administering the runtimes.

analyticsRepositoryConsult

This role allows viewing the repositories.

analyticsRepositoryAdmin

This role allows administering the repositories.

Deploy Analytics

Finally, you can deploy the Semarchy xDI Production Analytics web application (the semarchy-xdi-analytics.war or semarchy-xdi-analytics.ear file) in your application server.

The deployment steps depend on the application server. Refer to your application server’s documentation for detailed instructions.
Make sure that you have performed all the previous steps (JDBC driver installation, datasource and user configurations) before deploying Semarchy xDI Production Analytics.
Deploy Semarchy xDI Production Analytics in Apache Tomcat

To deploy Analytics in Apache Tomcat, copy the semarchy-xdi-analytics.war file to the Apache Tomcat webapp folder. Tomcat will auto-deploy the application.

Connect to Analytics

When the deployment is complete, you can access the Semarchy xDI Production Analytics application at the following URL (This URL may vary depending on the application server configuration): http://<host>:<port>/semarchy-xdi-analytics/semarchy

After logging in with a user having the required roles, the Semarchy xDI Production Analytics main page opens.

In the Apache Tomcat startup log file (or the console), the following message appears once the Semarchy xDI Production Analytics storage is initialized:

Analytics datasource successfully initialized