Using the Reportable REST API - how do I filter workitems by type?
I'm trying to get my head around the API for Rational Team Concert, so far I'd sum it up the experience of trying to extract data from RTC as like trying to get blood from a stone.
Eventually I found my way to what I believe is the documentation for the APIs:
https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI
First thing my "hello world" test was to try get a list of all workitems, I ended up with this:
/ccm/rpt/repository/workitem?fields=workitem/workItem[projectArea/name='MyProjectArea']/(summary|type/name|id)
I then wanted to do something a little more useful ... just pull defects:
/ccm/rpt/repository/workitem?fields=workitem/workItem[projectArea/name='MyProjectArea' and type/name='Defect']/(summary|type/name|id)
This returns an internal server error: HTTP Status 500 - CRRED8022E: Non Queryable Field: type/name
I've tried filtering by type=Defect, type=defect, and get a different error: CRRED0105E: Unsupported type name: com.ibm.team.workitem.WorkItemType
Question 1: How do I filter workitems by type?
Question 2: Is there some better documentation around how to use this API? I haven't found any information on how I can automate authentication to the API yet either, so far I'm cheating by using the cookies from a manually authenticated session in my browser.
Accepted answer
Hi David,
As you found out, you can't filter work items by the type name, but you can filter on the type *id* instead, i.e.
/ccm/rpt/repository/workitem?fields=workitem/workItem[type/id=<type_id>]/(summary|type/name|id)
That's also the case for the other examples that Subramanya mentioned - you can't filter on the state or severity name, but you can filter on their ID.
Unfortunately, we don't really have any documentation about this aside from the wiki page that you already found. In terms of authentication, it would depend on how you're accessing the API - e.g., is it a Java program, a script...? Authentication for the reportable REST API is the same as for any other REST APIs on the server, so you might be able to search the forums to figure out how to authenticate, depending on what method you're using. For example, here's a wiki article with some examples for Perl -
https://jazz.net/library/article/1086/
And here's a forum post about how it works using curl -
https://jazz.net/forum/questions/17204/problem-using-curl-to-access-work-item-api
As you found out, you can't filter work items by the type name, but you can filter on the type *id* instead, i.e.
/ccm/rpt/repository/workitem?fields=workitem/workItem[type/id=<type_id>]/(summary|type/name|id)
That's also the case for the other examples that Subramanya mentioned - you can't filter on the state or severity name, but you can filter on their ID.
Unfortunately, we don't really have any documentation about this aside from the wiki page that you already found. In terms of authentication, it would depend on how you're accessing the API - e.g., is it a Java program, a script...? Authentication for the reportable REST API is the same as for any other REST APIs on the server, so you might be able to search the forums to figure out how to authenticate, depending on what method you're using. For example, here's a wiki article with some examples for Perl -
https://jazz.net/library/article/1086/
And here's a forum post about how it works using curl -
https://jazz.net/forum/questions/17204/problem-using-curl-to-access-work-item-api
One other answer
As far as I know, not all the properties in RTC are allowed in filtering and this is one among them. (Other examples - state/name='New' or severity/name='Major')
You will see same error for
https://server:port/ccm/rpt/repository/workitem?fields=workitem/workItem[state/name='New']/(summary|projectArea/(name)|state/(name)|severity/(name))
I have not found any documentation apart from https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI#Field_selection_and_filtering
You will see same error for
https://server:port/ccm/rpt/repository/workitem?fields=workitem/workItem[state/name='New']/(summary|projectArea/(name)|state/(name)|severity/(name))
I have not found any documentation apart from https://jazz.net/wiki/bin/view/Main/ReportsRESTAPI#Field_selection_and_filtering