Planbox Agile

API calls are made by calling https://work.planbox.com/api. The API uses POST to pass arguments. Most API calls require you to be logged in unless specified otherwise.

Return value is a JSON object with these properties:

code: <result_code>,
content: <result>

Where <result_code> is the error code returned. On success will be 'ok'. On error will be 'error'.
Where <result> is the result.

Most examples on using the API are shown with Javascript using jQuery's post function. Some examples may also show calls using wget or PHP curl.

In the Planbox API terminology differs than that of the User Interface. So here's a list of objects you will find throughout the API.

• An initiative is called a product. It is the first project level. A product is uniquely identified by its product_id.
• A project is the second project level. A product contains one or multiple projects. A project is uniquely identified by itsproject_id.
• An item is called a story (analogous to a user story as defined in the Agile or SCRUM). It is the third project level. A project contains stories. A story is uniquely identified by its story_id.
• A task is the fourth project level. A story contains one or many tasks. A task is uniquely identified by its task_id.
• A resource is a Planbox user. A resource is uniquely identified by its resource_id.
• An iteration is analogous to a sprint as defined in SCRUM. An iteration is uniquely identified by its iteration_id.
• The logged resource is the Planbox user which is logged in, and making the API call.
• An event as shown in a calendar is either an iteration start or end, or a story with a deadline.

You can find the product id by looking at the hash tag in the URL when you are on the Items & Tasks or Initiative Settings Page pageinitiatives/1234:

http:work.planbox.com/initiatives/1234/edit

In this case the product_id is 1234.

You may have noticed that Planbox has URLs like this:

http:work.planbox.com/initiatives/1234#story_id=5678&story_pane_tab=files

The URL persists context. In this case the URL would send you to the Work page. Product 1234 would be loaded and story 5678 would be opened to the Files tab. The URL can be copied and sent by email or saved in a document for future reference. Pasting this URL in a browser would set up exactly that context - with item 5678 opened in product 1234.

You can craft these URLs yourself by following the guidelines below.

How it Works

The fragment after the hash tag # contains encoded information about what to display. This information is encoded in a modified JSON format. In short, double quotes and spaces are stripped to be URL friendly.

On the Work, Report and Manage page, the following attribute is supported:

• product_id: Load the given product.

On the Work page, the following attributes are supported.

• story_id: Open the pane for this item.
• story_pane_tab: Defines which tab in the item pane to show. Can be one of: tasks, details, files, comments or feedback. If omitted, tasks is shown.
• resource_ids: Defines the resource filter (i.e. My Work). Contains an array of resource ids. If omitted, Everyone's Work is shown.
• project_ids: Defines the project filter. Contains an array of project ids. If omitted, items for all projects are shown.
• filter_id: Defines which iteration tab to show. Can be 1 for Current, 2 for Next, 3 for Backlog or 4 for Last.

The Planbox API supports all data types defined in the JavaScript Object Notation specification or JSON.

Dates are specified as strings in the form YYYY-MM-DD. For example 2011-08-01 for August 1st 2011. Leading zeros are important.

Date/time are specified as strings in the form YYYY-MM-DD HH:MM:SS. For example 2011-08-01 14:05:34. In PHP this is equivalent to the date function format Y-m-d H:i:s.

Common Issues

HTTP Error 422: Unprocessable Entity

You have managed to get a token (api/login) and query for product (get_products) but when querying for projects (get_projects) the response is: "2 HTTP Error 422: Unprocessable Entity"

Url: https://work.planbox.com/api/get_projects 

PostData {"product_id": 123}

"message":"An error has occurred.","exceptionMessage":"The remote server returned an error: (422) Unprocessable Entity."

Posted data needs to be Form URL-Encoded or Multipart, not JSON. There’s a JavaScript example in our documentation for a sample API call:

http://support.planbox.com/knowledgebase/articles/206627-products-projects

Content type should be set to something like this: "application/x-www-form-urlencoded". Data format text depends on the language/tool being used to connect to Planbox API.

How can I uniquely identify stories and tasks in the API?

When an iteration changes and the task is carried over? Is there a unique id for the tasks and stories? I am tracking the status changes of the stories and tasks, and I am identifying them via their ID. the problem is that when the iteration changes and that task is carried over to the new iteration, a new ID is created.  

You can use the master_id, which points to the story or task that a cloned object refers to.