Microsoft Dynamics 365 Business Central

Der Workist Integrator ist eine App für Microsoft Dynamics 365 Business Central, die Ihr Business-Central-System mit der Workist-Plattform verbindet. Sie synchronisiert die notwendigen Stammdaten aus Business Central mit Workist und legt fertig verarbeitete Belege – zum Beispiel Verkaufsaufträge – automatisch in Business Central an.

Sie führt von einer allgemeinen Übersicht über Installation und Einrichtung bis hin zu Betrieb, Fehlerbehebung und einer technischen Referenz.

Übersicht

Der Workist Integrator wird als Per-Tenant-Extension (PTE) in Ihrer Business-Central-Umgebung installiert. Er erfüllt im Wesentlichen zwei Aufgaben:

• Stammdaten aus Business Central an Workist senden, damit Workist Ihre Belege korrekt auslesen und zuordnen kann.
• Fertig verarbeitete Belege aus Workist in Business Central anlegen und die erzeugte Belegnummer an Workist zurückmelden.

Funktionsweise

• Die App wird als PTE in Ihrem Business Central installiert.
• Die zu synchronisierenden Stammdaten werden in der App ausgewählt und über eine REST-API an Workist übertragen – standardmäßig einmal täglich (nächtlicher Job, konfigurierbar).
• Die App prüft in regelmäßigen Abständen, ob in Workist fertige Belege vorliegen, und importiert diese über die REST-API.
• Um die Systemlast gering zu halten, werden die benötigten Stammdaten vor der Übertragung in Puffertabellen in Ihrem Business-Central-System gesammelt.
• Die App führt API-Protokolle, mit denen sich Fehlermeldungen analysieren lassen.
• Nachdem ein Verkaufsauftrag in Business Central angelegt wurde, wird die Business-Central-Belegnummer an Workist zurückgemeldet – so bleibt der Beleg durchgängig nachverfolgbar.

Wichtige Funktionen

Der Workist Integrator deckt unter anderem folgende Vorgänge ab:

• Kunden nach Workist synchronisieren
• Artikel inklusive Lieferantenartikel nach Workist synchronisieren
• Kundenartikel (Artikelreferenzen für Kunden) nach Workist synchronisieren
• Lieferadressen der Kunden nach Workist synchronisieren
• Bestellzeilen (Purchase Order Lines) nach Workist synchronisieren
• Verkaufsaufträge aus Workist übernehmen und in Business Central anlegen
• Die Auftragsanlage an Workist zurückmelden
• Bestellungen aus Workist übernehmen
• Verkaufsangebote als Stammdaten für den Angebotsabgleich nach Workist synchronisieren
• Rechnungsadressen (abweichende Rechnungsanschriften der Kunden) nach Workist synchronisieren

Alle Synchronisierungsvorgänge laufen als Aufgabenwarteschlangenposten (Job Queue Entries) und lassen sich an Ihre Prozesse anpassen (siehe Betrieb).

Kompatibilität und Voraussetzungen

• Business Central 23.2 oder höher (die App wird gegen Application 23.2 gebaut).
• Administrative Berechtigungen für die Installation als Per-Tenant-Extension.
• REST-API-Kommunikation (HttpClient). In Sandbox-Umgebungen muss dafür die Option „Allow HttpClient Requests" in den Erweiterungseinstellungen aktiviert sein.
• Ein API-Schlüssel sowie die benötigten Lookup-Definition-IDs – beide erhalten Sie auf der Seite zur Kanalverwaltung in Workist.

Installation

Die Installation ist in der Regel unkompliziert und dauert üblicherweise nur wenige Minuten. Es entstehen keine zusätzlichen Kosten für die Implementierung.

Voraussetzungen

• Sie benötigen administrative Berechtigungen in Ihrer Business-Central-Umgebung.
• Sie erhalten das App-Paket als *.app-Datei von Workist. Speichern Sie diese Datei auf einem lokalen Laufwerk – Netzlaufwerke oder freigegebene Laufwerke funktionieren nicht in jedem Fall.

App als Per-Tenant-Extension installieren

1. Navigieren Sie in Business Central zur Seite „Erweiterungsverwaltung" (Extension Management).
2. Verwenden Sie im Menü „Verwalten" die Aktion „Erweiterung hochladen" (Upload extension) und wählen Sie die von Workist erhaltene *.app-Datei aus.
3. In der Regel stellen Sie das App-Paket für die aktuelle Version bereit. Wählen Sie als Schema-Synchronisierungsmodus immer „Add" (Hinzufügen) – es sei denn, Sie werden ausdrücklich um etwas anderes gebeten.
4. Bestätigen Sie die Datenschutzrichtlinie und den Haftungsausschluss und klicken Sie anschließend auf „Bereitstellen" (Deploy).

Auf der Seite „Status der Erweiterungsinstallation" (Extension Installation Status) können Sie den Fortschritt verfolgen. Im Fehlerfall finden Sie hier ebenfalls detaillierte Informationen.

Kein Downgrade möglich

Eine Erweiterung lässt sich nicht „herunterstufen". Beim Bereitstellen prüft Microsoft die Versionsnummer des gewählten *.app-Pakets gegen die bereits installierte Version. Die Versionsnummer des hochzuladenden Pakets muss höher sein als die der bereits installierten Erweiterung.

Sandbox-Umgebungen

In Sandbox-Umgebungen müssen Sie in den Erweiterungseinstellungen die Option „Allow HttpClient Requests" aktivieren. Ohne diese Einstellung kann die Erweiterung nicht über die REST-API kommunizieren.

Sollten während der Installation als PTE Probleme auftreten, deren Lösung hier nicht beschrieben ist – etwa ein bereits von einer anderen Erweiterung belegter Objekt-ID-Bereich –, wenden Sie sich bitte an Ihren Workist-Ansprechpartner.

Wartung und Updates

App-Updates im Rahmen von Business-Central-Updates werden von Workist übernommen. Laufende Fehlerbehebung und Weiterentwicklung der Plattform sind in Ihrem Workist-Paket enthalten.

Einrichtung

Bevor Sie den Workist Integrator nutzen können, müssen Sie ihn einrichten. Die dafür erforderlichen Angaben finden Sie auf der Seite zur Kanalverwaltung in Workist.

Suchen Sie in Business Central nach „Workist Integrator-Einrichtung". Dort finden Sie alle relevanten Einstellungen zur Workist-Integration.

API-Schlüssel und Verbindung

Das Feld für den API-Endpunkt dient nur zur Information; es ist nicht editierbar und kann nur von Workist per App-Update geändert werden.

Der REST-API-Schlüssel ist die Grundlage jeder Kommunikation mit der Workist-API und die erste Einstellung, die Sie vornehmen. Ohne API-Schlüssel funktioniert keiner der Synchronisierungsvorgänge. Wie Sie einen Token erstellen bzw. abrufen, beschreibt der Abschnitt API-Zugriffstoken erstellen im Quickstart der API-Dokumentation; fügen Sie ihn anschließend per Kopieren & Einfügen hier ein.

Beim Aktivieren des Workist Integrator werden der API-Schlüssel und die Verbindung geprüft. Tritt dabei ein Fehler auf, wechselt der Status „Aktiviert" automatisch zurück auf aus. Nach erfolgreicher Aktivierung lässt sich der API-Schlüssel nicht mehr ändern, solange die Verbindung aktiviert ist – deaktivieren Sie die Verbindung dafür zunächst.

Aufgabenwarteschlangen-Kategorie

Bei der Installation wird eine eindeutige Aufgabenwarteschlangen-Kategorie (Job Queue Category) angelegt. Sie trennt die Aufgaben von Workist von anderen regelmäßig laufenden Aufgaben. Sie können die Kategorie für die Workist-Posten ändern, sie darf jedoch nicht leer sein.

Wiederholungen fehlgeschlagener Tasks

Legt fest, wie oft ein fehlgeschlagener Task wiederholt wird. Führt ein API-Task zu einem Fehler, wird er entsprechend oft im Abstand von jeweils 5 Minuten wiederholt.

API-Protokoll-Detailgrad

Der API-Protokoll-Detailgrad (API Log Detail Level) steuert die Ausführlichkeit der Protokollierung für alle API-Interaktionen zwischen Business Central und Workist. Die Einstellung wurde eingeführt, um Performance- und Speicherprobleme in Umgebungen mit hohem Belegaufkommen zu vermeiden, in denen übermäßige Protokollierung schnell zu Millionen von Datenbankeinträgen pro Monat und damit zu erhöhter Datenbanklast führen kann.

Detailgrad	Beschreibung
None	Deaktiviert die API-Protokollierung vollständig. Mit äußerster Vorsicht einzusetzen, da keinerlei Einblick in API-Vorgänge oder Fehler mehr besteht.
Errors Only (Standard)	Protokolliert nur HTTP-Fehler, kritische Ausfälle und fehlgeschlagene Tasks. Empfohlene Einstellung für Produktivumgebungen: essenzielle Fehlersicht bei minimaler Datenbanklast.
Warnings	Protokolliert zusätzlich Warnungen wie Wiederholungsversuche oder unkritische Hinweise. Nützlich zur Überwachung oder bei der Analyse sporadischer Probleme.
Verbose	Protokolliert alles, inklusive erfolgreicher API-Aufrufe sowie Request-/Response-Details. Höchstes Protokollvolumen – nur vorübergehend zur Fehlersuche oder bei der Ersteinrichtung verwenden.

Empfehlungen:

• Produktivumgebungen: „Errors Only" für optimale Performance bei gleichzeitiger Sichtbarkeit kritischer Probleme.
• Test-/Staging-Umgebungen: „Warnings" oder „Verbose", um bei Tests detaillierte Informationen zu erfassen.
• Fehlersuche: vorübergehend auf „Verbose" umstellen und nach der Klärung wieder auf „Errors Only" zurückstellen.
• Ersteinrichtung: während der ersten Synchronisierungsläufe „Verbose" zur Validierung der Konfiguration, danach „Errors Only".

Eine Änderung des Detailgrads wirkt sofort und gilt für alle nachfolgenden API-Vorgänge. Bereits vorhandene Protokolleinträge sind davon nicht betroffen.

Kundendaten

In der Gruppe Kundendaten tragen Sie die Client Lookup Definition ID ein, die Sie auf Ihrer Workist-Kanalverwaltungsseite erhalten. Sobald die ID hinterlegt ist, können Sie die Kundensynchronisierung aktivieren. Ohne hinterlegte Lookup-Definition-ID schlägt die Aktivierung fehl.

Mit der Aktivierung wird ein Aufgabenwarteschlangenposten angelegt, der die Synchronisierung regelmäßig ausführt und einmalig sofort startet. Standardmäßig läuft er alle 1.440 Minuten (24 Stunden). Intervall und Tage können Sie in den Aufgabenwarteschlangenposten manuell anpassen.

Wie beim API-Schlüssel lässt sich die Lookup-Definition-ID nicht ändern, solange die Synchronisierung aktiviert ist – deaktivieren Sie sie dafür zunächst. Die Kunden-Puffergröße zeigt die Anzahl der beim letzten Lauf synchronisierten Kunden.

Artikeldaten

In der Gruppe Artikeldaten tragen Sie die Article Lookup Definition ID von Ihrer Workist-Kanalverwaltungsseite ein und aktivieren anschließend die Artikelsynchronisierung. Zeitplan und Sperrregeln entsprechen der Kundensynchronisierung (standardmäßig alle 1.440 Minuten, anpassbar; ID nur bei deaktivierter Synchronisierung änderbar). Die Artikel-Puffergröße zeigt die Anzahl der beim letzten Lauf synchronisierten Artikel.

Kundenspezifische Artikel: Wenn Sie kundenspezifische Artikel (Artikelreferenzen) synchronisieren möchten, tragen Sie die Debtor Article Lookup Definition ID ein und aktivieren „Customer Item Sync". Diese Synchronisierung läuft nicht als separate Routine, sondern ergänzt lediglich die Artikelreferenzen für Kunden in der Artikelliste, die vom Artikel-Synchronisierungsjob verwendet wird.

Lieferantenartikel: Artikel mit gepflegter Lieferantenartikelnummer (Vendor Item No.) erzeugen bei jedem Artikellauf einen zusätzlichen Eintrag. Dieser trägt dieselbe BC-Artikelnummer als article_id1 und die Lieferantenartikelnummer als article_id2, sodass Workist die Artikelkennung des Lieferanten als alternativen Suchschlüssel erkennt. Kann bei der Auftrags- oder Rechnungsanlage eine eingehende article_number nicht der BC-Artikelnummer zugeordnet werden, versucht die Integration die Zuordnung automatisch über die Lieferantenartikelnummer, bevor als letzte Stufe die Artikelreferenz herangezogen wird.

Auftragsimport

Um den Auftragsimport aus Workist zu aktivieren, schalten Sie die Option „Import and create orders" ein. Der Auftragsimport-Job läuft zunächst jede Minute; Sie können die Einstellungen des Aufgabenwarteschlangenpostens nach Bedarf anpassen.

Enthält ein eingehender Workist-Auftrag eine quote_number, wandelt die Integration das passende Verkaufsangebot automatisch mit der Standardfunktion von Business Central in einen Verkaufsauftrag um. Die Standard-Kopffelder (Kunde, Adresse, Datumsangaben usw.) werden aus dem Angebot übernommen. Zwei Felder stammen jedoch stets aus dem eingehenden Auftrag: die Externe Belegnummer (die Bestellnummer des Kunden) und „Ihr Zeichen" (die Kommissionsnummer) – diese unterscheiden sich erwartungsgemäß zwischen Angebot und bestätigtem Auftrag. Die automatisch erzeugten Zeilen aus der Umwandlung werden gelöscht und durch die Zeilendaten aus Workist ersetzt. Das Verkaufsangebot wird gemäß den Archivierungseinstellungen in der Debitoren & Verkauf Einrichtung automatisch archiviert.

Angebotsabgleich

In der Gruppe Angebotsabgleich tragen Sie die Offer Matching Lookup ID von Ihrer Workist-Kanalverwaltungsseite ein und aktivieren anschließend die Angebotssynchronisierung. Der Job läuft standardmäßig alle 60 Minuten (anpassbar); die ID lässt sich nur bei deaktivierter Synchronisierung ändern. Der Zähler Sent Offers zeigt die Anzahl der beim letzten Lauf synchronisierten Angebotszeilen.

Rechnungsadressen

In der Gruppe Rechnungsadressen tragen Sie die Invoice Address Lookup Definition ID von Ihrer Workist-Kanalverwaltungsseite ein und aktivieren anschließend die Synchronisierung der Rechnungsadressen (standardmäßig alle 1.440 Minuten, anpassbar).

Die Synchronisierung sendet alle nicht gesperrten Debitoren an den Adress-Lookup-Endpunkt von Workist. Die Debitorennummer (No.) dient dabei sowohl als partition_id (zur Identifikation des Kunden) als auch als address_id1 (Adresskennung) – der Stammdatensatz des Kunden dient also unmittelbar als seine Rechnungsadresse. Die ID lässt sich nur bei deaktivierter Synchronisierung ändern. Der Zähler Sent Invoice Addresses zeigt die Anzahl der beim letzten Lauf synchronisierten Adressen.

Betrieb

Alle Synchronisierungsvorgänge laufen als Aufgabenwarteschlangenposten unter der Workist-Kategorie. Wenn Sie den Eindruck haben, dass eine Synchronisierung nicht wie vorgesehen läuft, sind die Aufgabenwarteschlangenposten ein guter Ausgangspunkt für die Analyse. Ein fehlerhafter Workist-Posten trägt eine Fehlermeldung direkt am Aufgabenwarteschlangenposten.

Synchronisierungs-Jobs verwalten

Jobs deaktivieren und aktivieren

Deaktivieren bzw. aktivieren Sie den jeweiligen Job auf der Seite „Workist Integrator-Einrichtung" über die zugehörigen Umschalter (Toggle-Buttons).

Deaktivierte Jobs löschen

Ein Job kann in der Detailansicht gelöscht werden. Das ist nur möglich, wenn der Job zuvor den Status „Abwarten" hat.

Adressfeld-Aufteilung

Workist kann mehrere Adressbestandteile (z. B. Straßenname und Hausnummer) in einer einzigen Zeichenkette street_and_nr beliebiger Länge zusammenfassen. Die Adressfelder in Business Central sind jedoch begrenzt: 100 Zeichen für die erste Adresszeile („Adresse") und 50 Zeichen für die zweite Zeile („Adresse 2").

Wird eine Adresse direkt aus der API-Antwort geschrieben (also wenn kein BC-Datensatzcode bzw. keine ID Vorrang hat), teilt der Integrator jede street_and_nr mit mehr als 100 Zeichen automatisch auf:

1. Intelligente Trennung an der Wortgrenze: Der Integrator sucht ab Position 100 rückwärts nach dem nächsten Leerzeichen innerhalb eines Fensters von 15 Zeichen (Position 86–100). Wird ein Leerzeichen gefunden, wird dort getrennt – der Teil davor kommt in „Adresse", der Teil danach in „Adresse 2" (auf 50 Zeichen gekürzt).
2. Harte Trennung als Rückfall: Wird im Suchfenster kein Leerzeichen gefunden, wird exakt an Position 100 getrennt.
3. Kurze Adressen: Ist street_and_nr höchstens 100 Zeichen lang, wird sie unverändert in „Adresse" geschrieben und „Adresse 2" bleibt leer.

Die Aufteilung wird über alle Belegimport-Prozesse hinweg einheitlich angewendet (Verkaufsaufträge, RFQ/Verkaufsangebote, Eingangsrechnungen).

Lieferadressen-Behandlung

Beim Synchronisieren von Aufträgen werden Lieferadressen wie folgt verarbeitet:

1. Abgleich über den Adresscode: Stimmt delivery_address.number mit einer vorhandenen Lieferadresse (Ship-to Address) in Business Central überein, wird der Code auf den Verkaufsauftrag übernommen.
2. Felder name und misc: Die Felder delivery_address.name und delivery_address.misc werden immer auf den Verkaufsauftrag übertragen, auch wenn ein Adresscode verwendet wird. Sie überschreiben die hinterlegten Lieferadressinformationen – jedoch nicht, wenn sie in Workist leer sind.

Workist-Feld	BC-Feld	Immer übertragen
delivery_address.number	Ship-to Code	wenn Treffer gefunden
delivery_address.name	Ship-to Contact	✓ ja
delivery_address.misc	Ship-to Name 2	✓ ja
delivery_address.street_and_nr	Ship-to Address	wenn kein Code passt
delivery_address.postal_code	Ship-to Post Code	wenn kein Code passt
delivery_address.city	Ship-to City	wenn kein Code passt

Hinweise: Leere Werte aus Workist werden ignoriert – vorhandene BC-Werte bleiben erhalten. Adressen über 100 Zeichen werden gemäß Adressfeld-Aufteilung auf „Adresse" und „Adresse 2" verteilt. Bereits bestehende Aufträge sind nicht betroffen (nur neue Synchronisierungen).

Fehlerbehebung

Fehler beim Auftragsimport und Wiederholungsverhalten

Schlägt ein Auftragsimport in Business Central fehl (z. B. wegen Validierungsfehlern, fehlender Stammdaten oder Systemproblemen), versucht der Workist Integrator, Workist zu benachrichtigen, indem er den Auftrag über den API-Endpunkt /orders/{id}/mark_imported als FAILED markiert.

• Automatische Wiederholung: Die Integration wiederholt den PUT-Request bis zu fünfmal, falls der erste Versuch scheitert. Die Wartezeiten steigen linear (1 s, 2 s, 3 s, 4 s), zusätzlicher Zeitaufwand maximal ca. 10 Sekunden pro fehlgeschlagenem Auftrag.
• Auslöser für Wiederholungen: HTTP-Fehler der Workist-API (4xx, 5xx), Netzwerkfehler oder Zeitüberschreitungen sowie vorübergehende Nichtverfügbarkeit der API.
• Erfolgreiche Antworten: Antwortet Workist mit einem Erfolgsstatus (2xx), wird der Auftrag sofort als FAILED markiert, es erfolgt keine Wiederholung, und im API-Protokoll wird ein Erfolgseintrag erstellt.

Sind nach fünf Versuchen alle Wiederholungen erschöpft, gilt:

1. Status in Workist: Der Auftrag verbleibt in der Importwarteschlange von Workist (imported=false, import_failed=false).
2. Protokollierung: In Business Central wird ein kritischer Fehler im API-Protokoll erzeugt (CRITICAL: Failed to mark order [Order ID] as FAILED after 5 attempts.).
3. Folge: Der Auftrag wird in den folgenden Synchronisierungsläufen (standardmäßig jede Minute) wiederholt abgerufen, was zu vielen Protokolleinträgen führen kann.
4. Erforderliche Maßnahme: Es ist ein manueller Eingriff notwendig.

Workist API-Protokoll

Detaillierte Fehlerinformationen finden Sie auf der Seite „Workist API Log" in Business Central:

• Filtern Sie nach Status = „Error", um fehlgeschlagene Vorgänge zu finden.
• Achten Sie auf Einträge mit „CRITICAL" oder „Failed to mark order".
• Prüfen Sie die Felder für HTTP-Statuscode und Response auf detaillierte Fehlerinformationen.
• Nutzen Sie die Task Entry No., um Fehler bestimmten Synchronisierungsläufen zuzuordnen.

Empfehlungen

• Überwachen Sie das API-Protokoll regelmäßig (täglich oder wöchentlich), um stecken gebliebene Aufträge früh zu erkennen, bevor sie übermäßig viele Protokolleinträge erzeugen.
• Ursache prüfen: Ermitteln Sie in den Business-Central-Protokollen, warum der Auftragsimport ursprünglich fehlgeschlagen ist.
• Manuelle Lösungsmöglichkeiten: Auftragsdaten in Workist korrigieren und den Importstatus zurücksetzen; den Auftrag direkt in Workist als importiert markieren; Stammdatenprobleme in Business Central beheben (fehlende Kunden, Artikel usw.); bei anhaltenden API-Verbindungsproblemen den Workist-Support kontaktieren.
• Passen Sie bei wiederholten Fehlern gegebenenfalls das Intervall des Auftragsimport-Jobs an.

Technische Referenz

Berechtigungen

Der Workist Integrator wird mit einem einzigen Berechtigungssatz ausgeliefert. Dieser enthält RMID/X-Berechtigungen auf allen Objekten der App. Für granularere Berechtigungen müssen Sie einen eigenen Berechtigungssatz anlegen. Der Objektbereich des Workist Integrator ist 56000 bis 56499.

Feldzuordnungen

Für jeden Prozess bildet der Workist Integrator die Felder der Workist-API auf konkrete Business-Central-Tabellen und -Felder ab – mit Richtung (eingehend/ausgehend), API-Endpunkt und betroffenen Objekten. Abgedeckt sind unter anderem Verkaufsaufträge, RFQ/Verkaufsangebote, Kunden, Artikel und Kundenartikel, Liefer- und Rechnungsadressen, Bestellungen, Bestellbestätigungen, Lieferscheine sowie Eingangsrechnungen. Eine vollständige, feldgenaue Referenz stellen wir Ihnen auf Anfrage über Ihren Workist-Ansprechpartner bereit.

Integration Events

Der Workist Integrator löst zahlreiche Integration Events aus, mit denen Entwickler eigene Geschäftslogik in die Import- und Synchronisationsprozesse einklinken können – für den Import von Verkaufsaufträgen, Lieferscheinen, Eingangsrechnungen und RFQ sowie für Job-Queue- und API-Task-Handling (z. B. OnBeforeFinalizeSalesHeader oder OnAfterFinalizeSalesLine). Die vollständige Liste mit AL-Codebeispielen stellen wir Ihnen auf Anfrage über Ihren Workist-Ansprechpartner bereit.

App-Version

Diese Dokumentation beschreibt den Workist Integrator ab Version 24.0.4.68. Den vollständigen Änderungsverlauf (Changelog) erhalten Sie über Ihren Workist-Ansprechpartner.

Hinweise und Feedback

Vereinzelt können Feldbeschriftungen oder Tooltips unvollständig oder ungenau übersetzt sein. Über einen entsprechenden Hinweis freuen wir uns – ebenso über Vorschläge, Ideen und Fehlermeldungen. Bei Fragen erreichen Sie uns unter support@workist.com.