Planbox Agile

Planbox integrates with third party web applications. Natively we integrate with various applications. If you want to create an integration with your own application, you can do so as well with the following "Third Party API" call.

You do not need a Planbox account to access Planbox third party API calls. We assume the calls you make will be on behalf of a user. As such, you will require an Initiative Token and the User Email. Details on how to ask those to your user, and how your user can find their token can be found here.

https://work.planbox.com/api/third_party_create_story

Creates a new stroy in Planbox from a third party application.
Note: Access to this API call is granted only if the Third Party API feature is turned on for the initiative. The Planbox user can turn that on by going to the Features section on the Initiative Settings Page.

POST Arguments

• token: API initiative token. Can be found on the Initiative Settings Page below the Features section.
• source: Third Party name. Up to 20 characters allowed.
• creator_email: Planbox user email. Must be someone on the initiative with admin or write access.
  Note: Must be the same email used to log into Planbox.
• name: Short name of the story.
• description: Full description of the story.
• assignee_email: Optional. Planbox user to assign the task of the story to. If omitted, task will be unassigned.
  Note: Must be the same email used to log into Planbox.
• timeframe: Optional. Iteration in which to put the new story. Can be one of: current, next or backlog. Default is current.
• project_alias: Optional. Project in which to put the new story. It is the project alias. If omitted, Planbox chooses the first project in the initiative.
• type: Optional. Type of story as listed here.
• tags: Optional. Comma separated tag words to help you classify the story (called labels in UI).
• importance: Optional. Importance level of the story. If omitted, normal is used. Can be a number 1 to 5 as listed here.
• points: Optional. Number of points assign to this story. Default is 0.
• value: Optional. Business value of this story. Default is 0.
• due_on: Optional. Due date for the story. If omitted, no due date is set.
• attachments[]: Optional. An array of URLs to attach. These will appear as attachments on the stroy. Should be in this form:[{filename:"screenshot.jpeg", url:"http://www.example.com/screenshot.jpeg"}, ...]
  See PHP example below.

Result

Returns this JSON object:

{code:<result_code>, content:<result>}

Where <result_code> will be 'ok' on success, or 'error' on failure.
Where <result> contains the new story record on success or an error message string upon failure.

The story record has these properties:

• id: Unique story id.
• type: Type of story.
• tags: Story tags (labels).
• name: Name or iteration or story.
• description: Description of the story.
• url: Link to the story in Planbox.

Javascript Example

Uses jQuery's post function to create a new stroy.

$.post('https://work.planbox.com/api/third_party_create_story', {
	token:"amsdn23kdfkj23h1jk12",
	creator_email:"[email protected]",
	source:'third party api',
	type:'bug',
	timeframe:'current',
	name:'There is a bug',
	description:'Go here and click there. You will replicate the bug.'
}, 'json');

PHP cURL Example

Same example as above but using PHP. In addition, a file attachment is passed.

$url = 'https://work.planbox.com/api/third_party_create_story';
$fields = array(
	'token' => 'amsdn23kdfkj23h1jk12',
	'creator_email' => '[email protected]',
	'source' => 'third party api',
	'type' => 'bug',
	'timeframe' => 'current',
	'name' => 'There is a bug',
	'description' => 'Go here and click there. You will replicate the bug.',
	'attachments' => array(
		array(
			'url' => 'http://www.example.com/screenshot.jpeg',
			'filename' => 'screenshot.jpeg'
		)
	)
);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, count($fields));
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_exec($ch);
curl_close($ch);