Documentation for TROCK version 2.6, 3.0.

Release Notes

Previous Versions

User's Manual

General

Jira is great for issue tracking, and logging work is easy. But there is a feature missing: An overview of your logged work.

TROCK adds this overview to Jira including the following features:

• Have a look at what you’re logged for in a week-, month-, or custom time range view
• Log work directly in this view
• Quick-filter your logged issues for a project or a saved filter
• Show issues permanently, regardless if you’ve logged work on them or not

From the company’s point of view, these features could be interesting:

• Configure to forbid logging work for recent months
• Block or allow logging work by JQL

And from the managers point of view: Have a look of the logged work of a specific user or several users.

How To Display

Call the Logged Work page from your personal menu:

Navigation

Week-View, Month-View

Switch between week-view or month-view, navigate through the periods, or select a week or month directly using the date picker. The issues are shown in the Period Table labeled "In this period". This table shows issues with worklogs you logged on within the displayed period.

Custom Time Range

You can set an arbitrary time range up to one year. Instead of Week or Month, select Custom. The calendar symbol changes from a calendar to a pencil. Selecting Custom the first time, TROCK applies the previous time range from Week- or Month-view. Click the pencil button, and TROCK shows a dialog with start- and end-date input fields. Limitation is one year not to stress the browser that much and not let the user wait for a long time for the result.

There is not spinner until now indicating loading. So be patient at long periods.

The buttons for previous/next week/month as well as the short cuts "<-", "->", [t]oday and [d]ate picker are disabled.

TROCK remembers your set custom time range after returning from Week- or Month-view, even after the next log-in.

To ease setting of recurring start- and end-dates, TROCK proposes preconfigured time rages for quarters, half-years and full years: The time ranges with current date are displayed in bold.

To support orientation, the dates and sum-cells have tooltips displaying the date:

If the time range doesn’t fit to the screen, TROCK shows a scroll bar and also indicates this with "scroll arrows". You can click these arrows to skip to the end or back to the beginning of the time range.

Export to CSV

You can export the current view to a CSV text file.

TROCK exports the current viewed time range as comma separated data to an UTF-8 text file. The file name is e. g. trock_20180825151603_20180801-20180831_user1.csv and consists of:

• trock: prefix
• 20180825151603: Date and time of export, 2018-08-25 15:16:03
• 20180801: Start date 2018-08-01
• 20180831: End date 2018-08-31
• user1: In manager mode, the user the logged work is of, otherwise omitted

The Date format of the exported data is always a complete date like in Week-view, not only 01, 02…31 as in Month- or Custom-view. This ease possible processing of the export, and give orientation in custom time ranges greater than one month.

At import,

• choose comma as the delimiter character, and
• UTF-8 for text file encoding.

User Configuration: Quick Filter

If you are interested in specific issues you logged work on, use the quick project-or-filter-picker. While using, you can use the week/month selector, the navigation buttons, or the date picker; the selection will be retained. But reloading the page clears the picker.

Using the project- or-filter-picker, the table switches from the Period Table to the Filter Table. It is labeled with the project's or filter's name.

The sort order of a project is Jira’s natural one, which is by issue key descending. The sort order of a filter is the filter’s one.

If you select a project, only the issues with your logged work are shown, not all issues of that project. This is not to overload the browser with possible hundreds or thousands of issues.

Favorite Filter

You can select one favourite filter to display issues permanently. Click the cog-icon, select one favourite filter, and click OK.

Now two tables are displayed: The Filter Table and the Period Table. The issues in the Filter Table are ordered by the filter's sorting order. If the favourite filter contains an issue which would also be shown in the Period Table, this issue is shown only in the Filter Table.

An example case for the favourite filter:

You might think of one special JIRA project containing project-independent or time recording tasks. Write a filter to display these issues, as well as your assigned tasks.

Example: Filter "Permanent Tasks"

project = TIME or assignee = currentUser() ORDER BY key

The filter result will be shown until you select a different filter, or select “none”.

If the selected filter has been deleted or it’s permission has been changed, a warning symbol and a message is shown.

To fix this, select another filter or “none”.

Shortcuts

• w: Week-view
• m: Month-view
• c: Custom time range view
• <-: Previous week/month
• d: Show date picker in Week/Month-view, show Custom Time Range dialog in Custom-view
• t: Jump to week or month with today
• ->: Next week/month
• p: Focus project- or filter-picker
• r: Refresh (in contrast to the browser’s reload, the refresh retains the project- or filter-picker selection)
• e: Export to CSV
• u: Focus user picker (Manager View)

Manager View

TROCK allows users to see other user's logged work, if configured. The mapping who can see to who can be seen is configured by the Jira administrator, see Administrator's Manual. If you are allowed to see other's logged work, the Logged Work page shows you a user picker, preceded by the option to choose between “All allowed” or a specific one.

Regardless if "All allowed" or a single user is selected, TROCK always displays the result in the Filter Table only.

If you have selected “All allowed” or a user which is not you, you cannot log work.

All allowed

This option needs a project or filter selected in the project or –filter-picker.

“All allowed” means: Aggregated logged work of all users you are allowed to see, but limited to the issues in the project or filter.

If you have selected a project, only the issues with logged work are shown, not all issues of the project.

It could be the selected project or filter contains issues with worklogs of more users you are allowed to see. TROCK ignores that worklogs and indicates this by showing a red number. This is the number of users whose worklogs are ignored. Hovering over it shows a tooltip with more details in the form:

“6 worklogs of 4 authors are not displayed. This affects 3 issues. Because of the TROCK manager configuration you are not permitted to see all users worklogs.”

Administrator's Manual

Install

1. Download TROCK from Atlassian Marketplace
2. Install TROCK into Jira

Overview

Blocking

“Block by date” and “Block by JQL” settings apply to all parts of Jira where users may log work:

• Issue’s Log Work, Edit worklog and Delete worklog
• REST API
• TROCK Logged Work page

TROCK also respects the global Time Tracking setting (enabled/disabled) and the Work On Issues permission of the project’s permissions scheme.

Admin-setting “Block by date”

Block or allow logging work for previous month.

Admin-setting “Block by JQL”

Block or allow logging work by JQL. Set a descriptive message. This message is shown to the user if TROCK blocks logging work.

Manager View

TROCK allows mappings of 'manager-groups' to 'user-groups'. An empty user group means all users. Multiple manager- and user-groups per mapping are possible.

REST API

User Configs

GET http://localhost:2990/jira/rest/trock/latest/userconfigs

Results in:

[
    {
        "userKey": "user1",
        "reportType": 2,
        "startDate": 1548975600000,
        "endDate": 1551394799999,
        "customStartDate": 0,
        "customEndDate": 0,
        "filterId": null
    },
    {
        "userKey": "admin",
        "reportType": 1,
        "startDate": 0,
        "endDate": 1549234799999,
        "customStartDate": 1546297200000,
        "customEndDate": 1554069599999,
        "filterId": "0"
    }
]

Report Types:

1. Week
2. Month
3. Custom

Responses:

• 200 (OK): application/json, returns a list of users and their TROCK configurations stored in Jiras data base.
• 401 (Unauthorized): The currently authenticated user does not have system admin permission.

Dark Features

All dark features are controlled by the jira-trock.properties file.

Create file jira-trock.properties in one of these directories

• JIRA-INSTALL-DIR/atlassian-jira/WEB-INF/classes
• JIRA-HOME-DIR

with content:

##
# Create file jira-trock.properties in one of these directories:
#
#  - JIRA-INSTALL-DIR/atlassian-jira/WEB-INF/classes
#  - JIRA-HOME-DIR
#
# Deactivate and active TROCK add-on to reload these settings.
#


##
#  Dark Feature "isClientLoggingEnabled"
#
# You can switch frontend logging in browser's console on or off:
#   false, or commented out:  OFF
#   true:                     On
#isClientLoggingEnabled = false


##
#  Dark Feature "useUpdateAuthor"
#
# You can change the behaviour how TROCK looks for worklogs: By author which is the default, or by updateAuthor.
#   false, or commented out:  author
#   true:                  :  updateAuthor
#useUpdateAuthor = true


##
#  Dark Feature "exceptionToUITranslator"
#
# You can intercept an exception and print a message to the user by an exception-to-UI-mapping.
#
# Example:
#
# Image you have a SQL trigger for blocking some worklogs. If the trigger hooks in and blocks the worklog,
# it throws an exception:
#
# 2019-02-01 12:24:17,420 https-jsse-nio-8443-exec-9 ERROR      [o.a.c.c.C.[.[localhost].[/].[action]] Servlet.service() for servlet [action] in context with path [] threw exception [com.querydsl.core.QueryException: Caught SQLException for insert into worklog (issueid, author, updateauthor, worklogbody, grouplevel, rolelevel, timeworked, startdate, created, updated, id)
#     values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)] with root cause
# Error : 20000, Position : 12, Sql = insert into worklog (issueid, author, updateauthor, worklogbody, grouplevel, rolelevel, timeworked, startdate, created, updated, id)
# values (:1 , :2 , :3 , :4 , :5 , :6 , :7 , :8 , :9 , :10 , :11 ), OriginalSql = insert into worklog (issueid, author, updateauthor, worklogbody, grouplevel, rolelevel, timeworked, startdate, created, u
# pdated, id)
# values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?), Error Msg = ORA-20000: My SQL-Trigger has hooked in: This is my error-message from the stacktrace
# ORA-06512: at "JIRA.WORKLOG_INSERT_TRIGGER", line 108
# ORA-04088: error during execution of trigger 'JIRA.WORKLOG_INSERT_TRIGGER'
#         at oracle.jdbc.driver.T4CTTIoer11.processError(T4CTTIoer11.java:498)
#         at oracle.jdbc.driver.T4CTTIoer11.processError(T4CTTIoer11.java:446)
#
# TROCK offers two ways to show an error message to the user:
#
# 1. If the following regex is found in any line of the exception, show the message "My error-message!" to the user:
# exception.to.uimessage.mapping.1.regex = ^.+My SQL-Trigger has hooked in:\\s
# exception.to.uimessage.mapping.1.message = "My message!"
#
#
# 2. If the regex is found, show the string after the the regex to the user.
#   In this example, the resulting message is "This is my error-message from the stacktrace".
#  'exception.to.uimessage.mapping.1.message' is commented out or empty in this case:
# exception.to.uimessage.mapping.1.regex = ^.+My SQL-Trigger has hooked in:\\s
# Leave the message-property empty to let TROCK pick is from the stacktrace:
##exception.to.uimessage.mapping.1.message =
#
#
# You can define more than one regex by incrementing the index in the property:
#
#exception.to.uimessage.mapping.2.regex", "^.+Another regex:\\s