7.1 XMLport Architecture, Formats & Properties

7.1 XMLport Formats, Properties & Direction

In Microsoft Dynamics 365 Business Central, XMLports are dedicated AL application objects used to import and export structured business data between Business Central database tables and external systems or flat files. While modern integration architectures frequently leverage REST APIs and OData web services, XMLports remain the core engine for high-throughput batch file processing, legacy electronic data interchange (EDI), automated banking and payroll interfaces, and electronic document exchange (such as PEPPOL or custom XML invoices).

For developers preparing for the MB-820 certification exam, mastering XMLport object architecture, serialization formats, delimiter mechanics, character encoding standards, and runtime validation properties is essential under Domain 3 (Develop by using AL objects).

1. XMLport Object Architecture in AL

An XMLport is declared using the xmlport keyword followed by a unique object ID and name. The structure consists of top-level object properties, an optional requestpage block, a mandatory schema block defining the hierarchical or tabular data layout, and AL triggers.

xmlport 50120 "Export Customer CSV"
{
    Caption = 'Export Customer CSV';
    Format = VariableText;
    Direction = Export;
    FieldSeparator = ',';
    FieldDelimiter = '"';
    RecordSeparator = '<NewLine>';
    TableSeparator = '<<NewLine><NewLine>>';
    TextEncoding = UTF8;
    UseRequestPage = true;
    DefaultFieldsValidation = true;

    schema
    {
        textelement(RootNode)
        {
            tableelement(Customer; Customer)
            {
                RequestFilterFields = "No.", "Customer Posting Group";
                SourceTableView = sorting("No.") where(Blocked = const(" "));

                fieldelement(CustomerNo; Customer."No.") { }
                fieldelement(Name; Customer.Name) { }
                fieldelement(BalanceLCY; Customer."Balance (LCY)") { }
                fieldelement(City; Customer.City) { }
            }
        }
    }

    requestpage
    {
        layout
        {
            area(content)
            {
                group(Options)
                {
                    Caption = 'Options';
                    // Custom user filters or execution parameters
                }
            }
        }
    }
}

2. Core XMLport Formats: XML, VariableText & FixedText

The Format property dictates how the XMLport serialization engine processes raw bytes into structured schema nodes.

Format = Xml (Default)

• Designed for hierarchical data structures representing structured XML documents.
• Supports nested elements (textelement, tableelement, fieldelement) and element attributes (textattribute, fieldattribute).
• Honors XML namespaces defined in the Namespaces property.
• Ideal for standardized data interchange schemas such as PEPPOL BIS 3.0 electronic invoices, ISO 20022 financial messages, and SOAP-style payloads.

Format = VariableText

• Designed for delimited flat files such as Comma-Separated Values (CSV), Tab-Separated Values (TSV), and pipe-delimited files.
• Fields within each record are separated by the FieldSeparator string and optionally wrapped in quotes by the FieldDelimiter string.
• Delimited records do not maintain parent-child tag hierarchies; each record maps directly to a tabular row.
• Widely used for importing bank transaction statements, external e-commerce sales feeds, and general ledger journal batches.

Format = FixedText

• Designed for positional, fixed-column-width text files (e.g., legacy mainframe feeds, NACHA ACH banking files, and standardized payroll flat files).
• Delimiters between fields are not used; instead, the parser determines the start and length of each field based on the Width property declared on each schema element.
• Records must conform strictly to predefined column widths. If an incoming value exceeds or is shorter than the configured width, padding or truncation occurs according to the element data type.

3. Delimiter & Separator Properties

When Format is set to VariableText or FixedText, delimiter properties define how the runtime identifies record and field boundaries.

// Example: Pipe-Delimited Flat File Export without Quoting
xmlport 50121 "Export Pipe Delimited Items"
{
    Format = VariableText;
    Direction = Export;
    FieldSeparator = '|';
    FieldDelimiter = '<None>';
    RecordSeparator = '<NewLine>';
    TextEncoding = UTF8;

    schema
    {
        textelement(Root)
        {
            tableelement(Item; Item)
            {
                fieldelement(ItemNo; Item."No.") { }
                fieldelement(Description; Item.Description) { }
                fieldelement(UnitPrice; Item."Unit Price") { }
                fieldelement(Inventory; Item.Inventory) { }
            }
        }
    }
}

4. Direction, Encoding & Validation Properties

Direction

The Direction property controls the permissible execution mode of the XMLport:

• Both (Default): The XMLport can be invoked to import external data into Business Central or export database records to an output stream.
• Import: The XMLport can only be executed in import mode (e.g., Xmlport.Import(...) or interactive import). Attempting to call Xmlport.Export(...) on an Import-only XMLport throws a runtime error.
• Export: The XMLport is strictly constrained to exporting data. Attempting to call Xmlport.Import(...) throws a runtime error.

TextEncoding

When reading or writing file streams, character encoding determines how binary bytes are translated into characters. The TextEncoding property supports four options:

1. UTF8 (Default): Standard 8-bit variable-width Unicode encoding. Preferred for modern cloud interfaces, XML documents, and international CSV files.
2. UTF16: 16-bit Unicode encoding, commonly used in Windows-native architectures and specialized XML schemas requiring full UCS-2/UTF-16 support.
3. WINDOWS: Uses the Windows ANSI code page corresponding to the active server locale (typically Windows-1252 for Western European/US). Essential when exchanging files with legacy Windows desktop software.
4. MS-DOS: Uses the legacy OEM/DOS code page (such as CP437 or CP850). Required when interfacing with legacy POS hardware, barcode scanners, or older banking mainframe protocols.

DefaultFieldsValidation

• When DefaultFieldsValidation = true (default), assigning values to table fields during an import automatically triggers the field's OnValidate trigger in AL. This guarantees that business rules (such as checking blocked status, validating relationships, and calculating dependent fields) are enforced.
• When DefaultFieldsValidation = false, values are copied directly into the record buffer without executing field-level validation triggers. This mode is used for high-speed bulk data migration where source data is pre-validated, or where validation rules would cause circular dependency errors during initial import.
• Developers can override this default on a per-field basis using the FieldValidate property on individual fieldelement nodes.

UseRequestPage

• When UseRequestPage = true (default), running the XMLport interactively displays a modal request page where users can define sorting keys, apply table filters, and toggle execution options.
• When UseRequestPage = false, the XMLport runs headlessly without rendering a user interface. This is critical for automated background processes, Job Queue entries, and API integrations where modal UI calls cause runtime exceptions.

5. Architectural Comparison of XMLport Formats

Exam Watchout — Delimiters vs. Namespaces: Setting FieldSeparator or FieldDelimiter on an XMLport where Format = Xml has no effect. Conversely, defining XML attributes or namespaces on an XMLport where Format = VariableText or FixedText results in a compilation error or ignored runtime metadata.