10 Configuring Insights and Supporting Software

This section describes how to configure Oracle WebCenter Sites: Insights, including its supporting software — Kafka, HBase, and Endeca. Insights runtime consists of an Insights web application (WAR file) and a config directory shared across cluster members.

The following topics provide details about the supporting software and how to configure Insights:

Parent topic: Configuring WebCenter Sites Components

10.1 Software Components Required by Insights

Oracle WebCenter Sites: Insights relies on supporting software components, which you need to install and configure before Insights.

Before you deployInsights, install and configure the following software:

  • Apache Kafka 0.8.2.1 (with Zookeeper) — the messaging queue (data buffer) service for Insights

    Raw data collected by Insights is put into the Kafka message queue. Insights then pulls raw data from the queue; enriches it with visitor metadata like country, browser, and operating system; and writes it to the enriched data queue. Finally, Insights pulls the enriched data and writes it to HBase for permanent storage.

  • HBase 0.98.6-hadoop2 or CDH 5.2.0 (with Zookeeper) — the data store for enriched Insights data

  • Oracle Endeca Server 7.6

  • (Optional) Oracle Endeca Information Discovery 3.1(with Zookeeper) — the report generation tool.

    A data loader configured within Insights pulls specific ranges of data from HBase and loads them into Endeca to generate reports.

  • Zookeeper – a standalone instance that Insights can use for managing properties

Note:

Kafka, Endeca, and HBase are third-party products not distributed as part of Insights. You must obtain them from their respective vendors. Do not run any combination of Kafka, Endeca, and HBase on the same server because their zookeeper ports would conflict with one another. Run each service on a separate server instance (recommended) or change the zookeeper ports (not recommended).

10.2 Configuring Insights

You can configure Insights for your environment and test your configuration.

Before configuring Insights, you must satisfy the following prerequisites:

  • Install and configure Apache Kafka 0.8.2.1 and HBase 0.98.6-hadoop2.

  • Install and configure at least one fully functional instance of WebCenter Sites.

  • In the WebCenter Sites domain, configure the Insights Managed Servers, using the WebLogic Configuration Wizard and the “Oracle WebCenter Sites — Insights — 12.2.1.0.0” template, as Configuring the WebCenter Sites Domain describes.

    For Insights, the product home directory is ORACLE_HOME/wcsites/insights (WCS_INSIGHTS_HOME), and the configuration directory is DOMAIN_HOME/wcsites/insights/config (WCS_INSIGHTS_CONFIG).

  • If you have not already done so for the WebCenter Sites domain, grant read, write, and delete permissions for accessing the Oracle Platform Security Services credential store to ORACLE_HOME/wcsites/wcsites_common/lib/sites-security.jar by executing the following script:

    • On UNIX operating systems:

      DOMAIN_HOME/wcsites/bin/grant-opss-permission.sh

    • On Windows operating systems:

      DOMAIN_HOME\wcsites\bin\grant-opss-permission.bat

    Use the WebLogic Server Administrator user name and password, when prompted by the script.

  • Install and configure third-party supporting software for Insights, which Software Components Required by Insights describes.

To configure Insights:
  1. In the ORACLE_HOME/wcsites/insights/bin directory, update the following properties in the config.properties file with values appropriate for your environment.
    destination Full path to the Insights config directory. By default, this is DOMAIN_HOME/wcsites/insights/config.
    server.zookeeper.connect Host name and client port number of the standalone Zookeeper instance in the hostname:client-port format. If no standalone Zookeeper instance has been configured, set this to the same value as kafka.zookeeper.connect.
    kafka.zookeeper.connect Host name and client port number of Zookeeper for the target Kafka instance in the hostname:client-port format.
    metadata.broker.list Host name and metadata broker port number of the target Kafka instance in the kafka-hostname:broker-port format.
    hbase.zookeeper.quorum Host name of the target Zookeeper instance.
    hbase.zookeeper.property.clientPort Port number on which the target Zookeeper instance is listening for connections.
    vs.uri (Optional) URI of the target Visitor Services instance. Configure this property to enable the enrichment of impression data with visitor data from Visitor Services.
    cors.allowOrigin Host name(s) and port number(s) (in hostname:port format, comma-delimited) from which cross-domain resource requests will be accepted. Specifying a wildcard (*) as the value disables the CORS filter.
    zookeeper.overwrite (Optional) Specifies whether the existing Zookeeper node configuration will be overwritten on startup. Accepts true or false.

    (Optional) If you plan to load visitor impression data from HBase directly into Endeca without utilizing a data loader, also configure the following Endeca properties.

    endeca.hostname Host name of the target Endeca instance (not needed if already set as part of Endeca’s SSL configuration described earlier).
    endeca.port Port number on which the target Endeca instance is listening for connections.
    endeca.datadomain Name of the target Endeca data domain.
    endeca.context Context of the target Endeca server instance.
  2. Run the configuration utility: java -jar insights-configtool.jar config.properties.
  3. Start Insights:
    1. Make sure Hbase or CDH is up and running.
    2. Start Kafka server.
    3. the Insights Managed Server.
      After the Insights Managed Server is in a Running state, access the URLhttp://insights-server-host-name:insights-port/insights/, which should display a message, "Insights Web Service Application!".

    To check whether Insights is running, you can use logger name='oracle.wcsites.insights.consumer.hbase' set to logger level='TRACE:32' in insights-logging.xml, as the following example shows:

    <logger name='oracle.wcsites.insights.consumer.hbase' level='TRACE:32' useParentHandlers='false'>

    Then try to access http://insights-server-host-name:insights-port/insights/rest/tracker and check for the Insights log DOMAIN_HOME/servers/insights-server/logs/. You should see a log printing [oracle.wcsites.insights.consumer.hbase].

    Note:

    If the Insights Managed Server fails to start, increase the maximum number of processes available to the user (max user processes) in the operating system running on the physical machine hosting Insights, and try again.
  4. Test the configuration by accessing the following URL in a web browser: http://insights-host:port/insights/. The “Insights Web Service Application” message confirms that Insights is running.
  5. Configure WebCenter Sites to enable Insights integration:
    1. Log on to the WebCenter Sites Admin interface.
    2. Using the Property Management tool, set the following in config.properties:

      • insights.enable to true

      • insights.zookeeper.connect to the same value as server.zookeeper.connect

      • insights.datacaptureurl to http://insights-host:insights-port/insights

      • insights.asset.management.enabled to true

  6. If your WebCenter Sites page previews are not getting tracked, make sure you have AddAnlyticsImgtag in your templates used for previewing your pages; for example: <render:callelement elementname="insights/AddInsightsImgTag" args="c,cid,d,site,recid"/>.

Note:

Only users with the analytics role can access reports and other Insights-related configuration. Reports get data from Endeca, so if you can’t see your reports, make sure you have a loader configured for your site. A loader can be scheduled to load data from Hbase periodically or all at once. For more information, see Configuring the Data Loader in Administering Oracle WebCenter Sites.

For more information about configuring Insights, see Developing Insights in Developing with Oracle WebCenter Sites.

Note:

Because changes you make to a WAR file are not retained during redeployment, WAR file changes need to be copied over after each redeployment of the web applications. It is generally recommended to deploy the static artifacts such as images and stylesheet files onto the web server.
.