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.:

  1. DownloadDocumentData ruft 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.
  2. CreateCoreAndSQUEEZEDocument ruft 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 auf FINISHED.

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 unterbinden; Testsystem auf eine SQUEEZE-Testinstanz umstellen
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:

Mit IsHandled := true:

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. den Datenbanknamen aus der Tabelle "Active Session".
        // Ein Kennzeichen in einer eigenen 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

  1. Weist das Feld URL der Einrichtung direkt zu – ohne Validate und ohne abschließenden Schrägstrich. Validate auf dieses Feld öffnet die Anmeldung an SQUEEZE als Dialog. In der Aufgabenwarteschlange und bei Invoke-NAVCodeunit gibt es keinen Dialog, der Aufruf bricht dort mit einem Fehler ab.
  2. Ruft danach GetAPIData(SqzSetup, ApiKey, false) aus DXP 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

Wann umstellen

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.


Revision #2
Created 2026-10-27 14:39:35 UTC by Bernd Feddersen
Updated 2026-11-17 13:40:43 UTC by Bernd Feddersen