Zum Inhalt springen
Von C/AL zu AL: der Kurs für NAV-EntwicklerEin Kurs der decoso GmbH & Co. KGErstgespräch
Kursübersicht › Seite 7 von 11

Berichte, Queries, XMLports und APIs

Berichte mit RDLC-, Word- und Excel-Layout, Report Extensions, Queries, XMLports und eigene API-Pages. Dazu: was aus SOAP und OData wird.

Stand November 2026 · Version 29

Autor: Elvis Schmidt, decoso GmbH & Co. KG

Lernziele dieser Seite Nach dieser Seite kannst du einen Bericht in AL schreiben und mit RDLC-, Word- und Excel-Layout ausliefern, einen Standardbericht per reportextension erweitern oder ersetzen, Berichte ohne Dateisystem als PDF erzeugen, Query-Objekte für schnelle Auswertungen nutzen, XMLports über Streams ausführen und deine Daten über eine eigene API-Page nach außen anbieten. Außerdem weißt du, was aus SOAP, OData und den alten Anmeldeverfahren geworden ist.

1Was sich gegenüber NAV 2017 ändert

Bei Berichten bringst du aus NAV 2017 schon viel mit: Das Dataset mit DataItems und Columns, die Request Page, RDLC und Word-Layouts gab es dort bereits. Die klassischen Sections sind seit NAV 2013 Geschichte, daran ändert sich nichts. Neu ist vor allem das Drumherum: Layouts sind Dateien im Projekt, es gibt Excel als dritten Layouttyp, mehrere Layouts pro Bericht, und Standardberichte lassen sich erweitern statt kopieren.

ThemaNAV 2017Business Central (AL)
BerichtsdefinitionReport Dataset Designer in C/SIDETextdatei *.Report.al mit dataset, requestpage, rendering, labels
RDLC-LayoutIm Objekt eingebettet, Bearbeitung über „View → Layout“ mit Visual Studio oder Report BuilderEigene .rdl-Datei im Projektordner, Bearbeitung mit Microsoft Report Builder oder Visual Studio
Word-LayoutEingebettet, eigene Layouts über „Custom Report Layouts“Eigene .docx-Datei im Projekt, Kundenlayouts über Seite „Berichtslayouts“
Excel-LayoutNicht vorhanden.xlsx-Datei mit Datenblatt, Auswertung per Pivot/Formeln (ab 2022 Wave 1)
Mehrere LayoutsJe ein eingebautes RDLC- und Word-LayoutBeliebig viele im Abschnitt rendering
Standardbericht ändernObjekt ändern oder in 50000er-Bereich kopierenreportextension oder Ersatz per Event
PDF auf Server speichernREPORT.SAVEASPDF(Nr, Dateiname)Report.SaveAs(...) in einen OutStream
MenüeintragMenuSuiteUsageCategory und ApplicationArea am Bericht
QueryQuery DesignerTextdatei *.Query.al, zusätzlich QueryType = API
XMLportXMLport Designer, Dateiname auf Server oder ClientTextdatei *.XmlPort.al, Ausführung über Streams
WebdienstePage/Codeunit/Query als SOAP und OData veröffentlichenEigene API-Pages und API-Queries (OData V4, versioniert). SOAP ist abgekündigt; Microsoft-Pages lassen sich künftig weder als SOAP- noch als OData-Endpunkt veröffentlichen (Abschnitt 14)
Anmeldung von außenWindows, NavUserPassword, Web Service Access KeyIn der Cloud ausschließlich OAuth 2.0 über Microsoft Entra ID

2Aufbau eines Berichts in AL

Ein Bericht besteht aus bis zu vier Blöcken plus Triggern und Variablen. Das Snippet treport erzeugt das Gerüst.

report 50100 "ABC Customer Visits"
{
    // 1. Eigenschaften
    Caption = 'Customer Visits';
    UsageCategory = ReportsAndAnalysis;
    ApplicationArea = All;
    DefaultRenderingLayout = RdlcLayout;

    // 2. Daten
    dataset
    {
        dataitem(Customer; Customer)
        {
            column(CustomerNo; "No.") { }
        }
    }

    // 3. Anforderungsseite (Filter und Optionen)
    requestpage
    {
        layout { }
    }

    // 4. Layouts
    rendering
    {
        layout(RdlcLayout)
        {
            Type = RDLC;
            LayoutFile = './src/layouts/ABCCustomerVisits.rdl';
        }
    }

    // 5. Beschriftungen, die nur im Layout gebraucht werden
    labels
    {
        ReportTitle = 'Customer Visits';
    }

    // 6. Berichtstrigger und Variablen
    trigger OnPreReport()
    begin
    end;

    var
        FromDate: Date;
}
Wiedererkennung: dataset entspricht dem Report Dataset Designer, requestpage dem Request Page Designer, labels dem Report Label Designer. Nur rendering ist wirklich neu.

3Berichtseigenschaften

EigenschaftBedeutung
CaptionAnzeigename, Englisch im Code, Deutsch über XLIFF.
UsageCategoryMacht den Bericht in der Suche (Alt+Q) auffindbar. Üblich: ReportsAndAnalysis, für Stapelverarbeitungen Tasks, für Belege Documents.
ApplicationAreaWie bei Pages; ohne sie bleibt der Bericht in der Suche unsichtbar.
DefaultRenderingLayoutName des Standardlayouts aus dem Abschnitt rendering.
ProcessingOnlytrue für Stapelverarbeitungen ohne Ausdruck (Abschnitt 11).
UseRequestPagefalse unterdrückt die Anforderungsseite.
AllowSchedulingSteuert, ob Anwender den Bericht über „Senden an → Planen“ in die Aufgabenwarteschlange stellen dürfen.
PreviewModeNormal oder PrintLayout für die RDLC-Vorschau.
EnableHyperlinks, EnableExternalImagesRDLC-Schalter wie in NAV 2017.
WordMergeDataItemDataItem, pro dessen Datensatz ein eigenes Word-Dokument entsteht (Belegberichte).
DataAccessIntentReadOnly lässt den Bericht in der Cloud auf einer Lesereplik der Datenbank laufen. Sinnvoll für große Auswertungen, die nichts schreiben.
PermissionsZusätzliche Tabellenrechte für den Bericht, z. B. tabledata "Cust. Ledger Entry" = r.
TransactionTypeWie früher, selten nötig.
AdditionalSearchTermsWeitere Suchbegriffe für Alt+Q.
Veraltet: Die Eigenschaften RDLCLayout, WordLayout und DefaultLayout direkt am Bericht funktionieren noch, sind aber die alte Schreibweise aus den ersten AL-Jahren. Sie lassen sich nicht mit dem Abschnitt rendering mischen. Für neue Berichte nimmst du immer rendering.

4Dataset, Spalten und Trigger

DataItems

Die Verschachtelung in geschweiften Klammern ersetzt die Einrückung im alten Designer. Ein DataItem hat einen Namen und eine Tabelle: dataitem(Name; Tabelle). Der Name ist gleichzeitig die Record-Variable.

EigenschaftBedeutung
DataItemTableViewFeste Sortierung und Filter: sorting("No.") where(Blocked = const(" ")). Mit sorting verschwindet die Sortierauswahl auf der Anforderungsseite.
DataItemLinkVerknüpfung zum übergeordneten DataItem: "Customer No." = field("No.").
DataItemLinkReferenceNennt das DataItem, auf das sich der Link bezieht, falls es nicht das direkt übergeordnete ist.
RequestFilterFieldsVorgeschlagene Filterfelder auf der Anforderungsseite.
RequestFilterHeadingÜberschrift des Filterblocks.
PrintOnlyIfDetailÜbergeordneten Satz nur ausgeben, wenn es untergeordnete Sätze gibt.
CalcFieldsFlowFields, die automatisch berechnet werden.
MaxIterationBegrenzt die Durchläufe, typisch bei der Tabelle Integer.
UseTemporaryDataItem läuft über eine temporäre Tabelle, die du vorher im Code füllst.

Columns

column(CustomerNo; "No.") { }                          // Feld des DataItems
column(CustomerName; Name) { IncludeCaption = true; }  // liefert zusätzlich CustomerNameCaption
column(CompanyName; CompanyProperty.DisplayName()) { } // Ausdruck
column(VisitCount; VisitCount) { }                     // Variable
column(Amount; "Sales (LCY)")
{
    AutoFormatType = 1;                                // Betragsformat wie früher
}

Spaltennamen müssen im ganzen Bericht eindeutig sein und dürfen keine Leer- oder Sonderzeichen enthalten. Diese Namen siehst du später im RDLC-Dataset, im Word-XML-Mapping und als Spaltenüberschriften im Excel-Datenblatt. Wähle sie deshalb sorgfältig: Umbenennen bricht jedes vorhandene Layout, auch die Layouts, die sich Kunden selbst gebaut haben.

Trigger

EbeneTriggerTypische Verwendung
BerichtOnInitReportVorbelegung, bevor die Anforderungsseite erscheint
BerichtOnPreReportPrüfung der Optionen, Filtertexte merken
BerichtOnPostReportAbschlussmeldung
DataItemOnPreDataItemZusätzliche Filter setzen
DataItemOnAfterGetRecordBerechnungen pro Datensatz, CurrReport.Skip()
DataItemOnPostDataItemAufräumen, Summen abschließen

NAV 2017 (C/AL)

// Customer - OnAfterGetRecord()
CALCFIELDS("Balance (LCY)");
IF "Balance (LCY)" = 0 THEN
  CurrReport.SKIP;

Business Central (AL)

trigger OnAfterGetRecord()
begin
    Customer.CalcFields("Balance (LCY)");
    if Customer."Balance (LCY)" = 0 then
        CurrReport.Skip();
end;
Kein stillschweigendes WITH mehr: In DataItem-Triggern sprichst du Felder über den DataItem-Namen an (Customer."Balance (LCY)"). Nur im Quellausdruck einer column und in Eigenschaften wie DataItemLink darf der Feldname allein stehen.

Geblieben sind CurrReport.Skip(), CurrReport.Break() und CurrReport.Quit(). Entfallen oder als veraltet markiert sind die Relikte aus der Classic-Zeit, also CurrReport.PageNo, CreateTotals, TotalsCausedBy und ShowOutput. Seitenzahlen und Summen bildet das Layout.

Labels

labels
{
    ReportTitle = 'Customer Visits';
    PageCaption = 'Page';
    VisitDateCaption = 'Visit Date', Comment = 'Column header';
}

Labels landen in der XLIFF-Datei und werden wie alle anderen Texte übersetzt (Seite 4). Im RDLC stehen sie als Parameter zur Verfügung, im Word-Layout unter „Labels“ im XML-Mapping, in Excel-Layouts auf einem eigenen Blatt für Beschriftungen.

5Anforderungsseite

Die requestpage ist eine kleine Page im Bericht. Es gelten dieselben Regeln wie auf Seite 4: ApplicationArea, englische Captions, ToolTips.

requestpage
{
    SaveValues = true;          // merkt sich die Eingaben pro Benutzer

    layout
    {
        area(Content)
        {
            group(Options)
            {
                Caption = 'Options';

                field(FromDateCtrl; FromDate)
                {
                    ApplicationArea = All;
                    Caption = 'From Date';
                    ToolTip = 'Specifies the first visit date to include.';
                }
                field(ToDateCtrl; ToDate)
                {
                    ApplicationArea = All;
                    Caption = 'To Date';
                    ToolTip = 'Specifies the last visit date to include.';
                }
                field(ShowDetailsCtrl; ShowDetails)
                {
                    ApplicationArea = All;
                    Caption = 'Show Details';
                    ToolTip = 'Specifies whether each visit is printed.';
                }
            }
        }
    }

    trigger OnOpenPage()
    begin
        if ToDate = 0D then
            ToDate := WorkDate();
        if FromDate = 0D then
            FromDate := CalcDate('<-CM>', ToDate);
    end;
}

Im Web-Client bietet die Anforderungsseite dem Anwender mehr als früher: Vorschau im Browser, „Senden an“ (PDF, Word, Excel, Planen), Auswahl des Layouts direkt vor dem Ausführen (in neueren Versionen) und gespeicherte Einstellungen („Standardwerte verwenden von“). Wenn du SaveValues = true setzt, bedenke das beim Testen: Deine Vorbelegung in OnOpenPage wird von den gespeicherten Werten überschrieben. Darum prüft das Beispiel oben auf 0D.

6Layouts: RDLC, Word, Excel

rendering
{
    layout(RdlcLayout)
    {
        Type = RDLC;
        LayoutFile = './src/layouts/ABCCustomerVisits.rdl';
        Caption = 'Customer Visits (RDLC)';
        Summary = 'Detailed list grouped by customer.';
    }
    layout(WordLayout)
    {
        Type = Word;
        LayoutFile = './src/layouts/ABCCustomerVisits.docx';
        Caption = 'Customer Visits (Word)';
    }
    layout(ExcelLayout)
    {
        Type = Excel;
        LayoutFile = './src/layouts/ABCCustomerVisits.xlsx';
        Caption = 'Customer Visits (Excel)';
        Summary = 'Raw data with pivot table.';
    }
}
Leere Layoutdateien entstehen von selbst. Wenn die in LayoutFile genannte Datei nicht existiert, legt der Compiler sie beim Build (Strg+Umschalt+B) an – mit dem passenden Dataset, aber ohne Gestaltung. Bei jedem weiteren Build wird das Dataset in der .rdl-Datei an die Spalten im AL-Code angepasst.

Wann welcher Typ?

TypStärkenSchwächenEinsatz
RDLCVolle Kontrolle: Gruppierung, Summen, Ausdrücke, bedingte Sichtbarkeit, SeitenkopfSperriges Werkzeug, Anwender können es praktisch nicht selbst ändernKomplexe Listen, Belege mit viel Logik
WordAnwender können das Layout selbst anpassen, gut für Logo und BriefkopfKeine Berechnungen im Layout, Gruppierung eingeschränktBelege (Rechnung, Angebot), Anschreiben
ExcelAnwender werten mit Pivot, Diagrammen und Formeln selbst ausKein seitengenaues DruckbildAuswertungen, Listen, alles was früher „Export nach Excel“ war

RDLC bearbeiten

Installiere den kostenlosen Microsoft Report Builder (oder nutze Visual Studio mit der RDLC-Report-Designer-Erweiterung). Der Ablauf ist: Spalten in AL anlegen, bauen, .rdl-Datei im Report Builder öffnen und gestalten, speichern, mit Strg+F5 veröffentlichen und testen. In .vscode/settings.json kannst du über die AL-Einstellungen festlegen, dass sich .rdl-Dateien per Rechtsklick direkt im Report Builder öffnen.

Alles, was du aus NAV 2017 über RDLC weißt, gilt weiter: Tablix, Gruppen, =Fields!CustomerNo.Value, =First(...), die SetData/GetData-Technik für Kopfdaten im Seitenkopf, Code.-Funktionen. Auch die Schwächen sind dieselben.

Word bearbeiten

Öffne die .docx-Datei in Word, blende die Registerkarte „Entwicklertools“ ein und öffne den „XML-Zuordnungsbereich“. Dort wählst du den benutzerdefinierten XML-Teil des Berichts (er beginnt mit urn:microsoft-dynamics-nav/reports/...). Einzelne Felder fügst du per Rechtsklick als „Nur-Text-Inhaltssteuerelement“ ein. Für wiederholte Zeilen markierst du eine Tabellenzeile und fügst das DataItem als „Wiederholung“ ein. Das ist dieselbe Technik wie bei den Word-Layouts in NAV 2017.

Excel bearbeiten

Die erzeugte Arbeitsmappe enthält ein Datenblatt mit einer Tabelle, deren Spalten deinen column-Namen entsprechen. Du fügst weitere Blätter mit Pivot-Tabellen, Diagrammen oder Formeln hinzu, die auf diese Tabelle verweisen. Beim Ausführen ersetzt Business Central nur den Inhalt des Datenblatts. Das Dataset kommt flach an: Jede Zeile enthält die Spalten aller DataItem-Ebenen, die Spalten der übergeordneten Ebenen wiederholen sich. In neueren Versionen kann ein Bericht alternativ je DataItem ein eigenes Datenblatt liefern (Eigenschaft ExcelLayoutMultipleDataSheets).

Praxisempfehlung für Umsteiger: Viele Listenberichte, für die du früher stundenlang RDLC gebaut hast, sind heute mit einem Excel-Layout in zehn Minuten fertig – und der Kunde kann sie selbst weiterentwickeln. Prüfe bei jeder Auswertung zuerst, ob Excel reicht.

7Layouts beim Kunden verwalten

Die Seite „Berichtslayouts“ (Report Layouts) ersetzt die alten „Benutzerdefinierten Berichtslayouts“. Dort sieht der Kunde zu jedem Bericht alle Layouts: die aus deiner App, die aus anderen Apps und selbst hochgeladene. Er kann ein Layout exportieren, in Word oder Excel ändern, als neues Layout hochladen und pro Mandant als Standard festlegen. Das geht ohne Entwickler und ohne neue App-Version.

Für Belege bleibt zusätzlich die bekannte Kette bestehen: „Berichtsauswahl – Verkauf“ legt fest, welcher Bericht für Angebot, Auftrag oder Rechnung läuft, und über die Beleglayouts am Debitor lässt sich pro Kunde ein abweichendes Layout und eine E-Mail-Adresse hinterlegen.

Folge für dich als Entwickler: Kundenlayouts hängen an deinen Spaltennamen. Spalten hinzufügen ist immer unkritisch. Spalten umbenennen oder löschen macht Kundenlayouts kaputt, ohne dass du es beim Kompilieren merkst.

8Report Extensions

Mit reportextension (ab 2021 Wave 1, Version 18) erweiterst du einen fremden Bericht, ohne ihn zu kopieren. Du kannst Spalten zu vorhandenen DataItems hinzufügen, neue DataItems einhängen, die Anforderungsseite ergänzen, Trigger anhängen und eigene Layouts mitliefern.

reportextension 50100 "ABC Customer List Ext" extends "Customer - List"
{
    dataset
    {
        add(Customer)
        {
            column(ABCKundenklasse; "ABC Kundenklasse") { IncludeCaption = true; }
            column(ABCLetzterBesuch; "ABC Letzter Besuch") { IncludeCaption = true; }
        }

        // Neues DataItem unterhalb eines vorhandenen:
        addlast(Customer)
        {
            dataitem(ABCVisit; "ABC Customer Visit")
            {
                DataItemLink = "Customer No." = field("No.");
                column(ABCVisitDate; "Visit Date") { }
                column(ABCVisitDescription; Description) { }
            }
        }
    }

    requestpage
    {
        layout
        {
            addlast(Content)
            {
                field(ABCShowVisits; ABCShowVisits)
                {
                    ApplicationArea = All;
                    Caption = 'Show Visits';
                    ToolTip = 'Specifies whether customer visits are included.';
                }
            }
        }
    }

    rendering
    {
        layout(ABCExcelLayout)
        {
            Type = Excel;
            LayoutFile = './src/layouts/ABCCustomerList.xlsx';
            Caption = 'Customer List with Visits (Excel)';
        }
    }

    var
        ABCShowVisits: Boolean;
}

Was geht, was nicht

MöglichNicht möglich
Spalten zu vorhandenen DataItems (add)
Neue DataItems (addfirst, addlast, addafter, addbefore)
Felder und Gruppen auf der Anforderungsseite
Zusätzliche Layouts
Trigger OnPreReport, OnPostReport sowie DataItem-Trigger über modify(...) (laufen zusätzlich zum Original)
Eigene Variablen und Prozeduren
Vorhandene Spalten oder DataItems entfernen oder umbenennen
Vorhandenen Triggercode ersetzen
Eigenschaften des Originals wie DataItemTableView umbiegen (Details versionsabhängig)
Auf lokale Variablen des Originalberichts zugreifen
Das vorhandene Layout im Paket verändern – du lieferst immer ein eigenes mit
Wichtig zum Verständnis: Neue Spalten erscheinen nicht von selbst auf dem Ausdruck. Sie stehen nur im Dataset zur Verfügung. Sichtbar werden sie erst in einem Layout, das sie verwendet – entweder in deinem mitgelieferten oder in einem Kundenlayout. Üblicher Weg: Standardlayout über „Berichtslayouts“ exportieren, um deine Felder ergänzen, als LayoutFile in die Extension legen und beim Kunden als Standard auswählen.

Wie bei Table und Page Extensions gilt: pro App nur eine Extension je Bericht, und alle eigenen Namen bekommen dein Präfix, damit sie nie mit späteren Microsoft-Spalten kollidieren.

9Standardbericht ersetzen

Wenn die Extension nicht reicht, etwa weil du die Datenlogik grundlegend ändern musst, baust du einen eigenen Bericht (notfalls als Kopie des Standards aus den Symbolen) und sorgst dafür, dass er statt des Originals läuft. Dafür gibt es drei Wege.

WegWirkungGeeignet für
BerichtsauswahlReine Einrichtung, kein CodeBelege (Rechnung, Lieferschein, Mahnung …)
Event OnAfterSubstituteReportTauscht die Berichts-ID überall, wo der Bericht aus der Oberfläche oder per Report.Run gestartet wirdListen und Auswertungen, die fest im Standard verdrahtet sind
Aktion per Page ExtensionStandardaktion ausblenden, eigene Aktion einfügenEinzelne Stellen
codeunit 50110 "ABC Report Substitution"
{
    [EventSubscriber(ObjectType::Codeunit, Codeunit::ReportManagement, 'OnAfterSubstituteReport', '', false, false)]
    local procedure ReplaceCustomerList(ReportId: Integer; var NewReportId: Integer)
    begin
        if ReportId = Report::"Customer - List" then
            NewReportId := Report::"ABC Customer List";
    end;
}
Vorsicht bei mehreren Apps: Wenn zwei Apps denselben Bericht ersetzen, gewinnt, wer zuletzt läuft, und die Reihenfolge ist nicht festgelegt. Prüfe im Subscriber, ob NewReportId noch dem Original entspricht, bevor du überschreibst. Und: Ein kopierter Bericht bekommt keine Microsoft-Korrekturen mehr. Die Kopie ist immer die letzte Wahl.

10Berichte aus Code ausführen

AufrufBedeutung
Report.Run(Report::"X", true, false, Rec)Startet den Bericht; Parameter: Anforderungsseite zeigen, Systemdrucker, Record mit Filtern
Report.RunModal(...)Wie Run, der Code wartet aber auf das Ende
Report.RunRequestPage(Report::"X")Zeigt nur die Anforderungsseite und gibt die Eingaben als XML-Text zurück
Report.SaveAs(Report::"X", Parameter, ReportFormat::Pdf, OutStr)Erzeugt die Ausgabe in einen Stream – der Ersatz für SAVEASPDF
Report.Execute(Report::"X", Parameter)Führt mit gespeicherten Parametern aus, ohne Ausgabe (Verarbeitungsberichte)
Report.Print(Report::"X", Parameter)Druckt mit gespeicherten Parametern

NAV 2017 (C/AL)

Customer.SETRANGE("No.",CustNo);
REPORT.SAVEASPDF(
  50000,
  'C:\Temp\Besuche.pdf',
  Customer);
// danach Datei per Mail,
// DOWNLOAD usw.

Business Central (AL)

procedure DownloadVisitsPdf(CustNo: Code[20])
var
    Customer: Record Customer;
    TempBlob: Codeunit "Temp Blob";
    RecRef: RecordRef;
    OutStr: OutStream;
    InStr: InStream;
    FileName: Text;
begin
    Customer.SetRange("No.", CustNo);
    RecRef.GetTable(Customer);

    TempBlob.CreateOutStream(OutStr);
    Report.SaveAs(
        Report::"ABC Customer Visits", '',
        ReportFormat::Pdf, OutStr, RecRef);

    TempBlob.CreateInStream(InStr);
    FileName := 'Besuche_' + CustNo + '.pdf';
    DownloadFromStream(InStr, '', '', '', FileName);
end;

Der Stream aus Report.SaveAs lässt sich genauso gut an eine E-Mail hängen (EmailMessage.AddAttachment, siehe Seite 6), in einem Blob-Feld ablegen oder per HttpClient an ein Archivsystem schicken. Als ReportFormat gibt es Pdf, Word, Excel, Html und Xml. Mit Xml bekommst du das reine Dataset, das ist praktisch zum Testen ohne Layout.

Anforderungsseite einmal zeigen, später ausführen

var
    Parameters: Text;
begin
    Parameters := Report.RunRequestPage(Report::"ABC Customer Visits");
    if Parameters = '' then
        exit;                       // Anwender hat abgebrochen
    // Parameters z. B. in einer Einrichtungstabelle speichern
    // und später in der Aufgabenwarteschlange verwenden:
    Report.SaveAs(Report::"ABC Customer Visits", Parameters, ReportFormat::Pdf, OutStr);
end;
Hintergrundsitzungen: In der Aufgabenwarteschlange gibt es keine Oberfläche. Report.Run mit Anforderungsseite oder Vorschau schlägt dort fehl. Verwende SaveAs, Execute oder Print mit gespeicherten Parametern. Drucken in der Cloud läuft über Universal Print oder einen E-Mail-Drucker, nicht über lokale Windows-Drucker des Servers.

11Verarbeitungsberichte

Stapelverarbeitungen (Batch Jobs) sind weiterhin Berichte mit ProcessingOnly = true. Der Vorteil gegenüber einer Codeunit bleibt derselbe: Der Anwender bekommt eine Anforderungsseite mit Filtern und Optionen geschenkt und kann den Lauf planen.

report 50101 "ABC Update Last Visit"
{
    Caption = 'Update Last Visit Dates';
    ProcessingOnly = true;
    UsageCategory = Tasks;
    ApplicationArea = All;

    dataset
    {
        dataitem(Customer; Customer)
        {
            RequestFilterFields = "No.", "Customer Posting Group";

            trigger OnAfterGetRecord()
            var
                Visit: Record "ABC Customer Visit";
            begin
                Visit.SetRange("Customer No.", Customer."No.");
                Visit.SetCurrentKey("Customer No.", "Visit Date");
                if not Visit.FindLast() then
                    CurrReport.Skip();

                if Customer."ABC Letzter Besuch" <> Visit."Visit Date" then begin
                    Customer."ABC Letzter Besuch" := Visit."Visit Date";
                    Customer.Modify(true);
                    Counter += 1;
                end;
            end;
        }
    }

    trigger OnPostReport()
    begin
        if GuiAllowed() then
            Message(UpdatedMsg, Counter);
    end;

    var
        Counter: Integer;
        UpdatedMsg: Label '%1 customers were updated.', Comment = '%1 = number of customers';
}

Das SetCurrentKey setzt einen passenden Schlüssel in der Besuchstabelle voraus. Fehlt er, lege ihn in der Tabelle an oder sortiere anders.

12Query-Objekte

Queries gab es in NAV 2017 schon, sie wurden aber selten benutzt. In der Cloud lohnen sie sich mehr: Eine Query wird zu einer einzigen SQL-Abfrage mit Joins und Aggregation. Das ist bei großen Datenmengen um Größenordnungen schneller als verschachtelte FindSet-Schleifen, und direkten SQL-Zugriff als Ausweg hast du nicht mehr.

query 50100 "ABC Visits per Customer"
{
    Caption = 'Visits per Customer';
    QueryType = Normal;
    OrderBy = descending(VisitCount);

    elements
    {
        dataitem(Customer; Customer)
        {
            column(CustomerNo; "No.") { }
            column(CustomerName; Name) { }
            column(CustomerClass; "ABC Kundenklasse") { }

            dataitem(Visit; "ABC Customer Visit")
            {
                DataItemLink = "Customer No." = Customer."No.";
                SqlJoinType = InnerJoin;

                filter(VisitDateFilter; "Visit Date") { }

                column(VisitCount)
                {
                    Method = Count;
                }
                column(LastVisitDate; "Visit Date")
                {
                    Method = Max;
                }
            }
        }
    }
}
ElementBedeutung
column ohne MethodGruppierungsspalte (SQL GROUP BY), sobald irgendwo aggregiert wird
MethodSum, Count, Average, Min, Max; für Datumsfelder auch Day, Month, Year
filterFeld, das nur gefiltert, aber nicht ausgegeben wird
SqlJoinTypeInnerJoin, LeftOuterJoin (Standard), RightOuterJoin, FullOuterJoin, CrossJoin
DataItemTableFilterFester Filter auf dem DataItem
ColumnFilterFester Filter auf einer Spalte, auch auf aggregierten Werten (SQL HAVING)
TopNumberOfRowsBegrenzung der Zeilen, auch zur Laufzeit setzbar

Query im Code lesen

procedure ShowTopCustomers()
var
    VisitsPerCustomer: Query "ABC Visits per Customer";
    Result: TextBuilder;
begin
    VisitsPerCustomer.SetRange(VisitDateFilter, CalcDate('<-1Y>', WorkDate()), WorkDate());
    VisitsPerCustomer.TopNumberOfRows(5);
    VisitsPerCustomer.Open();
    while VisitsPerCustomer.Read() do
        Result.AppendLine(
            StrSubstNo('%1 %2: %3',
                VisitsPerCustomer.CustomerNo,
                VisitsPerCustomer.CustomerName,
                VisitsPerCustomer.VisitCount));
    VisitsPerCustomer.Close();

    Message(Result.ToText());
end;

Grenzen

Queries sind nur lesend. FlowFields lassen sich nur eingeschränkt verwenden, weil sie nicht in der Tabelle gespeichert sind; eine Summe über Posten bildest du deshalb per Join und Method = Sum nach. Eine Query ist keine Record-Variable: Du kannst sie nicht als SourceTable einer normalen Listenseite nehmen. Für die Anzeige füllst du eine temporäre Tabelle, oder du gibst der Query eine UsageCategory, dann kann der Anwender sie über die Suche öffnen und im Analysemodus auswerten (neuere Versionen).

13XMLports

XMLports funktionieren fachlich wie in NAV 2017, für XML ebenso wie für Textdateien mit festem oder variablem Format. Geändert hat sich die Schreibweise und die Art der Ausführung: Es gibt keinen Dateinamen auf dem Server mehr, sondern Streams.

xmlport 50100 "ABC Visit Export"
{
    Caption = 'Visit Export';
    Direction = Export;
    Format = Xml;
    Encoding = UTF8;
    UseRequestPage = false;

    schema
    {
        textelement(Visits)
        {
            tableelement(Visit; "ABC Customer Visit")
            {
                XmlName = 'Visit';

                fieldattribute(EntryNo; Visit."Entry No.") { }
                fieldelement(CustomerNo; Visit."Customer No.") { }
                fieldelement(VisitDate; Visit."Visit Date") { }
                fieldelement(VisitType; Visit."Visit Type") { }
                fieldelement(Description; Visit.Description)
                {
                    MinOccurs = Zero;
                }
                textelement(CustomerName)
                {
                    trigger OnBeforePassVariable()
                    var
                        Customer: Record Customer;
                    begin
                        if Customer.Get(Visit."Customer No.") then
                            CustomerName := Customer.Name
                        else
                            CustomerName := '';
                    end;
                }
            }
        }
    }
}
KnotentypNAV 2017 (Node Type / Source Type)AL
Element aus TextElement / Texttextelement(Name)
Element aus TabelleElement / Tabletableelement(Name; Tabelle)
Element aus FeldElement / Fieldfieldelement(Name; Variable.Feld)
Attribut aus TextAttribute / Texttextattribute(Name)
Attribut aus FeldAttribute / Fieldfieldattribute(Name; Variable.Feld)

Die Trigger heißen wie früher: OnPreXmlPort, OnPostXmlPort, am Tabellenelement OnAfterGetRecord, OnBeforeInsertRecord, OnAfterInsertRecord, an Textelementen OnBeforePassVariable (Export) und OnAfterAssignVariable (Import).

Ausführen über Streams

Export mit Download

procedure ExportVisitsXml()
var
    Visit: Record "ABC Customer Visit";
    TempBlob: Codeunit "Temp Blob";
    OutStr: OutStream;
    InStr: InStream;
    FileName: Text;
begin
    TempBlob.CreateOutStream(OutStr);
    Xmlport.Export(
        Xmlport::"ABC Visit Export",
        OutStr, Visit);

    TempBlob.CreateInStream(InStr);
    FileName := 'Besuche.xml';
    DownloadFromStream(
        InStr, '', '', '', FileName);
end;

Import nach Upload

procedure ImportVisitsXml()
var
    InStr: InStream;
    FileName: Text;
begin
    if not UploadIntoStream(
        'Select file', '',
        'XML files (*.xml)|*.xml',
        FileName, InStr)
    then
        exit;

    Xmlport.Import(
        Xmlport::"ABC Visit Import",
        InStr);
end;

Xmlport.Run(Xmlport::"X", true, false) gibt es weiterhin. Der Web-Client übernimmt dann Upload oder Download selbst und zeigt die Anforderungsseite. Für eigene Abläufe ist die Stream-Variante flexibler, weil die Daten ebenso aus einem HTTP-Aufruf oder einem Blob-Feld kommen können.

Wann XMLport, wann Code?

AufgabeEmpfehlung
CSV mit Anführungszeichen, Trennzeichen im Text, vielen SpaltenXMLport mit Format = VariableText (FieldSeparator, FieldDelimiter, TableSeparator)
Datei mit festen SpaltenbreitenXMLport mit Format = FixedText und Width je Feld
XML mit fester, tabellennaher StrukturXMLport
XML mit Namensräumen, wechselnder Struktur, tiefer VerschachtelungXmlDocument im Code (Seite 6)
JSONImmer Code mit JsonObject (Seite 6), XMLports können kein JSON
Bankformate, ZahlungsdateienZuerst das Data Exchange Framework des Standards prüfen

14Webdienste: SOAP, OData, API

In NAV 2017 hast du eine Page oder Codeunit in der Tabelle „Webdienste“ eingetragen und per SOAP oder OData angesprochen. Die Seite „Webdienste“ gibt es weiterhin, aber Microsoft baut diesen Weg schrittweise zurück. Der Stand unten wurde im November 2026 in der Microsoft-Dokumentation nachgeschlagen.

TechnikStandBewertung
SOAP allgemein (Page, Codeunit)Seit 2021 Release Wave 1 abgekündigt; soll laut Microsoft in einer kommenden Version entfernt werdenNicht mehr für Neues verwenden. Bestehende SOAP-Integrationen jetzt auf APIs oder OData V4 umstellen.
SOAP auf Microsoft-Pages (Seiten aus Apps des Herausgebers Microsoft)Seit Version 26 gesperrt, solange in der Funktionsverwaltung der Schalter „Disable SOAP web services on Microsoft UI pages“ aktiv ist; die Möglichkeit entfällt ganz (Version siehe Kasten unten)Erledigt. Wer es übergangsweise braucht, kopiert die Page in eine eigene Extension und veröffentlicht die Kopie.
OData V4 auf Microsoft-PagesFunktioniert noch; ab Version 30 (2027 Release Wave 1) lassen sich Microsoft-Pages nicht mehr als OData-Endpunkt bereitstellenNicht mehr darauf bauen. Begründung von Microsoft: Eine UI-Page ist keine API, sie darf sich mit jedem Release ändern, und das bricht Integrationen.
OData V4 auf eigenen Pages (aus deiner Extension)FunktioniertMöglich, aber dieselbe Schwäche: Die Schnittstelle ändert sich, sobald jemand die Page ändert, und Page-Trigger kosten Leistung. Besser gleich eine API-Page.
OData V4 auf veröffentlichten QueriesFunktioniertGut für lesende Auswertungen, etwa Power BI.
OData V4 „ungebundene Aktionen“ auf CodeunitsFunktioniertErsatz für SOAP-Codeunits, wenn du eine Funktion statt Daten anbieten willst.
Standard-APIs (v2.0)Von Microsoft gepflegtErste Wahl für Standarddaten: customers, items, salesOrders, salesInvoices …
Eigene API-Pages und API-QueriesEmpfohlenVersioniert, stabil, schnell – der Weg für alles Eigene und auf Dauer der einzige verlässliche.
Zwei Angaben zur Version: Für das endgültige Ende von SOAP auf Microsoft-Pages nennt die Microsoft-Dokumentation an zwei Stellen unterschiedliche Versionen. Der Artikel SOAP web services nennt 2026 Release Wave 2 (Version 29.0), der Artikel zum Funktionsschalter nennt Version 30.0. Plane mit dem früheren Termin und prüfe den aktuellen Stand in der Liste der abgekündigten Plattformfunktionen, dort steht auch das Ende von OData auf Microsoft-Pages mit Version 30.
Was das für eine Migration von NAV 2017 heißt: Jede Schnittstelle, die heute „Page 21 als Webdienst“ oder Ähnliches verwendet, muss neu gebaut werden. Prüfe zuerst, ob eine Standard-API (v2.0) die Daten schon liefert. Wenn nicht, baust du eine eigene API-Page (Abschnitt 15) mit genau den Feldern, die der Partner braucht. Das Kopieren einer Microsoft-Page in die eigene Extension ist nur eine Überbrückung, weil die Kopie keine Microsoft-Korrekturen mehr bekommt.

Webdienst mit der App ausliefern

Wenn du eine eigene Page oder Query als Webdienst veröffentlichen willst, muss das beim Kunden niemand von Hand eintragen. Lege eine XML-Datei ins Projekt:

<?xml version="1.0" encoding="UTF-8"?>
<ExportedData>
  <TenantWebServiceCollection>
    <TenantWebService>
      <ObjectType>Query</ObjectType>
      <ObjectID>50100</ObjectID>
      <ServiceName>ABCVisitsPerCustomer</ServiceName>
      <Published>true</Published>
    </TenantWebService>
  </TenantWebServiceCollection>
</ExportedData>

Beim Installieren der App wird der Eintrag angelegt. API-Pages brauchen das nicht, sie sind allein durch ihre Eigenschaften erreichbar.

15API-Pages im Detail

page 50103 "ABC Visits API"
{
    PageType = API;
    Caption = 'customerVisits', Locked = true;

    APIPublisher = 'meinefirma';
    APIGroup = 'kundenapp';
    APIVersion = 'v1.0';
    EntityName = 'customerVisit';
    EntitySetName = 'customerVisits';

    SourceTable = "ABC Customer Visit";
    ODataKeyFields = SystemId;
    DelayedInsert = true;
    Extensible = false;

    layout
    {
        area(Content)
        {
            repeater(Records)
            {
                field(id; Rec.SystemId)
                {
                    Caption = 'id', Locked = true;
                    Editable = false;
                }
                field(entryNumber; Rec."Entry No.")
                {
                    Caption = 'entryNumber', Locked = true;
                    Editable = false;
                }
                field(customerNumber; Rec."Customer No.")
                {
                    Caption = 'customerNumber', Locked = true;
                }
                field(visitDate; Rec."Visit Date")
                {
                    Caption = 'visitDate', Locked = true;
                }
                field(visitType; Rec."Visit Type")
                {
                    Caption = 'visitType', Locked = true;
                }
                field(description; Rec.Description)
                {
                    Caption = 'description', Locked = true;
                }
                field(lastModifiedDateTime; Rec.SystemModifiedAt)
                {
                    Caption = 'lastModifiedDateTime', Locked = true;
                    Editable = false;
                }
            }
        }
    }
}

Die Regeln

Eigenschaft / RegelErklärung
APIPublisher, APIGroup, APIVersionBilden den Pfad der URL. Nur Kleinbuchstaben und Ziffern, keine Leerzeichen. Version im Format v1.0, auch beta ist erlaubt.
EntityName, EntitySetNameEinzahl und Mehrzahl in camelCase. Der Mehrzahlname steht in der URL.
ODataKeyFields = SystemIdDie GUID aus den Systemfeldern (Seite 3) ist der Schlüssel nach außen. Sie bleibt auch stabil, wenn sich der Primärschlüssel durch Umbenennen ändert.
DelayedInsert = truePflicht bei API-Pages: Der Datensatz wird erst eingefügt, wenn alle Felder der Anfrage gesetzt sind.
FeldnamencamelCase, nur Buchstaben und Ziffern. Der Name vor dem Semikolon ist der JSON-Name.
CaptionsLocked = true, damit sie nicht in die Übersetzung wandern.
Kein ApplicationArea, keine AktionenAPI-Pages haben keine Oberfläche.
EnumsWerden als Text mit dem Namen des Enum-Werts übertragen, Sonderzeichen werden kodiert. Halte Enum-Namen deshalb schlicht.
TriggerOnInsertRecord, OnModifyRecord, OnDeleteRecord und Feldtrigger laufen wie auf normalen Pages; die Tabellentrigger laufen ebenfalls.
VersionierungEine veröffentlichte Version änderst du nicht mehr inkompatibel. Für Brüche legst du eine zweite Page mit APIVersion = 'v2.0' an und lässt die alte bestehen.

Adressen

// Online
https://api.businesscentral.dynamics.com/v2.0/{TenantId}/{Umgebung}/api/meinefirma/kundenapp/v1.0/companies({CompanyId})/customerVisits

// Docker (OData-Port des Containers, Standard 7048)
http://bcdev:7048/BC/api/meinefirma/kundenapp/v1.0/companies({CompanyId})/customerVisits

// Liste der Mandanten mit ihren IDs
.../api/v2.0/companies

Die wichtigsten Aufrufe

ZweckAufruf
Alle lesenGET .../customerVisits
Einen lesenGET .../customerVisits({id})
FilternGET .../customerVisits?$filter=customerNumber eq '10000' and visitDate ge 2026-01-01
Spalten wählen, sortieren, begrenzen?$select=id,visitDate&$orderby=visitDate desc&$top=20
Nur Änderungen seit Zeitpunkt?$filter=lastModifiedDateTime gt 2026-11-01T00:00:00Z
AnlegenPOST .../customerVisits mit JSON im Body
ÄndernPATCH .../customerVisits({id}) mit Header If-Match: {etag} (oder *)
LöschenDELETE .../customerVisits({id})
POST .../customerVisits
Content-Type: application/json

{
  "customerNumber": "10000",
  "visitDate": "2026-11-14",
  "visitType": "Phone",
  "description": "Rückruf wegen Angebot"
}

Der Wert "Phone" muss einem Wert deines Enums "ABC Visit Type" entsprechen. Der @odata.etag aus der Antwort ist die Versionsmarke des Datensatzes. Schickst du beim PATCH einen veralteten Wert, lehnt der Server ab – das ist der bekannte Fehler „Ein anderer Benutzer hat den Datensatz geändert“ in Schnittstellenform.

Unterseiten: Kopf und Zeilen in einem Aufruf

// In einer API-Page für Debitoren:
part(customerVisits; "ABC Visits API")
{
    Caption = 'customerVisits', Locked = true;
    EntityName = 'customerVisit';
    EntitySetName = 'customerVisits';
    SubPageLink = "Customer No." = field("No.");
}

Damit funktioniert GET .../abcCustomers?$expand=customerVisits, und sogenannte Deep Inserts (Kopf samt Zeilen in einem POST) sind möglich.

Gebundene Aktionen: Funktionen statt Daten

[ServiceEnabled]
procedure setVisitDateToToday(var ActionContext: WebServiceActionContext)
begin
    Rec.Validate("Visit Date", Today());
    Rec.Modify(true);

    ActionContext.SetObjectType(ObjectType::Page);
    ActionContext.SetObjectId(Page::"ABC Visits API");
    ActionContext.AddEntityKey(Rec.FieldNo(SystemId), Rec.SystemId);
    ActionContext.SetResultCode(WebServiceActionResultCode::Updated);
end;

Aufruf: POST .../customerVisits({id})/Microsoft.NAV.setVisitDateToToday. So bildest du Vorgänge wie „Buchen“, „Freigeben“ oder „Stornieren“ ab, für die du früher eine SOAP-Codeunit veröffentlicht hast.

API-Query

query 50101 "ABC Visit Statistics API"
{
    QueryType = API;
    APIPublisher = 'meinefirma';
    APIGroup = 'kundenapp';
    APIVersion = 'v1.0';
    EntityName = 'visitStatistic';
    EntitySetName = 'visitStatistics';
    DataAccessIntent = ReadOnly;

    elements
    {
        dataitem(Visit; "ABC Customer Visit")
        {
            column(customerNumber; "Customer No.") { }
            column(visitCount) { Method = Count; }
        }
    }
}

API-Queries sind nur lesend und ideal für Power BI oder andere Auswertungen, weil die Aggregation auf dem SQL Server passiert und die Abfrage auf der Lesereplik laufen kann.

Leistung und Grenzen

Die Cloud begrenzt Schnittstellenaufrufe: Es gibt eine maximale Seitengröße (der Server liefert dann @odata.nextLink zum Weiterblättern), Zeitlimits pro Anfrage und Grenzen für gleichzeitige Anfragen und Anfragen pro Zeitraum; bei Überschreitung kommt Status 429. Aufrufer sollten deshalb mit $select und $filter sparsam abfragen, Änderungen über lastModifiedDateTime abholen statt alles neu zu laden, bei 429 mit Wartezeit wiederholen und für Massenänderungen $batch nutzen. Für Benachrichtigungen ohne ständiges Abfragen gibt es Webhooks (subscriptions). Die genauen Grenzwerte ändern sich gelegentlich, sie stehen in der Microsoft-Dokumentation unter „Operational limits“.

16Anmeldung von außen

NAV 2017: Windows-Anmeldung oder Benutzername plus Web Service Access Key (Basic Authentication).

In Business Central Online ist Basic Authentication mit Web Service Access Key seit dem 1. Oktober 2022 abgeschaltet. Es bleibt OAuth 2.0 über Microsoft Entra ID (früher Azure AD). On-Premises bleibt der Zugriffsschlüssel vorerst möglich, und im Docker-Container kannst du zum Entwickeln mit Benutzername und Kennwort arbeiten. Teste die Schnittstelle aber vor der Auslieferung mit OAuth.

SzenarioVerfahrenEinrichtung
Programm ohne Benutzer (Dienst, Schnittstelle, Nachtlauf)Client Credentials („Service-to-Service“)App-Registrierung in Entra ID mit Anwendungsberechtigung API.ReadWrite.All für Dynamics 365 Business Central und Administratorzustimmung; in Business Central auf der Seite „Microsoft Entra-Anwendungen“ die Client-ID eintragen, aktivieren und Berechtigungssätze zuweisen
Programm im Namen eines angemeldeten BenutzersAuthorization Code FlowApp-Registrierung mit delegierter Berechtigung Financials.ReadWrite.All; es gelten die Rechte des Benutzers
// Token holen (Client Credentials)
POST https://login.microsoftonline.com/{TenantId}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={ClientId}
&client_secret={Secret}
&scope=https://api.businesscentral.dynamics.com/.default

// Danach jeder API-Aufruf mit Header:
Authorization: Bearer {access_token}

Zum Ausprobieren eignen sich die VS-Code-Erweiterung „REST Client“ (Aufrufe als .http-Datei im Repository, praktisch auch als Dokumentation), Postman oder Bruno. Die Entra-Anwendung bekommt in Business Central genau die Berechtigungssätze, die sie braucht, nicht SUPER. Wie du einen passenden Berechtigungssatz baust, ist Thema von Seite 8.

17Excel, Datenanalyse, Konfigurationspakete

Excel aus Code

Die temporäre Tabelle „Excel Buffer“ gibt es weiterhin, sie arbeitet in der Cloud über Streams statt über Dateien und Automation. Das Muster ist geblieben: Zeilen mit NewRow und AddColumn füllen, dann Arbeitsmappe erzeugen und herunterladen. Die genauen Prozedurnamen haben sich über die Versionen leicht verändert; schau mit F12 in die Tabelle. Für reine Auswertungen ist ein Bericht mit Excel-Layout meist die bessere Wahl, weil der Kunde das Ergebnis selbst gestalten kann.

Was der Anwender heute selbst kann

Einiges, wofür du in NAV 2017 Berichte geschrieben hast, braucht keinen Entwickler mehr. Auf jeder Liste gibt es „In Excel öffnen“ und „In Excel bearbeiten“ (mit Zurückschreiben), und der Analysemodus macht aus jeder Liste und jeder Query eine Pivot-Auswertung im Browser. Dazu kommen Power BI mit fertigen Konnektoren auf die APIs. Frage bei jeder Berichtsanforderung zuerst, ob eine gut gebaute Liste oder Query mit Analysemodus genügt.

Konfigurationspakete (RapidStart)

Für Datenübernahmen und Einrichtungsdaten gibt es weiterhin Konfigurationspakete: Tabellen auswählen, nach Excel exportieren, füllen, importieren, mit Validierung anwenden. Deine eigenen Tabellen und Erweiterungsfelder lassen sich dort genauso aufnehmen. Für große Datenmengen sind sie langsam; dann sind APIs oder ein eigener Import (Seite 6) besser. Für die Übernahme eines ganzen NAV-2017-Bestands in die Cloud gibt es das Cloud-Migrationswerkzeug; das ist ein eigenes Projekt und folgt auf Seite 10 im Überblick.

18Übung: Auswertung und Schnittstelle für die Besuchsverwaltung

Die Besuchsverwaltung aus den Seiten 3 bis 6 bekommt einen Bericht mit zwei Layouts, eine Query, einen XML-Export und eine API. Lege im Projekt den Ordner src/layouts an.

Schritt 1 – Bericht src/ABCCustomerVisits.Report.al

report 50100 "ABC Customer Visits"
{
    Caption = 'Customer Visits';
    UsageCategory = ReportsAndAnalysis;
    ApplicationArea = All;
    DefaultRenderingLayout = ExcelLayout;
    DataAccessIntent = ReadOnly;

    dataset
    {
        dataitem(Customer; Customer)
        {
            RequestFilterFields = "No.", "ABC Kundenklasse";
            PrintOnlyIfDetail = true;

            column(CustomerNo; "No.") { IncludeCaption = true; }
            column(CustomerName; Name) { IncludeCaption = true; }
            column(CustomerClass; "ABC Kundenklasse") { IncludeCaption = true; }
            column(CompanyName; CompanyProperty.DisplayName()) { }
            column(FilterText; FilterText) { }

            dataitem(Visit; "ABC Customer Visit")
            {
                DataItemLink = "Customer No." = field("No.");
                DataItemTableView = sorting("Entry No.");

                column(EntryNo; "Entry No.") { }
                column(VisitDate; "Visit Date") { IncludeCaption = true; }
                column(VisitType; "Visit Type") { IncludeCaption = true; }
                column(VisitDescription; Description) { IncludeCaption = true; }

                trigger OnPreDataItem()
                begin
                    if (FromDate <> 0D) or (ToDate <> 0D) then
                        Visit.SetFilter("Visit Date", '%1..%2', FromDate, ToDate);
                end;
            }
        }
    }

    requestpage
    {
        SaveValues = true;

        layout
        {
            area(Content)
            {
                group(Options)
                {
                    Caption = 'Options';

                    field(FromDateCtrl; FromDate)
                    {
                        ApplicationArea = All;
                        Caption = 'From Date';
                        ToolTip = 'Specifies the first visit date to include.';
                    }
                    field(ToDateCtrl; ToDate)
                    {
                        ApplicationArea = All;
                        Caption = 'To Date';
                        ToolTip = 'Specifies the last visit date to include.';
                    }
                }
            }
        }
    }

    rendering
    {
        layout(ExcelLayout)
        {
            Type = Excel;
            LayoutFile = './src/layouts/ABCCustomerVisits.xlsx';
            Caption = 'Customer Visits (Excel)';
            Summary = 'Raw data for pivot analysis.';
        }
        layout(RdlcLayout)
        {
            Type = RDLC;
            LayoutFile = './src/layouts/ABCCustomerVisits.rdl';
            Caption = 'Customer Visits (Print)';
            Summary = 'Printable list grouped by customer.';
        }
    }

    labels
    {
        ReportTitle = 'Customer Visits';
        PageCaption = 'Page';
    }

    trigger OnPreReport()
    begin
        if (ToDate <> 0D) and (FromDate > ToDate) then
            Error(DateOrderErr);
        FilterText := Customer.GetFilters();
    end;

    var
        FromDate: Date;
        ToDate: Date;
        FilterText: Text;
        DateOrderErr: Label 'The from date must not be later than the to date.';
}

Schritt 2 – Layouts erzeugen und gestalten

Baue mit Strg+Umschalt+B. Im Ordner src/layouts liegen danach eine .xlsx- und eine .rdl-Datei. Veröffentliche mit F5, suche „Customer Visits“ und führe den Bericht mit dem Excel-Layout aus. Du bekommst das Datenblatt mit allen Spalten. Füge in der heruntergeladenen Datei ein Blatt mit einer Pivot-Tabelle hinzu (Zeilen: CustomerName, Spalten: VisitType, Werte: Anzahl von EntryNo), speichere sie unter dem Namen der Layoutdatei in src/layouts und veröffentliche erneut. Der Bericht liefert jetzt die fertige Auswertung.

Für das RDLC-Layout öffnest du die .rdl-Datei im Report Builder, fügst eine Tabelle ein, gruppierst nach CustomerNo und ziehst die Besuchsfelder in die Detailzeile. Das Druckbild darf für diese Übung schlicht bleiben.

Schritt 3 – Report Extension src/ABCCustomerListExt.ReportExt.al

Übernimm die reportextension 50100 aus Abschnitt 8, zunächst nur mit dem add(Customer)-Block und dem Excel-Layout. Kontrolliere vorher mit F12 auf "Customer - List", dass der Bericht in deiner Version so heißt und das DataItem Customer heißt.

Schritt 4 – Query src/ABCVisitsPerCustomer.Query.al

Übernimm die Query aus Abschnitt 12 und die Prozedur ShowTopCustomers in eine neue codeunit 50111 "ABC Visit Statistics". Ergänze auf der Besuchsliste eine Aktion:

action(TopCustomers)
{
    ApplicationArea = All;
    Caption = 'Top Customers';
    ToolTip = 'Shows the five customers with the most visits in the last year.';
    Image = Statistics;

    trigger OnAction()
    var
        VisitStatistics: Codeunit "ABC Visit Statistics";
    begin
        VisitStatistics.ShowTopCustomers();
    end;
}

Schritt 5 – XMLport src/ABCVisitExport.XmlPort.al

Übernimm den XMLport aus Abschnitt 13. Da codeunit 50107 "ABC Visit Export" von Seite 6 den JSON-Export schon enthält, ergänze dort die Prozedur ExportVisitsXml und auf der Besuchsliste eine Aktion „Export XML“. Vergleiche danach beide Exporte: Der XMLport braucht für dieselbe Aufgabe deutlich weniger Code, ist dafür aber an die Tabellenstruktur gebunden.

Schritt 6 – API-Page src/ABCVisitsAPI.Page.al

Übernimm die Page aus Abschnitt 15. Lege im Repository eine Datei api-tests.http an (Erweiterung „REST Client“):

@base = http://bcdev:7048/BC/api
@auth = Basic admin:DeinKennwort

### Mandanten auflisten – id für die nächsten Aufrufe kopieren
GET {{base}}/v2.0/companies
Authorization: {{auth}}

### Besuche lesen
@company = HIER-DIE-COMPANY-ID
GET {{base}}/meinefirma/kundenapp/v1.0/companies({{company}})/customerVisits?$top=5
Authorization: {{auth}}

### Besuch anlegen
POST {{base}}/meinefirma/kundenapp/v1.0/companies({{company}})/customerVisits
Authorization: {{auth}}
Content-Type: application/json

{
  "customerNumber": "10000",
  "visitDate": "2026-11-14",
  "description": "Angelegt über die API"
}

Die Basic-Anmeldung funktioniert nur im Docker-Container. Gegen die Online-Sandbox holst du zuerst ein Token wie in Abschnitt 16 und sendest Authorization: Bearer .... Lege echte Kennwörter und Secrets nie im Repository ab; der REST Client kann sie aus Umgebungsvariablen oder einer nicht eingecheckten Einstellungsdatei lesen.

Schritt 7 – Prüfen

Öffne den angelegten Besuch in der Besuchsliste. Kontrolliere, ob die Logik aus dem OnInsert-Trigger der Tabelle (Seite 3) gelaufen ist, also ob zum Beispiel „ABC Letzter Besuch“ am Debitor aktualisiert wurde. Sende danach einen POST mit einer nicht vorhandenen Debitorennummer und sieh dir die Fehlermeldung im JSON an: Deine TableRelation und deine Prüfungen schützen die Daten auch über die Schnittstelle.

Schritt 8 – Übersetzen und einchecken

Englisch (Quelle)Deutsch (Ziel)
Customer VisitsKundenbesuche
OptionsOptionen
From DateVon Datum
To DateBis Datum
Customer Visits (Excel)Kundenbesuche (Excel)
Customer Visits (Print)Kundenbesuche (Druck)
Top CustomersTop-Kunden
Visits per CustomerBesuche pro Kunde
The from date must not be later than the to date.Das Von-Datum darf nicht nach dem Bis-Datum liegen.
git add .
git commit -m "Bericht, Query, XMLport und API fuer Kundenbesuche"
git push

Die Layoutdateien (.rdl, .xlsx, .docx) gehören ins Repository. Bei .xlsx und .docx zeigt Git keine lesbaren Unterschiede; schreibe deshalb in die Commit-Nachricht, was du am Layout geändert hast.

19Typische Fallen

FalleWas passiertAbhilfe
Spalte im Bericht umbenanntLayouts zeigen Fehler oder leere Felder, Kundenlayouts brechenSpaltennamen als Schnittstelle behandeln; lieber neue Spalte ergänzen
Spalte per Report Extension ergänzt, aber nichts zu sehenDas Standardlayout kennt die Spalte nichtEigenes Layout mitliefern und als Standard wählen
Felder im DataItem-Trigger ohne QualifizierungCompilerfehler oder WarnungCustomer.Name statt Name
Report.Run in der AufgabenwarteschlangeFehler wegen fehlender OberflächeSaveAs, Execute oder Print mit Parametern
SaveValues beim Testen vergessenAlte Eingaben überschreiben neue VorbelegungVorbelegung nur bei leeren Werten; beim Test Einstellungen zurücksetzen
Bild in jeder Dataset-Zeile (Firmenlogo)Bericht wird langsam und großLogo in eigenem DataItem über Integer mit einem Durchlauf
Verschachtelte Schleifen statt QueryLange Laufzeiten, Zeitüberschreitung in der CloudQuery mit Join und Aggregation
Microsoft-Page als SOAP- oder OData-Webdienst für eine IntegrationSOAP ist seit Version 26 gesperrt und entfällt; OData auf Microsoft-Pages entfällt mit Version 30. Die Schnittstelle fällt beim Update aus.Standard-API (v2.0) oder eigene API-Page
Eigene UI-Page als OData-WebdienstSchnittstelle bricht bei jeder Page-Änderung, langsamEigene API-Page mit Version
Alte NAV-Schnittstellen ungeprüft in die Migration übernommenDer Schnittstellenpartner steht am Stichtag ohne Verbindung daAlle Einträge der Tabelle „Webdienste“ im Altsystem auflisten und je Eintrag den Ersatz festlegen
API-Feldnamen mit Unterstrich oder Großbuchstaben am AnfangCompilerfehlercamelCase, nur Buchstaben und Ziffern
API-Version nachträglich geändertFremde Programme bekommen plötzlich FehlerNeue Version als zweite Page
Schnittstelle mit Benutzer und Web Service Access Key geplantFunktioniert in der Cloud nichtOAuth mit Entra-Anwendung
Entra-Anwendung mit SUPERSchnittstelle darf alles, auch löschenEigener, knapper Berechtigungssatz (Seite 8)
XMLport mit DateinameKein Dateisystem in der CloudXmlport.Import/Export mit Streams

20Selbsttest und Zusammenfassung

Selbsttest

  1. Welche vier Blöcke kann ein Bericht in AL enthalten, und welcher davon ist gegenüber NAV 2017 neu?
  2. Du fügst per Report Extension eine Spalte zum Bericht „Customer - List“ hinzu. Warum erscheint sie nicht auf dem Ausdruck, und was musst du tun?
  3. Wie erzeugst du in der Cloud ein PDF eines Berichts und hängst es an eine E-Mail, ohne eine Datei zu schreiben?
  4. Nenne zwei Wege, einen Standardbericht durch deinen eigenen zu ersetzen, und sage, wofür welcher passt.
  5. Warum ist eine Query bei einer Auswertung über Debitoren und Posten schneller als zwei verschachtelte Schleifen?
  6. Welche Eigenschaften machen eine Page zur API-Page, und warum ist SystemId der Schlüssel?
  7. Wie meldet sich ein Nachtlauf-Programm in Business Central Online an?
  8. Wann nimmst du einen XMLport, wann XmlDocument, wann JsonObject?
  9. Ein Kunde hat in NAV 2017 die Debitorenkarte als Webdienst veröffentlicht und liest sie aus einem Fremdsystem. Was rätst du ihm für Business Central?
Lösungen anzeigen
  1. dataset, requestpage, rendering, labels. Neu ist rendering mit beliebig vielen Layouts als Dateien.
  2. Die Spalte steht nur im Dataset. Sichtbar wird sie erst in einem Layout, das sie verwendet: eigenes Layout mitliefern (oder Kundenlayout anpassen) und als Standard auswählen.
  3. Report.SaveAs(..., ReportFormat::Pdf, OutStr) in den OutStream eines „Temp Blob“, daraus einen InStream erzeugen und an EmailMessage.AddAttachment übergeben.
  4. Berichtsauswahl (Einrichtung, für Belege) und Subscriber auf OnAfterSubstituteReport in Codeunit ReportManagement (für fest verdrahtete Listen). Dritter Weg: eigene Aktion per Page Extension.
  5. Die Query wird zu einer einzigen SQL-Abfrage mit Join und Aggregation auf dem Server; die Schleifen erzeugen pro Debitor eigene Abfragen und übertragen alle Zeilen.
  6. PageType = API mit APIPublisher, APIGroup, APIVersion, EntityName, EntitySetName, dazu ODataKeyFields = SystemId und DelayedInsert = true. SystemId ist eindeutig und bleibt beim Umbenennen des Primärschlüssels gleich.
  7. Mit OAuth 2.0 Client Credentials: App-Registrierung in Entra ID, in Business Central als Entra-Anwendung mit Berechtigungssätzen eingetragen, Token holen und als Bearer-Header senden.
  8. XMLport für tabellennahe XML- und Textdateien (CSV, feste Breite); XmlDocument für XML mit Namensräumen oder wechselnder Struktur; JsonObject für JSON.
  9. Die Debitorenkarte ist eine Microsoft-Page; sie lässt sich als SOAP-Dienst nicht mehr und als OData-Dienst ab Version 30 nicht mehr veröffentlichen. Zuerst die Standard-API customers (v2.0) prüfen; fehlen Felder, eine eigene API-Page bauen. Die Anmeldung wechselt auf OAuth.

Zusammenfassung

Dein Berichtswissen aus NAV 2017 bleibt gültig, es wandert nur in Textdateien. Layouts sind eigene Dateien im Repository, Excel ist als dritter und oft bester Typ dazugekommen, und der Kunde verwaltet seine Layouts selbst. Standardberichte erweiterst du mit reportextension und ersetzt sie nur im Notfall. Ausgaben entstehen in Streams statt in Dateien. Queries ersetzen den verlorenen SQL-Zugriff für Auswertungen. XMLports arbeiten über Streams. Nach außen sprichst du über versionierte API-Pages und API-Queries mit OAuth. SOAP ist abgekündigt, und Microsoft-Pages als Webdienst haben ein festes Ablaufdatum.

Weiter mit Seite 8: Berechtigungssätze als AL-Objekte, Entitlements, Install- und Upgrade-Codeunits, Datenumzug zwischen App-Versionen.

SOAP und OData im Einsatz?Wir prüfen eure Schnittstellen und stellen sie auf API-Pages um.

Erstgespräch vereinbaren

Fehler gefunden? Bitte melden. Wir prüfen jede Meldung.