Events vor dem Abholen und Anlegen von SQUEEZE-Belegen
Zielgruppe
Diese Dokumentation richtet sich an Drittanbieter-Entwickler, die steuern möchten, ob Business Central Belege aus SQUEEZE abholt – typischerweise, um das Abholen in einem Testsystem zu unterbinden.
Im Fokus stehen die beiden Integration Events in der Codeunit DXP SQZ API Mgt., die vor dem Abholen ausgelöst werden.
Die beiden Events sind ab SQUEEZE Version 2.54.0.0 verfügbar.
Hintergrund: Warum ein Testsystem keine Belege abholen sollte
Ist ein Testsystem mit derselben SQUEEZE-Instanz verbunden wie das Produktivsystem – etwa weil es als Kopie der Produktion angelegt wurde –, holt es dort ebenfalls Belege ab.
Beim Anlegen wird ein Beleg in SQUEEZE auf FINISHED gesetzt. Ein Beleg, den ein Testsystem abgeholt hat, steht dem Produktivsystem danach nicht mehr zur Verfügung.
Soll das Testsystem gar nicht mit SQUEEZE kommunizieren, geht das auch ohne Erweiterung, siehe Testsystem holt Belege aus Squeeze ab. Die Events sind für die Fälle gedacht, in denen das Testsystem das Abholen selbst erkennen und unterbinden soll oder nur bestimmte Belege zurückgehalten werden sollen.
Einordnung: Ablauf des Abholens
Das Abholen läuft in zwei Schritten, beide in der Codeunit DXP SQZ API Mgt.:
DownloadDocumentDataruft die IDs der Belege ab, die in SQUEEZE zum Export bereitstehen, und trägt sie in die Importwarteschlange ein. Außerdem ruft es Belege im Status „Neu erstellen“ (Resynchronize) erneut ab.CreateCoreAndSQUEEZEDocumentruft für jeden offenen Eintrag der Importwarteschlange den Beleg ab, legt den Core-Beleg (DXP Document) und den SQUEEZE-Beleg an, markiert den Eintrag als verarbeitet und setzt den Beleg in SQUEEZE aufFINISHED.
Beide Schritte laufen in der Aufgabenwarteschlange und bei der Aktion Belege jetzt herunterladen auf den Seiten Squeeze Belege, Squeeze Importwarteschlange und Squeeze Warteschlange. Vor jedem der beiden Schritte wird ein Event mit IsHandled ausgelöst.
Event-Matrix (Kurzüberblick)
| Event | Zeitpunkt | Steuerung | Typische Use-Cases |
|---|---|---|---|
OnBeforeDownloadDocumentData |
vor dem Abruf der Beleg-IDs aus SQUEEZE | IsHandled |
Abholen im Testsystem vollständig |
OnBeforeCreateCoreAndSQUEEZEDocumentV2 |
vor dem Abruf und der Anlage eines einzelnen Belegs | IsHandled |
bereits eingereihte Belege nicht anlegen; einzelne Dokumentenklassen oder Belege zurückhalten |
Events in DXP SQZ API Mgt.
OnBeforeDownloadDocumentData
Wird ganz am Anfang von DownloadDocumentData ausgelöst, bevor eine Verbindung zu SQUEEZE aufgebaut wird.
Signatur:
[IntegrationEvent(false, false)]
local procedure OnBeforeDownloadDocumentData(var IsHandled: Boolean)
Mit IsHandled := true wird der gesamte Schritt übersprungen: Es werden keine Beleg-IDs abgerufen, keine Einträge in die Importwarteschlange geschrieben und keine Belege im Status „Neu erstellen“ erneut abgerufen.
Die Squeeze Einrichtung wird erst nach diesem Event gelesen. Ein Subscriber kann hier also auch die Verbindung auf eine SQUEEZE-Testinstanz umstellen, statt das Abholen zu unterbinden – siehe Abschnitt Testsystem mit einer SQUEEZE-Testinstanz verbinden weiter unten.
OnBeforeCreateCoreAndSQUEEZEDocumentV2
Wird in CreateCoreAndSQUEEZEDocument für jeden Beleg ausgelöst, bevor er aus SQUEEZE abgerufen wird.
Signatur:
[IntegrationEvent(false, false)]
local procedure OnBeforeCreateCoreAndSQUEEZEDocumentV2(DocClass: Enum "DXP Document Class"; SQUEEZEDocId: Text[50]; var IsHandled: Boolean)
Parameter:
DocClass– Dokumentenklasse des Belegs, z. B.DXP Invoice / Credit MemooderDXP Order ConfirmationSQUEEZEDocId– ID des Belegs in SQUEEZEIsHandled– auftruesetzen, um den Beleg zu überspringen
Mit IsHandled := true:
- wird weder ein Core-Beleg noch ein SQUEEZE-Beleg angelegt,
- bleibt der Beleg in SQUEEZE unverändert – er wird nicht auf
FINISHEDgesetzt, - bleibt der Eintrag in der Importwarteschlange unverarbeitet und wird beim nächsten Lauf erneut angeboten.
Um ein Testsystem vollständig abzuschirmen, braucht ihr dieses Event zusätzlich zu OnBeforeDownloadDocumentData: Eine Kopie des Produktivsystems bringt auch die Einträge mit, die dort bereits in der Importwarteschlange standen. Ohne dieses Event würden sie im Testsystem angelegt.
Übersprungene Einträge werden bei jedem Lauf erneut versucht und zählen dabei zu den bis zu 10 Einträgen, die ein Lauf verarbeitet. Haltet ihr nur einzelne Belege zurück, können diese Einträge die Verarbeitung der übrigen aufhalten.
Das ältere Event OnBeforeCreateCoreAndSQUEEZEDocument ist obsolet und wird nicht mehr ausgelöst. Verwendet stattdessen OnBeforeCreateCoreAndSQUEEZEDocumentV2.
Minimalbeispiel: Abholen in einer Sandbox unterbinden
Das Beispiel behandelt jede Sandbox als Testsystem. Passt Objekt-IDs/Namen an euren Namespace und die Prüfung in IsTestSystem an eure Regeln an.
codeunit 50102 "My SQZ Test System Guard"
{
[EventSubscriber(ObjectType::Codeunit, Codeunit::"DXP SQZ API Mgt.", 'OnBeforeDownloadDocumentData', '', false, false)]
local procedure SkipDownloadInTestSystem(var IsHandled: Boolean)
begin
if IsTestSystem() then
IsHandled := true;
end;
[EventSubscriber(ObjectType::Codeunit, Codeunit::"DXP SQZ API Mgt.", 'OnBeforeCreateCoreAndSQUEEZEDocumentV2', '', false, false)]
local procedure SkipCreationInTestSystem(DocClass: Enum "DXP Document Class"; SQUEEZEDocId: Text[50]; var IsHandled: Boolean)
begin
if IsTestSystem() then
IsHandled := true;
end;
local procedure IsTestSystem(): Boolean
var
EnvironmentInformation: Codeunit "Environment Information";
begin
// Beispiel: jede Sandbox gilt als Testsystem.
// On-Premises oder bei anderen Regeln eine eigene Prüfung einsetzen,
// z. B. einden Datenbanknamen aus der Tabelle "Active Session".
// Ein Kennzeichen in einer eigenen Einrichtungstabelle.Tabelle eignet sich nicht,
// wenn das Testsystem als Kopie der Produktion entsteht.
exit(EnvironmentInformation.IsSandbox());
end;
}
Bei der Aktion Belege jetzt herunterladen erhält der Benutzer keine Rückmeldung, dass das Abholen übersprungen wurde. Wenn ihr das möchtet, zeigt im Subscriber eine Meldung an – nur wenn GuiAllowed() zutrifft, damit die Aufgabenwarteschlange davon unberührt bleibt.
Testsystem mit einer SQUEEZE-Testinstanz verbinden
Statt das Abholen zu unterbinden, kann ein Testsystem auch mit einer eigenen SQUEEZE-Testinstanz arbeiten. Das lohnt sich vor allem, wenn das Testsystem regelmäßig aus einer Sicherung der Produktion neu aufgebaut wird – etwa zu jedem Sprint – und danach ohne Handarbeit gegen die Testinstanz laufen soll.
Ein eigenes Event oder einen Parameter für die Verbindung braucht ihr dafür nicht. SQUEEZE liest die Squeeze Einrichtung aus der Datenbank, beim Abholen erst nach OnBeforeDownloadDocumentData. Stellt ihr die Einrichtung dauerhaft auf die Testinstanz um, gehen alle folgenden Aufrufe dorthin: Abholen und Anlegen der Belege, die Rückmeldung FINISHED, Anhänge, Viewer, Training und Stammdatensynchronisation.
Verbindung umstellen
- Weist das Feld
URLder Einrichtung direkt zu – ohneValidateund ohne abschließenden Schrägstrich.Validateauf dieses Feld öffnet die Anmeldung an SQUEEZE als Dialog. In der Aufgabenwarteschlange und beiInvoke-NAVCodeunitgibt es keinen Dialog, der Aufruf bricht dort mit einem Fehler ab. - Ruft danach
GetAPIData(SqzSetup, ApiKey, false)ausDXP SQZ API Mgt.mit dem API-Schlüssel der Testinstanz auf. Das ist derselbe Weg wie die Anmeldung auf der Einrichtungsseite, nur ohne Dialog: Der Schlüssel wird gegen die Testinstanz geprüft und gespeichert, Version und Tenant der Testinstanz werden übernommen, die Stammdatentabellen neu ermittelt und die Einrichtung gespeichert.
Schreibt den API-Schlüssel der Testinstanz nicht in den Quellcode. Legt ihn zum Beispiel im IsolatedStorage eurer eigenen Erweiterung ab. Im Produktivsystem hinterlegt, ist er nach jeder Kopie auch im Testsystem vorhanden.
Was ihr zusätzlich umstellen müsst
- Dokumentenklassen: Die Felder Squeeze Dokumentenklassen-ID und Squeeze Export-Schnittstellen-ID in der Dokumentenklassen Einrichtung gehören zur jeweiligen SQUEEZE-Instanz. Weichen sie in der Testinstanz ab, stellt sie im selben Schritt mit um.
- Offene Einträge der Importwarteschlange: Die Kopie bringt die Einträge mit, die in der Produktion noch nicht verarbeitet waren. Die Verarbeitung filtert nicht nach Tenant, diese Belege werden also in der Testinstanz gesucht. Kennt die Testinstanz sie nicht, schlägt jeder Versuch fehl, wird bei jedem Lauf wiederholt und belegt Plätze der bis zu 10 Einträge pro Lauf. Löscht sie nach dem Umstellen mit
DeleteUnprocessedImportQueueEntriesausDXP SQUEEZE Setup Mgt.und übergebt dabei den bisherigen Tenant. Merkt ihn euch vor dem Umstellen aus dem FeldTenantder Einrichtung. In einer Sitzung mit Benutzeroberfläche fragt die Funktion vor dem Löschen nach.
Wann umstellen
- Direkt nach dem Neuaufbau (empfohlen): On-Premises ruft ihr eure Codeunit im Skript, das die Sicherung zurückspielt, mit
Invoke-NAVCodeunitfür jeden Mandanten auf – bevor die Aufgabenwarteschlange anläuft. Beim Zurückspielen einer Sicherung werden die Aufgabenwarteschlangenposten nicht angehalten. Ohne diesen Schritt starten die SQUEEZE-Aufgaben, z. B. Abholen und Stammdatensynchronisation, sofort mit der Produktivverbindung. - Zusätzlich in
OnBeforeDownloadDocumentDataals Absicherung: Dieselbe Umstellung im Event,IsHandledbleibtfalse. Der laufende Abruf geht dann bereits gegen die Testinstanz. Das Event greift aber nur beim Abholen. Was vorher läuft, z. B. die Stammdatensynchronisation, nutzt noch die Produktivverbindung.
Testsystem erkennen
Erkennt das Testsystem nicht an einem Kennzeichen in einer Tabelle. Tabellen werden mit jeder Kopie der Produktion überschrieben, im Testsystem steht danach wieder der Wert der Produktion. On-Premises eignet sich der Datenbank- oder Serverinstanzname aus der Tabelle Active Session, in Business Central online IsSandbox() oder GetEnvironmentName() aus der Codeunit Environment Information.
Beispiel
Das Beispiel stellt ein On-Premises-Testsystem um, das an seinem Datenbanknamen erkannt wird. Passt Objekt-IDs, Namen, die Prüfung in IsTestSystem und die Herkunft von URL und API-Schlüssel an eure Umgebung an.
codeunit 50103 "My SQZ Test Connection"
{
// On-Premises: nach dem Zurückspielen der Sicherung je Mandant aufrufen, z. B.
// Invoke-NAVCodeunit -ServerInstance BC -CompanyName 'CRONUS AG' -CodeunitId 50103
trigger OnRun()
begin
ApplyTestConnection();
end;
[EventSubscriber(ObjectType::Codeunit, Codeunit::"DXP SQZ API Mgt.", 'OnBeforeDownloadDocumentData', '', false, false)]
local procedure SwitchToTestConnection(var IsHandled: Boolean)
begin
// Absicherung, falls der Aufruf nach dem Zurückspielen fehlt.
// IsHandled bleibt false: der Abruf läuft danach gegen die Testinstanz.
ApplyTestConnection();
end;
local procedure ApplyTestConnection()
var
SqzSetup: Record "DXP SQUEEZE Setup";
SqzApiMgt: Codeunit "DXP SQZ API Mgt.";
SqzSetupMgt: Codeunit "DXP SQUEEZE Setup Mgt.";
PreviousTenant: Text[250];
begin
if not IsTestSystem() then
exit;
if not SqzSetup.Get() then
exit;
if SqzSetup.URL = GetTestUrl() then
exit;
PreviousTenant := SqzSetup.Tenant;
SqzSetup.URL := GetTestUrl(); // kein Validate: das öffnet den Anmeldedialog
SqzApiMgt.GetAPIData(SqzSetup, GetTestApiKey(), false);
// Offene Einträge der Importwarteschlange aus der Produktion entfernen
SqzSetupMgt.DeleteUnprocessedImportQueueEntries(PreviousTenant);
// Weichen Dokumentenklassen-ID oder Export-Schnittstellen-ID in der
// Testinstanz ab: hier zusätzlich "DXP Document Class Setup" anpassen.
end;
local procedure IsTestSystem(): Boolean
var
ActiveSession: Record "Active Session";
begin
// Nicht über eine eigene Tabelle erkennen: die wird mitkopiert.
ActiveSession.Get(ServiceInstanceId(), SessionId());
exit(ActiveSession."Database Name" = 'BC_TEST');
end;
local procedure GetTestUrl(): Text[1024]
begin
// URL der Testinstanz ohne abschließenden Schrägstrich,
// z. B. aus einer eigenen Einrichtung
end;
local procedure GetTestApiKey(): Text
begin
// API-Schlüssel der Testinstanz, z. B. aus dem IsolatedStorage
// der eigenen Erweiterung - nicht im Quellcode
end;
}
Im Event kostet die Absicherung bei jedem Abholen nur das Lesen von Sitzung und Einrichtung: Ist die URL bereits umgestellt, endet ApplyTestConnection sofort.