Providing Oracle SES Search in a Secure Portlet

You can provide a secure portlet for Oracle SES on any OracleAS Portal page. You can place separate portlets for the search box and search results, and you can display customized results. Oracle SES portlets conform to the Web Services for Remote Portlets (WRSP) specification.

To implement a secure portlet, you must configure both Oracle SES and the OracleAS Portal page. The supported OracleAS Portal Server version is 10.1.4.2.0 with a mandatory one-off patch 7560661.

Choosing a Portlet Type

Oracle SES supports three different portlet types:

  • Full Portlet: Displays both the search box and the search results in a single portlet. The default name is SESPortlet. Figure 3-4 shows a full Oracle SES portlet.

  • Search Box Portlet: Displays the search box, source groups, and alternate keywords. The search results are displayed in a separate search results portlet, which must be on the same Portal page. The default name is SearchBox Portlet.

  • Search Results Portlet: Displays the result list, suggested links, and pagination links for a query entered in a search box portlet. The search results portlet must be on the same Portal page as the search box portlet. The default name is SearchResults Portlet.

Figure 3-4 Oracle SES Portlet

Surrounding text describes Figure 3-4 .

Figure 3-5 shows a search box portlet and a search results portlet. They automatically coordinate their interactions, so they are always synchronized.

Figure 3-5 SearchBox Portlet and SearchResults Portlet

Surrounding text describes Figure 3-5 .

Configuring Oracle SES for a Secure Portlet

On the Oracle SES (provider) side, you must edit the XML configuration file and restart the Oracle SES middle tier so that the changes take effect.

If you are supporting a secure portlet for the first time, follow this procedure:

Customizing the Portlet Configuration File

You can optionally make these changes at any time:


Supporting Multiple Instances of a Portlet Type
Supporting Result List Customizations

To implement your changes, follow this procedure:

Restarting the Oracle SES Middle Tier

About the Portlet Configuration File

The Oracle SES portlet configuration file is portlet.xml. It is located in the following directory:

ORACLE_HOME/search/webapp/search_portlet/search_portlet_war/WEB-INF

Note:

Only the Oracle SES administrator should edit the portlet.xml file. Changes to portlet.xml are global to the Oracle SES instance. Changes take effect when you restart the Oracle SES.

Customizing the Portlet Configuration File

The current version of portlet.xml supports all the functionality provided in Oracle SES 11g for secure portlets.

To configure a new default portlet.xml file 

  1. Create a copy of the file search_portlet.ear, which is located in ORACLE_HOME/search/webapp/. To do this, first create a folder called tempPortlet within the webapp directory, and then save a copy of the search_portlet.ear file in the tempPortlet folder.

  2. Navigate to the tempPortlet folder.

  3. Edit the portlet.xml file. To do this, from the tempPortlet folder, first expand the search_portlet.ear file, and then expand the search_portlet_war.war file within this.

    The portlet.xml file is located inside WEB-INF/ in the directory where you expanded search_portlet_war.war. For example, its path is ORACLE_HOME/search/webapp/tempPortlet/search_portlet/search_portlet_war/WEB-INF/portlet.xml.

  4. Open portlet.xml in an XML or text editor.

  5. Set the initialization parameters described in Table 3-4 as desired.

  6. Repackage the search_portlet_war.war. Use the command

     jar cvf search_portlet_war.war images/jsp/WEB-INF

  7. Repackage search_portlet.ear. Use the command

    jar cvfM search_portlet.ear search_portlet_war.war META-INF/

  8. Create a backup of the original search_portlet.ear file in ORACLE_HOME/search/webapp/.

  9. Copy search_portlet.ear from tempPortlet to ORACLE_HOME/search/webapp/.

  10. Redeploy the search_portlet.ear to the Oracle WebLogic Server using the Web console located at http://<hostname>:<portNumber>/console.

  11. Restart the Oracle SES midtier, as described in "Restarting the Oracle SES Middle Tier".

You can customize some portlet preferences from the Edit Defaults page and the Edit page in the Portal user interface. See "Using the Portal User Interface to Change Preferences".

Table 3-4 Oracle SES Portlet Initialization Parameters

Parameter Description

absUrlPrefix

Set to http://HostName:PortNumber/ where HostName and PortNumber are the host name and port number of the Oracle SES instance.

appID

Set this value to one of the keys that is configured as a federated trusted entity to enable secure search.

appPWD

Set this value to be the same as the password of the configured federated trusted entity to enable secure search.

Note: Set up federated trusted entities on the Global Settings - Federation Trusted Entities page in Oracle SES. Enter an entity name and password, then click Add. The entry is added to the Trusted Entities table.

displayMode

When configuring a second instance of a portlet type, set to one of the following values:

  • full: Displays the search box and search results in the same portlet. (Default)

  • search_box: Displays the search box in separate portlet. The search box portlet also displays source groups either in a list or as links, and optionally shows an image for the search button. See the searchButtonImage parameter.

  • search_results: Displays the results in a separate portlet for the search term entered in the search box portlet.

See "Supporting Multiple Instances of a Portlet Type".

enableSourceGroups

Controls the use of source groups:

true: Displays source groups.

false: Disables and hides source groups. Queries are performed on the All group.

endPointURL

Set to http://HostName:PortNumber/search/query/OracleSearch where HostName and PortNumber are the host name and port number of the Oracle SES instance.

navSize

Specifies the number of additional page number links to display on either side of the current page in the pagination links. (Default 3)

portletHeight

Controls the height of the portlet:

auto: Enables the portlet height to grow with the size of the content.

Integer: Sets the fixed height of the portlet in pixels.

searchButtonImage

Specifies an image to use for the Search button. (Optional)

Set to one of the following:

  • A relative path for an image hosted by the Oracle SES portlet such as /images/custom/search_btn.gif. You must configure resource proxy on the midtier of the Oracle Portal instance that is consuming the Oracle SES portlet. See "Configuring Resource Proxying" in the Oracle Application Server Portal Configuration Guide.

  • An absolute URL that points to an image located on another system, which must be accessible to portal end users.

Add any image files to the /images/custom portlet deployment directory. No other locations are supported.

searchInputBoxSize

Specifies the width of the search input text box.

  • Enter an integer, such as 50, to indicate characters.

  • Append a px suffix to the integer, such as 350px, to indicate pixels.

secureContentSearch

Controls access to secure data sources:

  • true: Enables secure search.

  • false: Enables public search only. (Default)

secureMode

Controls authentication of end users. You can set the following values:

  • 2: End users are not prompted for their credentials.(Default)

  • 3: End users must provide credentials. Use this setting when the end-user authentication for secure search has been set to Require login for public and secure content on the Global Settings - Query Configuration page.

useDefaultAppHtml

Controls use of advanced result configuration settings:

  • true: Enables advanced result configuration for the Oracle SES portlet. If you are using separate but connected search box and search results portlets, then set this parameter to true for both of them. When advanced result configuration is enabled, users of the secure portlet can configure fewer display options.

  • false: Disables advanced result configuration. (Default)

Advanced result configuration is enabled in the Oracle SES Administration GUI on the Configure Search Result List page.

wiringKey

Connects portlets using a shared key. (Optional)

Enter a unique key string value, such as tL2mZX8sjQ4k or NYSalesDepA12.

A key is recommended when multiple pairs of connected portlets share the same Portal page.

Supporting Result List Customizations

Oracle SES supports result list customizations for portals and for other search interfaces. You can choose the attributes returned by a query and format the results using a custom XSLT style sheet.

To support result list customizations in a secure portlet: 

  1. If you have not done so, customize the results list as described in "Customizing the Appearance of Search Results".

  2. Open portlet.xml in an XML or text editor.

  3. Set the useDefaultAppHtml parameter to true for the portlets that support result list customizations. This is either SESPortlet or both the SearchBox and SearchResults portlets.

  4. Restart the middle tier as described in "Restarting the Oracle SES Middle Tier".

See Also:

The Extensible Stylesheet Language Family (XSL) at http://www.w3.org/Style/XSL/

Supporting Multiple Instances of a Portlet Type

Under some circumstances, you might want to have different initialization parameter settings for different instances of the same portlet type. For example, you might want to have two SearchBox portlets on different Portal pages, but with different heights. Or you might want to have multiple instances of SESPortlet, with some instances displaying default results and other instances showing Advanced Result List Customization results.

To change the configuration of a second instance of a portlet type: 

  1. Open portlet.xml in an XML or text editor.

  2. Copy the <portlet> element for the existing instance of the portlet type.

  3. Enter new values for <portlet-name> and <display-name>.

  4. Make whatever other changes you want to the initialization parameter settings, then save the file.

  5. Restart the Oracle SES midtier, as described in "Restarting the Oracle SES Middle Tier".

The two portlet definitions appear as distinct choices when adding portlets to the Portal page region.

Restarting the Oracle SES Middle Tier

Restart the Oracle SES middle tier to enable the changes made to portlet.xml.

On Linux and UNIX, from the ORACLE_HOME/bin directory, enter the following command:

./searchctl restart

On Windows, enter the following command:

searchctl restart

You can now register the portal with OracleAS Portal.

Configuring an OracleAS Portal for a Secure Portlet

The OracleAS Portal administrator must register a secure portlet. The administrator and end users can optionally set preferences.

Registering a Secure Portlet in OracleAS Portal Tasks

As an OracleAS administrator, you must register Oracle SES as a Portlet provider and create a Portlet page that contains a secure portlet.

To register Oracle SES as a portlet provider: 

  1. Log on to OracleAS Portal.

  2. Click the Navigator link.

  3. Click the Providers tab.

  4. Click the Registered Providers link.

  5. Click the Register New… Provider link.

  6. Enter a name for the provider and select WSRP from the Implementation Style box. Click Next.

  7. Enter the Oracle SES portlet WSDL URL in the text box, then click Next.

    http://HostName:PortNumber/sesPortlet/portlets/WSRPBaseService?WSDL

    Where HostName and PortNumber are the host name and port number of the Oracle SES instance.

  8. Click Finish.

  9. Click OK to complete registration of portlet provider.

The following error can occur when registering the portlet:

HTTP transport error : java.lang.NullPointerException

If you encounter this error:

  • Confirm that the portlet WSDL URL that you entered during registration is correct.

  • If Oracle Portal 10.1.4 uses Oracle Database 10g Release 2, then install Portal patch 5009567.

To add a secure portlet to a Portlet page: 

  1. Click the Page groups tab in OracleAS Portal.

  2. Click the Create New… Page Group link.

  3. Enter a display name. Click Create.

  4. Click Add Portlet.

  5. Click Portlet Staging Area.

  6. Click the link that shows the provider name, as defined in the preceding procedure.

  7. Click one of the following links:

    SES Portlet: Displays the full portlet which contains both the search box and search results.

    SearchBox Portlet: Displays the search box, source groups, and alternate keywords.

    SearchResults Portlet: Displays the result list, suggested links, and pagination links.

  8. Click OK.

    The portlet is now added to the portal page.

Using the Portal User Interface to Change Preferences

You can set default values for certain user preferences by using the Edit Defaults page. These settings affect end users who have not yet personalized their portlet; they do not overwrite the user settings for portlets that have already been personalized.

These are among the configurable preferences for a secure portlet:

  • Number of search matches displayed in a portlet view

  • Displaying or hiding the date and author

  • Listing source groups in a drop-down list or in tabbed links

  • Opening links in a new window

  • Displaying a gray line between search results

To change the default preferences for a secure portlet: 

  1. Log on to OracleAS Portal as the administrator.

  2. Edit the Portal page containing the Oracle SES portlet as desired.

  3. Click the pencil icon in the upper left corner to display the Edit Defaults page.

  4. Make the desired changes.

  5. Click OK to save the changes.

End users can also set default values for certain user preferences from the Edit page. These preferences depend on the display mode of the portlet and certain initialization parameter settings in the portlet.xml file.

Note:

In previous releases, the base path of Oracle SES was referred to as ORACLE_HOME. In Oracle SES release 11g, the base path is referred to as ORACLE_BASE. This represents the Software Location that you specify at the time of installing Oracle SES.

ORACLE_HOME now refers to the path ORACLE_BASE/seshome.

For more information, see "Conventions".