XMLPort in AL

What Is an XML Port in AL?

An XML Port is an AL object that defines how external data is mapped to Business Central tables (import) or how Business Central data is serialized into an external format (export) . It acts as a controlled translation layer between ERP data and external file structures.

An XML Port defines:

• The structure of incoming or outgoing data
• How external fields map to table fields
• The order and hierarchy of data
• Optional validation or transformation logic

An XML Port does not:

• Store data permanently
• Replace business logic
• Act as a UI object

It is a data movement and transformation tool.

Why XML Ports Exist in Business Central

ERP systems rarely operate in isolation. Businesses frequently need to:

• Import data from legacy systems
• Export data to third-party platforms
• Exchange data with partners or government systems
• Perform bulk data uploads or downloads

XML Ports exist to handle these scenarios in a structured, repeatable, and auditable way, without relying on manual data entry or unsafe database operations.

Common Use Cases for XML Ports

XML Ports are commonly used when:

• Large volumes of data must be imported or exported
• The data structure is predefined
• Performance and repeatability matter
• APIs are not available or suitable

Typical examples include:

• Importing opening balances
• Exporting transaction data to accounting systems
• Uploading item or price lists
• Integrating with flat-file–based systems

Basic Structure of an XML Port

An XML Port is defined using the xmlport object and consists of:

• Object properties
• Direction (Import, Export, or Both)
• Schema definition
• Optional triggers

Each element defines how data flows between external files and Business Central tables.

Simple XML Port Import Example

The following example shows an XML Port that imports customer feedback data from a CSV-style file.

xmlport 50150 "Customer Feedback Import"
{
    Direction = Import;
    Format = VariableText;
    FieldSeparator = ',';

    schema
    {
        textelement(Root)
        {
            tableelement(Feedback; "Customer Feedback")
            {
                AutoSave = true;

                fieldelement(CustomerNo; Feedback."Customer No.")
                {
                }
                fieldelement(FeedbackText; Feedback."Feedback Text")
                {
                }
            }
        }
    }
}
    

This XML Port:

• Reads external text data
• Maps fields to table fields
• Automatically inserts records
• Requires no UI interaction

Schema and Elements Explained

The schema defines how the external data is structured. Each element plays a specific role.

• textelement represents a node or row structure
• tableelement represents a table record
• fieldelement maps external fields to table fields

The structure must match the external data exactly.

Direction Property

The Direction property defines how the XML Port operates.

It can be:

• Import (read external data)
• Export (write external data)
• Both (two-way exchange)

This property determines execution behaviour.

Format Property

The Format property defines the data format.

Common formats include:

• Xml
• VariableText (CSV, TXT)
• FixedText

Choosing the correct format is critical for successful data exchange.

Controlling Record Creation

The AutoSave property controls whether records are inserted automatically.

When enabled:

• Records are inserted automatically
• Table validations are still enforced
• Errors stop processing safely

Using Triggers in XML Ports

XML Ports support triggers such as OnBeforeInsertRecord and OnAfterAssignField.

trigger OnBeforeInsertRecord()
begin
    // Validation or transformation logic
end;
    

Triggers should be used only for:

• Data validation
• Format transformation
• Conditional handling

Core business logic should remain in tables or codeunits.

Export XML Port Example

XML Ports can also export data.

xmlport 50151 "Customer Feedback Export"
{
    Direction = Export;
    Format = VariableText;
    FieldSeparator = ';';

    schema
    {
        textelement(Root)
        {
            tableelement(Feedback; "Customer Feedback")
            {
                fieldelement(CustomerNo; Feedback."Customer No.") { }
                fieldelement(FeedbackText; Feedback."Feedback Text") { }
            }
        }
    }
}
    

This XML Port:

• Reads data from Business Central
• Writes structured output
• Can be scheduled or executed on demand

XML Ports and Upgrade Safety

XML Ports are:

• Isolated from base tables
• Fully extension-based
• Safe across upgrades

Because they do not modify standard objects, they remain stable even when the platform evolves.

Common Beginner Mistakes With XML Ports

Developers often:

• Hardcode file paths
• Ignore validation errors
• Overuse XML Ports when APIs are better
• Put business logic in XML Port triggers

XML Ports should focus on data structure and mapping, not business processing.

Summary

XML Ports in AL provide a structured and reliable way to exchange data between Business Central and external systems. They are best suited for file-based integrations, bulk data movement, and predefined data structures.

A well-designed XML Port:

• Maps data clearly
• Uses properties before code
• Keeps logic minimal
• Preserves data integrity

Understanding XML Ports completes the file-based integration layer of AL development.