Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter Portal
11g Release 1 (11.1.1.7.0)

Part Number E10148-20
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

43 Integrating the Tags Service

This chapter explains how to integrate the Tags service in a WebCenter Portal: Framework application at design time.

For more information about managing and including tags, see:

See Also:

You must register a resource viewer to enable custom resources to be rendered using Search or Tags, or to make the resources linkable to and from each other. For more information, see Section 7.3, "Extending Your Framework Application with Custom Components."

This chapter includes the following sections:

43.1 Introduction to the Tags Service

Tags enable users to apply their own meaningful terms to items, making those items more easily discoverable in search results and the Tag Center. The Tag Center is a page that displays the interactions among all the tags, tagged items, and their taggers in an application.

Having multiple users tag objects contributes to the collective knowledge, which makes searching much more relevant. WebCenter Portal search takes advantage of the knowledge captured by tagging by indicating the relevance of results based on the quality and frequency of their applied tags.

Tags let the users of data (instead of the publishers of data) classify information. In this way, tags act as a personal productivity tool and a method to increase searchability for everyone.

For example, suppose your application includes a component that provides a view of departmental human resources contacts. If you enable tags for this component, then a user who comes to it can bookmark it for themselves and assign tags like HR or contacts or department to help others find it as well.

The Tags service is available for pages, documents, and custom objects. Creating a tag automatically publishes the event to the Activity Stream.

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 follows
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.

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 Portal 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."

Note:

Typically, when you add tags in a Framework application, you also should add a search toolbar to enable searching for the objects with the tags. To add the search toolbar, follow the instructions in Section 44.2.3, "Adding the Search Service at Design Time."

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 Framework 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 Portal 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 Framework Application with Custom Components."

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

43.2 Basic Configuration for the Tags Service

This section describes required steps for adding this service to your application. It includes the following subsections:

43.2.1 Setting up Connections for the Tags Service

The Tags service requires a connection to the database with the WebCenter Portal 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:

43.2.2.1 Tags Service Components

The following JSF components are included in the service:

  • Tagging Button: When you add a Tagging Button, a Tags link on the page enables you to invoke the Tag This Item (or Tag This Page) dialog at runtime.

  • Tagging Menu Item: When you add a Tagging Menu Item, a menu option on the page enables you to invoke the Tag This Item (or Tag This Page) dialog at runtime.

In the Component Palette, drag and drop components to the page. In the resulting dialog box, you can configure attributes in the Tags components. You can configure attributes in the Tags components. For example, the SharedParam attribute lets you disable the Shared checkbox. (With the default value, the checkbox is enabled, so users can check it or uncheck it at will. With the always value, the checkbox is disabled in the true state, so all tags are public. With the never value, the checkbox is disabled in the false state, so all tags are private.) As another example, the ResourceScope attribute lets users tag objects in a different scope, such as a list of search results with the Tagging button next to each result, where the search is done in the default scope but the results could be in other scopes. For more information about the component attributes, see the online help.

43.2.2.2 Tags Service Task Flows

Table 43-1 lists the Tags service task flows.

Table 43-1 Tags Service Task Flows

Task Flow Definition

Tagging - Dialog

This task flow displays a dialog that appears to tag a particular object. This does not have any visible user interface rendering when dropped onto a page. It only becomes visible when the tagging button is clicked.

Tagging - Personal View

This task flow shows the tags created by the current user, objects tagged by those tags, and a cloud view of the tags. A service ID input parameter enables you to view tagged items of interest.

Because this is a non-public task flow, it requires authentication.

Tagging - Related Links

For an object identified by a unique ID, this task flow lists all the other objects that are tagged with similar tags.

The other objects listed include those that are similarly tagged; that is, their tag "sets" have an intersection of at least one. The list is ordered by the number of tags in the intersection.

Tagging - Tag Cloud

This task flow displays a tag cloud, which is a visual depiction of all the tags used. Tags are presented according to the frequency of their use. More frequently used tags display in bold fonts and varying font sizes—the larger the font, the more the tag has been applied.

When you click a tag in the tag cloud, you are redirected to Tag Center, where that tag is selected.

This task flow appears on a page with tagged items. It provides Resource Action Handling (RAH) links for all tags in the page.

Tagging - Tag Selection

Similar to the Tag Cloud task flow, the Tag Selection task flow also displays a tag cloud. However, when you select a tag, it marks the tag as selected, and you see the results in the Related Resources task flow. You are not redirected to the Tag Center.

With this task flow and the Tagging - Tagged Items task flow, you can click a tag in the tag cloud to see the items that use the tag. (In other words, selecting a tag in the Tagging - Tag Cloud task flow sends the tag word as an event to all interested event consumers, such as the Tagging - Tagged Items task flow.)

Tagging - Tagged Items

This task flow displays items pages, or documents that have been tagged. It can refine itself to show only the items tagged with the tag passed to it. This task flow can listen for events sent by the Tagging - Tag Cloud task flow.


43.2.2.3 How to Add the Tags Service to your Page

To add the Tags service to your WebCenter Portal: Framework application:

  1. Follow the steps described in Chapter 3, "Preparing Your Development Environment" to create a customizable page in your application.

  2. Ensure that you have set up a database connection to a database with the WebCenter Portal schema installed.

  3. Open the page where you included the search toolbar.

  4. On the Component Palette (All Pages), select the Tagging Button and drop it on the page, inside a PanelGroupLayout. Make it the first child of the PanelGroupLayout by placing it to the left of the search toolbar. The Tagging Button enables users to start tagging.

  5. Fill out the Insert Tagging Button dialog. Table 43-2 provides descriptions and example values for the fields in the dialog.

    Table 43-2 Fields in the Insert Tagging Button Dialog

    Field Description
    ResourceId
    

    The ID that uniquely identifies the object to which you are binding the Tagging Button. The value in this field need not be static. For example, you could use EL to insert a unique value for each row in a table. For example:

    • To tag pages, enter #{facesContext.viewRoot.viewId}

    • To tag custom components, enter customComponent123

    ResourceName
    

    The name of the object to which you are binding the Tagging Button. The value in this field need not be static. For example, you could use EL to insert a unique value for each row in a table.

    • To tag pages, enter #{facesContext.viewRoot.viewId}

    • To tag custom components, enter Custom Component 1

    ServiceId
    

    An application-wide ID. (With custom components, you add this to service-definition.xml when adding the resource viewer.)

    • To tag pages, enter oracle.webcenter.page

    • To tag custom components, enter mycompany.myproduct.myapp.mycomponent


    Figure 43-3 Insert Tagging Button Dialog for a Custom Component

    Description of Figure 43-3 follows
    Description of "Figure 43-3 Insert Tagging Button Dialog for a Custom Component"

  6. Click OK.

    Note:

    The Tagging Button includes additional properties you can set. For example, SharedParam lets you disable the Shared checkbox. (With the default value, the checkbox is enabled, so users can check it or uncheck it at will. With the always value, the checkbox is disabled in the true state, so all tags are public. With the never value, the checkbox is disabled in the false state, so all tags are private.)

  7. From the Resource Palette, expand WebCenter Portal - Services Catalog and Task Flows.

  8. Drag and drop Tagging Dialog from the Resource Palette on the page, optionally adding a redirection URL for anonymous page login.

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

  10. For custom resources, follow the steps described in Section 7.3, "Extending Your Framework Application with Custom Components" to register a resource viewer. For services exposing resources to be tagged (and therefore searched and viewed) WebCenter Portal provides a Resource Action Handling framework. The Tags service uses this framework to allow acting on a search result.

In the Source view where you added the Tags service, you should see something similar to Example 43-1.

Example 43-1 Tagging Button and Tagging - Dialog Task Flow Source

<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>

Note:

Even if there are multiple Tagging Buttons on the page, only one Tagging Dialog af:region is needed.

Run the page with the Tagging Button and Tagging - Dialog task flow. When the page renders in the browser, click the Tags link.

  1. When the dialog appears, enter the tag home and click Save. Note that every user of the system can perform this same operation and assign the same tag, which means that you get a weighted collection of tags.

  2. In the search toolbar, type the search term home, and click the Search icon.

  3. You should see home as a search result under Tags and Custom Component 1 as a search result under Tagged Items.

  4. Click Custom Component 1 and a dialog appears with the resource viewer you just created (Figure 43-4).

    Figure 43-4 Resource Viewer

    Description of Figure 43-4 follows
    Description of "Figure 43-4 Resource Viewer "

43.2.2.4 How to Modify the Tags Service Task Flow Parameters

Some Tags service task flows have optional task flow binding parameters.

Note:

You should not change the Tags service task flow properties unless you want to show items from a different resource or different service.

To see and adjust task flow binding parameter values after you have placed a task flow on a page:

  1. Navigate to the Edit Task Flow Binding dialog by clicking the Bindings tab at the bottom of the page (next to the Source tab).

  2. Under Executables, you'll see the task flow you added. Figure 43-5 shows an example of Tags task flows in the Executables section.

    Figure 43-5 Page Data Binding Definition

    Description of Figure 43-5 follows
    Description of "Figure 43-5 Page Data Binding Definition"

  3. Select the task flow, and next to the Executables heading, click the Edit selected element (pencil) icon.

  4. In the Edit Task Flow Binding dialog Figure 43-6, revise the binding parameter values as required.

    Figure 43-6 Edit Task Flow Binding Dialog for Tags - Related Links Task Flow

    Description of Figure 43-6 follows
    Description of "Figure 43-6 Edit Task Flow Binding Dialog for Tags - Related Links Task Flow"

  5. When you are finished, click OK.

  6. Save and run your page to see the results.

Table 43-3 describes the properties that are unique to the Tags service task flows.

Table 43-3 Tags Service Task Flow Parameters

Property Description Task Flow

resourceId

Unique ID of the item or resource within a given service that is used to find similarly tagged items. This value is set automatically.

Do not change this value unless you want to show items similar to a different resource.

Tagging - Related Links

serviceId

This parameter has a different meaning for the Related Links task flow and the Personal View task flow.

  • In Related Links, it is a resourceId/serviceId pair that defines the item that has related links. This value is set automatically. Do not change this value unless you want to show items similar to a different resource belonging to a different service.

  • In Personal View, it limits the tags to this service; for example, oracle.webcenter.page.

Tagging - Related Links

Tagging - Personal View

resourceScope

Scope of tags. This value is set automatically (either #{spaceContext.currentSpaceGUID} or something like s8bba98ff_4cbb_40b8_beee_296c916a23ed).

Do not change this value.

Tagging - Tag Cloud

Tagging - Tag Selection

Tagging - Tagged Items

redirectURL

Optional redirection URL for anonymous page login. This must include the /faces prefix; for example, /faces#{facesContext.viewRoot.viewId} If null or empty, then no login is displayed.

Tagging - Dialog


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 WebCenter Portal's Framework application template. For information about configuring ADF security, see Section 68.3, "Configuring ADF Security."

Note:

You must register a resource viewer to allow custom objects to be found using Search or Tags. For information about how the resource viewer's authorizerClass determines whether users can view the resource, see Section 7.3, "Extending Your Framework Application with Custom Components."

43.3 Advanced Information for the Tags Service

This section describes optional features available with this service. It includes the following subsections:

Note:

You can turn up logging levels for the tagging component (as you can with other components) in the logging.xml file, found under the WLS home.

43.3.1 Using the Tags Service Java APIs

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

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

43.3.2 Using the Tags Service REST APIs

WebCenter Portal provides REST APIs to support tags. Use the Tags 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:

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

43.3.2.1 Tags Entry Point

Each REST service has a link element within the Resource Index that provides the entry point for that service. To find the entry point for the Tags, find the link element with a resourceType of one of the following:

  • urn:oracle:webcenter:tagging:tags

  • urn:oracle:webcenter:tagging:taggeditems

  • urn:oracle:webcenter:tagging:users

The corresponding href or template element provides the URI entry point. The client sends HTTP requests to this entry point to work with the Tags service.

For more information about the Resource Index, see Section 53.5.1, "The Resource Index."

For more information about resource types, see Section 53.5.2.1, "Resource Type."

43.3.2.2 Tags Resource Type Taxonomy

When the client has identified the entry point, it then can navigate through the resource type taxonomy to perform the required operations. For more information about the individual resource types, see the appropriate section in Section 53.5.2.1, "Resource Type."

The taxonomy for the Tags service is:

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 

Under users, you can add the resource type for that object, such as peopleprofile.

Beyond the service entry points, URL templates allow clients to pass query parameters to customize their requests and control the form of returned data.

Collection resources in the tags resources support pagination (itemsPerPage and startIndex for tags and users and itemsPerPage for taggedItems). Other query parameters (search and projection) are not supported.

43.3.2.3 Security Considerations

Authentication is required before using Tags REST API methods.

For general security considerations, see Section 53.8, "Security Considerations for WebCenter Portal REST APIs."

43.3.2.4 Tags Resource Types

This section provides information about each resource type. It includes the following subsections:

43.3.2.4.1 urn:oracle:webcenter:tagging:tags

Use this resource type to identify the URI to use to read (GET) tags. The response from a GET operation includes all tags, a specific tag, a subset of tags, or a tag related to a specific list of tags or users.

Navigation Paths to tags

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   tags 
resourceindex
   spaces
      spaces:resourceindex
         spaces:tags 

Supported Methods for tags

The following methods are supported by this resource:

  • GET

    • request - body: none, Parameters: startIndex, itemsPerPage, keyword, serviceId, relatedTag, userId, scopeGuid, shared, tags, users

    • response - body: tag

    where:

    • startIndex—Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.

    • itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

    • keyword—Specifies the keyword for substring matches.

    • serviceId—Specifies the service ID for which you want to find tags (null for all).

    • relatedTag—Specifies a tag that is related to the list of tags. For example, if you have tagged item1 as "webcenter help" and item2 as "webcenter document" and you set relatedTag=webcenter, then you would get returend both tags (for help and document).

    • userId—Specifies a single user ID to find tags for (null for all). Uses logged-in user if null and not looking for shared tags.

    • scopeGuid—Specifies the GUID of the portal. When set to the Home space, it shows all (unfiltered) tags.

    • shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).

    • tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.

    • users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

Note:

Parameters can be used in certain combinations only.

Table 43-4 shows the available parameter combinations for each operation. For example, the tags parameter cannot be specified with the serviceId parameter.

Table 43-4 Parameter Combinations Available for Getting Tags

API Method keyword serviceId relatedTag userId scopeGuid shared tags users

findRelatedSystemTags

   

X

 

X

 

X

X

findPopularTagsCommon

X

X

 

X

 

X

   

findPopularTags (with GUID)

X

   

X

X

X

   

findPopularTags

X

   

X

 

X

   

Resource Types Linked to From tags

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table 43-5 lists the resource types that the client can link to from this resource. Tags have a reference link to themselves and to the next page or previous page of results.

Table 43-5 Related Resource Types for tags

rel resourceType

self

urn:oracle:webcenter:tagging:tags

Previous/Next

urn:oracle:webcenter:tagging:tags


43.3.2.4.2 urn:oracle:webcenter:tagging:tag

Use this resource type to identify the URI to use to read (GET), rename (PUT), and delete (DELETE) a tag. The response from a GET operation includes all tags, a specific tag, a subset of tags, or a tag related to a specific list of tags or users.

Navigation Paths to tag

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   tags
      tag
resourceindex
   spaces
      spaces:resourceindex
         spaces:tags
            spaces:tag

Supported Methods for tag

The following methods are supported by this resource:

  • GET

    • request - body: none, Parameters: none

    • response - body: tag

  • PUT

    • request - body: tag

    • response - body: tag

  • DELETE

    • request - body: none

    • response - body: none

Example 43-2 Body of the PUT command for Renaming a Tag

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

Resource Types Linked to From tag

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table 43-6 lists the resource types that the client can link to from this resource. A tag has a reference link to itself, to related taggedItems, to related users, and to related tags.

43.3.2.4.3 urn:oracle:webcenter:tagging:taggedItems

Use this resource type to identify the URI to use to read tagged items and their related resources (GET) or to add tagged items (POST).

The response from a GET operation includes a tagged item or all tagged items, which can be filtered by date, tag words, and so on. Each tag includes links used to operate on that tag. The response from a POST operation includes the tagged items that were created in this collection of tags and a link to operate on them.

Navigation Paths to taggedItems

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggedItems
resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItems

Supported Methods for taggedtems

The following methods are supported by this resource:

  • POST

    • request - body: taggedItem

    • response - body: taggedItem

    <taggeditem>
       <serviceId>oracle.webcenter.page</serviceId>
      
    <resourceId>/oracle/webcenter/page/somepath/someotherpath/a.jspx</resourceId>
       <tagWords>foo bar boo far</tagWords>
       <resourceTitle>This is renamed by me to be foofoo</resourceTitle>
       <scopeGuid>(optional) scope for the item</scopeGuid>
       <shared>(optional) make the item private </shared>
     </taggeditem> 
    
  • GET

    • request - body: none, Parameters: serviceId, keyword, relatedRID, scopeGuid, tags, users, dt, shared, itemsPerPage

    • response - body: tagged items

    where:

    • serviceId—Specifies the service ID of the item.

    • keyword—Specifies a keyword in the resource title.

    • relatedRID—Specifies a related tag. For example, if you tagged item1 as "webcenter help" and item2 as "fusionapps documents" and item3 as "webcenter documents" and set relatedRID=item3, then you would get back item1 and item2, because they share tags in common with item3.

    • scopeGuid—Specifies the GUID of the portal. When set to the Home space, it shows all (unfiltered) tags.

    • tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.

    • users—Specifies to filter by this list of users, separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

    • dt—Specifies to filter bookmarks by this date, which defaults to the most recent date on which bookmarks were saved {DD-MM-CCYY}.

    • shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).

    • itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

Note:

Parameters can be used in certain combinations only.

Table 43-7 shows the available parameter combinations for each operation. For example, the tags parameter cannot be specified with the serviceId parameter.

Table 43-7 Parameter Combinations Available for Getting Tagged Items

API Method serviceId keyword relatedRID scopeGuid tags users dt shared

findRelatedSystemResources

X

 

X

         

findUpdatedResources

     

X

   

X

 

findSystemResources

     

X

X

X

 

X

findFilterPersonalResources

X

X

 

X

       

findPersonalResources

     

X

X

X

 

X

findFilteredPersonalResources (no keyword)

X

   

X

       

Resource Types Linked to From taggedItems

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table 43-8 lists the resource types that the client can link to from this resource. Tagged items have a reference link to themselves and to the next page or previous page of results.

Table 43-8 Related Resource Types for taggedItems

rel resourceType

self

urn:oracle:webcenter:tagging:taggedItems

Previous/Next

urn:oracle:webcenter:tagging:taggedItems


43.3.2.4.4 urn:oracle:webcenter:tagging:taggedItem

Use this resource type to identify the URI to use to read tagged items and their related resources (GET), add tagged items (POST), update tags for a tagged item (PUT), and remove all tags from an item (DELETE).

The response from a GET operation includes a tagged item or all tagged items, which can be filtered by date, tag words, and so on. Each tag includes links used to operate on that tag. The response from a POST operation includes the tagged item that was created in this collection of tags and a link to operate on that tagged item.

Navigation Paths to taggedItem

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggedItem
resourceindex
   spaces
      spaces:resourceindex
         spaces:taggedItem

Supported Methods for taggedItem

The following methods are supported by this resource:

  • GET

    • request - body: none, Parameters: serviceId, keyword, tags, users, dt, shared, itemsPerPage

    • response - body: tagged item

    where:

    • serviceId—Specifies the service ID of the item.

    • keyword—Specifies a keyword in the resource title.

    • tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.

    • users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

    • dt—Specifies to filter bookmarks by this date, which defaults to the most recent date on which bookmarks were saved {DD-MM-CCYY}.

    • shared—Specify true to return personal resources only (that is, resources tagged privately only by that same user); false to return system resources (that is, resources with at least one public tag).

    • itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

  • PUT

    • request - body: taggedItem

    • response - body: taggedItem

    <taggeditem>
    <tagWords>foo bar boo far</tagWords>
    </taggeditem>
    
  • DELETE

    • request - body: none

    • response - body: none

Resource Types Linked to From taggedItem

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table 43-9 lists the resource types that the client can link to from this resource. A tagged item has a reference link to itself, to related tagged items, and an external link.

Table 43-9 Related Resource Types for taggedItem

rel resourceType

self

urn:oracle:webcenter:tagging:taggedItem

 

urn:oracle:webcenter:tagging:taggedItems

alternate

The resource type depends on the type of resource tagged; for example, a page would be urn:oracle:webcenter:page:page


43.3.2.4.5 urn:oracle:webcenter:tagging:users

Use this resource type to get a list of people related to a given list of tags.

Navigation Paths to users

This section shows how the client can navigate through the hypermedia to access this resource:

resourceindex
   taggingusers
resourceindex
   spaces
      spaces:resourceindex
         spaces:taggingusers

Supported Methods for users

The following methods are supported by this resource:

  • GET

    • request - body: none, Parameters: startIndex, itemsPerPage, tags, users

    • response - body: people profile

    where:

    • startIndex—Specifies the index of the first matching result that should be included in the result set (0-n ... zero based). This is used for pagination.

    • itemsPerPage—Specifies the maximum number of results to return in the response (1-n). This is used for pagination.

    • tags—Specifies to filter by this list of tags separated by URL-encoded spaces ('+'); for example, an item tagged with "webcenter" and "help" could be searched with tags=webcenter+help.

    • users—Specifies to filter by this list of users separated by URL-encoded spaces ('+'); for example, users=monty+vicki+pat.

Resource Types Linked to From users

The resourceType link attribute indicates the type of resource to which the link points. Clients should use the resourceType to determine the expected response bodies for GET and POST and allowable request bodies for POST and PUT.

Table 43-10 lists the resource types that individual users can link to from this resource. Users have a reference link to themselves and to the next page or previous page of results.

Table 43-10 Related Resource Types for users

rel resourceType

self

urn:oracle:webcenter:tagging:users

Previous/Next

urn:oracle:webcenter:tagging:users


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 follows
    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-3.

    Example 43-3 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 follows
    Description of "Figure 43-8 Insert Tagging Button Dialog for a Page"

  9. Click OK.

  10. From the Resource Palette, expand the WebCenter Portal - 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-4.

    Example 43-4 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 follows
    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 follows
    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 services exposing resources to be tagged (and therefore searched and viewed) WebCenter Portal 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 Framework Application with Custom Components."

43.3.5 Troubleshooting the Tags Service

This section provides troubleshooting tips on implementing the Tags service. It includes the following subsections:

43.3.5.1 Tag Center Results Do Not Appear When Tag Is Clicked

Problem

A resource to which a user has View permission has been tagged, but the user cannot see the resource in the Tag Center.

Solution

  1. In service-definition.xml, verify that the resource type has the Resource Authorizer configured properly.

  2. Enable logging for the Resource Authorizer to ensure that it is giving you permission to see the required objects.

43.3.5.2 The Tag Center Does Not Display Tagged Documents

Problem

Tagged WebCenter Portal Content Server documents do not appear in the Tag Center.

Solution

Check the version listed for the WebCenter Portal component in the Content Server. The result set name changed in WebCenter Portal release 11.1.1.6.0.

43.3.5.3 The Tagging Button Does Not Display On Page

Problem

The Tagging Button component is dropped on a page, but it does not show up.

Solution

  • The Tagging Button requires the Tagging Dialog task flow to be present on the page. Drop this task flow on the page or page template.

  • The Tagging Button requires a valid database connection. Ensure that there is a database connection present.

43.3.5.4 Clicking a Tagged Resource Does Not Go To The Correct Page

Problem

When clicking a tagging resource in Tag Center, users are not redirected to the correct page.

Solution

All tagging links are generated through the Resource Action Handling (RAH) framework. Ensure that RAH is configured properly.

  • Check service-definition.xml for that resource type to see if a resource viewer is configured properly.

  • Ensure that the resourceID and serviceID parameters passed for this resource are correct.