4 Preparing Your Application for Oracle WebCenter Services

This chapter describes how to prepare your application to consume Oracle WebCenter services. It contains the following sections:


WebCenter services enrich existing portals and Web sites with enterprise 2.0 capabilities, including social computing services, personal productivity services, online awareness and communications, content integration, and Web analytics. For conceptual information about WebCenter services, see Section 1.1.4, "Introduction to Oracle WebCenter Services."

For important basic information about WebCenter applications, such as how to create an application, how to create customizable pages, and how to implement security, see Chapter 3, "Preparing Your Development Environment."

4.1 Preparing Your WebCenter Application to Consume Services

This section describes the steps you must take to prepare your application to use Oracle WebCenter Web services. It contains the following subsections:

4.1.1 How to Prepare Your Application to Consume Services

You can configure any application to include a WebCenter service. When you create an application in JDeveloper, you can choose to base the application on a template. Although not a requirement, the WebCenter Application template makes all the appropriate WebCenter connection wizards and tag libraries readily visible and available in the New Gallery and Component palette. When you consume a WebCenter services task flow or component, the necessary libraries are automatically added to the project.Depending upon the service you plan to consume, your application must meet certain prerequisites. For example, if the service must know the identity of users, then your application must provide some level of security with user authentication.

This section includes the following sub-sections: Implementing Security for Services

Some services must know the identity of the user (for example, the Search service needs the user's identity for saving searches). For these services, you must at least configure your application to authenticate users such that they have distinct identities for the purposes of personalization and user preferences.

For details on how to implement a basic security solution for your WebCenter custom application, see Section 3.5.1, "How to Configure ADF Security." For details on how to implement a complete security solution for your custom application, see Chapter 37, "Securing Your WebCenter 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. You see the default task flow grants, as shown in Figure 4-1. You can further configure these grants in this view.

Figure 4-1 ADF Security Policies in the jazn-data.xml file

Description of Figure 4-1 follows
Description of "Figure 4-1 ADF Security Policies in the jazn-data.xml file" Setting Up SSL-Protected Connections for Services

If you are setting up a connection in JDeveloper for a WebCenter service, 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.


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 WebCenter services connections:

  1. From the JDeveloper tool bar, select Tools > Preferences.

    The Preferences dialog displays (see Figure 4-2).

    Figure 4-2 Preferences Dialog

    Description of Figure 4-2 follows
    Description of "Figure 4-2 Preferences Dialog"

  2. On the Preferences dialog, click HTTPS and Truststore Settings.

    The HTTPS and Truststore Settings pane displays (see Figure 4-3).

    Figure 4-3 HTTPS and Truststore Settings Pane

    Description of Figure 4-3 follows
    Description of "Figure 4-3 HTTPS and Truststore Settings Pane"

  3. Change the value of Client Trusted Certificate Keystore to:


    where <JAVA_HOME> is the location of the Java home directory.

  4. Click OK.

4.1.2 Setting Up an External Application Connection

When a WebCenter 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 WebCenter services permit the use of an external application to connect with the service and define authentication for it:

  • Documents

  • Instant Messaging and Presence

  • Mail

  • RSS Viewer (when using a secured RSS feed)

For more information about setting up the external application for a WebCenter service, see Chapter 14, "Integrating the Documents Service," Chapter 18, "Integrating the Instant Messaging and Presence Service," Chapter 19, "Integrating the Mail Service," and Chapter 15, "Integrating the RSS Service." For more information about external applications in general, see Section 37.2, "Working with External Applications."

4.1.3 Automated Task Flow Grants

Table 4-1 lists the grants that are given when a task flow from the corresponding service is consumed. Common grants are granted whenever any Oracle WebCenter service is consumed.

Table 4-1 Automated Task Flow Grants

Service Grant Actions Name (Target)



















































External Application





Instant Messaging and Presence























Page Editor




















Recent Activities









































In addition to the services in Table 4-1, grants are also given when the External Application - Change Password task flow is applied when creating an external application in Oracle JDeveloper. Specifically, the TaskflowPermission is given and placed in /oracle/adfinternal/extapp/view/fragments/.*.

4.2 Extending Your Application with Custom Components

This section introduces the Resource Action Handling Framework and describes how to register a resource viewer. It contains the following subsections:

4.2.1 Introducing the Resource Action Handling Framework

Custom components are just like out-of-the-box WebCenter services in that they manage and own resources. As such, they must make declarations that enable their resources to be accessible to the WebCenter services that invoke other services (that is, the Search, Tags, Links, and Recent Activities services). WebCenter provides a Resource Action Handling framework for services that expose resources to be viewed, searched, and tagged.

For example, the Resource Action Handling framework enables the Search service to look up and follow the mechanism to render a resource for any given service. Other facilities of the Resource Action Handling framework allow for authorization of resources to be declared and enforced when access is made.

The following resources invoke resource viewers using the Resource Action Handling framework:

  • Search

  • Tags

  • Links

  • Recent Activities

  • People Connections

    • Activity Stream (invoking itself)

    • Connections (invoking itself)

    • Feedback (invoking itself)

    • Profile (invoking Tags, Tagged Items, and itself)

    • Message Board (invoking itself)

  • External links pointing into WebCenter (from, for example, mail, documents, RSS feeds, or REST XML)

The following resources own task flows that can be invoked by the Resource Action Handling framework.

  • Announcements

  • Discussions

  • Documents (URL rewriter points to the GET handler)

  • Events

  • Group Spaces (URL rewriter that maps to /webcenter/spaces/Space1Name)

  • Mail

  • Notes

  • Page

  • People Connections

    • Activity Stream - Main View

    • Connections

    • Feedback

    • Profile

    • Profile Gallery

    • Message Board

  • Tags - Tag Center

4.2.2 Registering a Resource Viewer

You must register a resource viewer to enable custom resources to be rendered using Search or Tags, or to make the resources linkable to and from each other.

In the service-definition.xml file, you can define a resource viewer for any service to render that service's resources. The viewer can be a task flow or a URL rewriter acting on the resource ID.

For example, suppose a discussion forum message is found through the Search service. Clicking the result link launches the resource viewer that was declared for the Discussions service (by looking up the service-definition.xml of the Discussions service). By default, the target is rendered in a dialog.


When you add a Search, Tags, or Recent Activities task flow to your application, that service creates a sample service-definition.xml file. This file enables developers to declare their resource viewers and their implementations of interfaces for interacting with the Links and Search services; for example, the QueryManager interface implementation.

To register a custom resource viewer:

  1. In the Application Navigator, right-click the Page Flows node for the ViewController project and select New from the context menu.

  2. Under Categories, select JSF, then ADF Task Flow.

  3. Click OK.

  4. In the Create Task Flow dialog, change File Name to resource-viewer.xml. The Task Flow ID should automatically update to resource-viewer (Figure 4-4).

    Figure 4-4 Create Task Flow Dialog for Resource Viewer

    Description of Figure 4-4 follows
    Description of "Figure 4-4 Create Task Flow Dialog for Resource Viewer"

  5. Click OK.

    Ensure that the resource-viewer.xml file is created under ..\public_html\WEB-INF.

  6. From the Component Palette, ensure that ADF Task Flow is selected and drag View onto the task flow to create a page fragment.

  7. Rename the page fragment to resource-viewer, and click in an open area of the canvas to accept the change.

  8. Define a JSFF file for your page fragment.

  9. Double-click the page fragment.

  10. Click OK in the Create New JSF Page Fragment dialog.

  11. Go to the Source view in the editor and paste an af:outputText tag inside of the jsp:root element.

    Example 4-1 provides a very simple resource viewer. You could create a much more complex viewer.

    Example 4-1 Simple Resource Viewer

    <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
      <af:outputText value="Rendering #{pageFlowScope.resourceId}"
  12. Add a resourceId input parameter to the task flow, and set the value to #{pageFlowScope.resourceId}.

  13. After the task flow is defined, you must register it in the service-definition.xml file. In the Application Navigator, expand Application Resources, Descriptors and ADF META-INF.

  14. Double-click service-definition.xml to open it in the editor.

  15. In the file, you see a service definition that has been commented out. Uncomment it by removing the <!-- and --> tags around it.

  16. Set the id attribute to the service identifier.

    For example, the service identifier used when defining the Tagging Button could be mycompany.myproduct.myapp.mycomponent.

  17. Set the taskFlowId to /WEB-INF/resource-viewer.xml#resource-viewer.

    This identifier is the task flow path and file name concatenated with the task flow identifier declared in the Create Task Flow dialog. You can omit the remaining tags.

  18. The <resource-view> declaration has a class specification for the resource authorizer. This provides various ways to specify the resource view and determine which tagged objects are visible (and searchable) to users.

    Example 4-2 Specifying a Task Flow ID in a resource-view Declaration

    <resource-view taskFlowId="/somepath/somefile.xml#someId"

    The Search, Tags, and Discussions services use this type of declaration. Instead of having a view ID (JSPX page), the service supplies a task flow to render the resource.

    • The attribute taskFlowId signifies that the renderer is a task flow.

    • A task flow is used to render the resource specified by the resource ID.

    • The task flow honors a resourceId input parameter and uses that to render the resource.

    Example 4-3 Specifying a URL Rewriter Class Name (1)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.IdentityResourceUrlRewriter"


    Example 4-4 Specifying a URL Rewriter Class Name (2)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.MessageFormatResourceUrlRewriter"
        <!-- This starts from the context root which would be /webcenter -->
        <parameter name="message" value="/content/conn/UCM/path/{0}"/>


    Example 4-5 Specifying a URL Rewriter Class Name (3)

    <resource-view urlRewriterClass="oracle.webcenter.framework.internal.resource.MyResourceUrlRewriter"
        <parameter name="myParam" value="myValue"/>

    Services, such as Oracle SES and Documents, use a URL rewriter to treat the resource ID as a URL and rewrite the URL in an appropriate fashion. A URL rewriter changes the resource ID into a URL that can be launched with a goLink. Two ResourceUrlRewriters are provided:

    • oracle.webcenter.framework.internal.resource.IdentityResourceUrlRewriter is for Oracle SES. It takes the resourceId value as a URL as is.

    • oracle.webcenter.framework.internal.resource.MessageFormatResourceUrlRewriter is for Documents. It takes in a message parameter (in the service-definition). The message parameter contains a {0}, which is replaced with the value of the resourceId. The urlExternal parameter applies to all URL rewriters. This parameter's value determines whether the JSPX that consumes a resource action handler link should open a new window.

    The default behavior is to launch a new window dialog with that URL.

    Some resources, like pages and wikis, can have no resource viewer but may allow dubbing their resource IDs as page view IDs (Example 4-6).

    Example 4-6 No Resource Viewer (Resource ID as Page View ID)

    <resource-view authorizerClass="some.service.id.Authorizer3"/>

    The resource authorizer interface uses Java interfaces and classes to return useful information about service resources. For example, the oracle.webcenter.framework.resource.ResourceAuthorizer interface contains a method that returns the status (available or not available) for a unique resource ID (Example 4-7).

    Example 4-7 Method for Returning Status Against a Unique Resource ID

     * Check if the passed in resourceIds are viewable by the current user.
     * @param resourceId - the resourceId that we want to check
     * @return - a <code>ResourceInfo</code> with a ResourceStatus
     * of RESOURCE_IS_AVAILABLE if the passed in resourceId
     * is viewable by current user, otherwise returns
     * <code>RESOURCE_IS_NOT_AVAILABLE</code>.
    ResourceInfo getResourceInfo(String resourceId, Scope scope);
     * Check if the passed in resourceIds are viewable by the current user.
     * @param resourceIds - the resourceIds that we want to check
     * @return - a List of <code>ResourceInfo</code> with a ResourceStatus
     * of RESOURCE_IS_AVAILABLE if the passed in resourceId
     * is viewable by current user, otherwise returns
     * <code>RESOURCE_IS_NOT_AVAILABLE</code>.
    List<ResourceInfo> getResourceInfo(List<String> resourceIds, Scope scope);

    The oracle.webcenter.framework.resource.ResourceInfo interface exposes the following method:

    public ResourceStatus getResourceStatus();

    The oracle.webcenter.framework.resource.ResourceInfo.ResourceStatus enumeration includes the following possible values:

    Example 4-8 Possible ResourceStatus Values

     * Used to describe a related object's status.
     * Certain operations may be performed by relationship service depending
     * on what object status it receives from the service.  For example,
     * if it receives {@link #RESOURCE_DOES_NOT_EXIST} it may remove all
     * relationships associated with this object from the relationship schema
     * so future calls are not wasted on this object.
     public enum ResourceStatus
        * Used to describe a resource that is available.
        * Used to describe a resource that does not exist.
        * Should be used when the user does not have view access on the resource.

    The only method in the oracle.webcenter.framework.resource.ResourceUrlRewriter interface writes the URL, after a unique identifier is passed in. This URL can be an absolute URL or it can be one relative to the faces context root of the owning application.

    Example 4-9 Resource URL Rewriter Method

    public String rewriteUrl(String id);
  19. Your service should look similar to the one shown in Example 4-10.

    Example 4-10 Sample Service Definition for Resource View

      <service-definition id="mycompany.myproduct.myapp.mycomponent"
      <resource-view taskFlowId="/somepath/somefile.xml#someId"
      <name>My Custom Component</name>
      <description>My Custom Component's Description</description>
  20. Save the service-definition.xml file.

4.3 Configuring General Settings for Your Services

Optionally, you can enable users to set the time zone, the date and time format, the language (locale), and the accessibility mode for the services you add to your application. You can provide these capabilities through the WebCenter General Settings service. This service contains values that you can access either directly from the JSF page(s) in your WebCenter application or indirectly, through an API. The General Settings service covers the following areas:

  • Time Zone: By default, displays the time defined by the server running the WebCenter 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 the service 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.

The General Settings service 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-5 shows the Insert EL Expression dialog with General Settings.

Figure 4-5 Expression Builder for the generalSettings JSF Managed Bean

Description of Figure 4-5 follows
Description of "Figure 4-5 Expression Builder for the generalSettings JSF Managed Bean"

Table 4-2 describes the preference values for the General Settings service.

Table 4-2 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 (default, inaccessible, or screenReader) for use in the accessibility-mode setting in trinidad-config.xml.


Java date style to be used in dateStyle attributes when displaying dates and times.


Java time style to be used in timeStyle attributes when displaying dates and times.


Java date pattern to be used when displaying dates, and not times.The pattern must be a valid java.text.SimpleDateFormat pattern; for example: dd-MMM-yyyy. This takes precedence over preferredDateStyle.


Java time pattern to be used when displaying times, and not dates. This takes precedence over preferredTimeStyle.


Java date/time pattern to be used when displaying dates and times.

This takes precedence over preferredDateStyle and preferredTimeStyle.


Java time zone to be used in timeZone attributes when displaying dates and times.


Preferred skin name to use with the skin-family setting in trinidad-config.xml.

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-11 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-12 Code for Displaying Specified Date and Time

<af:outputText value="#{row.dateTimeValue}">
    <af:convertDateTime type="both"
                        locale="#{facesContext.externalContext.requestLocale}" />

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-13 Setting the Accessibility Mode in trinidad-config.xml


4.3.1 Building a Preferences User Interface

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-2.

Any WebCenter service that displays a date and time uses the settings configured in the General Settings service. For information on using the General Settings Service 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.

For more information, see Oracle Fusion Middleware Java API Reference for Oracle WebCenter.