ShowTable of Contents
IBM® Lotus® Quickr® services for WebSphere® Portal helps you share content, collaborate, and work faster online with your teams---inside or outside your firewall. The latest release, 8.5, catalogs all places in a central catalog on the landing page, and this article describes how you can add custom metadata to Places, and display and filter on that metadata in the catalog.
For instance, you will learn how place owners can tag their places with an industry and location and can allow end users to search for places based on the available industries. You can download the supplied Portlet and use it right away for adding metadata to Places according to your needs. We also cover all the required configuration steps for achieving this enhanced experience of the Quickr Places Catalog based on your own custom metadata.
Lotus Quickr Team Places includes team calendars, discussion forums, blogs, wikis, and other collaborative tools that help empower teams and keep projects on track. For the landing page, we use the Lotus Quickr My Places view for access to your team Places or to create a new Place, and we use the Public Places view to discover interesting public places and read through them.
From the public places page you can even find new places to join, if the place owner allows individuals to “self join” into a place. In Lotus Quickr 8.5 a new Places Catalog is introduced with type-ahead on the Places titles, search over Places metadata, and even tag-based navigation, which makes it easier than ever to find Places, particularly in large, distributed Lotus Quickr deployments.
If in your organization, Places have more specific characteristics, this article demonstrates how to extend the catalog through configuration. Characteristics that can be mapped as custom metadata and be used later by your Quickr users for filtering and navigating the Places as a means to find and discover relevant Places.
In the following sections, we explore the option to add custom metadata to Places. The extra metadata is available in the Places Catalog as additional information on each Place and also as dynamic filters know as facets.
Introducing custom metadata over Quickr Places
To assign custom metadata values to Places, we use a sample portlet that can be configured to handle many common scenarios. You must either deploy the Place Custom Metadata portlet provided with this article on your server or you can write a similar portlet to handle your specific metadata needs.
After deploying the portlet, an administrator configures and includes it in individual Quickr Places and templates. Once included in a Place, the place owners can add and edit metadata values for that Place, while all other users (editors, contributors, and readers) can view the metadata values.
With our sample metadata portlet, it's up to the server administrator to decide which types of metadata fields are allowed and include the portlet in templates. It's the place owner who sets the metadata or decides to add or remove the portlet from their place, and any user can navigate among places using the metadata set by the place owners.
You may even create multiple copies of the metadata portlet, each configured with different types of metadata for different types of places or different templates. For instance, you might have one instance of the portlet use the metadata “company”, “industry,” and “location” and another with the metadata “brand”, “product,” and “team”.
These two configurations of the metadata portlets could be used in two different templates on the same server. The section “Place Custom Metadata Portlet Deployment” below explains how to configure the portlet and add it to your places.
When the portlet is added to your Place, it's time to start setting metadata values. At the start, the portlet contains empty metadata values. Click the “” text to turn it into an input field and type a metadata value of your choice (see figure 1).
Figure 1. Place Custom Metadata portlet with edited value for “Company” name
Then press Enter (or click somewhere on the screen) to save it. You will be greeted with a success message, as shown in figure 2.
Figure 2. Saving new value as the Company name associated with specific Place
All owners of a Place can follow the same simple steps to add and edit their own Place's metadata (see figure 3). These values can then be surfaced from the Places Catalog.
Figure 3. Place with the Place Custom Metadata portlet
Exposing Places Custom Metadata in a Places Catalog
With the right configuration the Places Catalog is able to display custom metadata for Places and to support dynamic filters known as facets. The custom metadata itself is exposed in the Places list next to each Place and, on the left-hand side bar, it is displayed as filters.
However, these are not just normal filters; they are facets, which display the most popular values and the number of Places associated with each facet value. If you want to drill down by using the custom metadata, you can simply click one or more values from the facets lists to see all the Places associated with that particular list of values.
Notice that the custom metadata values and the number of associated Places are updated according to selected filters and the displayed list of Places.
Figure 4 shows an example of a Places Catalog for employees who work with different companies. In this case, each Place includes three custom metadata fields describing the name of the company, what the company does, and where the company is located.
Here you can see the list of all public Places with their custom metadata values and the metadata facets.
Figure 4. List of all public Places with their custom metadata
In figure 5, you can see the same Places filtered by the company name “Renovations”. Note that the industry and location fields have also been updated, showing that the places tagged for “Renovations” are only tagged with the Furniture industry, and Europe and US locations. You can also see how many places are tagged with US and how many with Europe in this case.
We could further filter by the location, normal tags, the owner, or any number of other criteria, to find places.
Figure 5. Places filtered by the company name “Renovations”
Using the Place Custom Metadata portlet
The portlet was developed to facilitate rapid Place metadata editing for the end user. All the source code has been packaged within the CustomPlaceMetadata.war file (available as an attachment to this article).
Essentially, a Quickr Place ATOM feed is retrieved by use of an XMLHttpRequest (XHR) asynchronous call and then parsed to find a Place's metadata values. When a user changes a metadata value, a PUT request is made to update it on the server.
Although the portlet is not hard-coded to any particular metadata, and can be used with a variety of fields, if you have more detailed requirements not handled by this portlet, the source code will provide a starting point for developing a portlet tuned to your metadata requirements.
Now we show how to deploy, configure, and use the Place Custom Metadata portlet.
Deploying the portlet
- Click the Advanced Administration link in the footer
- In the left-hand side bar, click Web Modules
- Click the Install button from within the Manage Web Modules portlet.
- Select the CustomPlaceMetadata.war from your local file system and click Next.
- Click Finish. You should see the confirmation message, “Web module was successfully installed,” once it completes.
Configuring the Custom Metadata fields
By default, the portlet comes packaged with three metadata names: Company, Industry, and Location, as seen in figure 6. This means that each Place containing the portlet can be assigned with a metadata value for each of these names.
Figure 6. Configuration of Custom Metadata Fields
However, you can edit these names to suit whatever you like (see figure 7). To do this:
- Click the Advanced Administration link in the footer.
- In the left-hand side bar, click Portlets, and search for the “Place Metadata” portlet.
- Click the “spanner” icon to configure the Place Metadata portlet.
- To edit the preferences, click the pencil (Edit value) icon, change the value in the Value field to what you want, and click OK. Your changes should be updated in the main screen
- To finalize the changes, you must click the OK button at the bottom of the screen. After that, once the portlet is dropped into a Place, it should expose the new metadata names.
You may also create copies of the portlet, using the Portlet management screen, and configure each copy with different allowed metadata.
Figure 7. Preferences changed to 'Brand', 'Product' and 'Team'
NOTE: If you change the metadata names and IDs via portlet configuration, it doesn't affect any existing templates or Places. However, it is possible to refresh the portlet and get the updated names by removing the portlet from a Place's page and re-adding the portlet again. The same goes for templates. (See relevant sections below for more detailed instructions.)
The Portlet has two preferences, customMetadataIds and customMetadataNames, which control what metadata values can be defined for Places:
- 'customMetadataIds' identify 'customMetadataNames' and are for internal use (i.e., they link up with the Places Catalog code).
- 'customMetadataNames' are exposed to users from the Place UI, and they're used for purely presentational purposes.
Note that the values are separated by semi-colons ';' and that the order of the ID and name preference must sync up. For example, the “company” ID relates to the “Company” name, the “industry” ID relates to the “Industry” name, and so on.
Adding to a Place
When you're finished configuring the portlet with the metadata of your choice, it's time to add it to a Place. Although only administrators can configure the portlet and set what metadata fields are allowed, all Place owners can add it to a Place and enter values for the metadata.
To add the Custom Metadata portlet to a Place:
- Once inside a place, click the Place Actions button in the top right-hand-side place bar and select Modify Place Layout.
- Create a page onto which you want to drop the portlet (skip this step if the page is already created).
- Click the pencil (Edit Page Layout) icon on the page's row where you want to add the portlet.
- On the next screen, click the Add Portlets button, enter 'Place Metadata' into the search field, and click Search.
- Select the checkbox for the Place Metadata portlet that shows in the results and click OK.
- Finally, click the Done button and click the Done button again.
The portlet should now be included in the page to which you added it, ready for use.
You can also add the portlet to the customization shelf, to make it easier for place owners to add the place individually. If you intend to add the portlet to your templates, it will always be in the place and you might not also want it in the customization shelf.
Refer to the developerWorks article, “Customizing themes in IBM Lotus Quickr 8.5 for WebSphere Portal”, section “Customize shelf”, for more information on modifying the customization shelf.
As mentioned above, all place managers can follow these steps to add the portlet to their place. Alternatively, administrators can package this layout into a template to make things easier. This approach is covered in the next section.
Adding to a template
Instead of individually dropping the portlet into each Place, you can edit your server templates so that they contain the portlet. Every subsequent Place created from these templates will include the Place metadata portlet.
The values in the portlet can be left as the server defaults, or even set to custom values (different than the server default values) from within the template XML. An easy way to do this is to first create a Place, dropping the portlet into it, and then save that Place as a template. To save a Place as a template, navigate to it and select Place Actions > Save as Template.
Places Catalog configuration to expose Place custom metadata
The following steps describe the configuration needed for indexing the custom metadata and displaying them in the catalog.
Adding/modifying Custom Metadata publish per Place
- Log in to the WebSphere Application Server administration console.
- Expand Resources > Resource Environment > Resource Environment Providers.
- Select PlacesRetriverProvider > Custom properties.
- Modify the parameter named configuration, which includes an XML, adding the XML snippet in listing 1 per metadata (update the field id, name, and description as appropriate).
- Expand Applications > Enterprise Applications; restart PlacesTemplatesSeedlistServletApp application.
Listing 1. XML code snippet
“<Field id="company" isRequired="true">
<FieldInfo Name="Company" Description="Company Name"
isContentSearchable="false" isFieldSearchable="true" isParametric="false"
isReturnable="true" isSortable="false" isExactMatchSupported="true">
Adding/modifying facets that are pre-calculated in Places Catalog engine
- Expand Applications > Enterprise Applications, and click the PlaceCenterApp application.
- Click Initialize parameters for servlets, and set the value of the debug parameter (for SearchAdminServlet) to “true”.
- Save your changes, open a browser, and type in the URL shown in listing 2.
Listing 2. URL to type in
4. Verify that the FACETS_CONFIG parameter is updated by typing in the following URL:
5. Expand Applications > Enterprise Applications, and click the PlaceCenterApp application.
6. Click Initialize parameters for servlets, and set the value of the debug parameter (for SearchAdminServlet) back to “false”.
7. Save your changes and restart the PlaceCenterApp application.
8. Log in to Lotus Quickr using the administrator user/password.
9. Click Place Center Administration, and expand “DefaultPlacesCrawlerLocal” source.
10. Click More actions and then select Clear Data.
11. Wait until all data is cleared (you can refresh the status until you see “OK”); click Collect Data.
Adding/modifying list of facets calculated for Places in the catalog in runtime
1. Expand Resources > Resource Environment > Resource Environment Providers.
2. Select PlacecntrPropertiesService > Custom properties.
3. Click New, and enter the property name “customMetadata”.
4. Set the string value to be an array of objects separated by commas such that each of them represents one metadata field and includes name, id, and count. For example:
where the name is the name to display in the catalog, the id is the metadata id, and the count is the maximum number of values to display in the facets section.
5. Expand Applications > Enterprise Applications, and click PlaceCenterApp application.
6. Click Initialize parameters for servlets.
7. Update the value of the three outputFields parameters (for PlacesSearchServlet, PublicPlacesServlet and MyPlacesServlet) to include the metadata ids. For example:
8. Expand Applications > Enterprise Applications; restart PlaceCenterApp application.
This article introduces metadata extensions for Places in the Quickr Places Catalog, which enables a centralized view of available places across a defined set of servers while showing dynamic filters and facets for those Places based on custom metadata. Also included are all the required configuration steps and any additional required utilities to leverage your Places custom metadata for Places discovery.
About the authors
Liat Rozenberg joined IBM in 2008 and is currently a developer on the Enterprise Information Discovery team that develops search solutions for WebSphere Portal and Lotus Quickr. She holds a M.Sc. degree in Computer Science from the University of Haifa, Israel.
Robert Campion joined IBM in 2008 and has worked as a Software Engineer on Lotus Quickr and Lotus Connections, primarily in the area of front-end development. He graduated from Dublin City University, Ireland, with a B.Sc. in Computer Applications.
Boaz Ben-Nahum joined IBM in 2004 and has specialized in developing search front-end, UI, and AJAX applications for WebSphere Portal and Lotus Quickr. He currently leads the WebSphere Portal and Lotus Quickr search team. He holds a B.Sc. degree in Computer Science from the Technion, Haifa, Israel.
Eitan Shapiro joined IBM in 2005 and is the Manager of the Enterprise Information Discovery team that develops search solutions for WebSphere Portal and Lotus Quickr. He holds a B.Sc. degree in Information Systems Engineering from the Technion, Haifa, Israel.
Jon Brunn is a Senior Software Engineer working on social and team collaboration software. He has more than 10 years of experience with content management systems and has contributed to Lotus Quickr, Lotus Connections, WebSphere Portal, Web Content Management, FileNet, and IBM Content Manager.