In your commit message, you specify the item number and action to perform within square brackets. For example, this commit message comments on two items.

[#1234 #5678] Bomb defused.

You can mark the item as complete by specifying a verb such as 'complete' or 'fixes'. Variations such as 'fixed' or 'fix' are also detected. For example, this will complete the item and comment on it:

[fixes #1234] Muffler had fallen... but is now fixed.

NOTE: Completing an item marks ALL tasks as complete. Tasks unassigned will automatically be assigned to the author of the commit. So if you are a developer, be careful not complete an item if others have incomplete tasks.

Item Number

The item number can be retrieved from the Item Panel. Simply click on it and it will be copied to the Clipboard. Alternatively, you can find the story id in the URL following the parameter "story_id".

NOTE: In Planbox 'item' or 'story' are synonyms. The UI uses the term 'item', the more general term. The API uses the term 'story'.

API Call Syntax

Your post-commit hook must call the Planbox URL https://www.planbox.com/api/source_commits and pass these arguments either through GET or POST:

• token: Your initiative token. Can be retrieved on the Settings page.
• email: Your email, as a developer committing code. The same one as in your Planbox account.
• commit_id: The commit number.
• message: The commit comment or message.

For example, here is a generic CURL example using POST:

curl --data "token=203dhfbac97de2ndbf1d8aa435bec9805" \
  --data-urlencode "email=john@example.com" \
  --data-urlencode "commit_id=6504" \
  --data-urlencode "message=[fixed #1234] Finally resolved this bug." \
  https://www.planbox.com/api/source_commits

When executed, a comment from John will be posted on the item #1234, and the item will be completed.

Here is the same example calling the URL and passing arguments through GET.

https://www.planbox.com/api/source_commits?token=203dhfbac97de2ndbf1d8aa435bec9805
&email=john@example.com
&commit_id=6504
&message=%5Bfixed%20%231234%5D%20Finally%20resolved%20this%20bug.

If you're using SVN, you can create a Subversion post-commit hook. Here is a sample script which also takes care of mapping a subversion author, to a Planbox email.

#!/bin/sh
set -e

REPO="$1"
REV="$2"

AUTHOR=`/usr/bin/svnlook author $REPO -r $REV`
MESSAGE=`/usr/bin/svnlook log $REPO -r $REV`

EMAIL=${AUTHOR}
case "$AUTHOR" in
  "martin") EMAIL="martin@example.com"
  ;;
  "john") EMAIL="john@example.com"
  ;;
esac

RESPONSE=`curl --data "token=203dhfbac97de2ndbf1d8aa435bec9805" \
  --data-urlencode "email=$EMAIL" \
  --data-urlencode "commit_id=$REV" \
  --data-urlencode "message=$MESSAGE" \
  https://www.planbox.com/api/source_commits`

echo $RESPONSE >> /var/log/planbox_post_commit.log

Follow these instructions to get it working:

1. In your subversion directory, step into the hooks directory
2. Copy file post-commit.tmpl to post-commit
3. Make it executable with chmod a+x post-commit
4. Cut and paste the script code from above. Then edit the file.
5. Modify user-to-email mapping
6. Set your token correctly in the call to curl

After that, try a commit and see commit comments appear in Planbox! Any error will be dumped into the log file. Feel free to comment/remove the last line echo $RESPONSE to turn off logging.

If you use Git, Jason Ardell has created a Git and Planbox command line interface (CLI). It is called git-planbox and open-source on GitHub. To install and configure it on your Linux or UNIX box, consult the git-planbox help page on GitHub.

Once installed and configured, you have access to these commands:

git-planbox list
  Get a list of stories to work on.

git-planbox show
  Show tasks, details, comments, and status for a story.

git-planbox start
  Begin working on a task. Enforces branch naming conventions and
  starts the timer for a task.

git-planbox pause
  Pause the timer for a task if it is running.

git-planbox finish
  Mark a task as finished. Stops the task's timer if it is running.

git-planbox help
  Display this help message.

The CLI makes use of the Planbox API. And since it is open source, it can be used as an example on integrating your own SCM with Planbox.

If you are using GitHub, Planbox integration is a breeze. Simply activate the Planbox service hook in GitHub and you'll be up and going. To do so, follow these instructions:

• In Planbox, go to the Initiative Settings page to retrieve your API token. Copy it to the Clipboard.
• In GitHub, select your repository and click on the Admin button.
• Click on Service Hooks and find Planbox in the list. Click on it.
• Scroll back up and locate the Token input. Paste the initiative API token and click on Update Settings

When you, or someone else in your team, performs a git commit, ensure to specify the Planbox item number in square brackets as described above. When a git push happens, GitHub will call Planbox passing every new commit. Planbox will create comments on the items specified, and optionally, complete them.

For example, assuming you just committed some changes with this message, and then performed a push.

Help copy for GitHub integration. [fix #1234]

In Planbox, the item #1234 will get this new comment and be completed.

Note
The email used in your commit must match your email in Planbox. If you don't see your commit appearing in comments, it may be because they do not match. GitHub allows you to have multiple emails.