| Oracle® Fusion Middleware Administrator's Guide for Oracle WebCenter Portal 11g Release 1 (11.1.1.6.0) Part Number E12405-17 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Middleware Administrator's Guide for Oracle WebCenter Portal 11g Release 1 (11.1.1.6.0) Part Number E12405-17 |
|
|
PDF · Mobi · ePub |
This chapter describes how to configure and manage the Activity Graph service for Oracle WebCenter Portal applications.
Always use the Activity Graph Administration, Fusion Middleware Control or WLST command-line tool to review and configure the Activity Graph service. 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 sections:
Section 12.1, "What You Should Know About the Activity Graph Service"
Section 12.2, "Configuration Roadmaps for the Activity Graph Service"
Section 12.4, "Preparing Data for the Activity Graph Service"
Section 12.5, "Customizing Reason Strings for Similarity Calculations"
Section 12.6, "Managing Activity Graph Schema Customizations"
Section 12.7, "Setting Up Activity Rank for Oracle Secure Enterprise Search"
Audience
The content of this chapter is intended for Fusion Middleware administrators (users granted Admin or Operator role through the Oracle WebLogic Server Administration Console). See also, Section 1.8, "Understanding Administrative Operations, Roles, and Tools."
The Activity Graph service 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 spaces or content that may be of interest, based on similar interactions with those spaces or items that the user is currently viewing.
The Activity Graph service 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 12-1).
There are three main components used by the Activity Graph service:
The Oracle Analytics Event Collector collects event data using the OpenUsage API and saves that data in the Activities database.
The Activity Graph engines include engines for gathering data, calculating similarity scores, and calculating search rankings.
The Activity Graph Query API exposes raw action data and processed recommendation data, and mechanisms (QRPPs) through which to filter results from people who do not have access to see them and decorate results with up-to-date metadata.
Figure 12-2 shows how the different components work together. The process is described below.
Figure 12-2 Activity Graph Service 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 service task flows, that queries the relation tables for recommendations using a recipe. A recipe is a weighted list of 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 similarity calculations, used by the Activity Graph service task flows. You can edit these similarity calculations or create custom similarity calculations. For more information, see the section "Defining Custom Similarity Calculations" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.
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 service task flows. For more information, see the section "Activity Graph Service Task Flows" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.
Use the roadmaps in this section as an administrator's guide through the configuration process:
Roadmap - Configuring the Activity Graph Service for the Spaces application
The flow chart (Figure 12-3) and table (Table 12-1) in this section provide an overview of the prerequisites and tasks required to get the Activity Graph service working in the Spaces application.
Figure 12-3 Configuring the Activity Graph Service for the Spaces Application
Table 12-1 Configuring the Activity Graph Service for the Spaces Application
| Actor | Task | Sub-task | Notes |
|---|---|---|---|
|
Administrator |
1. Install WebCenter Portal and the back-end components for the Analytics and Activity Graph services |
||
|
2. Configure a connection between WebCenter Portal: Spaces and the Analytics Collector using one of the following tools: |
|||
|
End User/ Administrator |
4. Test that activity graph data is available in the Spaces application |
4.a Log in and interact with Spaces, for example, by adding content (End User) 4.b Run the Activity Graph Engines (Administrator) 4.c View recommendations in an Activity Graph task flow, for example, the Recommended Connections task flow on the Profile page (End User) |
Roadmap - Configuring the Activity Graph Service for Framework applications
The flow chart (Figure 12-4) and table (Table 12-2) in this section provide an overview of the prerequisites and tasks required to get the Activity Graph service working in Framework applications.
Figure 12-4 Configuring the Activity Graph Service for Framework Applications
Table 12-2 Configuring the Activity Graph Service for Framework applications
The Activity Graph service 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 section "Setting Up a Database Connection" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.
The application must be configured to send usage events to the Analytics Event Collector. For more information, see Section 13.5, "Registering an Analytics Collector for Your Application."
Before the Activity Graph service 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 12.4, "Preparing Data for the Activity Graph Service."
The items suggested in the Similar Items task flow depend on the services that are available in your application. For example, documents are only recommended if the Documents service is available. For information about making a service available in your application, refer to the appropriate chapter for that service. An item can also be filtered out of the recommendations by the Resource Authorizer of the 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 section "Configuring Activity Graph" in the Oracle Fusion Middleware High Availability Guide.
The Activity Graph engines consist of three separate engines for gathering data, calculating similarity scores, and calculating search rankings. These engines are:
The Gathering Engine—gathers activities from the Analytics tables and other repositories via a set of registered activity providers.
The Collaborative Filtering Engine (CFE)—calculates similarity scores on pairs of objects and stores them in the activity graph for later generation of similarity recommendations. It does this by performing a set of similarity calculations. Similarity calculations are objects that tell the Collaborative Filtering Engine how to calculate similarity scores on a given set of domain and background node classes. Each resulting similarity score is a number between 0 and 1 designating how similar two objects are to each other given a specific criterion. Similarity calculations are specified by the following properties: their domain and background classes, a distance function, and a relation combination.
The Rank Engine—calculates a measure of importance of every node in the activity graph. These activity ranks can be stored in a search index and combined at query time with a query-dependent score to order search results. For more information, see Section 12.7, "Setting Up Activity Rank for Oracle Secure Enterprise Search." These scores are also useful in ordering context-free recommendations. For this reason, they are also stored in the Relation Store.
Before the Activity Graph service 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 subsections:
Section 12.4.1, "Running the Activity Graph Engines on a Schedule"
Section 12.4.2, "Running the Activity Graph Engines on Demand"
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:
Log in to Fusion Middleware Control and navigate to the home page for the WebCenter Portal application.
Using the navigation pane, navigate to WebCenter>Portal>Activity Graph Engines>Activity Graph (WC_Utilities)>activitygraph-engines.
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.
On the Activity Graph Schedule and Status page, select Run on a schedule.
In the Start on field, enter the date on which you want the schedule to start.
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.
From the at dropdown list, select the time of day at which you want the process to start.
Click Start.
The process will run on the date specified at the time selected, and then will continue to run as you have scheduled.
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:
Log in to Fusion Middleware Control and navigate to the home page for the WebCenter Portal application.
Using the navigation pane, navigate to WebCenter>Portal>Activity Graph Engines>Activity Graph (WC_Utilities)>activitygraph-engines.
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.
Select Run once now.
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.
Click Start.
You can monitor the progress of the process in the Status section of the dialog.
Click Stop at any time to stop the process, if required.
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.
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:
{RECOMMENDED_ITEM}—The name of the current recommended item.
{NUMBER_OF_ITEMS}—The number of objects in common. This corresponds to the numerator of the component score.
{TOTAL_ITEMS}—The total number of items in common. This corresponds to the denominator of the component score. The meaning depends on the similarity function associated with the top similarity URN.
{SIMILARITY_CALCULATION}—The name of the top similarity calculation.
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:
Open the UIBundle.properties file.
Locate the reason string that you want to customize and edit it as required.
To create a new reason string, use the following format:
reason-similarity-calculation=string
Save the UIBundle.properties file.
WebCenter Portal provides out-of-the-box integration with the Activity Graph service that includes metadata definitions for mapping WebCenter Portal service 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 service.
This section includes the following subsections:
For information about the ways you can extend Activity Graph metadata, see the section "Extending the Activity Graph Service" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.
Use the WLST command exportAGMetadata to export Activity Graph metadata definitions to an XML file. For command syntax and examples, see the section "exportAGMetadata" in the 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."
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 section "exportAGProviderConfiguration" in the 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.analytics')
For information on how to run WLST commands, see Section 1.13.3.1, "Running Oracle WebLogic Scripting Tool (WLST) Commands."
Use the WLST command importAGMetadata to import Activity Graph metadata definitions from an XML file. For command syntax and examples, see the section "importAGMetadata" in the 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."
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 section "deleteAllAGMetadata" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Note:
You should use this command only if you plan to import a new set of metadata.
You can delete metadata for individual Activity Graph objects using the WLST command indicated:
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 section "Activity Graph" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
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 section "renameAGNodeClass" in the 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 section "renameAGAction" in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Note:
These commands do not delete any metadata associated with the affected node class or action
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:
Gathering—The Rank Engine queries the Analytics store for data about the connections between users and documents.
Reshaping—The data is transformed into a matrix.
Multiplying—The matrix is used to calculate Activity Ranks.
Result storage—The Activity Ranks are stored in the Oracle SES search server so that they can be used at search time.
Candidates for Activity Rank are limited to an intersection of WebCenter Portal: Spaces 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:
Users
Documents
Blog entries
Wiki pages
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 the chapter "Managing the Search Service" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.
To configure Activity Rank for Oracle SES:
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.
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, 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
Restart the Oracle SES middle tier so that the changes take effect.
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.
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='welcome1') setAGPasswordCredential(appName='activitygraph-engines', propertyName='oracle.webcenter.activitygraph.providers.datasources.ses.soap.query.credential', userName='orcladmin', password='welcome1')
Restart the managed server on which the Activity Graph engines application is deployed (that is, the WC_Utilities managed server).
This section provides information to assist you in troubleshooting problems you may encounter while using the Activity Graph service.
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 12.3, "Activity Graph Service Prerequisites."
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.
|
 Copyright © 2009, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|