It's all about the answers!

Ask a question

Practicalities of the RTC 2.0 Rest APIs


Adrian Spender (36143) | asked Sep 15 '09, 9:58 a.m.
Hi,

I am trying to accomplish the relatively simple use case of programatically creating a new defect work item in my RTC 2.0 project. I'm doing this in Java, but that isn't relevant for this question.

So far:

- I have retrieved the service document
- From that I have retrieved the change management catalog
- From that I have found my project area and retrieved its service document

So, I have the URL to which I can POST new work items. However, looking at the example at:

https://jazz.net/wiki/bin/view/Main/ResourceOrientedWorkItemAPIv2#Creating_Work_Items

and I am wondering how exactly I can obtain the resource URLs for a number of items in my work item such as the filed against category and an owner.

For instance, in the example, the filed against is set to:

https://publicuri.test.org:9443/jazz/resource/itemOid/com.ibm.team.workitem.Category/_-hBTUEqVEd6HXO10niqZpg

How can I discover the URIs for the categories my project defines?

When retrieving a work item, I note that authors/owners/subscribers are represented like this:

https://myserver/jazz/oslc/users/_bXh-MI2KEd67ZIuoGFYkQg

Which when requested returns a parseable document with user information, but again how can I do the reverse and take information such as a userid and obtain the URI for that user?

I've looked through the change management and project area service documents but can't see anything obvious to try and retrieve. Also, I've not found documentation for querying anything other than work items.

Any clues?

16 answers



permanent link
Tristan Ratchford (16) | answered Sep 09 '11, 1:52 p.m.
Hi Nick,

It works! Thank you very much for the help!

Tristan

I played around with it a bit using the REST Client plugin.
A post to: https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/drafts/workitems
with the headers and body you gave resulted in a body of:

{
"oslc_cm:message": "Missing expected parameter: http:\/\/purl.org\/dc\/terms\/type",
"oslc_cm:status": 400
}

If I add the type, so body is:
 {"dc:title":"UserFeedback","dc:type":"defect"} 

then I get back a result where the body is the JSON for the draft work item, and the Location header has its URL.

You would then bring the user to that URL, which will redirect to the web UI, and let them complete the draft item and save it.

permanent link
Nick Edgar (6.5k711) | answered Sep 09 '11, 11:48 a.m.
JAZZ DEVELOPER
The types are at, e.g.:
https://jazz.net/jazz/oslc/types/_1w8aQEmJEduIY7C8B09Hyw
where the UUID is the context id (aka project area item id). Not sure if this is part of the OSLC_CM spec. I don't think it is.

The dc:type field when creating the work item should be one of the dc:identifiers for the listed types, e.g. "defect" or "task". It may also accept the type's URI, e.g. https://jazz.net/jazz/oslc/types/_1w8aQEmJEduIY7C8B09Hyw/task

permanent link
Nick Edgar (6.5k711) | answered Sep 09 '11, 11:40 a.m.
JAZZ DEVELOPER
I played around with it a bit using the REST Client plugin.
A post to: https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/drafts/workitems
with the headers and body you gave resulted in a body of:

{
"oslc_cm:message": "Missing expected parameter: http:\/\/purl.org\/dc\/terms\/type",
"oslc_cm:status": 400
}

If I add the type, so body is:
 {"dc:title":"UserFeedback","dc:type":"defect"} 

then I get back a result where the body is the JSON for the draft work item, and the Location header has its URL.

You would then bring the user to that URL, which will redirect to the web UI, and let them complete the draft item and save it.

permanent link
Tristan Ratchford (16) | answered Sep 09 '11, 11:34 a.m.
The guidance and tools mentioned in the OSLC Workshop may be helpful too: https://jazz.net/library/article/635


Hi Nick,

Thanks for the help! I'm new at web programming and forgot to check the HttpResponse entity (message).

I changed my JSONOBject as follows:


JSONObject lWorkItemJSON = new JSONObject();
lWorkItemJSON.put("dc:title", "UserFeedback");
lWorkItemJSON.put("dc:description", "Descriptions");



And the message reads :


{
"oslc_cm:message": "Missing expected parameter: http:\/\/purl.org\/dc\/terms\/type",
"oslc_cm:status": 400
}


This seems pretty straight-forward. I figure all I need to do is define what type of Work Item my draft Work Item will be (e.g. Task, Story etc).

However, I do have a further question. From the examples it seems that the Work Item Types are defined in our project area. Do you know where I could find the rdf:resource link for a Task? In other words, would I find the Task definition to add to my JSON object in the services.xml file I retrieved?

Thanks again,

Tristan

permanent link
Nick Edgar (6.5k711) | answered Sep 09 '11, 11:22 a.m.
JAZZ DEVELOPER
The guidance and tools mentioned in the OSLC Workshop may be helpful too: https://jazz.net/library/article/635

permanent link
Nick Edgar (6.5k711) | answered Sep 09 '11, 11:10 a.m.
JAZZ DEVELOPER
Hi Tristan,

The 'must-revalidate' is part of the Cache-Control header, so I don't think it's an indication of the problem. It's basically telling any caches to be sure not to serve cached content unless the client has properly authenticated.

Also, it doesn't seem to be an authentication problem, or I'd expect to get a 401 instead of a 400.

Is there any body to the response with more details?

permanent link
Tristan Ratchford (16) | answered Sep 09 '11, 8:05 a.m.
Ok, if you'll be using the Java client API, you should have a look at the other SDK resources at:
https://jazz.net/wiki/bin/view/Main/RtcSdk20


Hi Nick,

I'm also trying to create Draft work items using the RTC REST API, and am using the proper URLs retrieved from the discovery chain. However, I'm also getting HTTP 400 errors telling me to revalidate.

In my servlet I an doing the following :


HttpPost postWorkItem = new HttpPost(extractDraftURL);
postWorkItem.setHeader("Accept" ,"text/json");
String strData = "{\"dc:title\":\"UserFeedback\"}";
ByteArrayEntity lWorkItem = new ByteArrayEntity(strData.getBytes());
lWorkItem.setContentType("application/x-oslc-cm-change-request+json");
postWorkItem.setEntity(lWorkItem);
HttpResponse execute = httpClient.execute(postWorkItem, localContext);


All the code snippet is trying to do is create a draft work item with a title "UserFeedback".

And I get the following 400 error.

HTTP/1.1 400 Bad Request


I also tried using a StringEntity instead of a ByteArrayEntity, but no luck. By any chance do you know why I might be getting the 400 error?

permanent link
Nick Edgar (6.5k711) | answered Feb 18 '11, 1:58 p.m.
JAZZ DEVELOPER
Ok, if you'll be using the Java client API, you should have a look at the other SDK resources at:
https://jazz.net/wiki/bin/view/Main/RtcSdk20

permanent link
r vijay (3676) | answered Feb 18 '11, 4:20 a.m.
Thanks Nick, but i found another article to create work item from plain java (API) .
https://jazz.net/wiki/bin/view/Main/ClientLibrarySetup


I think this is bit simple & close to my requirement.

Thanks,
Vijay

permanent link
Nick Edgar (6.5k711) | answered Feb 16 '11, 10:36 a.m.
JAZZ DEVELOPER
Hi Vijay,

The problem is that you're using the URL copied from the article, so the context UUID does not map to your project area item id. From the article's Creating Draft Work Items section: "The factory URL for draft work items is also available from the service descriptors document".

You need to fetch the overall catalog to discover the corresponding UUID and URL for your projects, then fetch the services document for your project to discover the URL for posting draft work items (and other services).

For example, on jazz.net, https://jazz.net/jazz/rootservices has:
<oslc_cm:cmServiceProviders rdf:resource="https://jazz.net/jazz/oslc/workitems/catalog"/>



https://jazz.net/jazz/oslc/workitems/catalog has:
<oslc_disc:ServiceProvider>

<dc:title>Rational Team Concert</dc:title>
<oslc_disc:details rdf:resource="https://jazz.net/jazz/process/project-areas/_1w8aQEmJEduIY7C8B09Hyw"/>
<oslc_disc:services rdf:resource="https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/workitems/services.xml"/>
<ns1:consumerRegistry rdf:resource="https://jazz.net/jazz/process/project-areas/_1w8aQEmJEduIY7C8B09Hyw/links"/>
</oslc_disc:ServiceProvider>
</oslc_disc:entry>

(and likewise for other project areas)

and https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/workitems/services.xml has:
<oslc_cm:factory oslc_cm:default="true">

<dc:title>Default location for creation of change requests</dc:title>
<oslc_cm:url>https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/workitems</oslc_cm:url>
</oslc_cm:factory>

and
<oslc_cm:factory calm:id="drafts">

<dc:title>Location for creation of draft change requests</dc:title>
<oslc_cm:url>https://jazz.net/jazz/oslc/contexts/_1w8aQEmJEduIY7C8B09Hyw/drafts/workitems</oslc_cm:url>
</oslc_cm:factory>


Note that draft work items need to be manually reviewed and saved before they become a regular work item.

The work item type (dc:type) and category (rtc_cm:filedAgainst) also need to be discovered, though there are some built-in types like defect and task.
I don't see any OSLC-defined support for querying these though (and note that category is an RTC CM concept, not OSLC CM). I suggest using "dc:type": "task" for now, and let the user fill in the category.

Hope this clarifies a bit.

Your answer


Register or to post your answer.