This chapter contains procedures for using a script to install Analytics on the WebCenter Sites web application.
This chapter contains the following sections:
The silent installer is a Java-based script, developed on Ant. The script installs Analytics locally (on the computer where it is executed) and non-interactively.
The more common installation scenarios are covered in this chapter. They are:
Single-server: Installing Analytics and its database on a single server (Figure 25-1)
Dual server: Installing Analytics and its database on separate servers (Figure 25-2)
Enterprise-level: Analytics in fully distributed mode (Figure 25-3)
A silent installation involves all the steps from preparing the installation folders and setting up the database to deploying the web applications and utility programs. The remaining sections of this chapter, starting with Installation Steps guide you through the steps that you need to complete in order to run the silent installer. Below is a summary.
Briefly, you will do the following to install Analytics, after ensuring that prerequisites (in Chapter 26, "Prerequisites for Installing Analytics") are satisfied:
Unzip Analytics:
Unzip Analytics on the master node. (In a distributed installation, unzip Analytics on other relevant nodes, including the server that hosts SQL Plus.)
Note:
Consider the following:The silent installer is packaged with the Analytics product.
The silent installer must be executed on the SQL Plus host in order to update the Oracle database with Analytics-specific schema.
Unzip Analytics on the WebCenter Sites host.
Note:
The silent installer must be executed on the WebCenter Sites host in order to initialize WebCenter Sites to Analytics. You will help to initialize by specifying the location of the WebCenter Sitesfuturetense_xcel.ini property file, so that it can be modified by the silent installer with Analytics-specific settings.
Initializing WebCenter Sites enables the AddAnalyticsImgTag to capture data on site visitors. For more information about the AddAnalyticsImgTag, see the chapter "Enabling Data Capture for Different Types of Reports" in the Oracle Fusion Middleware WebCenter Sites: Analytics Developer's Guide.
Customize the analytics-build.properties file for Analytics. Customize the file on every server where the Analytics product was unzipped to declare information that the silent installer needs in order to correctly deploy the Analytics product in your environment, and to initialize Analytics to WebCenter Sites (as explained in the note above).
Prepare to run the installer by checking environment variables and classpaths to make sure they are properly set.
Install and deploy Analytics by running the silent installer on every server where the Analytics product is unzipped.
Configure WebCenter Sites to enable Analytics. In this step, you customize the analytics-build.properties file on the WebCenter Sites host.
When the silent installer starts running, it performs the following steps:
Prepares Analytics product folders to store all the installed components, ready for your use.
Prepares a separate subdirectory for the Analytics/Hadoop job scheduling system.
Sets up and prepares a separate subdirectory for the hdfsagent utility, required by the sensor.war web application.
Customizes various configuration files (shown in Chapter 28, "Tuning Analytics Configuration Parameters"), using the values that you specified in the analytics-build.properties file:
Renames global.xml-dist to global.xml and sets its properties to the values that you specified in analytics-build.properties.
Renames log4j.properties-dist to log4j.properties and sets its properties to the values that you specified in analytics-build.properties.
Customizes properties in futuretense_xcel.ini (one of the WebCenter Sites property files).
Updates your Oracle database with the Analytics database schemas by using SQL Plus and running the following scripts: create_sys.sql, create_normal.sql, and region.sql.
Unpacks the reports.zip archive and places the files in a subdirectory (on the local file system) referenced by the reporting engine.
Auto deploys the Analytics web applications (sensor.war, analytics.war, and analyticsadmin.war) to your designated application server.
The silent installer on the WebCenter Sites host updates the WebCenter Sites system, allowing it to determine that Analytics is installed. This update enables the analytics link, displayed in the upper left-hand corner of the WebCenter Sites Admin interface.
Note:
Before starting the steps in this section, ensure that all prerequisites listed in Chapter 26, "Prerequisites for Installing Analytics" are satisfied.Steps for installing Analytics are the following:
Step 2. Customizing analytics-build.properties for Analytics
Step 3. Preparing to Run the Silent Installer
Step 5. Configuring WebCenter Sites to Enable Analytics
The Analytics product, analytics2.5.zip, contains the silent installer.
Complete one of the following steps, depending on the type of installation you plan to create:
Single-server installation (Figure 25-1). In this scenario, you are installing Analytics on its own server (which hosts all Analytics supporting software). Unzip analytics2.5.zip on the server.
Dual-server installation (Figure 25-2). In this scenario, you are installing Analytics and its database on their own servers.
Unzip analytics2.5.zip on the Analytics server.
If SQL Plus is installed on the database server's host, unzip analytics2.5.zip on the database server's host. (To enable communication between SQL Plus and the Oracle database, the silent installer must be run on the server that hosts SQL Plus.)
Enterprise-level installation (Figure 25-3). In this scenario, you are installing Analytics in fully distributed mode. Unzip analytics2.5.zip on the master node and on each remaining server where you wish to install Analytics components.
For example, if your load balancing scheme requires multiple Analytics Sensors (data capture applications) to be deployed on different data capture nodes, unzip analytics2.5.zip on all the data capture nodes.
Note:
To enable SQL Plus to update the Oracle database with Analytics-specific schema, make sure thatanalytics2.5.zip is unzipped on the server that hosts SQL Plus.Unzip analytics2.5.zip on the WebCenter Sites host.
Continue to Step 2. Customizing analytics-build.properties for Analytics.
The analytics-build.properties property file contains all the environment-specific configuration data that is required by the Analytics silent installer. In this step, you will customize analytics-build.properties in order to provide installation specifications to the silent installer. (The analytics-build.properties file is divided into sections. Each section is specific to certain information necessary to tailor the system for your use.)
Complete the following steps on each server where you plan to install Analytics (or its components):
To customize analytics-build.properties for Analytics
Back up analytics-build.properties (located in the root of the Analytics Kit).
Open analytics-build.properties in a text editor of your choice, and set the properties as indicated in the following sections:
Section 27.2.2.3, "System Configuration and Operation Defaults"
Section 27.2.2.5, "Application Server Deployment Properties"
Section 27.2.2.7, "Hadoop Properties"
Note:
Windows Only. When you specify the path to an installation directory, be sure to enclose the path in double quotes if it contains spaces.This group of properties provides information of a generalized nature for the installation process. In this section, you will specify paths to Analytics directories, the location of third-party components, and the email addresses of administrators who can reset passwords and create accounts.
Table 27-1 General installation properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Absolute path to the final Analytics installation directory. |
|
|
Absolute path to the directory where the Swiff Chart product is installed. Note: The path must end with a slash (on UNIX) or backslash (on Windows). |
|
|
Email address for the Analytics administrator who is responsible for password recovery. Set the email address in the |
|
|
Email address of the Analytics administrator who is responsible for creating accounts. Set the email address in the |
|
|
URL at which help relating to Analytics can be obtained:
|
Visitor detection is done by the Analytics Sensor (data capture application). By default, the analytics-build.properties file supports the Sessionfingerprint method of tracking visitors across all sites. The Sessionfingerprint method identifies each visitor by a combination of the IP address, screen resolution, and agent string.
Using Table 27-2, verify or set (as indicated) the visitor detection properties in analytics-build.properties. The properties specify how identifiers are generated by the system for inclusion in object impressions (which are captured and processed by the system). Identifiers are important to providing the correct grouping of object impressions for aggregation.
Note:
An object impression is a single invocation of thesensor servlet. For more information, see the section "Object Impressions" in Oracle Fusion Middleware WebCenter Sites: Analytics Administrator's Guide.Table 27-2 Visitor detection properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Specifies the ID generator that is used to identify sessions. Caution: The default value is |
|
|
Specifies the ID generator that is used to identify a visitor to the site. Note: The default value is If the default generator is insufficient, you have two other options by which to uniquely identify a visitor: self-organized detection and cookie method. If you wish to implement these options or refine the |
Verify that the encoding property in analytics-build.properties is set to UTF-8 and the application server's setting is set to the same value. The silent installer will set the encoding parameter in global.xml to the value that you provide in analytics-build.properties.
Set the properties related to data processing and archiving (described in Table 27-3), as necessary:
Table 27-3 Data processing and archiving properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Allows the system to derive relative midnight used for file rotation. Relative midnight and the Format: minutes Default value: |
|
|
Specifies whether buttons for navigating to the WebCenter Sites interface are enabled or disabled in the Analytics interface. Default value: |
|
|
Specifies whether HDFS Agent archiving of raw data files is enabled. If To enable archiving, set this property to Default value: |
|
|
Specifies the path to the directory for storing archived data files. Must be a valid URI. Sample value:
Format: directory path |
|
|
Specifies the start time ( For example, to start archiving at 4:00 PM every day, set: Format:24-hour format, expressed as Default value: |
|
|
Determines when purge jobs will run. When this property is set to Default value: |
sensor.requestqueue .maxsize |
Specifies This property specifies a threshold value that triggers a The threshold value for this property is expressed as an object impression, i.e., a single invocation of the (The Analytics Sensor component is represented in the Overview option of the Components tab in the panel of the Analytics Administration interface, shown in the figure Hadoop Jobs Process Flow in the Oracle Fusion Middleware WebCenter Sites: Analytics Administrator's Guide. Default value: |
sensor.requestqueue .warnsize |
Specifies This property specifies a threshold value that triggers a The threshold value for this property is expressed as an object impression, i.e., a single invocation of the (The Analytics Sensor component is represented in the Overview option of Components tab in the panel of the Analytics Administration interface, shown in the figure Hadoop Jobs Process Flow in the Oracle Fusion Middleware WebCenter Sites: Analytics Administrator's Guide. Default value: |
In this section, you will specify the WebCenter Sites URL and the basic URL (http://<address>:<port>) where each Analytics web application will reside after the installation is complete. See Table 27-4.
In this section, you will specify which application server the installer will use to deploy the Analytics web applications. You will also disable the unused application servers. See Table 27-5, Table 27-6, Table 27-7, and Table 27-8.
Note:
Ensure the following:For the application server that will be used, set its install property to true. Set all other relevant properties.
For each unused application server, do not delete the statement pertaining to the application server. Verify that the application server's install property is set to false (the default). Otherwise, the installer will try to deploy the Analytics web applications to that server.
Table 27-5 WebLogic deployment properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
WebLogic admin user id. |
|
|
Password for the WebLogic admin user specified above. |
|
|
Server name, cluster name, or virtual host name. |
|
|
URL to the admin function in WebLogic. |
|
|
Path to the WebLogic home directory. |
Table 27-6 JBoss deployment properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
Path to the JBoss deployment directory. |
Table 27-7 Tomcat deployment properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
Path to the Tomcat home directory. |
Table 27-8 WebSphere deployment properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
WebSphere admin user id. |
|
|
WebSphere admin password. |
|
|
WebSphere home directory. |
|
|
WebSphere node name. |
|
|
WebSphere |
|
|
WebSphere |
|
|
Location of the Analytics |
|
|
Namespace that has been defined to represent a single node (machine instance) or multiple nodes where a software component is distributed and run. When installing an Analytics application on the WebSphere application server, you must specify how the application is to be distributed, by specifying the name of the cell and node where the application will be installed and run. |
|
|
Name of the server within the WebSphere installation where the application is deployed. |
In this section, you will specify information that the installer will use to access the Oracle database to store Analytics data. You will also specify JDBC/JNDI information to be placed in the Analytics configuration files. JDBC and JNDI data are mutually exclusive. Only one of them must have its enabled property set to true. See Table 27-9, Table 27-10, and Table 27-11.
Table 27-9 Database properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
Database home directory. |
|
|
System user name. |
|
|
System user password. |
|
|
Host address. |
|
|
Host port number. |
|
|
Database SID. |
Table 27-10 JDBC database writer properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
Name of the database connection. |
|
|
There must be exactly one connection marked with |
|
|
Type of connection: |
|
|
JDBC driver class. |
|
|
JDBC URL |
|
|
JDBC attribute. Database user name |
|
|
JDBC attribute; database password |
Table 27-11 JNDI properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Set to |
|
|
Name of the database connection. |
|
|
There must be exactly one connection marked with |
|
|
Type of connection: |
|
|
JNDI attribute. JNDI name |
In this section, you will provide information about your Hadoop configuration (Table 27-12):
The base path to the Hadoop installation directory
Paths to raw data. One path specifies where, on the local file system, raw data will be recorded by the Analytics Sensor (data capture application). The other path specifies where, on the Hadoop distributed file system, the raw data will be written by the HDFS agent.
Table 27-12 Hadoop properties in analytics-build.properties
| Property | Description |
|---|---|
|
|
Path to the Hadoop installation directory. |
|
|
The default path in HDFS for writing Analytics raw data. |
|
|
URL of the Hadoop task tracker web application. |
|
|
URL of the Hadoop file system web application. |
|
|
Local file system path where the data capture application will record raw data. |
Before running the silent installer, complete the following steps on all servers where you unzipped the silent installer:
Make sure that JAVA_HOME and ANT_HOME in your environment are set to the correct paths.
Start all the Analytics application servers (they must be running for the silent installer to work).
If you are using UNIX, issue the following command to ensure that the next command (to run the installer) can be executed:
chmod +x analytics_install.sh
If you are installing on WebLogic, run one of the following commands to ensure that the classpath is properly set and the WebLogic deployment task will run correctly:
UNIX:
<WL_HOME>/server/bin/setWLSEnv.sh
Windows:
<WL_HOME>\setWLSEnv.bat
In this step, you will run the silent installer, which will install the Analytics product against the analytics-build.properties file, in which you specified:
Where Analytics will be installed on your file system.
Which application server you wish to use and where it exists.
The location of your database.
The location of your WebCenter Sites.
Where other associated products or software components are located on your system.
This section contains the following installation scenarios:
In this scenario, you will install the entire Analytics product on the same server that runs all Analytics supporting software.
To install Analytics on a single server
Run the silent installer:
UNIX:
./analytics_install.sh
Windows:
analytics_install.bat
Note:
For descriptions of the components that are installed, see Table 27-13. For information about the events that occur when the silent installer runs, see the next step in this procedure.When the analytics_install command begins executing, the installation process begins and the script performs the steps listed in Section 27.1.2, "Silent Installer Actions." When the installation process completes successfully, the following message is displayed:
The silent install has finished. -------------------------------------------------------------- Your installation of Analytics is complete. Please review your application server documentation and make sure that it is configured for UTF-8 encoding. --------------------------------------------------------------
Note:
If an error occurs, the installation process terminates and displays the following message:"The install script ended with error code nn. Please consult the log and check for errors."
If an error is reported on the console, inspect the analytics-install.log to identify the problem (the analytics-install.log file is located in the directory where the silent installer resides). Typically, problems arise when one or more properties have been incorrectly configured. Carefully review and correct any property which is not correct, then rerun the silent installer.
If an error occurs because of failure to find a necessary component, make the appropriate adjustments to your JAVA_HOME, or ANT_HOME environment settings, and rerun the silent installer.
When the installer has successfully completed its task, initialize WebCenter Sites to Analytics. Go to Step 5. Configuring WebCenter Sites to Enable Analytics.
In this scenario, you will install the Analytics product on the server that hosts Analytics supporting software, except for the database. The Analytics database is installed on its own server.
To install Analytics on two servers
Run the silent installer on the server where you wish to install Analytics:
UNIX:
./analytics_install.sh sensor hadoopjobs analytics analyticsadmin cs_integration verify_install
Windows:
analytics_install.bat sensor hadoopjobs analytics analyticsadmin cs_integration verify_install
When the analytics_install command begins executing, the installation process begins. For information about the events that occur when the silent installer runs, see step 2 in Section 27.2.4.1, "Single-Server Analytics Installation."
Run the silent installer on the database server, where SQL Plus is already installed. (Running the silent installer initializes the Oracle database with Analytics schema, as explained in Table 27-13. See the Ant target database.):
UNIX:
./analytics_install.sh database
Windows:
analytics_install.bat database
When the installer has successfully completed its task, initialize WebCenter Sites to Analytics. Go to Step 5. Configuring WebCenter Sites to Enable Analytics.
For a distributed installation, you will install different parts of the Analytics product on the servers where you unzipped analytics2.5.zip. You will run the analytics_install command and specify which part (i.e., Ant target) to install on the given server. If your selected target has dependencies on supporting systems, the silent installer will verify that the supporting systems are installed (and running in the case of the Analytics database). Table 27-13 lists each target that is recognized by the silent installer and its dependency on other systems.
To install Analytics in distributed mode
Run the installer on each Analytics server where you wish to install an Analytics component:
UNIX:
./analytics_install.sh <Ant_target>
Windows:
analytics_install.bat <Ant_target>
Note:
The<Ant_target> parameter can be an individual Ant target or a space-separated list of targets, defined in Table 27-13. To install targets one at a time, run the silent installer for each target. If you do not specify a target, all Analytics components (defined in Table 27-13) will be installed on the given server.Table 27-13 Ant targets and their dependencies
| Ant Target | Description | Server on which to Unzip Silent Installer | Dependencies |
|---|---|---|---|
|
|
Installs the data capture web application and HDFS Agent (Oracle-specific). |
Data Capture |
None |
|
|
Installs the Oracle-specific Analytics/Hadoop job scheduler. |
Master Node |
Oracle |
|
|
Updates the Oracle database with Analytics schema. The |
Server on which SQL Plus is installed |
Oracle |
|
|
Installs the Analytics reporting engine web application. |
Administration, Reporting |
Oracle |
|
|
Installs the Analytics administration web application. |
Administration, Reporting |
Oracle |
|
|
Modifies The silent installer locates |
WebCenter Sites Host |
None |
|
|
Provides an object impression used to verify Hadoop Jobs. Note: You will use this target when verifying the Analytics installation in Chapter 30, "Verifying Your Analytics Installation." |
Data Capture |
None |
When the analytics_install command begins executing, the installation process begins. For information about the events that occur when the silent installer runs, see step 2 in Section 27.2.4.1, "Single-Server Analytics Installation."
When the installer has successfully completed its task, configure WebCenter Sites to enable Analytics and specify the locations of the Analytics servers. Go to Step 5. Configuring WebCenter Sites to Enable Analytics.
Once Analytics is successfully installed, complete the steps below on the WebCenter Sites host.
Note:
WebCenter Sites does not have to be running in order for the steps in this section to be completed successfully.Specify the location of the WebCenter Sites futuretense_xcel.ini property file, so that it can be modified by the silent installer with Analytics-specific settings.
Open analytics-build.properties and modify the properties described in Table 27-14.
Table 27-14 Properties that update futuretense_xcel.ini
| Property | Description |
|---|---|
|
|
Specifies that WebCenter Sites is local (relative to the silent installer). Verify that this property is set to |
|
|
Specifies the location of the WebCenter Sites Sample values:
|
|
|
Specifies the path to WebCenter Sites Confirms to WebCenter Sites that Analytics is installed. This property modifies Sample value: Use the value that is set in |
Run the silent installer on the WebCenter Sites host:
UNIX:
./analytics_install.sh cs_integration
Windows:
analytics_install.bat cs_integration
When the silent installer completes its task, continue to Section 27.3, "Next Step."
Before verifying the Analytics installation, complete the following steps, as necessary:
Inspect the Analytics configuration files that have been updated by the silent installer. Refer to Chapter 28, "Tuning Analytics Configuration Parameters." This chapter also contains instructions for setting up logging for the Hadoop Job scheduler.
Optional. Modify the visitor tracking configuration. See Chapter 29, "Configuring Visitor Detection" for instructions.
To complete the Analytics installation, follow the steps in Chapter 30, "Verifying Your Analytics Installation."