Handling time buckets

This article is for Tempo for Cloud.

Please contact Atlassian Support for any Jira Automation related questions. Also, please join Tempo Ecosystem for Developers for Tempo REST API related questions.

In the Professional Service Industry it is very common to deal with negotiated time buckets between the service provider and customer. The Service provider needs to make sure to deliver the content but also needs to make sure to not extend the time budget agreed on. You (or your service manager) want to get notified when the time spent has reached a certain threshold (e.g. 75 or 90% of the negotiated budget). By leveraging Tempo Accounts and Automation for Jira you could achieve that and we show you how. The tutorial is guiding you through one scenario but you want or need to adapt according to your needs.

Setup

Tempo Accounts are well suited to keep track of service contract efforts. Tempo Accounts can be assigned (as a Jira custom field) to several Jira issues that are distributed in multiple Jira projects. All time tracking information is collected on Account level. In this guide we leverage a long forgotten field inside the Tempo Account which is called “monthly budget”.

The Tempo Account is assigned to several issues. Now we need to check when time is logged against the Tempo Account and ensure that the monthly budget has not been exceeded. If we have used our budget, then we want to send a notification email to our stakeholders.

Automation Trigger

For our automation trigger we select “Work logged” and select “all worklog operation” (create, edit and delete). Even though that the work is logged inside Tempo the Jira worklog event will get fired.

A change on the Tempo worklog attributes will not fire the event. Only changes to the worklog description or the amount of time logged.

Check

Once the worklog event is triggered we can collect all the information for the worklog event during our automation rule. The information we will need is time logged and when but we will also need the Jira issue and its associated information. The first thing to check is if there is a Tempo Account assigned to the Jira issue where the time has been logged against.

Get the Tempo Account

Now we have the information about the Tempo Account on the Jira issue and can access it through the smart value:

{{issue.Account.id}}

Since we will leverage the Tempo REST API to gather the time spent on the account and the REST API endpoint can use Tempo Account id, we will do a web request to the endpoint:

https://api.tempo.io/4/accounts/{{issue.Account.id}}

In the response we will get the information about the Tempo Account:

{
    "self": "https://api.tempo.io/4/accounts/35",
    "key": "BJT",
    "id": 35,
    "name": "BJT",
    "status": "OPEN",
    "global": false,
    "monthlyBudget": 20,
    "lead": {
        "self": "https://cops.atlassian.net/rest/api/2/user?accountId=5b198320e249415c02f69600",
        "accountId": "5b198320e249415c02f69600"
    },
    "category": {
        "self": "https://api.tempo.io/4/account-categories/BILL",
        "key": "BILL",
        "id": 2,
        "name": "Billable",
        "type": {
            "name": "Billable"
        }
    },
    "customer": {
        "self": "https://api.tempo.io/4/customers/17",
        "key": "BJT",
        "id": 17,
        "name": "BJT"
    },
    "links": {
        "self": "https://api.tempo.io/4/accounts/BJT/links"
    }
}

Make sure you check the option “Delay execution of subsequent rule actions until we've received a response for this webhook” to make it possible for automation rule to work with the information from the webhook response.

Now we want to store some values from Tempo Account API to create variables to use later. First, we get the variable

Account key with the smart value:

Please repeat the same web request a few more times to get the variable

Account name with the smart value:

and we can access the information about the variable:

the Monthly budget with the smart value:

We store the monthly budget information as a variable to access that information later in our automation rule.

Additionally, we can grab the Account Lead’s Atlassian ID to send the email notification to that person.

Get Time tracking information on the Tempo Account

Now we have all information we need to gather the time tracking information for the Tempo Account. Therefore we will leverage the endpoint:

Since we only interested in the amount of worklogs for the month where the worklog has been created we need to leverage the “from” and “to” parameters. Since Jira allows us to set the first day of month and the last day of month with smart values we set the “from” parameter to:

and the “to” parameter accordingly to:

Since Jira automation we don´t want to do extra work by looping through the paginated response we should exceed the returned results parameter to the maximum of 1,000 by passing the “limit” parameter:

The final API call will look like:

If you have expected more than 5,000 worklogs per account per month (guess it is very unlikely) you will need loop the response(s) by leveraging the "next" parameter in the API response in the “meta” section.

Please check the “Delay …” option. Now we can easily grab the total amount of hours spent from Tempo Account API:

Since it will return the results in seconds, you will need to convert it into “hours” by dividing the sum by 3,600, then round it up to an integer value and store the value as a variable {{HoursSpentInMonth}} to make further calculation easier.

Finally, we will compute the amount of time (in percentage) spent during the month and store it in the variable {{BudgetUsed}}:

Get Tempo Account Lead

Now we have gathered all the info through this automation. We need to get the Account Lead’s email address(es) to send out notification with the variable {{AccountLead}} by using this Jira REST API. Please use Jira API Token in this case.

Store the email address(es) to the variable {{AccountLeadEmail}}.

Email Notification

We will check if the time spent has reached our threshold of 90% of the monthly budget.

When the condition is met, we can compose message leveraging all of the Account info gathered during the automation for the receiver(s) to take action.

When condition is not met, a different notification can be sent out instead. But this is setup mainly for testing purpose to make sure the automation run correctly.

Sample Email: