Erste Schritte

Voraussetzungen

Für die Entwicklung werden benötigt:

• Microsoft Dynamics 365 Business Central ab Application-Version 24.0.0.0
• AL Runtime 13.0 oder höher
• ein Sandbox- oder Entwicklungsmandant, in dem der DHL Connector in mindestens Version 25.23.0.0 installiert ist
• ein eigener Objekt-ID-Bereich für die Consumer-App
• die erforderlichen DHL-Benutzerrechte für die ausgeführten Funktionen

Die Consumer-App darf eine höhere Business-Central- oder Runtime-Version verwenden.

Connector beziehen

Der Connector wird als kompilierte .app ausgeliefert oder von Solutioo im Zielmandanten installiert. Der Quellcode ist für eine Dependency nicht erforderlich.

Der bevorzugte Entwicklungsweg ist:

1. Solutioo stellt den DHL Connector im gemeinsamen Sandbox-Mandanten bereit.
2. Der Entwickler verbindet sein AL-Projekt mit diesem Mandanten.
3. Die Dependency wird in app.json eingetragen.
4. Mit AL: Download Symbols werden die Symbole geladen.
5. Die Consumer-App wird kompiliert und nach dem DHL Connector installiert.

Alternativ kann Solutioo ein freigegebenes .app-Paket für die lokale .alpackages-Ablage bereitstellen. Das Paket darf nicht verändert oder weitergegeben werden.

Dependency in app.json

{
  "dependencies": [
    {
      "id": "9d801b56-1d24-42d4-a98b-5663f28bdb4f",
      "name": "DHL Connector",
      "publisher": "Solutioo",
      "version": "25.23.0.0"
    }
  ],
  "application": "24.0.0.0",
  "runtime": "13.0"
}

Die angegebene Version ist die Mindestversion. Eine neuere kompatible DHL-Version erfüllt die Dependency ebenfalls. id, name und publisher müssen exakt übereinstimmen.

Consumer, die nur die Events bis 25.22.0.0 nutzen, bleiben kompatibel. Die additiven Events aus 25.23.0.0 erfordern diese Mindestversion.

Symbole laden

1. In .vscode/launch.json die Sandbox oder den Zielmandanten konfigurieren.
2. Sicherstellen, dass Version 25.23.0.0 oder höher installiert ist.
3. Den Befehl AL: Download Symbols ausführen.
4. Prüfen, ob ein Symbolpaket Solutioo_DHL Connector_*.app in .alpackages vorhanden ist.
5. Das Projekt mit AL: Package kompilieren.

Das Symbolpaket enthält Signaturen und Metadaten der erreichbaren Objekte, jedoch keinen Quellcode. Debug-Zugriff ist kein Bestandteil des Integrationsvertrags und hängt von der ausgelieferten Paket- und Umgebungsrichtlinie ab.

Permission Set der Consumer-App

Für lesende Integrationen kann das Basisrecht eingebunden werden:

permissionset 50100 "MY DHL Integration"
{
    Assignable = true;
    IncludedPermissionSets = "SOUDHL Base";

    Permissions =
        codeunit "My DHL Integration" = X;
}

SOUDHL Base reicht nicht automatisch für Paket- oder Labelerzeugung. Benutzer, die diese Funktionen ausführen, benötigen zusätzlich das zu ihrer DHL-Lizenz gehörende Permission Set SOUDHL User oder DHL Integration Super User.

Ein Permission Set der Consumer-App kann fehlende App-Entitlements nicht umgehen.

Mandant vorbereiten

Vor einem Integrationstest:

• DHL Connector vollständig einrichten,
• DHL Parcel DE oder Express auswählen,
• mindestens eine DHL-Box konfigurieren,
• DHL-Benutzerrechte zuweisen,
• ausgehende HttpClient-Aufrufe für die DHL-App erlauben,
• Testaufträge mit Versandadresse, Artikeln, Gewicht und Abmessungen anlegen.

Zugangsdaten werden ausschließlich über die DHL-Einrichtungsseiten gepflegt. Eine Consumer-App darf sie weder lesen noch schreiben.

Smoke Test

Dieser Test prüft, ob die Symbole verfügbar sind und liest gleichzeitig den konfigurierten Servicemodus:

codeunit 50101 "My DHL Smoke Test"
{
    procedure IsExpressServiceConfigured(): Boolean
    var
        DhlApi: Codeunit "SOUDHL API Management";
    begin
        exit(DhlApi.IsExpress());
    end;
}

false bedeutet in diesem Test normalerweise, dass Parcel DE konfiguriert ist; es bedeutet nicht automatisch, dass der Connector fehlt. Für einen echten Verbindungstest sollte ein vorbereiteter Sandbox-Auftrag über den dokumentierten Label- oder Preisprozess verwendet werden. Token oder Credentials dürfen nicht als Testergebnis ausgegeben werden.