Power BI / Azure Integration

Azure App-Registrierung

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

1. Gehe in Azure zu "App-Registrierungen" und klicke auf "Neue Registrierung"

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

   2. Unterstützte Kontotypen

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

2. Gehe in der erstellten App zu "API-Berechtigungen" und klicke auf "Berechtigung hinzufügen"

   1. Wähle "Power Bi Service"

   2. Wähle "Delegierte Berechtigungen"

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

   4. Klicke auf "Berechtigung hinzufügen"

3. Erstelle nun ein "Client-Geheimnis". Gehe zu "Zertifikate & Geheimnisse" und klicke auf "Neues Client-Geheimnis"

   1. Notiere den Wert (nicht die "Geheimnis-ID") – er wird nur einmal direkt nach dem Erstellen angezeigt.

Power-BI-Konfiguration

In Power BI muss Dienstprinzipalen die Nutzung der Power-BI-API erlaubt werden.

1. Gehe in den Einstellungen zum "Admin-Portal".

2. Suche unter "Mandanteneinstellungen" nach "Entwicklereinstellungen"

   1. Aktiviere "Dienstprinzipalen die Verwendung von Power-BI-APIs erlauben"

Zusätzlich musst du dem "Power BI Service (Dienstprinzipal)" Zugriff auf den Workspace geben. Hinweis: Ein Dienstprinzipal kann nicht auf den persönlichen "Mein Arbeitsbereich" zugreifen – du musst daher einen eigenen Workspace erstellen (oder einen vorhandenen, geteilten nutzen) für den Export.

1. Erstelle einen neuen Workspace (nicht "Mein Arbeitsbereich"), falls du noch keinen eigenen hast

2. Öffne diesen Workspace und klicke auf "Zugriff verwalten"

3. Füge deine erstellte App hinzu

Installation

Das Plugin wird wie jedes andere Plugin installiert. Die gesamte Konfiguration erfolgt im eigenen Administrations-Modul – siehe unten. Bei der Installation werden sinnvolle Standardwerte und ein Standard-Feld-Mapping für beide Feeds angelegt.

Das Power-BI-Modul

Öffne Einstellungen → Power BI. Das Modul ist auf zwei Ebenen aufgebaut:

• Die oberste Ebene schaltet zwischen den beiden Export-Feeds und der gemeinsamen Verbindung um: Order Export, Kunden Export und Verbindung.
• Jeder Feed (Order / Kunden) hat die Untertabs Übersicht, Felder, Associations und Export.

Die Konfiguration ist global (nicht pro Verkaufskanal). Zugangsdaten und Dataset teilen sich beide Feeds; nur Tabellenname und Push-Verzögerung werden pro Feed konfiguriert.

Verbindung (geteilt)

Der Tab Verbindung enthält alles, was sich beide Feeds teilen:

• Client ID: die "Anwendungs-ID (Client)" von der Übersichtsseite der App. Das ist nicht die "Geheimnis-ID" (Secret ID) des Client-Geheimnisses.
• Client Secret: der Wert (Value) des oben erstellten Client-Geheimnisses – nicht dessen "Geheimnis-ID". (Der Wert wird nur einmal direkt nach dem Erstellen angezeigt.)
• Tenant ID / Directory ID: die "Verzeichnis-ID (Mandant)" von der Übersichtsseite der App.
• Workspace ID: die ID des eigenen Workspace (nicht "Mein Arbeitsbereich"), in der Workspace-URL zu finden, z. B. https://app.powerbi.com/groups/05asdede0-7cc2-4ad7-8e39-acd73fab27dk
• Dataset-Name: der Name des zu erstellenden Datasets (vorbelegt mit Shopware Export, bei Bedarf ändern).
• Dataset-ID: leer lassen – wird nach "Dataset erstellen" automatisch gefüllt.
• Power-BI-Export aktiv: Hauptschalter für den Live-Push.

Hier gibt es zwei Aktionen:

• Verbindung testen: speichert die Einstellungen und prüft, ob Azure erreichbar und die Zugangsdaten gültig sind. Die Status-Ampeln auf der Übersicht jedes Feeds zeigen danach das Ergebnis.
• Dataset erstellen: legt in Power BI das Dataset samt Bestellungstabelle und – wenn der Kunden-Feed aktiv ist – der Kundentabelle an, basierend auf den konfigurierten Tabellennamen. Danach wird die Dataset-ID automatisch gefüllt. Hinweis: Power-BI-Push-Datasets erlauben kein nachträgliches Umbenennen/Hinzufügen von Tabellen – ein späterer Tabellennamen-Wechsel erfordert ein erneutes "Dataset erstellen".

Übersicht (pro Feed)

Der Tab Übersicht jedes Feeds zeigt den aktuellen Einrichtungszustand und die feed-spezifischen Einstellungen:

• Status: Azure verbunden, Dataset vorhanden, Tabelle vorhanden, letzte Synchronisierung.
• Verbindung testen: Live-Prüfung der Power-BI-Verbindung (aktualisiert die Ampeln).
• Daten leeren: entfernt alle exportierten Zeilen aus der Tabelle dieses Feeds (Order oder Kunden). Ein Bestätigungsdialog zeigt den betroffenen Tabellennamen.
• Feed-Einstellungen:
  • Tabellenname: die Bestellungs- bzw. Kundentabelle im Dataset (vorbelegt mit Orders / Customers).
  • Push-Verzögerung (Stunden): Verzögerung, bevor eine neu eingegangene Bestellung / ein neu registrierter Kunde übertragen wird. Bei Bestellungen sinnvoll, damit Rechnungsnummer, Zahlungs- und Versandstatus noch nachgepflegt werden können. Pro Feed getrennt einstellbar. Standard 0 (sofort). Nur ganze Stunden.
  • Zu exportierende LineItem-Typen (nur Order-Feed): welche Shopware-LineItem-Typen exportiert werden (siehe unten).
  • Kunden-Feed aktivieren (nur Kunden-Feed): aktiviert den automatischen Export des Kundenstamms.

Das Ändern des Tabellennamens stößt beim Speichern automatisch eine Schema-Synchronisierung an. Existiert die (neue) Tabelle noch nicht im Dataset, erstelle das Dataset im Verbindung-Tab neu.

Zu exportierende LineItem-Typen (Order-Feed)

Wähle, welche Shopware-LineItem-Typen exportiert werden. Standard: nur product. Mögliche Werte:

• product: reguläre Produktpositionen
• promotion: Promotion-/Gutschein-Positionen
• custom: manuell hinzugefügte Positionen
• credit: Gutschriften
• discount: Rabatte
• container: Container-Positionen
• quantity: Mengen-Artikel
• shipping: Versandkosten als synthetische Position (siehe unten)

Feld-Mapping

Jede Zeile, die an Power BI gepusht wird, entsteht aus den konfigurierten Feldern des jeweiligen Feeds. Die Reihenfolge der Felder im Baum ist die Spaltenreihenfolge im Power-BI-Schema. Order- und Kunden-Feed haben jeweils ihren eigenen Feldsatz.

Jedes Feld hat drei Eigenschaften:

• Name: der Name der Spalte in Power BI
• Typ: der Power-BI-Datentyp: string, Int64, Double, bool oder DateTime
• Wert: ein Twig-Template, das einmal pro Zeile gerendert wird

Die Variablen-Chips über dem Editor fügen die gängigsten Variablen des aktuellen Feeds ein.

Twig-Kontext – Order-Feed

Das Template wird einmal pro LineItem (und einmal pro Versandzeile, falls aktiv) mit diesen Variablen gerendert:

• order: die OrderEntity mit allen geladenen Associations
• lineItem: die aktuelle OrderLineItemEntity (auch eine synthetische Entity für Versandzeilen)
• product: die ProductEntity oder null bei Nicht-Produkt-Positionen
• orderCustomer, customer

Beispiele:

{{ order.orderNumber }}

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

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

Twig-Kontext – Kunden-Feed

Das Template wird einmal pro Kunde mit diesen Variablen gerendert:

• customer: die CustomerEntity
• group: die Kundengruppe
• salutation
• defaultBillingAddress, defaultShippingAddress

Beispiele: {{ customer.customerNumber }}, {{ customer.email }}, {{ customer.group.name|default('') }}, {{ customer.createdAt ? customer.createdAt|date('Y-m-d H:i:s') : '' }}

Versandzeilen (Order-Feed)

Ist der LineItem-Typ shipping aktiv, wird pro Lieferung mit einem Versandkosten-Gesamtbetrag ≠ 0 eine zusätzliche Zeile erzeugt. Das Plugin baut dafür eine synthetische OrderLineItemEntity (Typ shipping, Label = Name der Versandart, Menge/Einzelpreis/Gesamtpreis aus den Versandkosten, der vollständige CalculatedPrice, Position = letzte Position + 1). Templates wie {{ lineItem.label }} oder {{ lineItem.price.totalPrice }} funktionieren unverändert; product ist bei Versandzeilen null, daher Produktzugriffe absichern, z. B. {{ product ? product.productNumber : '' }}.

Mapping testen

Der Button Mapping testen rendert das komplette Mapping gegen einen echten Datensatz (eine Bestellung im Order-Feed, einen Kunden im Kunden-Feed) und zeigt die resultierenden Zeilen in einer Tabelle, ohne etwas an Power BI zu pushen. So lassen sich Werte, Zeilenanzahl und Twig-Templates vor dem Livegang prüfen.

Felder synchronisieren

Nach jeder Mapping-Änderung (neue Felder, Typänderungen, Import) muss das Tabellenschema in Power BI angeglichen werden. Nutze den Button Felder synchronisieren oben auf der Felder-Seite. Änderst du den Typ einer Spalte, die bereits Daten enthält, nutze zuerst Daten leeren auf der Übersicht, sonst lehnt Power BI die Schema-Änderung ab.

Import / Export

Die Buttons Mapping exportieren und Mapping importieren sichern bzw. stellen die Feldkonfiguration des aktuellen Feeds als JSON-Datei wieder her. Beim Import werden vorhandene Felder (anhand des Namens) überschrieben, neue ergänzt; vorhandene Felder, deren Name nicht in der Datei steht, bleiben unangetastet.

Associations

Der Tab Associations ergänzt zusätzliche DAL-Association-Pfade, die vor dem Rendern des Mappings je Datensatz geladen werden. Jeder Pfad in eine eigene Zeile. Order- und Kunden-Feed haben eine eigene Liste; sie gilt für Live-Push, Voll-Export und die Mapping-Vorschau.

Order-Standard: lineItems.product, orderCustomer.customer.group, deliveries.shippingMethod. Häufig ergänzt: billingAddress.country, deliveries.stateMachineState, transactions.paymentMethod, transactions.stateMachineState, currency, stateMachineState, documents.documentType.

Kunden-Standard: group, salutation, defaultBillingAddress, defaultShippingAddress.

Export-Tab

Der Tab Export pusht im Hintergrund eine Menge bestehender Datensätze an Power BI.

• Order-Feed: optional per Bestelldatum eingrenzen (Von / Bis). Leer lassen, um alle Bestellungen zu exportieren.
• Kunden-Feed: optional per Registrierungsdatum eingrenzen (Registriert ab / bis), um die Menge zu reduzieren. Leer lassen, um den gesamten Kundenstamm zu exportieren.

Export starten beginnt sofort, Export abbrechen stoppt einen laufenden Job, Aktualisieren aktualisiert den Fortschrittsbalken. Verlauf anzeigen listet frühere Läufe mit Status, Parametern, Zeitstempeln und etwaiger Fehlermeldung.

Automatischer Export

• Bestellungen: jede neu eingegangene Bestellung wird bei aktivem Live-Push automatisch übertragen (mit der konfigurierten Order-Push-Verzögerung).
• Kunden: bei aktivem Kunden-Feed wird jeder neu registrierte Kunde (inkl. Gast-Accounts) automatisch übertragen. Änderungen an bestehenden Kunden werden nicht erneut gepusht – nutze dafür einen Voll-Export.

E-Mail-Export (Plugin-Konfigurationsseite)

Der klassische tägliche CSV-E-Mail-Export wird unter Erweiterungen → Meine Erweiterungen → Power BI → Konfigurieren eingestellt (die einzigen verbleibenden Einstellungen auf der Plugin-Konfigurationsseite):

1. Aktiv: E-Mail-Export aktivieren / deaktivieren

2. E-Mails: die Empfänger, durch Kommas getrennt

3. CSV-Trennzeichen: Spaltentrennzeichen für die CSV (Standard ist ein Komma)

Wenn aktiviert, werden die Bestelldaten einmal täglich als CSV an die konfigurierten E-Mails versendet. Ein passendes E-Mail-Template erscheint unter Einstellungen → E-Mail-Templates als PowerBi Export Orders Mail; du kannst den Text anpassen (es stehen keine Variablen zur Verfügung).

Hinweis: Der E-Mail-Export nutzt aktuell einen festen Spaltensatz und nicht das Feld-Mapping. Das Feld-Mapping gilt nur für den Power-BI-Push.

Messenger

Live-Push und Voll-Export laufen über Shopwares Messenger-Queue. Stelle sicher, dass die Standard-Worker laufen, damit die Nachrichten verarbeitet werden:

php bin/console scheduled-task:run

php bin/console messenger:consume async

Empfohlener Ablauf

1. Öffne den Tab Verbindung, trage die Azure-Zugangsdaten, Workspace ID und Dataset-Name ein und setze den Bestellungs- (und ggf. Kunden-)Tabellennamen in der Übersicht des jeweiligen Feeds.
2. Wenn du den Kunden-Feed nutzt, aktiviere ihn in der Übersicht des Kunden-Exports.
3. Klicke auf Verbindung testen, um die Zugangsdaten zu prüfen.
4. Klicke im Verbindung-Tab auf Dataset erstellen, um Dataset und Tabellen anzulegen.
5. Setze die zu exportierenden LineItem-Typen für den Order-Feed (für Versandkosten shipping ergänzen).
6. Ergänze bei Bedarf zusätzliche Associations im Tab Associations des jeweiligen Feeds.
7. Baue die Felder unter Felder (oder importiere ein zuvor exportiertes JSON).
8. Prüfe mit Mapping testen gegen eine echte Bestellung / einen echten Kunden.
9. Klicke auf Felder synchronisieren, damit Power BI das Schema kennt.
10. Aktiviere Power-BI-Export aktiv im Verbindung-Tab und/oder starte einen Voll-Export im Tab Export.

Noch Fragen? Schau in unsere FAQs oder kontaktiere uns direkt: scope01.com/shopware-power-bi-plugin/