Getting started with Worklog Assistant

Super quick start

  • Right-click on any field header to show or hide. Extend or shrink columns by dragging edges
  • Double-click an issue to start tracking time against it
  • Double-click again to stop
  • Switch to the "Pending Worklogs" tab
  • Double-click any specific attribute you would like to change about the worklog
  • Click "Publish Worklog"
  • Repeat

For System Administrators

If you are interested in deploying Worklog Assistant across a company network, the deployment guide may be of some assistance.

Prerequisites

Worklog Assistant requires JIRA® 3.1 and up with the SOAP API enabled. Ask your JIRA® administrator to follow the instructions here in order to enable RPC calls: Enable SOAP for JIRA®. Specifically, see the "Accept remote API calls" section.

Launching Worklog Assistant

After installing Worklog Assistant, you can find the launch icon in your quicklaunch bar on Windows or under the "Worklog Assistant" entry in the Programs submenu. On Ubuntu or Debian, you can find it in the "Office" menu.

Configuring Worklog Assistant

Configuring connection to JIRA® server

The first time you launch Worklog Assistant, the configuration dialog is shown. If you ever need to go back to this dialog, you can click the "Configuration" button from the main screen.

The only information Worklog Assistant needs from you:

  • Username: The user ID you use to log in to JIRA®
  • Password: The password matching the above ID.
  • Server URL: The URL of the JIRA® server. Usually something like http://jira.mycompany.com. HTTPS is supported.

The password is stored encrypted using the OS-provided keychain so it is secure and only the logged in user can decipher the password.

Controlling worklog visibility

When worklogs are submitted through Worklog Assistant, by default, they are visibile to everyone who has access to the project. By choosing a project role for the purposes of worklog visibility, Worklog Assistant will use that specific project role when submitting all worklogs.

Choosing a filter

Choosing a filter

Worklog Assistant relies on the user having set up filters in JIRA® beforehand. See here for instructions on how to create a filter.

Once you have set up your filters, the drop-down box is populated with your list of filters. Nominally, Worklog Assistant chooses one to start with. If you would like to use a different filter, choose one from the drop-down.

The issues in the table below the drop-down are the issues matching the filter.

Start tracking time

Tracking time

The fundamental operation in Worklog Assistant is tracking time. Once you have selected an appropriate issue filter, you simply double-click the issue you are interested in tracking time against. Immediately, the row representing the issue has a background of bright green.

When you are done tracking time against the issue, simply double-click it again.

The "Pending Worklogs" tab should now contain the number of unpublished worklogs. For example, it may read "Pending Worklogs (1)" if you have one unpublished worklog.

Note: It is very important not to switch filters while tracking time against an issue otherwise Worklog Assistant stops tracking time against it.

Making notes while logging time

Making notes while logging time

To make notes while working on an issue, use the text box at the bottom of the screen. When you turn the timer off, the notes are used as the worklog comment when submitted to JIRA®.

Generate a timesheet

To see a summary of the week's work, click the "Timesheet" tab as shown below.

Timesheet tab

You can use the date navigation controls to view different periods of time. To choose a specific period, click the button with the calendar icon.

To import worklogs from JIRA for the current period, click the "Import" button. Then choose a filter or execute a JIRA search to retrieve a list of issues that you want to import.

Import worklogs

Timesheet example

Export timesheet

Using custom scripts, you can export worklogs to a system of your choice. Use the "Export" button on the timesheet tab.

Detecting idle time

Periodically, you may be away from the computer in a meeting or at lunch. Worklog Assistant detects when you are away from the computer and stops the active task. Upon your return, Worklog Assistant will prompt the user to ask whether they would like to apply the time away to any specific task. See the screenshots directly below for examples.

Worklog Assistant detecting idle time.

Choose a task for applying your away time

Apply the away time to a JIRA® task with comments.

Amending Filters

In some cases, it is inconvenient to create a filter specifically for the purpose of tracking against a single issue. In this case, you can add a comma-separated list of issue keys (PROJ-NNNN), as shown in the screenshot below. This list will be added to any filter that you view and will persist across invocations of Worklog Assistant.

Add a comma separated list of issue keys to amend the issues a given filter returns

Logging Work Manually

By right-clicking on an issue and selecting "Log Work", a dialog will pop up where you can edit a new worklog entry. This worklog entry will be added to the "Pending Worklogs" tab.

Workflow and context-sensitive actions

Workflow and context sensitive actions

Worklog Assistant supports the execution of context-sensitive workflows through the context menu (right-click) for a specific issue. For workflow transitions that do not require input from the user, no further action needs to be taken. For workflows that need input, your default browser wil be launched and take you directly to the workflow transition page.

Note: For transitions that reqiure input, you may be required to login first.

You may also add a comment to the selected issue by choosing the "Add Comment" action from the context menu.

Publish worklogs to JIRA®

Submitting worklogs to JIRA®

Switch to the "Pending Worklogs" tab and click the "Publish Worklogs" button.

In some cases, you may want to modify some of the attributes of the worklog. You can do this by double-clicking the relevant field.

For the field labeled "Elapsed", you may enter JIRA®-like timestrings described in hours and minutes as well as fractional hours.

Example valid strings are:

  • 1.5h
  • 1h
  • 1h 5m
  • 5m

Invalid strings include:

  • 1.5h 5m
  • 1d
  • 1.5m
  • 1w

For the field labeled "Remaining time estimate", you may enter JIRA® timestrings which indicate how much longer you expect to work on this issue. Worklog Assistant will attempt to parse the string as described above otherwise it will be left as is.

Worklog rounding

Rounding and consolidating control

If you prefer to have Worklog Assistant round worklogs and/or collect all related worklogs into a single worklog before publishing, you can use the controls shown above in bottom of the "Pending worklogs" screen. By default, both functionalities are disabled.

Consolidating worklogs

Consolidating worklogs allows you to ensure that you only submit one worklog per issue. Consider the logged time below:

Pending worklogs before consolidation

By pressing the "Consolidate worklogs now" button, the worklogs for each issue will be combined into a single worklog, as shown below:

Pending worklogs after consolidation

Notice that the total time logged for each issue remains the same and that the comments have been aggregated.

Worklog rounding

Rounding worklogs allows you to ensure that odd-minute worklogs are never logged. This allows for more aesthetic reports as well as the ability to implement time billing policies. To ensure that the rounding is unbiased, the user has controls which allow for a form of "banker's rounding" as applied to worklogs. That is, in some cases, the worklogs will be rounded up, in other cases, they will be rounded down. This is "fair" rounding.

Still considering the above example, by modifying the controls, we can round to the "nearest" 15 minute interval as shown below:

Modifying the default rounding behaviour

By clicking the "Round above worklogs" button, we obtain the following results:

Result of rounding worklogs using above controls

Observe that the "fair rounding" has rounded one set of worklogs up (1h 15m) and one set down (15m).

This feature can be controlled in enterprise deployments. See the deployment guide.

Hiding uninteresting fields

Hiding uninteresting fields

If you want to hide columns in either the Issues or Pending Worklogs tab, right-click on the column headers and choose which columns to show or hide. These settings will be saved for you.

Custom Field Support

Worklog Assistant supports custom fields for JIRA 5+

Working Offline

By selecting the "Work offline" checkbox on the top-right of the main screen, Worklog Assistant will sync all the filters in your list and work offline. You can now log work, run client-side filters and switch between filters all while working disconnected. Please note that synchronizing may take some time for filters with a large number of issues.

Work offline

Extending Worklog Assistant

Worklog Assistant allows you to execute custom scripts at various times. Some of the things you can do with this functionality:

  • Manage branches for issues you work on.
  • Look up external information.
  • Export worklogs to other systems.
  • Take screenshots of your desktop.
  • Your imagination is the limit!

This is accomplished by including different types of custom scripts:

  • Context menu - These scripts are executed by the user by right-clicking an issue and selecting the "Custom" menu
  • Worklog export - These scripts are executed by the user when s/he wants to export their recorded worklogs into a different format.
  • Issue Timer Toggle - These scripts are executed when an issue's timer is toggled on or off. When the issue is toggled off, the extra variables JIRA_CurrentWorklogElapsedTime and JIRA_CurrentWorklogElapsedTimeInSeconds are included in the environment.
  • Timed script - These scripts are executed once per minute. If an issue timer is active, then the issue's information is included in the environment along with the elapsed time variables referred to above.

Once a custom script is defined (see below), you can execute them using the context menu by right-clicking on an issue and choosing the command you want executed. A sample menu is shown below:

Custom Scripts Menu

Defining Custom Scripts

Custom scripts can be defined using the configuration dialog as shown below. Also shown is simple example of how a script can give feedback by simulating an error condition (non-zero exit code).

Custom Scripts Configuration

Each script is executed using the platform's command interpreter:

Windows cmd.exe
Mac and Linux /bin/bash

To access the fields of the selected issue in the script, prefix "JIRA_" and replace all spaces with an underscore. For example, to access the "Original estimate" field, use:

Windows %JIRA_ORIGINAL_ESTIMATE%
Mac and Linux $JIRA_Original_estimate

As of this writing, the issue fields provided are:

  • JIRA_Assignee
  • JIRA_Created
  • JIRA_CurrentWorklogElapsedTime - Note: only if the timer is running
  • JIRA_CurrentWorklogElapsedTimeInSeconds - Note: only if the timer is running
  • JIRA_Description
  • JIRA_Due_date
  • JIRA_ID
  • JIRA_IsSubtask - Available as an environment variable(=1) if the task is a subtask
  • JIRA_Key
  • JIRA_LoginPassword - The password used to login (used for performing extra actions against JIRA)
  • JIRA_LoginUser - The username used to login
  • JIRA_Original_estimate
  • JIRA_Original_estimate_in_seconds
  • JIRA_Pending_worklog_totals
  • JIRA_Pending_worklog_totals_in_seconds
  • JIRA_Priority
  • JIRA_Project
  • JIRA_Rank
  • JIRA_Ranking
  • JIRA_Remaining_estimate
  • JIRA_Remaining_estimate_in_seconds
  • JIRA_Reporter
  • JIRA_Resolution
  • JIRA_Status
  • JIRA_Summary
  • JIRA_Time_spent
  • JIRA_Time_spent_in_seconds
  • JIRA_Type
  • JIRA_Updated
  • JIRA_ViewUrl - The URL to use to view the issue
  • JIRA_Votes

If you are creating a worklog script, the script will have the issue's fields as above available as well as the following fields for the worklog:

  • JIRA_WorklogID
  • JIRA_WorklogIssueID
  • JIRA_WorklogAuthor
  • JIRA_WorklogComment
  • JIRA_WorklogCreated
  • JIRA_WorklogGroupLevel
  • JIRA_WorklogRoleLevelID
  • JIRA_WorklogStartDate
  • JIRA_WorklogStartDate_TimeT
  • JIRA_WorklogTimeSpent
  • JIRA_WorklogTimeSpentInSeconds
  • JIRA_WorklogUpdateAuthor
  • JIRA_WorklogUpdated
  • JIRA_WorklogExportWhich - Number identifying which worklog in the series (1-based)
  • JIRA_WorklogExportTotal - Total number of worklogs that will be exported
  • JIRA_WorklogExportDirectory - A directory you can use (might have to create it) to put auxiliary data
  • JIRA_WorklogExportStartDate_TimeT - Start date for export in time_t format (may or may not have any worklogs on this date)
  • JIRA_WorklogExportEndDate_TimeT - End date for export (ditto)

Worklog Assistant includes a nominal screenshot utility as well. This is available through the JIRA_TakeScreenshot parameter. The usage should be:

$JIRA_TakeScreenshot /path/to/file.png

Examples

Here are some examples that demonstrate various custom scripts with varying degrees of complexity.

  • Worklog Export - A fairly complex script which exports all worklogs and creates a report similar to the built-in report for Worklog Assistant.
  • Logging work to subtasks only - An example of how to restrict the types of issues for which you can log work. Also an example of how to use custom scripts to create a commit message.
  • Switching branches - An example of how you can use Worklog Assistant to switch branches the names of which are keyed on the issue key itself.
  • Worklog Assistant: Custom Workflows - A blog post by Don Bosco Nguyen van Hoi of Mothership GmbH describing how to use Worklog Assistant to execute custom transitions when you start working on an issue.