-- DenisTyrell - 03 Mar 2010

Tag: a keyword or term associated with or assigned to a piece of information

Tagging Support

A variety of tagging support is available from different CM providers and the level of support from the provider should be discoverable. It will generally be one of the following types:

1) Simple text values that can be arbitrarily added to a CM item (Ex: The provider defines a single text field with a comma delimited list of keywords)

2) Structured values that can only be added from a list of existing tags (Ex: The provider defines a collection of tag objects for each CM item)

Tag Handling

The OSLC layer should abstract the handling of tags so that a common tagging interface is exposed through OSLC.

Consumers should be able to:

1) Retrieve a collection of tags that are applied to a particular CM item

2) Add/Remove a tag from the collection of tags for a particular CM item

3) Query a repository and return a collection of CM items that have a specific tag or list of tags applied to them

4) [Optional] Retrieve the list of all available tags for a repository. (This may return no tags or not be implemented by the provider)

5) [Optional] Add a tag to the list of available tags for a repository. (This might not be implemented by the provider)

6) [Optional] Remove a tag from the list of available tags for a repository. (This might not be implemented by the provider)

How to determine the type of tag being used

At Change Request level, define a new property oslc_cm:TagSupport to find out the tag type being used

• Use the existing dc:subject to indicate free form, or comma delimited, tag
  <oslc_cm:TagSupport>dc:subject</oslc_cm:TagSupport>
• Use a new property oslc_cm:TagResource to indicate structured tag
  <oslc_cm:TagSupport>oslc_cm:TagResource</oslc_cm:TagSupport>

Define Tag as a New OSLC Resource

Similar to Change Request, tag can be defined as an OSLC resource. Following the OSLC core spec, the Tag resource may be defined as:

OSLC Domain	Namespace URI (URI)	http://open-services.net/xmlns/oslc-core-1.0#
OSLC Domain	Default Prefix (String)	oslc
OSLC Resource	Name (String)	Tag
OSLC Resource	Type URI (URI)	http://open-services.net/xmlns/oslc-core-1.0#Tag
OSLC Resource	Version String (String)	oslc-cm-2.0
OSLC Property	Title (String)	Tag
OSLC Property	Description (String)
OSLC Property	Occurs (String)	one-or-many
OSLC Property	Value-type (URI)	Resource
OSLC Common Property	dc:title, dc:description, dc:creator, dc:created, dc:modified, dc:contributor
Tag Specific Property	visibility	public, team, or private
Tag Specific Property	scope	all, project

It is optional to support tag management on the CRUD operations. The tag related query and CRUD operation can be handled pretty much the same way as any resource like Change Request.

Define ResourceTag? as a New OSLC Resource

Name: ResourceTag?
Type URI: http://open-services.net/xmlns/cm/2.0#ResourceTag
Version: 2.0
Description: Tag applied to or associated with the artifact or any OSLC resource
dc:identifier (exactly-one)
dc:creator (exactly-one)
dc:created (exactly-one)
dc:title (XMLLiteral xhtml, exactly-one)
dc:description (exactly-one)
oslc_cm:tagDefIdentifier (exactly-one)

Add a new Tags property on Change Request

Name: Tags
Description: The Tags property holds a reference to the set of all tags that are applied to the change request

Occurs: zero-or-one
Value-type: Resource URI (rdf:resource attribute). On return it provides a collection of ResourceTag? .
Version: 2.0

Sample Change Request Tags

For structured tags, <oslc_cm:tags> is used to define the collection of tags associated with the change request:
<oslc_cm:tags>
<oslc_cm:url> https://rtc:9443/jazz/oslc/contexts/workitems/ WI123[/tags]</oslc_cm:url>
</oslc_cm:tags>

After the client runs the above tag query, the returned tag collection for the change request may look like:

< oslc_cm:tag>
<dc:identifier>WITAG001</dc: identifier >
<dc:title>Stopper</dc:title>
<dc:description>Show stopper and needs to be fixed ASAP</dc:description>
<dc:creator>U423</dc:creator>
<dc:created>04-01-2010T17:42:30</dc:created>
</oslc_cm:tag>
< oslc_cm:tag>
<dc:identifier>WITAG011</dc:identifier>
<dc:title>FinishToday</dc:title>
<dc:description> Item needs to be done by the end of the day </dc:description>
<dc:creator>U456</dc:creator>
<dc:created>03-01-2010T11:22:36</dc:created>
</oslc_cm:tag>

Retrieve Tags on Change Request

To retrieve the tags applied to the change request, add the oslc_cm:tags request parameter to the attribute profile as part of the GET:
GET https://rtc.com:9443/jazz/resource/itemOid/com.ibm.team.workitem.WorkItem/WI123?oslc_cm.properties=dc:title,oslc_cm:tags
Accept: application/x-oslc-cm-change-request+xml

The call returns the following:
<oslc_cm:ChangeRequest
xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" xmlns:oslc_disc="http://open-services.net/xmlns/discovery/1.0/"
xmlns:dc="http://purl.org/dc/terms/" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/"
xmlns:jp="http://jazz.net/xmlns/prod/jazz/presentation/1.0/" xmlns:jd="http://jazz.net/xmlns/prod/jazz/discovery/1.0/"
xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/" xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:calm="http://jazz.net/xmlns/prod/jazz/calm/1.0/">
<dc:title>My First Bug</dc:title>
< oslc_cm:tags oslc_cm:collref="https://rtc:9443/jazz/oslc/WI123/workitems/tags" />
</oslc_cm:ChangeRequest>

Apply Tags to Change Requests

Using the new resource Tag defined above, <oslc_tag:selectionDialog/> can be used to show available tags to use and apply to the underlining change request:

<oslc_tag:selectionDialog calm:id=" tag "
oslc_cm:hintWidth="550px" oslc_cm:hintHeight="360px">
<dc:title>Tag Selection</dc:title>
<oslc_tag:url> https://rtc:9443/jazz/_ajax-modules/com.ibm.team.tag.tagPicker?projectAreaName=MyProject&dc%3Atype=tag</oslc_tag:url>
</oslc_tag:selectionDialog>

End user can multi-select the appropriate tags from the dialog. Client needs to handle the <oslc_cm:tags/> creation (if the change request has no tags), or modification (if the change request has already had some tags.)

When commit the changes, need to provide a collref of ResourceTag? .

Find Change Requests that Have a List of Tags Applied

There are 2 ways to query. One is to use the 'simple query' service:
GET https://rtc:9443/jazz/oslc/contexts/_gasc4Ju-Ed6cerS9lb5AWw/workitems?oslc_cm.query = oslc_cm:tags in "Stopper, Blocked" and dc:modified>="04-02-2010T18:42:30"
&oslc_cm.properties=dc:title
Accept: application/x-oslc-cm-change-request+xml

The second way is to extend the Change Request 'selectionDialog' service to add tag field for filtering.