25 Managing Personalization

This chapter describes how to configure and manage personalization in Oracle WebCenter Portal.

This chapter includes the following sections:

Permissions:

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

  • WebCenter Portal: Administrator role granted through Portal Builder Administration.

  • Portal Framework application: Administrator role granted through the Administration Console.

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

25.1 About Personalization for Oracle WebCenter Portal

Personalization for Oracle WebCenter Portal provides a dynamically derived user experience for your portal application. Personalization evaluates defined sources of input data, generates a decision based on that evaluation, and applies this information to a declaratively defined personalization scenario. Personalization, for example, can return content or change application flow based on information about a user in a Human Resources database, targeting the application experience for that specific user.

Personalization is installed as an application in the wc_domain on the WC_Utilities server. Client applications access Personalization remotely over HTTP using RESTful services. Design-time JDeveloper tools are used to create Property Service and Conductor artifacts to be executed remotely using REST calls.Personalization is also available in the JDeveloper integrated domain for projects that include the Personalization technology libraries when you first create your application. For evaluation purposes and iterative development, this domain offers the quickest and easiest way to explore Personalization. For more information about the Personalization architecture and services, see the "Personalizing Oracle WebCenter Portal Applications" chapter in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

25.2 Personalization Prerequisites and Limitations

This section describes the system requirements and dependencies for Personalization in the following sections:

25.2.1 Personalization Installation Requirements

If you are using the CMIS (Content Management Interoperability Services) or Activity Graph data providers, or the People Connections locator within a Personalization Conductor scenario, then Oracle WebCenter Portal must be installed. For High Availability environments only, Coherence is also required.

25.2.2 Personalization REST API Configuration Requirements

Before you can use the Personalization REST APIs, you must perform two server-side configurations described in Section 24.2, "Performing Required Manual Configurations to Enable REST." For more information on security tokens, see also the "Security Considerations for WebCenter Portal REST APIs" section in the Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

25.2.3 Personalization Configuration Requirements

If you are using the CMIS provider, Activity Graph provider, PeopleConnections locator, or custom providers you must configure them as shown in Section 25.4, "Configuring Providers."

If you are using Content Presenter to present content in a portal or Portal Framework application, then you must also configure Content Presenter to display the results of your scenarios as described in Section 25.6, "Configuring Content Presenter."

Personalization relies on Trust Services to provide single sign-on (SSO) between different managed servers within the WebCenter Portal domain. Trust Services must be configured using the WLST scripts configureTrustWCPS.py and configureConnectionsWCPS.py provided in the user_projects/applications/wc_domain directory. For JDeveloper's integrated domain, only a single script (configureWCPS.py) located in the DefaultDomain/scrpts-wcps directory is used. For more information about configuring Trust Services and single sign-on using this script see Section 25.7, "Configuring Single Sign-On."

25.2.4 Personalization Security

Personalization is compatible with whatever source of user authentication services are configured within the WLS security realm. That is, it can use the default identity store and policy and credential store for the domain.

If you are using the People Connections locator or Activity Graph data providers, users must also be configured as WebCenter Portal users.

Personalization REST services are accessed though a pre-configured Personalization Web application that requires authenticated access for all resources (all URIs), with the exception of the resourceIndex. You can modify these constraints to provide either less security to execute scenarios (where anonymous access is needed), or more security to prevent the ability to create new scenarios. For information about modifying the default security settings, see Section 25.8, "Overriding the Default Security Settings."

In WebCenter Portal, Trust Services provides single sign-on for Personalization REST calls. This requires that the WLS TrustServicesIdentityAsserter is configured (it is not pre-configured). You can do this manually using the WLS Console or with the provided WLST scripts configureTrustWCPS.py and configureConnectionsWCPS.py located in the user_projects/applications/wc_domain directory. For JDeveloper's integrated domain, a single script (configureWCPS.py) located in the DefaultDomain/scrpts-wcps directory is used.

You can also optionally secure your WebCenter Portal application's connection to the Personalization server and Personalization providers with single sign-on. For more information about configuring single sign-on, see section Section 25.7, "Configuring Single Sign-On." Access to Property Service data can also be limited by an application using a filter (IPropertyPermission) to pre-authorize access to property data.

Scenarios can use an out-of-the-box function library supporting basic Role evaluation and testing to authorize access to scenarios.

25.2.5 Personalization Limitations

By default, Personalization uses a managed server-scoped cache, meaning any changes made to cached data outside the managed server will not be seen by additional installations of Personalization. For clustered (multiple) deployments of Personalization, Coherence may be configured for a cluster-aware cache.

25.2.6 Personalization Configuration Options

This section describes the out-of-the-box providers and other optional extensions to Personalization for WebCenter Portal, and the configuration required to integrate them into your Personalization project.

The out-of-the-box Personalization data providers allow you to write scenarios and access profile data based on existing WebCenter Portal tools. These WebCenter Portal tools expose their data via RESTful Web services. The Personalization data providers act as REST clients of these Web services and make it easy to author scenarios within JDeveloper based on these external data sources. You can also provide your own data provider and property locator implementations to integrate your own sources of external data.

CMIS Provider

The CMIS provider is an out-of-the-box provider that you can optionally use as a data source in your Personalization project. WebCenter Portal content services are exposed using the CMIS (Content Management Interoperability Services) standard. The CMIS REST service runs on the WC_Spaces server and provides access (based on separate configuration choices) to Oracle WebCenter Content Server.

If a Personalization user is also a portal user, access to user content stored through the portal is possible from a scenario. For more information about Content Server see Chapter 9, "Managing Content Repositories." For more information about configuring the CMIS provider, see Section 25.4.2, "Configuring the CMIS Provider."

Activity Graph Data Provider

The Activity Graph data provider is an out-of-the-box provider that you can optionally use as a data source in your Personalization project. Activity stream information from a portal or Portal Framework application is exposed through Activity Graph. The Activity Graph REST service runs on the WC_Spaces server and provides access to activity stream based recommendations as formed by the activity graph.

If a Personalization user is also a portal user, access to activity related recommendations (for portal content-types) is possible from a scenario. For more information about the Activity Graph service, see Chapter 10, "Managing Activity Graph." For more information about configuring the Activity Graph provider, see Section 25.4.3, "Configuring the Activity Graph Provider."

Oracle People Connections Locator

The People Connections locator is a locator that you can optionally use as a data source in your Personalization project. People Connections information is exposed through the People Web service. The People Connection REST service runs on the WC_Spaces server and provides access to social profile data as created in the context of a portal. If a Personalization user is also a portal user, access to People profile data is possible from a scenario. For more information about People Connections, see the "Integrating People Connections" chapter in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.Unlike the other out-of-the-box data providers, the People Connection Web service is accessed through the general purpose Property Service data provider using the IPropertyLocator extension interface. For more information about configuring the People Connections provider, see Section 25.4.4, "Configuring the Oracle People Connections Locator."

25.3 Configuring the WebCenter OPSS Trust Service

Personalization leverages a new feature from OPSS (Oracle Platform Security Services) for single-sign-on. Enabling this feature by following the configuration steps described here is required in all but the simplest Personalization use cases.

The OPSS Trust Service does not need to be configured when:

  • Directly interacting with the Conductor and Property service from a REST client

  • The Conductor and Property Service are being used by Personalization client libraries from a custom JEE Web application deployed in the same domain as Personalization, if JSessionId has been configured for both Web applications (note that there will be many exceptions logged making debugging difficult)

The OPSS Trust Service must be configured when:

  • Personalization is part of a production deployment

  • There are Personalization scenarios that require the out-of-the-box data providers (Activity Graph, CMIS, and People Connections Locator)

  • The Conductor and Property Service are being used by Personalization client libraries from a custom JEE Web application deployed in the same domain as Personalization

  • Cross-domain trust is required (i.e., an integrated domain connection configured to use the WC_domain CMIS provider)

This section contains the following subsections:

25.3.1 Configuring the Trust Service in the Oracle WebCenter Portal Domain

The default Oracle WebCenter Portal installation includes the Personalization domain extension template, which installs two WLST python scripts (configureTrustWCPS.py and configureConnectionsWCPS.py), in the domain home:

oracle/user_projects/applications/wc_domain/scripts

These scripts and associated configureWCPS.properties file contain usage instructions. Note that these are sample scripts, and that before running the scripts, you must edit the properties file and, at a minimum, specify the ocs.server name (typically the Content Server), the spaces.server.host name, and the fmwconfig.location. These values are unique to each Oracle WebCenter Portal installation and must be edited. Other values may also need to be changed according to the local environment (the machine port numbers, for example, may be different).

The configureConnectionsWCPS.py script sets up the default Personalization connection information for you (i.e., connection information for Activity Graph, CMIS, and People Connections). The script relies on the WCPS.py library, which is only installed on the Oracle WebCenter Portal domain (and not in the integrated WLS domain). You can, however, run configureConnectionsWCPS.py in the Oracle WebCenter Portal domain and point it (using a t3 URL) to an integrated WLS domain.

Caution:

the Trust Service configuration set up by configureTrustWCPS.py should not be applied remotely. The script should only be run from the WebCenter Portal domain (wc_domain).

You must use the WCP_ORACLE_HOME/common/bin/wlst.sh command file (for example, $WCP_ORACLE_HOME/common/bin/wlst.sh configureconnectionsWCPS.py) that sets up environment variables correctly for these scripts.

After running the scripts, restart all servers in the domain including the Admin server.

Testing the Configuration

To see Trust Service single sign-on in operation, you must be calling the Conductor or Property Service from a custom JEE Web application (using the Personalization client libraries), or be executing a scenario that uses a Personalization connection (such as the Activity Graph or CMIS data providers), or accessing a People Connections property using the People Connections locator.

When doing any of the above, you should see the following default log entry in WC_Utilities-diagnostic.log:

[2010-11-10T07:30:40.362-08:00] [WC_Utilities] [NOTIFICATION] [] [oracle.jps.trust] [tid: [ACTIVE].ExecuteThread: '3' for queue: 'weblogic.kernel.Default (self-tuning)']
[ecid: 0000IkqQG4NBh49LJeCCyf1CqfXw000008,0] [APP: wcps-services#11.1.1.4.0] Token issue operation

You should also see the following default log entry in the WC_Spaces-diagnostic.log (if accessing services there):

[2010-11-10T07:30:40.236-08:00] [WC_Spaces] [NOTIFICATION] [] [oracle.jps.trust] [tid: [ACTIVE].ExecuteThread: '1' for queue: 'weblogic.kernel.Default (self-tuning)']
[ecid: d461d36d4a552b90:-1fe62a5d:12c365bb19b:-8000-000000000000002c,0] [APP: webcenter#11.1.1.4.0] Token validate operation.

25.3.2 Configuring the Trust Service in the Integrated WLS Domain

A separate python script is shipped with the JDeveloper installer to configure the integrated WLS domain located in the following directory:

DefaultDomain\scrpts-wcps\

This script can be run manually or using JDeveloper's External Tools function.

Edit the properties file if you are using a non-default user or password. After creating and starting the integrated WLS domain, run the script from the scrpts-wcps directory:

Oracle\MiddlewareRC8\oracle_common\common\bin\wlst.cmd configureWCPS.py configureWCPS.properties

Note:

The configureTrustWCPS.py script is called when you select Configure WCPS Trust Service from the Tools menu. By default, this script refers to port 7101 on the Integrated WebLogic Server. If this default Integrated WebLogic Server port number was changed for some reason, you must update the configureWCPS.properties file with the correct port number. The script and properties file are located in the domain, here:

\system*\DefaultDomain\scrpt-wcps\configureWCPS.properties

\system*\DefaultDomain\scrpt-wcps\configureWCPS.py

You need to change this line in the configureWCPS.properties file:

admin.url=t3://localhost:7101

Restart the integrated WLS domain.

Testing the Configuration

Default logging levels are not enough to confirm token-issue and token-validate operations. Use the Configure Oracle Diagnostic Logging feature in JDeveloper and navigate to the oracle.jps.trust logger and set the level to Finest as shown below:

  1. From the View menu, select ApplicationServer Navigator.

  2. Expand Application Servers.

  3. Right-click IntegratedWeblogicServer and select Configure Oracle Diagnostic Logging.

  4. Set the logging level to Finest

Now run a scenario involving a custom JEE Web application calling the Conductor or Property Services.

25.3.3 Configuring Cross-Domain Trust

The Trust Service supports cross-domain trust, meaning if keystores have been created in different WLS domains, a client may allocate a token in domain 'A', issue an HTTP request with the token to domain 'B', and have the identity asserter validate and authenticate the user/request in domain 'B' through single sign-on. Note that a key assumption is that the user in domain 'A' exists in, and is the same user in domain 'B'.

By default, when running the configureWCPS.py script in the integrated WLS domain a certificate named extDomain.cer is generated. To enable cross-domain trust between the integrated WLS domain and Oracle WebCenter Portal domain:

Copy extDomain.cer to your Oracle WebCenter Portal domain (wc_domain) installation and import it there. Copy the extDomain.cer file to the scripts location:

oracle/user_projects/applications/wc_domain/scripts

Type in the following command to import the certificate:

keytool -importcert -alias orakey1 -file extDomain.cer -keystore ../../../../wlserver_10.3/wc_domain/config/fmwconfig/default-keystore.jks -storepass weblogic

Restart the servers in the Oracle WebCenter Portal domain.

Testing the Configuration

The simplest way to validate cross domain trust is to create a People Connections Personalization connection in the integrated WLS domain that points to the WebCenter Portal domain's WC_Spaces server. Then, create and deploy a simple scenario to the integrated WLS domain that fetches a People Connections property value. Finally, confirm that the 'Token Validate Operation' message described above is logged on the WC_Spaces server.

25.4 Configuring Providers

Personalization for WebCenter Portal provides out-of-the-box providers for Activity Graph and the Content Server, and a locator for People Connections. For scenarios using any of these providers, you must configure them using the configureWCPS.py WLST script as described in the following sections. If you are using custom providers or locators, then you must also configure them as described in the section on configuring custom providers. You do not need to configure providers or locators if they are not being used in your scenarios.

You can develop scenarios without the out-of-the-box providers, or exclusively with custom providers or downloaded from the Oracle Technology Network (OTN). Also, if you are developing exclusively within the JDeveloper integrated domain, you do not ordinarily have access to these WC_Spaces-based services (since WebCenter Portal does not run in the integrated domain). With advanced configurations (also supported by configureWCPS.py) you can access the WebCenter Portal services in the WC_Spaces domain from the integrated domain's Personalization server. This uses cross-domain trust and does require the provider connections to be configured.The configureTrustWCPS.py and configureConnectionsWCPS.py scripts (located in the WC_Spaces domain), or configureWCPS.py for JDeveloper's integrated WLS domain (located in the DefaultDomain/scrpts-wcps domain directory) are used to configure the corresponding domains by pointing to the appropriate WLS Administration server.

25.4.1 Creating or Modifying Provider Connection Settings

This section describes how to use WLST and Fusion Middleware Control to create or change the connection information (stored in wcps-connections.xml). It also describes how you can write a custom configuration class to configure a custom provider.

This section contains the following subsections:

25.4.1.1 Understanding Personalization Connection Information

Personalization connection information is maintained in wcps-connections.xml, which can be found in the domain directory at the following location:

<domain directory>/config/fmwconfig/wcps-connections.xml

Although editing this file directly is not recommended, there are several ways in which you can modify connection information:

25.4.1.2 Connection Configuration Attributes

Connection properties are maintained in wcps-connections.xml in the following form:

        <properties>
            <property>
                <name>{property name}</name>
                <value>{property val}</value>
            </property>

The following shows the connection properties and attributes that can be modified using WLST or Fusion Middleware Control. Note that each connection property is specific to the provider or locator that the connection is for. For example, the CMIS provider will have different connection properties than the Activity Graph provider.

  • <connection-name> - unique name for this connection. Connections can be retrieved by name.

  • <connection-type> - unique type for this connection. Connections can be retrieved by type. Note that connection-type only needs to be specified for custom connections. For the out-of-the-box data providers this field is set internally.

  • <namespace> - generally, this must match the namespace the accessing scenario is deployed within. The namespace is how the Conductor determines how to locate the appropriate <connection> for a given scenario. You can use a wildcard '*' to make this connection element available in all namespaces. If left unspecified in the WLST script, namespace will default to '*'.

  • <name>isDefault</name> - marks this connection as the default connection (if multiple are defined). Since it is a connection property it must have the form:

    <properties>
            <property>
                <name>isDefault</name>
                <value>true</value>
            </property>
</properties>

    Note that multiple connections can have the "isDefault" flag set to true. If this is the case, it is up to the individual provider to return the default connection.

25.4.1.3 Configuring Connections Using WLST

A set of Personalization WLST commands is provided to allow easy configuration of your provider connections. You can combine these commands into a script, an example of which is provided that can be customized or used directly. The sample script sets up provider connections and also initializes the Trust Services.

The Personalization WLST commands are installed at WCP_ORACLE_HOME/common/wlst/WCPS.py and are invoked using the WCP_ORACLE_HOME/common/bin/wlst.sh(cmd) script.

Each out-of-the-box data provider is supported with specific WLST commands (described in sections below). For custom data providers, use the generic WLST commands to configure a connection. For example:

createWCPSCustomConnection('customConnectionName', 'connectionType', properties={ 'name1': 'value1', 'name2': 'value2' })

For a complete list of Personalization WLST connection and other commands, see the "Personalization" section in the Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

25.4.1.4 Configuring Connections Using Fusion Middleware Control

You can use Fusion Middleware Control to view or edit the JMX MBeans (the connection configuration MBeans for Activity Graph, Content Server, and People Connections deployed with Personalization).

To view or edit connection configuration MBeans:

  1. Open Fusion Middleware Control Navigate to Personalization Services.

  2. Click WCPS-Services.

  3. From the Application Development drop-down menu, select System MBean Browser.

  4. In the MBean browser under 'Application Defined MBeans', select oracle.wcps.connections and continue to drill down to the connection information you wish to modify.

  5. On the Attributes tab, select Properties to view current values of connection attributes.

  6. On the Operations tab, select setProperty and click Invoke to modify the name/value pairs.

25.4.1.5 Writing a Custom Configuration Class

Custom configuration classes (classes annotated with @ConnectionConfiguration) are implemented by customers writing their own data providers. This allows custom data providers to use the Personalization connection framework to retrieve connection information configured using the Personalization WLST scripts.

Custom configuration classes for data providers are more fully described in the "Implementing Custom Data Providers: Introduction" chapter in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

25.4.2 Configuring the CMIS Provider

If you are working outside of the Integrated WLS domain (i.e., in the WC_Spaces domain), before you can use the CMIS provider in your scenario, you must first configure connection settings for it.

Connection settings for the CMIS provider are maintained in wcps-connections.xml in the wc_domain conductor extensions directory (domain scoped). Although it is not recommended that you edit this file directly, there are several other ways in which you can modify connection settings. Use one of the methods described in Section 25.4.1, "Creating or Modifying Provider Connection Settings." to configure the connection settings for the CMIS provider.

Connection Element and Property Descriptions

<connection-name> - unique name for this connection. Connections can be retrieved by name.

<connection-type>cmis.provider.connection</connection-type> - defines the connection type for the CMIS provider.

<namespace> - generally, this must match the namespace the accessing scenario is deployed within. The namespace is how the Conductor determines how to locate the appropriate <connection> for a given scenario. Using a wildcard '*', you can make this connection element available in all namespaces.

<name>isDefault</name> - marks this connection as the default connection (if multiple connections are defined)

<name>repositoryId</name> - this property must be changed to match the Content Repository in your environment.

<name>path</name> - this property must be changed to match the Content Repository in your environment. Defaults to /api/cmis/repository/repositoryId if not specified

<name>scheme</name> - protocol to access the CMIS REST service (HTTP or HTTPS for SSL). Defaults to HTTP if not explicitly specified.

<name>host</name> - machine name hosting the CMIS REST service. This is the machine name of the WC_Spaces managed server.

<name>port</name> - machine port number hosting the CMIS REST service. This is the machine port number of the WC_Spaces managed server.

<name>pathTrim</name> - Default is no trim if not explicitly specified

<name>rewriteUrls</name> - can be set to None, Consumer, or Producer. See the REST Proxy page for details. If you want the direct URLs (from the CMIS server for document links), set this to None. Default is no rewrite (None).

<name>username</name> - (Optional) the username to use when connecting to the CMIS REST service. Can be used to force a connection to a fixed username.

<name>password</name> - (Optional) the password to use when connecting to the CMIS REST service. Used in conjunction with username, can be used to force a connection to a fixed username/password. Not recommended for use outside of development environment since password access is not secured.

<name>timeoutInMillisecs</name> - Time in milliseconds before the CMIS query read response times out

<name>propagateTimeoutExceptions</name> - If true, propagate the timeout exceptions. Otherwise, log the exception and return null for the CMIS query response.

<name>restResourceURL</name> - the restResourceURL is the REST URL endpoint that defines the API resources for the CMIS REST service.

<property>
    <name>restResourceURL</name>
    <value><a target="_blank" href="http://my.webcenter.host:8888/rest/api/resourceIndex">http://my.webcenter.host:8888/rest/api/resourceIndex</a></value>
</property>

25.4.3 Configuring the Activity Graph Provider

If you are working outside of the Integrated WLS domain (i.e., in the WC_Spaces domain), before you can use scenarios that rely on the Activity Graph provider, you must configure connection information for your local environment.

Connection settings for Activity Graph are maintained in wcps-connections.xml in the wc_domain conductor extensions directory (domain scoped). Although it is not recommended that you edit this file directly, there are several other ways in which you can modify connection settings. Use one of the methods described in Section 25.4.1, "Creating or Modifying Provider Connection Settings" to configure the connection settings for the Activity Graph provider.

Connection Element and Property Descriptions

<connection-name> - unique name for this connection. Connections can be retrieved by name.

<connection-type>activity.provider.connection</connection-type> - defines the connection type for the Activity Graph provider.

<namespace> - generally, this must match the namespace the accessing scenario is deployed within. The namespace is how the Conductor determines how to locate the appropriate <connection> for a given scenario. Using a wildcard '*', you can make this connection element available in all namespaces.

<name>isDefault</name> - marks this connection as the default connection (if multiple connections are defined)

<name>scheme</name> - protocol to access the Activity Graph REST service (HTTP or HTTPS for SSL). Defaults to HTTP if not explicitly specified.

<name>host</name> - machine name hosting the Activity Graph REST service. This is the machine name of the WC_Spaces managed server.

<name>port</name> - machine port number hosting the Activity Graph REST service. This is the machine port number of the WC_Spaces managed server.

<name>rewriteUrls</name> - can be set to None, Consumer, or Producer. See the REST Proxy page for details. If you want the direct URLs (from the CMIS server for document links), set this to None. Default is no rewrite (None).

<name>user</name> - (Optional) the username to use when connecting to the Activity Graph REST service.

<name>password</name> - (Optional) the password to use when connecting to the Activity Graph REST service. Used in conjunction with username, can be used to force a connection to a fixed username/password. Not recommended for use outside of development environment since password access is not secured.

<name>restResourceIndex</name> - the URI suffix to append to the host/port for the REST resource index (for example: '/rest/api/resourceIndex')

<name>restResourceURL</name> - the restResourceURL is the REST URL endpoint that defines the API resources for the Activity Graph REST service.

<property>
   <name>restResourceURL</name>
   <value><a target="_blank" href="http://my.webcenter.host:8888/rest/api/resourceIndex">http://my.webcenter.host:8888/rest/api/resourceIndex</a></value>
</property>

25.4.4 Configuring the Oracle People Connections Locator

If you are working outside of the Integrated WLS domain (i.e., in the WC_Spaces domain), before you can use scenarios that rely on the People Connections locator, you must configure connection information for your local environment.

The Property Service uses an IPropertyLocator (the People Connections IPropertyLocator) to interface with the People Connections service. The Property Provider that interfaces with the People Connections service uses this IPropertyLocator to make People Connections REST calls for a given user (or self) and return the 'Person' object represented by that REST service call. The Person attributes represent values for that WebCenter Portal profile.

Connection settings for the People Connections IPropertyLocator are maintained in wcps-connections.xml in the wc_domain conductor extensions directory (domain scoped). Although it is not recommended that you edit this file directly, there are several other ways in which you can modify connection settings. Use one of the methods described in Section 25.4.1, "Creating or Modifying Provider Connection Settings." to configure the connection settings for the People Connections IPropertyLocator.

Connection Element and Property Descriptions

<connection-name> - unique name for this connection. Connections can be retrieved by name.

<namespace> - generally, this must match the namespace the accessing scenario is deployed within. The namespace is how the Conductor determines how to locate the appropriate <connection> for a given scenario. Use a wildcard '*' to make this connection element available in all namespaces.

<name>isDefault</name> - marks this connection as the default connection (if multiple are defined)

<name>scheme</name> - protocol to access the People Connections REST service (HTTP or HTTPS for SSL). Defaults to HTTP if not explicitly specified.

<name>host</name> - machine name hosting the People Connections REST service. This is the machine name of the WC_Spaces managed server.

<name>port</name> - machine port number hosting the People Connections REST service. This is the machine port number of the WC_Spaces managed server.

<name>user</name> - (Optional) the username to use when connecting to the People Connections REST service. Can be used to force a connection to a fixed username.

<name>password</name> - (Optional) the password to use when connecting to the People Connections REST service. Used in conjunction with username, can be used to force a connection to a fixed username/password. Not recommended for use outside of development environment since password access is not secured.

<name>restResourceIndex</name> - appended to the People Connections REST service host/port, pointing to the location of the resourceIndex (available REST services) page (for example: '/rest/api/resourceIndex')

Bootstrapping the Person class to the Properties Provider

In order for the Property Service to know about and use the results of the People Connections REST calls, it needs to know about a 'Person'. This means creating a 'Person' property set definition, along with its individual attributes set as property definitions, before a 'Person' can be instantiated and its properties set.

The People Connections IPropertyLocator code does this by bootstrapping that process in a servlet listener, configured in its web.xml file as shown in the example below:

<?xml version="1.0" encoding="UTF-8" ?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">
 
    <!-- Allows connection config classes to be loaded from the connections.xml file -->
     <listener>
      <listener-class>oracle.wcps.connection.lifecycle.VersatileModuleLifecycleCallback</listener-class>
    </listener>
 
     <listener>
      <listener-class>oracle.wcps.people.util.BootstrapPropertiesListener</listener-class>
    </listener>
 
</web-app>

Accessing the People Connections REST connection configuration information

Because the People Connections IPropertyLocator is not an actual 'provider', you cannot access its connection information in provider code, as for example Activity Graph. Instead, internal code uses the VersatileModuleLifecycleCallback class to make that configuration information available, and consequently makes this is a required listener to be configured in web.xml. Once that listener has been activated, the code can make calls to access connection information and parameterize the IPropertyLocator code to point to the People Connections REST server.

Tying the PC IPropertyLocator to the Properties Service Provider

The Properties Service Provider (PSP) knows about the People Connections IPropertyLocator through the namespaces. In the bootstrapping process above, the PropertySetDefinition (and its definitions) are namespaced with "people.connections.person" and a locator class "oracle.wcps.people.property.PeoplePropertyLocator". In using the PSP, the namespace and PropertySetDefinition are passed to the PSP. The PSP uses the locator class defined in the PropertySetDefinition to instantiate and delegate to property values (Person values from the People Connections REST service).

The locator and namespaces are critical in this process. They are defined as constants in the internal PropertyDefConstants class. Note that these do not need to be configured.

25.4.5 Configuring Custom Providers

Connection settings for Activity Graph are maintained in wcps-connections.xml in the wc_domain conductor extensions directory (domain scoped). Although it is not recommended that you edit this file directly, there are several other ways in which you can modify connection settings. Use one of the methods described in Section 25.4.1, "Creating or Modifying Provider Connection Settings." to configure the connection settings for your custom provider. Refer to Section 25.4.1.2, "Connection Configuration Attributes" for information about the configuration file elements and property descriptions.

25.5 Configuring Coherence

If your installation is using Coherence for caching (a requirement for "high-availability" environments), four separate caches must be set up: one each for Namespaces, Property Definitions, Property Set Definitions, and Property Sets.

The sample wcps-cache-config.xml configuration file below shows how to configure simple Coherence local caches. For more advanced cache types, refer to the Coherence documentation. Note that Coherence classes must be accessible via the same class loader as Personalization. The Coherence wcps-cache-config.xml file must also be accessible by that same class loader. For more information, see the oracle.wcps.cache.CacheFactory class in the JavaDoc for WebCenter Portal in Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal. See also the "Configuring Coherence as the Caching Mechanism" section in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

<?xml version="1.0" encoding="UTF-8" ?>
<cache-config>
    <caching-scheme-mapping>
        <cache-mapping>
            <cache-name>com.oracle.p13n.service.property.namespaces</cache-name>
            <scheme-name>ns-local-side</scheme-name>
        </cache-mapping>
        <cache-mapping>
            <cache-name>com.oracle.p13n.service.property.propertydefinitions_*</cache-name>
            <scheme-name>pd-local-side</scheme-name>
        </cache-mapping>
        <cache-mapping>
            <cache-name>com.oracle.p13n.service.property.propertysetdefinitions_*</cache-name>
            <scheme-name>psd-local-side</scheme-name>
        </cache-mapping>
        <cache-mapping>
            <cache-name>com.oracle.p13n.service.property.propertysets_*</cache-name>
            <scheme-name>ps-local-side</scheme-name>
        </cache-mapping>
        <cache-mapping>
            <cache-name>*</cache-name>
            <scheme-name>properties-default-local</scheme-name>
        </cache-mapping>
    </caching-scheme-mapping>
 
    <caching-schemes>
                <!--    
                        The following schemes are all local.  For a clustered deployment,
                        a distributed, replcated, or other clustered scheme is recommended.
                        See Coherence documentation for more information.
                -->
 
        <local-scheme>
            <scheme-name>ns-local-side</scheme-name>
            <service-name>NamespaceCache</service-name>
 
            <eviction-policy>HYBRID</eviction-policy>
            <high-units>{back-size-limit 0}</high-units>
            <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>{back-expiry 1h}</expiry-delay>
            <flush-delay>1m</flush-delay>
 
            <cachestore-scheme/>
        </local-scheme>
 
        <local-scheme>
            <scheme-name>pd-local-side</scheme-name>
            <service-name>PropertyDefinitionCache</service-name>
 
            <eviction-policy>HYBRID</eviction-policy>
            <high-units>{back-size-limit 0}</high-units>
            <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>{back-expiry 1h}</expiry-delay>
            <flush-delay>1m</flush-delay>
 
            <cachestore-scheme/>
        </local-scheme>
 
        <local-scheme>
            <scheme-name>psd-local-side</scheme-name>
            <service-name>PropertySetDefinitionCache</service-name>
 
            <eviction-policy>HYBRID</eviction-policy>
            <high-units>{back-size-limit 0}</high-units>
            <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>{back-expiry 1h}</expiry-delay>
            <flush-delay>1m</flush-delay>
 
            <cachestore-scheme/>
        </local-scheme>
 
        <local-scheme>
            <scheme-name>ps-local-side</scheme-name>
            <service-name>PropertySetCache</service-name>
 
            <eviction-policy>HYBRID</eviction-policy>
            <high-units>{back-size-limit 0}</high-units>
            <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>{back-expiry 1h}</expiry-delay>
            <flush-delay>1m</flush-delay>
 
            <cachestore-scheme/>
        </local-scheme>
 
                <local-scheme>
            <scheme-name>properties-default-local</scheme-name>
            <service-name>DefaultCache</service-name>
 
            <eviction-policy>HYBRID</eviction-policy>
            <high-units>{back-size-limit 0}</high-units>
            <unit-calculator>FIXED</unit-calculator>
            <expiry-delay>{back-expiry 1h}</expiry-delay>
            <flush-delay>1m</flush-delay>
 
            <cachestore-scheme/>
        </local-scheme>
 
    </caching-schemes>
    
</cache-config>

25.6 Configuring Content Presenter

Before you can run Personalization scenarios using Content Presenter, you need to configure the connections file (connections.xml) so that Content Presenter can see your Conductor server and the tagged scenarios. For more information about Content Presenter, see the "Publishing Content Using Content Presenter" chapter in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.

The connections.xml file holds the connection information for the application that you're working with on the WebCenter Portal side. Content Presenter gets a list of all URL connections that are registered within this file and for any that begin with "Conductor", Content Presenter will assume this is a URL pointing to a Conductor server. For more information about connections.xml, see Appendix A, "WebCenter Portal Files" in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.

Because Content Presenter runs on the WC_Spaces server while Personalization scenarios are executed on the WC_Utilities server, you also need to configure the cross-domain trust service. For more information, see Section 25.3, "Configuring the WebCenter OPSS Trust Service."

You can configure the Content Presenter task flow either at runtime, or from JDeveloper when adding the Content Presenter task flow to a page. These two configuration options for Content Presenter, as well as configuration requirements on the Conductor side are described in the following subsections:

25.6.1 Configuring the WebCenter Portal Application's Content Server Connection

For a Portal Framework application, use JDeveloper to set up the URL connection, or set the Content Presenter task flow parameters as described in Section 25.6.2, "Configuring the Content Presenter Task Flow Parameters." For WebCenter Portal, you can use either WLST commands or Fusion Middleware Control to configure the connection.

This section contains the following subsections:

25.6.1.1 Configuring Connections for WebCenter Portal Using WLST

For WebCenter Portal, you can use the adf_createHttpUrlConnection WLST command to manage URL connections as shown in the following example:

adf_createHttpUrlConnection('webcenter','Conductor','http://example.com:8891/wcps/api/conductor?namespace=CP_namespace&

For more information about the adf_createHttpUrlConnection command, see the "adf_createHttpUrlConnection" section in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.

25.6.1.2 Configuring Connections for WebCenter Portal Using Fusion Middleware Control

For WebCenter Portal, you can use Fusion Middleware Control to configure connections.

To configure connections using Fusion Middleware Control:

  1. Log in to Fusion Middleware Control and navigate to the home page for the WebCenter Portal application.

    See: Section 6.2, "Navigating to the Home Page for WebCenter Portal"

  2. From the WebCenter Portal menu, select ADF -> Configure ADF Connections.

    The ADF Connections Configuration page displays (see Figure 25-1).

    Figure 25-1 ADF Connections Configuration Page

    Description of Figure 25-1 follows
    Description of "Figure 25-1 ADF Connections Configuration Page"

  3. Set the Connection Type to Url, enter the Connection Name as Conductor, and click Create Connection.

    The URL Connections section displays (see Figure 25-2).

    Figure 25-2 ADF Connections Configuration Page (URL Connections)

    Description of Figure 25-2 follows
    Description of "Figure 25-2 ADF Connections Configuration Page (URL Connections)"

  4. Click the Edit (Pencil) icon.

    The URL Connection dialog displays (see Figure 25-3).

    Figure 25-3 URL Connection Dialog

    Description of Figure 25-3 follows
    Description of "Figure 25-3 URL Connection Dialog"

  5. Edit the URL so that it points to the Content Server instance used by the WebCenter Portal application. For example:

    http://example.com:8891/wcps/api/conductor?namespace=CP_namespace&repoId=myhost-ucm11g

  6. Update any other fields as required for your local connection and click OK.

25.6.2 Configuring the Content Presenter Task Flow Parameters

You can configure a Content Presenter instance through its task flow parameters. These can either be set at runtime in the Content Presenter Configuration dialog, or from JDeveloper as you add the Content Presenter task flow. To do this manually, you need to set two parameters: the Data Source Type parameter must be set to dsTypeScenarioResults, and the Data Source parameter should be set to something like:

conductor-connection-name=ConductorConnectionName,namespace=
ScenarioNamespace,scenario-name=ScenarioName,inputparam1=value1,inputparam2=value2

Note that the conductor-connection-name value must match with a URL connection that points to a valid Conductor server. Also, the namespace used should be the name of the namespace to which the specified scenario belongs. Finally, any input parameters that the scenario may be expecting can appended (as shown above), with a comma separating the name/value pairs.

For more information about configuring Content Presenter for Personalization, see:

25.6.3 Configuring the Conductor's Scenario Tags

On the Conductor side, your Scenarios must have the correct tag in order for Content Presenter to see them. Content Presenter uses the tag ContentPresenterScenario, so any scenarios you want Content Presenter to pick up must have this tag associated with them.

Once you have everything set up on both the Conductor and WebCenter Portal application side, everything else is fairly simple. When you open the Content Presenter Configuration dialog at runtime, the Content Source selection list displays Results of a Scenario. Selecting this displays a table of all of the scenarios that have been tagged for Content Presenter consumption. The first Scenario is always selected, and if it has any Input Parameters defined, they will be displayed below the table with input fields.

As you select scenarios in the table, the Input Parameters below will be updated. After selecting a scenario and specifying any input parameters, you can either preview or save Content Presenter to get the results. The results will be displayed much like any other multi-valued content source and will ultimately depend on the template selected for display purposes.

Note:

Any results that are returned from a scenario for use within Content Presenter must return a valid CMIS query as Content Presenter takes the return value and runs it (as a CMIS query) against the repository specified within the Conductor URL.

25.7 Configuring Single Sign-On

Single sign-on is configured as part of running the configureTrustWCPS.py and configureConnectionsWCPS.py scripts for configuring the Oracle WebCenter Portal domain, or the configureWCPS.py script for configuring JDeveloper's integrated WLS domain. When you run these scripts they also set up Trust Services single sign-on, which allows single sign-on for REST HTTP requests between client JEE Web applications, the Personalization Web application, and the WC_Spaces Web application REST services used by the out-of-the-box data providers. All these applications are also configured to support OAM/OSSO-provided single sign-on tokens, as well, without any additional Personalization-specific configuration. For more information, see Section 25.3.3, "Configuring Cross-Domain Trust."

25.8 Overriding the Default Security Settings

By default, all access to Personalization REST resources (other than the resourceIndex) requires authentication. In most cases this will be sufficient for development. However, for production environments, you may want to modify the default security constraints. The following sections describe how to set up less security to execute scenarios (where anonymous access is needed), and more security to prevent the ability to create new scenarios.

This section contains the following subsections:

25.8.1 Allowing Anonymous Execution of Scenarios

Adding the following security constraint to the domain's conductor-extensions-library\WEB-INF\web.xml, file will honor default descriptor (authentication required) security, plus allow anonymous GET/POST on scenarios created or deployed from an anonymous application or namespace:

<security-constraint>
  <web-resource-collection>
    <web-resource-name>ConductorJerseyWebApplication</web-resource-name>
    <url-pattern>/api/conductor/namespaces/anonymous/scenarios/*</url-pattern>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
  </web-resource-collection>
  <!-- Allow anonymous user access&nbsp; in this namespace -->
  <!--auth-constraint>
     <role-name>Users</role-name>
   </auth-constraint-->
</security-constraint>

25.8.2 Disabling Scenario Creation by Anonymous Users

You can disable scenario creation for any anonymous user using a simple filter that you add to the domain's conductor-extensions-library\WEB-INF\web.xml file. An example filter (AnonymousScenarioFilter) is shown below:

<filter>
    <filter-name>AnonymousScenarioFilter</filter-name>
    <filter-class>oracle.wcps.samples.AnonymousScenarioFilter</filter-class>
  </filter>
  <filter-mapping>
    <filter-name>AnonymousScenarioFilter</filter-name>
    <url-pattern>/api/conductor/namespaces/PublicPersonalization/scenarios</url-pattern>
  </filter-mapping>
  <security-constraint>
      <web-resource-collection>
          <web-resource-name>ConductorJerseyWebApplication</web-resource-name>
          <url-pattern>/api/conductor/namespaces/PublicPersonalization/scenarios/*</url-pattern>
          <http-method>GET</http-method>
          <http-method>POST</http-method>
      </web-resource-collection>
      <!--
        Commented out to allow anonymous user access  in this namespace
      <auth-constraint>
      <role-name>Users</role-name>
      </auth-constraint>
      -->
  </security-constraint>

The filter explicitly checks for an anonymous user (httpRequest.getUserPrincipal() == null) and an HTTP POST operation on the /api/conductor/namespaces/PublicPersonalization/scenarios URL, which is the REST resource for creating a scenario.

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain)
        throws IOException, ServletException
    {
        if (request instanceof HttpServletRequest)
        {
            HttpServletRequest httpRequest = (HttpServletRequest)request;
            String method = httpRequest.getMethod();
            if ("POST".equalsIgnoreCase(method) && httpRequest.getUserPrincipal() == null)
            {
              throw new ServletException("Anonymous users cannot create scenarios.");
            }
        }
        chain.doFilter(request, response);
    }

25.8.3 Disabling Scenario Creation by Authenticated Users

A simple change to the filter described in Section 25.8.2, "Disabling Scenario Creation by Anonymous Users" (removing the httpRequest.getUserPrincipal() check) would disable scenario creation for all users. Although the HTTP POST operation is also used to request execution of scenarios, the URI in that case is different (and protected in the <security-constraint> not the filter <url-pattern>).