/api/get_checklist_headers Not Returning Full List
05/12/2015
This issue using BIM 360 Field API was brought up a few times in the past. Unfortunately the documentation isn't updated, yet. So let me write about it.
Q. I'm trying to retrieve checklists for a given project in BIM 360 Field. I’m using REST call /api/get_checklist_headers. This request does not seem to return all the checklists for a project that we see in the Field Web UI. Why is that? How can we get all the list?
A. There is one more parameter missing in the documentation to control this behavior; you will need to include parameter application_version = 1.10 or greater.
This is due to the enhancement added to support “rich content” (multi-select, single-select checkboexes) in the BIM 360 Field Mobile v1.10 and later. To be compatible with older versions, this API method omit any checklists which contain rich content by default. To include them, you need to explicitly specify application_version=1.10 or later when calling /api/get_checklist_headers.
Note that above parameter will return all the checklists including deleted ones. This is as designed as the mobile client has to know about deleted checklists when synchronizing. It is recommended to use filter_id for “All Checklist” if your goal is to retrieve all the checklist you see in the Field Web UI. You can get the list of fileter_id’s from /api/projects call. Each project in the list includes a list of available filters.
In summary, use parameters, application_version=1.10 and filter_id, when calling /api/get_checklist_headers. (A change request to update the documentation is logged as CS-16773.)
/fieldapi vs. /api
While on this topic, I would also like to point out that there is /fieldapi/checklists/v1, which also allows you to retrieve a list of checklists. This returns a minimal set of checklist information, including the checklist ID. This version of method does not inherit conditions mentioned above. To retrieve checklist details, you can call the /fieldapi/checklists/v1/:id API method.
When you see similar methods in two versions, one in /fieldapi and one in /api, you may want to use /fieldapi version. As a general rule,
- /fieldapi/{object}/v{version} – this is designed for API users. This is preferred over /api unless there isn’t a supported operation.
- /api – this is designed for BIM 360 Field Mobile, but is open for API customer use.
Mikako