Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle WebCenter Interaction
10g Release 3 (10.3.0.1)

Part Number E14107-02
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

9 Managing Search

This section describes how to implement search for documents that reside in the Knowledge Directory, in communities, or in the collection of crawled links.

Customizing Search Service Behavior

This section discusses the following topics:

Search Result Types

You can limit your search to particular types of objects.

Result Type Description
Documents Returns documents from the portal Knowledge Directory.
Knowledge Directory Folders Returns folders from the portal Knowledge Directory.
Users Returns portal users.
Communities Returns communities.
Community Pages Returns pages in a community
Portlets Returns portlets.
Collaboration Items Returns documents, discussions, and task lists from Oracle WebCenter Collaboration.
Publisher Items Returns documents from Publisher.

Search Results Sorting Options

You can specify how your search results are sorted.

Option Description
Relevance Displays your results according to how closely they match your search query.

Note: Best bets are only shown in search results when sorting by relevance.

Last Modified Date Displays your results in the order in which they were most recently edited. The result that was modified most recently will display first.
Folder Groups your results by the folders in which they are stored and displays a list of the folders that contain search results.
Object Type Groups your results by type of object (such as documents, users, communities, or portlets) and displays a list of the types of objects returned by your search.

About Best Bets and Top Best Bets

Best bets associate specific search phrases (specified by the portal administrator) with a set of search results. When end users enter a search query that matches a best bet search phrase, the best bet results appear as the first results in the relevance-ranked result list. Additionally, users can choose to go directly to the highest ranking best bet, the top best bet, instead of seeing the normal search results. For example, the top best bet for the term “HR” might be the Human Resources community. If users use the top best bet feature, they go directly to the Human Resources community instead of seeing all search results for the term “HR.”

Note:

  • Best bets are not case-sensitive.

  • Best bets apply only to the portal banner search box and search portlet. Best bets are not used by other portal search interfaces, such as advanced search or object selection search.

  • Users go to the top best bet (for example, a community) only if they have at least Read access to it. If they do not, they see the list of search results to which they do have access.

  • The phrase “Best Bet” appears next to each best bet result to inform the user that the result has been judged especially relevant to the query.

Creating Best Bets

Best bets associate specific search phrases (specified by the portal administrator) with a set of search results. When end users enter a search query that matches a best bet search phrase, the best bet results appear as the first results in the relevance-ranked result list. Additionally, users can choose to go directly to the highest ranking best bet, the top best bet, instead of seeing the normal search results. For example, the top best bet for the term “HR” might be the Human Resources community. If users use the top best bet feature, they go directly to the Human Resources community instead of seeing all search results for the term “HR.”

To access the Search Results Manager you must have the following rights:

  • Access Administration activity right

  • Access Utilities activity right

  • Access Search Results Manager activity right

Note:

  • Best bets are case-insensitive.

  • You can create hundreds of best bets, each mapping to a maximum of 20 results.

  • Since best bets are handled by the Search Service and are not managed portal objects, best bets do not migrate from development to production environments; you must re-create them in the production environment.

  1. Click Administration.

  2. From the Select Utility list, select Search Results Manager.

  3. Launch the Best Bet Editor by clicking New Best Bet.

  4. Complete the best bet settings as described in the online help.

Users who search for the phrase you specified now see the best bets you created. Users can go directly to the top best bet by using the top best bet operator (>) in their search or by clicking rather than Search.

Note:

For information on how to enable this button using the Search tag, see the Oracle Fusion Middleware Web Service Developer's Guide for Oracle WebCenter Interaction, which is located on the Oracle Technology Network at http://www.oracle.com/technology/documentation/bea.html.

How Banner Field Settings Affect Search Results

When a user enters a query into a search box in the portal, the portal searches the properties specified on the Banner Fields page of the Search Results Manager and ranks those results based on the specified weighting settings.

Note:

Banner field settings apply to all searches: search from the portal banner, advanced search, object selection search, and any other portal search interfaces.

The default banner field properties are Name, Description, and Full-Text Content. However, you can also add other properties, such as Keyword, Department, or Author, to further refine the search results.

Another way of controlling the search results is by modifying the relevance weight for banner field properties. Overweighting a property increases its relevancy ranking; and underweighting it decreases it. For example, you can manipulate the search to first return documents whose content matches the search string (by overweighting the Full-Text Content property) followed by documents whose name matches the search string (by underweighting the Name property). When users type widgets, documents with widgets in the content appear first in a relevance-ranked search result; they are followed by documents or files with widgets in their names.

Controlling Search Results with Banner Fields and Weighting

When a user enters a query into a search box in the portal, the portal searches the properties specified on the Banner Fields page of the Search Results Manager and ranks the results based on the specified weighting settings. The default banner field properties are Name, Description, and Full-Text Content, with a high weight applied to Name. However, you can add other properties (such as Keyword, Department, or Author) and change the weighting to further refine the search results.

To access the Search Results Manager you must have the following rights:

  • Access Administration activity right

  • Access Utilities activity right

  • Access Search Results Manager activity right

Note:

Since banner field settings are a Search Service setting and not managed portal objects, the settings do not migrate from development to production environments; you must re-create them in the production environment.
  1. Click Administration.

  2. From the Select Utility list, select Search Results Manager.

  3. Click the Banner Fields page.

    The Banner Fields page displays the properties that the portal searches. The following information is displayed for each banner field.

    Column Description
    Property The property on the search banner.
    Percent Weight The proportion of the weight assigned to the property field.
    Weight The relevance ranking of the property field. Type in a weight for each property field. If you want to attach more weight to a particular property field, increase the weight number.

  4. Add, edit, or delete banner fields to improve search results.

    • To add a new property field and set its weight:

      1. Click Add Field.

        New fields appear.

      2. From the Property list, select the property field you want to add.

      3. Set the weight by typing a number in the text box in the Weight column.

    • To delete a property field, select it and click the Delete icon.

    • To remove any customizations you have made, click Restore Defaults.

    • To change the weight of a property field, type a number in the text box in the Weight column.

      The values in the Percent Weight column are automatically updated when you change the value in the Weight column.

About Spell Correction for Searches

Automatic spell correction is applied to the individual terms in a basic search when the terms are not recognized by the Search Service. Spell correction is not applied to quoted phrases.

For example, if a user queries for portel server but the term “portel” is unknown to the Search Service, items matching the terms “portal” and “server” would be returned instead. The same applies to Internet Style mode and query operators mode. So, for instance, a search for portel <NEAR> server would return documents containing the terms “portal” and “server” in close proximity, but only if there are no matches for “portel” and “server” in close proximity.

Automatic spell correction is enabled by default. You can disable it from the Search Results Manager in the administrative portal user interface. Users can disable spell correction on a per-search basis by using the <WORD> operator.

Enabling and Disabling Spell Correction for Searches

Automatic spell correction is applied to the individual terms in a basic search when the terms are not recognized by the Search Service. Spell correction is not applied to quoted phrases.

To access the Search Results Manager you must have the following rights:

  • Access Administration activity right

  • Access Utilities activity right

  • Access Search Results Manager activity right

Note:

Spell correction is enabled by default.
  1. Click Administration.

  2. From the Select Utility list, select Search Results Manager.

  3. Click the Thesaurus and Spell Correction page.

  4. Enable or disable spell correction.

    • To enable spell correction, select the Apply Spell Correction check box.

    • To disable spell correction, clear the Apply Spell Correction check box.

About the Search Thesaurus

The Search Service allows you to create a thesaurus (or synonym list), load it into the server, and enable thesaurus expansion for all user queries. Thesaurus expansion allows a term or phrase in a user's search to be replaced with a set of custom related terms before the actual search is performed. This feature improves search quality by handling unique, obscure, or industry-specific terminology.

For example, with conventional keyword matching, a search for the term “web applications” might not return documents that discuss portlets or web services. However, by creating a thesaurus entry for “web applications,” it is possible to avoid giving users zero search results because of differences in word usage. The entries allow related terms or phrases to be weighted for different contributions to the relevance ranking of search results. For example, “web applications” is not really a synonym for web services, so a document that actually contains web applications should rank higher than one that contains web services.

The entries are lower-case, comma-delimited lists of the form:

web applications,portlets,web services[0.5]

In this example, the number [0.5] corresponds to a non-default weighting for the phrase web services.

Thesaurus entries can be created to link closely related terms or phrases, specialized terminology, obsolete terminology, abbreviations and acronyms, or common misspellings. The expansion works by simply replacing the first term in an entry with an OR query consisting of all the terms or phrases in the entry. The weights are then taken into consideration when matching search results are ranked.

The thesaurus expansion feature is best used for focused, industry- or domain-specific examples. It is not intended to cover general semantic relationships between words or across languages, as with a conventional paper thesaurus. Although the Search Service thesaurus expansion can definitely improve search quality, adding entries for very general or standard terms can actually degrade search quality if it leads to too many search result matches.

About the Thesaurus File

The thesaurus is a comma-delimited file, in which each line represents a single thesaurus entry.

The first comma-delimited element on a line is the name of the thesaurus entry. The remaining elements on that line are the search tokens that should be treated as synonyms for the thesaurus entry. Each synonym can be assigned a weight that determines the amount each match contributes to the overall query score. For example, a file that contains the following two lines defines thesaurus entries for couch and dog:

couch,sofa[0.9],divan[0.5],davenport[0.4]
dog,canine,doggy[0.85],pup[0.7],mutt[0.3]

Searches for couch generate results with text matching terms couch, sofa, divan, and davenport. Searches for dog generate results that have text matching terms dog, canine, doggy, pup, and mutt. In the example shown, the term dog has the same contribution to the relevance score of a matching item as the term canine. This is equivalent to a default synonym weighting of 1.0. In contrast, the presence of the term pup contributes less to the relevance score than the presence of the term dog, by a factor of 0.7 (70%).

The example thesaurus entries constitute a complete comma-delimited file. No other information is needed at the beginning or the end of the file. Entries can also contain spaces. For example, a file that contains the following text creates a thesaurus entry for New York City:

new york city,big apple[0.9],gotham[0.5]

Searches for the phrase “new york city” will return results that also include results containing “big apple” and “gotham.” Thesaurus expansion for phrase entries only occurs for searches on the complete phrase, not the individual words that constitute the phrase. Similarly, the synonym entries are treated as phrases and not as individual terms. So while a search for “new york city” returns items containing “big apple” and “gotham,” a search for new (or for york, or for city, or for “new york”) will not. Conversely, an item that contains big or apple but not the phrase “big apple” will not be returned by a search for “new york city.”

Comma-delimited files support all UTF8-encoded characters; they are not limited to ASCII. However, punctuation should not be included. For example, if you want to make ne'er-do-well a synonym of wastrel, replace the punctuation with whitespace:

wastrel,ne er do well[0.7]

This matches documents that contain ne'er-do-well, ne er do well or some combination of these punctuations and spaces (such as ne'er do well). If you want your synonym to match documents that contain neer-do-well, which does not separate the initial ne and er with an apostrophe, you must include a separate synonym for that, such as:

wastrel,ne er do well[0.7],neer do well[0.7]

Comment lines can be specified by beginning the line with a “#”:

# furniture entries 
couch,sofa[0.9],divan[0.5],davenport[0.4]
#chair,stool[5.0]
# animal entries
dog,canine[0.9],doggy[0.85],pup[0.7],mutt[0.3]

In this example, the Search Service parses two thesaurus entries: couch and dog. There will be no entry for chair.

These examples are of entries that contain only ASCII characters. This utility supports non-ASCII characters as well, as long as they are UTF8-encoded.

Note:

Some editors, especially when encoding UTF-8, insert a byte order mark at the beginning of the file. Files with byte order marks are not supported, so remove the byte order mark before running the customize utility.

A CDF thesaurus file can have at most 50,000 distinct entries (lines). Each entry can have at most 50 comma-delimited elements (including the name of the entry). If either of these limits are exceeded, the customize utility will exit with an appropriate error message.

Creating and Implementing the Synonym List for the Thesaurus

After you create the file, you load it into the Search Service.

  1. Create a comma-delimited, UTF-8 file containing the desired thesaurus entries.

    For details on how to format entries, see About the Thesaurus File.

    Note:

    Thesaurus entries must be in lower-case.
  2. Stop the Search Service.

    The comma-delimited file is converted to a binary format in the next step. The conversion removes and replaces certain files used by the Search Service, and this removal and replacement cannot be done while the Search Service is running.

  3. At a command prompt, run the customize utility.

    The utility must be run from a command prompt, taking command-line arguments for the thesaurus file and the path to the Search Service installation:

    customize -r thesaurus_file SEARCH_HOME
    

    Replace thesaurus file with the path to the thesaurus file and replace SEARCH_HOME with the root directory of the Search Service installation.

    For example, if your thesaurus file is located in \temp and your Search Service was installed in the default

    location, type:
    customize -r \temp\thesaurus.cdf C:\bea\alui\ptsearchserver\10.3.0
    

    The files in SEARCH_HOME\common are removed and replaced by files of the same name, though their contents now represent the mappings created by the customize utility.

  4. Restart the Search Service.

    The files produced by the customize utility are loaded when the Search Service starts.

If you have not already done so, you must enable the thesaurus in the Search Results Manager.

Enabling the Search Thesaurus

The Search Service allows you to create a thesaurus (or synonym list), load it into the server, and enable thesaurus expansion for all user queries. Thesaurus expansion allows a term or phrase in a user's search to be replaced with a set of custom related terms before the actual search is performed. This feature improves search quality by handling unique, obscure, or industry-specific terminology.

To access the Search Results Manager you must have the following rights:

  • Access Administration activity right

  • Access Utilities activity right

  • Access Search Results Manager activity right

  1. Click Administration.

  2. From the Select Utility list, select Search Results Manager.

  3. Click the Thesaurus and Spell Correction page.

  4. Select Use the Thesaurus.

If you have not already done so, you must create the synonym list in the database.

Reverting to the Default Thesaurus Mappings

The customize utility has a command-line mode for reverting to the set of mappings files that shipped with the Search Service (removing any thesaurus customizations).

  1. Stop the Search Service.

  2. At a command prompt, run the customize utility.

    The utility must be run from a command prompt, taking a command-line argument for the path to the Search Service installation:

    customize -default SEARCH_HOME
    

    Replace SEARCH_HOME with the root directory of the Search Service installation.

    For example, if your Search Service was installed in the default location, type:

    customize -default C:\bea\alui\ptsearchserver\10.3.0
    

    The files in SEARCH_HOME\common are removed and replaced with the original thesaurus file contents.

  3. Restart the Search Service.

    The files produced by the customize utility are loaded when the Search Service starts.

If you no longer want to use thesaurus expansion, disable the thesaurus in the Search Results Manager.

Customizing Categorization of Search Results

Users can use the Sort By list on the search results page to sort results by object type or by folder location in the Knowledge Directory or Administrative Objects Directory. You can customize this list to include additional categories relevant for your users. For example, if you use a property in your portal documents named Region, you can customize the Sort By list to include Sort By Region: New England, Midwest, and so forth.

The first issue to consider when assessing whether categorizing search results by a particular property is a good idea is whether the property will be defined for a substantial percentage of all search results. For instance, if 90% of search results do not have the property defined, then when categorizing by that property, most everything will fall under “All Others”, and the categorization will not be very useful. For that reason, as a rule of thumb it is not generally recommended to add a custom categorization option for a property which is undefined for more than half of all documents and administrative objects.

The other issue to consider is whether the values for the property will make reasonable category titles. In order for categorization to work well for a property, each value should be a single word or a short noun phrase, for example, New England, Midwest, Product Management, Food and Drug Administration, and so forth. The values should not be full sentences or long lists of keywords, for example, “This content crawler crawls the New York Times finance section”. The entire contents of the property value for each item will be considered as a single unit for the purposes of categorization, so it will look odd if a full sentence is returned as a category title.

The first step in the process of adding a new categorization option is to ensure that documents and objects include the property you want to use to sort by category. See Mapping Source Document Attributes to Portal Properties Using the Global Document Property Map and Associating Properties with Portal Objects Using the Global Object Property Map.

You must also ensure that the property that defines the category for sorting has the following configuration:

  • Supported for use with documents

  • Visible in the user interface

  • Searchable

  • Mandatory

    Since the search results categorization will only be valuable if there are many items with defined values for the property, and will be of maximum value if everything has a value for the property.

  • Named appropriately

Enabling Custom Search Results Sorting

You can enable sorting by custom properties by editing the portalconfig.xml file.

  1. Get the object ID of the properties you want to configure for custom sorting.

    1. Navigate to the property in the Administrative Objects Directory.

    2. Click the property to open it.

    3. Click the Names and Descriptions page and copy the object ID.

  2. Open portalconfig.xml in a text editor and find the <Search> section.

  3. Add the following entries to the <Search> section:

    <CategoryName_1 value="CategoryName"/>
    <CategoryField_1 value="PTObjectID"/> 
    

    Replace CategoryName with the name you want to appear in the Sort By list (for example, Region).Replace ObjectID with the integer that identifies the property object.

  4. To add more entries, repeat Step 3, adding analogous tags named CategoryName_2, CategoryField_2, CategoryName_3, CategoryField_3, and so forth.

    Note:

    The Category tags must be numbered consecutively without skipping. For example, if there is a CategoryName_3 tag, it must be preceded by tags for CategoryName_1 and CategoryName_2.

About Grid Search

Grid search consists of shared files (for example, C:\cluster) and search nodes. When you start up the Search Service, it looks at the cluster.nodes file in the shared files location to determine the host, port, and partition of each node in the cluster. It monitors and communicates the availability of the search nodes and distributes queries appropriately.

The Search Service also automatically repairs and reconciles search nodes that are out of sync with the cluster. At startup, nodes will check their local TID against the current cluster checkpoint and index queues. If the current node is out-of-date with respect to the rest of the cluster, it must recover to a sufficiently current transaction level (at or past the lowest cluster node TID) before servicing requests for the cluster. Depending upon how far behind the local TID is, this operation may require retrieval of the last-known-good checkpoint data in addition to replaying queued index requests.

Although the Search Service performs many actions automatically to keep your cluster running properly, there are some maintenance and management tasks you perform manually to ensure quality search in your portal.

About Checkpoints

A checkpoint is a snapshot of your search cluster that is stored in the cluster folder (for example, C:\bea\alui\cluster), a shared repository available to all nodes in the cluster. When initializing a new cluster node, or recovering from a catastrophic node failure, the last known good checkpoint will provide the initial index data for the node's partition and any transaction data added since the checkpoint was written will be replayed to bring the node up to date with the rest of the cluster.

You manage checkpoints on the Checkpoint Manager page of the Search Cluster Manager. You can perform the following actions with the Checkpoint Manager:

  • Manually create an individual checkpoint or schedule checkpoints to be automatically created on a periodic basis.

  • Restore your search collection from a checkpoint.

Since checkpoint data is of significant size, limit the number of checkpoints maintained by the system. Specify how many checkpoints to keep on the Settings page of the Search Cluster Manager.

About Search Cluster Topology

Your search cluster is made up of one or more partitions, each of which is made up of one or more nodes. As your search collection becomes larger, the collection can be partitioned into smaller pieces to facilitate more efficient access to the data. As the Search Service becomes more heavily utilized, replicas of the existing partitions, in the form of additional nodes, can be used to distribute the load. Additional nodes also provide fault-tolerance; if a node becomes unavailable, queries are automatically issued against the remaining nodes.

Note:

If a partition becomes unavailable, the cluster will continue to provide results; however, the results will be incomplete (and thus indicated in the query response).

You manage the partitions and nodes in your search cluster on the Topology Manager page of the Search Cluster Manager. You can perform the following actions with the Topology Manager:

  • Add or delete a node.

  • Repartition the cluster (add or delete partitions).

    Note:

    Adding a partition to the cluster requires redistributing of potentially hundreds of thousands of documents.
  • Assign a node to a different partition.

About Search Logs

Search logs are kept for the search cluster as well as for each node in the search cluster. The cluster logs are stored in the \cluster\log folder, for example, C:\bea\alui\cluster\log\cluster.log. The cluster logs include cluster-wide state changes (such as cluster initialization, node failures, and node recoveries), errors, and warnings.

The node logs are stored in the node's logs folder, for example, C:\bea\alui\ptsearchserver\10.3.0\node1\logs. There are two kinds of node logs: event logs and trace logs. Event logs capture major node-local state changes, errors, warnings, and events. Trace logs capture more detailed tracing and debugging information.

There are several ways to view the logs:

  • You can open the log file in a text reader.

  • You can view search logging through PTSpy.

  • You can set up another OpenLog listener to receive logging information.

A new cluster log is created with each new checkpoint. The log that stores all activity since the last checkpoint is called cluster.log. When a new checkpoint is created, the cluster.log file is saved with the name checkpoint.log, for example, 0_1_5116.log.

About the Command Line Admin Utility

The Command Line Admin Utility lets you to perform the same functions you can perform in the Search Cluster Manager as well as change the run level of the cluster and purge and reset the search collection.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe). Invoking the command with no arguments displays a summary of the available options:

% $RFHOME/bin/native/cadmin
Usage: cadmin <command> [command-args-and-options] [--cluster-home <CLUSTER_HOME>]

This Command Line Admin Utility lets you perform the following actions:

Requesting Search Cluster Status

You can use the Command Line Admin Utility to view the status of your search cluster.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

  • Run the status command to display the status of the cluster.

    % cadmin status --cluster-home=/shared/search

    By default, the status command displays a terse, one-line summary of the current state of the cluster:

    2005-04-22 13:54:13 checkpoint_xxx 0/1/198 0/1/230 impaired
    
  • Run the status command with the verbose flag to display the full set of information, including the status of every node in the cluster.

    % cadmin status --verbose --cluster-home=/shared/search

    2005-04-22 13:54:13 /shared/search checkpoint_xxx
    cluster-state: impaired
    cluster-tid: 0/1/198 0/1/230
    partition-states: complete impaired
    node p0n0: 0 192.168.1.1 15244 0/1/198 0/1/460 run
    node p0n1: 0 192.168.1.2 15244 0/1/198 0/1/460 run
    node p1n0: 1 192.168.1.3 15244 0/1/198 0/1/230 run
    node p1n1: 1 192.168.1.4 15244 0/1/100 0/1/120 offline
    
  • Run the status command with the period flag to repeatedly emit status requests at a specified interval.

    % cadmin status --period=10 --count=5

    2005-04-22 13:54:13 checkpoint_xxx 0/1/198 0/1/230 impaired
    2005-04-22 13:54:23 checkpoint_xxx 0/1/198 0/1/230 impaired
    2005-04-22 13:54:33 checkpoint_xxx 0/1/198 0/1/230 impaired
    2005-04-22 13:54:43 checkpoint_xxx 0/1/198 0/1/230 impaired
    2005-04-22 13:54:53 checkpoint_xxx 0/1/400 0/1/428 complete
    

Requesting Search Cluster Status for a Particular Node

You can use the Command Line Admin Utility to request information about specific nodes within the cluster.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

  • Run the nodestatus command to display the status of a particular node.

    % cadmin nodestatus p0n0 p1n0

    This displays the same type of information that is displayed as part of the verbose cluster status request:

    node p0n0: 0 192.168.1.1 15244 0/1/198 0/1/460 run
    node p1n0: 1 192.168.1.3 15244 0/1/198 0/1/230 run
    
  • Run the nodestatus command with the period flag to repeatedly emit status requests at a specified interval.

    % cadmin nodestatus p0n0 p1n0 --period=10

    2005-04-22 13:54:13 p0n0 0 192.168.1.1 15244 0/1/198 0/1/460 run
    2005-04-22 13:54:13 p1n0 0 192.168.1.1 15244 0/1/198 0/1/460 run
    2005-04-22 13:54:23 p0n0 0 192.168.1.1 15244 0/1/198 0/1/460 run
    2005-04-22 13:54:23 p1n0 0 192.168.1.1 15244 0/1/198 0/1/460 run
    

Changing the Run Level of the Cluster

You can use the Command Line Admin Utility to modify the run level of the cluster, or of individual nodes within the cluster. For example, you might want to place nodes in standby mode prior to changing cluster topology or shutting them down.

Transitioning from standby to any of the operational modes (recover, readonly, stall, run) will validate the node's state against the cluster state and will trigger a checkpoint restore if one is warranted. Transitions to readonly or offline modes are also potentially useful: readonly mode halts incorporation of new index data on a node; offline mode will cause the search server to exit.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

  • To set run level of p0n0 and p1n0 to standby:

    % cadmin runlevel standby p0n0 p1n0

  • To set run level of the entire cluster to run (affects only non-offline nodes):

    % cadmin runlevel run

Initiating a Cluster Checkpoint

A checkpoint is a snapshot of your search cluster that is stored in the cluster folder (for example, C:\bea\alui\cluster), a shared repository available to all nodes in the cluster. When initializing a new cluster node, or recovering from a catastrophic node failure, the last known good checkpoint will provide the initial index data for the node's partition and any transaction data added since the checkpoint was written will be replayed to bring the node up to date with the rest of the cluster.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

Reloading from a Checkpoint

You can use the Command Line Admin Utility to reload your cluster from a saved checkpoint.

  1. Run the restore command.

    % cadmin restore

Since restoring from a checkpoint is a time-consuming process, the admin utility displays its progress.

Example 9-1 Output from Restoring from a Checkpoint

Restoring cluster from \\cluster_home\checkpoint_xxx
Node p0n0 retrieving data
Node p0n1 retrieving data
0%..10%..20%..30%..40%..50%..60%..70%..80%..90%..100%
Node p0n0 restarted
Node p0n1 restarted
Restoration complete

Changing Cluster Topology

You can use the Command Line Admin Utility to add or remove nodes from the search cluster or repartition the search cluster.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

  1. Run the topology command.

    % cadmin topology new.nodes

  2. Change the cluster.nodes file.

    • To add new nodes to the search cluster (for failover capacity), install a new node, and edit the cluster.nodes file to include the node as a peer on an existing partition.

      Issue a “soft reset” to the cluster through the command line utility, which causes all nodes to re-examine the cluster topology file and thus recognize the new node. When the new node receives a soft reset, it recognizes that it needs to catch up to the rest of the cluster and begins the automated index recovery process from the last checkpoint.

    • To repartition the cluster, edit the number of partitions in the cluster.nodes file. You will be asked to confirm the action and the admin utility will confirm that a checkpoint exists before performing the repartitioning operation.

Since changing cluster topology can be a time-consuming process, the admin utility displays its progress.

Example 9-2 Output from Adding and Removing Nodes

Current topology:
<contents of current cluster.nodes file>
New topology:
<contents of new.nodes file>
Nodes to add: p0n2, p1n2, p2n2
Nodes to remove: p0n0, p1n0, p2n0
Is this correct (y/n)? y
Applying changes…
p0n2 has joined
p2n0 has left
...
Changes applied successfully

Example 9-3 Output from Repartitioning the Cluster

Current topology:
<contents of current cluster.nodes file>
New topology:
<contents of new.nodes file>
Nodes to add: p3n0, p3n1
Is this correct (y/n)? y
CAUTION: the requested changes require repartitioning the search collection
The most recent checkpoint is checkpoint_xxx from 2004-04-22 16:00:00
Is this correct (y/n)? y
Repartitioning from 3 partitions into 4
0%
5%
<progress messages>
100%
Repartitioning successful
Applying changes…
p0n2 has joined
p2n0 has left
...
Changes applied successfully

If the repartition fails, the search collection leaves the cluster in its original state, if at all possible, and provides information about the failure. The cluster.nodes file is rolled back to the previous state after making sure that the last-known good checkpoint refers to an un-repartitioned checkpoint directory.

Aborting a Checkpoint or Reconfiguration Operation

You can abort a long-running checkpoint or cluster reconfiguration operation by exiting from the command line utility.

  • To exit from the command line utility, type CTRL+C.

    The cluster will be restored to its state prior to attempting the checkpoint or topology reconfiguration.

    In the case of a checkpoint operation, the utility sends a “checkpoint abort” command to the checkpoint coordinator to cleanly abort the checkpoint create/restore operation.

    In the case of a cluster reconfiguration, the utility restores the original cluster.nodes file and initiates a soft restart of the affected cluster nodes to restore the cluster to its previous configuration.

Purging and Rebuilding the Search Collection

You can purge and rebuild the contents of the search collection. You might want to do this in a dire situation where the contents of the cluster are corrupted beyond repair and good checkpoints are not available for recovery.

  1. Put all cluster nodes in standby mode.

  2. Purge the collection.

  3. Rebuild the collection.

  4. If your portal deployment includes Oracle WebCenter Collaboration, rebuild the Oracle WebCenter Collaboration index.

Purging the Search Collection

You can purge the contents of the search collection. You might want to purge the cluster in staging or development systems, or if you want to clean out the search collection without re-installing all the nodes. Purging (and rebuilding) the search collection may also be useful in a dire situation where the contents of the cluster are corrupted beyond repair and good checkpoints are not available for recovery.

As a safeguard against purging the collection by accident, all cluster nodes must be in standby mode.

The Command Line Admin Utility is located in bin\native folder in the Search Service installation folder (for example, C:\bea\alui\ptsearchserver\10.3.0\bin\native\cadmin.exe).

By default, the checkpoints and index queue are left in place. This allows you to rebuild the local index on a node where the archive appears to be corrupted. You can add a flag to the command to remove the checkpoints.

  • To purge the search collection, but keep checkpoints:

    % cadmin purge

    As a safeguard against purging the collection by accident, you must confirm the action before the purge command is sent out.The purge command causes a node to generate empty archive collections (document, spell, and mappings) and perform a soft-restart to load them into memory. Before reloading, the admin utility updates the checkpoint files in the shared repository to prevent the nodes from automatically reloading from an existing checkpoint.

  • To purge the search collection and delete existing checkpoints:

    % cadmin purge --remove-checkpoints

Sometimes the purge command does not work properly, where it fails to purge the index files. During this scenario the search file structure gets tainted and the Search Service will not start up.If this occurs you receive an error similar to this:

Failed Unexpected exception while sending PURGE to searchserver01, Error during parsing: Failed -- purge failed on streetfighter01 This node should be shutdown, purged, and restarted manually.

At this point you will not be able to shut down, purge, or restart the Search Service. You must re-run the Oracle WebCenter Interaction installer. Select only the Search Service option and choose overwrite.

If you are purging the collection to correct a problem (for example if your collection was corrupted or you had to reinstall the Search Service), your next step is to rebuild the collection.

Rebuilding the Search Collection

Your search index might get out of sync with your database if, during the course of a crawl, the Search Service became unavailable or a network failure prevented an indexing operation from completing. Another possibility is that a Search Service with empty indices was swapped into an existing portal with pre-existing documents and folders.

To rebuild the search collection you must have the following rights:

  • Access Administration activity right

  • Access Search Results Manager activity right

The Search Service Manager lets you specify when and how often the Search Update Agent repairs your search index. Rather than synchronizing particular objects, the repair synchronizes all objects in the database with the search index. Searchable objects in the database are compared with IDs in the search index. If an object ID in the database is not in the search index, the Search Update Agent attempts to re-index the object; if an ID in the search index is not in the database, the Search Update Agent removes the object from the search index.

Run the Search Update Agent for purposes of background maintenance or complete repopulation of the search index.

  1. Configure the Search Service to repair itself.

    1. Click Administration.

    2. From the Select Utility list, choose Search Service Manager.

    3. Under Search Repair Settings, change Next Repair Date to a time in the past.

    4. Click Administration again.

  2. Wait one minute for the setting to update.

  3. Run one of the Search Update jobs in verbose mode.

    1. Open the Intrinsic Operations folder.

    2. Open one of the Search Update jobs.

      The Job Editor opens.

    3. Change the Logging Level to Verbose and click Finish.

      Note:

      Make note of the logging mode before you change it, so that you can change it back after the repair is complete.
    4. Select the job you just edited and click Run Once.

      By running the job this way, you avoid having to go back into the job and revert to the previous schedule settings.

  4. Ensure that the job is running in repair mode.

    1. Open the job you just created; it should be called something like Search Update 1 — Run Once.

      The Job Editor opens.

    2. Click the Job History page.

    3. Click the job name.

      The job log opens.

    4. Ensure that the job is running in repair mode.

      The second line of the job log should be similar to this:

      Mar 1, 2008 9:10:02 AM- PTIndexer.ctor : Indexing will extract at most 1000000 encoded bytes of text from each document.
      

      About half-way down the first page of the log you should see a message that should be similar to this:

      Mar 1, 2008 9:10:02 AM- Search Update Agent is repairing the directories...
      
  5. Reinstall the Search Service and select Overwrite the existing search index. For details on installing the Search Service, refer to the Installation Guide for Oracle WebCenter Interaction.

Rebuilding the Oracle WebCenter Collaboration Search Collection

Rebuilding reconciles data between the Oracle WebCenter Collaboration database and Search Service index. Since this is a lengthy and computationally expensive process, use the rebuild operation only when absolutely necessary.

To access the Collaboration Administration Utility you must have the following rights:

  • Access Administration activity right

  • Access Utilities activity right

  • Manage Collaboration activity right

  1. Click Administration.

  2. In the Select Utility list, click Collaboration Administration.

  3. Click the Search Service page.

  4. Click Rebuild Search Collection.

About the Search Update Job

The Search Update job performs the following actions on the search index: updates the index, releases expired locks on users and objects, and repairs the search index according to the Search Service Manager repair settings.

The Search Update job is located in the Intrinsic Operations administrative folder. The default frequency of the Search Update job is one hour, which is suitable for most portal deployments. If your search index is very large, the Search Update Agent might not be able to finish in one hour, so you should edit the frequency of the job.

How the Search Index is Updated

As users create, delete, and change objects in the portal, the search index gets updated. In some cases, the portal updates the search index immediately; in other cases, the search is not updated until the next time the Search Update Agent runs.

The following table describes the cases in which the search index is updated immediately (I) or updated by the Search Update Agent (SU).

Object Create Delete Move Change Name or Description Change Other Properties
Document I SU SU I I
Directory Folder I SU SU I SU
Administrative Folder I I I I I
Administrative Object I I I I I

Note:

If the Knowledge Directory preferences are set to use the search index to display browse mode, changes will not display until the Search Update Agent runs. The Knowledge Directory edit mode and the Administrative Object Directory display objects according to the database, and therefore show changes immediately.

About Providing Search Access to External Repositories with Federated Searches

Federated searches allow you to establish search relationships with other sources (including other portals, web sites, or custom databases). Federated searches provide end users a single interface and unified result set for searches over multiple Oracle WebCenter Interaction portals, as well as parallel querying of external internet and intranet-based search engines.

There are incoming and outgoing federated searches:

Search Web Services

Search web services allow you to specify general settings for your remote search repository, leaving the security settings to be set in the associated outgoing federated searches. This allows you to segregate access to your search repository through multiple outgoing federated searches.

If there is a non-portal repository that you want to search, Oracle or another vendor might have written a search web service to access it. If not, Oracle provides an IDK that enables you to write your own search web services in Java or .NET. For details, refer to the Oracle Fusion Middleware Web Service Developer's Guide for Oracle WebCenter Interaction, which is located on the Oracle Technology Network at http://www.oracle.com/technology/documentation/bea.html.

Note:

The settings for outgoing federated search objects will often be specific to the search web services that implement the searches. In these cases, the web services themselves provide the configuration options as Service Configuration Interface (SCI) pages.

Portal-to-Portal Searches

One Oracle WebCenter Interaction portal can request and/or serve content to another Oracle WebCenter Interaction portal. When you install the portal, the Public Access incoming federated search is created. This allows other Oracle WebCenter Interaction portals to search this portal as the Guest user.

To allow other search relationships, you must create new incoming or outgoing federated searches. Whether your portal is requesting or serving content, you and the other administrators involved need to agree upon the following issues prior to establishing federated searches:

  • Which portals will serve content?

  • Which portals will request content?

  • What portal identification name and password will be used to identify the portals?

    For every request issued, the requesting portal sends an ID and password to identify itself to the serving portal. You must enter the same ID and password in both the requesting portal's outgoing federated search and the serving portal's incoming federated search.

  • What content from the serving portal will be available to the requesting portal?

    If both portals share a common external database of users, such as an LDAP server or Active Directory domain, and those users have been imported into both portals, grant the shared users access to the appropriate content on the serving portal. This provides the greatest degree of content security without requiring any additional administrative work.

    If the portals do not share a database of user information, users from the requesting portal must impersonate users from the serving portal. Because impersonation is specified on a group basis (that is a group from the requesting portal is set to impersonate a user from the serving portal), you should create a different serving portal user for each requesting portal group that needs access to different content in the serving portal.

    Note:

    You should create new serving portal users specifically for the purpose of impersonation, then communicate the user names and what they can access to the administrator of the requesting portal.

    The serving portal can also allow unauthenticated users to search the portal as the Guest user.

After you and the other administrators involved have determined how this relationship will work, you are ready to establish your incoming or outgoing federated searches.

For an example of how requesting portal users can impersonate serving portal users to gain access to secured content, see Example of Impersonating Serving Portal Users.

To learn how multiple portals accessing the same user repository can share content, see Building a Composite Portal with Federated Searches.

Building a Composite Portal with Federated Searches

Multiple portals accessing the same user repository can share content. All portals involved in the relationship must import the same users and groups from a single user repository.

There are two scenarios for building a composite portal:

  • Multiple content portals each possess links to a large number of documents. A single user can visit the separate content portals, always with the same user name and password, and always receive access to the correct content.

    In this scenario, each portal acts as both a serving and a requesting portal.

  • One portal is set up as a master portal rather than a content portal. Through this master portal, users can access content from the various content portals.

    In this scenario, the master portal acts as the requesting portal, and the content portals act as the serving portals.

  • On each serving portal, the administrator creates an incoming federated search that includes the authentication sources that the serving portals share with the requesting portals.

    All users making requests to a serving portal need to be imported into the portal through one of these common authentication sources.

  • On each requesting portal, the administrator creates an outgoing federated search for each content portal, selecting No for Send portal authentication.

    Users will make the requests using their own user accounts.

Creating a Search Web Service

Before you create a search web service, you must:

  • Install the search provider on the computer that hosts the portal or on another computer

  • Create a remote server pointing to the computer that hosts the search provider (optional, but recommended)

To create a search web service you must have the following rights and privileges:

  • Access Administration activity right

  • Create Web Service Infrastructure activity right

  • At least Edit access to the parent folder (the folder that will store the search web service)

  • At least Select access to the remote server that the search web service will use

  1. Click Administration.

  2. Open the folder in which you want to store the search web service.

  3. In the Create Object list, click Web Service — Search.

    The Search Web Service Editor opens.

  4. On the Main Settings page, complete the following tasks:

    • Associate a remote server for the web service

    • Specify the path to the search provider

    • Specify time-out settings for the web service

    • Enable the web service

  5. Click the HTTP Configuration page and complete the following tasks:

    • Specify whether you want the content to display within the portal interface and whether the portal should transform JavaScript and CSS files

    • Specify whether the content should be gatewayed

  6. Click the Advanced URL Settings page and complete the following tasks:

    • If the web service requires search-specific configuration settings, specify the path to the configuration page

    • If the web service requires administrative configuration settings or user preferences that affect more than just this web service, specify the shared settings

  7. Click the Advanced Settings page and complete the following tasks:

    • Specify what general information, if any, you want this web service to pass to its associated federated searches

    • Specify how information from this web service is encoded

  8. Click the Authentication Settings page and complete the following task:

    • Specify what authentication information, if any, you want this web service to pass to its associated federated searches

  9. Click the Preferences page and complete the following task:

    • Specify, by name, the user preferences you want to send to the objects associated with the web service

  10. Click the User Information page and complete the following tasks:

    • If you want to send information mapped to user properties by default, select the desired properties

    • If you want to send other user information, specify the properties

  11. Click the Debug Settings page and complete the following task:

    • Enable desired error tracing

  12. Click the Properties and Names page and complete the following tasks:

The default security for this search web service is based on the security of the parent folder. You can change the security when you save this search web service (on the Security tab page in the Save As dialog box), or by editing this search web service (on the Security page of the Search Web Service Editor).

Portal administrators with at least Select access to this search web service can create outgoing federated searches based on the web service.

Allowing Other Portals to Search Your Portal

An incoming federated search allows other Oracle WebCenter Interaction portals to search your portal.

Before you create an incoming federated search, you must:

  • Agree upon a portal identification name and password with the administrator of the requesting portal.

  • If the users from the requesting portal do not exist in your portal, create one or more portal users that can be impersonated by users of the requesting portal.

To create an outgoing federated search you must have the following rights and privileges:

  • Access Administration activity right

  • Create Federated Searches activity right

  • At least Edit access to the parent folder (the folder that will store the federated search)

  • If the users from the requesting portal do not exist in your portal, at least Select access to the authentication sources or groups that include the impersonated users

  1. Click Administration.

  2. Open the folder in which you want to store the federated search.

  3. In the Create Object list, click Federated Search - Incoming.

  4. In the Portal identification name box, type the agreed upon name.

  5. In the Portal identification password box, type the agreed upon password.

  6. In the Password confirmation box, type the password again.

  7. In the Served links are valid for box, type the minimum number of minutes or which these results should be cached.

    After a requesting portal issues a search of your portal, the links returned by the search are stored for at least as long as you specify here. After this period has elapsed, the user on the requesting portal might need to re-issue the search.

  8. To allow unauthenticated users to search the portal as a guest, click the Allow unauthenticated users to search as the Guest user box.

  9. If the users from the requesting portal do not exist in your portal, select the authentication sources or groups that include the impersonated users.

    Incoming search requests include the name of a local portal user (that is, a user from the serving portal) to impersonate during the search. The request is honored only if the impersonated user is a member of one of the authentication sources or one of the groups you specify.

    • To add an authentication source, click Add Authentication Source, in the Choose Authentication Sources dialog box, select an authentication source, and click OK.

    • To add a group, click Add Group, in the Choose Groups dialog box, select a group, and click OK.

    • To delete an authentication source or a group, select it and click the Remove icon.

      To select or clear all of the authentication source or group boxes, select or clear the box to the left of Authentication Sources or Groups.

    • To toggle the order in which the authentication sources or groups are sorted, click Authentication Sources or Groups.

Providing Search Access to External Repositories with Outgoing Federated Searches

An outgoing federated search enables users of your portal to search other Oracle WebCenter Interaction portals or other external repositories.

Before you create an outgoing federated search, you must:

  • Create a search web service.

  • Agree upon a portal identification name and password with the administrator of the serving portal.

  • If your portal users do not exist in the serving portal, work with the serving portal user to determine the serving portal users that can be impersonated and what they can access.

To create an outgoing federated search you must have the following rights and privileges:

  • Access Administration activity right

  • Create Federated Searches activity right

  • At least Edit access to the parent folder (the folder that will store the federated search)

  • If your portal users do not exist on the serving portal, at least Select access to the groups that need to impersonate serving portal users

  1. Click Administration.

  2. Open the folder in which you want to store the federated search.

  3. In the Create Object list, click Federated Search - Outgoing.

    The Choose Web Service dialog box opens.

  4. Select the web service that provides the basic settings for your outgoing federated search and click OK.

    The Outgoing Federated Search Editor opens, displaying the Portal to Portal Settings page.

  5. If you are not searching another Oracle WebCenter Interaction portal, leave No selected.

    If you are searching another Oracle WebCenter Interaction portal:

    1. Next to Send portal authentication, select Yes.

    2. In the Portal identification name box, type the agreed upon name.

    3. In the Portal identification password box, type the agreed upon password.

    4. In the Password confirmation box, type the password again.

    5. If your portal users do not exist on the serving portal, under User Name Aliasing, map groups from your portal to users from the serving portal that they can impersonate:

      Note:

      When a requesting user tries to search a serving portal, the requesting portal examines the list of mapped groups from the top down; the first group in the list to which the requesting user belongs is used to determine what serving portal user the requesting user will impersonate. Therefore, groups with high levels of security should be mapped first (at the top of the list), so that requesting users are granted the highest level of security available to them.
      • Click Add Group, in the Select Group dialog box, select the groups you want to add and click OK.

      • To the far right of the group, click the Edit icon.

      • In the Use this user name alias column box, type the name of the serving portal user whom you want this group of requesting users to impersonate.

      • Click the Save icon to save the mapping.

        To delete a group, select it and click the Remove icon. To select or clear all of the group boxes, select or clear the box to the left of Members of this group.

After the administrator of the serving portal has set up the incoming federated search, your users can use federated search to search content from the other portal.

Example of Impersonating Serving Portal Users

This example shows how a search relationship might be set up between two separate portals.

The fictional company Servicor wants to share content with its fictional partner Requesticon. In this case, Servicor's portal is the serving portal, and Requesticon's portal is the requesting portal.

Configuring the Serving Portal

First, the administrator of the Servicor portal creates two portal users: Requesticon Engineer and Requesticon Executive. Both of these users are added to the portal group named Requesticon Visitors.

These users are then individually granted access to appropriate content on the Servicor portal. Requesticon Engineer is granted Read access to the Engineering, QA, and Product Management folders of the Servicor Knowledge Directory. Requesticon Executive is granted Read access to the Servicor Market and Investor Relations folders.

The administrator of the Servicor portal then sets up an incoming federated search. On the Main Settings page of the Incoming Federated Search Editor, the Servicor portal administrator includes the WCI Authentication Source and the group Requesticon Visitors. The WCI Authentication Source is included because the Requesticon Engineer and the Requesticon Executive users were both created in the portal; had they been imported through another authentication source, then that authentication source would need to be included instead. The Requesticon Visitors group is included here to prevent users of the requesting portal from attempting to impersonate any user other than Requesticon Engineer or Requesticon Executive.

With the serving portal configured this way, only requests issued by Requesticon Engineer and Requesticon Executive are answered, and only appropriate content is visible.

Configuring the Requesting Portal

On the Main Settings page of the Outgoing Federated Search Editor, the administrator of the Requesticon portal selects Yes for Send portal authentication. Then, under User Name Aliasing, the Requesticon portal administrator maps the group Executives to the Servicor user named Requesticon Executive and the group Engineers to the Servicor user named Requesticon Engineer. This way, all users that are members of the Engineers group impersonate Requesticon Engineer when issuing requests, and all users that are members of the Executives group issue requests as Requesticon Executive.

Note:

The Requesticon Engineer and Requesticon Executive exist only in the Servicor portal, not in the Requesticon portal; these users were created specifically for impersonation by Requesticon users.

When a requesting user tries to search a serving portal, the requesting portal examines the list of mapped groups from the top down; the first group in the list to which the requesting user belongs is used to determine what serving portal user the requesting user will impersonate. Therefore, groups with high levels of security should be mapped at the top of the list. The requesting portal administrator made sure to add the Executives group before the Engineers group so that if any user on the requesting portal is a member of both the Executives group and the Engineers group, then that user will impersonate the Requesticon Executive user. Being an executive, this user is likely to be granted access to more content.