System reports (fixed-slot reports)¶

Most reports are chosen by the user: they open a grid, click Reports and pick one. For a few documents calServer brings the place along itself. That comes in three shapes:

calServer produces the document on its own, at a point where nobody is asked — the loan receipt, which the rental dialog only offers as a checkbox ("Send loan receipt by e-mail").
The document belongs to the product, even though the user triggers it — the price list, offered as a PDF on the price list page. The pick happens among the templates of the "Price list" area, and on a fresh installation that list is empty: the surface exists, nothing says which bundle belongs in it.
A second process reads the same row — the order document. It is picked from the menu like any report, but its invoice variant doubles as the source of the e-invoice (ZUGFeRD / EN 16931). Its activation and field mappings have to hang off a reliable row; "whichever booking report someone once created" is no anchor for a document that matters for tax purposes.

Those are called system reports here. They live in the same report management as every other report and are maintained the same way: upload, versioning, letterhead, report variables, signatures and release rules.

The placeholder¶

Every system report has a fixed row under Administration > Report management > Master reports — the placeholder. It is created during installation (and added to existing systems on the next update) and is there from the start, even before anything has been uploaded.

Two things mark it:

the System report tag next to the name,
the note "No report uploaded yet" together with the name of the matching reference bundle, as long as the row is empty.

The placeholder cannot be deleted. That is deliberate: it is the only place where its feature is configured. Without it the loan receipt mail would go out without its attachment again, and nothing in the application would show why. To stop the report from being produced, deactivate the row instead of deleting it.

Everything else is free: name, folder, format, letterhead, DMS filing, role and group restrictions. A duplicate of a system report is an ordinary report — it does not inherit the system marker and can be deleted again.

While nothing is uploaded

An empty placeholder does not appear in the reports menu of the detail page — a button whose only possible outcome is an error message is no offer. Once a report is in place it sits there like any other and can be printed by hand as well.

Available system reports¶

System report	Grid / folder	When calServer produces it	Reference bundle
Loan receipt	`location` / `locations`	When a rental is booked, as the attachment of the loan receipt mail to the borrower or delivery contact	`LOCATION-JSON-SAMPLE`
Price list	`price_list` / `prices`	On demand under Prices > Price list, per price group and reference date	`PRICE-LIST-JSON-SAMPLE`
Order document	`booking` / `orders`	From the booking: offer, order confirmation, delivery note or invoice — the booking status decides which. Also the source of the e-invoice	`ORDER-JSON-SAMPLE`

Already have an order report?

On systems migrated from V1 the order document usually exists already. If your row is named Auftragsbeleg and sits under booking/orders, the update adopts it — it keeps its bundle, letterhead and variables and only gains the system marker. If it is named anything else (the more common case) it stays an ordinary report and an empty placeholder appears next to it. That is deliberate: many systems carry several order reports, and calServer does not guess which one is "the right one". You can either fill the placeholder or deactivate it — only the e-invoice requires using it.

Setting up a system report¶

Download the reference bundle from calhelp/calServer-reports — which one is in the table above (and on the placeholder row itself). Each is a V2 JSON template in the sense of V2 reports with a JSON data source: no embedded SQL, and therefore independent of the database backend.
Under Administration > Report management > Master reports find the placeholder row (tag System report) and upload the bundle as a ZIP via Upload file.
Done. The data contract is detected from the bundle (location-report for the loan receipt, price-list for the price list, order-document for the order document); a data_contract report variable is not needed.

From then on calServer uses the report: the loan receipt is attached to the mail, the price list appears as a PDF button on the price list page, the order document in the booking's report menu.

With nothing uploaded nothing breaks — the loan receipt mail still goes out, just without an attachment, and the price list page says on PDF that no template is in place yet. A booking never fails over a missing or broken report.

Window letters: loan receipt, despatch note and order document¶

Four reference bundles are window letters to DIN 5008 form B — the loan receipt (LOCATION-JSON-SAMPLE), the despatch note (FREE-DELIVERY-JSON-SAMPLE) and the order document (ORDER-JSON-SAMPLE, including its slim delivery-note variant DELIVERY-JSON-SAMPLE). They share the same geometry: address field 20 mm from the left and 45 mm from the top (85 × 45 mm), return-address line above it inside the field, information block from 125 mm, subject line at 98.4 mm, fold and punch marks at 105 / 148.5 / 210 mm. A DIN-lang envelope to DIN 680 therefore shows exactly the address.

For the order document this holds in every variant: offer, order confirmation, delivery note, invoice and the neutral document (for a status outside the status groups) share the same head; only the blocks below differ. Which address shows through the window follows from the document type: invoices address the invoice address, delivery notes the delivery address, everything else the ordering customer. A second, differing address prints as an info block below the subject line, not in the window — there is room for one.

The four letters fit pre-printed stationery¶

If you configure a stationery template (report setting use template, PDF template or the global letterhead), calServer places it underneath the document — page 1 of the template under document page 1, page 2 under every following page. The four window letters keep a fixed clear area for this and do not run into the sheet's header, footer or margins:

Area	Boundary on the sheet
Type area left / right	20 mm / 195 mm
Top edge, following pages	26.8 mm
Top edge, page 1 (address field)	45 mm
Bottom edge of content	249 mm

If your letterhead stays above 26.8 mm and your footer block below 249 mm, all four documents fit without changes. The 20 mm on the left are deliberately the margin pre-printed stationery normally uses for its header and footer rules, so the document's table and separators line up flush with the sheet.

Stationery usually carries two things itself. Turn them off on the document so they do not appear twice:

Variable	Effect
`show_fold_marks`	`0` turns off fold and punch marks. Applies to all four window letters
`show_supplier_footer`	`0` turns off address, VAT/tax number, commercial register and bank details in the footer. Only the order document prints them

Both default to 1: without stationery the document has to carry the mandatory details itself. A sheet with a taller header or footer needs an adjusted copy of the bundle — the bundle README names the four numbers involved.

The loan receipt as a despatch note¶

The reference bundle LOCATION-JSON-SAMPLE is a window letter to DIN 5008 form B: the delivery address sits in the address field (20 mm from the left, 45 mm from the top, 85 × 45 mm) and therefore shows through the window of a DIN-lang envelope. The small return-address line prints above it, and every row of the equipment list carries a tick box — the sheet doubles as the checklist when packing and at goods-in. It has no signature lines: the sheet travels with the shipment, nobody signs for it at a counter.

For the return-address line to be filled the company_* report variables need content — the same ones the despatch note and the order document use. Easiest with report_type = all, maintained once:

Variable	Content
`company_sender_line`	The finished one-line sender note. Leave empty and the report composes it from the four below
`company_name`, `company_street`, `company_zip`, `company_city`	Sender address
`company_country`	Your country. It also controls the recipient's country line: printed only when the delivery country differs
`show_fold_marks`	`0` turns off fold and punch marks (for pre-printed stationery that already carries them). Applies to all four window letters

Tracking number and despatch note come from the booking itself — but calServer cannot know which location field you keep them in. Two report variables of type location point at them:

Variable	Points at the field holding
`shipping_tracking_field`	the tracking number
`shipping_note_field`	the note about the shipment

The content is the field's api_name as shown under Administration > Field management for table location (the column key works too — calServer translates it). On a factory field set the two still carry their V1 code as api_name; just copy the value out of field management. If your field is already called tracking_number or shipping_note, the report finds it without a variable.

With nothing configured, tracking number and note simply do not appear on the sheet — no empty field is printed.

None of this constrains a layout of your own: the row takes any bundle, and form A (address field from 27 mm) is a single coordinate on the address-field frame in the reference bundle.

E-invoice (ZUGFeRD) on the order document¶

The e-invoice is optional and switched on at this very report. Without the variable nothing about today's behaviour changes.

Switching it on¶

Set the report variable zugferd on the order document (the Variables tab of the report row):

Value	Meaning
`en16931`	The profile that satisfies the German e-invoicing mandate. Recommended.
`basic`	Smaller mandatory set, for simple documents
`extended`	Extended profile

Unset means off. A typo (en16391) also means off — it deliberately does not fall back to a profile nobody chose.

The output only applies when the booking is in the invoice status group and the format is PDF. Offers, order confirmations and delivery notes stay untouched.

The master data that goes with it¶

An e-invoice needs more than the printout. Add these report variables (type booking or all):

Variable	What for
`company_vat_id` or `company_tax_number`	Mandatory under § 14 UStG
`company_country` (or `company_country_code`)	Must resolve to a country — both "Deutschland" and "DE" work
`company_payment_due_days`	Payment term in days; the due date is derived from it
`company_iban`, `company_bic`, `company_bank_name`	Payment means on the invoice
`zugferd_invoice_number_field`	Only if the invoice number is not the order number: `api_name` of the custom field carrying it
`zugferd_delivery_date_field`	`api_name` of the custom field with the delivery/service date (§ 14 UStG)
`zugferd_buyer_reference_field`	`api_name` of the field with the buyer reference; for public authorities the routing ID

Invoice number field: configured means binding

If zugferd_invoice_number_field is configured and the named field on the booking is empty, no e-invoice is produced — the order number is not used silently instead. Otherwise the invoice would carry a number your accounting does not know, and nobody would notice.

Check before going live¶

Before switching on, test against a real invoice:

GET /api/v2/bookings/{booking-id}/reports/{report-id}/einvoice

If the endpoint returns the XML, your master data is sufficient. If it returns 422, the response lists what is missing — tax number, country code, invoice number. The endpoint works without the zugferd variable set; that is exactly what it is for.

The same endpoint serves the plain XML for recipients that do not take a hybrid PDF (public authorities, some large customers).

What you get¶

A PDF/A-3b with an embedded factur-x.xml, on every path the invoice leaves the house by: download, mail attachment, DMS filing and release. The preview stays a plain PDF; an XML attachment is not visible on screen anyway.

If something goes wrong

If embedding fails, the PDF goes out without the attachment and the reason goes to the log. An installation that could no longer print any invoice after switching on would be the worse failure. Whether an invoice works as an e-invoice is what the check endpoint tells you beforehand.

Limits¶

Tax categories are limited to standard rate and 0 %. Small-business exemption (§ 19 UStG), reverse charge and intra-community supply need additional exemption reasons and are not covered yet.
No credit notes or cancellation documents yet.
Units the international catalogue does not know are coded as "piece". The printed text stays unchanged; the check endpoint tells you which units are affected.

What is special about the price list¶

The price list has no record to hang off: its "subject" is the pair of price group and reference date, both set at the top of the Prices > Price list page. Both go into the report as parameters and into the file name (Preisliste_<group>_<date>.pdf).

The letterhead comes from the report management's overlay as with any report, not from the template. The reference bundle deliberately leaves room for it at the top and prints nothing there itself — which is why the same template fits every tenant.

Unlike the loan receipt the price list does not appear in the report picker of the mail templates: it is printed and handed over, not sent automatically.

Preview from the booking form¶

The loan receipt can be inspected before booking: in the booking form, below the "Send loan receipt by e-mail" checkbox, there is Leihschein-Vorschau (loan receipt preview). It renders the report from the values currently in the form — device, customer, delivery contact, loan period, note.

It renders through the same report the mail attaches, with the same letterhead. What the preview shows is what goes out.

Nothing is written in the process: no loan entry, no booked period, and number sequences ([GLOBAL_COUNTER_1] and friends in the field defaults) are only calculated, never consumed. Previewing twice does not skip a number.

For a set booking the preview shows the main device — matching the fact that only one receipt is sent for the whole set.

Requires a V2 JSON template

The preview requires the configured loan receipt to be a V2 bundle with a JSON data source. A classic SQL template reads the loan entry from the database — which does not exist before booking, so it could only ever produce a blank page. In that case the preview says so and renders nothing. If no report is uploaded at all, or the report is deactivated, it names that reason too.

Your own template instead of the reference¶

The reference bundles are starting points, not a requirement. If you have your own layout, upload it the same way — a classic V1 template with embedded SQL works on the same row too (it then runs over JDBC instead of the JSON dataset).

Where else the loan receipt can be wired up¶

On systems migrated from V1 the loan receipt mail may have a report assigned directly: in the location_create mail template via Attachment = master report plus a report selection. That assignment still takes precedence over the placeholder, so an existing configuration is not changed by the update. If it points nowhere (report deleted), calServer falls back to the placeholder.

To get rid of the assignment, reset the template's attachment; the placeholder then applies exclusively.