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.
| Thema | NAV 2017 | Business Central (AL) |
|---|---|---|
| Berichtsdefinition | Report Dataset Designer in C/SIDE | Textdatei *.Report.al mit dataset, requestpage, rendering, labels |
| RDLC-Layout | Im Objekt eingebettet, Bearbeitung über „View → Layout“ mit Visual Studio oder Report Builder | Eigene .rdl-Datei im Projektordner, Bearbeitung mit Microsoft Report Builder oder Visual Studio |
| Word-Layout | Eingebettet, eigene Layouts über „Custom Report Layouts“ | Eigene .docx-Datei im Projekt, Kundenlayouts über Seite „Berichtslayouts“ |
| Excel-Layout | Nicht vorhanden | .xlsx-Datei mit Datenblatt, Auswertung per Pivot/Formeln (ab 2022 Wave 1) |
| Mehrere Layouts | Je ein eingebautes RDLC- und Word-Layout | Beliebig viele im Abschnitt rendering |
| Standardbericht ändern | Objekt ändern oder in 50000er-Bereich kopieren | reportextension oder Ersatz per Event |
| PDF auf Server speichern | REPORT.SAVEASPDF(Nr, Dateiname) | Report.SaveAs(...) in einen OutStream |
| Menüeintrag | MenuSuite | UsageCategory und ApplicationArea am Bericht |
| Query | Query Designer | Textdatei *.Query.al, zusätzlich QueryType = API |
| XMLport | XMLport Designer, Dateiname auf Server oder Client | Textdatei *.XmlPort.al, Ausführung über Streams |
| Webdienste | Page/Codeunit/Query als SOAP und OData veröffentlichen | Eigene 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ßen | Windows, NavUserPassword, Web Service Access Key | In 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;
}
dataset entspricht dem Report Dataset Designer, requestpage dem Request Page Designer, labels dem Report Label Designer. Nur rendering ist wirklich neu.
3Berichtseigenschaften
| Eigenschaft | Bedeutung |
|---|---|
Caption | Anzeigename, Englisch im Code, Deutsch über XLIFF. |
UsageCategory | Macht den Bericht in der Suche (Alt+Q) auffindbar. Üblich: ReportsAndAnalysis, für Stapelverarbeitungen Tasks, für Belege Documents. |
ApplicationArea | Wie bei Pages; ohne sie bleibt der Bericht in der Suche unsichtbar. |
DefaultRenderingLayout | Name des Standardlayouts aus dem Abschnitt rendering. |
ProcessingOnly | true für Stapelverarbeitungen ohne Ausdruck (Abschnitt 11). |
UseRequestPage | false unterdrückt die Anforderungsseite. |
AllowScheduling | Steuert, ob Anwender den Bericht über „Senden an → Planen“ in die Aufgabenwarteschlange stellen dürfen. |
PreviewMode | Normal oder PrintLayout für die RDLC-Vorschau. |
EnableHyperlinks, EnableExternalImages | RDLC-Schalter wie in NAV 2017. |
WordMergeDataItem | DataItem, pro dessen Datensatz ein eigenes Word-Dokument entsteht (Belegberichte). |
DataAccessIntent | ReadOnly lässt den Bericht in der Cloud auf einer Lesereplik der Datenbank laufen. Sinnvoll für große Auswertungen, die nichts schreiben. |
Permissions | Zusätzliche Tabellenrechte für den Bericht, z. B. tabledata "Cust. Ledger Entry" = r. |
TransactionType | Wie früher, selten nötig. |
AdditionalSearchTerms | Weitere Suchbegriffe für Alt+Q. |
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.
| Eigenschaft | Bedeutung |
|---|---|
DataItemTableView | Feste Sortierung und Filter: sorting("No.") where(Blocked = const(" ")). Mit sorting verschwindet die Sortierauswahl auf der Anforderungsseite. |
DataItemLink | Verknüpfung zum übergeordneten DataItem: "Customer No." = field("No."). |
DataItemLinkReference | Nennt das DataItem, auf das sich der Link bezieht, falls es nicht das direkt übergeordnete ist. |
RequestFilterFields | Vorgeschlagene Filterfelder auf der Anforderungsseite. |
RequestFilterHeading | Überschrift des Filterblocks. |
PrintOnlyIfDetail | Übergeordneten Satz nur ausgeben, wenn es untergeordnete Sätze gibt. |
CalcFields | FlowFields, die automatisch berechnet werden. |
MaxIteration | Begrenzt die Durchläufe, typisch bei der Tabelle Integer. |
UseTemporary | DataItem 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
| Ebene | Trigger | Typische Verwendung |
|---|---|---|
| Bericht | OnInitReport | Vorbelegung, bevor die Anforderungsseite erscheint |
| Bericht | OnPreReport | Prüfung der Optionen, Filtertexte merken |
| Bericht | OnPostReport | Abschlussmeldung |
| DataItem | OnPreDataItem | Zusätzliche Filter setzen |
| DataItem | OnAfterGetRecord | Berechnungen pro Datensatz, CurrReport.Skip() |
| DataItem | OnPostDataItem | Aufrä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;
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.';
}
}
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?
| Typ | Stärken | Schwächen | Einsatz |
|---|---|---|---|
| RDLC | Volle Kontrolle: Gruppierung, Summen, Ausdrücke, bedingte Sichtbarkeit, Seitenkopf | Sperriges Werkzeug, Anwender können es praktisch nicht selbst ändern | Komplexe Listen, Belege mit viel Logik |
| Word | Anwender können das Layout selbst anpassen, gut für Logo und Briefkopf | Keine Berechnungen im Layout, Gruppierung eingeschränkt | Belege (Rechnung, Angebot), Anschreiben |
| Excel | Anwender werten mit Pivot, Diagrammen und Formeln selbst aus | Kein seitengenaues Druckbild | Auswertungen, 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).
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.
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öglich | Nicht 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 |
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.
| Weg | Wirkung | Geeignet für |
|---|---|---|
| Berichtsauswahl | Reine Einrichtung, kein Code | Belege (Rechnung, Lieferschein, Mahnung …) |
Event OnAfterSubstituteReport | Tauscht die Berichts-ID überall, wo der Bericht aus der Oberfläche oder per Report.Run gestartet wird | Listen und Auswertungen, die fest im Standard verdrahtet sind |
| Aktion per Page Extension | Standardaktion ausblenden, eigene Aktion einfügen | Einzelne 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;
}
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
| Aufruf | Bedeutung |
|---|---|
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;
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;
}
}
}
}
}
| Element | Bedeutung |
|---|---|
column ohne Method | Gruppierungsspalte (SQL GROUP BY), sobald irgendwo aggregiert wird |
Method | Sum, Count, Average, Min, Max; für Datumsfelder auch Day, Month, Year |
filter | Feld, das nur gefiltert, aber nicht ausgegeben wird |
SqlJoinType | InnerJoin, LeftOuterJoin (Standard), RightOuterJoin, FullOuterJoin, CrossJoin |
DataItemTableFilter | Fester Filter auf dem DataItem |
ColumnFilter | Fester Filter auf einer Spalte, auch auf aggregierten Werten (SQL HAVING) |
TopNumberOfRows | Begrenzung 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;
}
}
}
}
}
| Knotentyp | NAV 2017 (Node Type / Source Type) | AL |
|---|---|---|
| Element aus Text | Element / Text | textelement(Name) |
| Element aus Tabelle | Element / Table | tableelement(Name; Tabelle) |
| Element aus Feld | Element / Field | fieldelement(Name; Variable.Feld) |
| Attribut aus Text | Attribute / Text | textattribute(Name) |
| Attribut aus Feld | Attribute / Field | fieldattribute(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?
| Aufgabe | Empfehlung |
|---|---|
| CSV mit Anführungszeichen, Trennzeichen im Text, vielen Spalten | XMLport mit Format = VariableText (FieldSeparator, FieldDelimiter, TableSeparator) |
| Datei mit festen Spaltenbreiten | XMLport mit Format = FixedText und Width je Feld |
| XML mit fester, tabellennaher Struktur | XMLport |
| XML mit Namensräumen, wechselnder Struktur, tiefer Verschachtelung | XmlDocument im Code (Seite 6) |
| JSON | Immer Code mit JsonObject (Seite 6), XMLports können kein JSON |
| Bankformate, Zahlungsdateien | Zuerst 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.
| Technik | Stand | Bewertung |
|---|---|---|
| SOAP allgemein (Page, Codeunit) | Seit 2021 Release Wave 1 abgekündigt; soll laut Microsoft in einer kommenden Version entfernt werden | Nicht 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-Pages | Funktioniert noch; ab Version 30 (2027 Release Wave 1) lassen sich Microsoft-Pages nicht mehr als OData-Endpunkt bereitstellen | Nicht 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) | Funktioniert | Mö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 Queries | Funktioniert | Gut für lesende Auswertungen, etwa Power BI. |
| OData V4 „ungebundene Aktionen“ auf Codeunits | Funktioniert | Ersatz für SOAP-Codeunits, wenn du eine Funktion statt Daten anbieten willst. |
| Standard-APIs (v2.0) | Von Microsoft gepflegt | Erste Wahl für Standarddaten: customers, items, salesOrders, salesInvoices … |
| Eigene API-Pages und API-Queries | Empfohlen | Versioniert, stabil, schnell – der Weg für alles Eigene und auf Dauer der einzige verlässliche. |
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 / Regel | Erklärung |
|---|---|
APIPublisher, APIGroup, APIVersion | Bilden den Pfad der URL. Nur Kleinbuchstaben und Ziffern, keine Leerzeichen. Version im Format v1.0, auch beta ist erlaubt. |
EntityName, EntitySetName | Einzahl und Mehrzahl in camelCase. Der Mehrzahlname steht in der URL. |
ODataKeyFields = SystemId | Die 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 = true | Pflicht bei API-Pages: Der Datensatz wird erst eingefügt, wenn alle Felder der Anfrage gesetzt sind. |
| Feldnamen | camelCase, nur Buchstaben und Ziffern. Der Name vor dem Semikolon ist der JSON-Name. |
| Captions | Locked = true, damit sie nicht in die Übersetzung wandern. |
Kein ApplicationArea, keine Aktionen | API-Pages haben keine Oberfläche. |
| Enums | Werden als Text mit dem Namen des Enum-Werts übertragen, Sonderzeichen werden kodiert. Halte Enum-Namen deshalb schlicht. |
| Trigger | OnInsertRecord, OnModifyRecord, OnDeleteRecord und Feldtrigger laufen wie auf normalen Pages; die Tabellentrigger laufen ebenfalls. |
| Versionierung | Eine 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
| Zweck | Aufruf |
|---|---|
| Alle lesen | GET .../customerVisits |
| Einen lesen | GET .../customerVisits({id}) |
| Filtern | GET .../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 |
| Anlegen | POST .../customerVisits mit JSON im Body |
| Ändern | PATCH .../customerVisits({id}) mit Header If-Match: {etag} (oder *) |
| Löschen | DELETE .../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
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.
| Szenario | Verfahren | Einrichtung |
|---|---|---|
| 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 Benutzers | Authorization Code Flow | App-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 Visits | Kundenbesuche |
| Options | Optionen |
| From Date | Von Datum |
| To Date | Bis Datum |
| Customer Visits (Excel) | Kundenbesuche (Excel) |
| Customer Visits (Print) | Kundenbesuche (Druck) |
| Top Customers | Top-Kunden |
| Visits per Customer | Besuche 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
| Falle | Was passiert | Abhilfe |
|---|---|---|
| Spalte im Bericht umbenannt | Layouts zeigen Fehler oder leere Felder, Kundenlayouts brechen | Spaltennamen als Schnittstelle behandeln; lieber neue Spalte ergänzen |
| Spalte per Report Extension ergänzt, aber nichts zu sehen | Das Standardlayout kennt die Spalte nicht | Eigenes Layout mitliefern und als Standard wählen |
| Felder im DataItem-Trigger ohne Qualifizierung | Compilerfehler oder Warnung | Customer.Name statt Name |
Report.Run in der Aufgabenwarteschlange | Fehler wegen fehlender Oberfläche | SaveAs, Execute oder Print mit Parametern |
SaveValues beim Testen vergessen | Alte Eingaben überschreiben neue Vorbelegung | Vorbelegung 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 Query | Lange Laufzeiten, Zeitüberschreitung in der Cloud | Query mit Join und Aggregation |
| Microsoft-Page als SOAP- oder OData-Webdienst für eine Integration | SOAP 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-Webdienst | Schnittstelle bricht bei jeder Page-Änderung, langsam | Eigene API-Page mit Version |
| Alte NAV-Schnittstellen ungeprüft in die Migration übernommen | Der Schnittstellenpartner steht am Stichtag ohne Verbindung da | Alle Einträge der Tabelle „Webdienste“ im Altsystem auflisten und je Eintrag den Ersatz festlegen |
| API-Feldnamen mit Unterstrich oder Großbuchstaben am Anfang | Compilerfehler | camelCase, nur Buchstaben und Ziffern |
| API-Version nachträglich geändert | Fremde Programme bekommen plötzlich Fehler | Neue Version als zweite Page |
| Schnittstelle mit Benutzer und Web Service Access Key geplant | Funktioniert in der Cloud nicht | OAuth mit Entra-Anwendung |
Entra-Anwendung mit SUPER | Schnittstelle darf alles, auch löschen | Eigener, knapper Berechtigungssatz (Seite 8) |
| XMLport mit Dateiname | Kein Dateisystem in der Cloud | Xmlport.Import/Export mit Streams |
20Selbsttest und Zusammenfassung
Selbsttest
- Welche vier Blöcke kann ein Bericht in AL enthalten, und welcher davon ist gegenüber NAV 2017 neu?
- 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?
- Wie erzeugst du in der Cloud ein PDF eines Berichts und hängst es an eine E-Mail, ohne eine Datei zu schreiben?
- Nenne zwei Wege, einen Standardbericht durch deinen eigenen zu ersetzen, und sage, wofür welcher passt.
- Warum ist eine Query bei einer Auswertung über Debitoren und Posten schneller als zwei verschachtelte Schleifen?
- Welche Eigenschaften machen eine Page zur API-Page, und warum ist
SystemIdder Schlüssel? - Wie meldet sich ein Nachtlauf-Programm in Business Central Online an?
- Wann nimmst du einen XMLport, wann
XmlDocument, wannJsonObject? - 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
dataset,requestpage,rendering,labels. Neu istrenderingmit beliebig vielen Layouts als Dateien.- 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.
Report.SaveAs(..., ReportFormat::Pdf, OutStr)in den OutStream eines „Temp Blob“, daraus einen InStream erzeugen und anEmailMessage.AddAttachmentübergeben.- Berichtsauswahl (Einrichtung, für Belege) und Subscriber auf
OnAfterSubstituteReportin CodeunitReportManagement(für fest verdrahtete Listen). Dritter Weg: eigene Aktion per Page Extension. - 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.
PageType = APImitAPIPublisher,APIGroup,APIVersion,EntityName,EntitySetName, dazuODataKeyFields = SystemIdundDelayedInsert = true.SystemIdist eindeutig und bleibt beim Umbenennen des Primärschlüssels gleich.- 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.
- XMLport für tabellennahe XML- und Textdateien (CSV, feste Breite);
XmlDocumentfür XML mit Namensräumen oder wechselnder Struktur;JsonObjectfür JSON. - 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.