27 Procedures for Installing Analytics

This chapter contains procedures for using a script to install Analytics on the WebCenter Sites web application.

This chapter contains the following sections:

27.1 Overview of the Analytics Silent Installer

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.

27.1.1 Installation Summary

Briefly, you will do the following to install Analytics, after ensuring that prerequisites (in Chapter 26, "Prerequisites for Installing Analytics") are satisfied:

  1. Unzip Analytics:

    1. 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.

    2. 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 Sites futuretense_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.

  2. 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).

  3. Prepare to run the installer by checking environment variables and classpaths to make sure they are properly set.

  4. Install and deploy Analytics by running the silent installer on every server where the Analytics product is unzipped.

  5. Configure WebCenter Sites to enable Analytics. In this step, you customize the analytics-build.properties file on the WebCenter Sites host.

27.1.2 Silent Installer Actions

When the silent installer starts running, it performs the following steps:

  1. Prepares Analytics product folders to store all the installed components, ready for your use.

  2. Prepares a separate subdirectory for the Analytics/Hadoop job scheduling system.

  3. Sets up and prepares a separate subdirectory for the hdfsagent utility, required by the sensor.war web application.

  4. 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).

  5. 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.

  6. Unpacks the reports.zip archive and places the files in a subdirectory (on the local file system) referenced by the reporting engine.

  7. Auto deploys the Analytics web applications (sensor.war, analytics.war, and analyticsadmin.war) to your designated application server.

  8. 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.

27.2 Installation Steps

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 1. Unzipping Analytics

Step 2. Customizing analytics-build.properties for Analytics

Step 3. Preparing to Run the Silent Installer

Step 4. Installing Analytics

Step 5. Configuring WebCenter Sites to Enable Analytics

27.2.1 Step 1. Unzipping Analytics

The Analytics product, analytics2.5.zip, contains the silent installer.

To unzip Analytics

  1. 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 that analytics2.5.zip is unzipped on the server that hosts SQL Plus.

  1. Unzip analytics2.5.zip on the WebCenter Sites host.

  2. Continue to Step 2. Customizing analytics-build.properties for Analytics.

27.2.2 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

  1. Back up analytics-build.properties (located in the root of the Analytics Kit).

  2. Open analytics-build.properties in a text editor of your choice, and set the properties as indicated in the following sections:

27.2.2.1 General Installation Properties

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

Analytics.installation.path

Absolute path to the final Analytics installation directory.

swchart.instdir

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).

forgotpassword.value

Email address for the Analytics administrator who is responsible for password recovery. Set the email address in the global.xml file.

noaccount.value

Email address of the Analytics administrator who is responsible for creating accounts. Set the email address in the global.xml file.

href.help.value

URL at which help relating to Analytics can be obtained:

http://www.oracle.com/technetwork/middleware/webcenter/sites/overview/index.html


27.2.2.2 Visitor Detection Properties

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 the sensor 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

sessionIdGenerator

Specifies the ID generator that is used to identify sessions.

Caution: The default value is AppServerID. Do not modify this value. It is a reference to the object that generates the ID.

visitorIdGenerator

Specifies the ID generator that is used to identify a visitor to the site.

Note: The default value is SessionfingerprintId. The default value generates an identifier that is a combination of IP address, screen size, and agent (browser type).

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 Sessionfingerprint configuration (to detect visitors on selected sites), you can do so after Analytics is installed, by modifying global.xml directly. Instructions are available in Chapter 29, "Configuring Visitor Detection."


27.2.2.3 System Configuration and Operation Defaults

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

midnight.offset

Allows the system to derive relative midnight used for file rotation. Relative midnight and the session.rotate.delay determine when the daily cycle for capturing session data ends. (Information about session.rotate.delay can be found in Table 28-1.)

Format: minutes

Default value: 0

cs_enabled

Specifies whether buttons for navigating to the WebCenter Sites interface are enabled or disabled in the Analytics interface.

Default value: true

archive.enabled

Specifies whether HDFS Agent archiving of raw data files is enabled.

If archive.enabled is set to either true or false, the data.txt file will be deleted from the analytics root folder.

To enable archiving, set this property to true. Once archiving is enabled, HDFS Agent will automatically create archives of raw Analytics data on a periodic basis by moving data.txt to the archiving folder. (The archive directory and start time are specified in the following properties: archive.output.dir and archive.start.time)

Default value: false

archive.output.dir

Specifies the path to the directory for storing archived data files. Must be a valid URI.

Sample value:

  • Windows:

    archive.output.dir=file://d:/archive

  • Linux:

    archive.output.dir=/analytics/archive

Format: directory path

archive.start.time

Specifies the start time (HH:mm) for archiving raw data. The HDFS Agent will start the archiving task on a daily basis at the time specified in this property.

For example, to start archiving at 4:00 PM every day, set: archive.start.time=16:00

Format:24-hour format, expressed as HH:mm, where HH ranges from 00–23 and mm ranges from 00–59.

Default value: 06:00

purgejobs.enabled

Determines when purge jobs will run. When this property is set to true the system will automatically schedule cleanup jobs to remove subfolders and files after they have been successfully processed.

Default value: false

sensor.requestqueue 
  .maxsize

Specifies CRITICAL condition for the Analytics Sensor.

This property specifies a threshold value that triggers a CRITICAL (red) condition when the sensor cannot respond quickly enough to the amount of raw data that it needs to record. When the threshold is reached or exceeded, the Analytics Sensor component is displayed in red.

The threshold value for this property is expressed as an object impression, i.e., a single invocation of the sensor servlet.

(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: 10000

sensor.requestqueue
  .warnsize

Specifies WARNING condition for the Analytics Sensor.

This property specifies a threshold value that triggers a WARNING (yellow) condition when the sensor cannot respond quickly enough to the amount of raw data that it needs to record. When the threshold is reached or exceeded, the Analytics Sensor component is displayed in yellow.

The threshold value for this property is expressed as an object impression, i.e., a single invocation of the sensor servlet.

(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: 3000


27.2.2.4 Web Server URL Properties

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.

Table 27-4 Web server URL properties in analytics-build.properties

Property Description
analytics.sensor.web.server 

URL of sensor web application.

analytics.report.web.server 

URL of Analytics web application.

analytics.admin.web.server 

URL of Analytics administration web application.


27.2.2.5 Application Server Deployment Properties

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

install.weblogic

Set to true to deploy to WebLogic.

weblogic.userid

WebLogic admin user id.

weblogic.password

Password for the WebLogic admin user specified above.

weblogic.targets

Server name, cluster name, or virtual host name.

weblogic.admin.url

URL to the admin function in WebLogic.

weblogic.home.dir

Path to the WebLogic home directory.


Table 27-6 JBoss deployment properties in analytics-build.properties

Property Description

install.jboss

Set to true to deploy to JBoss.

jboss.deploy.dir

Path to the JBoss deployment directory.


Table 27-7 Tomcat deployment properties in analytics-build.properties

Property Description

install.tomcat

Set to true to deploy to Tomcat.

tomcat.home.dir

Path to the Tomcat home directory.


Table 27-8 WebSphere deployment properties in analytics-build.properties

Property Description

install.websphere

Set to true to deploy to WebSphere.

websphere.userid

WebSphere admin user id.

websphere.password

WebSphere admin password.

websphere.home.dir

WebSphere home directory.

websphere.node.name

WebSphere node name.

websphere.base.command

WebSphere wsadmin command.

websphere.save.command

WebSphere save command.

websphere.engine.instdir.value

Location of the Analytics reportingengine installation directory.

websphere.cell.name

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.

websphere.server.name

Name of the server within the WebSphere installation where the application is deployed.


27.2.2.6 Database Connection Properties

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

install.database

Set to true to run install schema queries.

db.home.dir

Database home directory.

db.sys.user

System user name.

db.sys.password

System user password.

db.host

Host address.

db.port

Host port number.

db.sid

Database SID.


Table 27-10 JDBC database writer properties in analytics-build.properties

Property Description

jdbc.enabled

True | false

Set to true to configure JDBC settings.

jdbc.name.value

Name of the database connection.

jdbc.default.value

There must be exactly one connection marked with default="true"

jdbc.type.value

Type of connection: jdbc

jdbc.classname.value

JDBC driver class.

jdbc.url.value

JDBC URL

jdbc.user.value

JDBC attribute. Database user name

jdbc.password.value

JDBC attribute; database password


Table 27-11 JNDI properties in analytics-build.properties

Property Description

jndi.enabled

True | false

Set to true to configure JNDI settings.

jndi.name.value

Name of the database connection.

jndi.default.value

There must be exactly one connection marked with default="true"

jndi.type.value

Type of connection: resource

jndi.resource.value

JNDI attribute. JNDI name


27.2.2.7 Hadoop Properties

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

hadoop.installation.path

Path to the Hadoop installation directory.

hadoop.hdfs.defaultfs

The default path in HDFS for writing Analytics raw data.

hadoop.tasktracker.url

URL of the Hadoop task tracker web application.

hadoop.filesystem.url

URL of the Hadoop file system web application.

logwriter.output.path

Local file system path where the data capture application will record raw data.


27.2.3 Step 3. Preparing to Run the Silent Installer

Before running the silent installer, complete the following steps on all servers where you unzipped the silent installer:

  1. Make sure that JAVA_HOME and ANT_HOME in your environment are set to the correct paths.

  2. Start all the Analytics application servers (they must be running for the silent installer to work).

  3. 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
    
  4. 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
      

27.2.4 Step 4. Installing Analytics

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:

27.2.4.1 Single-Server Analytics Installation

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

  1. 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.

  2. 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.

  3. When the installer has successfully completed its task, initialize WebCenter Sites to Analytics. Go to Step 5. Configuring WebCenter Sites to Enable Analytics.

27.2.4.2 Dual-server Analytics Installation

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

  1. 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."

  2. 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
      
  3. When the installer has successfully completed its task, initialize WebCenter Sites to Analytics. Go to Step 5. Configuring WebCenter Sites to Enable Analytics.

27.2.4.3 Distributed Analytics Installation

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

  1. 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

    sensor

    Installs the data capture web application and HDFS Agent (Oracle-specific).

    Data Capture

    None

    hadoopjobs

    Installs the Oracle-specific Analytics/Hadoop job scheduler.

    Master Node

    Oracle

    database

    Updates the Oracle database with Analytics schema.

    The database Ant target loads Analytics-specific database definitions into SQL Plus. SQL Plus then updates the Oracle database with the definitions, and so initializes the database with the schema required by Analytics.

    Server on which SQL Plus is installed

    Oracle

    analytics

    Installs the Analytics reporting engine web application.

    Administration, Reporting

    Oracle

    analyticsadmin

    Installs the Analytics administration web application.

    Administration, Reporting

    Oracle

    cs_integration

    Modifies futuretense_xcel.ini (located on the WebCenter Sites system. WebCenter Sites does not have to be running in order for the installer to modify futuretense_xcel.ini).

    The silent installer locates futuretense_xcel.ini against the cs.local property (which you set during the installation process).

    WebCenter Sites Host

    None

    verify_install

    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


  2. 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."

  3. 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.

27.2.5 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.

  1. 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

    cs.local

    Specifies that WebCenter Sites is local (relative to the silent installer). Verify that this property is set to true.

    src.ini.file

    Specifies the location of the WebCenter Sites futuretense_xcel.ini property file.

    Sample values:

    • Windows:

    • C:/JSK_060809\RunTime\ContentServer/7.5.1/futuretense_xcel.ini 
      
    • Linux:

    • /home/fatwire/RunTime/contentServer/7.5.1/futuretense_xcel.ini 
      
      

    mod.ini.file

    Specifies the path to WebCenter Sites futuretense_xcel.ini file. (The path is identical to the path in the src.ini.file property.)

    Confirms to WebCenter Sites that Analytics is installed. This property modifies futuretense_xcel.ini (according to the settings you specify in analytics-build.properties), and writes the modified futuretense_xcel.ini file to the specified location. The original futuretense_xcel.ini file (specified by src.ini.file) is automatically backed up.

    Sample value: Use the value that is set in src.ini.file.


  2. Run the silent installer on the WebCenter Sites host:

    • UNIX:

      ./analytics_install.sh cs_integration
      
    • Windows:

      analytics_install.bat cs_integration
      
  3. When the silent installer completes its task, continue to Section 27.3, "Next Step."

27.3 Next Step