Integrationsbeispiele

Die folgenden Beispiele verwenden Objekt-IDs aus einem fiktiven Consumer-Bereich. Sie müssen an den eigenen Bereich und die eigenen Präfixe angepasst werden.

Pakete automatisch erzeugen

codeunit 50130 "My DHL Packing"
{
    procedure CreateSuggestedPackages(OrderNo: Code[20]; BoxCode: Code[20])
    var
        SalesHeader: Record "Sales Header";
        DhlPackingMgt: Codeunit "SOUDHL Packing Mgt";
    begin
        SalesHeader.Get(SalesHeader."Document Type"::Order, OrderNo);

        // 0 = Paketanzahl automatisch bestimmen.
        DhlPackingMgt.CreatePackages(SalesHeader, 0, BoxCode);
    end;
}

Für einen expliziten Modus:

DhlPackingMgt.CreatePackagesWithPackingMode(
    SalesHeader,
    0,
    BoxCode,
    Enum::"SOUDHL Packing Mode"::"Smart Distribute");

Die Methode kann bei unvollständigen Stammdaten oder nicht passenden Artikeln einen AL-Fehler auslösen. Für unbeaufsichtigte Prozesse sollte der Aufrufer eine klar definierte Fehlerbehandlung verwenden.

Packing-Eingaben über Event ändern

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Packing Mgt",
    'OnBeforeCreatePackages',
    '', false, false)]
local procedure ForceStandardBox(
    var SalesHeader: Record "Sales Header";
    var FixedPackageCount: Integer;
    var BoxCode: Code[20];
    var PackingMode: Enum "SOUDHL Packing Mode")
begin
    if BoxCode = '' then
        BoxCode := 'STD';
end;

Das Event läuft nach der Standardauflösung und vor Validierung. Ein Fehler bricht ab, bevor Pending-Pakete gelöscht werden.

Empfänger vor dem Persistieren normalisieren

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Package Recipient Mgt",
    'OnAfterSnapshotFromSalesHeader',
    '', false, false)]
local procedure TrimRecipientName(
    var PackageHeader: Record "SOUDHL Package Header";
    SalesHeader: Record "Sales Header")
begin
    PackageHeader."Recipient Name" := DelChr(PackageHeader."Recipient Name", '<>', ' ');
end;

Der geänderte Header wird anschließend vom Connector gespeichert. Name, Adresse, E-Mail und Telefon nicht protokollieren.

Label für ein vorhandenes Paket erzeugen

codeunit 50131 "My DHL Labels"
{
    procedure CreateLabel(PackageId: BigInteger; DocumentNo: Code[20])
    var
        PackageHeader: Record "SOUDHL Package Header";
        DhlApi: Codeunit "SOUDHL API Management";
        ExtraMessage: Text;
    begin
        PackageHeader.Get(PackageId, DocumentNo);

        if PackageHeader.Uploaded then
            exit;

        if not DhlApi.GenerateLabel(PackageHeader, ExtraMessage) then
            Error('DHL label could not be created: %1', ExtraMessage);

        // GenerateLabel aktualisiert und committet den Datenbankdatensatz.
        PackageHeader.Get(PackageId, DocumentNo);

        if ExtraMessage <> '' then
            Message('The label was created with a warning: %1', ExtraMessage);
    end;
}

Für Hintergrundprozesse sollte die Warnung protokolliert oder an den aufrufenden Prozess zurückgegeben werden, statt Message zu verwenden.

Labelergebnis ohne Failure-Event auswerten

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL API Management",
    'OnAfterGenerateLabel',
    '', false, false)]
local procedure AfterLabel(
    PackageHeader: Record "SOUDHL Package Header";
    Success: Boolean;
    ExtraMessage: Text)
begin
    if Success then
        exit;
    // Success = false deckt fachliche und technische Fehler ab.
end;

Bei Erfolg läuft das Event nach dem Commit(). Ein Subscriber-Fehler rollt das Label nicht zurück.

Express-Produktcode bestimmen

local procedure ResolveExpressProductCode(
    Product: Enum "SOUDHL Express Product"): Code[5]
var
    ExpressHelper: Codeunit "SOUDHL Express Helper";
begin
    exit(ExpressHelper.MapProductCode(Product));
end;

Live-Express-Preis abrufen

local procedure GetExpressRate(
    SalesHeader: Record "Sales Header";
    Product: Enum "SOUDHL Express Product";
    WeightKg: Decimal;
    LengthCm: Decimal;
    WidthCm: Decimal;
    HeightCm: Decimal;
    var Price: Decimal;
    var Currency: Text)
var
    DhlApi: Codeunit "SOUDHL API Management";
    ExpressHelper: Codeunit "SOUDHL Express Helper";
    ProductCode: Code[5];
    ExtraMessage: Text;
begin
    if not DhlApi.IsExpress() then
        Error('The DHL Connector is not configured for DHL Express.');

    ProductCode := ExpressHelper.MapProductCode(Product);

    if not DhlApi.GetRate(
        SalesHeader."Ship-to Country/Region Code",
        SalesHeader."Ship-to Post Code",
        SalesHeader."Ship-to City",
        WeightKg,
        LengthCm,
        WidthCm,
        HeightCm,
        ProductCode,
        Price,
        Currency,
        ExtraMessage)
    then
        Error('DHL rate could not be retrieved: %1', ExtraMessage);
end;

OnBeforeGetRate kann Destination, Maße oder Produktcode ändern. OnAfterGetRate läuft auch dann, wenn Express nicht konfiguriert ist.

Express-Request über Event ergänzen

codeunit 50132 "My DHL Subscribers"
{
    [EventSubscriber(
        ObjectType::Codeunit,
        Codeunit::"SOUDHL API Management",
        'OnBeforeSendShipmentRequest',
        '', false, false)]
    local procedure SetExpressProduct(
        var RequestJson: JsonObject;
        PackageHeader: Record "SOUDHL Package Header";
        SalesHeader: Record "Sales Header")
    var
        ExpressHelper: Codeunit "SOUDHL Express Helper";
        ProductCode: Code[5];
    begin
        ProductCode := ExpressHelper.MapProductCode(
            Enum::"SOUDHL Express Product"::ExpressWorldwide);

        if RequestJson.Contains('productCode') then
            RequestJson.Replace('productCode', ProductCode);
    end;
}

Dieser Subscriber läuft nur für Express. Das JSON darf nicht protokolliert werden.

Parcel-DE-Request ergänzen

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL API Management",
    'OnBeforeSendParcelDEShipmentRequest',
    '', false, false)]
local procedure BeforeParcelRequest(
    var RequestJson: JsonObject;
    PackageHeader: Record "SOUDHL Package Header";
    SalesHeader: Record "Sales Header")
begin
    if not RequestJson.Contains('profile') then
        exit;
end;

Pflichtknoten nicht entfernen und keine Credentials verwalten. Fachliche Header-Änderungen gehören bevorzugt nach OnBeforeGenerateLabel.

Eigene Versandoberfläche verwenden

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Sales UI",
    'OnBeforeSetPackageSubpageVisible',
    '', false, false)]
local procedure HideStandardPackagePart(
    SalesHeader: Record "Sales Header";
    var IsVisible: Boolean)
begin
    IsVisible := false;
end;

[EventSubscriber(
    ObjectType::Codeunit,
    Codeunit::"SOUDHL Sales UI",
    'OnBeforeSetListActionsVisible',
    '', false, false)]
local procedure HideStandardDhlActions(var IsVisible: Boolean)
begin
    IsVisible := false;
end;

Produktiv sollte das Ausblenden von einer eigenen Setup-Option abhängen, damit Administratoren das Standard-DHL-UI bei Bedarf wieder aktivieren können.

Lookup auf DHL-Boxen

tableextension 50133 "My Sales Header DHL" extends "Sales Header"
{
    fields
    {
        field(50133; "My DHL Box Code"; Code[20])
        {
            Caption = 'DHL Box Code';
            TableRelation = "SOUDHL Box".Code;
        }
    }
}

Lookups sind zulässig. Direkte Änderungen an DHL-Boxen aus der Consumer-App sollten vermieden werden.