If you’ve worked with integrations in Business Central, chances are you’ve had to deal with XML at some point. In a previous post I covered how to create an XML file in AL. This time we’ll go the other direction—reading and parsing an XML document using the built-in XML data types in AL.

We’ll work through a realistic example: reading a multi-level XML file that contains a sales order header with one or more sales lines.

You can find the full code for the example on GitHub.

The XML Data Types You Need to Know

AL ships with a set of XML data types purpose-built for reading and writing XML. For parsing an XML document you’ll primarily use these:

• XmlDocument – represents the entire XML document. This is your entry point.
• XmlElement – represents a single element (tag) in the document.
• XmlNode – a more general type that can be an element, attribute, text, etc. You’ll often cast nodes to elements.
• XmlNodeList – a collection of child nodes returned by methods like GetChildNodes() or GetChildElements().
• XmlAttribute – represents an attribute on an element (e.g., currency="USD").
• XmlDeclaration – represents the <?xml ...?> declaration at the top of the document.
• XmlNamespaceManager – manages namespace lookups when your XML uses namespaces.

For most parsing tasks, XmlDocument, XmlElement, XmlNode, and XmlNodeList are all you need.

The Sample XML

Here’s the XML we’ll parse. It represents a sales order with a header and two lines:

<?xml version="1.0" encoding="utf-8"?>
<SalesOrder>
  <Header>
    <OrderNo>SO-1001</OrderNo>
    <CustomerNo>C-10000</CustomerNo>
    <OrderDate>2026-03-01</OrderDate>
    <Currency>USD</Currency>
  </Header>
  <Lines>
    <Line>
      <LineNo>10000</LineNo>
      <ItemNo>ITEM-1000</ItemNo>
      <Description>Widget A</Description>
      <Quantity>5</Quantity>
      <UnitPrice>12.50</UnitPrice>
    </Line>
    <Line>
      <LineNo>20000</LineNo>
      <ItemNo>ITEM-2000</ItemNo>
      <Description>Widget B</Description>
      <Quantity>3</Quantity>
      <UnitPrice>25.00</UnitPrice>
    </Line>
  </Lines>
</SalesOrder>

This is a typical multi-level structure: a root <SalesOrder> element wrapping a single <Header> and a <Lines> collection containing multiple <Line> children.

Loading the XML Document

The first step is getting the XML text into an XmlDocument. You can load it from a text variable, an InStream, or from a BLOB field—whatever your source happens to be. Here’s the most common pattern using XmlDocument.ReadFrom():

procedure ReadSalesOrderXml(XmlText: Text)
var
    XmlDoc: XmlDocument;
begin
    if not XmlDocument.ReadFrom(XmlText, XmlDoc) then
        Error('Failed to parse XML document.');

    ProcessSalesOrder(XmlDoc);
end;

ReadFrom() returns true if the XML was well-formed and parsed successfully, which makes it easy to handle malformed input up front. You can also load from an InStream:

procedure ReadSalesOrderFromStream(XmlStream: InStream)
var
    XmlDoc: XmlDocument;
begin
    XmlDocument.ReadFrom(XmlStream, XmlDoc);
    ProcessSalesOrder(XmlDoc);
end;

Navigating to the Root Element

Once you have an XmlDocument, grab the root element with GetRoot():

procedure ProcessSalesOrder(XmlDoc: XmlDocument)
var
    RootElement: XmlElement;
begin
    XmlDoc.GetRoot(RootElement);

    // RootElement is now <SalesOrder>
    ReadHeader(RootElement);
    ReadLines(RootElement);
end;

From the root element you can drill into child elements by name using SelectSingleNode() or by iterating with GetChildElements().

Reading the Header

To pull values from the <Header> element, use SelectSingleNode() to locate the header, then grab each child element’s inner text:

procedure ReadHeader(RootElement: XmlElement)
var
    HeaderNode: XmlNode;
    HeaderElement: XmlElement;
    OrderNo: Code[20];
    CustomerNo: Code[20];
    OrderDate: Date;
    Currency: Code[10];
begin
    if not RootElement.SelectSingleNode('Header', HeaderNode) then
        Error('Header element not found.');

    HeaderElement := HeaderNode.AsXmlElement();

    OrderNo := CopyStr(GetElementValue(HeaderElement, 'OrderNo'), 1, MaxStrLen(OrderNo));
    CustomerNo := CopyStr(GetElementValue(HeaderElement, 'CustomerNo'), 1, MaxStrLen(CustomerNo));
    Evaluate(OrderDate, GetElementValue(HeaderElement, 'OrderDate'));
    Currency := CopyStr(GetElementValue(HeaderElement, 'Currency'), 1, MaxStrLen(Currency));

    Message('Order: %1, Customer: %2, Date: %3, Currency: %4',
        OrderNo, CustomerNo, OrderDate, Currency);
end;

A SelectSingleNode() call returns true and populates the node variable if a match is found, so you can check whether the node exists before using it. Once you have the node, convert it to an XmlElement with AsXmlElement() so you can work with element-specific methods.

A Handy Helper: GetElementValue

You’ll find yourself reading inner text from child elements constantly, so a small helper keeps things clean:

procedure GetElementValue(ParentElement: XmlElement; ChildName: Text) ReturnValue: Text
var
    ChildNode: XmlNode;
begin
    if ParentElement.SelectSingleNode(ChildName, ChildNode) then
        ReturnValue := ChildNode.AsXmlElement().InnerText();
end;

This returns the text content of a named child element, or an empty string if the element isn’t found. Adjust this to throw an error or return a default depending on whether the element is required in your scenario.

Reading the Lines

Here’s where the multi-level structure comes in. The <Lines> element contains multiple <Line> children, so we need to iterate:

procedure ReadLines(RootElement: XmlElement)
var
    LinesNode: XmlNode;
    LinesElement: XmlElement;
    LineNodeList: XmlNodeList;
    LineNode: XmlNode;
    LineElement: XmlElement;
    LineNo: Integer;
    ItemNo: Code[20];
    Description: Text[100];
    Quantity: Decimal;
    UnitPrice: Decimal;
begin
    if not RootElement.SelectSingleNode('Lines', LinesNode) then
        Error('Lines element not found.');

    LinesElement := LinesNode.AsXmlElement();
    LineNodeList := LinesElement.GetChildElements('Line');

    foreach LineNode in LineNodeList do begin
        LineElement := LineNode.AsXmlElement();

        Evaluate(LineNo, GetElementValue(LineElement, 'LineNo'));
        ItemNo := CopyStr(GetElementValue(LineElement, 'ItemNo'), 1, MaxStrLen(ItemNo));
        Description := CopyStr(GetElementValue(LineElement, 'Description'), 1, MaxStrLen(Description));
        Evaluate(Quantity, GetElementValue(LineElement, 'Quantity'));
        Evaluate(UnitPrice, GetElementValue(LineElement, 'UnitPrice'));

        Message('Line %1: Item %2 (%3) - Qty %4 @ %5',
            LineNo, ItemNo, Description, Quantity, UnitPrice);
    end;
end;

Key points:

• GetChildElements('Line') returns an XmlNodeList containing only the <Line> child elements.
• The foreach loop walks each <Line> node.
• We convert each node to an XmlElement and then use the same GetElementValue helper to pull values.

Dynamically Reading Child Elements

If you don’t know the child element names ahead of time, you can iterate all children of a node:

local procedure ReadHeader(RootElement: XmlElement; var OutputLines: List of [Text])
    var
        HeaderNode: XmlNode;
        HeaderElement: XmlElement;
        ChildNodes: XmlNodeList;
        ChildNode: XmlNode;
        ChildElement: XmlElement;
    begin
        if not RootElement.SelectSingleNode('Header', HeaderNode) then
            Error('Header element not found.');

        HeaderElement := HeaderNode.AsXmlElement();
        ChildNodes := HeaderElement.GetChildElements();

        OutputLines.Add('--- Header ---');
        foreach ChildNode in ChildNodes do begin
            ChildElement := ChildNode.AsXmlElement();
            OutputLines.Add(ChildElement.Name() + ': ' + ChildElement.InnerText());
        end;
    end;

    local procedure ReadLines(RootElement: XmlElement; var OutputLines: List of [Text])
    var
        LinesNode: XmlNode;
        LinesElement: XmlElement;
        LineNodeList: XmlNodeList;
        LineNode: XmlNode;
        LineElement: XmlElement;
        ChildNodes: XmlNodeList;
        ChildNode: XmlNode;
        ChildElement: XmlElement;
    begin
        if not RootElement.SelectSingleNode('Lines', LinesNode) then
            Error('Lines element not found.');

        LinesElement := LinesNode.AsXmlElement();
        LineNodeList := LinesElement.GetChildElements('Line');

        foreach LineNode in LineNodeList do begin
            LineElement := LineNode.AsXmlElement();
            ChildNodes := LineElement.GetChildElements();

            OutputLines.Add('--- Line ---');
            foreach ChildNode in ChildNodes do begin
                ChildElement := ChildNode.AsXmlElement();
                OutputLines.Add(ChildElement.Name() + ': ' + ChildElement.InnerText());
            end;
        end;
    end;

Putting It All Together

Here’s the full Codeunit so you can see how all the pieces connect:

Codeunit 50100 "Read Sales Order XML"
{
    procedure ReadSalesOrderXml(XmlText: Text)
    var
        XmlDoc: XmlDocument;
    begin
        if not XmlDocument.ReadFrom(XmlText, XmlDoc) then
            Error('Failed to parse XML document.');

        ProcessSalesOrder(XmlDoc);
    end;

    local procedure ProcessSalesOrder(XmlDoc: XmlDocument)
    var
        RootElement: XmlElement;
    begin
        XmlDoc.GetRoot(RootElement);
        ReadHeader(RootElement);
        ReadLines(RootElement);
    end;

    local procedure ReadHeader(RootElement: XmlElement)
    var
        HeaderNode: XmlNode;
        HeaderElement: XmlElement;
        OrderNo: Code[20];
        CustomerNo: Code[20];
        OrderDate: Date;
        Currency: Code[10];
    begin
        if not RootElement.SelectSingleNode('Header', HeaderNode) then
            Error('Header element not found.');

        HeaderElement := HeaderNode.AsXmlElement();

        OrderNo := CopyStr(GetElementValue(HeaderElement, 'OrderNo'), 1, MaxStrLen(OrderNo));
        CustomerNo := CopyStr(GetElementValue(HeaderElement, 'CustomerNo'), 1, MaxStrLen(CustomerNo));
        Evaluate(OrderDate, GetElementValue(HeaderElement, 'OrderDate'));
        Currency := CopyStr(GetElementValue(HeaderElement, 'Currency'), 1, MaxStrLen(Currency));

        Message('Order: %1, Customer: %2, Date: %3, Currency: %4',
            OrderNo, CustomerNo, OrderDate, Currency);
    end;

    local procedure ReadLines(RootElement: XmlElement)
    var
        LinesNode: XmlNode;
        LinesElement: XmlElement;
        LineNodeList: XmlNodeList;
        LineNode: XmlNode;
        LineElement: XmlElement;
        LineNo: Integer;
        ItemNo: Code[20];
        Description: Text[100];
        Quantity: Decimal;
        UnitPrice: Decimal;
    begin
        if not RootElement.SelectSingleNode('Lines', LinesNode) then
            Error('Lines element not found.');

        LinesElement := LinesNode.AsXmlElement();
        LineNodeList := LinesElement.GetChildElements('Line');

        foreach LineNode in LineNodeList do begin
            LineElement := LineNode.AsXmlElement();

            Evaluate(LineNo, GetElementValue(LineElement, 'LineNo'));
            ItemNo := CopyStr(GetElementValue(LineElement, 'ItemNo'), 1, MaxStrLen(ItemNo));
            Description := CopyStr(GetElementValue(LineElement, 'Description'), 1, MaxStrLen(Description));
            Evaluate(Quantity, GetElementValue(LineElement, 'Quantity'));
            Evaluate(UnitPrice, GetElementValue(LineElement, 'UnitPrice'));

            Message('Line %1: Item %2 (%3) - Qty %4 @ %5',
                LineNo, ItemNo, Description, Quantity, UnitPrice);
        end;
    end;

    local procedure GetElementValue(ParentElement: XmlElement; ChildName: Text) ReturnValue: Text
    var
        ChildNode: XmlNode;
    begin
        if ParentElement.SelectSingleNode(ChildName, ChildNode) then
            ReturnValue := ChildNode.AsXmlElement().InnerText();
    end;
}

Working with Attributes

Sometimes values live in attributes rather than child elements. For example, if <Header> had a currency attribute instead of a child element:

<Header currency="USD">

You’d read it using the Attributes() collection:

var
    AttrCollection: XmlAttributeCollection;
    CurrencyAttr: XmlAttribute;
    CurrencyValue: Text;
    i: Integer;
begin
    AttrCollection := HeaderElement.Attributes();
    for i := 1 to AttrCollection.Count do
        if AttrCollection.Get(i, CurrencyAttr) then
            if CurrencyAttr.Name() = 'currency' then begin
                CurrencyValue := CurrencyAttr.Value();
                break;
            end;
end;

Alternatively, you can use an XPath expression with SelectSingleNode() to target an attribute directly, which is often cleaner:

var
    AttrNode: XmlNode;
    CurrencyValue: Text;
begin
    if HeaderElement.SelectSingleNode('@currency', AttrNode) then
        CurrencyValue := AttrNode.AsXmlAttribute().Value();
end;

Handling Namespaces

If your XML uses namespaces (common with SOAP responses, e-invoicing standards like PEPPOL/UBL, and bank file formats like ISO 20022), you’ll need an XmlNamespaceManager. Here’s a quick example:

var
    XmlDoc: XmlDocument;
    NsMgr: XmlNamespaceManager;
    RootElement: XmlElement;
    ResultNode: XmlNode;
begin
    XmlDocument.ReadFrom(XmlText, XmlDoc);
    NsMgr.NameTable(XmlDoc.NameTable());
    NsMgr.AddNamespace('so', 'http://example.com/salesorder');

    XmlDoc.GetRoot(RootElement);
    RootElement.SelectSingleNode('so:Header', NsMgr, ResultNode);
end;

The namespace prefix you add to the manager ('so') doesn’t have to match the prefix in the XML—it just needs to map to the same URI.

Gotchas and Tips

• Always check the return value of ReadFrom(). If the XML is malformed you’ll get false rather than a runtime error, which gives you a chance to log the problem and handle it gracefully.
• SelectSingleNode() vs GetChildElements() vs SelectNodes(): Use SelectSingleNode() when you expect exactly one match by name. Use GetChildElements() when you expect zero or more children to iterate. Use SelectNodes() when you need XPath expressions that match multiple nodes at varying depths—it returns an XmlNodeList just like GetChildElements().
• XmlReadOptions: ReadFrom() has overloads that accept an XmlReadOptions parameter. If you need to preserve whitespace in the document (for example, when processing pre-formatted text content), set XmlReadOptions.PreserveWhitespace to true before calling ReadFrom().
• Type conversions: InnerText() always returns Text. Use Evaluate() to convert to Integer, Decimal, Date, etc. Watch out for locale-sensitive formats with dates and decimals—consider using XmlConvert or explicit format strings when parsing dates.
• Large documents: For very large XML files, consider processing nodes as you go rather than loading everything into variables. AL’s XML types handle the DOM in memory, so extremely large files can affect performance.
• Missing elements: Decide early whether a missing element is an error or just an empty value. The GetElementValue helper above silently returns empty text—adjust this for your requirements.

Wrapping Up

Reading XML in AL follows a straightforward pattern: load the document with XmlDocument.ReadFrom(), grab the root with GetRoot(), and then navigate the tree using SelectSingleNode() and GetChildElements(). A small helper like GetElementValue keeps your code clean when you’re pulling lots of values. For multi-level structures like our sales header/lines example, it’s just a matter of nesting the same pattern—navigate to the parent, iterate the children.

If you haven’t already, check out my earlier post on creating an XML file in AL to see the other side of the coin.

Learn more:

• XmlDocument Data Type
• XmlElement Data Type
• XmlNode Data Type
• XmlNodeList Data Type
• XmlNamespaceManager Data Type

Note: The code and information discussed in this article are for informational and demonstration purposes only. Always test in a sandbox first. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2 online.

If you’ve spent any time in AL development, you’ve probably reinvented a wheel or two. Written a quick parser for a date string, wrestled with URL encoding for an API call, or built a little helper to compare dates safely. The "Type Helper" Codeunit (ID 10, namespace System.Reflection) exists specifically to handle this kind of utility work—and it’s surprisingly comprehensive.

This post walks through useful procedures grouped by category, with practical AL examples for each.

You can find the full code for the example on GitHub.

What Is the Type Helper Codeunit?

"Type Helper" is a base application Codeunit that provides a broad set of utility methods covering:

• String and character checks
• Date, time, and timezone formatting and conversion
• URL/HTML encoding
• Record and field reflection
• Option field helpers
• Stream reading
• Amount/currency format strings

It’s not flashy, but it saves real time. Before writing your own utility procedure, check here first.

String Utilities

IsNumeric

procedure IsNumeric(Text: Text): Boolean

Returns true if a text value can be parsed as a Decimal.

var
    TypeHelper: Codeunit "Type Helper";
    Result1, Result2: Boolean;
    Value1, Value2: Text;
begin
    Value1 := '42.5';
    Value2 := 'hello';

    Result1 := TypeHelper.IsNumeric(Value1);   // true
    Result2 := TypeHelper.IsNumeric(Value2);  // false
    Message('IsNumeric(''' + Value1 + '''): %1\IsNumeric(''' + Value2 + '''): %2', Result1, Result2);
end;

Useful for validating user input or imported data before calling Evaluate.

IsPhoneNumber

procedure IsPhoneNumber(Input: Text): Boolean

Validates that a string contains only digits, spaces, parentheses, dashes, and +. It uses a regex under the hood.

var
    TypeHelper: Codeunit "Type Helper";
    Value1, Value2: Text;
begin
    Value1 := '+1 (555) 123-4567';
    Value2 := 'not-a-phone';

    Message('IsPhoneNumber(''' + Value1 + '''): %1\IsPhoneNumber(''' + Value2 + '''): %2',
        TypeHelper.IsPhoneNumber(Value1), TypeHelper.IsPhoneNumber(Value2));
end;

IsLatinLetter / IsDigit / IsUpper

procedure IsLatinLetter(ch: Char): Boolean
procedure IsDigit(ch: Char): Boolean
procedure IsUpper(ch: Char): Boolean

Character-level checks. Handy when parsing text character by character.

var
    TypeHelper: Codeunit "Type Helper";
    ch: Char;
begin
    ch := 'A';
    if TypeHelper.IsLatinLetter(ch) then
        Message('It is a letter.');

    ch := '3';
    if TypeHelper.IsDigit(ch) then
        Message('It is a digit.');
end;

TextDistance

procedure TextDistance(Text1: Text; Text2: Text): Integer

Calculates the Levenshtein distance (I didn’t know what this was before digging into this Codeunit) between two strings—the minimum number of single-character edits to get from one string to the other. Useful for fuzzy matching or detecting near-duplicates.

var
    TypeHelper: Codeunit "Type Helper";
    Distance: Integer;
begin
    Distance := TypeHelper.TextDistance('Business', 'Busines');  // 1
    Distance := TypeHelper.TextDistance('Hello', 'World');       // 4
end;

Note: Strings are limited to ~1024 characters.

NewLine / CRLFSeparator / LFSeparator

procedure NewLine(): Text
procedure CRLFSeparator(): Text[2]
procedure LFSeparator(): Text[1]

Returns the system newline string, a carriage-return + line-feed pair, or just a line feed. Avoid hardcoding character codes.

var
    TypeHelper: Codeunit "Type Helper";
    Msg: Text;
begin
    Msg := 'Line one' + TypeHelper.CRLFSeparator() + 'Line two';
    Message(Msg);
end;

Date and Time

FormatDateWithCurrentCulture

procedure FormatDateWithCurrentCulture(DateToFormat: Date): Text

The simplest way to format a Date using the current user’s locale. Great for displaying dates in messages or reports.

var
    TypeHelper: Codeunit "Type Helper";
    FormattedDate: Text;
begin
    FormattedDate := TypeHelper.FormatDateWithCurrentCulture(WorkDate());
    Message(FormattedDate);
end;

FormatDate (overloads)

procedure FormatDate(DateToFormat: Date; LanguageId: Integer): Text
procedure FormatDate(DateToFormat: Date; Format: Text; CultureName: Text): Text

Two overloads let you format with a specific language ID or a custom format string and culture name.

var
    TypeHelper: Codeunit "Type Helper";
begin
    // Format using a language ID (e.g., 1033 = en-US)
    Message(TypeHelper.FormatDate(WorkDate(), 1033));

    // Format using a .NET format string and culture name
    Message(TypeHelper.FormatDate(WorkDate(), 'MMMM dd, yyyy', 'en-US'));
end;

CompareDateTime

procedure CompareDateTime(DateTimeA: DateTime; DateTimeB: DateTime): Integer

Compares two DateTime values with a built-in millisecond-level tolerance that accounts for SQL precision rounding. Returns 1, 0, or -1.

var
    TypeHelper: Codeunit "Type Helper";
    StartDateTime: DateTime;
    EndDateTime: DateTime;
    Result: Integer;
begin
    StartDateTime := CreateDateTime(WorkDate(), 080000T);
    EndDateTime := CreateDateTime(WorkDate(), 170000T);

    Result := TypeHelper.CompareDateTime(StartDateTime, EndDateTime);
    Message('CompareDateTime result: %1 (negative means first is earlier)', Result);
end;

Don’t compare DateTime values directly with = when they come from the database—use this instead.

AddHoursToDateTime

procedure AddHoursToDateTime(SourceDateTime: DateTime; NoOfHours: Integer): DateTime

Adds a number of hours to a DateTime value.

var
    TypeHelper: Codeunit "Type Helper";
    NewDT: DateTime;
begin
    NewDT := TypeHelper.AddHoursToDateTime(CurrentDateTime, 8);
end;

GetHMSFromTime

procedure GetHMSFromTime(var Hour: Integer; var Minute: Integer; var Second: Integer; TimeSource: Time)

Breaks a Time value into its hour, minute, and second components.

var
    TypeHelper: Codeunit "Type Helper";
    H: Integer;
    M: Integer;
    S: Integer;
    CurrentTime: Time;
begin
    CurrentTime := Time;
    TypeHelper.GetHMSFromTime(H, M, S, CurrentTime);
    Message('Current time -> H:%1 M:%2 S:%3', H, M, S);
end;

EvaluateUnixTimestamp

procedure EvaluateUnixTimestamp(Timestamp: BigInteger): DateTime

Converts a Unix epoch timestamp (BigInteger, seconds since Jan 1 1970) to a DateTime, adjusting for the user’s timezone offset.

var
    TypeHelper: Codeunit "Type Helper";
    ResultDT: DateTime;
    TimeStamp: BigInteger;
begin
    TimeStamp := 1740657600;
    ResultDT := TypeHelper.EvaluateUnixTimestamp(TimeStamp);
    Message('EvaluateUnixTimestamp(' + Format(TimeStamp, 9) + '): %1', ResultDT);
end;

GetCurrUTCDateTime / GetCurrUTCDateTimeAsText / GetCurrUTCDateTimeISO8601

procedure GetCurrUTCDateTime(): DateTime
procedure GetCurrUTCDateTimeAsText(): Text
procedure GetCurrUTCDateTimeISO8601(): Text

Three shortcuts for getting the current UTC time in different formats.

var
    TypeHelper: Codeunit "Type Helper";
begin
    // DateTime value
    MyDT := TypeHelper.GetCurrUTCDateTime();

    // RFC 1123 text: "Thu, 27 Feb 2026 14:30:00 GMT"
    MyText := TypeHelper.GetCurrUTCDateTimeAsText();

    // ISO 8601: "2026-02-27T14:30:00Z"
    MyText := TypeHelper.GetCurrUTCDateTimeISO8601();
end;

GetCurrUTCDateTimeISO8601 is especially useful when building API payloads.

Timezone Conversions

GetUserTimezoneOffset

procedure GetUserTimezoneOffset(var Duration: Duration): Boolean

Returns the current user’s UTC offset as a Duration. Returns false if the user has no timezone set.

var
    TypeHelper: Codeunit "Type Helper";
    Offset: Duration;
begin
    if TypeHelper.GetUserTimezoneOffset(Offset) then
        Message('Offset in ms: %1', Offset);
end;

Type Conversion and Formatting

Evaluate

procedure Evaluate(var Variable: Variant; String: Text; Format: Text; CultureName: Text): Boolean

The general-purpose type evaluator. Pass in a Variant of the target type, a text string, an optional format, and an optional culture name.

var
    TypeHelper: Codeunit "Type Helper";
    Value: Variant;
    ParsedDate: Date;
    Ok: Boolean;
begin
    ParsedDate := 0D;
    Value := ParsedDate;
    Ok := TypeHelper.Evaluate(Value, '02/27/2026', 'MM/dd/yyyy', 'en-US');
    if Ok then
        ParsedDate := Value;
end;

FormatDecimal

procedure FormatDecimal(Decimal: Decimal; DataFormat: Text; DataFormattingCulture: Text): Text

Formats a Decimal with a .NET format string and culture name. Useful for building API payloads or localized output.

var
    TypeHelper: Codeunit "Type Helper";
    Formatted: Text;
begin
    Formatted := TypeHelper.FormatDecimal(1234.56, 'N2', 'en-US');  // "1,234.56"
    Formatted := TypeHelper.FormatDecimal(1234.56, 'N2', 'de-DE');  // "1.234,56"
end;

IntToHex

procedure IntToHex(IntValue: Integer): Text

Converts an integer to its hexadecimal representation.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(TypeHelper.IntToHex(255));   // "FF"
    Message(TypeHelper.IntToHex(4096));  // "1000"
end;

Maximum / Minimum

procedure Maximum(Value1: Decimal; Value2: Decimal): Decimal
procedure Minimum(Value1: Decimal; Value2: Decimal): Decimal

Returns the larger or smaller of two Decimal values.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message('%1', TypeHelper.Maximum(10.0, 25.5));  // 25.5
    Message('%1', TypeHelper.Minimum(10.0, 25.5));  // 10
end;

Web and URL Encoding

These are essential any time you’re calling external APIs or generating web links in AL.

UrlEncode / UrlDecode

procedure UrlEncode(var Value: Text): Text
procedure UrlEncode(var Value: SecretText): SecretText
procedure UrlDecode(var Value: Text): Text

var
    TypeHelper: Codeunit "Type Helper";
    Encoded: Text;
begin
    Encoded := 'search term with spaces';
    TypeHelper.UrlEncode(Encoded);
    Message(Encoded);  // "search+term+with+spaces"
end;

There’s also an overload that accepts and returns SecretText for encoding credentials without exposing the raw value.

HtmlEncode / HtmlDecode

procedure HtmlEncode(var Value: Text): Text
procedure HtmlDecode(var Value: Text): Text

Encodes characters like <, >, & for safe HTML output, or decodes them back.

var
    TypeHelper: Codeunit "Type Helper";
    SafeHtml: Text;
begin
    SafeHtml := '<script>alert("xss")</script>';
    TypeHelper.HtmlEncode(SafeHtml);
    Message(SafeHtml);  // "&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;"
end;

UriEscapeDataString / UriGetAuthority

procedure UriEscapeDataString(Value: Text): Text
procedure UriGetAuthority(Value: Text): Text

UriEscapeDataString percent-encodes a value (RFC 3986). UriGetAuthority extracts the scheme + host from a URL.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(TypeHelper.UriEscapeDataString('hello world'));  // "hello%20world"
    Message(TypeHelper.UriGetAuthority('https://api.example.com/v1/items'));
    // "https://api.example.com"
end;

Option Field Helpers

GetOptionNo

procedure GetOptionNo(Value: Text; OptionString: Text): Integer

Looks up the integer index of an option value string within an option set string. Returns -1 if not found.

var
    TypeHelper: Codeunit "Type Helper";
    Idx: Integer;
begin
    Idx := TypeHelper.GetOptionNo('Posted', 'Open,Released,Posted,Canceled');
    // Returns 2
end;

GetNumberOfOptions

procedure GetNumberOfOptions(OptionString: Text): Integer

Counts how many comma-separated options are in an option string.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message('%1', TypeHelper.GetNumberOfOptions('Open,Released,Posted'));  // 2 (counts commas)
end;

Watch out: this counts commas, so it returns n - 1 for n options. Adjust accordingly.

Record and Field Reflection

GetField / GetFieldLength

procedure GetField(TableNo: Integer; FieldNo: Integer; var Field: Record Field): Boolean
procedure GetFieldLength(TableNo: Integer; FieldNo: Integer): Integer

GetField retrieves field metadata from the Field virtual table and returns false if the field doesn’t exist or is obsolete (ObsoleteState = Removed). GetFieldLength returns the declared length of a text field.

var
    TypeHelper: Codeunit "Type Helper";
    FieldRec: Record Field;
begin
    if TypeHelper.GetField(Database::Customer, Customer.FieldNo(Name), FieldRec) then
        Message('Max length: %1', TypeHelper.GetFieldLength(Database::Customer, Customer.FieldNo(Name)));
end;

SortRecordRef

procedure SortRecordRef(var RecRef: RecordRef; CommaSeparatedFieldsToSort: Text; Ascending: Boolean)

Applies a sort order to a RecordRef using a comma-separated list of field names.

var
    TypeHelper: Codeunit "Type Helper";
    RecRef: RecordRef;
begin
    RecRef.Open(Database::Customer);
    TypeHelper.SortRecordRef(RecRef, '"No."', true);  // ascending by No.
    if RecRef.FindSet() then
        repeat
            // ...
        until RecRef.Next() = 0;
end;

GetKeyAsString

procedure GetKeyAsString(RecordVariant: Variant; KeyIndex: Integer): Text

Returns the key fields of a record as a comma-separated string. Useful for logging or telemetry.

var
    Cust: Record Customer;
    TypeHelper: Codeunit "Type Helper";
    KeyText: Text;
begin
    if Cust.FindFirst() then begin
        KeyText := TypeHelper.GetKeyAsString(Cust, 1);
        Message('GetKeyAsString: %1', KeyText);
    end;
end;

Stream Reading

ReadAsTextWithSeparator / TryReadAsTextWithSeparator

procedure ReadAsTextWithSeparator(InStream: InStream; LineSeparator: Text): Text
[TryFunction]
procedure TryReadAsTextWithSeparator(InStream: InStream; LineSeparator: Text; var Content: Text): Boolean

Reads an InStream into a Text value, using a specified line separator. TryReadAsTextWithSeparator wraps the call in a [TryFunction] for error-safe reading.

var
    TempBlob: Codeunit "Temp Blob";
    TypeHelper: Codeunit "Type Helper";
    FileContent: Text;
    IStream: InStream;
    OStream: OutStream;
begin
    TempBlob.CreateOutStream(OStream);
    OStream.WriteText('Line 1');
    OStream.WriteText(TypeHelper.CRLFSeparator());
    OStream.WriteText('Line 2');
    OStream.WriteText(TypeHelper.CRLFSeparator());
    OStream.WriteText('Line 3');

    TempBlob.CreateInStream(IStream);
    FileContent := TypeHelper.ReadAsTextWithSeparator(IStream, TypeHelper.CRLFSeparator());
    Message('ReadAsTextWithSeparator:\%1', FileContent);
end;

Amount and Currency Formatting

GetAmountFormatLCYWithUserLocale

procedure GetAmountFormatLCYWithUserLocale(): Text
procedure GetAmountFormatLCYWithUserLocale(DecimalPlaces: Integer): Text

Returns a BC format string for displaying amounts in the local currency, formatted for the current user’s locale. Pass an optional decimal places count.

var
    TypeHelper: Codeunit "Type Helper";
    AmtFormat: Text;
begin
    AmtFormat := TypeHelper.GetAmountFormatLCYWithUserLocale();
    Message(Format(1234.56, 0, AmtFormat));
end;

GetXMLAmountFormatWithTwoDecimalPlaces / GetXMLDateFormat

procedure GetXMLAmountFormatWithTwoDecimalPlaces(): Text
procedure GetXMLDateFormat(): Text

Return BC format strings suitable for XML output—two decimal places for amounts and the standard XML date format.

var
    TypeHelper: Codeunit "Type Helper";
begin
    Message(Format(Today, 0, TypeHelper.GetXMLDateFormat()));        // e.g., "2026-02-27"
    Message(Format(12345.6, 0, TypeHelper.GetXMLAmountFormatWithTwoDecimalPlaces()));  // "12345.60"
end;

Wrapping Up

The "Type Helper" codeunit is one of the most useful utility libraries in BC’s base application—and one of the most underused. Before writing your own string parser, encoding helper, or date workaround, it’s worth skimming the procedure list. There’s a good chance something here already does exactly what you need.

A few things to keep in mind:

• LanguageIDToCultureName and GetCultureName are obsolete as of v26—Use Codeunit 43 Language instead.
• UrlEncodeSecret is obsolete as of v27—Use the SecretText overload of UrlEncode instead.

Learn more: Codeunit “Type Helper” – Microsoft Learn

Note: The code and information discussed in this article are for informational and demonstration purposes only. Always test in a sandbox environment before deploying to production. This content was written referencing Microsoft Dynamics 365 Business Central 2025 Wave 2.