43 Integrating the Tags Service

43.1.1 Understanding the Tags Service

You can apply one or more meaningful terms, called tags, to remind yourself and alert other users of the content they might expect to find at the tagged location. Anywhere you see the Tags icon (Figure 43-1), you can apply a tag.

Figure 43-1 The Tags Icon

Description of "Figure 43-1 The Tags Icon"

Tags let you apply your own classifications to items. For example, you could apply the tag phone to a product page that provides useful information about new phones. When you or other users search for phone, the tagged page displays in the search results.

When you access the Tag Center, you see all users who applied the same tag anywhere else in the application. Within the Tag Center, a tag cloud (Figure 43-2) displays all currently applied tags.

Figure 43-2 A Tag Cloud

Description of "Figure 43-2 A Tag Cloud"

A tag cloud is a visual depiction of all tags. Tags are presented according to the frequency of their use—the larger the font, the more the tag has been applied to items. Click a tag in the tag cloud to run a search that returns a list of all items that use the tag.

43.1.2 Requirements for the Tags Service

The Tags service requires that you set up the WebCenter schema and create a database connection to the schema. Tag information is stored in the database. For details, see Section 7.2.2, "Setting Up a Database Connection."

The Tags service requires security. If users are not authenticated, then they cannot tag objects. If the application is not secured, then pages are not returned in search results for tagged items.

To enable the ability to tag documents, you must have the Document Manager task flow in the WebCenter Portal application. For more information, see Chapter 29, "Integrating the Documents Service."

43.1.3 What Happens at Runtime

At runtime, when you search for a tag word, results are returned in the Tagged Items section of the search results. By default, tagged items that are accessed through their tags are rendered in a full screen replacing the same window.You can override this and have it open in a popup window.

You can tag custom components, find those tags either through a search or in the Tag Center, and access tagged items through their associated tags.

For services exposing resources to be tagged (and therefore searched and viewed) WebCenter provides a Resource Action Handling framework. The Tags service uses this framework to allow acting on a search result. For more information, see Section 7.3, "Extending Your Application with Custom Components."

For more information about the service at runtime, see Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

43.2.1 Setting up Connections for the Tags Service

The Tags service requires a connection to the database with the WebCenter schema installed.

For details about setting up a database connection, see Section 7.2.2, "Setting Up a Database Connection."

43.2.2 Adding the Tags Service at Design Time

To enable basic tagging, you must add either the Tagging Button component or the Tagging Menu Item component and the Tagging - Dialog task flow. In addition, to tag custom objects, you must register a resource viewer to visualize the tagged component when it is discovered by users.

This section describes how to enable tagging by adding the Tagging Button and the Tagging - Dialog task flow. It includes the following subsections:

• Section 43.2.2.1, "Tags Service Components"

• Section 43.2.2.2, "Tags Service Task Flows"

• Section 43.2.2.3, "How to Add the Tags Service to your Page"

• Section 43.2.2.4, "How to Modify the Tags Service Task Flow Parameters"

<af:form id="f1">
        <af:region value="#{bindings.searchtoolbar1.regionModel}" id="r1"/>
        <tag:taggingButton resourceId="#{facesContext.viewRoot.viewId}"
                           serviceId="oracle.webcenter.page"
                           resourceName="#{facesContext.viewRoot.viewId}"
                           id="tb1"/>
        <af:region value="#{bindings.tagginglaunchdialog1.regionModel}"
                   id="r2"/>
      </af:form>

43.2.3 Setting Security for the Tags Service

The Tags service requires security. If users are not authenticated, then they cannot tag objects. If the application is not secured, then pages are not returned in search results for tagged items.

ADF security is configured by default if you created your application using the WebCenter Portal Application template. For information about configuring ADF security, see Section 67.3, "Configuring ADF Security."

43.3.1 Using the Tags Service Java APIs

Custom components can implement the Tags service APIs to create a tagging back end compatible with the WebCenter REST APIs or Tags service task flows and components.

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

43.3.2 Using the Tags Service REST APIs

Oracle WebCenter provides REST APIs to support the Tags service. Use the Tags service REST APIs to do the following:

• Find all tags or find a subset of tags by criteria

• Get a specific tag

• Delete tags

• Update or rename tags

• Get tagged items

• Untag an item

• Add a new tagged item

• Change tags for a tagged item

• Find all tagged items or find tagged items by a filter, such as a date or a tag word

• Get related user by tag

This section describes the REST APIs associated with the Tags service. It includes the following subsections:

• Section 43.3.2.1, "Tags Entry Point"

• Section 43.3.2.2, "Tags Resource Type Taxonomy"

• Section 43.3.2.3, "Security Considerations"

• Section 43.3.2.4, "Tags Resource Types"

For an introduction to the REST APIs, see Section 55, "Using Oracle WebCenter REST APIs."

urn:oracle:webcenter:tagging:tags
   urn:oracle:webcenter:tagging:tag
urn:oracle:webcenter:tagging:taggedItems
   urn:oracle:webcenter:tagging:taggedItem
urn:oracle:webcenter:tagging:users 

resourceindex
   tags 

resourceindex
   spaces
      spaces:resourceindex
         spaces:tags 

resourceindex
   tags
      tag

resourceindex
   spaces
      spaces:resourceindex
         spaces:tags
            spaces:tag

<tag>
<name>newId</name>
</tag>

resourceindex
   taggedItems

resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItems

resourceindex
   taggedItem

resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItem

resourceindex
   taggingusers

resourceindex
   spaces
      spaces:resourceindex
         spaces:taggingusers

43.3.3 Optional Way to Show Tags on Pages

While it is possible to add the Tagging Button and task flows on a page-by-page basis, typically you want to add the search toolbar and tags as part of a page template that you can apply whenever building a page that requires it. To add tags through a page template:

1. Open the project where you plan to create pages with the Tags service.

2. Right-click the project name and select New from the context menu.

3. Under Categories, select JSF and, under Items, select JSF Page Template.

4. For File Name, enter looksee1template.

   Figure 43-7 Create JSF Page Template Dialog

   
   Description of "Figure 43-7 Create JSF Page Template Dialog"
   
   

5. Click OK.

6. Go to the Source view and modify the code to be similar to that in Example 43-2.

   Example 43-2 Sample JSF Page Template

   <af:pageTemplateDef var="attrs">
     <af:xmlContent>
       <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
         <display-name>looksee1template1</display-name>
         <facet>
           <facet-name>content</facet-name>
         </facet>
       </component>
     </af:xmlContent>
     <af:panelGroupLayout layout="vertical">
       <!-- Our toolbar -->
       <af:panelGroupLayout id="toolbar" layout="horizontal" halign="end"
                            inlineStyle="background-color:cyan;width:100%">
       </af:panelGroupLayout>
       <af:panelStretchLayout startWidth="300"
                              inlineStyle="height:600px; width:100%;">
         <f:facet name="start">
           <af:panelSplitter id="sidebar" orientation="vertical">
             <f:facet name="first">
               </f:facet>
             <f:facet name="second">
             </f:facet>
           </af:panelSplitter>
         </f:facet>
         <f:facet name="center">
           <af:facetRef facetName="content"/>
         </f:facet>
       </af:panelStretchLayout>
     </af:panelGroupLayout>
   </af:pageTemplateDef>
   

7. On the Component Palette, select the Tagging Button and drop it on the page, inside the PanelGroupLayout. Make it the first child of the PanelGroupLayout.

8. Fill out the Insert Tagging Button dialog as shown in Figure 43-8.

   Table 43-11 provides descriptions and example values for the fields in the dialog.

   Table 43-11 Fields in the Insert Tagging Button Dialog for a Page

   Field	Description
   ResourceId	Unique identifier of your page. In this case, because the resource ID is meant for a page, enter #{facesContext.viewRoot.viewId}.
   ResourceName	Name of the page. In this case, enter #{facesContext.viewRoot.viewId}. (You can enter a more user-friendly name.)
   ServiceId	Service identifier that you add to service-definition.xml when adding the resource viewer. In this case, enter oracle.webcenter.page. Note: Because oracle.webcenter.page is available in the Page service library, nothing must be added to service-definition.xml.

   
   

   Figure 43-8 Insert Tagging Button Dialog for a Page

   
   Description of "Figure 43-8 Insert Tagging Button Dialog for a Page"
   
   

9. Click OK.

10. From the Resource Palette, expand the WebCenter Services Catalog and the Task Flows.

11. Drag Tagging Dialog from the Resource Palette and drop it on the page inside of the panelGroupLayout.

12. When prompted, select Region as the way to create the task flow.

13. Drag Search Toolbar and drop it after the Tagging Dialog you just added to the page template in the panelGroupLayout.

14. When prompted, select Region as the way to create the task flow.

15. Drag Document Library - Recent Documents and drop it in the second facet of the panelSplitter with identifier sidebar.

16. When prompted, select Region as the way to create the task flow.

17. In the Edit Task Flow Binding dialog, for connectionName, enter the name of the connection to your document library's content repository; for example, ${'MyFileSystem'}. For information on how to set up a connection to your content repository, see Section 26.2, "Configuring Content Repository Connections."

18. The source for your page template should now look similar to Example 43-3.

    Example 43-3 JSF Page Template with Tags and Search

    <af:pageTemplateDef var="attrs">
      <af:xmlContent>
        <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
          <display-name>looksee1template1</display-name>
          <facet>
           <facet-name>content</facet-name>
          </facet>
        </component>
      </af:xmlContent>
      <af:panelGroupLayout layout="vertical">
       <!-- Our toolbar -->
       <af:panelGroupLayout id="top" layout="horizontal" halign="end"
                   inlineStyle="background-color:cyan;width:100%">
        <tag:taggingButton resourceId="#{facesContext.viewRoot.viewId}"
                         resourceName="#{facesContext.viewRoot.viewId}"
                            serviceId="oracle.webcenter.page"/>
         <af:region value="#{bindings.tagginglaunchdialog1.regionModel}"
                    id="tagginglaunchdialog1"/>
         <af:region value="#{bindings.searchtoolbar1.regionModel}"
                    id="searchtoolbar1"/>
       </af:panelGroupLayout>
        <af:panelStretchLayout startWidth="300"
                              inlineStyle="height:600px; width:100%;">
         <f:facet name="start">
         <af:panelSplitter orientation="vertical">
          <f:facet name="first">
           <af:region value="#{bindings.taskservicetaskflowdefinition1.regionModel}"
                      id="taskservicetaskflowdefinition1"
                      inlineStyle="position:absolute; left:0px; width:100%;
                       height:100%"/>
          </f:facet>
          <f:facet name="second">
           <af:region value="#{bindings.doclibrecentdocuments1.regionModel}"
                      id="doclibrecentdocuments1"/>
          </f:facet>
           </af:panelSplitter>
          </f:facet>
          <f:facet name="center">
           <af:facetRef facetName="content"/>
          </f:facet>
        </af:panelStretchLayout>
       </af:panelGroupLayout>
      </af:pageTemplateDef>
    

19. Create two new pages based upon the page template you just created. In the Create JSF Page dialog, select looksee1template1 from the Use Page Template list.

    • Create a page called Search.jspx and add the Search task flow in the center facet.

    • Create a page called Documents.jspx and add the Document Library - List View task flow as the center facet. In the Edit Task Flow Binding dialog, for connectionName, enter the name of the connection to your document library's content repository; for example, ${'MyFileSystem'}. For information on how to set up a connection to your content repository, see Section 26.2, "Configuring Content Repository Connections."

20. Save your pages.

To run your pages with tags:

1. In the Applications Navigator, run the Search.jspx page.

2. After you log in and the page comes up, click the Tags link.

3. In the Tag this Page dialog, enter search page test customapp for Tags (Figure 43-9).

   Figure 43-9 Tag this Page Dialog for Search Page

   
   Description of "Figure 43-9 Tag this Page Dialog for Search Page"
   
   

4. Click Save.

5. Navigate to Documents.jspx (or run it separately).

6. Click the Tags link.

7. In the Tag this Page dialog, enter doclib documents page test customapp for Tags (Figure 43-10).

   Figure 43-10 Tag this Page Dialog for Documents Page

   
   Description of "Figure 43-10 Tag this Page Dialog for Documents Page"
   
   

8. Click Save.

9. In the search toolbar for the Documents.jspx page, enter search and click the Search icon.

10. Under Tags, click search.

43.3.4 Using the Resource Action Handling Framework to Tag Custom Objects

For WebCenter services exposing resources to be tagged (and therefore searched and viewed) WebCenter provides a Resource Action Handling framework. For example, rows in a table can be tagged.

To register a resource viewer, see Section 7.3, "Extending Your Application with Custom Components."