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.

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

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

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

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.

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

Open the page where you included the search toolbar.

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.

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

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

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

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

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.

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.

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.

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

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

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

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

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.

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

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

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.

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:

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.

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:

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.

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.

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:

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

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

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

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

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

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

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

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

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

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

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