Support for Atlassian Server Products (and apps like BigPicture) is ending in February 2024.

Are you planning a migration to Cloud? Make sure you don't lose your BigPicture data/configurations in the process. Check out this page for information on how to migrate BigPicture's data to Cloud. If you have any questions please email support@appfire.com

Public API

You can use the public API endpoints to set up integration between BigPicture and external tools. To get responses, you need to have admin permissions.

Base URL

How to determine the base URL (Jira Server, Jira Data Center)

To determine the base URL for the public API:

  1. Navigate to Jira Administration > System > General configuration.
  2. Under the General Settings section, find the base URL, for example, https://yourcompanyname.com.

Use the following format for the base URL in the public API (replace {Jira BaseURL} with your base URL):

{Jira BaseURL}/rest/softwareplant-bigpicture/1.0

Example:

https://yourcompanyname.com/rest/softwareplant-bigpicture/1.0

How to determine the base URL (Jira Cloud)

BigPicture can be located on different servers. For example, during a version update, BigPicture is moved to another server which causes the change of the base URL.

To determine the base URL of the server where BigPicture is located, you have to call our Cloud Manager with a token to the public API:

GET https://cloud.softwareplant.com/cloudmanager/bigpicture/where-am-i
Authorization: APIToken {your API token}

In response, you should get the location of BigPicture, for example:

{
  "location": "https://cloud.softwareplant.com/bigpicture/jiracloud/101"
}

Use the following format for the base URL in the public API:

{location received from cloudmanager}/rest

What happens when BigPicture is moved to another server

When BigPicture changes location to another server, then a call to the public API of the old server returns a 401 error. After that, it is necessary to call our Cloud Manager again to determine the BigPicture location using the 297534735.

Synchronize absences of your Resources

Provide API to synchronize the following absences of your Resources with data from other systems used by your organization, e.g., SAP. 

  • Regular work time
  • Holiday
  • Sick leave

Jira and BigPicture admins can perform queries on these endpoints:

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.


OperationRequest type: URLAdditional infoExample of response

Get absence for a particular Resource

GET baseUrl/public/ppm/resources/{individualId}/absences

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

For {individualId}, use a pattern: EXT_USER@<extplatform_id>@<user_id_in_extplatform>

Replace <extplatform_id> with an ID for an external platform you use data from. If your default external platform is Jira Server, enter 2. To check <extplatform_id>, go to App Configuration → Integrations →  Connections. Click F12 to see a side window on the right. Go to "Network" → "Fetch/XHR". Refresh the page, click "extplatform" and navigate to the "Preview" section. The <extplatform_id> will be visible there, as presented below. Copy an ID for the platform you want to use. 

Next, replace <user_id_in_extplatform> with a real ID of the user from the external platform you want to use (for Jira Server, enter a user ID in Jira, for another extplatform like Trello, provide a user ID in Trello).
If <user_id_in_extplatform> is an email address, double “@” and use the pattern EXT_USER@@<extplatform id>@@<email@com>, then provide a real email in <email@com>.

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Example of API response for Resource absence:

Create absence for a particular Resource

POST baseUrl/public/ppm/resources/{individualId}/absences

Content-Type: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Request Body:

{ "startDate": "2022-12-02", "endDate": "2022-12-02", "absenceType": "HOLIDAY", "comment": "new comment content", "percentageUnavailability": 100 }

There are 5 different absenceType you can use:

  • HOLIDAY
  • LEAVE AT REQUEST
  • SICK LEAVE
  • MATERNITY LEAVE
  • OTHER REASON

You can set percentageUnavailability to 50 or 100. 
Other values are not supported. 50 means the Resource is absent half a day, while 100 informs that the Resource is absent all day. 

To provide data, use the pattern: YYYY-MM-dd.

Update absence for a particular Resource

PUT baseUrl/public/ppm/resources/{individualId}/absences?startDate={startDate}

Content-Type: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Request Body:

{ "startDate": "2024-07-21", "endDate": "2024-09-21", "absenceType": "OTHER REASON", "comment": "updated comment content", "percentageUnavailability": 50 }

Delete absence for a particular Resource

DELETE baseUrl/public/ppm/resources/{individualId}/absences?startDate={startDate}

Content-Type: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Get all Teams in a given Box

Jira and BigPicture admins can use the following endpoint to get all Teams in a given Box.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional infoExample of response

Get all Teams in a given Box

GET baseURL/public/ppm/teams?boxIds={boxId1}&boxIds={boxId2}

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

Replace {boxId1}, {boxId2} with real IDs. You can enter as many boxIds as you want. You can find your boxId in the URL bar or next to the status of the Box, as presented below.

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Example of GET Team response:



Get task assignment of your Resources

 Jira and BigPicture admins can use the following endpoint to get assignments of tasks for Resources.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional infoExample of response

Get assignments of tasks for Resources

GET baseURL/public/ppm/boxarea/resourcetaskassignment/{boxId}/
resourcetaskassignment?startDate={startDate}&endDate={endDate}&taskEffortMode={taskEffortMode}

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

Replace {boxId} with real boxId of box you would like to retrieve data from. You can find your boxId in the URL bar or next to the status of the Box, as presented below.

To provide data, use the pattern: YYYY-MM-dd.

The following taskEffortMode can be applied:

  • ORIGINAL_EFFORT_ESTIMATE,
  • REMAINING_EFFORT_ESTIMATE,
  • STORY_POINT_EFFORT_ESTIMATE

By default, ORIGINAL_EFFORT_ESTIMATE will be generated for taskEffortMode even If you do not replace {taskEffortMode} in the endpoint.

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Example task assignment response:



Get all Box IDs associated with a selected task in the scope

 Jira and BigPicture admins can use the following endpoint to get all Box IDs connected with a selected task in the scope.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional info

Get all Box IDs associated with a selected task in the scope

GET {baseURL}/public/ppm/boxarea/task/{taskIdorExtPlatformTaskKey}/boxes

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

You can find taskId in BigPicture, for example, "108".

  1. Click F12 to see a side window on the right.
  2. Navigate to "Network" -> "Fetch/XHR".
  3. Start editing a selected task inline in BigPicture.
  4. Click the updateFieldValue parameter and go to the "Payload" section. The taskId is visible there. 

For ExtPlatformTaskKey, use this pattern {extplatformId}@{extTaskType}@{extTaskId}, for example, "2@1@1034407". 

  1. Go to a Jira issue and click F12 to see a side window on the right.
  2. Navigate to "Network" -> "Fetch/XHR".
  3. Refresh the page.
  4. Find the loadBoxStructure parameter (use the search box to find it faster). 
  5. Go to the "Payload" section. 

Make sure that the WBS widget is enabled. 

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Get the field definition of a Box

 Jira and BigPicture admins can use the following endpoint to get the field definition of a Box.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional info

Get the field definition of a Box

GET {baseUrl}/public/ppm/box/field/definition

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Example of response:

Example response
{
   "boxFieldDefinitions":[
      {
         "boxFieldDefinitionId":13,
         "boxFieldDefinitionLabel":"Actual Cost",
         "dataType":"NUMBER",
         "readOnly":true,
         "removable":false,
         "selectOptions":[
            
         ]
      },
      {
         "boxFieldDefinitionId":111,
         "boxFieldDefinitionLabel":"Actual Cost (Tasks)",
         "dataType":"NUMBER",
         "readOnly":true,
         "removable":false,
         "selectOptions":[
            
         ]
      },
      {
         "boxFieldDefinitionId":10,
         "boxFieldDefinitionLabel":"Archived",
         "dataType":"LABELS",
         "readOnly":true,
         "removable":false,
         "selectOptions":[
            
         ]
      }
   ]
}

Get selected fields of a Box

 Jira and BigPicture admins can use the following endpoint to get selected fields of a Box.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional info

Get selected fields of a Box

POST {baseUrl}/public/ppm/box/{boxId}/selectedFields

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

Replace {boxId} with a real ID. You can find your boxId in the URL bar or next to the status of the Box, as presented below.

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Example of request body:

Example request
{
"boxIds":["PROG-1741", "ROOT"],
"fields":{
   "1":["NONE"],
    "2":["MAX"]
}
}

Example of response:

Example response
{
   "fields":{
      "ROOT":{
         "aggregations":{
            "1":{
               "NONE":{
                  "dataTypeId":"STRING",
                  "value":""
               }
            },
            "2":{
               "MAX":{
                  "dataTypeId":"DATE",
                  "value":"2069-12-31"
               }
            }
         }
      },
      "PROG-1741":{
         "aggregations":{
            "1":{
               "NONE":{
                  "dataTypeId":"STRING",
                  "value":""
               }
            },
            "2":{
               "MAX":{
                  "dataTypeId":"DATE",
                  "value":"2025-12-31"
               }
            }
         }
      }
   }
}

Get values of respective aggregation for a particular task 

 Jira and BigPicture admins can use the following endpoint to get values of respective aggregation by global task field names.

Cookie: JSESSIONID=sessionId is used for calls to the public API on Jira Server/ Jira Data Center. It is not required on Jira Cloud.

OperationRequest type: URLAdditional info

Get values of respective aggregation for a particular task 

GET baseUrl/public/ppm/boxarea/task/{taskIdOrExtPlatformTaskKey}/field/aggregations

Accept: application/json

Authorization: APIToken <token>

Cookie: JSESSIONID=sessionId

Replace baseUrl with your real URL, for example: https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0 

You can generate an APIToken in BigPicture -> My settings -> API tokens. For more info, click here. The token is valid for 1 year. 

To catch your sessionId, you can:
Open BigPicture and click F12 to see a side window on the right. Go to "Network" -> "Fetch/XHR". Refresh the page and copy your JSESSIONID, as presented below.

Parameters:

ParameterLocationTypeDescription
taskIdOrExtPlatformTaskKeyPathString 

Providing taskId or ExtPlatformTaskKey is mandatory.

You can find taskId in BigPicture, for example, "108".

  1. Click F12 to see a side window on the right.
  2. Navigate to "Network" -> "Fetch/XHR".
  3. Start editing a selected task inline in BigPicture.
  4. Click the updateFieldValue parameter and go to the "Payload" section. The taskId is visible there. 

For ExtPlatformTaskKey, use this pattern {extplatformId}@{extTaskType}@{extTaskId}, for example, "2@1@1034407". 

  1. Go to a Jira issue and click F12 to see a side window on the right.
  2. Navigate to "Network" -> "Fetch/XHR".
  3. Refresh the page.
  4. Find the loadBoxStructure parameter (use the search box to find it faster). 
  5. Go to the "Payload" section. 

Make sure that the WBS widget is enabled. 

fieldIdQuery StringString or Integer

Providing taskFieldId or globalFieldName is mandatory.

Enter taskFieldId - TaskFieldId (integer) used to identify a field in BigPicture, for example, "518".

Enter globalFieldName - GlobalFieldName (String) used to identify global field names, for example, "Story Points". 

aggregationTypeQuery StringString

Providing aggregationType is mandatory.

Possible values:

- MIN
- MAX
- SUM
- SUM_NO_PARENT
- AVG
- AVG_NO_PARENT

boxIdQuery StringString

Providing boxId is optional. This parameter can be used as a context for aggregation.

You can find your boxId in the URL bar or next to the status of the Box, for example, "PROG-30". 

Example of query:

Giving the structure for a task, where DEV-4 has taskId=4


Request in curl
curl --request GET 'https://qa.softwareplant.com/prod/rest/softwareplant-bigpicture/1.0/public/ppm/boxarea/task/4/field/aggregations?fieldId=Story Points&aggregationType=SUM_NO_PARENT' \
--header 'Authorization: APIToken eyJ0eXBlIjoiSldUIiwiYWxnIjoiSFM1MTIifQ.eyJpc3MiOiIwMDAwMDAwIiwic3ViIjoiSklSQVVTRVIxMDAwMCIsImV4cCI6MTY2OTk3ODQ2NSwiaWF0IjoxNjY5MzczNjY1fQ.nR2kvya9ngBXe5rMXqSnHttFskvBwKUZe3o-i5AXWNv9pVtehKdc0Vo7SvUCreZAAnTq2Bm1TtcBrp7hTXPkmQ' \
--header 'Cookie: JSESSIONID=DAEA639C9BB35602BA6DD6047AE28F91; atlassian.xsrf.token=BRV5-VZPW-OO88-0AGP_9ef14177ddf00af1495cb7818d5b29c83c1a899c_lin'

Parameters used in the query: 

taskIdOrExtPlatformTaskKey - 4

fieldId - "Story Points"

aggregationType - SUM_NO_PARENT

Example of response:

Example response
{
    "currentVersion": 1,
    "latestVersion": 1,
    "cargo": {
        "value": {
            "dataTypeId": "NUMBER",
            "number": 6.0,
            "histogram": false
        }
    }
}