Field API: Filter Issues by Issue Type
07/16/2015
This topic was raised through a forum post. I also saw a similar inquiry came internally, too. I thought it's worth a little bit of explanation.
Q. We would like to get a list of issues filtered by project and issue type. However, we do not find any API option to filter by issue type using BIM 360 Field API /api/get_issues. If we attempt to get the whole list and filter ourselves, we are running into timeout exceptions as most of our projects have large number of issues. Is there any other way to retrieve such a list?
A. You can use the following REST call:
POST /fieldapi/issues/v1/search
with conditions parameter. A condition is a string with a form of:
field identifier,operator,"condition value"
where operator is one of predefined comparison types, such as eq (equal), neq (not equal), startwith (start with). (Please refer to the documentation for full listing.)
As an example, given an issue type id, let's says "123-xxx-yyy-zzz", you can write a search condition to look for issues with this specific issue type as:
conditions = ["f--issue_type_id,eq,\"123-xxx-yyy-zzz\""]
This reads as “issue type id equals xxx.”
If you are writing in C#, the above will be like the following with escape characters added:
string conditions =
"[\"f--issue_type_id,eq,\\\"123-xxx-yyy-zzz\\\"\"]"
Note that conditions parameter is a list. You will need to put triplet defining a condition between a pair of square brackets “[ ]”. If you want to specify more than one condition, you simply add condition triplet, separated by comma (,).
Other examples of condition might be:
["cf--<custom filed guid>,like,\"inspect\""]
and
["f--status,in,[\"Work Completed\",\"Draft\"]”]
The former reads as “custom field xxx is like “inspect”. The latter reads as “status is Work Completed or Draft”.
To retrieve issue types, you can use: POST /fieldapi/issues/v1/types
The response of search call does not include full issue record. If the information you are looking for is not the part of data that search returns, you can use: POST /fieldapi/issues/v1/retrieve
Mikako