As a consultant, keeping track of my time is obviously very important. I use Toggl to track every task (billable or not) that I work on for each client. However, I also have to update each client’s Jira project with the time I spent on each ticket as well as our billing system’s timesheet (we’ll leave that for another post and another day). This used to be a very manual process. I would have to check Toggl reports for each day and then log into Jira, pull up the ticket, and add a worklog. Here is where TogglToJira comes in.
TogglToJira provides a basic level of automation. I no longer have to manage the worklog entries in Jira. I only have to keep track of my time in Toggl. Here is how it works. In Toggle, I have each client and project setup. Each task that I work on is simply the ticket number from Jira (in a future version I will pull the ticket number from either a tag or the Toggl task ID so that I can use the description field as the worklog comment). TogglToJira uses YAML files to understand which clients get worklog entries created as well as the URL for their Jira instance (and what credentials to use with Jira’s REST API). I do this because not every client uses Jira and not every task gets logged to a Jira ticket (we have internal non-billable tasks that don’t get logged to tickets, but the time still needs to be reported in our timesheet system). The YAML for the Toggl settings looks like this:
--- workspace_id: user_agent: TogglToJira api_token:
Now you can probably guess, finding the workspace_id is a little cumbersome. I wish the Toggl API allowed you to either specify a workspace name or to allow you to simply use your default workspace. Alas, it doesn’t. So to find your workspace ID, go to https://www.toggl.com/app/workspaces and click the little box to the left of the workspace name you want to work with. Choose “Settings” from the dropdown menu. You are taken to a page where you can edit the settings for that workspace. Your workspace ID will be in the URL of your browser (it’s the number at the end of https://www.toggl.com/app/workspaces/edit/).
The user_agent can be left set at TogglToJira as long as you are not making any changes to the code (if you do plan to make changes, please set the user_agent to your email address. This will allow Toggl to identify your API calls and let you know if you are doing something bad/wrong).
You can find your api_token on your profile page at https://www.toggl.com/app/profile.
You also need to configure the YAML file for your Jira sites should look like this:
--- Sites: Jira1: url: user: pass: Jira2: url: user: pass: Clients: Client Name From Toggl1: site: Jira1 Client Name From Toggl2: site: Jira2
Here you will define sites and clients. Each site corresponds to a Jira instance. Many of our clients have their tickets managed in our Jira instance. So I set those up under “Jira1” providing the base URL for the Jira instance (e.g. https://yourcompany.atlassian.net or https://yourcompany.jira.com) along with the same credentials I use to log into the web interface. I setup each client using the name I gave the client in Toggl and then a reference to the site that client is using for Jira.
Now for the fun part: running it. You can execute the process from a terminal window by running:
php bootstrap.php [date in format yyyy-MM-dd]
The date is optional. If you don’t specify it, then it will use yesterday’s date. Below is an example of the output you should see:
******** Created Jira Worklogs ********** Array (  => Client1 ticket CLIENT1-123 was logged on 2014-08-01 for 0.75h  => Client1 ticket CLIENT1-456 was logged on 2014-08-01 for 0.5h  => Client2 ticket CLIENT2-789 was logged on 2014-08-01 for 0.25h ) ******* No Jira Worklogs Created ******** Array (  => Internal task Timesheet was NOT logged on 2014-08-01 for 0.25h ) *****************************************
I’ll admit, the output is a bit rudimentary. But it works for my needs. Check out the project on GitHub and let me know what you think in the comments below.