Ai/TrafagSalesExporter/docs/ALPHAPLAN_DISCOVERY_EXPORTER_GUIDE_2026-06-08.md

Alphaplan Discovery Exporter Guide

Stand: 2026-06-08

Zweck: Diese Anleitung dokumentiert das Phase-1-Paket fuer Deutschland/Alphaplan. Das Paket soll auf dem deutschen Alphaplan-/SQL-Server laufen, relevante SQL-Datenbanken, Tabellen und Views finden, CSV-Dateien erzeugen und diese optional per rclone nach SharePoint laden.

Status

• Paket erstellt: AlphaplanExportPackage.
• ZIP erstellt: AlphaplanExportPackage.zip.
• Phase: Discovery / Rohdatenanalyse.
• BiDashboard-Import wird dadurch noch nicht angepasst.
• BiDashboard-App-Code wird fuer diesen Exporter nicht benoetigt.
• PowerShell-Syntax des Scripts wurde lokal geprueft.

Dateien

Datei	Zweck
AlphaplanExportPackage/Run-AlphaplanDiscoveryAndUpload.ps1	All-in-one Discovery, optional Samples, optional rclone Upload
AlphaplanExportPackage/README.txt	Kurzanleitung fuer den DE-Server
AlphaplanExportPackage.zip	Kopierbares Paket fuer den DE-Server
docs/ALPHAPLAN_SQL_RCLONE_KONZEPT_DE_2026-06-08.md	Fach-/Technikkonzept
docs/ALPHAPLAN_DISCOVERY_EXPORTER_GUIDE_2026-06-08.md	Diese Nachdokumentation

Zielbild

Der Export laeuft direkt auf dem Alphaplan-Server in Deutschland:

1. PowerShell startet das Script.
2. Script verbindet sich read-only mit SQL Server.
3. Script scannt SQL-Datenbanken, Tabellen und Views.
4. Script bewertet Kandidaten anhand von Namen und Spalten.
5. Script schreibt candidate_objects.csv.
6. Script schreibt export_summary.csv.
7. Optional schreibt es kleine sample_*.csv.
8. Optional laedt rclone die Dateien nach SharePoint.

SharePoint-Ziel

Default:

trafag-bi:Import/Finance/Deutschland/AlphaplanRaw

Dieser Rohdatenordner ist bewusst getrennt vom produktiven Deutschland-Import. So koennen die Discovery-CSV nicht versehentlich vom bestehenden Import als finale Finance-Dateien gelesen werden.

Lokaler Zielordner auf dem DE-Server

Default:

C:\Trafag\AlphaplanExport

Unterordner:

C:\Trafag\AlphaplanExport\out
C:\Trafag\AlphaplanExport\logs

Pro Lauf entsteht:

C:\Trafag\AlphaplanExport\out\Alphaplan_SQL_Discovery_YYYYMMDD_HHMMSS

Ergebnisdateien

Datei	Inhalt
candidate_objects.csv	Relevante SQL-Tabellen/Views mit Score, Spalten, Datums-/Betrags-/Key-Kandidaten
export_summary.csv	Status pro Datenbank und optional pro Sample-Export
README.txt	Laufbezogene Kurzbeschreibung
sample_*.csv	Optionale kleine Beispielauszuege aus Top-Kandidaten

Bewertung der Kandidaten

Das Script bewertet Tabellen/Views ueber Objekt- und Spaltennamen. Treffer gibt es u. a. fuer:

• Rechnung, Faktura, Invoice, Beleg
• Umsatz, Verkauf, Sales, Revenue
• Position, Zeile, Line
• Auftrag, Order
• Kunde, Debitor, Customer, Adresse
• Artikel, Material, Item, Produkt
• Betrag, Netto, Umsatz, Amount, Price, Preis, Summe
• Menge, Anzahl, Quantity, Qty
• Waehrung, Currency
• Warengruppe, Produktgruppe
• Gutschrift, Storno, Credit

Die Discovery ist kein finaler Beweis, sondern eine Vorauswahl fuer DE/IT und Finance.

Wichtige Parameter

Parameter	Default	Zweck
-ServerInstance	localhost	SQL Server / Instanz
-Database	leer	leer = alle erreichbaren User-Datenbanken scannen
-SqlCredential	leer	optional SQL-Login statt Windows Integrated
-BaseDirectory	C:\Trafag\AlphaplanExport	lokaler Arbeitsordner
-MaxCandidatesPerDatabase	80	maximale Kandidaten je Datenbank
-ExportSamples	aus	kleine Beispiel-CSV erzeugen
-MaxSampleObjects	15	maximale Sample-Objekte
-SampleRows	200	Zeilen pro Sample
-SkipUpload	aus	nur lokal erzeugen, kein rclone Upload
-RcloneExe	C:\Tools\rclone.exe	bevorzugter rclone Pfad
-RcloneRemote	trafag-bi	rclone Remote
-RcloneTarget	Import/Finance/Deutschland/AlphaplanRaw	SharePoint-Zielpfad

Standardlauf lokal ohne Upload

Auf dem DE-Server im Paketordner:

Set-ExecutionPolicy -Scope Process Bypass
.\Run-AlphaplanDiscoveryAndUpload.ps1 -SkipUpload

Das ist der empfohlene erste Test, weil keine SharePoint-/rclone-Abhaengigkeit geprueft werden muss.

Standardlauf mit Upload

Set-ExecutionPolicy -Scope Process Bypass
.\Run-AlphaplanDiscoveryAndUpload.ps1

Das Script prueft/erstellt das SharePoint-Ziel mit rclone mkdir, laedt CSV/TXT hoch und verifiziert danach candidate_objects.csv per rclone lsf.

Lauf fuer bekannte Datenbank

Wenn der Alphaplan-Datenbankname bekannt ist:

.\Run-AlphaplanDiscoveryAndUpload.ps1 -Database "ALPHAPLAN"

Wenn die SQL-Instanz nicht localhost ist:

.\Run-AlphaplanDiscoveryAndUpload.ps1 -ServerInstance "SERVERNAME\INSTANCE" -Database "ALPHAPLAN"

Lauf mit Samples

.\Run-AlphaplanDiscoveryAndUpload.ps1 -Database "ALPHAPLAN" -ExportSamples

Samples sind auf TOP 200 pro Objekt limitiert. Sie helfen Andreas/DE IT, die Inhalte der Top-Kandidaten schnell zu beurteilen.

SQL Authentifizierung

Windows Integrated ist Default. Fuer SQL-Login:

$cred = Get-Credential
.\Run-AlphaplanDiscoveryAndUpload.ps1 -ServerInstance "SERVERNAME\INSTANCE" -Database "ALPHAPLAN" -SqlCredential $cred

Empfohlen ist ein read-only Benutzer oder Windows-Servicekonto.

rclone Voraussetzungen

rclone muss auf dem DE-Server eingerichtet sein.

Erwarteter Remote-Name:

trafag-bi

Der Remote soll auf die Dokumentbibliothek Shared Documents dieser Site zeigen:

https://trafagag.sharepoint.com/sites/WorldwideBIPlatform

Tests:

rclone lsd trafag-bi:
rclone lsd trafag-bi:"Import/Finance"
rclone lsd trafag-bi:"Import/Finance/Deutschland"

Das Script sucht rclone automatisch an diesen Stellen:

- Parameter -RcloneExe
- rclone.exe im Scriptordner
- C:\Tools\rclone.exe
- C:\Tools\rclone\rclone.exe
- C:\Tools\rclone\rclone\rclone.exe
- rclone aus PATH

Firewall und Berechtigungen

Vom DE-Server benoetigt:

• SQL Zugriff auf die lokale/interne Alphaplan-Datenbank.
• Ausgehend TCP 443 zu Microsoft 365/SharePoint fuer rclone.
• Bei Erstkonfiguration optional Browser-/Device-Login fuer Microsoft 365.

Vom BiDashboard-Server benoetigt:

• Kein direkter SQL-Zugriff auf Alphaplan fuer Phase 1.

SQL-Rechte:

• read-only
• idealerweise Zugriff nur auf benoetigte Datenbanken, Tabellen oder Views
• keine Schreibrechte

Abgrenzung zum finalen Import

Phase 1 erzeugt noch kein finales Finance-Format. Ziel ist nur:

• richtige Datenbanken finden
• relevante Tabellen/Views finden
• Feldnamen und Beziehungen erkennen
• Beispiele fuer Andreas/DE IT bereitstellen

Der spaetere Import kann danach auf eine finale SQL-View oder ein gemapptes CSV umgestellt werden. Empfohlene finale View:

vw_BiDashboard_FinanceSales_DE

Checkliste fuer DE/IT

Nach dem ersten Discovery-Lauf bitte pruefen:

• Welche Datenbank ist Alphaplan produktiv?
• Welche Tabelle/View ist Rechnungs-Kopf?
• Welche Tabelle/View ist Rechnungs-Position?
• Wie werden Kopf und Position verbunden?
• Welche Spalte ist Rechnungsnummer?
• Welche Spalte ist Positionsnummer?
• Welche Spalte ist Rechnungsdatum oder Buchungsdatum?
• Welche Spalte ist Nettoumsatz auf Positionsebene?
• Welche Spalte ist Menge?
• Welche Spalte ist Artikel-/Materialnummer?
• Welche Spalten enthalten Kundenname, Kundennummer und Kundenland?
• Wie erkennt man Gutschriften?
• Wie erkennt man Stornos?
• Gibt es eine Aenderungs-/Erfassungsdatumsspalte fuer Delta?

Bekannte Grenzen

• Discovery erkennt Kandidaten heuristisch anhand von Namen. Tabellen mit neutralen Alphaplan-Namen koennen fehlen.
• Wenn SQL-Rechte zu eng sind, sind die CSV leer oder unvollstaendig.
• RowCountEstimate ist eine SQL-Server-Schaetzung aus Partition-Stats.
• Sample-Dateien sind nur Auszuege und nicht fuer Summenabgleich geeignet.
• Der Upload prueft aktuell candidate_objects.csv, nicht jede einzelne Sample-Datei.

Naechster Schritt

1. ZIP auf DE-Server kopieren.
2. Discovery lokal ohne Upload ausfuehren.
3. candidate_objects.csv pruefen.
4. Discovery mit Upload ausfuehren.
5. Andreas/DE IT markiert die relevanten Alphaplan-Objekte.
6. Danach wird der finale Alphaplan-Finance-Export oder die Importanpassung definiert.