🗂️ KSeF Field Mapping

The KSeF Field Mapping module allows you to define custom mapping rules for fields from Business Central documents to the corresponding XML sections of a KSeF invoice. This gives you flexible control over what data goes into electronic invoices without any code changes.

Key Features

AI — create mappings using natural language descriptions with AI (learn more).
Map fields from headers and lines of posted sales invoices and service invoices.
Support for multiple KSeF sections: AdditionalDescription, OrderDate, OrderNumber, ContractDate, ContractNumber, Discount – conditions, Discount – amount, Index, ItemOrServiceName, GTIN, CN, and ItemBatchNumber.
Retrieve information from related data – e.g., shipping agent name, order number, or item reference.
Explicit clearing of a field value in the KSeF structure – e.g., removing an automatically generated index or CN code.
Predefined values – e.g., automatically adding serial numbers from item tracking as AdditionalDescription, or exporting selected dimensions as AdditionalDescription.
Source data filtering – limit the mapping to documents meeting specific criteria.
Automatic language-based filtering – when a related table contains a "Language Code" field or a field with a relation to the Language table, the system automatically filters records by the language of the source document.
Field value formatting – ability to apply an AL format string to a field value, e.g., display a date as a month name or format a number with a specific precision. Formatting respects the document language – e.g., month names appear in the invoice's language.
Mapping priority – control the order in which mappings are applied: when multiple configurations target the same output label, the mapping with the higher priority that matches a given record (header or line) is used. Lower-priority mappings are skipped for records already matched by a higher-priority one.
Support for both invoices and credit memos.
Automatic validation of settings – the system will alert you if something is configured incorrectly.

Supported Document Areas

Document Area	Application Level
Sales	Header, Line
Service	Header, Line

Supported KSeF Sections

Section	Description
AdditionalDescription	Additional descriptions on the invoice – mapped at the header or line level
OrderDate	Date of the order associated with the invoice
OrderNumber	Number of the order associated with the invoice
ContractDate	Date of the contract associated with the invoice
ContractNumber	Number of the contract associated with the invoice
Discount – conditions	Cash discount (early payment discount) conditions on the invoice
Discount – amount	Cash discount amount or percentage on the invoice
Index	Index (internal code) assigned to invoice lines
ItemOrServiceName	Item or service name assigned to invoice lines
GTIN	GTIN code assigned to invoice lines
CN	CN code (Combined Nomenclature) assigned to invoice lines
ItemBatchNumber	Item batch number – allows clearing the automatically generated value

How It Works

General Workflow

On the KSeF Helper - KSeF Field Mapping page, create a new mapping manually or using AI, selecting the KSeF section, document area, and application level.

Define the mapping steps – specify which field (and optionally from which related table) the value should be retrieved from.
Optionally configure a record filter so that the mapping only applies to selected documents.
Enable the mapping – from this point on, the system will automatically populate data in KSeF invoices.

Multi-Step Mapping

Each mapping can consist of one or more navigation steps:

Step 1 – specifies a field in the source table (e.g., posted sales invoice header).
Step 2 and beyond – navigate to related tables via a relation field. When selecting a table in step 2+, the system by default shows only tables related to the current source table (based on field relations). This behavior can be changed in settings – the Filter related tables in lookup field on the KSeF Helper - Settings page.

Example: to retrieve a shipping agent name from a sales invoice, step 1 points to the Shipping Agent Code field in the invoice header, and step 2 navigates to the Shipping Agent table and reads the Name field.

Combining Multiple Fields into One Value

When you need to compose a value from several fields in the same table, create multiple steps pointing to consecutive fields and enable the Combine multiple values option. The system will combine the results of individual steps, separated by a defined separator.

Example: to pass the full delivery recipient address from a service invoice as AdditionalDescription, each step retrieves a consecutive address field (name, street, city, postal code, country), and the separator " - " joins them into one value.

You can retrieve data from any table related to a document. The example below shows a mapping that, for each sales invoice line, retrieves the item extended text from the Extended Text Line table – step 1 points to the No. field in the invoice line, and step 2 navigates to the extended text table and reads the Text field.

Exporting Dimensions as AdditionalDescription

The predefined configuration of type Dimensions automatically exports selected shortcut dimensions to KSeF invoices. The mapping card shows a Dimensions to Include section where you select the dimensions of interest.

Tips

For the OrderDate, OrderNumber, ContractDate, ContractNumber, Discount – conditions, Discount – amount, Index, ItemOrServiceName, GTIN, CN, and ItemBatchNumber sections, the application level is set automatically and cannot be modified.
For the ItemOrServiceName section, an additional Field Separator field is available, allowing you to combine values from multiple mappings into a single name.
Disabling a mapping (Enabled = false) means it is not taken into account during XML generation.
Priority: mappings are processed in descending priority order. When a mapping matches a record (the filter returns a result), subsequent mappings with a lower priority for the same output label are skipped for that record. Mappings with equal priority are all executed. The default priority value is 0.

A detailed description of fields and configuration pages can be found in the Settings section.

Field Value Formatting

The Format field in mapping steps allows you to change how a field value is displayed. It uses standard AL format strings (FormatString). You can format dates, numbers, and text, and also add fixed text before or after the field value.

Fixed Text in Format

A format string can contain any text outside the tags in angle brackets < >. This allows you to add a label, prefix, or suffix to the field value.

Format	Example result (for date 16.05.2026)
`Terms: <Day,2>.<Month,2>.<Year4>`	Terms: 16.05.2026
`Delivery date: <Day,2> <Month Text> <Year4>`	Delivery date: 16 May 2026

Date Formatting Examples

Format	Example result (for date 16.03.2026)
`<Day,2>.<Month,2>.<Year4>`	16.03.2026
`<Year4>-<Month,2>-<Day,2>`	2026-03-16
`<Month Text> <Year4>`	March 2026
`<Day>. <Month Text> <Year4>`	16. March 2026
`<Year4>/<Month,2>`	2026/03
`<Day,2>-<Month,2>-<Year>`	16-03-26

Note

Month names are displayed in the document's language. If the invoice is set to Polish, the result will be "marzec". For English – "March".

Number Formatting Examples

Format	Example result (for value 1234.5)
`<Precision,2:2><Standard Format,0>`	1,234.50
`<Precision,4:4><Standard Format,0>`	1,234.5000
`<Precision,0:0><Standard Format,0>`	1,235
`<Sign><Integer><Decimals>`	1234.5
`<Sign><Integer Thousand><Decimals,3>`	1,234.500

How to Set Formatting

Open the KSeF field mapping card.
In the Mapping Steps section, find the step whose value you want to format.
In the Format column, enter the appropriate AL format string.
Save the settings – from now on the field value will be formatted according to the specified pattern.