Power BI / Azure Integration

Azure App-Registrierung

Damit das Plugin mit PowerBi kommunizieren kann, muss in Azure eine App registriert werden.

1. In Azure auf "App-Registrierungen" gehen und "Neue Registrierung" anklicken

   1. Name: Name der App, z. B. der Shopname

   2. Unterstützte Kontotypen

   3. Redirect URL: z. B. die Shop-URL

2. In der erstellten App auf "API-Berechtigungen" gehen und "Berechtigung hinzufügen" anklicken

   1. "Power Bi Service" auswählen

   2. "Delegierte Berechtigungen" auswählen

   3. Das Plugin benötigt nur die Berechtigungen "Dataset.ReadWrite.All" und "Workspace.Read.All"

   4. "Berechtigung hinzufügen" klicken

3. Anschließend muss ein "Client-Geheimnis" angelegt werden. In "Zertifikate & Geheimnisse" auf "Neues Client-Geheimnis" klicken

   1. Den "Wert" notieren.

PowerBi-Konfiguration

In PowerBi muss Service Principals der Zugriff auf die PowerBi-API erlaubt werden.

1. Im Bereich "Einstellungen" das "Admin-Portal" öffnen.

2. Unter "Tenant-Einstellungen" nach "Entwicklereinstellungen" suchen

   1. "Allow service principals to use Power BI APIs" aktivieren

Der "PowerBi Service (Service Principal)" benötigt außerdem Zugriff auf den Workspace.

1. Den eigenen Workspace öffnen (nicht "My Workspace")

2. "Zugriff verwalten" anklicken

3. Die zuvor erstellte App hinzufügen

Installation und Konfiguration

Das Plugin lässt sich wie jedes andere Shopware-Plugin installieren.

Einstellungen

E-Mail-Export

1. Aktiv: E-Mail-Export ein- bzw. ausschalten

2. E-Mails: Empfängeradressen, durch Komma getrennt

3. CSV-Trennzeichen: Spaltentrenner für die CSV-Datei (Standard ist das Komma)

Ist die Funktion aktiv, werden die Bestelldaten einmal täglich als CSV per E-Mail an die konfigurierten Empfänger geschickt. Der erste Export enthält die Bestellungen des aktuellen Tages. Danach umfasst jeder Export die Bestellungen seit dem letzten Lauf.

PowerBi-Konfiguration (für den direkten Export nach PowerBi)

1. Aktiv: Live-Push ein- bzw. ausschalten

2. Workspace ID: ist in der URL zu finden, z. B. https://app.powerbi.com/groups/05asdede0-7cc2-4ad7-8e39-acd73fab27dk

3. Dataset Name: Name des neu zu erstellenden Datasets (darf in PowerBi noch nicht existieren)

4. Dataset ID: leer lassen, wird nach "Erstelle Dataset" automatisch gefüllt

5. Bestellungstabelle Name: Name der Bestellungstabelle innerhalb des Datasets

6. Zu exportierende LineItem-Typen: welche Shopware-LineItem-Typen exportiert werden. Standard: nur product. Verfügbare Werte:

   • product: reguläre Produktpositionen
   • promotion: Promotions / Gutscheine
   • custom: manuell hinzugefügte Positionen
   • credit: Gutschriften
   • discount: Rabatte
   • container: Container-LineItems
   • quantity: Mengen-Artikel
   • shipping: Versandkosten als synthetisches LineItem (siehe unten)

7. Push-Verzögerung (Stunden): Verzögerung (in Stunden), bevor eine neu eingegangene Bestellung an PowerBi gepusht wird. Sinnvoll, um Daten wie Rechnungsnummer oder Statusänderungen Zeit zum Befüllen zu geben, bevor der Snapshot erzeugt wird. Standard: 0 (sofortiger Push).

Alle PowerBi-Einstellungen sind pro Sales-Channel konfigurierbar.

Azure-Konfiguration (für den direkten Export nach PowerBi)

1. Client ID: wird auf der Übersichtsseite der Azure-App-Registrierung angezeigt

2. Client Secret: der Wert des oben angelegten Client-Geheimnisses

3. Tenant ID / Directory ID: wird auf der Übersichtsseite der Azure-App-Registrierung angezeigt

Aktionen

Die Karte Aktionen in der Plugin-Konfiguration bietet folgende Schaltflächen:

• Azure Verbindung testen: prüft, ob Client ID, Client Secret und Tenant ID korrekt sind.
• PowerBi Einstellungen testen: prüft, ob die Workspace ID erreichbar ist und (falls eine Dataset ID gesetzt ist) ob Dataset und Bestellungstabelle existieren.
• Erstelle Dataset: legt das Dataset und die Bestellungstabelle in PowerBi anhand der konfigurierten Werte Dataset Name und Bestellungstabelle Name an. Nach erfolgreicher Ausführung wird das Feld Dataset ID automatisch befüllt.
• Initialisiere Orderfeed: erzeugt den CSV-Orderfeed im Hintergrund neu.
• Dataset leeren: entfernt alle Zeilen aus der PowerBi-Bestellungstabelle. Nützlich vor einem erneuten Import mit geändertem Schema.

Feldzuordnung

Über Einstellungen → Power BI erreichbar. Die Seite hat drei Tabs: Felder, Assoziationen und Export.

Jede Zeile, die an PowerBi gepusht wird, entsteht aus den konfigurierten Feldern. Die Reihenfolge im Baum entspricht der Reihenfolge der Spalten im PowerBi-Schema.

Jedes Feld hat drei Eigenschaften:

• Name: Name der Spalte in PowerBi
• Typ: der PowerBi-Datentyp, eines von string, Int64, Double, bool oder DateTime
• Wert: ein Twig-Template, das pro LineItem ausgewertet wird

Twig-Kontext

Innerhalb des Wert-Templates stehen folgende Variablen zur Verfügung:

• order: die OrderEntity mit allen geladenen Assoziationen
• lineItem: die aktuelle OrderLineItemEntity (bei Versandzeilen ein synthetisches Objekt, siehe unten)
• product: die ProductEntity, oder null bei Nicht-Produkt-LineItems
• orderCustomer, customer

Alles, was an diesen Entitäten hängt (inklusive lineItem.payload, order.deliveries, order.transactions etc.), ist über die normale Twig-Property-Syntax zugänglich, sofern die entsprechende Assoziation geladen ist.

Beispiele:

{{ order.orderNumber }}

{{ order.stateMachineState ? order.stateMachineState.name : '' }}

{% set t = order.transactions ? order.transactions.last : null %}{{ t and t.paymentMethod ? t.paymentMethod.name : '' }}

{% set ct = lineItem.price and lineItem.price.calculatedTaxes ? lineItem.price.calculatedTaxes.first : null %}{{ ct ? ct.taxRate : '' }}

Versandzeilen

Ist der LineItem-Typ shipping aktiviert, wird für jede Lieferung mit Versandkosten ungleich null eine zusätzliche Zeile erzeugt. Das Plugin baut dafür eine synthetische OrderLineItemEntity mit:

• type: shipping
• label: Name der Versandart
• quantity, unitPrice, totalPrice: aus den Versandkosten übernommen
• price: das vollständige CalculatedPrice-Objekt (inklusive Steuern)
• position: letzte Position + 1

Bestehende Templates wie {{ lineItem.label }} oder {{ lineItem.price.totalPrice }} funktionieren ohne Anpassung auch für Versandzeilen. product ist bei Versandzeilen null; produktspezifische Zugriffe sollten daher in einer Bedingung gekapselt werden, z. B. {{ product ? product.productNumber : '' }}.

Mapping testen

Die Schaltfläche Mapping testen öffnet einen Dialog, in dem eine bestehende Bestellung ausgewählt werden kann. Das Plugin rendert das vollständige Mapping gegen diese Bestellung und zeigt die erzeugten Zeilen in einer Tabelle an, ohne etwas an PowerBi zu pushen. Damit lässt sich prüfen:

• ob alle konfigurierten Felder korrekt gefüllt werden
• ob die Zeilenanzahl den Erwartungen entspricht (LineItems plus ggf. Versandzeilen)
• ob Twig-Fehler in den Templates vorliegen

Import / Export

Mit den Schaltflächen Mapping exportieren und Mapping importieren lässt sich die komplette Feldkonfiguration als JSON-Datei sichern und wiederherstellen.

• Export lädt eine JSON-Datei herunter, die jedes Feld mit id, name, type, value und afterId enthält.
• Import liest eine solche JSON-Datei ein und fügt sie in die bestehende Konfiguration ein:        
  • Felder, die bereits existieren (Treffer anhand des Namens), werden überschrieben: Typ, Wert und Position werden aus der Datei übernommen.
  • Felder, die noch nicht existieren, werden angelegt.
  • Vorhandene Felder, deren Name nicht in der Datei steht, bleiben unverändert.

Felder synchronisieren

Nach jeder Änderung am Mapping (neue Felder, Typänderungen, Import) muss das Tabellenschema in PowerBi angeglichen werden. Dafür dient die Schaltfläche Felder synchronisieren oberhalb des Feldbaums. Wenn der Typ einer Spalte geändert wird, die bereits Daten enthält, vorher Dataset leeren in der Plugin-Konfiguration ausführen, da PowerBi sonst die Schemaänderung ablehnt.

Assoziationen

Auf dem Tab Assoziationen können zusätzliche DAL-Assoziationspfade hinterlegt werden, die vor dem Rendern des Mappings für jede Bestellung geladen werden. Jeder Pfad steht in einer eigenen Zeile. Die Liste gilt für den Live-Push, den Bulk-Export und die Vorschau über "Mapping testen".

Standardmäßig geladen werden lineItems.product, orderCustomer.customer.group und deliveries.shippingMethod. Beispiele für häufig zusätzlich benötigte Pfade:

• billingAddress.country
• deliveries.shippingOrderAddress.country
• deliveries.stateMachineState
• transactions.paymentMethod
• transactions.stateMachineState
• currency
• stateMachineState
• documents.documentType

E-Mail-Vorlage

Nach der Installation steht unter Einstellungen → E-Mail-Vorlagen die Vorlage PowerBi Export Orders Mail zur Verfügung. Der Text kann angepasst werden. In dieser Vorlage stehen keine Variablen zur Verfügung.

Bestellungen nach PowerBI exportieren

Über den Tab Export der Plugin-Seite lässt sich ein zeitlich begrenzter Batch bestehender Bestellungen an PowerBi übertragen.

Zeitraum festlegen

Von / Bis:

• Mit dem Kalender Start- und Enddatum auswählen
• Damit wird das früheste bzw. späteste Bestelldatum festgelegt, das im Export enthalten ist
• Sollen alle Bestellungen exportiert werden, beide Felder leer lassen

Aktionen

Nach dem Festlegen des Zeitraums stehen drei Schaltflächen zur Verfügung:

Export starten

• Startet den Export-Prozess sofort
• Exportiert alle Bestellungen im gewählten Zeitraum

Export abbrechen

• Bricht den laufenden Export ab

Aktualisieren

• Aktualisiert den angezeigten Status bzw. den Fortschrittsbalken des laufenden Exports

Fortschritt beobachten

Während ein Export läuft, wird ein Fortschrittsbalken angezeigt. Der Link Verlauf anzeigen unterhalb der Schaltflächen blendet eine Liste vergangener Export-Läufe mit Status, Parametern, Zeitstempeln und etwaigen Fehlermeldungen ein.

Troubleshooting

• Schlägt ein Export fehl, finden sich im Verlauf Details zum Fehler
• Größere Zeiträume können entsprechend länger laufen, etwas Geduld
• Hängende Exports abbrechen und neu starten
• Ist ein Feld in der Vorschau "Mapping testen" leer, fehlt meist eine Assoziation; diese auf dem Tab Assoziationen ergänzen
• Mit Azure Verbindung testen und PowerBi Einstellungen testen in der Plugin-Konfiguration die Zugangsdaten überprüfen

Messenger

Der Live-Push und der Bulk-Export laufen über die Shopware Messenger-Queue. Es muss sichergestellt sein, dass die Standard-Shopware-Worker laufen, damit die Nachrichten verarbeitet werden:

php bin/console scheduled-task:run

php bin/console messenger:consume async

Empfohlener Ablauf

1. Die Azure- und PowerBi-Konfiguration ausfüllen.
2. In der Plugin-Konfiguration Azure Verbindung testen und PowerBi Einstellungen testen klicken, um die Zugangsdaten zu prüfen.
3. Erstelle Dataset klicken, um das Dataset und die Bestellungstabelle in PowerBi anzulegen.
4. Zu exportierende LineItem-Typen setzen (mindestens product, bei Bedarf shipping für Versandkosten).
5. Bei Bedarf auf dem Tab Assoziationen zusätzliche Pfade ergänzen.
6. Felder unter Felder anlegen (oder ein zuvor exportiertes JSON importieren).
7. Das Mapping über Mapping testen an einer realen Bestellung verifizieren.
8. Felder synchronisieren klicken, damit PowerBi das Schema kennt.
9. Den Live-Push aktivieren (Aktiv in der PowerBi-Konfiguration) und/oder einen Bulk-Export auf dem Tab Export starten.