Practicalities of the RTC 2.0 Rest APIs
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
Hi Adrian/Patrick ,
I too have a similar requirement, want to create a RTC work item from Lotus Notes Environment. I tried the following curl -k -c ./cookies.txt "https://localhost:9443/jazz/authenticated/identity" {works fine} curl -k -L -b ./cookies.txt -c ./cookies.txt -d j_username=ADMIN -d j_password=ADMIN "https://localhost:9443/jazz/authenticated/j_security_check" {works fine} curl -k -b ./cookies.txt "https://localhost:9443/jazz/oslc/workitems/1.json" {works fine,just to see the format} curl -D - -k -b ./cookies.txt -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Accept: text/json" -X POST --data-binary @c:\create-simple.json "https://localhost:9443/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/drafts/workitems" {doesn't work} I am just trying to create a draft work item, but it says "must-revalidate". okies.txt -H "Content-Type: application/x-oslc-cm-change-request+json" -H "Acce t: text/json" -X POST --data-binary @c:\create-simple.json "https://localhost:9 43/jazz/oslc/contexts/_9BHm0EqVEd6HXO10niqZpg/drafts/workitems" HTTP/1.1 404 Not Found Server: Apache-Coyote/1.1 Cache-Control: max-age=0, must-revalidate Expires: Wed, 16 Feb 2011 04:41:12 GMT Vary: Accept, Accept-Language Content-Type: text/json;charset=UTF-8 Transfer-Encoding: chunked Date: Wed, 16 Feb 2011 04:41:12 GMT { "message": "CRJAZ0215I Item not found: com.ibm.team.process.internal.common impl.ProjectAreaHandleImpl@2c582c58 (stateId: null, itemId: , origin: <unset>, immutable: <unset>)", "status": 404 } "dc:description":"A description for the new work item", "dc:type": { "rdf:resource":"https:\/\/localhost:9443\/jazz\/oslc\/types\/_9BHm0EqVEd6HXO10niqZpg\/defect" }, "rtc_cm:filedAgainst": { "rdf:resource":"https:\/\/localhost:9443\/jazz\/resource\/itemOid\/com.ibm.team.workitem.Category\/_-hBTUEqVEd6HXO10niqZpg" } } Can you please let me know what i am missing in the json file. Thanks, Vijay |
Hi Adrian,
I have been struggling with similar questions that you posted here so I thought I'd answer a question that was not answered. How to figure out the available Categories for a Team Area or Project ? I use the following: https://localhost/jazz/oslc/categories.xml If your repository hosts a lot of projects then you can proceed to limit the result down to only a certain project by using the oslc_cm.properties in the url. That should allow you to populate your own UI or automated function to pick a Category for creating a work item. Regards, Mario |
So instead of specifying The example was corrupted. Here it is again: So instead of specifying <rtc_cm:ownedBy rdf:resource="https://localhost:9443/jazz/oslc/users/celsius"/> you could specify something along the lines of: <rtc_cm:ownedBy rdf:resource="${emailAddress:anders_celsius@example.jazz.net}"/> |
|
Thanks for the detailed outline of the scenario, Adrian.
So, I can cheat and maintain a manual mapping of categories by simply Actually, there is such an API, but as it isn't aligned with OSLC or JFS yet and *very* likely to change, I am a bit reluctant to document it: https://localhost:9443/jazz/oslc/users.xml?oslc_cm.query=rtc_cm:emailAddress=%22user@domain.com%22 Besides providing official support for this, our thinking also goes into the following direction: So instead of specifying <rtc_cm> you could specify something along the lines of: <rtc_cm> It seems that the existing REST API is following Fielding a little bit I wholeheartedly agree that many discussions around REST are too religious. IMO, we took what makes sense from a resource oriented view on our artifacts. I personally like the fact that references to other artifacts are links, e.g. the 'owner' of a work item is the URL of the user resource. For a client that reads the resource, it is clear how to get at the user details: just fetch the contents using the URL. For a client that needs to update or create a work item, that's admittedly harder, but this is something we are working on -- along the lines of the example above. -- Regards, Patrick Jazz Work Item Team |
|
Thanks for the comprehensive response.
I'd argue that in many use cases there is sufficient knowledge about the data you are mapping from and the project area definition into which you need to create work items to be able to reasonably perform a mapping. I understand that the more general use case of OSLC-CM appears to be vendor interop, but there are lots more useful things to do with a REST API. For example, let me expand my particular scenario. We are a Lotus development team moving piece by piece over to using RTC. This is a non-trival organization change for us and one aspect is bugs. We have a long established Lotus Notes database where our bugs live. Unfortunately we also have the use of that tool ingrained into our process and tools very tightly. We can't just stop using it and switch to RTC for bug tracking overnight. So, we want to integrate the two to allow the testers and release managers to work in their beloved Notes DB, but to allow developers to have bugs reflected in their planning and execution in RTC. As Notes is not a web-based application, and as it doesn't run anywhere near the RTC install the REST APIs seem like a logical starting point for us to build such integration. The first, simple user story is: "By clicking a button in an already populated SPR (in the Notes DB) the developer can create a work item with the correct filed against and owner in RTC for them to then plan in their iteration work" This is a case of a simple, well defined use case that does not need to take account of the fact that RTC is so flexible in terms of project configuration. It will work against our project, configured the way we want. We have categories that we've defined and that we can map to existing information in the Notes DB. We do have more than five developers however, more like 150! Whilst I've not looked in detail I suspect that the web-form approach isn't going to work in an Eclipse based Notes environment. Secondly I don't want the users to have to re-fill all of the information that already exists. What I want is a way to be able to know how to specify a filed against category and an owner in a work item I can POST to RTC. So, I can cheat and maintain a manual mapping of categories by simply performing queries against existing work items to get the resource URIs, that's easy enough and the list of categories is stable enough. However I can't do this for people. There is no way (that I know of) of being able to discover the resource URI for a person given information such as their RTC login ID (which for us is their IBM Intranet ID) Therefore it sounds like the compromise we are going to have to make is to create a draft work item using the REST API and then simply open the resultant URL up in a browser window for the user to then manually fill out the rest. Not ideal, but not a disaster either. It seems that the existing REST API is following Fielding a little bit too closely in it's adherence to RESTful thinking to the possible detriment of it's actual usefulness. A little bit more flexibility in being able to specify data in ways other than a resource URI (armed with a bit of knowledge) would go a long way. |
|
The Work Items 2.0 Rest API is an implementation of the OSLC-CM 1.0
specification which doesn't say anything yet about how to get metadata like value sets etc. This is however one of the main topics of OSLC-CM 2.0. Actually, there is an implementation for value sets and querying other resources than work items, but as it needs alignment with OSLC, it is experimental, undocumented and subject to change. Creating work items in a completely configurable environment like RTC is actually less trivial than it sounds. You don't know what attributes a work item has, you don't know the required attributes etc. So you are quickly in a position to handle everything that the work item editors do. In order to prevent this, the 2.0 implementation provides ready-to-use embeddable Web modules that allow you to create work items from another application by embedding these modules. Depending on your use case, you could still leverage the API to easily create work items: Get the JSON or XML representation of an existing work item and use it as a template. You would modify e.g. summary and description and POST it back to the factory URL. This works only for a specific project area, however, and only if there are a limited number of referenced attributes (e.g. only 5 different users as potential owners etc. that you could hard-code on your side). This will definitely not cover the needs of a client application that is required to work with any repository/project area). This recent blog post has some more details about the focus and possibilities of the current implementation: http://jazz.net/blog/index.php/2009/09/11/oslc-and-rational-team-concert/ -- Regards, Patrick Jazz Work Item Team |
Your answer
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.