E
dit
A
ttach
P
rintable
r6 - 2017-01-05 - 19:59:37 - Main.Websmith
You are here:
TWiki
>
Deployment Web
>
CLMOSLCAPIChangesFor601
<div id="header-title" style="padding: 10px 15px; border-width:1px; border-style:solid; border-color:#FFD28C; background-image: url(<nop>https://jazz.net/wiki/pub/Deployment/WebPreferences/TLASE.jpg); background-size: cover; font-size:120%"> ---+!! CLM Version 6.0.1 OSLC API Changes for Enumerations <img src="https://jazz.net/wiki/pub/Deployment/WebPreferences/todo.png" alt="todo.png" width="50" height="50" align="right"> %DKGRAY% Authors: Main.LarrySmith<br> Build basis: Products, editions, or versions that apply to the content. If no build basis applies to this content, set the build basis to None. %ENDCOLOR%</div></sticky> <!-- Page contents top of page on right hand side in box --> <sticky><div style="float:right; border-width:1px; border-style:solid; border-color:#DFDFDF; background-color:#F6F6F6; margin:0 0 15px 15px; padding: 0 15px 0 15px;"> %TOC{title="Page contents"}% </div></sticky> <sticky><div style="margin:15px;"></sticky> This document describes some changes made to the OSLC V2.0 API in RTC Version 6.0.1. The changes were made to enable specific reports that required the API to be more compliant with the standard. There are two OSLC REST API changes made in 6.0.1 that could potentially break scripts that use the OSLC REST API from prior versions. These changes are considered improvements over previous releases and were necessary for standards compliance and to enable cross-project reporting to work in Report Builder. * The first item changes the way enumerations literal URI's are specified in responses. * The second item changes the response to a JSON request for an enumeration so it is a JSON object instead of array of literals. ---++ The Resource URI of an Enumeration Literal Changes in RTC Version 6.0.1 RTC allows user to specify External Value of enumeration literal. The literal is configured in the project area administration as follows: <br/><img src="%ATTACHURLPATH%/oslc-fig1-Low.png" alt="oslc-fig1-Low.png" width="800"/> The way this literal is returned in an OSLC response has changed in RTC Version 6.0.1 ---+++ Before RTC Version 6.0.1: Enumeration without an External Value *Before RTC Version 6.0.1*, consider an enumeration literal without an external value: <br/><img src="%ATTACHURLPATH%/oslc-fig2-Low.png" alt="oslc-fig2-Low.png" width="800" /> Before RTC Version 6.0.1, if user doesnt specify an External Value and then does an OSLC GET on the enumeration literal resource, the literal is referenced with the internal value: <verbatim> <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1"> </verbatim> For example, a GET request: <br/><img src="%ATTACHURLPATH%/oslc-fig3-GET.png" alt="oslc-fig3-GET.png" width="800" /> <br/><img src="%ATTACHURLPATH%/oslc-fig5a-GET-xml.png" alt="oslc-fig5a-GET-xml.png" width="800"/> would return a response: <verbatim> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1"> <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/> <rtc_cm:iconUrl rdf:resource="https://localhost:9443/ccm/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/> <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title> <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier> </rdf:Description> </rdf:RDF> </verbatim> This does not change in RTC Version 6.0.1 because there is no external value. ---+++ Before RTC Version 6.0.1: Enumeration with an External Value *Before RTC Version 6.0.1*, consider an enumeration literal with an external value: <br/><img src="%ATTACHURLPATH%/oslc-fig5-Low.png" alt="oslc-fig5-Low.png" width="800" /> Before RTC Version 6.0.1, if user does specify an external value and then does an OSLC GET on the enumeration literal resource, the literal is referenced with the external value: <verbatim> <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"> </verbatim> Notice how the literal value is used in the reference URI. For example, a GET request: <br/><img src="%ATTACHURLPATH%/oslc-fig6-GET.png" alt="oslc-fig6-GET.png" width="800"/> would return a response: <verbatim> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > <rdf:Description rdf:about="https://localhost:9443/ccm/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"> <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/> <rtc_cm:iconUrl rdf:resource="https://localhost:9443/ccm/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/> <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title> <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier> </rdf:Description> </rdf:RDF> </verbatim> When the external value changes, these URI's will note be valid anymore. ---++ After RTC Version 6.0.1 the URI is Stable One drawback of the initial implementation is that the enumeration literal resource URI is not stable. The URI can change if the user changes the enumeration value of the enumeration literal. Since the enumeration literal URI is embedded in every work item and enumeration resources referenced, the links and data becomes invalid when the enumeration value changes. In 6.0.1 release, the URI is made more stable by always using the internal literal value in the reference and adding an _owl:sameAs_ triple in the resource to map the value properly. The value of owl:sameAs triple is the external URI of the enumeration literal. For more information see <a href="https://jazz.net/wiki/bin/view/LinkedData/UseUrisForEnums" >Best Practice: Use URIs to Represent Enumerated Values</a>. ---+++ After RTC Version 6.0.1: Enumeration with External Value In RTC Version 6.0.1 and later, consider if user does specify external value for the literal: <br/><img src="%ATTACHURLPATH%/oslc-fig5-Low.png" alt="oslc-fig5-Low.png" width="800" /> Now when an OSLC GET is requested for the enumeration literal resource, the literal is referenced with the internal value and an _owl:sameAs_ element is added: <verbatim> <rdf:Description rdf:about="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1"> ... <owl:sameAs rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"/> ... </verbatim> Notice how the literal value is not used in the reference URI and is mapped by the _owl:sameAs_ element. Now the administrator is free to change the literal value without invalidating the links. Because the _owl:sameAs_ resolves the links correctly, the pre-6.0.1 user scenarios is still supported as the literal resource can be accessed using either URI. For example, a GET request: <br/><img src="%ATTACHURLPATH%/oslc-fig6a-GET.png" alt="oslc-fig6a-GET.png" width="800" /> would return a response: <verbatim> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#" xmlns:dcterms="http://purl.org/dc/terms/" xmlns:j.0="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/" xmlns:rtc_cm="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/" > <rdf:Description rdf:about="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/priority.literal.1"> <rdf:type rdf:resource="http://jazz.net/xmlns/prod/jazz/rtc/cm/1.0/Literal"/> <rdf:type rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority"/> <owl:sameAs rdf:resource="https://localhost:9443/jazz/oslc/enumerations/_gxHFEC51EeauNJ_abwY7Dg/priority/low"/> <rtc_cm:iconUrl rdf:resource="https://localhost:9443/jazz/service/com.ibm.team.workitem.common.internal.model.IImageContentService/processattachment/_gxHFEC51EeauNJ_abwY7Dg/enumeration/low.gif"/> <dcterms:title rdf:datatype="http://www.w3.org/2001/XMLSchema#string">Low</dcterms:title> <dcterms:identifier rdf:datatype="http://www.w3.org/2001/XMLSchema#string">priority.literal.1</dcterms:identifier> </rdf:Description> </rdf:RDF> </verbatim> The new URI format is more stable for some configurations. ---++ Enumeration Requests Return a JSON Object instead of an Array Before RTC Version 6.0.1, when user gets an application/json representation of an enumeration resource, the returned resource was returned as a JSON array of enumeration literals. However, array returned for the enumeration resource does not contain any information about the enumeration itself. It only lists the enumeration literals. In 6.0.1, a JSON object is returned instead, and this includes information about enumeration itself in the resource representation. ---+++ Before RTC Version 6.0.1: Enumeration JSON Response For example, *before RTC Version 6.0.1*, a GET request: <br/><img src="%ATTACHURLPATH%/oslc-fig9-GET-json.png" alt="oslc-fig9-GET-json.png" width="800"/> would return an array as a response. <verbatim> [ { "rdf:type":[ { "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal" } ], "rtc_cm:iconUrl":"https:\/\/localhost:9443\/ccm\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/low.gif", "dcterms:title":"Low", "rdf:about":"https:\/\/localhost:9443\/ccm\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.1", "dcterms:identifier":"priority.literal.1" }, { "rdf:type":[ { "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal" } ], rtc_cm:iconUrl":"https:\/\/localhost:9443\/ccm\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/high.gif", "dcterms:title":"High", "rdf:about":"https:\/\/localhost:9443\/ccm\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.2", "dcterms:identifier":"priority.literal.2" } ] </verbatim> The array only provides information about the literals and does not contain any information about the enumeration. ---+++ After RTC Version 6.0.1: Enumeration JSON Response *After RTC Version 6.0.1*, the resource is returned as a a JSON object. For example, in RTC Version 6.0.1, a GET request: <br/><img src="%ATTACHURLPATH%/oslc-fig10-GET-json.png" alt="oslc-fig10-GET-json.png" width="800" /> now returns a JSON object as a response: <verbatim> { "rdf:type": [ { "rdf:resource":"http:\/\/www.w3.org\/2000\/01\/rdf-schema#Class" } ], "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority", "acc:accessContext": { "rdf:resource":"https:\/\/localhost:9443\/jazz\/acclist#_gxHFEC51EeauNJ_abwY7Dg" }, "prefixes": { "rtc_cm":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/", "oslc":"http:\/\/open-services.net\/ns\/core#", "owl":"http:\/\/www.w3.org\/2002\/07\/owl#", "rdf":"http:\/\/www.w3.org\/1999\/02\/22-rdf-syntax-ns#", "acc":"http:\/\/open-services.net\/ns\/core\/acc#", "dcterms":"http:\/\/purl.org\/dc\/terms\/" }, "oslc:results": [ { "rdf:type": [ { "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority" }, { "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal" } ], "rtc_cm:iconUrl":"https:\/\/localhost:9443\/jazz\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/low.gif", "dcterms:title":"Low", "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.1", "dcterms:identifier":"priority.literal.1" }, { "rdf:type": [ { "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority" }, { "rdf:resource":"http:\/\/jazz.net\/xmlns\/prod\/jazz\/rtc\/cm\/1.0\/Literal" } ], "rtc_cm:iconUrl":"https:\/\/localhost:9443\/jazz\/service\/com.ibm.team.workitem.common.internal.model.IImageContentSe rvice\/processattachment\/_gxHFEC51EeauNJ_abwY7Dg\/enumeration\/high.gif", "dcterms:title":"High", "rdf:about":"https:\/\/localhost:9443\/jazz\/oslc\/enumerations\/_gxHFEC51EeauNJ_abwY7Dg\/priority\/priority.literal.2", "dcterms:identifier":"priority.literal.2" } ] } </verbatim> Here we see more information about the Enumeration available in the object attributes. ---+++++!! External links: Referenced Items: * <a href="https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=366205">Task 366205: Enumeration owl:sameAs implementation does not work as expected]</a> * <a href="https://jazz.net/jazz/web/projects/Rational%20Team%20Concert#action=com.ibm.team.workitem.viewWorkItem&id=360439">Task 360439: Enumeration should have rdf:type of rdfs:Class & Enumeration Literal should have rdf:type of its owner Enumeration</a> <sticky></div></sticky>
E
dit
|
A
ttach
|
P
rintable
|
V
iew topic
|
Backlinks:
We
b
,
A
l
l Webs
|
H
istory
: r6
<
r5
<
r4
<
r3
<
r2
|
M
ore topic actions
Deployment
Deployment web
Planning and design
Installing and upgrading
Migrating and evolving
Integrating
Administering
Monitoring
Troubleshooting
Community information and contribution guidelines
Create new topic
Topic list
Search
Advanced search
Notify
RSS
Atom
Changes
Statistics
Web preferences
NOTE: Please use the Sandbox web for testing
Status icon key:
To do
Under construction
New
Updated
Constant change
None - stable page
Smaller versions of status icons for inline text:
Copyright © by IBM and non-IBM contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our
Terms of Use.
Please read the following
disclaimer
.
Dashboards and work items are no longer publicly available, so some links may be invalid. We now provide similar information through other means. Learn more
here
.