The export module allows you to export filtered timesheet data into several formats.

Difference between export and invoice

There are a couple of differences in these two Kimai modules, the most important ones:

• Invoices can only be created for a dedicated customer, where an export can be created without selecting a customer
• Invoices do more calculation (e.g. tax)
• Invoices support self-created templates in more formats (e.g. XLSX, ODS, DOCX)

Security and privacy

Giving a user the permission create_export to export data, allows him to see most time related data in Kimai (like customer, projects, activities, rates, time worked per user and more).

The “mark as export” checkbox is only available for users with the edit_export_other_timesheet permission.

Export state

Invoices and exports share the export state, which is used to mark timesheet records as processed. These records cannot be edited any longer by regular users and are excluded by default from further invoices and exports.

You need to activate the checkbox before creating the export, to automatically set the export state on all filtered timesheet records.

For further information read the timesheet documentation.

Adding export templates

Since Kimai 1.9 you can add templates for PDF and HTML exports.

Export documents are searched in two locations:

• var/export/ - does not exist by default, please create it when you add a new template
• templates/export/renderer/ - don’t change files in here, will be overwritten with te next update

Be aware of the following rules:

• HTML templates have the file extension .html.twig
• PDF templates have the file extension .pdf.twig
• Templates are addressed by their filename
• You can use every document name only once.
  • Having var/export/default.html.twig and templates/export/renderer/default.html.twig will lead to unpredictable results
  • Use unique filenames and prefix them with your company name, eg acme-export.html.twig
• You should store your templates in var/export/, as this directory is not shipped with Kimai and not touched during updates
• You can configure different search directories through the config key kimai.export.documents if you want to add additional template source directories
• You can hide the default templates by setting the key kimai.export.defaults to an empty array / null

After you created a new or updated an existing template, you have to clear the cache to see the results:

bin/console kimai:reload --env=prod

rm -r var/cache/prod/*

Please copy & paste one of default templates to var/export/ as starting point and rename it afterwards.

You can translate the button for your template, by adding its name to the export translation file, eg. translations/export.en.xlf. Internally for each template a new ExportRenderer service is registered, called exporter_renderer.filename_EXT_twig (see ExportServiceCompilerPass).

PDF Templates

You can customize the following values from within your PDF templates:

• many mPDF options and configurations like the page format
• the generated filename by using the option named filename

{%- set customer = query.customers|length == 1 ? query.customers.0 : null -%}
{%- set filename = 'ACME_' ~ (customer is not null ? customer.name|replace({' ': '-'}) ~ '_' : '') ~ query.begin|date_format('Y-m') -%}
{%- set option = pdfContext.setOption('filename', filename) -%}
{%- set option = pdfContext.setOption('format', 'A4-L') -%}

PDF/A compliance

You can create a PDF/A1-b compliant document by setting these configurations in your template:

{%- set option = pdfContext.setOption('PDFA', true) -%}
{%- set option = pdfContext.setOption('PDFAauto', true) -%} 

Custom fonts

If you want to use a custom font in your PDF, you can configure it like that:

{%- set fontData = pdfContext.setOption('fonts', {
'demo': {
    'R': 'Demo-Regular.ttf',
    'B': 'Demo-Bold.ttf',
    'I': 'Demo-Italic.ttf',
    'BI': 'Demo-BoldItalic.ttf'
}
}) -%}
<style>
body { 
    font-family: 'demo', sans-serif;
}
</style> 

The font files must be stored in the directory var/data/fonts/ within the Kimai directory, in this case it would be:

• var/data/fonts/Demo-Regular.ttf
• var/data/fonts/Demo-Bold.ttf
• var/data/fonts/Demo-Italic.ttf
• var/data/fonts/Demo-BoldItalic.ttf

Page size

Want to display the PDF in a different size, e.g. because your customer expects US-Letter and not the standard size DIN-A4? Xou can add a CSS rule to your twig template:

<style>
@page { 
    sheet-size: LETTER-L;
}
</style> 

Available sizes are:

• A4, A3, Letter, Legal, Executive, Folio, Demy, Royal, A, B, Ledger, Tabloid …
• A4-L, A3-L, Letter-L, Legal-L, Executive-L, Folio-L … for landscape

More information available in the MDPF documentation and the full list of available sizes can be found here (check format).

Custom fields

You can access custom fields with:

{% set cf = entry.metaField('example') %}
{% if cf is not null and cf.value is not null %}
    {{ cf.value }}
{% endif %}