# Installation Guide

# Installation

This chapter describes the steps you take to install Analytics and its components:

1. Ensure you have completed pre-installation steps. For details, see Installation Prerequisites
2. Install Analytics on the remote server host computer. For details, see Installing Analytics.
3. Integrate Analytics with WebLogic Portal. For details, see Integrating Analytics with WebLogic Portal
4. Configure the Analytics database. For details, see Configuring the Analytics Database.
5. Configure Analytics. For details, see Configuring Analytics.
6. Register portal events with Analytics. For details, see Registering Portal Events with Analytics.
7. Start Analytics and portal services. For details, see Starting Analytics and Portal Services.

## Installing Analytics

This section describes how to install the core application. The instructions are the same for installing on a Windows or UNIX/Linux host, with slight exceptions as noted. To install Analytics:

1. Back up the machine running Analytics using the tool of your choice.
2. Log in to the remote server host computer as the local administrator (on Windows) or a user with directory write privileges (on UNIX or Linux).
3. Copy the installer to the disk location from which you plan to launch it. The installer file is one of the following:

- Windows: ALAnalytics_WLP_v2-1.exe
- UNIX/Linux: ALAnalytics_WLP_v2-1

4. Close all unnecessary applications.
5. Execute the installer file.
6. Complete the installation wizard pages as described in the following table and according to the settings you planned when you completed the Analytics Installation Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.

   Table 4-1 Installation Wizard Pages
   Wizard Page | Description
   --- | ---
   Introduction | Description of installer wizard.
   License Agreement | Read and accept the license agreement.
   Installation Directory | The default is: C:\bea\alui (Windows) /opt/bea/alui (UNIX and Linux)
   License Directory | Specify the path to the location where you want to store the evaluation version of the license.bea file. This location must be in BEA_HOME. The default location of BEA_HOME is: C:\bea (Windows) /opt/bea (UNIX/Linux)
   Existing License Update | (Only appears if you have an existing license) Choose to either merge the evaluation license with the existing license, replace the existing license with the evaluation license, or leave the existing license alone. If you already have an production license for Analytics, choose Leave Alone.
   Application Port | Select http or https protocol. The default port is 11944. This is the port that the portal uses to query Analytics for the Analytics reports UI.

7. On the final Wizard page, click Install to begin the installation.

Note: | After the installer has copied all files to the installation directory, click Done. The Analytics Configurator will launch; however, do not complete the configuration at this time. First, configure the Analytics Database, described in Configuring the Analytics Database. Note that the Analytics Configurator does not launch on Linux systems if a default browser is not specified.

Note: | The installer writes a log file to the directory where it is installed (for example: C:\bea\alui). If you encounter problems during installation, examine the error messages in the log file.

Caution: | We recommend that you sync the clocks on the servers that run Analytics and the portal before proceeding with configuration. If the clocks are not aligned, some events and sync jobs behave incorrectly.

## Integrating Analytics with WebLogic Portal

To integrate Analytics with your WebLogic Portal, you must add Analytics-specific facets to both your enterprise application and your web application. This section discusses:

- Adding the Analytics Facet to your EAR Application
- Adding the Analytics Facet to your Web Application
- Configuring the Analytics Integration
- Deploying Analytics in your Production Domain

For more information about adding facets to your WebLogic Portal applications, see WebLogic Portal Development Guide.

### Adding the Analytics Facet to your EAR Application

To add the Analytics facet to your EAR application:

1. In the Package Explorer view, right-click the EAR Project and choose Properties.
2. Select Project Facets in the tree that is displayed in the left pane of the dialog.
3. Click Add/Remove Project Facets.

The Add/Remove Project Facets - Select Project Facets dialog appears.

4. Expand and select the WebLogic Portal (Optional) check box.

All the optional facets for WebLogic Portal are selected by default; you can de-select facets you do not need, but leave the Analytics facet selected.

5. Click Finish.
6. Click OK.

The Package Explorer view includes the new facet content.

### Adding the Analytics Facet to your Web Application

To add the Analytics facet to your web application:

1. In the Package Explorer view, right-click your web project and choose Properties.
2. Select Project Facets in the tree that is displayed in the left pane of the dialog.

The project facets associated with your web project appear in the table.

3. Click Add/Remove Project Facets. The Add/Remove Project Facets - Select Project Facets dialog displays.
4. Expand and select the WebLogic Portal (Optional) check box.

All the optional facets for WebLogic Portal are selected by default, you can de-select facets you do not need, but leave the Analytics facet selected.

5. Click OK to add the selected facet.

### Configuring the Analytics Integration

To complete the Analytics integration within your development environment, edit the Analytics configuration file. To do this, you must know the following:

- The Analytics Administration URL
- The Analytics Reports URL
- The Open API Config fully-qualified domain name and port number

To edit the configuration file:

1. In the Merged Projects tab, navigate to the analytics-config.xml file: `//``yourEAR``/META-INF/templates/analytics-config.xml`.
2. Right-click the analytics-config.xml file and select Copy to Workspace... to view the Copy to Workspace dialog.
3. Click OK.

The analytics-config.xml file is copied to your Workspace. You can now make any modifications.

4. In the Projects tab, navigate to the copied analytics-config.xml file.
5. Right-click the file and select Open With > Text Editor.
6. Edit the analytics-config.xml file to match the configuration of the configuration of your Analytics environment.

See below for a sample analytics-config.xml file that includes explanatory comments.

7. Save the edited configuration file.

##### Sample analytics-config.xml File

    <?xml version="1.0"?>

    <analytics-config xmlns="http://www.bea.com/ns/portal/90/analytics-config">

    <! -- Ensure that the enabled attribute is defined as "true". --!>

    	<enabled>true</enabled>

    <! -- When configuring Analytics to work with WebLogic Portal, you must use fully-qualified domain names (server.domain.com) when referencing Analytics Administration, the WebLogic Portal Administration Console, and the Analytics Configuration Tool when editing the XML configuration file. You cannot use IP addresses. --!>

    <! -- Use the open-api-config element to define the fully-qualified domain name and port of the machine on which Analytics is installed. --!>

    	<open-api-config>

    		<host-name>work.bea.com</host-name>

    		<port>31314</port>

    	</open-api-config>

    <! -- In the reports-url element, replace work.bea.com with the fully-qualified domain name that you defined in the open-api-config element. --!>

    <reports-url>http://work.bea.com:11944/analytics/ui/console.jsf?EnterpriseAppName={url:enterpriseAppName}&amp;WebAppName={url:webAppName}</reports-url>

    <! -- In the admin-url element, replace work.bea.com with the fully-qualified domain name that you defined in the open-api-config element. --!>

    <admin-url>http://work.bea.com:11944/asmanager/ui/runtimemgr.jsf?EnterpriseAppName={url:enterpriseAppName}&amp;WebAppName={url:webAppName}</admin-url>

    <! -- Optionally, add references to WebLogic Portal property sets for collection of Analytics user profile information. User profile values for the referenced Property Set attributes will be collected on behalf of users when they log into a portal application and sent along for storage in the Analytics database. These profile values can then be used for report filtering in the Analytics Administration Console.

    For more information about property sets, see the
    WebLogic Portal User Management Guide. --!>

    <profile-property>GroupSpace:im_id</profile-property>

    <profile-property>GroupSpace:phone_number</profile-property>

    <profile-property>GroupSpace:first_name</profile-property>

    <profile-property>GroupSpace:timezone</profile-property>

    <profile-property>GroupSpace:email</profile-property>

    <profile-property>GroupSpace:last_name</profile-property>

    <profile-property>GroupSpace:title</profile-property>

    </analytics-config>

### Deploying Analytics In Your Production Domain

In this procedure, you will use the WebLogic Server Console to add the Analytics library to your production domain and ensure it is deployed on every server within your cluster. You will deploy two libraries: `wlp-analytics-web-lib.war` and `wlp-analytics-app-lib.ear`

To deploy Analytics to your WebLogic Portal production domain:

1. From the WebLogic Portal domain where you wish to deploy Analytics, run the WebLogic Server Console.
2. In the Domain Structure section, select Deployments. This displays a list of the deployed components.
3. In the Change Center section, click Lock & Edit.
4. In the Summary of Deployments section, click Install.
5. Navigate to the location of the `wlp-analytics-web-lib.war` file and select it (`WebLogic_Server_Hom` e`/portal/lib/modules/wlp-analytics-web-lib.war`).
6. Click Next.
7. Select Install this deployment as a library and click Next.
8. Make changes as required.
9. Click Finish.
10. Optionally, verify that the library is deployed to the server.

1. In the Deployments table, navigate to the library you just deployed.
2. Click the name of the library to new its configuration.
3. In the Targets tab, verify that the library is targeting the correct server(s).
4. Click Save.

11. In the Change Center section, click Activate Changes.
12. Repeat these steps for the `wlp-analytics-app-lib.ear` library.

## Configuring the Analytics Database

This section describes how to set up the Analytics database. It contains the following sections:

- Creating and Setting Up the Analytics Database on Microsoft SQL Server 2000
- Creating and Setting Up the Analytics Database on Microsoft SQL Server 2005
- Creating and Setting Up the Analytics Database on Oracle

### Creating and Setting Up the Analytics Database on Microsoft SQL Server 2000

To create and set up the Analytics database on Microsoft SQL Server 2000:

1. Copy the scripts from install_dir\ptanalytics\2.1\sql\mssql to the database host computer.
2. Create the Analytics database user:

1. Create the Analytics database user with the user name you provisioned when you completed the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.
2. Configure the Analytics database user to use SQL Server Authentication.
3. Set the Analytics database user password to the password you designated when you completed the Analytics Installation and Configuration Worksheets document.

3. Create the Analytics database with the following properties:

- Create a database with the name you provisioned when you completed the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.
- Configure the size of the database. The growth of the database is directly correlated to the number of events present in the system. Events include such things as page views, portlet views, user logins, and discussion posts. Estimate 100 MB of growth per 1 million events. For example, if your portal receives roughly 1 million events per day, you should anticipate growth of 36.5 GB per year.

4. Grant the Analytics database user the public and db_owner roles for the Analytics database.
5. On the Analytics database Properties | Permissions tab, grant the Analytics database user all permissions to the Analytics database.
6. Connect to the Analytics database as the Analytics database user.
7. Run the setup scripts for the database, located in the install_dir\ptanalytics\2.1\sql\mssql\ folder, in the following order (make sure that you are running the scripts on the Analytics database):

1. db_creation.sql
2. install_seeddata.sql

Next, configure the Analytics application, as described in Configuring Analytics.

### Creating and Setting Up the Analytics Database on Microsoft SQL Server 2005

To create and set up the Analytics database on Microsoft SQL Server 2005:

1. Copy the scripts from install_dir\ptanalytics\2.1\sql\mssql to the database host computer.
2. Create the Analytics database user:

1. Create the Analytics database user with the user name you provisioned when you completed the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.
2. Configure the Analytics database user to use SQL Server Authentication.
3. Set the Analytics database user password to the password you designated when you completed the Analytics Installation and Configuration Worksheets document.

3. Create the Analytics database with the following properties:

- Create a database with the name you provisioned when you completed the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.
- Configure the size of the database. The growth of the database is directly correlated to the number of events present in the system. Events include such things as page views, portlet views, user logins, and discussion posts. Estimate 100 MB of growth per 1 million events. For example, if your portal receives roughly 1 million events per day, you should anticipate growth of 36.5 GB per year.
- Change the default database for the Analytics database user to the Analytics database.

4. Grant the Analytics database user the db_owner role for the Analytics database.
5. Create the Analytics database schema. Specify the Analytics database user as the schema owner.
6. Grant the Analytics database user the sysadmin server role.
7. Connect to the Analytics database as the Analytics database user, using SQL Server Authentication.
8. Run the setup scripts for the database, located in the install_dir\ptanalytics\2.1\sql\mssql\ folder, in the following order (make sure that you are running the scripts on the Analytics database):

1. db_creation.sql
2. install_seeddata.sql

Next, configure the Analytics application, as described in Configuring Analytics

### Creating and Setting Up the Analytics Database on Oracle

To create and set up the Analytics database on Oracle:

1. Copy the oracle directory from install_dir\ptanalytics\2.1\sql to the Analytics database's host computer. This folder contains the scripts that you will use to set up and configure the Analytics Oracle Database.
2. Log on to the host computer for the Analytics database as owner of the Oracle system files.
3. Execute the following steps as the system user in your Oracle database.

1. Determine the name of the SID that you will be using for this installation. If you changed the SID from the default when you installed the portal, you need to update create_analytics_tablespaces.sql to reflect the SID that you used, substituting all occurrences of the default SID name with your SID name. The default SID name is BEAS.

If you are creating a new SID, configure AL32UTF8 as the database character set and AL16UTF16 as the national character set.

2. Run the script create_analytics_tablespaces.sql for your platform. This file is located in a platform specific subdirectory within the oracle directory that you copied in Step 1.
3. Run the script create_analytics_user.sql.

Note: | If you do not want the script to use the defaults when creating the Oracle database user and password, edit the script. The default user is analyticsdbuser; the default password is analyticsdbuser. The create_analytics_user.sql script is located in the oracle directory that you copied in Step 1.

4. Add the Oracle database user and password values into the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document (you will enter these values into the Analytics Configurator during the procedure described in "Configuring Analytics").

4. Execute the following steps as the analytics user that you just created.

1. Run the script create_analytics_schema.sql. This script creates all of the tables and indexes that are necessary to run Analytics. The create_analytics_schema.sql script is located in the oracle directory that you copied in Step 1.
2. Run the script install_analytics_seeddata.sql. This script adds all of the initial seed data that are necessary to run the Analytics product. The install_analytics_seeddata.sql script is located in the oracle directory that you copied in Step 1.

5. Run your database's analysis tool on the portal database to the efficiency of the database.

Next, configure the Analytics application, as described in Configuring Analytics

## Configuring Analytics

This section describes how to configure Analytics.

Note: | Different sets of component-specific configuration pages appear, depending on the components that you just installed.

To configure Analytics:

1. Return to the browser window that launched when you completed the installer. If you have closed the browser window, you can launch the Analytics Configurator on Windows by choosing Start | Programs | BEA | Analytics Configurator. On UNIX or Linux, open the following location in a web browser: http://localhost:11944/configurator/ui/start.jsf.

Caution: | On Windows 2003, IE Security settings might prevent the configurator from completing. If this is the case, configure IE to completely trust the Analytics host computer.

2. Click Continue to begin the sequence of configuration pages. Complete the following configuration pages using the values you decided on when you completed the Analytics Configurator Worksheet, which is included in the Analytics Installation and Configuration Worksheets document.

   Table 4-2 Analytics Configurator Pages
   Configuration Page | Settings | Comments
   --- | --- | ---
   Configure Analytics Database Information | Analytics DB |
   Analytics DB Server Name | Does not appear if you select Use JDBC URL
   Analytics DB Port | Does not appear if you select Use JDBC URL
   Analytics DB Name | Does not appear if you select Use JDBC URL
   Analytics DB JDBC URL | Appears if you select Use JDBC URL
   Analytics DB Username |
   Analytics DB Password |
   Use JDBC URL | We recommend that you only use a JDBC URL if the standard method of configuration does not work for your environment, for example if you use Oracle RAC or a SQL Server cluster.
   Configure WLP Server Information | WLP Server URL | Example: http://WebLogicPortal Hostname:port/WLPAnalyticsSync. WLPAnalyticsSync is defined in the weblogic-application.xml of the WLP application; the default is EARnameAnalyticsSync. Use the fully qualified domain hostname.

3. An installer screen appears that summarizes your configuration. Review this screen and make changes, if necessary.
4. On the final page, click Update.

Note: | If you encounter Analytics Configurator-related errors, follow the instructions in the error message or see Troubleshooting

## Registering Portal Events with Analytics

To register portal events, run the following from the command line on the portal host machine:

- PTANALYTICS_HOME\bin\AnalyticsLoadEvents.bat ..\settings\config\analytics-wlp-event-def.xml (Windows)
- PTANALYTICS_HOME/bin/AnalyticsLoadEvents.sh ../settings/config/analytics-wlp-event-def.xml (UNIX/Linux)

## Starting Analytics and Portal Services

This section provides information on starting Analytics and portal services. Perform the procedure that is appropriate to your operating system.

### Starting Analytics Services on Windows

After you have installed Analytics services and all Analytics components:

- Ensure the BEA AL Analytics service has been started. From the Windows Control Panel, click Administrative Tools | Services; if the Analytics service has not started, right-click it and choose Start.
- Ensure the BEA AL Analytics Collector service has been started. From the Windows Control Panel, click Administrative Tools | Services; if the Analytics Collector service has not started, right-click it and choose Start.

### Starting Analytics Services on UNIX and Linux

After you have installed Analytics services and all Analytics components:

- Ensure the BEA AL Analytics service has been started: install_dir/ptanalytics/2.1/bin/analyticsd.sh start
- Ensure the BEA AL Analytics Collector service has been started:
  install_dir/ptanalytics/2.1/bin/collectord.sh start