../E63259-01.epub /> ../E63259-01.mobi />
This chapter describes how to prepare your application to consume tools and services in Oracle WebCenter Portal.
This chapter includes the following topics:
Oracle WebCenter Portal tools and services enrich portals and Web sites with social computing services, personal productivity services, online awareness and communications, content integration, and Web analytics.
This section summarizes the key technologies. This can help you determine which tools and services to implement and the best way to customize your user interface.
Note:
WebCenter Portal tools and services expose their functionality through task flows that you can add to the pages of your application. If these task flows do not quite meet your requirements, you can customize them to change their look and feel or functionality. For example, you can add text, change labels, remove regions or components, or show additional attributes. For more information, see Chapter 23, "Customizing WebCenter Portal Tools and Services Task Flows."This section includes the following subsections:
Some tools and services in WebCenter Portal are considered horizontal in that they interact with other tools and services across an application.
Table 4-1 lists integration points in WebCenter Portal.
Table 4-1 Integration Points in WebCenter Portal
WebCenter Portal Tool or Service | RSS | Search | Tags | Links | Comments and Likes | Activity Stream | Activity Graph | Notifications | Analytics |
---|---|---|---|---|---|---|---|---|---|
Activity Graph |
X |
n/a |
X |
||||||
Announcements |
X |
X |
X |
X |
X |
||||
Blogs |
X |
X |
X |
X |
X |
X |
X |
X |
|
Discussions |
X |
X |
X |
X |
X (replies on topics) |
X |
X (replies) |
X |
|
Documents, including wikis |
X |
X |
X |
X |
X |
X |
X |
X |
|
Events |
X partial |
X |
X |
X |
|||||
Instant Messaging and Presence (IMP) |
X |
||||||||
Lists |
X |
X |
X |
X |
X |
X |
|||
|
X |
||||||||
Notes |
X |
X |
|||||||
People Connections |
X partial |
X partial |
X (Activity Stream, Message Board) |
X (Message Board, Profiles, Feedback |
X (Message Board) |
X |
X |
||
Polls |
|||||||||
Recent Activities |
X |
||||||||
Search |
n/a |
X |
X partial |
X |
|||||
Tags |
X |
n/a |
X |
Note:
Search (listed in the table) uses WebCenter Portal search adapters to search each available component. However, large-scale implementations should be configured to use Oracle SES search for best performance. Oracle SES searches applications for the following resources:Documents, including wikis and blogs
Announcements and discussions
For more information, see Chapter 45, "Integrating Search."
This section describes the APIs available for WebCenter Portal tools and services.
Note the following considerations when multiple customization options are available:
Use REST APIs to build a custom client for accessing WebCenter Portal; for example, an iPhone application that interacts with WebCenter Portal.
REST APIs may provide the fastest and easiest way to customize the user interface and develop custom components. Consider using data controls or native APIs to build a custom user interface for accessing WebCenter Portal.
Use data controls or native APIs to build a custom portal or composite Framework application.
Use data controls or native APIs if you are proficient with Java, JDeveloper, and ADF. To use other languages, especially JavaScript, use REST APIs.
Table 4-2 lists tools and services with available APIs.
Table 4-2 Supported Technologies for Tools and Services
WebCenter Portal Tool or Service | Data Controls | Java APIs | REST APIs | Back End APIs |
---|---|---|---|---|
Activity Graph |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Analytics |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Announcements |
Web Services with Oracle WebCenter Portal's Discussions Server (requires configuration, because WebCenter Portal is set up with custom authentication) See the Jive Forums documentation on the Oracle Fusion Middleware documentation library (in the WebCenter Portal product area) |
|||
Comments & Likes |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Discussions |
Web Services with Oracle WebCenter Portal's Discussions Server (requires configuration, because WebCenter Portal is set up with custom authentication) See the Jive Forums documentation on the Oracle Fusion Middleware documentation library (in the WebCenter Portal product area) |
|||
Documents (with wiki and blogs) |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
Oracle Fusion Middleware Content Management REST Service Developer's Guide |
See Oracle Fusion Middleware Java API Reference for Oracle WebCenter Content Remote Intradoc Client (RIDC) Oracle Fusion Middleware Services Reference Guide for Oracle Universal Content Management |
|
Events |
Web Services with Microsoft Exchange |
|||
General Settings |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Links |
||||
Lists |
||||
Notifications |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Pagelet Producer |
||||
People Connections |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
Chapter 42, "Using the People Connections REST APIs" (for Profile and Activity Stream) |
||
Personalization |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal (for developing custom Providers and Locators) |
|||
Polls |
||||
Resource Action Handler Framework |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
|||
Search |
Section 45.3.5, "Using the Search Data Control" Note: Only Oracle SES search supports the search data control. |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
Section 45.3.4, "Using the Search REST APIs" Note: Only Oracle SES search supports the search REST APIs. |
Web Services and Java APIs with Oracle Secure Enterprise Search |
Tags |
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal |
See Also:
Oracle Fusion Middleware Java API Reference for Oracle WebCenter Portal for more information about Expression Language APIsSeveral tools and services provide data controls for building a customized user interface with a Framework application or task flow. Deploying this task flow into an ADF library allows for a portable consumption of the task flow; for example, you could add it to a resource catalog for a page template in a portal in a WebCenter Portal application.
You do not need to integrate a tool or service before you can use its data control to edit the user interface. An application is configured for the respective tool or service when one of its data controls or task flows is used.
Note:
Oracle ADF architecture provides data controls for the user interface to understand the structure of your data. Metadata describes data collections, properties, methods, and types. When you drag and drop attributes, collections, and methods onto a page, JDeveloper automatically creates the bindings from the page to the associated tools and services.See Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework for detailed information about data controls.
To use a built-in data control:
In JDeveloper, create a WebCenter Portal Framework application with any connections required.
In the Resource Palette, expand My Catalogs, WebCenter Portal - Services Catalog, and Data Controls.
Right-click the data control and choose Add to Project.
Figure 4-1 Data Controls in the Resource Palette
Drag and drop methods and properties from the data control to a ADF JSF page.
Note:
There are two other ways to add data controls to your application:From the Resource Palette, choose IDE connections, and navigate to the data control. Right-click the data control, and select Add to Project.
From Project Properties, choose Libraries and Classpath, and click the Add Library button. With this approach, you must know the JDeveloper library that contains the data control you want.
This section describes the steps you must take to prepare your application to use WebCenter Portal tools and services. It includes the following subsections:
Section 4.2.1, "How to Prepare Your Application to Consume Tools and Services"
Section 4.2.3, "Setting Up an External Application Connection"
You can configure any application to include a tool or service. When you create an application in JDeveloper, you can choose to base the application on a template. Although not a requirement, WebCenter Portal's Framework application template makes all the appropriate connection wizards and tag libraries readily visible and available in the New Gallery and Component palette. When you consume a task flow or component, the necessary libraries are automatically added to the project.
Depending upon the tool or service you plan to consume, your application must meet certain prerequisites. For example, if the tool must know the identity of users, then your application must provide some level of security with user authentication.
This section includes the following subsections:
Some tools must know the identity of the user (for example, search needs the user's identity for saving searches). For these tools and services, you must at least configure your application to authenticate users such that they have distinct identities for the purposes of user customization and preferences.
ADF security is configured by default if you created your application using WebCenter Portal's Framework application template.
See Also:
Section 74.3, "Configuring ADF Security" for details on how to implement a basic security solution for your Framework application
Chapter 74, "Securing Your WebCenter Portal Framework Application" for details on how to implement a complete security solution for your Framework application
After you configure ADF security for your application, you can open the jazn-data.xml
file and modify your sample user's privileges for each task flow. To open the ADF Security Policies Editor, locate the file in the Application Resources panel and double-click its name, or select Application - Secure - Resource Grants (Figure 4-2). The Resource Type drop down controls the set of grants that are shown in the table. You can show only the grants for a particular permission type by selecting it from the list.
Figure 4-2 ADF Security Policies in the jazn-data.xml File
If you are setting up a back-end connection in JDeveloper, and the connection is being made to an SSL-protected endpoint (with a valid certificate from a trusted certificate authority) then you need prepare your environment accordingly.
Note:
This Preferences setting change is required only for connections made using Integrated WLS as the default server. If you are deploying to a Managed Server, this settings change is not required.To set preferences for SSL-protected connections:
From the JDeveloper tool bar, select Tools > Preferences.
The Preferences dialog displays (Figure 4-3).
On the Preferences dialog, click Credentials (Figure 4-4).
Change the value of Client Trusted Certificate Keystore to:
<JAVA_HOME>/jre/lib/security/cacerts
where <JAVA_HOME>
is the location of the Java home directory.
Click OK.
Many tools and services require a connection to a database schema where relevant information is stored. For example, with links, relationship mapping information, such as what object is linked to what other object, is stored in the database.
Table 4-3 lists the tools and services that require a database connection.
Table 4-3 Associated Data Source
Tool or Service | Database Schema |
---|---|
Activity Graph |
ACTIVITIES schema |
Activity Stream |
WEBCENTER schema |
Analytics |
ACTIVITIES schema |
Blogs |
WEBCENTER schema |
Comments |
WEBCENTER schema |
Documents (including wikis and blogs) that want to include Comments and Activity Stream |
WEBCENTER schema |
Links |
WEBCENTER schema |
Lists |
WEBCENTER schema |
Oracle Portal Adapter |
PORTAL schema (name of the Oracle Portal schema) For more information, see the section "Setting Up the Environment to Use the Federated Portal Adapter" in the Oracle Fusion Middleware Administrator's Guide for Oracle Portal. |
People Connections |
WEBCENTER schema |
Polls |
WEBCENTER schema |
Tags |
WEBCENTER schema |
Announcements |
DISCUSSIONS schema |
Discussions |
DISCUSSIONS schema |
See Also:
Section 2.2.5, "Configuring WebCenter Back-End Services" for information about installing the schemas
The "Deploying the Application to a WebLogic Managed Server" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal for data source considerations when deploying your application to a production environment
To create the database connection:
In the Application Navigator, expand the Application Resources panel.
Right-click Connections, then click Database.
Enter the following information for your database connection:
Connection Name: webcenter/CustomPortal
or activities/CustomPortal
Note:
Oracle recommends that you use these names for ease of deployment to a Framework managed server.If your application contains task flows that use the WebCenter Portal schema, then name the database connection webcenter/CustomPortal
.
If the application contains task flows that use the Activities schema, then name the database connection activities/CustomPortal
.
Connection Type: Oracle (JDBC)
Username: username
Password: password
Host: host where you install the WebCenter Portal schema; for example, localhost
JDBC Port: port; for example, 1521
SID: system identifier for the database with the same JDBC; for example, ORCL
Note:
If the Save Password checkbox is not selected, then when deploying from JDeveloper to a managed server or the Integrated WebLogic Server, you must manually create the data source after deployment.For detailed information on how to create a JDBC data source for Oracle WebLogic Server, see the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Click OK.
In the Associate to Data Source dialog, select the appropriate schema.
If you named the connection webcenter/CustomPortal
, then select to associate this connection to the WebCenter Portal schema.
If you named the connection activities/CustomPortal
, then select to associate this connection to the Activities schema.
Click OK (Figure 4-6).
Figure 4-6 Associating to Data Source from the Connection Wizard
The data source association applies separately to each project in the workspace. If there is more than one WebCenter Portal project in the workspace, then the dialog displays a dropdown list allowing the user to choose which project to configure.
Note:
While you can set up the connections to back-end servers at design time in Oracle JDeveloper, you can later add, delete, or modify connections in your deployed environment using Enterprise Manager Fusion Middleware Control.See the guide Oracle Fusion Middleware Administering Oracle WebCenter Portal for more information.
For existing database connections, you can associate data sources by right-clicking the connection and selecting Associate to Data Source (Figure 4-7).
Figure 4-7 Associating to Data Source for Existing Connections
When a tool or service interacts with an application that handles its own authentication, you can associate that application with an external application definition to allow for credential provisioning.
The following tools and services permit the use of an external application to connect with it and define authentication for it:
Documents
Events
Instant Messaging and Presence
RSS Viewer (when using a secured RSS feed)
See Also:
Chapter 28, "Integrating Documents," Chapter 34, "Integrating Instant Messaging and Presence," Chapter 35, "Integrating Mail," and Chapter 52, "Integrating RSS" for more information about setting up an external application
Section 74.13, "Working with External Applications" for more information about external applications in general
Many services used with WebCenter Portal provide access to resources. For example, search results can include links to documents, tags, activities, and other types of resources. This section explains how to specify the way such resources are rendered in the portal.
Section 4.3.2, "Rendering Resources in the Same Browser Window"
Section 4.3.4, "Rendering Resources in a New Browser Window"
Section 4.3.5, "Setting Rendering Behavior with the resourceActionBehavior Tag"
Section 4.3.6, "Updating adf-config.xml in Deployed Framework Applications"
Figure 4-8 shows sample results for a search. There are numerous clickable elements in the results, including links to user profiles, documents, tags, blogs, and wiki pages.
For Portal Framework applications, most services render their resources directly in the browser window.
The possible resource rendering behaviors available within WebCenter Portal are:
Full-screen rendering in the same browser window. This option is the default for most services. The resource is opened in a viewer task flow by navigating from the browser to the resource using the same browser window. See Section 4.3.2, "Rendering Resources in the Same Browser Window."
ADF inline popup. This option opens the resource in an inline popup (a dialog-like window that pops up and is contained within the current browser window.) See Section 4.3.3, "Rendering Resources in an ADF Inline Popup."
New browser window. This option renders the resource in a new browser window. See Section 4.3.4, "Rendering Resources in a New Browser Window."
By default, most resources are rendered full-screen in the same browser window.
Note:
In some special cases, resources are intentionally rendered by default in an inline popup dialog, as explained in Section 4.3.5, "Setting Rendering Behavior with the resourceActionBehavior Tag."To explicitly set the default rendering to the browser window, you can do the following:
In the Application Navigator, open the Application Resources list.
Open the Descriptors folder and then open the ADF META-INF folder.
Open the adf-config.xml
file in the editor and add a <resource-handler>
element, as shown in Example 4-1. In this example, the DefaultResourceActionHandler (the default class to which rendering is delegated) specifies the desired behavior. If you were to remove the <resource-handler>
element from adf-config.xml
entirely, the behavior would be exactly the same. The behavior specified in Example 4-1 applies to all services.
To change the default rendering from the browser window to an ADF inline popup dialog, do the following:
In the Application Navigator, open the Application Resources list.
Open the Descriptors folder and then open the ADF META-INF folder.
Open the adf-config.xml
file in the editor and add a <resource-handler>
element, as shown in Example 4-2. In this example, the DefaultResourceActionHandler (the default class to which rendering is delegated) is overridden by the display-as-popup=true
attribute.
Example 4-2 Specifying ADF Inline Popup for Rendering
<wpsC:adf-service-config xmlns="http://xmlns.oracle.com/webcenter/framework/service"> <resource-handler class="oracle.webcenter.framework.resource.view.DefaultResourceActionHandler" display-as-popup="true" /> </wpsC:adf-service-config>
If the user clicks the Maximize button in an inline popup, then the currently specified default handler is invoked. For DefaultResourceActionHandler, the resource appears full-screen in the browser. If PopUpResourceActionHandler is specified in adf-config.xml
, then it displays in a new browser window. See also Section 4.3.4, "Rendering Resources in a New Browser Window."
To change the default rendering from within the browser window to a new browser window, do the following:
In the Application Navigator, open the Application Resources list.
Open the Descriptors folder and then open the ADF META-INF folder.
Open the adf-config.xml
file in the editor and add the <resource-handler>
element, as shown in Example 4-3. In this case, rendering is delegated to the PopUpResourceActionHandler class.
Rendering behavior that is set in adf-config.xml
can be overridden on the resource link itself using the resourceActionBehavior
tag and setting the useResourcePopup
attribute to values of always
, never
or appDefined
.
WebCenter Portal uses this technique for targeted cases where a full navigation does not make sense. For example, search results may include the resource's author. When you click this user name link, you see the popup summary profile of the author without navigating away from the search result.
If useResourcePopup
is not set, or if it is set to appDefined
on the resource link, then the display-as-popup
attribute in adf-config.xml
is honored.
Note:
In cases where WebCenter Portal services override the<resource-handler>
by design, the useResourcePopup
tag is set to always
in their resourceActionBehavior
tags. You can change this by customizing the task flow itself.In deployed applications, the <resource-handler>
settings in adf-config.xml
can be added and updated using WLST commands. For command syntax and examples, see the sections, "setWebCenterServiceFrameworkConfig" and "getWebCenterServiceFrameworkConfig" in Oracle Fusion Middleware WebLogic Scripting Tool Command Reference.
Optionally, you can enable users to set the time zone, the date and time format, the language (locale), and the accessibility mode for the tools and services you add to your application. You can provide these capabilities through WebCenter Portal General Settings. This contains values that you can access either directly from the JSF page(s) in your Framework application or indirectly through an API. General Settings covers the following areas:
Time Zone: By default, displays the time defined by the server running the application. This is based on java.util.Timezone
; for example, GMT+0800
. It also supports the format Region/Country
; for example, Europe/Amsterdam
.
Date/Time: By default, configured to the style java.text.DateFormat.SHORT
. This is based on java.text.DateFormat
; for example, java.text.DateFormat.MEDIUM
. Supported values are SHORT
, MEDIUM
, LONG
and FULL
.
Language: By default, defined by the locale of the user's browser. This is based on java.util.Locale
; for example, fr-CA
.
Accessibility Settings: A value to use with the accessibility-mode
setting in the trinidad-config.xml
file. Valid values are default
, inaccessible
, or screenReader
.
Application Skin: A value to use with the skin-family
setting in the trinidad-config.xml
file. This is based on the Trinidad skin-family
attribute. Valid values are defined by skins included with the application.
To use this directly from your application, use Expression Language in your JSF pages to access the generalSettings
managed bean. The style is based on the java.util.Timezone
, and the pattern is based on java.text.SimpleDateFormat
.
When you add generalSettings
as the value attribute of an ADF component, for example af:activeOutputText
, you can open the Expression Builder, then navigate to JSF Managed Beans > generalSettings to view the preference values for the bean.
General Settings supports both pattern-based and style-based formats. If a pattern is not specified, then the style is used. By default, the patterns are not specified or null.
Figure 4-9 shows the Insert EL Expression dialog with General Settings.
Figure 4-9 Expression Builder for the generalSettings JSF Managed Bean
Table 4-4 describes the preference values for General Settings.
Table 4-4 General Settings Managed Bean Preference Values and Descriptions
General Settings Preference Value | Description |
---|---|
|
Displays the current date in the user's selected locale. |
|
Displays the current date and time in the user's selected locale. |
|
Displays the current time in the user's selected locale. |
|
Preferred accessibility mode ( |
|
Java date style to be used in |
|
Java time style to be used in |
|
Java date pattern to be used when displaying dates, and not times.The pattern must be a valid |
|
Java time pattern to be used when displaying times, and not dates. This takes precedence over |
|
Java date/time pattern to be used when displaying dates and times. This takes precedence over |
|
Java time zone to be used in |
|
Preferred skin name to use with the |
For example, to display the current date and time in the user's selected locale, time zone, and format, add the following to your page:
Example 4-4 Code for Displaying Current Date and Time in User's Locale
<af:outputText value="#{generalSettings.formattedCurrentDateTime}"/>
Or, to display a specific date and time:
Example 4-5 Code for Displaying Specified Date and Time
<af:outputText value="#{row.dateTimeValue}"> <af:convertDateTime type="both" dateStyle="#{generalSettings.preferredDateStyle}" timeStyle="#{generalSettings.preferredTimeStyle}" timeZone="#{generalSettings.userTimeZone}" locale="#{facesContext.externalContext.requestLocale}" /> pattern="#{generalSettings.preferredDateTimePattern}" </af:outputText>>
To take advantage of the preferred accessibility mode, you must add an EL (Expression Language) expression to the application's trinidad-config.xml
file to set the accessibility mode; for example:
Example 4-6 Setting the Accessibility Mode in trinidad-config.xml
<accessibility-mode>#{generalSettings.preferredAccessibilityMode}</accessibility-mode>
You can build a user interface using the General Settings API to enable users to either accept the default settings or apply their desired settings. The API contains the same preference values described in Table 4-4.
Any tool or service in WebCenter Portal that displays a date and time uses the settings configured in General Settings. For information on using the General Settings API to build a preferences user interface, see the Javadoc for oracle.webcenter.generalsettings
. Specifically, the oracle.webcenter.generalsettings.model
package contains APIs to get and set preference values for each of the settings. Use these APIs to build a custom user interface to allow users to view and set their preferred values.
By default, ADF obtains the user's locale from the user's browser settings. You can change this behavior to have the user's preferred locale be set in the application using a Preferences UI.
To make the behavior change, include oracle.webcenter.generalsettings.model.filter.GeneralSettingsLocaleFilter
as a servlet filter in web.xml
and adfBindings
. This servlet filter sets the default locale (ADF Locale) from the General Settings locale preference instead of from the user's browser.
Add the General Setting locale filter to web.xml
with the following rules:
Define the filter. For example:
<filter> <description> WebCenter General Settings locale setting. </description> <filter-name> generalSettingsLocaleFilter </filter-name> <filter-class> oracle.webcenter.generalsettings.model.filter.GeneralSettingsLocaleFilter </filter-class> </filter>
Add the filter after the adfBindings
filter with the same servlet-name. For example:
<filter-mapping> <filter-name> generalSettingsLocaleFilter </filter-name> <servlet-name>Faces Servlet</servlet-name> </filter-mapping>
If this filter is not set, then the locale is sourced first from the client browser locale setting, and then from the ADF locale setting.
If this filter is set, then the locale is sourced from the General Settings. If the General Settings locale preference does not exist, then it reverts to the non-filter default behavior.