🗂️ KSeF Field Mapping – Settings
KSeF Field Mapping
The page displays all defined field mappings. For each mapping the following are visible:
| Field | Description |
|---|---|
| Entry No. | Unique mapping identifier |
| Priority | Mapping priority (default 0). Higher value = higher priority. Mappings are processed in descending order. When a mapping matches a record (document header or line), all subsequent mappings with a lower priority for the same output label are skipped for that record. Mappings with equal priority are all executed. |
| KSeF Section | Target section in the XML file (AdditionalDescription, OrderDate, OrderNumber, ContractDate, ContractNumber, Discount – conditions, Discount – amount, Index, ItemOrServiceName, GTIN, CN, ItemBatchNumber) |
| Output Label | Field name in the XML file |
| Document Area | Sales or Service |
| Application Level | Header or Line |
| Enabled | Whether the mapping is active |
| Enable for Credit Memos | Whether the mapping applies to credit memos |
| Error Count | Number of validation errors (0 = configuration correct) |
Lines with validation errors are automatically highlighted in red.
List Actions
| Action | Description |
|---|---|
| Prepare with AI | Opens the AI dialog where you can describe the mapping in natural language – AI will generate a complete configuration. See AI – KSeF Field Mapping. |
| Load Examples | Opens the example configuration selection page. The user selects which examples to load – the selected mappings are added to the existing settings (without removing existing ones). |
| Clear All Settings | Deletes all existing mappings. The action requires confirmation. |
| Enable Selected | Enables all selected mappings at once – no need to open each card separately. |
| Export Mappings | Exports all KSeF field mappings to a JSON file for transfer to another environment. |
| Import Mappings | Imports mappings from a previously exported JSON file. Imported mappings are added to existing ones. |
| Synchronize Mappings | Copies field mappings to selected companies in the same environment. |
KSeF Field Mapping Card
Scope Section
| Field | Description |
|---|---|
| KSeF Section | Target section type in XML |
| Output Label | Field label in XML |
| Priority | Mapping priority (default 0). Higher value = higher priority. When a mapping matches a record, subsequent mappings with a lower priority for the same label are skipped for that record. Mappings with equal priority are all executed. |
| Enabled | Activate the mapping |
| Document Area | Sales or Service |
| Application Level | Header or Line. Visible only for sections where a choice is possible (AdditionalDescription). For other KSeF sections the level is set automatically. |
| Enable for Credit Memos | Extend the mapping to credit memos |
Value Source Section
This section is visible for all KSeF types except ItemBatchNumber.
| Field | Description |
|---|---|
| Mapping Source Type | How the field value is determined: From Tables (value retrieved from BC tables), Clear Value (explicit clearing of the KSeF field), or Predefined (predefined value). Default: From Tables. |
| Predefined Value Type | Type of predefined value – visible only when Mapping Source Type = Predefined. Available options: Serial Numbers (automatically add serial numbers from shipment tracking), Dimensions (automatically add selected dimensions as AdditionalDescription). |
| Field Separator | Character or string used to combine values from multiple mappings (visible only for the ItemOrServiceName section) |
| Combine Multiple Values | Whether values from multiple document lines should be combined into one |
Record Filtering Section
An optional filter that limits the mapping to documents meeting specific conditions. Clicking the filter field opens the standard Business Central filtering view.
Dimensions to Include Section
This section is visible only when Mapping Source Type = Predefined and Predefined Value Type = Dimensions. It contains up to 8 fields corresponding to shortcut dimensions configured in General Ledger Setup. Only dimensions that have a shortcut dimension code assigned are visible. Field names are dynamic and correspond to dimension names from the general ledger settings.
Select the desired dimensions so that their codes and values are added as AdditionalDescription entries on the KSeF invoice.
Mapping Steps Section
An embedded sub-page with the list of mapping steps (see below). Visible only when Mapping Source Type = From Tables.
Configuration Errors Section
This section is visible only when configuration errors have been detected. It displays detailed error messages that must be corrected before enabling the mapping.
The Validate action runs a full validation and refreshes the status of displayed errors.
KSeF Field Mapping Steps
| Field | Description |
|---|---|
| Step No. | Step order (1, 2, 3...) |
| Table | Name of the source table (automatically determined for step 1 based on document area and application level) |
| Field No. | Field number in the table |
| Field Name | Field name (filled in automatically) |
| Field Caption | Field caption |
| Relation Field No. | Number of the field linking to the next table (for intermediate steps) |
| Relation Field Name | Relation field name |
| Format | Optional AL format string applied to the field value. Allows formatting dates, numbers, and other values. Examples: <Month Text> <Year4> (month name and year), <Year4>-<Month,2>-<Day,2> (ISO date format), <Precision,2:2><Standard Format,0> (number with 2 decimal places). Formatting respects the document language – e.g., month names appear in the invoice's language. |
Actions
- Add Next Step – adds the next mapping step, enabling navigation to a related table
- Insert Step Here – inserts a new step before the currently selected row
- Delete Selected Rows – deletes the selected mapping steps and automatically renumbers the remaining ones
- Move Up – moves the selected step one position up in the sequence
- Move Down – moves the selected step one position down in the sequence
- Validate Configuration – checks the validity of all steps
Below the step list, a readable description of the configuration is displayed in text form, e.g.:
"Retrieve field [Name] from table [Sales Invoice Header] (step 1), then navigate to table [Shipping Agent] via field [Shipping Agent Code] and retrieve field [Name] (step 2)."
Configuration Examples
Adding an Additional Description from the Invoice Header
- Create a new mapping with the AdditionalDescription section.
- Set the output label, e.g., "Notes".
- Select the Sales area, Header level.
- In step 1, point to the appropriate field from the posted sales invoice header table.
- Enable the mapping.
Adding a Product Index to Lines
- Create a new mapping with the Index section.
- Select the Sales area, Line level.
- In step 1, point to the field from which the index code should be retrieved (e.g., a field from the invoice line pointing to an external catalog number).
- Optionally add step 2 to navigate to a related table.
- Enable the mapping.
Overriding the Item or Service Name in Lines
- Create a new mapping with the ItemOrServiceName section.
- Select the Sales area, Line level.
- In step 1, point to the field from which the name should be retrieved (e.g., description from the invoice line or name from a related item table).
- Optionally add additional mapping steps to retrieve values from multiple fields – the system will automatically combine them into one name, separated by a configured separator.
- Set the Field Separator (e.g., a space or dash) to specify the character connecting individual values.
- Enable the mapping.
Note
If multiple mapping steps are defined for the ItemOrServiceName section, their results are combined into a single name value, separated by the configured separator. This allows you to, for example, compose a name from the line description and product code in the form "Description - Code".
Clearing a Field Value in KSeF
The Clear Value option in the Mapping Source Type field allows you to clear the value generated by the system for a given KSeF section. This is useful when the standard KSeF mechanism automatically fills in e.g. the index or CN code, and the user wants those fields to remain empty in the KSeF structure.
- Create a new mapping with the selected section (e.g., Index or ItemOrServiceName).
- Set Mapping Source Type to Clear Value.
- Select the appropriate document area and application level.
- Enable the mapping.
Note
The Clear Value option is not available for the AdditionalDescription section – this section is used for adding additional descriptions and clearing it is not applicable.
Adding Serial Numbers as AdditionalDescription (Predefined)
The Predefined option in the Mapping Source Type field allows you to automatically generate values based on built-in rules. The Serial Numbers option is currently available, which retrieves serial numbers from item tracking lines for each document line and adds them as AdditionalDescription entries.
- Create a new mapping with the AdditionalDescription section.
- Set Mapping Source Type to Predefined.
- In the Predefined Value Type field, select Serial Numbers.
- Set the output label, e.g., "Serial Number".
- Select the Sales area, Line level.
- Enable the mapping.
Note
For each invoice line with assigned serial numbers, the system will create a separate AdditionalDescription entry with the serial number. Serial numbers are retrieved from the standard Business Central item tracking mechanism.
Adding Dimensions as AdditionalDescription (Predefined)
The Dimensions option in the Predefined Value Type field allows you to automatically export shortcut dimension values assigned to a document as AdditionalDescription entries in the KSeF invoice. Each selected dimension generates a separate entry, where the label is the dimension name and the value is the dimension value code.
- Create a new mapping with the AdditionalDescription section.
- Set Mapping Source Type to Predefined.
- In the Predefined Value Type field, select Dimensions.
- Set the output label, e.g., "Dimensions".
- Select the Sales area and the appropriate application level (Header or Line).
- In the Dimensions to Include section, select the dimensions to be exported.
- Enable the mapping.
Note
Only shortcut dimensions configured in General Ledger Setup are visible. If the company uses e.g. 4 shortcut dimensions, only 4 fields will appear on the mapping card. Field names correspond to dimension names from the settings. The dimension name is used as the AdditionalDescription entry label, and the dimension value code assigned to the document is used as the value.