Timetracking and Attendance in ERPNext, integrated with Jira

Who is this for?

Companies that use Atlassian Jira for project management and ERPNext for time tracking and billing.

Features

• Allows logging of miscellaneous time, project time, breaks and paid breaks
• Allows to set a percentage of working time as billable time in a Working Time Log
• Rounds billable time to 5 minutes
• Fetches issue titles from Jira (used as time log description)
• Creates ERPNext Timesheets
• Creates ERPNext Attendances
• Report of actual vs. expected working time per Employee
• Sends email reminders to employees for submitting their draft working time entries
  • If a draft working time entry is older than 3 days, and
  • on the last working day of the month
• Working Time Policy enforcement per employee, including:
  • Maximum productive time per day
  • Mandatory break requirements based on productive time thresholds
  • Minimum rest time between days
  • Blocked weekdays
  • Holiday blocking (based on the employee's holiday list)

Setup

• Install this app

  bench get-app https://github.com/alyf-de/working_time
  bench install-app working_time

• Create a Jira Site, enter your Site URL, Username and a non-scoped API Token (scoped API tokens are not supported)

• Enable Ignore Employee Time Overlap and Ignore User Time Overlap in Projects Settings

• Open or create an ERPNext Project

  • Link it to your Jira Site
  • Set the Billing Rate per Hour

• Create Activity Cost records for your Employees (Activity Type: "Default")

• Create your first Working Time

  • Add a time log with description,
  • Add a time log and mark it as a break,
  • Add a time log and link it to a Project and Jira issue Key

• Submit your Working Time

Time Fields

Working Time separates productive time, break time and paid time:

• Productive Time (productive_time) is the total duration of logs that are not marked as breaks.
• Break Time (break_time) is the total duration of logs marked as breaks, including paid breaks.
• Paid Break Time (paid_break_time) is the total duration of break logs where Paid (is_paid_break) is enabled.
• Paid Working Time (working_time) is the paid total: Productive Time plus Paid Break Time. Number cards, stats and reports use this field as the paid working time total.
• Project Time (project_time) and Billable Time (billable_time) are calculated from non-break project logs.

In a Working Time Log, mark Break (is_break) for any physical break. Regular working logs are paid by default and should not be marked as breaks. Regular breaks are unpaid by default. Use Paid (is_paid_break) only for exceptional break rows that should count toward paid working time, such as mandatory but passive travel time.

Working Time Policy restrictions use Productive Time for maximum time and threshold checks, while mandatory break requirements use Break Time. This means paid breaks count as paid time, but do not increase productive time for policy restrictions.

German users may refer to this article for more information.

Notes on Time Logs

Each Working Time Log Note is either internal or external:

Type	Format	Used for
Internal	plain text	internal documentation only
External	starts with +, at least 3 characters after +	customer-facing invoice text

On save, billable rows without a Task or Jira Key must include an external note with at least 3 characters after +.

Short rules

No note required when any of the following applies:

• the row is a break
• a Task is set
• a Jira Key is set

External note required when:

• the row has a Project and Billable is greater than 0%
• no Task and no Jira Key

Decision flow

flowchart TD
    A[Working Time Log row] --> B{Break?}
    B -->|yes| OK[No note required]
    B -->|no| C{Task or Jira Key set?}
    C -->|yes| OK
    C -->|no| D{Billable > 0% and Project set?}
    D -->|no| OK
    D -->|yes| E{External note +... with 3+ chars?}
    E -->|yes| OK
    E -->|no| FAIL[Reject: add Task, Jira Key, or external note]

Loading

Examples

Scenario	Result
100%, no Task/Key, note = Fixed bug	Rejected - internal note does not count for billing
100%, no Task/Key, note = +Fixed bug	OK - external note satisfies billable rule
100%, no Task/Key, note = +ab	Rejected - external note needs 3+ characters after +
100%, Task set, no note	OK - Task satisfies billable rule

Billable Time Logs

Billable rows (Project set and Billable greater than 0%) must include at least one billing reference:

• a Task, or
• a Jira issue Key, or
• an external Note (starting with +)

Rows with only an internal note are rejected on billable rows. Billable time is rounded to 5-minute increments when Timesheets are created on submit.

Further Reading

Want to add pretty time logs to your invoice? Check out our print formats.

License

ERPNext extension "Working Time": Timetracking and Attendance in ERPNext, integrated with Jira. Copyright (C) 2024 ALYF GmbH and contributors

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.