Time Tracking: a new module in Atlassian Connect for JIRA

November 7th 2016 Simone Russo in Developer experience, Add-ons

We're happy to announce a new Connect module for JIRA: the Time Tracking Provider module. With the Time Tracking Provider module, JIRA administrators can add alternate time tracking tools and select which one should be displayed. This hides JIRA's native fields and buttons for time tracking so that add-ons can provide their own time tracking models. That way, users aren't confused about where to track time.

In this post, we'll show you how this new module works and how to implement it in your add-on.

The Time Tracking Provider module comes with a shiny new redesign of the time tracking configuration page. It now looks like this:

However, that's not all. We've introduced another major improvement from the old time tracking screen. Previously, this screen only allowed you to turn time tracking on and off. Now, you can select from a list of available time tracking implementations!

Your add-on can add one or more elements to this list by declaring a module of type jiraTimeTrackingProvider. This allows the add-on to use the new Time Tracking Conditions:

Condition key Evaluates to true when...
time_tracking_enabled any time tracking provider is selected
jira_tracking_provider_enabled JIRA's own time tracking is selected
addon_time_tracking_provider_enabled when a specific provider is selected (for example the one defined by your add-on)

Let's look at an example to see how this works.

First, we declare the jiraTimeTrackingProvider modules. In the descriptor below, we have defined two modules: one for an "advanced" feature (advanced-time-tracking-provider) and one for a "basic" feature (basic-time-tracking-provider):

"jiraTimeTrackingProviders": [
    {
        "key": "advanced-time-tracking-provider",
        "name": {
            "value": "Advanced time tracking"
        },
        "adminPageKey": "time-tracking-admin-page"
    },
    {
        "key": "basic-time-tracking-provider",
        "name": {
            "value": "Basic time tracking"
        }
    }
]

Note, the adminPageKey attribute is optional. If specified, it must reference the key of an Admin Page module defined in the same add-on. A link to this Admin Page module will be displayed under the 'Time tracking provider' dropdown.

After adding the jiraTimeTrackingProvider modules to your descriptor, they will be available in the 'Time tracking provider' dropdown:

Next, we will define two jiraIssueTabPanels; one for each time tracking provider. Check out the descriptor below (note, we're using the add-on key 'time-tracking-addon' in this example but you can substitute it for your own).

We've added an addon_time_tracking_provider_enabled condition to each panel. This condition ensures that the panel is only displayed if its related time tracking provider is selected in the time tracking configuration (as described previously).

"jiraIssueTabPanels": [
    {
        ...
        "name": {
            "value": "Advanced time tracking panel"
        },
        "conditions": [
            {
                "condition": "addon_time_tracking_provider_enabled",
                "params": {
                    "addonKey": "time-tracking-addon",
                    "moduleKey": "advanced-time-tracking-provider"
                }
            }
        ]
    },
    {
        ...
        "name": {
            "value": "Basic time tracking panel"
        },
        "conditions": [
            {
                "condition": "addon_time_tracking_provider_enabled",
                "params": {
                    "addonKey": "time-tracking-addon",
                    "moduleKey": "basic-time-tracking-provider"
                }
            }
        ]
    }]

The following screenshots demonstrate what happens to the issue tab panels when we select the different providers. You can populate the panel however you like.

Screenshot: Panel when time tracking is disabled
Screenshot: Panel when the advanced provider is selected
Screenshot: Panel when the basic provider is selected

The addon_time_tracking_provider_enabled condition can also be used on other module types, such as Pages, Web Panels, Web Items and more. Refer to the documentation to check whether a module supports conditions or not.

That's it! You should now understand how to use the Time Tracking Provider module in JIRA. You can find the source of the example add-on used in this post here. Happy developing!

If you have any questions please ask in the comments below or raise an issue in the Ecosystem Developer Service Desk.