🤖 AI – KSeF Field Mapping

The AI module allows you to create KSeF field mapping configurations using natural language descriptions. Simply describe what data you want to add to the KSeF invoice, and AI will automatically generate a complete mapping configuration – selecting the appropriate KSeF section, source tables, mapping steps, and filters.

The module uses the Azure OpenAI service and requires prior configuration of the connection in the KSeF settings.

Prerequisites

  1. Azure OpenAI connection configured in the AI section on the KSeF Helper - Settings page.
  2. The KSeF Field Mapping feature active on the Copilot & AI Capabilities page in Business Central.
  3. The N24KSH KSeFMapAdmin permission set assigned to the user.

How to Launch AI

  1. Open the KSeF Helper — KSeF Field Mapping page.
  2. Click the Create Mapping with AI action on the action bar.

An AI dialog box will open with a description field and a preview of results.

Important

This feature uses AI (Azure OpenAI) to generate mapping configurations. Results generated by AI may be inaccurate or incomplete – always review the configuration before saving and enabling the mapping.

Note

The mapping description is limited to 1500 characters. AI only handles queries related to KSeF field mapping configuration – queries unrelated to this topic will be rejected with an error message.

How It Works

Step 1 – Describe the Mapping

In the Describe the mapping field, enter in natural language what data you want to add to the KSeF invoice. You can write in Polish or English. For example:

  • "Add the buyer's phone number as an additional description"
  • "Map the customer's external reference as the order number"
  • "Add the GTIN code from the item reference for invoice lines"
  • "Combine ship-to name, address, city and postal code into one description with a separator"
  • "Clear the CN code in invoice lines"
  • "Add serial numbers as additional description for lines"
  • "Add MPK and PROJECT dimension values to the additional description in lines"
  • "Format the document date as month and year"
  • "Map the contract number from the External Document No. field as ContractNumber"
  • "Map the document date as ContractDate"
  • "Add discount terms from the Payment Terms Description field as Discount – conditions"

You can also select one of the ready-made Prompt Guide suggestions, which will automatically fill in the description field with example text.

Step 2 – Select Document Type

In the Sales / Service field, select whether the mapping should apply to sales or service documents.

Step 3 – Generate Configuration

Click the Generate button. AI will process your description in two stages:

  1. Table discovery – AI analyzes the description and determines which Business Central tables it will need data from.
  2. Mapping generation – AI creates a complete mapping configuration based on the description and available fields in the tables.

Step 4 – Review the Result

After generating the configuration, you will see a preview with the following information:

Field Description
Output Label Field name in KSeF XML – you can edit it before saving
KSeF Section Type Target KSeF section (e.g., AdditionalDescription, OrderNumber, GTIN)
Document Area Sales or Service
Application Level Header or Line. Displayed only for the AdditionalDescription section – for other sections the level is set automatically.
Source Mapping Type How the value is determined: From Tables, Clear Value, or Predefined (Serial Numbers / Dimensions). The Value Source section is hidden for ItemBatchNumber.
Combine Multiple Values Whether values from multiple steps are combined with a separator
Selected Dimensions Displayed only when AI selected the Predefined – Dimensions type. Shows which shortcut dimensions (Dimension 1–8) will be added to the invoice.

Below are displayed:

  • Mapping Lines – a table with mapping steps (source table, relation field, result field, format string)
  • Mapping Path – a readable step-by-step description of how the system will resolve the value

Step 5 – Optional Adjustments

Before saving, you can:

  • Change the output label – customize the field name in KSeF XML.
  • Enable/disable credit memo support – the Enable for Credit Memos field.
  • Configure a record filter – click the Record Filter field to open the standard Business Central filtering view and limit the mapping to selected documents.

Step 6 – Save or Discard

  • Click Save Mapping to save the generated configuration. The mapping will be added to the KSeF field mapping list with the Disabled status – review it and enable it manually.
  • Click Discard to abandon the result without saving.
Note

If the result does not meet expectations, you can modify the description and click Regenerate – AI will prepare a new proposal.

Ready-Made Prompts

The AI dialog contains a set of ready-made prompts to help you get started:

Prompt Description
Buyer phone number Adds the customer's phone number from the Customer table as AdditionalDescription
Order number Maps the "External Document No." field as OrderNumber
Order date Maps the document date as OrderDate
GTIN for lines Adds the GTIN code from the item reference
Product index Adds the index from the item reference
Ship-to recipient Combines delivery data (name, address, city, postal code) with a separator
Clear CN code Clears the CN code value in lines
Serial numbers Adds serial numbers as AdditionalDescription
External document no. Maps the external document number to AdditionalDescription
Clear batch no. Clears the batch number value in lines
Sales comments Adds comments from the Sales Comment Line table
Extended text Maps Description 2 from the invoice line
Buyer email Adds the customer's email address to AdditionalDescription
Document dimensions Adds configured shortcut dimension values as AdditionalDescription

Troubleshooting

Problem Solution
"AI is not configured" message Check that the Endpoint, Deployment, and API Key for Azure OpenAI are filled in the KSeF settings, and that the KSeF Field Mapping feature is active in Copilot & AI Capabilities
Generation error Check the correctness of the endpoint, deployment name, and API key in settings. Make sure the Azure OpenAI resources are available
AI did not find a table or field Try rephrasing the description using more precise table and field names – e.g., "phone number from the Customer table" instead of "customer phone"
Validation failed Review error messages in the diagnostics section. The most common cause is an incorrect field or table name in the AI response – try regenerating
"Request is not related to KSeF field mapping" message AI rejected the query as unrelated to KSeF configuration. Describe what data you want to add to the KSeF invoice
"Message is too long" message Shorten the mapping description to a maximum of 1500 characters