Integrates Harvest and FogBugz timetracking
PHP
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docker
src
.dockerignore
.gitignore
Dockerfile
bugyield
bugyield.php
composer.json
composer.lock
config.sample.yml
readme.textile

readme.textile

BugYield

BugYield is a console application which tracks changes to tickets (issues, work items, bugs whatever) across systems (two-way) to avoid tedious double registrations.
Which means that the developers only need to track time in Harvest, and then ticket-titles will be transferred automatically from your ticket system to the Harvest time entry AND time spend on that ticket will be synchronized in the chosen ticket-system.

BugYield currently supports two ticket management systems FogBugz and Jira and time tracking system Harvest.

Important note: We haven’t been using FogBugz for years, and cannot confirm it still works.

Installation

Clone the repository and remember to initialize submodules (“git submodule init” and “git submodule update”). Downloads are currently not functional as GitHub does not include submodules.
CURL and PHP 5.3 must be installed (5.2 won’t cut it!).
You might need to change the #! path in the “bugyield” file. Use “which php” in order to find the proper path.

Configuration

BugYield needs to know where and how to access the systems involved. This configuration is handled by a config.yml file. Copy the provided config.sample.yml and update it with account information. If your configuration file is not located in the root directory you can specify the path to the config file using the --config option.

Usage

BugYield currently supports two use cases:

  1. Time synchronization: Mapping entries in Harvest to time elapsed in FogBugz or Jira tickets
  2. Title synchronization: Mapping ticket titles from FogBugz or Jira to Harvest entries

BugYield works in the context of one or more Harvest projects identified through their id, full name or code. Projects can be specified in the configuration or using the --harvest-project option.

Run ./bugyield from the command line to show all available commands.

  1. Time synchronization example:
    ./bugyield tim --bugtracker=a-label Run BugYield with the bugtracker defined in config.yml with the label “a-label”
  1. Title synchronization example:
    ./bugyield tit --bugtracker=a-label Run BugYield with the bugtracker defined in config.yml with the label “a-label”

Just change the --bugtracker=XXXX with another label to run another bugtracker. We have current one FogBugz instance and two Jira bugtrackers configured in the same config.yml

Running in docker

When running in docker, you should mount in the config file:

docker run -v /path/to/config.yml:/bug-yield/config.yml reload/bug-yield

In development, you can mount in the full source and run a command immediately:

docker run -v /path/to/config.yml:/bug-yield/config.yml reload/bug-yield /bug-yield/bugyield --bugtracker=sometracker tim

Time synchronization

BugYield can update tickets in FogBugz and Jira with time registrations in Harvest. This makes it easier to show how much time has been spent on a ticket and how this corresponds with estimates.

It works like this:

  1. Add #[ticket-id] without the []’s in the Harvest entry notes
  2. Run the timesync command
  3. The elapsed time field for the FogBugz/Jira ticket is updated and a new comment/worklog is added to the ticket showing the entry id, the time spent, the task type and the notes from Harvest.

If the time or task for the Harvest entry is changed at a later point in time, subsequent execution of the timesync command adds a new comment to the ticket and the elapsed time field is adjusted accordingly.

If a Harvest entry contains multiple ticket ids the time spent is distributed evenly across the mentioned tickets.

If BugYield detects serious inconsistencies, then it will email the offending user and optionally a separately defined email address (e.g. to the Project Manager).

PRO TIP for JIRA

Make sure that the Closed state is editable in your Jira workflows, thus enabling bugyield to update worklogs on closed issues – see Jira documentation

Title synchronization

BugYield can update entries in Harvest with ticket titles from FogBugz and Jira. This makes it easier register time on specific tickets without typing other than the ticket-number (prefixed with a #).
NOTE: When an entry has been submitted and thereby locked, then we can’t edit the entry, and it will fail.

It works like this:

  1. Add #[ticket-id] without the []’s in the Harvest entry notes
  2. Run the titlesync command
  3. The entry notes in Harvest are updated with the ticket titles from FogBugz/Jira replacing #[ticket-id] with #[ticket-id]([ticket-title])

If a FogBugz/Jira ticket title is changed at a later point in time, subsequent execution of the titlesync command makes sure that the Harvest entry notes are updated accordingly.

To do

  • Disable support for FogBugz – we don’t use it anylonger and haven’t testet it for a long while.

Known errors and problems

CURL and SSL errors

When synchronizing with FogBugz we sometimes get SSL certificate errors. A quick fix is to make CURL ignore invalid SSL certifikates. Do that by adding this line to vendor/fogbugz-php-library/src/fogbugz_request.php on line 32:
curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,false); // added by rasmus, ignore SSL verification. @See http://unitstep.net/blog/2009/05/05/using-curl-in-php-to-access-https-ssltls-protected-sites/
I’m sure that there are better ways of handling this issue…

Brackets in ticket titles

If you put brackets in your ticket title, you make it difficult for BugYield to recognize our “codes”. It will handle the ticket, but display warnings and remove any comments on the Harvest entry created by the user.