Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Portal
11g Release 1 (11.1.1.6.0)

Part Number E10148-19
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
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

46 Integrating the Activity Graph Service

This chapter explains how to integrate the Activity Graph service in a WebCenter Portal: Framework application at design time.

This chapter includes the following sections:

For more information about managing and using the Activity Graph service, see:

46.1 Introduction to the Activity Graph Service

The advent of Enterprise 2.0 has enabled users to contribute content at unprecedented rates. In view of this, there is now a need for better information retrieval technologies that are seamlessly integrated with Enterprise 2.0 products, such as Framework applications. The Activity Graph service provides the solution by leveraging collective intelligence to benefit search and social applications.

This section provides an overview of the Activity Graph service, its task flows, its benefits, and the underlying architecture. It includes the following subsections:

46.1.1 Understanding the Activity Graph Service

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 within 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 engine. The Activity Graph engine provides 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 46-1).

Figure 46-1 An Activity Graph

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

In an enterprise, this analysis of the interaction of people with other people and with content produces similarity scores for making contextual recommendations based on an extensible set of actions, such as viewing, editing, tagging, and so on. For online vendors, for example, such contextual recommendations help provide a selection of suggested additional purchases. In a social networking environment, recommendations suggest additional connections to make based on the friends of the friends you have already connected with.

The Activity Graph engine also calculates an activity rank for content and passes this information to Oracle Secure Enterprise Search to enable more relevant content to appear higher in search results. For more information see the section "Setting Up Activity Rank for Oracle Secure Enterprise Search" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

Node Classes

Activity graph nodes are grouped into classes. The default node classes for WebCenter Portal are:

  • Users (WC.user)

  • Spaces (WC.group-space)

  • Documents (WC.document)

  • Wiki Pages (WC.wiki-page)

  • Blogs (WC.blog)

  • Discussion Topics (WC.topic)

If you want to extend the Activity Graph engine to integrate with other applications, then you can create custom node classes for the objects in those applications. For more information, see Section 46.4.1, "Defining Custom Node Classes."

Actions

An action is a specific type of event. It has a source and a target. For example, if a user, say Monty, looks at a document, that is a view action with Monty as the source and the document as the target. Other actions between users and items include create, like, and tag. Actions can also occur between two users, for example, when two users connect with each other.

Table 46-1 lists the default actions defined for WebCenter Portal.

Table 46-1 WebCenter Portal Default Actions

Action URN Description

connect

Connecting with another user.

create

Creating a space, document, wiki page, blog, topic, or message.

edit

For all items except spaces:

  • Checking in a new version of document

  • Editing a wiki page or blog

  • Replying to a topic

  • Editing a message

For spaces:

  • All of the above plus

  • Creating, editing, or deleting a page

  • Creating, editing, or deleting a list

  • Creating, editing, or deleting an event

comment

Commenting on a document, wiki, or blog

like

Liking a document, wiki, blog, or message

tag

Tagging a document, wiki, or blog

view

Viewing a space page, document, wiki page, blog entry, or discussion topic

download

Downloading a document, wiki, or blog

edit-count

Checking in a new version of a document, editing a wiki page or blog, replying to a topic, editing a message

view-count

Viewing a document, wiki page, blog, or discussion topic


When one of these WebCenter Portal actions occurs, for example, Monty viewing his document, it is picked up by the Events Collector, a component of WebCenter Portal's Analytics, and placed in an event table in the Activities database (Figure 46-2).

Figure 46-2 Data Collection by WebCenter Portal's Analytics

Description of Figure 46-2 follows
Description of "Figure 46-2 Data Collection by WebCenter Portal's Analytics"

When the activity data gathering process starts, Analytics Activity Provider reads actions from the Analytics event tables and uses a registered set of mappings to generate activities (Figure 46-3). 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.

Figure 46-3 Data Gathering by the Activity Graph Engine

Description of Figure 46-3 follows
Description of "Figure 46-3 Data Gathering by the Activity Graph Engine"

If you want to integrate the Activity Graph engine with other applications, then you can create custom actions for the actions that users perform in those applications. For more information, see Section 46.4.2, "Defining Custom Actions."

Similarity Calculations

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 (Figure 46-4). 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.

Figure 46-4 Recommendations Calculation by the Activity Graph Service

Description of Figure 46-4 follows
Description of "Figure 46-4 Recommendations Calculation by the Activity Graph Service"

Table 46-2 lists the similarity calculations used by the Activity Graph service task flows (for information about the task flows, see Section 46.2.3.1, "Activity Graph Service Task Flows").

Table 46-2 Activity Graph Service Similarity Calculations

URN Applies to Description Used by Task Flow

item-edit

Documents

Wiki pages

Blogs

Topics

Users who edited the current item also edited the recommended item

Similar Items

item-like

Documents

Wiki pages

Blogs

Topics

Users who liked the current item also liked the recommended item

Similar Items

item-comment

Documents

Wiki pages

Blogs

Topics

Users who commented on the current item also commented on the recommended item

Similar Items

item-tag

Documents

Wiki pages

Blogs

Topics

Users who tagged the current item also tagged the recommended item

 

item-all

Documents

Wiki pages

Blogs

Topics

Users who interacted in any way with the current item, including viewing it, also interacted in some way with the recommended item

Similar Items

gs-edit

Spaces

Users who participated in the current space also participated in the recommended space

Similar Spaces

gs-all

Spaces

Users who interacted in any way with the current space, including viewing pages or content in the space, also interacted in some way with the recommended space

Similar Spaces

user-connect

Users

The current user shares a number of connections with the recommended user

Recommended Connections

user-edit

Users

The current user edited some items that the recommended user also edited

Recommended Connections

user-like

Users

The current user likes some items that the recommended user also likes

Recommended Connections

user-comment

Users

The current user commented some items that the recommended user also commented on

Recommended Connections

user-tag

Users

The current user tagged some items that the recommended user also tagged

Recommended Connections

user-all

Users

The current user interacted in some way, including viewing, with some items that the recommended user also interacted with

Recommended Connections


You can edit these similarity calculations to change the weightings. If you want to integrate the Activity Graph engine with other applications, then you can create additional similarity calculations. For more information, see Section 46.4.3, "Defining Custom Similarity Calculations.".

Query Result Post-Processors (QRPPs)

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.

WebCenter Portal provides three QRPPs (run in the following order):

  • WebCenter Portal Security QRPP—Filters out recommendations for objects for which the current user does not have view permissions by calling the Resource Authorizer, which is the same WebCenter Portal component used by the Search service for view authorization.

  • Analytics Metadata QRPP—Retrieves additional metadata, for example, description and icon URL, for each recommended object from the Analytics tables.

  • WebCenter Portal URL QRPP—Retrieves a URL for each recommended object by calling the Resource Action Handler, which is the same WebCenter Portal component used by the Search service.

You can create your own QRPPs to further filter the results or to integrate the Activity Graph engine with other applications. For more information, see Section 46.4.6, "Registering Custom QRPPs."

Activity Graph Service Task Flows

Recommendations are presented to users via the Activity Graph service task flows. The Activity Graph service provides the following task flows:

  • Recommended ConnectionsRecommends users that the current user may want to connect with based on his or her current connections and shared interactions with objects in the application.

  • Similar SpacesSuggests spaces with which users have interacted in a similar way as the current space.

  • Similar ItemsSuggests items with which users have interacted in a similar way as the current item.

For more information, see Section 46.2.3.1, "Activity Graph Service Task Flows."

46.1.2 Requirements for the Activity Graph Service

The Activity Graph service requires that the Activity Graph engine 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 WebCenter Portal's schema and to the Activities database. For more information, see Section 7.2.2, "Setting Up a Database Connection."

The application must be configured to send usage events to the Analytics Event Collector. For more information, see the section "Registering an Analytics Collector for Your Application" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

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 the section "Preparing Data for the Activity Graph Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

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.

46.1.3 What Happens at Runtime

At runtime, the context is provided for the Activity Graph service task flow:

  • For the Recommended Connections task flow, the context is the current user.

  • For the Similar Spaces task flow, the context is the current space.

  • For the Similar Items task flow, the context is a WebCenter Portal resource, provided through task flow input parameters or through ADF UI events.

The task flow then queries the Activity Graph database for recommendations through the Activity Graph Query API, using the recipe provided in the task flow parameters. The list of recommendations returned from the Query API may be filtered by QRPPs before being listed in the task flow.

For more information about the service at runtime, see the section "Working with the Activity Graph Service" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

46.2 Basic Configuration for the Activity Graph Service

This section describes required steps for adding the Activity Graph service to your application. It includes the following subsections:

46.2.1 Configuration Roadmap for the Activity Graph Service

The flow chart (Figure 46-5) and table (Table 46-3) in this section provide an overview of the prerequisites and tasks required to get the Activity Graph service working in Framework applications.

Figure 46-5 Configuring the Activity Graph Service for WebCenter Portal: Framework Applications

Description of Figure 46-5 follows Install WebCenter Portal and the back-end components for the Analytics and Activity Graph services Configure a connection to the WebCenter Portal schema in JDeveloper Configure a connection to the Activities database in JDeveloper Configure a connection to the Analytics Collector in JDeveloper Add an Activity Graph task flow to a page in JDeveloper Set up the Activity Graph Engines schedule Use JDeveloper Use Fusion Middleware Control Use WLST Use WLS Admin Console Use JDeveloper, then deploy the application Use Fusion Middleware Control Use WLST Log in and interact with the application, adding content and so on Run the Activity Graph Engines View recommendations in the Activity Graph task flow Default
Description of "Figure 46-5 Configuring the Activity Graph Service for WebCenter Portal: Framework Applications"

Table 46-3 Configuring the Activity Graph Service for WebCenter Portal: Framework Applications

Actor Task Sub-task

Administrator

1. Install WebCenter Portal and the back-end components for the Analytics and Activity Graph services

 

Developer

2. Integrate the Activity Graph service in your application

2.a Configure a connection to WebCenter Portal's schema in JDeveloper

2.b Configure a connection to the Activities database in JDeveloper

2.c Configure a connection to the Analytics Collector in JDeveloper

2.d Add an Activity Graph task flow to a page in JDeveloper

Administrator

3. (Optional) Set up the Activity Graph Engines schedule

 

Developer/

Administrator

4. Deploy the application using one of the following tools:

 
 

5. (Optional) Add/modify connection parameters using one of the following tools:

 

End User/

Administrator

6. Test that activity graph data is available in the application

6.a Log in and interact with the application, for example, by adding content (End User)

6.b Run the Activity Graph Engines (Administrator)

6.c View recommendations in the Activity Graph task flow, for example, the Recommended Connections task flow on your Profile page (End User)


46.2.2 Setting Up Connections for the Activity Graph Service

The Activity Graph service requires a the following connections:

Note:

While you can set up the connections to back-end servers at design time in JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control. For more information, see the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.2.3 Adding the Activity Graph Service at Design Time

This section provides descriptions of the Activity Graph service task flows and steps you through the addition of the Activity Graph service to your application. It includes the following subsections:

46.2.3.1 Activity Graph Service Task Flows

This section describes and illustrates the task flows available through the Activity Graph service.

Table 46-4 lists the task flows provided by the Activity Graph service.

Table 46-4 Activity Graph Service Task Flows

Task Flow Description

Recommended Connections

This task flow enables viewing and connecting to users whom the Activity Graph engine has calculated to be similar to the current user.

For more information, see Section 46.2.3.1.1, "The Recommended Connections Task Flow."

Similar Spaces

This task flow enables viewing and interacting with spaces that the Activity Graph engine has calculated to be potentially of interest to the current user.

For more information, see Section 46.2.3.1.2, "The Similar Spaces Task Flow."

Similar Items

This task flow enables viewing and interacting with the WebCenter Portal items that the Activity Graph engine has calculated to be potentially of interest to the current user.

For more information, see Section 46.2.3.1.3, "The Similar Items Task Flow."


46.2.3.1.1 The Recommended Connections Task Flow

The Recommended Connections task flow enables viewing and connecting to users who have been calculated to be similar to the current user.

The Recommended Connections task flow is available by default on each user's Profile page.

For information about how to use this task flow at runtime, see the section "Working with the Recommended Connections Task Flow" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

Table 46-5 shows the similarity calculations and their weightings used in the default recipe for the Recommended Connections task flow. You can change this recipe by editing the similarityURNList task flow binding parameter. For more information, see Section 46.2.3.3, "How to Modify Activity Graph Service Task Flow Parameters."

Table 46-5 Default Recipe for Recommended Connections

Similarity Calculation Weight

user-connect

100

user-edit

50

user-like

50

user-comment

10

user-tag

10

user-all

1


The user with the highest overall recommendation score is displayed first in the task flow. For each recommended user, if the highest scoring related similarity calculation has an associated reason string, that string is displayed underneath the user's name and description to provide details for why the user was recommended.

If no reason string is defined for the top similarity function, nothing is displayed. You can edit the similarity calculation reason strings, or provide additional strings. For more information, see the section "Customizing Reason Strings for Similarity Calculations" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.2.3.1.2 The Similar Spaces Task Flow

The Similar Spaces task flow enables viewing and interacting with spaces that have been calculated to be potentially of interest to users of the current space. The suggested spaces are not specific to the current user, however the task flow lists only those spaces that the current user has permission to see.

For information about how to use this task flow at runtime, see the section "Working with the Similar Spaces Task Flow" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

Table 46-6 shows the similarity calculations and their weightings used in the default recipe for the Similar Spaces task flow. You can change this recipe by editing the similarityURNList task flow binding parameter. For more information, see Section 46.2.3.3, "How to Modify Activity Graph Service Task Flow Parameters."

Table 46-6 Default Recipe for Similar Spaces

Similarity Calculation Weight

gs-edit

10

gs-all

1


The space with the highest overall recommendation score is displayed first in the task flow. For each recommended space, if the highest scoring related similarity calculation has an associated reason string, that string is displayed underneath the space's name and description.

If no reason string is defined for the top similarity calculation, nothing is displayed. You can edit the similarity calculation reason strings, or provide additional strings. For more information, see the section "Customizing Reason Strings for Similarity Calculations" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.2.3.1.3 The Similar Items Task Flow

The Similar Items task flow enables viewing and interacting with the WebCenter Portal items that the Activity Graph engine has calculated to be potentially of interest to users of the currently selected item. The suggested items are not specific to the current user, however the task flow lists only those items that the current user has permission to see.

Items of interest may include a wiki page, a blog post, a document, or a discussion topic.

The Similar Items task flow determines the context for its recommendations based on items selected on other task flows on the page. This information is provided through task flow input parameters (typically using an EL expression) or through the WebCenterResourceSelected ADF UI event. The task flows that determine the context of the Similar Items task flow are:

  • Documents service task flows:

    • Recent Documents

    • Document List Viewer

    • Document Navigator

    • Document Explorer

    • Folder Viewer

    • Document Manager

    • Document Browser

  • Discussions Manager task flow

The Similar Items task flow is included in the Document Explorer Related Items pane for files to show items similar to the currently viewed file. For more information, see the section "Viewing and Adding Tags, Links, and Recommendations to a File" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

For information about how to use this task flow at runtime, see the section "Working with the Similar Items Task Flow" in the Oracle Fusion Middleware User's Guide for Oracle WebCenter Portal: Spaces.

Table 46-7 shows the similarity calculations and their weightings used in the default recipe for the Similar Items task flow. You can change this recipe by editing the similarityURNList task flow binding parameter. For more information, see Section 46.2.3.3, "How to Modify Activity Graph Service Task Flow Parameters."

Table 46-7 Default Recipe for Similar Items

Similarity Calculation Weight

item-edit

100

item-like

50

item-comment

20

item-tag

10

item-all

1


The item with the highest overall recommendation score is displayed first in the task flow. For each recommended item, if the highest scoring related similarity calculation has an associated reason string, that string is displayed underneath the item's name and description to provide details for why the item was recommended.

If no reason string is defined for the top similarity function, nothing is displayed. You can edit the similarity calculation reason strings, or provide additional strings. For more information, see the section "Customizing Reason Strings for Similarity Calculations" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.2.3.2 How to Add Activity Graph Service Task Flows to a Page

The section describes how to add the Recommended Connections task flow to an application page. The steps provided here are the same for all Activity Graph service task flows.

To add the Recommended Connections task flow to your Framework application:

  1. Prepare your application as described in Section 46.1.2, "Requirements for the Activity Graph Service."

  2. Open the page on which you want to add the task flow.

  3. In the Resource Palette, open My Catalogs, then WebCenter Portal - Services Catalog, then the Task Flows folder.

  4. Drag and drop the Recommended Connections task flow (or whichever Activity Graph service task flow you prefer) onto the JSF (.jspx) page.

  5. Select Region from the resulting context menu.

    You may be prompted to add the Activity Graph service ADF library (activitygraph-service-view.jar) to the project. Confirm by clicking Add Library. This operation may take a moment to complete.

  6. In the Edit Task Flow Binding dialog, enter values for the parameters, or accept the defaults.

    For more information, see Section 46.2.3.4, "Activity Graph Service Task Flows and Task Flow Parameters."

  7. Click OK.

    The task flow is added to the page, and the project's libraries are configured to run the task flow.

  8. Save and run your page.

46.2.3.3 How to Modify Activity Graph Service Task Flow Parameters

Each Activity Graph service task flow has a set of required and optional task flow binding parameters. These provide a means of capturing information that is useful to the task flow's successful function.

In addition to providing required values for successful task flow rendering, you can use task flow binding parameters to customize the appearance and behavior of a task flow instance. For example, you can use parameter values to determine whether headers and footers are rendered, the number of rows and columns of information to show, whether to apply a filter to returned data, and the like.

You can provide task flow binding parameter values when you drag and drop a task flow onto an application page. Doing so opens the Task Flow Bindings dialog (for more information, see Section 46.2.3.2, "How to Add Activity Graph Service Task Flows to a Page").

You can also adjust task flow binding parameter values after you have placed a task flow on a page.

To access the Edit Task Flow Binding dialog:

  1. Click the Bindings tab at the bottom of the page (next to the Source tab) to go to the Bindings view.

  2. Under Executables, you'll see the task flow you added.

    Figure 46-6 shows an example of a Recommended Connections task flow in the Executables section.

    Figure 46-6 Recommended Connections in the Page Data Binding Definition

    Description of Figure 46-6 follows
    Description of "Figure 46-6 Recommended Connections in the Page Data Binding Definition"

  3. Select the task flow, and next to the Executables heading, click the Edit selected element (pencil) icon.

  4. In the Edit Task Flow Binding dialog (Figure 46-7), revise the binding parameter values as required (for more information, see Section 46.2.3.4, "Activity Graph Service Task Flows and Task Flow Parameters").

    Figure 46-7 Edit Task Flow Binding Dialog for Recommended Connections

    Description of Figure 46-7 follows
    Description of "Figure 46-7 Edit Task Flow Binding Dialog for Recommended Connections "

  5. When you are finished, click OK.

  6. Save and run your page to see the results.

46.2.3.4 Activity Graph Service Task Flows and Task Flow Parameters

Table 46-8 lists and describes task flow binding parameters applicable to the Activity Graph service.

Table 46-8 Activity Graph Service Task Flow Binding Parameters

Parameter Task Flows Description

resourceId

Recommended Connections

Similar Spaces

Similar Items

The ID of the person, space, or item to use as a context for recommendations.

For connections, the default value is the expression language token for the currently logged in user.

For spaces, the default value is the expression language token for the resource ID of the space containing the task flow.

For items, the value is derived from the selection event.

classURN

Similar Items

The node class of the context. By default the information is derived from the selection event.

objectName

Similar Spaces

Similar Items

The name of the space or item to use as a context for recommendations.

For spaces, the default value is the expression language token for the resource ID of the space containing the task flow.

For items, the value is derived from the selection event.

recipe

Recommended Connections

Similar Spaces

Similar Items

A comma separated list of registered similarity calculation = weight pairs. The list determines what recommendations appear and how they are ordered.

The default recipes for each task flow are listed in Section 46.2.3.1, "Activity Graph Service Task Flows."

classURNRestrictions

Similar Items

A comma separated list of the node classes of objects to exclude from the recommendations.

By default this is empty, meaning that there are no restrictions on which classes of objects may be returned.

excludeObjectActions

Recommended Connections

Similar Spaces

Similar Items

A comma separated list of registered actions. The task flow will not show people, spaces, or items on which the logged in user took any of the listed actions.

For example, the default value for the Similar Items task flow is create, edit, comment, tag, meaning that users are not recommended items which they themselves created, edited, commented on, or tagged.

The WebCenter Portal default actions are listed in Table 46-1.

serviceId

Similar Items

Used in conjunction with resourceId, and optionally resourceType, as an alternative to classURN for identifying the node class of an object.

resourceType

Similar Items

Used in conjunction with resourceId and serviceId, as an alternative to classURN for identifying the node class of a WebCenter Portal object.

For example resourceType is used by the Documents service to identify whether an object is a wiki, blog, or document.

suppressPopup

Similar Items

Determines whether links in the task flow launch content in inline popups (false) or in browser windows (true).

The default value is false.


46.3 Advanced Information for the Activity Graph Service

This section describes advanced features available with the Activity Graph service. It includes the following subsections:

46.3.1 Using the Activity Graph Data Control

The Activity Graph service provides a data control that enables you to create your own user interface (task flows) for the service.

The Activity Graph data control exposes two methods to query Activity Graph for suggestions of similar items and similar users, and one method to record items the user is not interested in.

  • getSimilarObjects—Returns a list of SuggestionWrappers for a given source and similarity calculation, with choices for complex similarity calculation recipes and filtering of node classes and actions.

  • recordNotInterested—Records that the user is not interested in a given object.

Note:

For convenience, the getSimilarObjects method takes string arguments instead of the list and map arguments used at the lower levels of the APIs, since that is typically how you would configure them as task flow input parameters.

Typically, there are three things that you need to bind your data control to a method: a MethodAction, a MethodIterator to iterate through the results of the method, and a Tree to pick attributes of the resulting data structure. You can create these manually in a page definition file, or more easily, use the wizards that JDeveloper provides.

To add the Activity Graph data control to your project:

  1. Add the RecommendationDataControl to your project (either by selecting it in the catalog, right-clicking and choosing Add to Project or by dragging and dropping it onto a JSP page (.jspx) in your project).

  2. Drag an ADF Table to a JSP page.

  3. When prompted, check the bind to datasource checkbox.

  4. Navigate to the RecommendationDataControl and select the SuggestionWrapper result from the API method you desire. This will automatically create a method action binding and an iterator to the resultant collection.

  5. Select the nodes that you want to expose. This will automatically create a Tree to access values in the suggestion.

  6. Configure the parameters for the method action, typically these will be expressions that you would have defined as pageFlowScope variables.

    • classURN—The URN of the node class of the source for the recommendation.

    • objectURN—The URN of the source for the recommendation.

    • userCredentialClass—if null, the WebCenter Portal user type is used.

    • recipe—a comma separated list of similarity calculations to be used and their associated weights. For example:

      • For a Similar Items task flow:

        item-edit=100,item-like=50,item-comment=20,item-tag=10,item-all=1
        
      • For a Recommended Connections task flow:

        user-connect=100,user-edit=50,user-like=50,user-comment=10,user-tag=10,user-all=1
        
      • For a Similar Spaces task flow:

        gs-edit=10,gs-all=1
        
    • classURNRestrictionList—a comma separated list of classes to filter the results.

    • excludeObjectActionList—a comma separated list of action URNs to use to filter the results.

    • maxResults—the maximum number of recommendations to return

46.3.2 Using the Activity Graph Service REST APIs

WebCenter Portal provides REST APIs to support the Activity Graph service. Use the Activity Graph service REST APIs to create your own interface for providing recommendations for connections, spaces, and items.

This section describes the REST APIs associated with the Activity Graph service. It includes the following subsections:

For an introduction to the REST APIs, see Chapter 54, "Using Oracle WebCenter Portal REST APIs."

46.3.2.1 Activity Graph Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. For the Activity Graph service there are two entry points: one for recommendations and one for items. To find the entry points for the Activity Graph service, find the link element with one of the following resourceTypes:

urn:oracle:webcenter:activitygraph:recommendations
urn:oracle:webcenter:activitygraph:items

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with the Activity Graph service.

For more information about the Resource Index, see Section 54.5.1, "The Resource Index."

For more information about resource types, see Section 54.5.2.1, "Resource Type."

46.3.2.2 Activity Graph Resource Type Taxonomy

When the client has identified the entry point to use, it can then navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Section 46.3.2.2, "Activity Graph Resource Type Taxonomy."

The taxonomy for the Activity Graph service is:

urn:oracle:webcenter:activitygraph:recommendations
   urn:oracle:webcenter:activitygraph:recommendations:recommendation
urn:oracle:webcenter:activitygraph:items
   urn:oracle:webcenter:activitygraph:items:item

46.3.2.3 Security Considerations

There are no specific security considerations for this service. For general security considerations, see Section 54.8, "Security Considerations for WebCenter Portal REST APIs."

46.3.2.4 Activity Graph Resource Types

This section provides you with all the information you need to know about each resource type. It includes the following subsections:

46.3.2.4.1 urn:oracle:webcenter:activitygraph:recommendations

Use this resource to identify the URI to use to retrieve (GET) recommended connections, spaces, or items based on their similarity to the specified object. The response from a GET operation includes each object in the requested list, and each object includes links used to operate on that object.

Nodes in the activity graph are identified by a combination of node class URN and object URN.

For example, to identify the user, monty, you can specify:

  • classURN=WC.user

  • objectURN=monty

The nodes provided out of the box are all WebCenter Portal resources (users, documents, spaces, and so on) and so have WebCenter Portal service and resource IDs. The Activity Graph REST APIs provide another way for you to identify these out of the box nodes using the serviceId and objectURN (which contains the resource ID).

For example, to identify the user, monty, you can specify:

  • serviceId=oracle.webcenter.people

  • objectURN=monty

If a service's objects are further classified by resource type, for example, the Documents service, you must also specify the resource type.

For example, to identify a particular document, you can specify:

  • serviceId=oracle.webcenter.doclib

  • resourceType=document

  • objectURN=document1

Any new node classes that are created (that is, non-native WebCenter Portal objects) should be identified using node class and object URNs.

Navigation Paths to recommendations

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   recommendations

Supported Methods for recommendations

The following methods are supported by this resource:

  • GET

    • request - Parameters: startIndex, itemsPerPage, utoken

      For information about these common parameters, see "Common Request Query Parameters".

      The following additional parameters are available:

      • classURN—the node class URN that identifies the type of the object for which you are requesting recommendations. For example WC.user, WC.group-space.

      • objectURN—the object URN that provides a unique identifier for the object for which you are requesting recommendations. For example monty, 1000.

      • recipe—a semicolon-separated list of similarity URNs and optional associated weights (indicated by a colon) that is used to determine which objects to recommend. For example, gs-edit:10;gs-all:1

      • classURNRestrictions—a comma-separated list of types of objects, identified by node class URN, to exclude from the recommendations

      • excludeObjectActions—a comma-separated list of actions, identified by action URN, used to exclude objects from the recommendations if the current user has performed that action on the object. For example, if the client is retrieving recommended spaces, the gs-edit action could be specified to exclude spaces that the current user has edited (since the user already knows about those spaces).

      • serviceId—the WebCenter Portal service ID that identifies the type of object for which you are requesting recommendations (you can use this instead of classURN for out of the box objects).

      • resourceType—The WebCenter Portal resource type of the object for which you are requesting recommendations, used in combination with serviceId if necessary.

      • userCredentialClassURN—the node class URN of the user exercising the REST API. The default value is WC.user. If you are integrating the Activity Graph engine with another application, this may need to be a different node class.

    • response - body: 0 or more recommendations

For more information, see Section 54.5.2.5, "Templates."

Resource Types Linked to from recommendations

Table 46-9 lists the resource types that the client can link to from this resource.

Table 46-9 Related Resource Types for recommendations

rel resourceType

self

urn:oracle:webcenter:activitygraph:recommendations


46.3.2.4.2 urn:oracle:webcenter:activitygraph:recommendations:recommendation

The recommendation response contains the recommended objects and the URIs for use in accessing those objects.

Navigation Paths to recommendation

This section shows how the client can navigate through the hypermedia to access the recommendation resource:

resourceIndex
   recommendations
      recommendation

Read-only Elements for recommendation

Table 46-10 lists the read-only elements for the recommendations resource.

Table 46-10 Read-only Elements for recommendation

Element Type Description

score

Float

The overall score of this recommendation relative to the other recommendations in the list. This is the weighted sum of the component scores associated with each of the similarity URNs that comprise the recipe and is a floating point number between 0 and 1.

item

urn:oracle:webcenter:activitygraph:items:item

The recommended user, item, or space.

componentScores

A list of componentScore elements

A list of the component scores associated with the different similarity URNs in the recipe for the recommendation. A component score may have a reason and a link which can be used to retrieve the common items that the user and the recommended object have interacted with.


46.3.2.4.3 urn:oracle:webcenter:activitygraph:items

Use this resource to identify the URI to use to retrieve (GET) objects that the source object and recommended object have in common. You can use this to determine the reasons why a particular object was recommended. The response from a GET operation includes each item in this collection of items, and each item includes links used to operate on that item.

Navigation Paths to items

This section shows how the client can navigate through the hypermedia to access this resource:

resourceIndex
   items

Supported Methods for items

The following methods are supported by this resource:

  • GET

    • request - Parameters: startIndex, itemsPerPage, utoken

      For information about these common parameters, see "Common Request Query Parameters".

      The following additional parameters are available:

      • similarityURN—the URN of the similarity calculation to be used determine which objects are similar to the recommended object. For example item-tag, gs-edit, user-connect

      • srcClassURN—the node class URN that identifies the type of the object that was used to request the recommendations. For example WC.user, WC.group-space.

      • srcObjectURN—the URN of the object that was used to request the recommendations. For example monty, 1000.

      • trgClassURN—the node class URN that identifies the type of the recommended object

      • trgObjectURN—the object URN that provides a unique identifier for the recommended object

      • userCredentialClassURN—the node class URN of the user exercising the REST API. The default value is WC.user. If you are integrating the Activity Graph engine with another application, this may need to be a different node class.

    • response - body: 1 or more items

For more information, see Section 54.5.2.5, "Templates."

Resource Types Linked to from items

Table 46-11 lists the resource types that the client can link to from this resource.

Table 46-11 Related Resource Types for items

rel resourceType

self

urn:oracle:webcenter:activitygraph:items


46.3.2.4.4 urn:oracle:webcenter:activitygraph:items:item

Use this resource type to identify the URI to use to update (PUT) a recommendation to indicate user interest in the recommended object.

Navigation Paths to item

This section shows how the client can navigate through the hypermedia to access the item resource:

resourceIndex
   recommendations
      recommendation
         item
resourceIndex
   items
      item

Supported Methods for item

The following method is supported by this resource type:

  • PUT

    • Request—Body: item

    • Response—Body: item

Writable Elements for item

Table 46-12 lists the writable elements for this resource type.

Table 46-12 Writable Elements for item

Element Type Required Constraints Description

status

String

Yes

interested

not interested

Whether the user is interested in the object


Read-only Elements for item

Table 46-13 lists the read-only elements for this resource type. Not all of these elements are available for all objects.

Table 46-13 Read-only Elements for item

Element Type Description

classURN

String

Node class of the object

objectURN

String

Identifier for the object

name

String

Name of the object

description

String

Description of the object

modified

Date

Date on which the object was last updated

modifiedByUser

PersonReference

User information about the user who last updated the object, including GUID, ID, display name, and a link to the profile icon

author

PersonReference

User information about the user who created the object, including GUID, ID, display name, and a link to the profile icon


Resource Types Linked to from item

Table 46-14 lists the resource types that the client can link to from this resource.

Table 46-14 Related Resource Types for item

rel resourceType

self

urn:oracle:webcenter:activitygraph:items:item

via

resourceType of the underlying object


46.4 Extending the Activity Graph Service

Out of the box, Activity Graph includes metadata definitions for mapping WebCenter Portal service event data to WebCenter Portal's 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 WebCenter Portal's Analytics by manipulating XML files. The XML files can be exported, edited in a text editor, and then imported.

To update Activity Graph metadata definitions, you must first export them to a local XML file:

After exporting the metadata definitions to an appropriate file, you can then edit the file in an editor of your choice to add your own definitions. When you have made your changes, you must import the metadata file back to the managed server. For information about importing Activity Graph metadata definition files, see the section "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

This section includes the following subsections:

46.4.1 Defining Custom Node Classes

The Activity Graph metadata provide definitions for the node classes that represent WebCenter Portal objects, such as users, spaces, and documents. For more information and for a list of the default node classes supported by WebCenter Portal, see "Node Classes".

You can define your own node classes, for other WebCenter Portal objects or for objects from other applications, by exporting the Activity Graph metadata definitions to an XML file, editing the file, and then importing the metadata back into WebCenter Portal. For example, if you want to integrate your CRM application with Activity Graph, you could define a node class for service requests.

To define a custom node class:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to define the new node class. For each custom node class, you must specify:

    • URN—An attribute of the nodeClass element, this is a string that uniquely identifies the node class

    • nodeType—A sub-element that indicates whether objects defined by the node class are items or users. Valid values are Item or User.

    • numericURNs—A sub-element that indicates whether or not the URNs of the objects of this class are numeric. This enables you to integrate Activity Graph more efficiently with applications that use numeric IDs. Valid values are true or false.

    • properties—A list of name, value pairs. A node class's properties are available at runtime to provide additional metadata about the class. For example, all out-of-the-box WebCenter Portal objects modeled in Activity Graph define properties for serviceID and resourceType, which are used by the Activity Graph task flows to tailor the display of recommendations based on their service and resource type:

      <properties>
        <property name="oracle.webcenter.resourceType" value="wiki" />
        <property name="oracle.webcenter.serviceID" value="oracle.webcenter.doclib" />
      </properties>
      

    Example 46-1 Node Class Definition

    <nodeClasses>
      <nodeClass URN="WC.wiki-page">
        <nodeType>Item<nodeType>
        <properties>
          <property name="oracle.webcenter.resourceType" value="wiki" />
          <property name="oracle.webcenter.serviceID" value="oracle.webcenter.doclib" />
        </properties>
      </nodeClass>
    </nodeClasses>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.4.2 Defining Custom Actions

Activity Graph includes metadata definitions for the actions that occur in Framework applications. For more information, see "Actions".

You can define your own actions, for WebCenter Portal or for other applications, by exporting the Activity Graph metadata definitions to an XML file, editing the file, and then importing the metadata back into WebCenter Portal. For example, if you want to integrate your CRM application with Activity Graph, you could define new actions for opening a service request, assigning a service request to a customer service representative, and closing a service request.

To define a custom action:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to define the new action. For each custom action, you must specify:

    • URN—An attribute of the action element, this is a string that uniquely identifies the action

    • actionType—A sub-element. Valid values are:

      • Simple—These actions are useful for counting. They have no other metadata besides the source, the target, and the occurred time. For example, WebCenter Portal comes with a preregistered view-count simple action whose associated relation value increases each time the person clicks on the same item, but also decays over time.

      • Boolean—These actions are useful when you just want to know whether something has happened or not, but not how many times it has happened. Boolean actions have one additional Boolean as metadata. For example, WebCenter Portal comes with a Boolean view action whose associated relation value doesn't increase each time the person clicks on the same item. It just records whether a person has clicked on a specific item or not.

      • Non-negative Integer—Actions that have one additional integer as metadata, where the integer cannot be negative. Rating (assigning a number of stars) is the typical example.

      • Integer—Actions that have one additional integer as metadata. This can be used for ratings that allow negative values.

    • symmetric—A sub-element that indicates whether the source and target of the action are interchangeable. An example of a symmetric action is the connect action, which occurs when two users connect in the People Connections service. Valid values are true or false.

    • sourceType—A sub-element that identifies the type of object that performs the action. Valid values are User or Item.

    • targetType—A sub-element that identifies the type of object on which the action is performed. Valid values are User or Item.

    • relationType—A sub-element. Valid values are Sum or LastAssigned. Sum actions increment each time they occur, for example the edit-count action. LastAssigned actions keep whatever value was passed in the most recent occurrence of the action. Non-counting simple actions like create and edit are LastAssigned. An example of a LastAssigned Integer action would be a rating action.

    • relationDecayPeriod—(Optional) A sub-element that identifies the amount of time, in days, after which the action starts to lose (or decay) value. When computing the relation value, the value of each action is multiplied by the decay factor every decay period following the occurrence of the action.

    • relationDecayFactor—(Optional) A sub-element that is a floating value between 0 and 1 that determines how much the action's value decreases (or decays) after the decay period. When computing the relation value, the value of each action is multiplied by the decay factor every decay period following the occurrence of the action.

    Example 46-2 Action Definition

    <actions>
      ...
      <action URN="connect">
        <actionType>Boolean</actionType>
        <symmetric>true</symmetric>
        <sourceType>User</sourceType>
        <targetType>User</targetType>
        <relationType>LastAssigned</relationType>
        <relationIsNonNegative>true</relationIsNonNegative>
      </action>
      ...
      <action URN="edit-count">
        <actionType>Simple</actionType>
        <symmetric>false</symmetric>
        <sourceType>User</sourceType>
        <targetType>Item</targetType>
        <relationType>Sum</relationType>
        <relationDecayPeriod>1</relationDecayPeriod>
        <relationDecayFactor>0.97</relationDecayFactor>
      </action>
      ...
    </actions>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.4.3 Defining Custom Similarity Calculations

Activity Graph includes metadata definitions for the similarity calculations that are used by WebCenter Portal. For more information, see "Similarity Calculations".

You can define your own similarity calculations, for WebCenter Portal or for other applications, by exporting the Activity Graph metadata definitions to an XML file, editing the file, and then importing the metadata back into WebCenter Portal. For example, if you want to integrate your CRM application with Activity Graph, you could define an item-assign similarity calculations for to help recommend other service requests that were assigned to the same person.

To define a custom similarity calculation:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to define the new similarity calculation. For each similarity calculation, you must specify:

    • URN—An attribute of the similarityCalculation element that is a string that uniquely identifies the similarity calculation.

    • similarityFunction—A sub-element that identifies the function that measures the similarity of items. There is currently only one supported similarity function: Tanimoto. This function measures similarity between two items as the ratio of the number of common actions to the total number of actions on those items.

    • domainClasses—A sub-element that identifies the node classes for which similarity scores are calculated. These are the targets of the actions represented in the similarity calculation's relation combination.

    • backgroundClasses—A sub-element that identifies the node classes that are the sources of the actions in the similarity calculation's relation combination.

    • relationCombination—A sub-element that defines a new relation by combining one or more registered relations. There are two types of relation combination:

      • Boolean OR (used by all WebCenter Portal out-of-the-box similarity calculations) The resulting relation combination has a value of 1 (meaning true) if any of the component relations have a positive value, and 0 (meaning false) otherwise.

      • Weighted Sum (used by all WebCenter Portal out-of-the-box rank calculations) The resulting relation combination is a weighted sum of the values for each of its component relations.

      For each component relation, specify:

      • actionURN—the URN of the action for the component relation

      • use inverse—set to false (the default) to use the component relation to calculate similarity directly for the target objects, or true to use the component relation to calculate similarity for the source objects rather than the target objects. For example, if the view relation has the source object (user) viewing a target object (document), then to calculate similarity for documents, set use inverse=false. To calculate similarity for source objects (users), set use inverse=true.

      • weight—(for Weighted Sum relation combinations) the weight to apply to the component relation represented as a floating-point number

    Example 46-3 Similarity Calculation Definition

    <similarityCalculations>
      <similarityCalculation URN="item-edit">
        <similarityFunction>Tanamoto</similarityFunction>
        <domainClasses>
          <URN>document:wcServiceID=oracle.webcenter.doclib</URN>
          <URN>wiki-page:wcServiceID=oracle.webcenter.wiki</URN>
          <URN>blog:wcServiceID=oracle.webcenter.wiki</URN>
          <URN>topic:wcServiceID=oracle.webcenter.collab.forum</URN>
        </domainClasses>
        <backgroundClasses>
          <URN>user:wcServiceID=oracle.webcenter.people</URN>
        </backgroundClasses>
        <relationCombination type="BOOLEAN_OR">
          <component inverse="false" actionURN="create" />
          <component inverse="false" actionURN="comment" />
          <component inverse="false" actionURN="edit" />
        </relationCombination>
      </similarityCalculation>
    </similarityCalculations>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.4.4 Defining Custom Rank Calculations

Activity Graph includes metadata definitions for the rank calculations that are used by the Activity Graph Rank Engine to calculate the importance of nodes in the activity graph. For more information, see the section "Setting Up Activity Rank for Oracle Secure Enterprise Search" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

You can define your own rank calculations, for WebCenter Portal or for other applications, by exporting the Activity Graph metadata definitions to an XML file, editing the file, and then importing the metadata back into WebCenter Portal.

To define a custom rank calculation:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to define the new rank calculation. For each rank calculation, you must specify:

    • URN—An attribute of the rankCalculation element, this is a string that uniquely identifies the rank calculation.

    • domainClasses—A sub-element that identifies a list of node classes to which the rank calculation applies.

    • relationCombination—A sub-element that defines a new relation by combining one or more registered relations. There are two types of relation combination:

      • Boolean OR (used by all WebCenter Portal out-of-the-box similarity calculations) The resulting relation combination has a value of 1 (meaning true) if any of the component relations have a positive value, and 0 (meaning false) otherwise.

      • Weighted Sum (used by all WebCenter Portal out-of-the-box rank calculations) The resulting relation combination is a weighted sum of the values for each of its component relations.

      For each component relation, specify:

      • actionURN—the URN of the action for the component relation

      • use inverse—set to false (the default) to use the component relation to calculate similarity directly for the target objects, or true to use the component relation to calculate similarity for the source objects rather than the target objects. For example, if the view relation has the source object (user) viewing a target object (document), then to calculate similarity for documents, set use inverse=false. To calculate similarity for source objects (users), set use inverse=true.

      • weight—(for Weighted Sum relation combinations) the weight to apply to the component relation represented as a floating-point number

    • resultAcceptorClass—A sub-element that identifies the fully qualified class name for the class that implements the IRankResultAcceptor interface. This class receives a set of object rankings from the Rank Engine and stores them in a search engine where they can later be used to influence search query ranking. WebCenter Portal includes one rank acceptor out of the box, which will persist ranks to Oracle Secure Enterprise Search.

    Example 46-4 Rank Calculation Definition

    <rankCalculations>
      <rankCalculation URN="activity-rank">
        <domainClasses>
          <URN>WC.user</URN> 
          <URN>WC.document</URN> 
          <URN>WC.wiki-page</URN> 
          <URN>WC.blog</URN> 
        </domainClasses>
        <relationCombination type="WEIGHTED_SUM">
          <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" /> 
        </relationCombination>
        <resultAcceptorClass>
          oracle.webcenter.activitygraph.providers.rankAcceptors.ses.SesRankResultAcceptor
        </resultAcceptorClass> 
      </rankCalculation>
    </rankCalculations>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.4.5 Registering Custom Activity Providers

Activity providers are used by the Activity Graph engine during the gathering process to generate activities from recorded occurrences of actions. For example, the Analytics Activity Provider reads actions from the Analytics event tables and uses a registered set of mappings to generate activities. These activities are then used to determine relations, which are used in turn to determine recommendations and search ranks.

If you want to integrate other applications with the Activity Graph engine, you can create your own activity providers to generate activities from those applications.

To make a custom activity provider available to the Activity Graph engine, you must register it by adding an activity provider assignment to the Activity Graph metadata definitions. An activity provider assignment maps the triple of the action, srcClass, and trgClass to the Java class that implements the activity provider.

Note:

If more than one triple maps to the same provider class, there must be a provider assignment for each triple. For example, the out-of-the-box metadata declares a number of provider assignments mapping all triples to a single class, AnalyticsActivityProvider.

To register a custom activity provider:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to define the new activity provider assignment. For each activity provider assignment, you must specify:

    • action—An attribute of the providerAssignment element, this specifies which action is being mapped to the providerClass. Specify one registered action.

    • srcClass—An attribute of the providerAssignment element, this specifies which source class is being mapped to the providerClass. Specify one registered node class.

    • trgClass—An attribute of the providerAssignment element, this specifies which target class is being mapped to the providerClass. Specify one registered node class.

    • providerClass—A sub-element that identifies the fully qualified name of the Java class that implements the activity provider for the specified action, source class, and target class triple.

    Example 46-5 Activity Provider Assignment Definition

    <providerAssignments>
      <providerAssignment action="connect" srcClass="WC.user" trgClass="WC.user">
        <providerClass>
         oracle.webcenter.activitygraph.providers.activityProviders.analytics.AnalyticsActivityProvider
        </providerClass>
      </providerAssignment>
    </providerAssignments>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.4.6 Registering Custom QRPPs

WebCenter Portal provides several QRPPs to filter recommendation results. For more information, see "Query Result Post-Processors (QRPPs)".

You can create your own QRPPs to further filter recommendation results or to provide display metadata for recommendations when you are integrating the Activity Graph engine with other applications. To make a QRPP available to the Activity Graph engine, you must register it by adding a QRPP registration to the Activity Graph metadata definitions.

To register a custom QRPP:

  1. Use the WLST command exportAGMetadata to export the Activity Graph metadata to a local XML file. For more information, see the section "Exporting Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

  2. Edit the XML file to register the new QRPP. For each QRPP, you must specify:

    • URN—An attribute of the QRPP element, this is a string that uniquely identifies the QRPP.

    • priority—An attribute of the QRPP element, this is an integer indicating the order in which the QRPP should be run in relation to the other registered QRPPs.

    • description—A sub-element that provides a brief description of what the QRPP does.

    • providerClass—A sub-element that identifies the fully qualified name of the Java class that implements the QRPP.

    Example 46-6 QRPP Definition

    <QRPPs>
      <QRPP priority="1" URN="WebCenter Portal Security QRPP">
        <description>
          Uses the WebCenter Portal Resource Authorizer to perform security filtering.
        </description>
        <providerClass>
          oracle.webcenter.activitygraph.providers.qrpps.security.WCSecurityQueryResultPostProcessor
        </providerClass> 
      </QRPP>
    </QRPPs>
    
  3. Use the WLST command importAGMetadata to import the updated Activity Graph metadata file to the managed server where the Framework application is deployed. For more information, see "Importing Activity Graph Metadata" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

46.5 Troubleshooting the Activity Graph Service

This section provides information to assist you in troubleshooting problems you may encounter while using the Activity Graph service.

The following troubleshooting solutions assume that:

46.5.1 Troubleshooting the Activity Graph Service Task Flows (All Task Flows)

Problem

Recommendations are not shown in the task flows even after valid user activity.

Solution

Check whether the events are being captured by the Analytics Event Collector. You can verify this by checking the collector logs. If the logs do not show the events being captured, the problem is with the Analytics Event Collector.

For more information, see the section "Validating Analytic Event Collection" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

Problem

The Analytics Event Collector logs show that events are being captured but recommendations are not shown in the task flows.

Solution

Check the last run time of the Activity Graph engine on the Activity Graph Schedule and Status Page. You may need to adjust the schedule or launch an immediate run in order to gather and analyze recent events.

Problem

The Activity Graph engine has run successfully recently, but recommendations are not shown in the task flows.

Solution

Verify the relation tables in the Activities database (ActivitiesDS) for the presence of any data. If the Activity Graph engines are working correctly, these relation tables should have some data in them. If data is present in the tables and there are still no recommendations in the task flows, then the task flows might be broken.

46.5.2 Troubleshooting the Recommended Connections Task Flow

Problem

Some users are not shown as recommended connections in spite of valid user interactions.

Solution

This might happen if WebCenter Portal: Spaces and the services are not wired with the same OID. In this case, users who are not present in the OID to which the services are wired will not be suggested recommendation connections. The same users should be present in both the OIDs, or the WebCenter Portal: Spaces and services should be wired to the same OID.

46.5.3 Troubleshooting the Similar Spaces Task Flow

Problem

A space is not suggested in the Similar Spaces task flow even after a successful user interaction.

Solution

Check to see that the logged in user has permissions to access the space by finding the space in the Browse Spaces task flow.

46.5.4 Troubleshooting the Similar Items Task Flow

For recommended items to be displayed in the Similar Items task flow, the item for which the recommended items are to be displayed should be selected in another task flow on the page (for example, the Document Manager task flow).

Problem

An item is not suggested in the Similar Items task flow even after valid user interaction.

Solution

This could be because the current user does not have view privileges on the item. This is the correct behavior. Users should not see recommendations for items on which they do not have sufficient privileges. If the user should be able to see the item, grant the user sufficient privileges.

Problem

Specific types of items are not being displayed (for example, documents, wikis, and blogs are seen in the task flow, but not discussions).

Solution

Check the status of the specific service. If the service is unavailable items from that service will not be displayed in the Similar Items task flow.

Problem

Items are suggested only for some users; other users do not get any suggested items in the Similar Items task flow.

Solution

This might happen if WebCenter Portal: Spaces and the services are not wired with the same OID. In this case, users who not present in the OID to which the services are wired will not see suggested items from that service. The same users should be present in both the OIDs, or the WebCenter Portal: Spaces and services should be wired to the same OID.