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.

The following parameters are required to add a tag:

Field or Control

Description

Node

Node corresponds to the tag domain. Nodes can be associated with a domain using the Tagging Application Domain page in PeopleSoft Interaction Hub (Portal Administration, Tagging, Tagging Domain). Nodes used in tagging web service must be of the type External. When a search is performed, this differentiates between the tags added through the web service and those added through the related content framework.

Portal

This corresponds to the portal name of the application.

The Portal value can be any string.

Namespace

Namespace is like a Java package. It helps in logical grouping of tags. If the namespace is not preconfigured in PeopleSoft Interaction Hub then a namespace is automatically created in the name of the domain.

URL

URL acts as a key. URL maps directly to content. If two URLs are the same then the tags are added to the same content. It is the user's responsibilty to provide unique URLs for the content that is to be tagged. Unique URLs can be generate by concatenating the relative URL of a component with the necessary keyvals. The URL supplied for tagging a PeopleSoft application must be a relative URL and not an absolute URL. This way if the server name changes then the URL also changes. When the user tries to retrieve the tags for content tagged prior to the server name change the operation will fail as the new url will not point to the tags previously added. Use the GenerateComponentRelativeURL function or GenerateComponentPortalURL function to generate the relative URL. The relative URL that is passed with the input message is concatenated with the node URI set in the node definition page to get the complete URL.

See the product documentation for PeopleTools: PeopleCode Language Reference, PeopleCode Built-in Functions, GenerateComponentRelativeURL, PeopleTools: PeopleCode Language Reference, PeopleCode Built-in Functions, GenerateComponentContentRelURL.

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.

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.

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

Field or Control

Description

lang

This corresponds to the language the user has entered their tags in. Use PeopleSoft language codes. The default is the system default (%language_base).

userid

The user ID that entered the tag. The user ID must be a valid PeopleSoft user.

cmd

The command value.

Possible values are:

  • ADD_TAGS

  • MODIFY_TAGS

  • CLEAR_TAGS

  • REMOVE_TAGS

  • GET_TAGS

  • SEARCH_TAGS

  • TAG_CLOUD

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

Field or Control

Description

id

This is a required parameter for the following commands:

  • ADD_TAGS

  • MODIFY_TAGS

  • CLEAR_TAGS

  • REMOVE_TAGS

  • GET_TAGS

node

The name of the node that sent the command

portal

The portal name. If the tagging system is non-PeopleSoft, define a standard value that is used by all your tag commands.

ns

The tagging namespace.

url

The URL the tags are associated with.

tags

The comma separated list of tags that are being manipulated.

This is a required parameter for the following commands:

  • ADD_TAGS

  • MODIFY_TAGS

  • REMOVE_TAGS

type

Valid values are:

  • public – these tags are viewable by all users for the content.

  • private – these tags are viewable only by the user who created the tags.

This is a required parameter for the following commands:

  • ADD_TAGS

  • MODIFY_TAGS

  • CLEAR_TAGS

  • REMOVE_TAGS

  • GET_TAGS

label

The label parameter is used for tag searching in the tag browser. This value is shown as the link title of the piece of content that contains the tag that has been searched.

This is a required parameter for ADD_TAGS.

It is an optional parameter for MODIFY_TAGS.

descr

This is the description for tag searching in the tag browser. This value is shown as the short description below the title for the piece of content that's been searched.

This is a required parameter for the following commands:

  • ADD_TAGS

  • MODIFY_TAGS

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

Field or Control

Description

Status

The status of the command.

  • 0 - Success

  • Non 0 - Error. (All errors default to 1.)

ErrorMsg

If Status is a value other than 0, then the xml node is returned with a message detailing the error.

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

Field or Control

Description

Status

The status of the command.

  • 0 – Success

  • Non 0 – Error. (All errors default to 1.)

ErrorMsg

If Status is a value other than 0, then the xml node is returned with a message detailing the error.

Tag

One tag node is returned for each tag.

type

Valid values are:

  • public – these tags are viewable by all users for the content.

  • private – these tags are viewable only by the user who created the tags.

The anchor tag is a standard HTML link for the tag to the defined tag browser page.

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

Field or Control

Description

lang

This corresponds to the language the user has entered their tags in. Use PeopleSoft language codes. The default is the system default (%language_base).

userid

The user ID that entered the tag. The user ID must be a valid PeopleSoft user.

cmd

The command value – SEARCH_TAGS.

domain

The tagging domain that is being searched.

This is a required parameter.

ns

The namespace that is being searched.

This is an optional parameter.

The default is to search all namespaces within the domain.

num_results

The maximum number of results to return.

This is a required parameter.

search

The tag that is being searched.

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

Field or Control

Description

Status

The status of the command.

  • 0 - Success.

  • Non 0 - Error. (All errors default to 1.)

ErrorMsg

If Status is a value other than 0, then the xml node is returned with a message detailing the error.

Result

Each row of data is returned as a Result.

  • Label – The short description of a search result.

  • Description – The long description of a search result.

  • RelatedTags – Any tags associated with the search result are listed here, comma separated.

  • Url – link to the search result.

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

Field or Control

Description

lang

This corresponds to the language the user has entered their tags in. Use PeopleSoft language codes. The default is the system default (%language_base).

userid

The user ID that entered the tag. The user ID must be a valid PeopleSoft user.

cmd

The command value – TAG_CLOUD

scope

This defines where tags are retrieved to generate the cloud. Specify values in KEY=VALUE pairs separated by a comma. Valid Keys are:

  • DOMAIN – The tagging application domain. This key is required.

  • TAG_NS – A namespace associated in the domain.

This key is optional.

If no namespace is defined, all tags from the domain are used.

num_results

The maximum number of results to show in the tag cloud.

This is a required parameter.

search

The tag that is being searched.

sort

The sort order of the tag cloud.

Possible values are:

  • ALPHA-A – Alphabetical ascending A-Z.

  • ALPHA-D – Alphabetical descending Z-A.

  • COUNT-A – Count ascending 0-X.

  • COUNT-D – Count descending X-0.

  • ATIME-A –: List tags oldest added time first.

  • ATIME-D – List tags newest added time first.

This is an optional parameter.

The default is ATIME-D.

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

Field or Control

Description

Status

The status of the command.

  • 0 - Success.

  • Non 0 - Error. (All errors default to 1.)

ErrorMsg

If Status is a value other than 0, then the xml node is returned with a message detailing the error.

TagBrowserUrl

The URL to the tag browser.

TagCloud

Contains all the tags in the tag cloud.

Tag

The tag with these attributes:

  • Count – How often the tag is used to link a piece of content.

  • Size – The default suggested sizing of the tag.

  • Weight – Suggested weighting of the tag.

    Possible values are:

    • lighter

    • normal

    • bold

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.