An external HR platform, 1000s of Jira tasks, or 100s of employees are all opportunities for automation – and you need an API for that. Let’s have a closer look at the REST API of BigPicture. What data can you select, update or insert into the database of Jira BigPicture using an API? What limitations could you potentially face?
Most of the content is valid with BigGantt, too.
What data can you update, insert or select through an API?
We can safely say nearly any BigPicture / BigGantt template could be populated through an API. We see BigPicture users who:
- create vacation plans in an external HR platform and have these plans imported into BigPicture through the API
- start BigPicture programs through the API
- create milestones through the API. Say, they have ‘Milestone’ labels on tasks in some external project management app, and they wish to automatically create milestones in BigPicture’s Gantt chart, rather than regular tasks.
Specs of BigPicture’s REST API
There are no publicly available specs of BigPicture’s API. If you wish to start using BigPicture’s API you can either:
(1) Contact our support team
E-mail us at firstname.lastname@example.org, tell us what data you wish to manipulate through the API, and you’ll likely receive some tips. Only do this if you can’t do the (2).
Note: we cannot guarantee that the tips from our support team will work in the long term. In fact, it’s almost certain that your API interface will stop working at some point, unless you understand the ‘private vs. public API’ issue, and properly maintain your interface. Refer to the ‘Why no API documentation is publicly available’ section below for an explanation.
(2) Reverse engineer our API using your web browser’s Developer tools
Save your and our support team’s time. Use Developer tools present in your Chrome / Firefox to get the necessary specs. No need to contact our support team if you go for the (2). Follow this example:
Say, you plan to update holiday plans through the REST API of BigPicture:
- go to the tab in Jira BigPicture where you would normally update the concerned data. In this case, go to Administration > Holiday Plans and then select Details > Edit on any of the plans from the list
- access your Chrome’s Developer tools (CTRL + SHIFT + I)
- switch to the ‘Network’ tab of the Developer tools, XHR sub-tab, enter ‘bigpicture’ into the text filter, as evident in the picture below
- now start manipulating BigPicture’s data; for instance, mark a day in the calendar as a holiday; see the below screenshot – we chose the 10th of April
- click the Holiday plan’s ‘Save’ button
- at this point, a POST request should have been recorded by the Developer tools
In the below screenshot we underlined elements you need to look at:
- the URL, whose ‘softwareplant.com’ part you should obviously replace with your own domain, the one your BigPicture sits on (you’re on Jira Server / Data Center, right? More on Cloud below)
- the POST method – you write and not read data (when reading data you would be looking for GET)
- and Request Payload section which you should follow when building your own JSON
It’s more sustainable to pursue the (2) than the (1), even though the (2) requires more expertise. Continue reading for the explanation.
Why no API documentation is publicly available
Because it’s a private API. ‘Private’ implies ‘I can change without notice’. The API in BigPicture is not a public one, hence there is no documentation. You need a bit more expertise to use the private API than you would need with the public one. Also, you have to be ready for API-related issues, when you upgrade BigPicture / BigGantt to a higher version.
Expect the API of a newly added module, or feature of BigPicture to change frequently, while the APIs of mature modules could remain unchanged for years.
- the above procedure applies to Jira Server and Data Center
- normally you would call the API using ScriptRunner for Jira. You’d do that from within your own Jira Server / Data Center context, so you would have already been authenticated, and that makes things easier for you
- with Jira Cloud, it would be trickier to invoke the API:
- you would have to reach out to our, SoftwarePlant’s servers, where ‘your’ BigPicture resides
- you would have to generate a token to authenticate yourself within SoftwarePlant’s environment
BigPicture 7.4 for Jira Server, Data Center and Cloud is now live. It has new Quick assignee, Multi-select, and Time Tracking (Spent) features, among others.
New Reporting component for BigPicture 7.3 and the corresponding version of BP Enterprise is scheduled for a release in July. Pie and column charts, as well as spreadsheet-style reports, will be available – more.
See you in:
- San Diego for SAFe Summit, Sep 29 – Oct 4
- Paris during Valiantys Enterprise Day, Oct 17