Install Semarchy xDI Analytics

This page details how to install, configure, and run Semarchy xDI Analytics.

Installation process

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

Semarchy xDI 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 xDI Analytics installation process is as follows:

Download xDI Analytics
Prepare the infrastructure
Create the database schema
Configure the environment
Configure the database connection
Configure the users
Configure extra settings
Deploy Analytics

After deployment, further configuration will happen in the Analytics Web interface.

Depending on the Java Web Application Server you are using, the steps to install xDI Analytics will be slightly different. However, the following process should be the same for most applications, aside from locations and small details.

Download xDI Analytics

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

Prepare the infrastructure

You need:

An account with administrative rights on the application server to deploy and configure the Analytics application.
A database user account, which will be used by xDI Analytics to store its data in a database.

Create the database schema

Before installing xDI Analytics, you must create a database schema it can use. The schema is used to store all Analytics data. You can create the schema manually, or use your database administration interface.

We provide sample creation scripts in this section. Adapt this script based on your database configuration.

Example 1. Create a 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 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

Save what you put in for <analytics_db_user>, <analytics_db_password>, and <analytics_db_database_name> (for SQL Server), as you need them to configure the datasource.

Configure the environment

xDI Analytics stores configuration files, temporary data, logs, and additional drivers in a directory on the server. This directory is set by the XDI_ANALYTICS_WEBAPP_HOME environment variable. The user running the application server process must have read and write permissions for this directory. The application server log will return a warning in case of permission errors.

It is recommended to set XDI_ANALYTICS_WEBAPP_HOME to a different directory in than the application server folder, to keep xDI Analytics configuration files separate from the application server.

The following examples illustrate how to set the variable in different environments.

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%

Apache Tomcat must have this environment variable set. Otherwise, the folder will be created in a temporary work folder which will be removed by the application server.

When running Tomcat as a service on Windows, it is recommended to set the startup configuration using environment variables. You can do this in one of two ways:

From the Windows Control Panel.
By configuring the service using the Tomcat tooling.

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

Example 6. Add an environment variable for Tomcat as a service (Windows)

tomcat9 //US//Tomcat9 ++Environment XDI_ANALYTICS_WEBAPP_HOME=/usr/analytics/

Deprecated environment variables

Older versions of xDI Analytics supported the STAMBIA_WEBAPP_HOME environment variable. This environment variable is deprecated, and will no longer work after Designer version 2024.1 LTS.

Older configurations still using the STAMBIA_WEBAPP_HOME environment variable should change it to use XDI_ANALYTICS_WEBAPP_HOME instead.

Configure the database connection

xDI Analytics connects to its database via a datasource managed by the application server. You must install a JDBC driver and configure a datasource in order for the connection to work.

Install the database JDBC driver

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

For Apache Tomcat, install JDBC drivers by copying the appropriate files to the Tomcat lib directory.

Different application servers may need extra steps to make this driver visible to the application server or the datasource.

Configure the datasource

A JNDI datasource configures the connection to the storage database and schema. xDI Analytics looks for a datasource resource named jdbc/xdi-analytics-datasource-tomcat for Apache Tomcat, or jdbc/xdi-analytics-datasource for other application services.

You can configure the datasource in Tomcat by adding a resource to the Apache Tomcat Context configuration file (context.xml). The following example is for a PostgreSQL database named analytics_db on the localhost server using port 5432:

<Context>
  ...
    <Resource name="jdbc/xdi-analytics-datasource-tomcat"  (1)
    auth="Container" type="javax.sql.DataSource"
        driverClassName="org.postgresql.Driver" (2)
        url="jdbc:postgresql://localhost:5432/<analytics_db_name>" (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 datasource configuration properties.

Other application servers use different configuration formats. Refer to their documentation for more details, and make sure to use the jdbc/xdi-analytics-datasource resource name.

Configure the users

Users accessing xDI Analytics authenticate with the application. They receive a set of roles that control access to features in Analytics.

Configure the users who will access Analytics, and their roles, in the application server.

Configure users and roles in Apache Tomcat.

To add users and roles, edit the tomcat-users.xml file and add or modify user nodes as shown in the following template.

<tomcat-users>
  <user
    name="youruser"
    password="yourpassword"
    roles="admin-gui, manager-gui, analyticsAdmin, analyticsConnect" (1)
  />
</tomcat-users>

1	`analyticsAdmin` and `analyticsConnect` roles from Analytics, and `admin-gui` and `manager-gui` roles from Tomcat.

Analytics comes with the following roles, and their associated privileges:

Table 1. xDI Analytics roles
Role	Description
analyticsConnect	Grants login permissions. This role is required for all users connecting to xDI Analytics
analyticsAdmin	Grants full access to all the features with no restrictions. This role overrides other ones.
analyticsParameterConsult	Grants access to view parameters. This includes Preferences, Keys Editor, Security Editor, Runtime Editor, Log Databases Editor.
analyticsParameterAdmin	Grants access to modify parameters. This includes Preferences, Keys Editor, Security Editor, Runtime Editor, Log Databases Editor.
analyticsSessionConsult	Grants access to view the Sessions Reports.
analyticsSessionAdmin	Grants access to administer Sessions Reports. This includes viewing, creating, editing, deleting Sessions Reports.
analyticsSessionAction	Grants access manage delivery sessions. This includes starting, stopping, restarting, or deleting sessions.
analyticsRuntimeConsult	Grants access to view runtimes.
analyticsRuntimeAdmin	Grants access to operate and control runtimes. This includes scheduling a delivery, scheduling a purge, or running commands.
analyticsRepositoryConsult	Grants access to view Delivery Repositories and their configuration in the administration interface.
analyticsRepositoryAdmin	Grants access to administer Delivery Repositories and their configuration in the administration interface. This includes creating, editing, viewing, and running actions on Delivery Repositories.

For other applications servers, refer to their documentation for configuration steps.

Configure extra settings

Change the error messages

Apache Tomcat, and other application servers, displays their own HTTP error pages by default. For example, a 404 error would show the following:

Image of a generic Tomcat HTTP Status 404 error page

You can change these error pages if you want to display your own messages, or to hide web server information that is considered a security risk in some environments. xDI Analytics comes with generic, minimal error pages you can use.

To change error pages for Tomcat:

Open the conf/server.xml file.
Find the node that starts with <Engine name="Catalina".
Find its `<Host>`subnode.
Add or find a <Valve> node with the attribute className="org.apache.catalina.valves.ErrorReportValve", as shown in the following example:

<Server port="8005" shutdown="SHUTDOWN">
  <...>
  <Service name="Catalina">
    <...>
    <Engine name="Catalina" defaultHost="localhost">
      <...>
      <Host name="localhost"  appBase="webapps" unpackWARs="true" autoDeploy="false">
        <...>
        <Valve className="org.apache.catalina.valves.ErrorReportValve"
               errorCode.404="<path-to-file>" (1)
               errorCode.0="<path-to-file>" (1)
               showServerInfo="false" />
        <...>
      </Host>
    </Engine>
  </Service>
</Server>

1	Replace `<path-to-file>` with a path to an HTML file.

To use the error pages that come bundled with Analytics, use the <Valve> node with the following file references:

<Valve className="org.apache.catalina.valves.ErrorReportValve"
        errorCode.404="${catalina.base}/webapps/semarchy-xdi-analytics/WEB-INF/error404.html"
        errorCode.0="${catalina.base}/webapps/semarchy-xdi-analytics/WEB-INF/error.html"
        showServerInfo="false" />

More information about the Tomcat Error Report Valve is available in the Tomcat documentation.

Deploy Analytics

The final step is to deploy the xDI Analytics web application (the semarchy-xdi-analytics.war or semarchy-xdi-analytics.ear file) in your application server. Make sure that you have performed all the previous steps first.

To deploy Analytics in Apache Tomcat, copy the semarchy-xdi-analytics.war file to the Apache Tomcat webapp folder. Tomcat will recognize the file and complete deployment.

For other applications servers, refer to their documentation for detailed instructions.

Connect to Analytics

When you are finished, you can access xDI Analytics application at the following URL: http://<host>:<port>/semarchy-xdi-analytics/semarchy

The URL may vary depending on how the application server was configured.

After logging in with a user who has the necessary roles, the xDI Analytics main page opens.

The Apache Tomcat startup log file and console will show the following message once xDI Analytics storage is initialized:

Analytics datasource successfully initialized