Time tracking
The general information on time registration is described under time registration. This page specifically describes the how to track time.
To make time tracking as light as possible, we register everything in Kimai. Sign in with the SSO button; it is the same account you use everywhere else.
Kimai runs on our own infrastructure and is reachable from the office network and over the VPN, so tracking time from a train needs the VPN on your phone. The site works in a phone browser and can be added to your home screen.
Configuration
Section titled “Configuration”Your account is set to the Dutch locale nl_NL, which is what gives you
DD-MM-YYYY and a 24-hour clock, while the interface itself stays English. Both
live under My profile -> Preferences, next to your timezone, so change them if
you prefer something else.
A brand new account starts on the English locale, which means M/D/YY and an
AM/PM clock. Kimai has no way to default that per company without switching
everyone’s interface to Dutch, so set it once after your first sign-in.
What hours to book
Section titled “What hours to book”Generally, when you’re not working, you don’t book any hours. So, the lunch break or walking the dog 🐶 is not included as working hours. So you don’t enter those in Kimai.
If you worked on one topic all day, you can just book 8 hours of work on a project and fill in a short description (preferably with a link to an issue) through My times.
If you work on several topics during the day, it makes sense to use the time tracker as “stopwatch” allowing you to start/stop time tracking at the start and end of the activity. You fill in what you did per activity and assign different projects where needed to each activity.
Projects
Section titled “Projects”For several reasons described later, it’s important to pick the right project to attach your booked time to. You can see the full list of projects here.
For new clients and projects, you can obviously create a new project. A project
belongs to a customer, which is the client it is billed to; our own work sits under
the customer d-centralize.
Every entry also carries an activity. Pick General unless the project has a more
specific one.
Customer orders and epic links
Section titled “Customer orders and epic links”Each separately awarded customer project has its own Kimai project. Verify the offer and award letter, then search active and archived projects by their references before creating a project under the customer being billed.
Record the verified references in these Kimai project fields:
| Kimai field | Value |
|---|---|
| Project number | Our offer number |
| Order number | Customer order reference, including any required invoice reference codes |
| Order date | Date of the customer’s award |
| Description | Offer date, source documents, awarded scope, billing contact and epic URL |
| Time budget | Maximum agreed hours for the whole award, including agreed reserve hours |
Link to source documents when they are available in a shared system; otherwise include their exact filenames and dates. The owning epic links directly to the Kimai project and names its customer, project, offer and order references, as described in epic guidance.
Use a lifetime time budget for the whole award. Record planned work and reserve hours separately in the project description and owning epic, with their total as the maximum. Show budgets and progress in hours only, without monetary values. Verify the hour limit against the contract and supporting agreement; label a planning estimate as an estimate. If no hour limit is agreed, ask the owner to confirm one rather than presenting an estimate as a contractual maximum.
Compare all recorded project hours with the hour budget to assess delivery effort. Kimai’s built-in remaining-budget calculation counts only billable entries, so also check the project’s total recorded hours. Reconcile earlier bookings when creating a project for work already in progress. Keep live usage in Kimai; date any progress snapshot added to an epic.
Book time to the project that owns the work, including work that enables another project. Split time entries when switching projects. Multiple mission labels or a shared dependency do not combine separate customer awards into one booking destination. A child epic with its own award uses its own Kimai project.
Project Structure
Section titled “Project Structure”There’s a convention around project names.
Project names start with Appsemble |, ITSLanguage |,or d-centralize | to indicate what company to book the hours under.
Within the Appsemble | your have the “catch all” project simply called Appsemble, but
try not to use such generic “projects”.
A bit more specific is Appsemble | Core development if you’re working on just that.
If you’re working for a client, use Appsemble | Eindhoven.
If you’re working on a specific app for client, use: Appsemble | Eindhoven | Team Barometer.
There’s a special case for interns, please split the hours you work on a project as described above, but use the
d-centralize | Internship project for mandatory school work. This allows us to see the real amount of time that went
in a project excluding the internship related work.
Next to the regular projects to book your hours on, there are special projects:
Leave | Official holidays(non-working days): book 8 hours when a day is listed as Public/National holiday and paid day off (see Holidays). If it’s not a paid day off, the general guideline applies: you’re not working, so no need to book hours.Leave | Personal holiday(personal holiday hours): when you don’t feel like working for (part of) the day. More on how this works at Statutory leave.Leave | Sick: book the hours to this “project” when you’re unfit to work.Leave | Maternity leave: when you’re on maternity leave.
In addition to a project and a description, it might be important to add tags as well.
This is only needed when you’re working on a client project so we know what percentage of
your time to bill the client for.
In the following example, we’ll be working on client project Appsemble | Restaurants Management.
| task | cost bearer | use these tags |
|---|---|---|
| If app X suffer from something buggy in Appsemble, now or in the near future | 100% appsemble. | CB_APPSEMBLE |
| If it’s feature where app X is the first user but it’s clear other apps in the future benefit too. | Split between appsemble and client | CB_SPLIT |
| Clearly a feature for app X without any other app using it soon in sight. | 100% client | CB_CLIENT |
Using these tags we can fairly bill clients. Especially with Appsemble, we’re working on core features the first time a clients needs them. It’s not always fair to bill them for it fully. It’s important to use these specific tags so our billing scripts recognise them. A tag has to exist before you can attach it: ask an admin to add one rather than typing a new name and assuming it stuck.
Issue and MR links
Section titled “Issue and MR links”When billing clients, a script verifies if an issue is mentioned in the form of <project>#<issue number>.
When the reference is written like support#123, the script will rewrite it to https://gitlab.com/appsemble/support/-/issues/123.
Similar to appsemble#123, the script will rewrite it to https://gitlab.com/appsemble/appsemble/-/issues/123.
You can also link a MR using appsemble!123.
If you can, prefer linking an issue over a MR.