Administering the Tagging Framework

A tag is a relevant keyword or term associated with a piece of information such as a picture, a geographic map, a blog entry, a video clip, and so on. In this way tags describe an item and enable keyword-based classification and searching.

Tags are commonly used as means for users to store, organize, search, and manage bookmarks of web pages. The bookmarks can be viewed and searched chronologically, by category or tags, or using a search engine.

The PeopleSoft Enterprise Portal tagging framework enables users to tag Portal content and search the Portal using tags. Tags appear in the search results of the Portal search page and also in the search pages for various Enterprise Portal features, such as Content Management, Discussion Forums, Workspaces, and so on. Users can also perform searches using tags. A search using tags returns all the content tagged for that tag.

Private tags are not searched and are not returned with search results. The exception is in the Tag Browser page the user's own private tags are returned with the search results when a search scope of All My Tags is selected.

This chapter presents an overview of the tagging framework and discusses:

• Enabling web services.

• Managing the tagging framework.

• Implementing tagging web services.

Understanding the Tagging Framework

Tagging provides the means for Enterprise Portal and applications users to store, organize, search, and manage content bookmarks. It enables both publishers of content and consumers of that content to classify the material in a way that is meaningful to them. Significantly, users are able to share their tags or bookmarks with other users, thus benefitting the user community from the shared information--in this case tags. This increases the probability of properly characterizing the content and hence its discoverability and use. Tags are also a way to measure what particular topics are of relevance to the user community.

Tagging capability also provides for navigation to other content that is related through the same tags without the need to hard-code those connections.

Thus, tagging is both a means of classifying things and a way of creating ad hoc navigation paths among related items.

A PeopleSoft Enterprise Portal tag search page uses a database search, not Verity search. A user can immediately search for newly created tags because the tag search is not dependent on the Verity indexes being refreshed. Search results are filtered based on the users security permissions before being displayed. However, because the search is not performed using Verity, the results are not ranked.

The exception is that on the Portal search page and the search pages for Portal features, the tag search is based on Verity indexes. After new tags are added, the corresponding index has to be rebuilt before a the new tags will be returned in a search on the Portal search page.

Tags on any page are hyperlinks to the tag browser page with default search results of the tag selected. For instance, clicking on a tag labeled Community in a managed content item redirects the user to the tag browser page with search results for Community displayed.

See Also

Using Portal Features, Understanding Tagging in Enterprise Portal

Enabling Web Services

Enterprise Portal is delivered with tagging enabled for Content Management, Discussion Forums, and Workspaces. To use tagging with applications outside of Enterprise Portal you will need to enable tagging through web services.

Enabling web services requires single signon between the consuming application, such as HCM,)and Enterprise Portal, and user profile synchronization. The web services interface provided through Integration Broker contains the following services:

• Add tags

• Remove tags

• Clear tags

• Modify tags

• Get tags

• Search

• Tag Cloud

See Using Public Web Services.

See Configuring Integration Broker.

See Also

Enterprise PeopleTools 8.50 PeopleBook: Security Administration, Understanding User Profile Synchronization

Enterprise PeopleTools 8.50 PeopleBook: Security Administration, Implementing Single Signon

Enterprise PeopleTools 8.50 PeopleBook: Integration Broker, Consuming Services

Managing the Tagging Framework

This section describes how to:

• Define tagging domains.

• Define tag namespaces.

• Map namespaces to search index groups.

Pages Used to Managing the Tagging Framework

Defining Tag Domains

Access the Tagging Application Domain page (Portal Administration, Tagging, Tagging Domain).

Description	The description text entered here appears as the Search Scope name in the Scope dropdown list on theTag Browser.
Tag Browser URL	Specify the URL for the tag browser page for this domain. This URL will be prepended to the tags. If this is specified, it is assumed that the domain has its own tag browser page to display search results of the tags. If this field is left blank the domain will use the default Enterprise Portal tag browser. Note. If the Enterprise Portal tag browser is used, there will only be limited support for the search results of remote tags because of the limited amount of information that is stored for the tags in the repository. The search will not be able to query the source database for additional title or description information.
Message Node Name	Identifies the node in the PeopleSoft Enterprise Portal environment with which the tag domain is associated.

Defining Tag Namespaces

Tag namespaces prevent conflicts among unique identifiers in different features and enable categorizing tags at the namespace level. For instance, suppose both Discussion Forums and Managed Content have a content with an ID of 3421. To prevent these conflicts, each should reside in its own namespace.

A domain can contain many tag namespaces, but each namespace can only be associated with one domain.

Local Interface

Access the Tag Namespace page (Portal Administration, Tagging, Tagging Namespace).

Use a local interface to implement tagging within the Enterprise Portal application. Use the Package Name, Path, and Application ID fields to identify the application class that will be used with the namespace. The application class specifed here must implement the EPPTG_TAGS:TaggedContent application class.

Remote Interface

The following page shows the Tagging Namespace page with the Remote Interface option selected.

Mapping Namespaces to Search Index Groups

Namespaces are mapped to Enterprise Portal search index groups. One namespace can be mapped to only one search index group. Tags are added to only those indexes in the index group that are selected in the grid labeled Select Index to Add Tags. If the index group name is changed then all the indexes selected in the grid are dropped from the mapping.

See Also

Administering Search Indexes

Implementing Tagging Web Services

A PeopleSoft application can incorporate tagging in its pages by configuring the tag service using the related content framework. However, these tags are primarily tied to the transcation instances of the business component and do not give the flexibility to add tags to data elements that are available across the various levels of the page. Using the tagging web service, developers can add tags to any data element at any level in the page.

Adding a Tag

The following parameters are required to add a tag:

Ideally a content reference (CREF) corresponds to a namespace, but it is not necessary. A namespace is just a logical grouping of tags, just as a domain is a logical grouping of tags in an application.

Tagging an External Application

Tags can also be used by external (non-PeopleSoft) applications using the tagging web service. However, in this case the complete URL has to be sent in the input message instead of the relative URL. The important point to note here is that the URL string must start with HTTP://.

This differentiates external application tags from PeopleSoft system tags. The differentiation is needed to prevent the suffixing of a portal URI to form an absolute URL, which occurs in the case of PeopleSoft system tags. In this case the portal name is just a string.

Configuring Tagging Web Services

Follow these steps to configure tagging web services:

1. Create a tag domain using the Application Tag domain page (Portal Administration, Tagging, Tagging Domain) before using the web service.

2. Create a separate domain that is mapped to a node for each PeopleSoft and each non-PeopleSoft application.

   The node type of the node used in the web service must be External.

3. Create unique URLs.

   The URL for different content in a PeopleSoft system or non-PeopleSoft system must be unique.

   With a PeopleSoft system you must use the GenerateComponentRelativeURL function to provide a relative URL. This will be concatenated with the portal URI of the node assigned to the system. Use a relative URL instead of an absolute URL to address the issue of possible change of the server.

   With external system tags you must provide the absolute URL. The URL provided for external system content must start with http://. A URL is identified as belonging to an external system only by the presence of the string http:// at the beginning.

Web Services Command Format

Tagging web services use the following command format:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>ADD_TAGS</cmd>
    <id>
      <node>PSHR</node>
      <portal>EMPLOYEE</portal>
      <ns>JOBS</ns>
      <url>s/JOBPAGE.GBL/?ID=1</url> 
    </id>
      <tags>dream</tags>
      <type>public</type>  
      <label>Job Page</label>              
      <descr>Job Details Page</descr>      
  </tagop>
</tagging>

Command Format Parameters

Basic Tag Commands

This section describes the implementation of the basic tag commands:

• ADD_TAGS

• MODIFY_TAGS

• CLEAR_TAGS

• REMOVE_TAGS

• GET_TAGS

Basic Input

This is an example of input for a basic tag command:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>ADD_TAGS</cmd>
    <id>
      <node>PSHR</node>
      <portal>EMPLOYEE</portal>
      <ns>JOBS</ns>
      <url>s/JOBPAGE.GBL/?ID=1</url> 
    </id>
      <tags>dream</tags>
      <type>public</type>  
      <label>Job Page</label>              
      <descr>Job Details Page</descr>      
  </tagop>
</tagging>

This is an example of input for a basic external system tag.

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>ADD_TAGS</cmd>
    <id>
      <node>Tag</node>
      <portal>EMPLOYEE</portal>
      <ns>JOBS</ns>			[ case sensitive]
      <url>http://Monster.com/?ID=2</url> 
    </id>
      <tags>bad, low-paying</tags>
      <type>public</type>  			[ public or private ] 
      <label>Find Jobs</label>              
      <descr>You can search for Jobs here...</descr>      
  </tagop>
</tagging>

Basic Input Parameters

Basic Output

The following xml is an example of output for these commands:

• ADD_TAGS

• MODIFY_TAGS

• CLEAR_TAGS

• REMOVE_TAGS

<?xml version=""1.0""?>
<TagResponse>
  <Status>1</Status>
  <ErrorMsg>Invalid Node</ErrorMsg>
</TagResponse>

Basic Output Parameters

Get Ouput

This is an example of output for the GET_TAGS command:

<?xml version=""1.0""?>
<TagResponse>
  <Status>0</Status>
  <Tag type="public">
    <a class="EPPTGTAGTEXT" href="http://localhost/psc/ps_newwin/EMPLOYEE/EMPL/c/
     EPPTG_TAGGING.EPPTG_TAG_BROWSE.GBL? 
Page=EPPTG_TAG_BROWSE&amp;Action=U&amp;EPTG=1&amp;TAG=dream" 
  target="newwin">dream</a>
  </Tag>
  <Tag type="private">
    <a class="EPPTGTAGTEXT" href="http://localhost/psc/ps_newwin/EMPLOYEE/EMPL/c/
      EPPTG_TAGGING.EPPTG_TAG_BROWSE.GBL? 
Page=EPPTG_TAG_BROWSE&amp;Action=U&amp;EPTG=1&amp;TAG=private" 
  target="newwin">private</a>
  </Tag>
</TagResponse>

Get Output Parameters

Add Operation

The Add operation adds tags to content. Repeated invocation of Add on the same content URL will append tags to the existing list of tags for the content.

Modify Operation

Modify is similar to Add except that each invocation of Modify on a content URL will overwrite the existing tags for the content. Add and Modify have the same message format.

Clear Operation

The Clear operation is used to clear all the tags of a content for a particular user.

The Clear operation has a <type> parameter that can take the values public, private, and all. Invoking Clear with <type>all</type> is equivalent to invoking clear twice, once with <type>public</type> and once with <type>private</type>.

Clear Input

This is an example of input for Clear:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>CLEAR_TAGS</cmd>
    <id>
      <node>TAG</node>
      <portal>EMPLOYEE</portal>
      <ns>JOBS</ns>
      <url>S/JOBPAGE.GBL/?ID=4</url>
    </id>      
      <type>public</type> 		[ public or private or all ]
  </tagop>
</tagging>

Remove Operation

The Remove operation removes the tags specified in the request message. Tag removal can be performed for a particular user or for all users using the <all_user> node. If <all_user> is set to Y then tags will be removed for all users. Type = private and all_user=Y is an invalid combination and will be captured in the validation.

Remove Input

The following is an example of input for Remove:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>REMOVE_TAGS</cmd>
    <id>
      <node>TagHR</node>
      <portal>EMPLOYEE</portal>
      <ns>JOBS</ns>
      <url>s/JOBPAGE.GBL</url> 
    </id>
      <tags>Colloborative, Best, dram, Schrewd</tags>
      <type>public</type>  
      <all_user>y</all_user>		[ y or n]
  </tagop>
</tagging>

Get Operation

The Get operation returns the public and private tags available for a particular content URL.

Search Operation

A search can be performed at the domain or namespace level. While domain is mandatory for any search operation, namespace is an optional parameter for the Search web service.

The number of results that are returned is set using the optional node <num_results>. Output contains a search result label, description, URL, and related tags information. A tag browser URL (which can be set in the Application Domains page) is provided once in the output message at the same level as the results node.

Search Input

This is an example of input for Search:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>SEARCH_TAGS</cmd>
    <domain>PSHR</domain>
    <ns>PSHR</ns>
    <num_results>5</num_results>       
    <search>dream</search>
  </tagop>
</tagging>

Search Input Parameters

Search Output

This is an example of output for Search:

<?xml version="1.0"?>
<TagSearchResults>
  <Status>0</Status>
  <Result>
    <Label>Job Page</Label>
    <Description>Job Details Page</Description>
    <RelatedTags>dream</RelatedTags>
    <Url>http://ape.peoplesoft.com/psp/ps_newwin/S/JOBPAGE.GBL</Url>
  </Result>
  <Result>
    <Label>BenefitsPage</Label>
    <Description>BenefitsPage Details Page</Description>
    <RelatedTags>dream</RelatedTags>
    <Url>http://ape.peoplesoft.com/psp/ps_newwin/S/JOBPAGE.GBL/ID=2</Url>
  </Result>
  <Result>
    <Label>Movies</Label>
    <Description>Great Movies</Description>
    <RelatedTags>Sequel, dream</RelatedTags>
    <Url>HTTP://WWW.YAHOO.COM/ID=2</Url>
  </Result>
</TagSearchResults>

Search Output Parameters

Tag Cloud Operation

The tag cloud is a visual representation of tags currently used in the system. Different font sizes help visualize the usage patterns of tags. Larger fonts depict more frequently used tags, while smaller fonts depict less frequently used tags.

Tag Cloud Input

This is an example of input for Tag Cloud:

<?xml version="1.0"?>
<tagging>
  <tagop lang="ENG" userid="VP1">
    <cmd>TAG_CLOUD</cmd>
    <scope>DOMAIN=PSFT_HR,TAG_NS=JOBS</scope>  
     <num_results>100</num_results>
    <sort>ALPHA-D</sort>  
    <period>90</period>        
    <personal_cloud>true</personal_cloud>  
  </tagop>
</tagging>

Tag Cloud Input Parameters

Tag Cloud Output

This is an example of output for Tag Cloud:

<?xml version="1.0"?>
<TagSearchResults>
  <Status>0</Status>
  <TagBrowserUrl>http://localhost/psc/ps_newwin/EMPLOYEE/EMPL/c/
   EPPTG_TAGGING.EPPTG_TAG_BROWSE.GBL? 
   Page=EPPTG_TAG_BROWSE&amp;Action=U&amp;EPTG=1&amp;TAG=</TagBrowserUrl>
  <TagCloud>
    <Tag Count="1" Size="80%" Weight="normal">VP</Tag>
    <Tag Count="10" Size="120%" Weight="normal">Sequel</Tag>
    <Tag Count="5" Size="100%" Weight="normal">Mobile</Tag>
    <Tag Count="5" Size="100%" Weight="normal">Manager</Tag>
  </TagCloud>
</TagSearchResults>

Tag Cloud Output Parameters

Tag Browser

The search result links that correspond to tags added using web service must open in a new window.

For search results that correspond to PeopleSoft system tags, the portal URI entered at the node definition page must be concatenated with the relative URL provided in the input message. The complete URL that is obtained by appending the node's portal URI and relative URL should give a complete and valid PeopleSoft URL.

The search results corresponding to non-PeopleSoft system tags will have the same URL as supplied in the input message. In the case of external system tags the URL supplied must be a full URL and must start with http://. The URL is used as such in the search results in tag browser as it is a complete URL.

Each domain in the application domain page will have a scope corresponding to it in the tag browser page.