Skip Headers
Oracle® Fusion Middleware Administering Oracle WebCenter Portal
11g Release 1 (11.1.1.8.3)

Part Number E27738-04
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

10 Managing Activity Graph

This chapter describes how to configure and manage activity graph for WebCenter Portal and Portal Framework applications.

Note:

Always use the activity graph administration, Fusion Middleware Control, or WLST command-line tool to review and configure the activity graph. Oracle does not recommend that you edit files manually (unless specifically instructed to do so) as this can lead to misconfiguration.

This chapter includes the following topics:

Permissions:

To perform the tasks in this chapter, you must be granted the WebLogic Server Admin role through the Oracle WebLogic Server Administration Console and the Administrator role in the deployed application:

For more information about roles and permissions, see Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

10.1 About Activity Graph

Activity graph provides suggestions of people that a user may be interested in connecting with, based on existing connections and shared interaction with objects in the application. It also directs users to portals or content that may be of interest, based on similar interactions with those portals, items that the user is currently viewing, or the most active items.

The activity graph presents these suggestions based on data gathered and analyzed by the activity graph engines. The activity graph engines provide a central repository for actions that are collected by enterprise applications. Thinking in terms of a mathematical graph, application users and the enterprise content with which they interact are nodes, and the actions between users and between users and content are directed edges (Figure 10-1).

Figure 10-1 An Activity Graph

Description of Figure 10-1 follows
Description of "Figure 10-1 An Activity Graph"

There are three main components used by the activity graph:

Figure 10-2 shows how the different components work together. The process is described below.

Figure 10-2 Activity Graph Architecture

Description of Figure 10-2 follows
Description of "Figure 10-2 Activity Graph Architecture"

When an action occurs in WebCenter Portal, for example, Monty viewing his document, it is picked up by the Analytics Events Collector and placed in an event table in the Activities database.

When the activity data gathering process starts, the Analytics Activity Provider reads actions from the Analytics event tables and uses a registered set of mappings to generate activities. An activity is one occurrence of an action and is used to determine relations, aggregated occurrences of actions, which are stored in the relation tables. For example, the fact that Monty has viewed this particular document five times is a relation. Information in the relation tables is used to determine recommendations and search ranks.

The activity graph query API is a Java API, used by the activity graph task flows, that queries the relation tables for recommendations using a recipe. A recipe is a weighted list of rank or similarity calculations. A similarity calculation provides a similarity score (a number between zero and one) that designates how similar two objects are to each other given a specific criterion. The weighting of each calculation determines its significance in deciding the overall recommendation score. Recommendations are ordered by their total recommendation score. WebCenter Portal provides default calculations, used by the activity graph task flows. You can edit these calculations or create custom calculations. For more information, see the "Defining Custom Similarity Calculations" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

After the initial list of recommendations for a particular object is generated, the results can be filtered into something more appropriate and useful to present to users. This is achieved using Query Result Post-Processors (QRPPs). QRPPs take the current list of recommendation results return a modified list as output. A QRPP may filter out recommendations, for example by removing recommendations for objects that the current user is not permitted to see, or may add or modify result metadata.

Recommendations are then presented to users via the activity graph task flows. For more information, see the "Adding the Activity Graph at Design Time" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

10.2 Configuration Roadmaps for Activity Graph

Use the roadmaps in this section as an administrator's guide through the configuration process:

10.3 Activity Graph Prerequisites

The activity graph requires that the activity graph engines application has been installed and configured. For more information, see the Oracle Fusion Middleware Installation Guide for Oracle WebCenter Portal.

In addition, in your application you must create a connection to the WebCenter Portal schema and to the Activities database. For more information, see the "Setting Up a Database Connection" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

The application must be configured to send usage events to the Analytics Event Collector. For more information, see Section 11.5, "Registering an Analytics Collector for Your Application."

Before the activity graph can make recommendations, the activity graph engines must have been run at least once to gather the data and calculate similarity scores. For more information see Section 10.4, "Preparing Data for the Activity Graph."

Additionally, the items suggested in the Similar Items task flow, the Top Items task flow, and the Recommendation data control depend on the tools and services available in your application. For example, documents are only recommended if the Documents tool is enabled. An item can also be filtered out of the recommendations by the Resource Authorizer of the tool/service that owns the item.

In a cluster environment, all instances of the activity graph engines application should be disabled except for one. For more information, see the "Configuring Activity Graph for WebCenter Portal" section in Oracle Fusion Middleware High Availability Guide.

10.4 Preparing Data for the Activity Graph

The activity graph engines consist of three separate engines for gathering data, calculating similarity scores, and calculating search rankings. These engines are:

Before the activity graph can begin to recommend objects, these engines must be run at least once to gather the data and calculate similarity scores. After this initial run, the engines can be run on demand, or on a schedule to ensure that new activities are captured and analyzed.

This section includes the following topics:

10.4.1 Running the Activity Graph Engines on a Schedule

You can run the activity graph engines on a schedule to ensure that new activities are captured and analyzed on a regular basis. This is useful for applications with heavy traffic and frequently updated content.

To run the activity graph engines on a schedule:

  1. Log in to Fusion Middleware Control and navigate to the home page for the Activity Graph application (activitygraph-engines).

    Use the Navigator to access the page, select either:

    - Application Deployments > activitygraph-engines

    - WebLogic Domain > wc_domain > WC_Utilities > activitygraph-engines

  2. Under Web Modules, click the URL for the activity graph Schedule and Status Page and log in.

    Note:

    To access this page, you must be a member of the Administrators group.

    The activity graph Schedule and Status page does not support multibyte user names and passwords, so you must log in using an ASCII-only user name and password.

    Tip:

    You can access the activity graph Schedule and Status page directly by going to the following URL:

    http://host:port/activitygraph-engines
    

    where http://host:port is the URL for the WC_Utilities managed server.

  3. On the activity graph Schedule and Status page, select Run on a schedule.

  4. In the Start on field, enter the date on which you want the schedule to start.

  5. In the Run every field, enter a value to determine how regularly the process occurs. For example, to run the process every day, enter 1 in the field. To run the process every other day, enter 2 in the field, and so on.

  6. From the at dropdown list, select the time of day at which you want the process to start.

  7. Click Start.

    The process will run on the date specified at the time selected, and then will continue to run as you have scheduled.

10.4.2 Running the Activity Graph Engines on Demand

If the data in your application is not likely to change very frequently, you can run the activity graph engines on demand as and when required. You can also use this option to run the activity graph engines on demand in between regularly scheduled runs.

To run the activity graph engines on demand:

  1. Log in to Fusion Middleware Control and navigate to the home page for the Activity Graph application (activitygraph-engines).

    Use the Navigator to access the page, select either:

    - Application Deployments > activitygraph-engines

    - WebLogic Domain > wc_domain > WC_Utilities > activitygraph-engines

  2. Under Web Modules, click the URL for the activity graph Schedule and Status Page and log in.

    Note:

    To access this page, you must be a member of the Administrators group.

    The activity graph Schedule and Status page does not support multibyte user names and passwords, so you must log in using an ASCII-only user name and password.

    Tip:

    You can access the activity graph Schedule and Status page directly by going to the following URL:

    http://host:port/activitygraph-engines
    

    where http://host:port is the URL for the WC_Utilities managed server.

  3. Select Run once now.

  4. Select Incremental Update to update the tables with any activities that occurred since the last time the activity graph engines ran.

    Select Full Rebuild to delete all existing data and repopulate the tables with all activities. This may take some time.

  5. Click Start.

    You can monitor the progress of the process in the Status section of the dialog.

  6. Click Stop at any time to stop the process, if required.

  7. If you want to return to a regular schedule after the on demand process has run, be sure to select Run on a schedule, check that the details are correct, and then click Start to resume the schedule.

10.5 Customizing Reason Strings for Similarity Calculations

Similarity calculations can have associated reason strings to help users understand why a particular recommendation was made. When a person or object is recommended, if the highest scoring related similarity calculation has an associated reason string, that string is displayed in the task flow. You can edit the reason strings provided for similarity calculations, or create additional strings.

Each similarity calculation can define two strings for each reason to provide singular and plural phrasing.

Reason strings can be customized with the following tokens:

For example, the user-connect similarity calculation defines the following two reason strings:

reason-user-connect=You share {NUMBER_OF_ITEMS} connections with {RECOMMENDED_ITEM}.

reason-user-connect=You share {NUMBER_OF_ITEMS} connection with {RECOMMENDED_ITEM}.

To customize reason strings for similarity calculations:

  1. Open the UIBundle.properties file.

  2. Locate the reason string that you want to customize and edit it as required.

  3. To create a new reason string, use the following format:

    reason-similarity-calculation=string
    
  4. Save the UIBundle.properties file.

10.6 Managing Activity Graph Schema Customizations

WebCenter Portal provides out-of-the-box integration with the activity graph that includes metadata definitions for mapping WebCenter Portal event data from Analytics. This metadata is automatically loaded the first time the activity graph engines application starts.

You can extend activity graph metadata to change how actions are gathered from Analytics by manipulating XML files. To work with the metadata, you must first export the data to an XML file. After editing the XML files, you can then import the metadata back into the activity graph.

This section includes the following topics:

For information about the ways you can extend activity graph metadata, see the "Extending the Activity Graph" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

10.6.1 Exporting Activity Graph Metadata

Use the WLST command exportAGMetadata to export activity graph metadata definitions to an XML file. For command syntax and examples, see the "exportAGMetadata" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For example:

exportAGMetadata(appName='activitygraph-engines',
directoryPath='/scratch/monty', definitionFileName='activityGraphMetaData.xml',
includeProviderConfigurations=1)

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

10.6.2 Exporting Provider Configuration

Use the WLST command exportAGProviderConfiguration to export provider configuration metadata, for a given provider, to an activity graph metadata definition file. For command syntax and examples, see the "exportAGProviderConfiguration" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For example:

exportAGProviderConfiguration(appName='activitygraph-engines',
directoryPath='/scratch/monty',
definitionFileName='activityGraph-analytics-mappings.xml',
urn='oracle.webcenter.activitygraph.providers.analytics')

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

10.6.3 Importing Activity Graph Metadata

Use the WLST command importAGMetadata to import activity graph metadata definitions from an XML file. For command syntax and examples, see the "importAGMetadata" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."

10.6.4 Deleting Activity Graph Metadata

Use the WLST command deleteAllAGMetadata to delete all the activity graph metadata that is defined for a WebCenter Portal application. You should use this command in conjunction with the WLST command importAGMetadata to completely reinstall activity graph metadata. For command syntax and examples, see the "deleteAllAGMetadata" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

Only use this command if you plan to import a new set of metadata.

You can delete metadata for individual activity graph objects using the WLST command indicated:

  • Node class (deleteAGNodeClass)

  • Action (deleteAGAction)

  • Similarity calculation (deleteAGSimilarityCalculation)

  • Rank calculation (deleteAGRankCalculation)

  • Provider assignment (deleteAGProviderAssignment)

  • QRPP (deleteAGQRPPRegistration)

Note:

These delete methods delete metadata from the schema. As a result of this, any associated data in the Activities database is removed the next time the activity graph engines are run.

For more information, see the "Activity Graph" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

10.6.5 Renaming Actions and Node Classes

Use the WLST command renameAGNodeClass to change the URN of a node class currently registered with activity graph. For command syntax and examples, see the "renameAGNodeClass" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Use the WLST command renameAGAction to change the URN of an action currently registered with activity graph. For command syntax and examples, see the "renameAGAction" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

Note:

These commands do not delete any metadata associated with the affected node class or action

10.7 Setting Up Activity Rank for Oracle Secure Enterprise Search

Enterprise content contributed through WebCenter Portal and Fusion applications has a rich structure that lends itself to using the Markov Chain Analysis mathematical technique. This technique is used by the rank engine to produce an activity rank for each node that improves end user searches by producing more relevant result sets. This is achieved by introducing a measure of the importance of various objects into the Oracle Secure Enterprise Search (Oracle SES) search index. This importance can then be factored into how results are ordered in combination with more standard search criteria (term frequency, and so on). The determination of an object's importance is predicated on the history of users' interactions with that object.

With activity rank, the importance of a person depends on the number of items the person creates and edits; the importance of those items; the number of people who connect with the person; and the importance of those people. The importance of an item depends on the importance of its author; the number of people who view, tag, and edit the item; and the importance of those people.

The rank engine process can be divided into four phases:

Candidates for activity rank are limited to an intersection of WebCenter Portal objects having Oracle SES crawler implementations, WebCenter Portal analytics instrumentation, and registration for activity graph rank calculation.

For an object to receive an activity rank that will affect search behavior, it must be eligible to have its event data collected from Analytics, a rank computation generated by activity graph, and an indexed entry in search with the value of the attribute wc_serviceId matching one of the classes registered in activity graph. The currently supported objects are:

Note:

Ranks are still calculated and used even in the case where the class of object is not searchable itself.

The range of actions considered for computing activity rank are defined in the rankCalculation specified in the activityGraphMetaData.xml file. The out-of-the-box declaration includes the following user actions:

<component actionURN="connect" weight="10.0"/>
<component actionURN="edit" weight="20.0" inverse="true"/>
<component actionURN="view-count" weight="1.0"/>
<component actionURN="create" weight="100.0" inverse="true"/>
<component actionURN="create" weight="100.0"/>
<component actionURN="edit-count" weight="20.0"/>
<component actionURN="download" weight="5.0"/>
<component actionURN="tag" weight="10.0"/>
<component actionURN="comment" weight="10.0"/>

From this you can see that the single action of viewing a document conveys significantly less importance (weight="1.0") to that document than the act of creating (weight="100.0") or tagging (weight="10.0") the document.

Additionally, when the inverse attribute is set to true, a relationship from object-to-user is denoted. The effect of this relationship is to enable users to accrue authority from objects whose rank appreciates. For example, the author of a document (a create relationship) collects rank from that document as its rank appreciates from actions performed by other users on that document—tagging, viewing, downloading—which then amplifies the weight of the user's future actions.

When the activity graph rank engine completes its rank calculation for all of the affected objects, it sends a resulting set of identifiers with normalized ranks between 1 and 10 to a plug-in class, the SesRankResultAcceptor. This class simply pushes the ranks into the search index using the Oracle SES SOAP API. Once accepted by the SOAP API, the ranks, or docscores as they are known in Oracle SES, are immediately factored into the search ranking (providing the DocScore feature is fully enabled).

So, for two or more items within the same strata of a result set, those with higher docscores will receive higher search scores than they would otherwise, potentially raising them to a higher rank within that strata.

Before You Begin

Since activity rank works in conjunction with Oracle SES, you must make sure that Oracle SES is installed and configured correctly. Also, as activity rank only affects searchable items, the rank engine should be run after the SES crawler has finished a run. For more information, see Chapter 18, "Managing Oracle Secure Enterprise Search in WebCenter Portal."

To configure activity rank for Oracle SES:

  1. The rank engine expects to use docscore attributes with external names of DOC_SCORE_1 for ACTIVITY-RANK and DOC_SCORE_2 for LIKE-RANK. Therefore, you must perform a one-time mapping call to establish these fields by calling the stored procedure eq_sdata.create_sdata_attribute:

    exec eq_sdata.create_sdata_attribute('ACTIVITY-RANK');
    exec eq_sdata.create_sdata_attribute('LIKE-RANK');
    

    Note:

    These stored procedures must be invoked from the server hosting the Oracle SES instance.

  2. You must also add entries for these attributes to the Oracle SES ranking.xml file to determine the weight that they carry.

    For Oracle SES 11.1.2.2 only, add the following:

    <ranking>
      <docscore-factor>
        <attribute-name>ACTIVITY-RANK</attribute-name>
        <column-name>DOC_SCORE_1</column-name>
        <weight>1.0</weight>
      </docscore-factor>
      <docscore-factor>
        <attribute-name>LIKE-RANK</attribute-name>
        <column-name>DOC_SCORE_2</column-name>
        <weight>1.0</weight>
      </docscore-factor>
    </ranking>
    

    For all other versions of Oracle SES, add the following:

    <ranking>
      <docscore-factor>
        <attribute-name>ACTIVITY-RANK</attribute-name>
        <column-name>DOC_SCORE_1</column-name>
        <weight>1.0</weight>
      </docscore-factor>
      <docscore-factor>
        <attribute-name>LIKE-RANK</attribute-name>
        <column-name>DOC_SCORE_2</column-name>
        <weight>1.0</weight>
      </docscore-factor>
      <docscore-factor>
        <attribute-name>Doc_Score</attribute-name>
        <weight>1.0</weight>
      </docscore-factor>
    </ranking>
    

    Tip:

    The ranking.xml file is located in the following directory:

    $SES_HOME/search/webapp/config
    
  3. Restart the Oracle SES middle tier so that the changes take effect.

  4. Use the WLST command setAGProperty to set the following activity graph properties:

    oracle.webcenter.activitygraph.providers.datasources.ses.soap.admin.url
    oracle.webcenter.activitygraph.providers.datasources.ses.soap.query.url
    

    For example:

    setAGProperty(appName='activitygraph-engines',
    propertyName='oracle.webcenter.activitygraph.providers.datasources.ses.soap.admin.url',
    propertyValue='http://seshostname:7777/search/api/admin/AdminService',
    propertyType='String')
    
    setAGProperty(appName='activitygraph-engines',
    propertyName='oracle.webcenter.activitygraph.providers.datasources.ses.soap.query.url',
    propertyValue='http://seshostname:7777/search/query/OracleSearch',
    propertyType='String')
    

    Setting these properties enables the SESRankResultAcceptor to connect to the Oracle SES server and record ranks in the index.

  5. Use the WLST command setAGPasswordCredential to set the user names and passwords to use to access the URLs defined by the two properties.

    Note:

    The credentials should match a user that has access to all searchable items.

    For example:

    setAGPasswordCredential(appName='activitygraph-engines',
    propertyName='oracle.webcenter.activitygraph.providers.datasources.ses.soap.admin.credential',
    userName='eqsys',
    password='MyPassword1')
    
    setAGPasswordCredential(appName='activitygraph-engines',
    propertyName='oracle.webcenter.activitygraph.providers.datasources.ses.soap.query.credential',
    userName='orcladmin',
    password='MyPassword1')
    
  6. Restart the managed server on which the activity graph engines application is deployed (that is, the WC_Utilities managed server).

10.8 Troubleshooting Issues with Recommendations

This section provides information to assist you in troubleshooting problems you may encounter while using the activity graph.

Note:

The following troubleshooting solutions assume that the activity graph engines are deployed correctly, the WC_Utilities managed server is up and running, and the property openusage enabled is true.

You should also ensure that you have read Section 10.3, "Activity Graph Prerequisites."

10.8.1 Troubleshooting the Activity Graph Engines Schedule and Status Page

Problem

The activity graph Schedule and Status page throws an error while running the activity graph engines

Solution

Basic verification in this case is to verify the deployment status of the activity graph engines from the WebLogic Console.

Problem

When the activity graph engines are started from the Schedule and Status page, the status of the engines is not reflected in the UI.

Solution

Check the activity graph logs to verify whether the engines are actually running or not. If the logs show that the engines are running, then the issue is only with the UI and it will not have any effect on the recommendations being displayed in the task flows. If the logs do not show any entries for the gathering/CFE engines, then there might be a problem with the event mapping file.

Tip:

The activity graph engines logs can be found in:

domain/log/WC_Utilities.out
domain/servers/WC_Utilities/logs/WC_Utilities-diagnotics.log

Problem

Cannot log in to the activity graph Schedule and Status page.

Solution

The activity graph Schedule and Status page does not support multibyte user names or passwords. Log in as an administrator with an ASCII-only user name and password.