Version 1.1.0 · Redmine 5.1 and 6 · GPLv2
This manual covers installation, configuration and daily use of the atori invoicing plugin.
The plugin adds customer master data, draft-to-paid invoice workflow, ZUGFeRD 2.x-compliant PDF output and payment tracking to Redmine. Invoices are independent of Redmine's project and issue models, but individual invoice items can reference approved TimeEntry records to build billable line items straight from tracked hours.
Key concepts:
TimeEntry records for traceability back to the tracked hours.prawn and prawn-table (installed via the plugin Gemfile)files/ for generated PDFscd /path/to/redmine
unzip at_rechnungstellung-1.2.0.zip -d plugins/
bundle install
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# restart Redminebundle install is required here because the plugin brings its own Gemfile declaring prawn and prawn-table.
cd /path/to/redmine
git clone <repo-url> plugins/at_rechnungstellung
bundle install
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung RAILS_ENV=production
# restart RedmineAfter restart, log in as administrator and open Administration → Plugins. The Rechnungstellung plugin should appear with version 1.1.0. Invoices and Customers entries should appear in the top navigation for users with the corresponding permissions.
cd /path/to/redmine
bundle exec rake redmine:plugins:migrate NAME=at_rechnungstellung VERSION=0 RAILS_ENV=production
rm -rf plugins/at_rechnungstellung
# restart RedmineThe rake task rolls back the plugin's migrations and drops its tables (customers, customer-project mapping, invoices, invoice items, time-entry links, payments). Core Redmine data is untouched.
Open Administration → Plugins → Rechnungstellung → Configure. The settings are grouped into four sections:
Issuer details – name, address, country, tax number, VAT ID, email, phone, website, bank details. These populate the header and footer of every generated PDF.
Invoice numbering – number format (e.g. RG-{YYYY}-{NNNN}), padding for the sequential counter, default currency, default VAT rate, default payment terms (in days).
PDF layout – logo position (left or right, configurable margin and width), colours (primary, secondary, title, total gross), font, table styling (zebra, border style, padding), DIN-5008 letter-head block, margins, free-form intro / thank-you / legal text.
E-mail dispatch – default subject and body templates, optional BCC address for the issuer's archive.
Settings live in a dedicated partial and are all form fields – no YAML or environment variables.
Three independent global permissions are exposed:
| Permission | Scope | Typical role |
|---|---|---|
| View invoices | Read invoices and payments | Accountant |
| Manage invoices | Create, edit, issue, cancel, email | Project manager, accountant |
| Manage customers | CRUD on customer master data | Project manager |
All permissions are global (not per-project), matching how accounting typically operates across the organisation.
At the bottom of the plugin settings page a Demo PDF section offers a download link that renders a sample invoice PDF using the current issuer details, logo, colors, number format and PDF-layout options. No real customer or invoice is created; the sample uses a fictional "Musterfirma GmbH" with three line items (two at the default VAT rate, one at 7%) to exercise typical table layout, thousands separators, and multi-rate totals.
Workflow:
The demo PDF is rendered through the same builder as real invoices, so what you see here is what customers will receive.
Customers → New customer. Fill in name, address, country code (ISO 3166-1 alpha-2), optionally VAT ID, tax number and banking data. Assign one or more Redmine projects to enable their time entries to be pulled into invoices for this customer.
Choose the customer's e-invoice format: ZUGFeRD (default, B2B), XRechnung (for German public-sector recipients) or none (plain PDF only). For XRechnung customers, enter the Leitweg-ID – this is mandatory per the XRechnung specification and is validated on save.
Invoices → New invoice. Pick a customer; the issuer data is taken from the plugin settings. Add line items manually, or use From time entries to pull approved hours for a date range and a project. Items can mix sources freely – tracked hours alongside flat-fee manual lines.
Each item carries its own unit, unit price and VAT rate so mixed-rate invoices (e.g. 19% + 7% in Germany) produce correct totals without manual reconciliation.
Preview renders the PDF on the fly from the current draft without persisting. Useful for visual checks during editing. The preview is not numbered – number assignment happens only at issuance (see next).
Issue assigns the next invoice number according to the configured format, sets the state to issued, and finalises the document. Issued invoices are read-only: the underlying PDF and the invoice number become the commercial record. Changes require cancellation (see §5.7) and a new draft.
The e-invoice output matches the customer's configured format: ZUGFeRD customers receive a hybrid PDF plus a downloadable {number}-factur-x.xml; XRechnung customers receive a plain PDF plus a separate {number}-xrechnung.xml; none customers receive a plain PDF without any XML.
Send by email opens a composer with the default subject and body pre-filled from settings. The PDF is attached automatically. An optional BCC to the issuer's archive mailbox is honoured. After sending, the sent_at timestamp is recorded.
New payment on the invoice page takes a date, amount and optional reference (bank transaction ID, cheque number). Partial payments move the invoice to partially_paid and reduce the open amount displayed on the invoice. A payment that closes the full amount transitions the invoice to paid.
Payments can be deleted to correct mistakes; the state is recalculated from the remaining payments.
An issued invoice that turns out to be wrong is cancelled, not deleted. Cancel creates a reverse cancellation invoice with a new number and links it to the original. Both the original and the cancellation are preserved for the audit trail, and payment tracking reflects the zero balance after cancellation.
The Invoices list has filters for open, overdue, paid, cancelled and date ranges. Overdue is computed from the invoice's due date relative to today. Export to CSV via the standard Redmine list export.
PDF rendering fails with "prawn not found" or similar. The plugin's Gemfile declares prawn and prawn-table. Run bundle install in the Redmine directory after installing the plugin, then restart the Redmine process.
Time entries don't appear when building from time. Verify that (1) the selected customer has the source project assigned under its master record, (2) the date range covers the entries, and (3) the entries are flagged as approved via the at_zeiterfassung plugin if approvals are enforced. Unapproved entries are excluded by design.
Invoice number not assigned. Invoice numbers are assigned at the issued transition, not on draft save. Check the state of the invoice – a draft shows "no number yet" and remains fully editable.
The recipient doesn't accept the e-invoice XML. Check the customer's e-invoice format first. Public-sector recipients in Germany typically require XRechnung (pure XML, Leitweg-ID validated) – not ZUGFeRD. Private recipients generally accept ZUGFeRD (hybrid PDF/A-3 with embedded EN-16931 XML). Switch the customer's format to match the recipient's requirement and re-issue. If a specific profile variant is demanded (Factur-X Basic, EN 16931 Comfort, XRechnung-CII) and the output is rejected, report back with the recipient's exact specification – we will verify profile conformance.
XRechnung customer refuses to save: "Leitweg-ID can't be blank". The Leitweg-ID is mandatory for customers whose e-invoice format is set to XRechnung. Enter the Leitweg-ID as communicated by the public-sector recipient, or change the format to ZUGFeRD or none if XRechnung is not actually required.
Logo placement or colours don't apply. Plugin settings are cached. Restart the Redmine process or clear the Rails cache after changing PDF-layout settings. Logo paths are resolved relative to the Redmine root; symlink or copy the image into a stable location before referencing it.
Email dispatch fails. Redmine's standard mailer settings are used (config/configuration.yml → email_delivery). If Redmine's issue notifications work but invoice emails don't, check for attachment size limits on the outbound SMTP server – invoice PDFs with rich layouts can exceed a few hundred KB.
Support is included for twelve months from the date of purchase.
E-mail: support@atori.de Initial response: within 48 hours on business days.
When reporting issues, please include:
log/production.log, if available