Our Blog > Blog Detail

Web Content Viewer- Asponte Custom Skin


Unraveling the mysteries of Portal Search REST API - Part 2

  • Created By: Maria Rauba
  • Updated: June 16, 2016
  • Tags: search, portal, rest, facets, seedlist, constraints, api, remote, collection, count, faulty, ibm, service, weight, facetedfields, custom

In part 1 I talked about some of the issues with the documentation of the Search REST API.  In Part 2, I'll outline how to setup facets (or filters) for your search.  

Step 1 - Identify fields to use as facets:

Any of the built-in WCM fields like title, keywords, categories can be used as a facet, but you can also use custom fields.  If you have custom fields that are text or short text, then you can get them added to the seedlist and then available as a facet.  See this article: http://www.ibm.com/support/knowledgecenter/en/SS3JLV_8.0.0/wcm/wcm_config_search.html. This will create a field in the search results with the prefix "meta_":

<wplc:field id="meta_department">Human Resources</wplc:field>

Any custom non-text fields that you may want to use as a facet will need to be added to a custom seedlist.  One thing we noticed with custom seedlist items is that if you name them with mixed case like MyCustomField, it gets added to the seedlist with that name, but then the search results will show that name twice, once with the mixed case, and a second time with all lower case:

Seedlist: <wplc:field id="MyApplicationType">text_html</wplc:field>

Search Results has both:  <wplc:field id="MyApplicationType">text_html</wplc:field>  and

                  <wplc:field id="myapplicationtype">text_html</wplc:field>

This seems like a bug, but does not really cause any problems, just a duplicate field.  To avoid this, simply create the custom seedlist name in lowercase.

Step 2 - Setup the faceted fields in the search service

Once you identify the fields, you will need to set the 'facetedFields' parameter in your search service.  This parameter is not mentioned anywhere in the wiki, but it is mentioned in the IBM's faceted search article.

You will set 'facetedFields' to a value such as:

[ "applicationtype", "authoringtemplate", "meta_department", "tag"]

For both a default search service and a remote search service, the portal AND the remote search server will need to be restarted.  I was working with a remote search service once and I tried a shortcut to just restart the PSEStandalone app on the remote search server, but this sometimes caused faulty collections to occur.  Also, I have seen cases where if you just restart the portal, fields get in the seedlist but they are not searchable until you restart the remote search server.  (see my blog post about how to make tags available for searching.  So it is just best practice to restart both.

You will also need to re-crawl the collection.  I can't tell you how many times I forgot to do this!

Step 3 - Test the facets with a Search REST API request

Formulate your request with a parameter for each facet based on this wiki article: http://www.ibm.com/support/knowledgecenter/SSHRKX_8.5.0/mp/search-rest-api/facets-spec.html

Here is an example (line breaks added for clarity):


&facet={"id": "authoringtemplate", "count": "ALL", "sortOrder": "DESC"}

&facet={"id": "applicationtype", "count": "ALL", "sortOrder": "DESC"}

&facet={"id": "meta_year", "count": "ALL", "sortOrder": "DESC"}

&facet={"id": "tag", "count": "ALL", "sortOrder": "DESC"}

&index=Remote PSE service EJB::/apps/search/indexes/My Content Library2&query=maria&start=0&results=10

The response should contain a facets section near the bottom like:

<ibmsc:facets xmlns:ibmsc="http://www.ibm.com/search/content/2010" taxonomyId="facets">
<ibmsc:facet id="authoringtemplate" type="">
<ibmsc:facetValue id="authoringtemplate/AT Landing Page" label="AT - Landing Page" weight="2"/>
<ibmsc:facetValue id="authoringtemplate/AT News" label="AT - News" weight="2"/>
<ibmsc:facetValue id="authoringtemplate/AT Resource" label="AT - Resource" weight="2"/>
<ibmsc:facet id="applicationtype" type="">
<ibmsc:facetValue id="applicationtype/text_html" label="text_html" weight="6"/>
<ibmsc:facet id="year" type="">
<ibmsc:facetValue id="year/2013" label="2013" weight="4"/>
<ibmsc:facetValue id="year/2015" label="2015" weight="1"/>
<ibmsc:facetValue id="year/2016" label="2016" weight="1"/>



If you do not see the 'ibmsc:facets' section, then you probably forgot to do the restart or the re-crawl.

A key thing to note in the facets is the 'weight' attribute. This is the count of all items in the entire result set that match that facet, not just in the current page.  This information can be very useful to label your facets with a count.


Once you have facets, then you can specify constraints against them to filter your search results.  I'll dive into constraints, sorting and WCM Categories as facets in the 3rd part of this blog.

I hope that the mystery of the Portal Search REST API is getting clearer for you as you read these blog posts!

Contact Form- Asponte Custom Skin


Contact Us


Call Us 888-926-9434
Complementary Content