In diesem How-to zeige ich Schritt für Schritt, wie du Kreditoren aus einer Excel-Datei in Microsoft Dynamics 365 Business Central importierst – mit SQL Server Integration Services (SSIS) und dem KingswaySoft Integration Toolkit für Business Central.
Ziel: Upsert (anlegen oder aktualisieren) anhand der Kreditorennummer
Voraussetzungen
- Visual Studio mit SQL Server Data Tools (SSDT)
- KingswaySoft – SSIS Integration Toolkit for Microsoft Dynamics 365 Business Central
- Zugriff auf Business Central (Sandbox/Prod), Azure AD App (Client ID/Secret oder Benutzer-Login)
- BC-API erreichbar (z. B.
https://api.businesscentral.dynamics.com/v2.0/<tenant>/<environment>/api/v2.0/), Company-Name bekannt - Excel-Datei, z. B.
Vendors.xlsx, Tabelle Kreditoren mit Spalten:VendorNo, Name, Address, PostCode, City, CountryCode, Phone, Email, CurrencyCode, PaymentTermsCode
Architektur auf einen Blick
Excel (Quelle) → Datenbereinigung (Derived Column / Data Conversion) →
Lookups (Payment Terms etc.) → Business Central Destination (Upsert) → Fehlerausgabe (CSV/SQL).
1) Connection Manager anlegen
1.1 Excel
- Excel Connection Manager → Datei wählen → Tabelle/Range
Kreditoren$.
1.2 Business Central (KingswaySoft)
- Business Central/NAV Connection Manager hinzufügen.
- Service Type: API (empfohlen)
- Authentication: OAuth 2.0 (Authorization Code oder Client Credentials)
- Service URL: deine API-Basis
- Company: exakter Firmenname wie in BC
- Login → Test Connection.
Tipp: Für produktive Läufe besser Client Credentials/Anwendungskonto nutzen.
2) Datenfluss (Data Flow) aufbauen
2.1 Quelle: Excel Source
- Table/View:
Kreditoren$.
2.2 Typen & Bereinigung
- Data Conversion: Strings auf DT_WSTR (passende Länge), Postleitzahl nicht in Zahl umwandeln.
- Derived Column (Beispiele):
Email = TRIM(LOWER(Email))CountryCode = UPPER(SUBSTRING(CountryCode,1,2))DisplayName = REPLACENULL(Name, "—")Number = TRIM(VendorNo)
2.3 Lookups (IDs statt Codes)
Viele BC-API-Felder erwarten IDs. Beispiel Payment Terms:
- Business Central Source (KingswaySoft)
- Entity:
paymentTerms - Spalten:
id, code - Lookup Transformation
- Join
PaymentTermsCode(Excel) →code(BC) - Rückgabe:
paymentTermsId - Fehlende Treffer → No Match Output in eine Error-CSV leiten.
(Analog möglich für Currency, Payment Method usw., falls im Ziel benötigt.)
2.4 Ziel: Business Central Destination (Upsert)
- Business Central Destination (KingswaySoft)
- Action: Upsert
- Entity:
vendors - Upsert Key:
number
Mapping (typisch & “API-sicher”):
| BC vendors Feld | Quelle (SSIS) |
|---|---|
| number | Number |
| displayName | DisplayName |
| phoneNumber | Phone |
| currencyCode | CurrencyCode |
| paymentTermsId | Lookup-Ergebnis |
| address.street | Address |
| address.city | City |
| address.postalCode | PostCode |
| address.countryLetterCode | CountryCode |
Nicht jedes BC-Feld ist in der Standard-API vorhanden. Für zusätzliche Felder (z. B. Posting Groups) entweder Custom API Page per Extension bereitstellen oder die OData Page nutzen und im Destination-Component entsprechend auswählen.
2.5 Fehlerpfad
- Error Output der Destination auf Flat File oder SQL-Tabelle:
RowData, ErrorCode, ErrorColumn, ErrorDescription.
3) Paket steuern & absichern
- Batch Size/Concurrency im KingswaySoft-Ziel moderat halten (API-Throttling vermeiden).
- Retry mit Backoff aktivieren (KingswaySoft hat eingebaute Retry-Optionen).
- Partial Commit: Bei großen Dateien in Chunks laden (z. B. 5–10k Zeilen).
- Preview Run (Sandbox): erst 10–50 Zeilen testen.
4) Beispiel: Minimaler Excel → Vendor-Mapping
| Excel-Spalte | BC vendors Feld |
|---|---|
| VendorNo | number |
| Name | displayName |
| Address | address.street |
| PostCode | address.postalCode |
| City | address.city |
| CountryCode | address.countryLetterCode |
| Phone | phoneNumber |
| CurrencyCode | currencyCode |
| PaymentTermsCode | paymentTermsId (Lookup) |
5) Typische Fehler & Fixes
| Fehlercode / Meldung | Ursache & Lösung |
|---|---|
| 401/403 | OAuth/Permission prüfen: App-Registrierung, Benutzerrechte, Company |
| 422 (Unprocessable Entity) | Pflichtfeld fehlt oder falscher Datentyp (z. B. falsches Länderformat) |
| 429 (Too Many Requests) | Drosselung → Batch kleiner, Retry aktivieren |
| Invalid navigation property | Feld nicht in API vorhanden → Custom API Page oder anderes Endpoint wählen |
6) Optional: Staging & QS
- Excel erst in SQL-Staging laden (Flat File/Excel → OLE DB Destination).
- Dort Validierungen (E-Mail-Pattern, Duplikate VendorNo, Referenz-Mappings).
- Danach sauberen Staging-View als Quelle für den BC-Load nutzen.
7) Deployment & Betrieb
- SSIS-Projekt in SSIS Catalog (SSISDB) deployen.
- Environment-Parameter (Tenant, Environment, Company, ClientId/Secret, API-URL) konfigurieren.
- SQL Agent Job einrichten (manuell/zeitgesteuert).
- Logging in SSIS Catalog Reports + eigene Fehler-CSV/SQL-Tabelle.
Checkliste Go-Live
- Sandbox-Test erfolgreich (inkl. Lookups)
- Dedupe-Strategie (Upsert über number)
- Retry/Backoff aktiv
- Fehlerpfad geprüft
- Berechtigungen/Compliance geklärt
Schreibe einen Kommentar