Custom-fields plugin

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

Features

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)

Documentation

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

Checkbox

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

“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.

Usage

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.

Permissions

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

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

Compatibility

The plugin is compatible with the following Kimai releases:

Copy files

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

var/plugins/MetaFieldsBundle/

The file structure needs to like like this afterwards:

var/plugins/
├── 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:

bin/console kimai:reload --env=prod

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

You might have to set file permissions afterwards:

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

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