Logo - Keleo


Software development company founded by Kevin Papst

Try it

You can test this plugin in our dedicated plugin demo:

  • Username: susan_super
  • Password: kitten

Find more testing accounts here.

Create free configurable additional fields for timesheets, customers, projects, activities and users.
Last update: 25 Jun 2019

A Kimai plugin, which allows configuring additional fields for timesheets, customers, projects, activities and expenses.


Configure additional fields for the following entities:

  • Timesheets
  • Customers
  • Projects
  • Activities
  • User
  • Expenses - see Expenses plugin

The custom fields will be shown on the “create and edit entity” forms and can have the following types:

  • string (simple text field)
  • integer (number without decimal point)
  • number (number with decimal places)
  • duration
  • money
  • language (dropdown of languages, shown in the users language)
  • currency (dropdown of currencies, shown in the users language)
  • country (dropdown of countries, shown in the users language)
  • color (browser specific input element to select a color)
  • date
  • datetime
  • email
  • textarea (multi-line text field)
  • invoice template (dropdown)
  • checkbox (on/off)
  • choice-list (drop-down)


You can create as many fields as you want for each data type, where each field:

  • is either optional or mandatory
  • has its own visibility, so the access can be restricted:
    • to certain customer/project/activity combinations (eg. a “location” field will only be shown for customer X and project Y)
    • to users with certain permissions or roles
  • can be described with a name and help text
  • has a maximum length of 255 character

The custom-field data is then available in:

  • Data-tables will display all visible fields
  • Exports (HTML and Spreadsheets include all visible fields)
  • Timesheet exports (include visible timesheet fields)
  • API (collections and entities)
  • Invoice templates (custom templates have access to all fields)

You can change the “weight” of custom-fields, so they show up in the order you define.

Be aware:

  • Restricted fields won’t be visible on the create forms, as Kimai initially can’t know if the rule will apply: in these cases the fields will only be shown in the edit forms
  • Sensitive data can be configured as “invisible”, so it will not show up in the above mentioned places
  • Custom fields for users are not exported via the API (this is a limitation in the core application)

Field types


Use the value 1 as default value for a pre-checked box or 0 for an unchecked box.

If a checkbox is marked as mandatory, the user has to check it in order to submit the form.


“Choice-list” is a different word for “Select-box” or “Drop-down”. You have to add the entries as comma separated list into the default-value field. For example a list consisting of fruits would look like this: Banana,Apple,Orange,Pineapple,Peach.

As the first entry is pre-selected, you can add an empty field to the dropdown by starting the list with a leading , like this: ,Banana,Apple,Orange,Pineapple,Peach. Combined with the mandatory flag, this will force your users to select an entry from the list to be able to submit the form.

Invoice template

A select box that is useful if you want to generate automatic invoices via command line / cronjobs.

The Kimai command bin/console kimai:invoice:create supports invoice templates via custom-field (see docs). The option parameter --template-meta takes the internal name of the custom field that will identify the invoice template to be used.


When logged in as SUPER_ADMIN, you should now see the custom-fields administration screen at /en/expenses/.

If this was successful, you can now think about giving permissions to other users as well.


This bundle introduces new permissions, which limit access to certain functions:

Permission Name Description
configure_meta_fields allows to administrate the custom field definitions

By default, these are assigned to each user with the role ROLE_SUPER_ADMIN.





The plugin is compatible with the following Kimai releases:

Bundle version Kimai version
1.15 1.11
1.14 1.10.2
1.10 - 1.13 1.9
1.8 - 1.9 1.7
1.6 - 1.7 1.6.2
1.5 1.6
1.3.2 - 1.4.1 1.4
1.1.1 - 1.2 1.1
1.0 1.0

Copy files

Extract the ZIP file and upload the included directory and all files to your Kimai installation to the new directory:


The file structure needs to like like this afterwards:

├── MetaFieldsBundle
│   ├── MetaFieldsBundle.php
|   └ ... more files and directories follow here ...

Clear cache

After uploading the files, Kimai needs to know about the new plugin. It will be found once the cache was re-built. Call these commands from the Kimai directory:

How to reload Kimai cache

bin/console kimai:reload --env=prod

FTP users: please have a look at this documentation.

If you are running an older version of Kimai (before 1.8) you have to use:

bin/console cache:clear --env=prod
bin/console cache:warmup --env=prod

You might have to set file permissions afterwards:

Fix Kimai file permission

You have to allow PHP (your webserver process) to write to var/ and it subdirectories.

Here is an example for Debian/Ubuntu (to be executed inside the Kimai directory):

chown -R :www-data .
chmod -R g+r .
chmod -R g+rw var/
chmod -R g+rw public/avatars/

Test Kimai before executing these commands (they are likely not required in a shared-hosting environment). You probably need to prefix them with sudo and the group might be called different than www-data.

Create database

Run the following command:

bin/console kimai:bundle:metafields:install

This will create the required database tables and update them to the latest version.


Updating the plugin works exactly like the installation:

  • Delete the directory var/plugins/MetaFieldsBundle/
  • Execute all installation steps again:
    • Copy files
    • Clear cache
    • Update database with bin/console kimai:bundle:metafields:install

All items by Keleo

Audit-Trail plugin

Records detailed change/audit logs for timesheets, customers, projects and activities and displays them in a per-item timeline.

Custom-fields plugin

Create free configurable additional (optional and mandatory) fields for timesheets, customers, projects and activities in various formats.

Expenses plugin

Keep track of your expenses based on a customer, project and activity. These expenses can be categorized and included in your invoices.

Kiosk plugin

Attendance time-tracking in an environment, where the user has no access to Kimai (eg. in a warehouse) by using a barcode or RFID scanner to start and stop timesheets.

Task management plugin

Create tasks, start/stop/pause them, assign them to users and teams - a todo-list management plugin that is connected to your time-tracker and adds two new dashboard widgets
Console client (PHAR)
Custom CSS plugin
Custom plugin development
Fail2Ban plugin
Grandtotal plugin
3rd party
Installation & Update support
Recalculate rates plugin