# Workist Dokumentation > Aufträge und Anfragen automatisiert verarbeiten --- Source: https://docs.workist.com/docs.md # Workist Dokumentation Willkommen in der Workist-Dokumentation. Workist verarbeitet Aufträge und Anfragen automatisiert — Ihr KI-Agent für den Vertrieb. ## Wie funktioniert Workist? Der Workist-Agent erkennt automatisch Aufträge, liest relevante Informationen aus, validiert diese anhand der Stammdaten und überträgt schließlich alles eigenständig ins ERP-System. Bei Fehlern oder Unsicherheiten wird das Team proaktiv um Hilfe gebeten, um eine korrekte Übertragung zu garantieren. ## Kernfunktionen - **Vorlagenfrei** — die Workist-KI versteht Kontexte; keine starren Layouts, keine festen Regeln. - **ERP-integriert** — tiefe Kompatibilität mit SAP, Microsoft Dynamics, Sage und weiteren Systemen. - **Zero-Touch** — automatischer Abgleich mit Stammdaten für hohe Genauigkeit vor dem Export. - **Selbstlernend** — das System wird mit jedem Dokument und jeder Interaktion besser. ## Für wen ist es gedacht? B2B-Hersteller und Distributoren, die ein hohes Transaktionsvolumen bewältigen und die manuelle Dateneingabe beenden möchten — um Abläufe zu optimieren, ohne bestehende Workflows zu stören. **Was Sie benötigen:** Ihr aktuelles ERP-System, Ihre Standard-Geschäftsdokumente (PDFs, Excel) und eine schnelle Integration. ## Erste Schritte - **[Implementierungsleitfaden](/docs/implementation-guide.md)** — die Selbst-Einrichtung von Workist in fünf Schritten. - **[Kanal-Konfiguration](/docs/channel-configuration.md)** — alle Einstellungen eines Verarbeitungskanals im Detail. - **[Stammdaten](/docs/master-data.md)** — Grundlage für den automatischen Abgleich. - **[Datenaustausch](/docs/data-exchange.md)** — SFTP, API und Konnektoren. - **[KI-Assistenten](/docs/ai-assistants.md)** — diese Dokumentation in Claude und anderen KI-Assistenten nutzen. --- Source: https://docs.workist.com/docs/smart-inbox.md # Workist Smart Inbox Die Workist Smart Inbox verbindet Microsoft-Outlook-Postfächer mit Workist, sodass eingehende E-Mails automatisch klassifiziert werden – als Bestellung, Preisanfrage (RFQ), Rechnung, Auftragsbestätigung oder Sonstiges. So gelangen relevante Dokumente ohne manuelles Weiterleiten in die richtigen Workist-Kanäle. ## Zwei Varianten Es gibt zwei Varianten der Smart Inbox – je nachdem, welche Art von Postfach Sie verbinden möchten: - Shared Smart Inbox – der häufigste Anwendungsfall: Teams verbinden gemeinsam genutzte Outlook-Postfächer (Sammelpostfächer). Workist klassifiziert eingehende E-Mails und wendet Aktionen an, etwa das Verschieben in Ordner oder das Markieren als gelesen. - Persönliche Smart Inbox – Mitarbeitende verbinden ihr individuelles Outlook-Postfach. Workist klassifiziert eingehende E-Mails und versieht sie direkt in Outlook mit Tags (z. B. Bestellungen oder Preisanfragen). Jede Variante hat einen eigenen Admin-Guide, der die angeforderten Berechtigungen erläutert und die Erteilung der Admin-Zustimmung Schritt für Schritt beschreibt. ## Admin-Zustimmung Damit Workist auf die Postfächer zugreifen darf, muss ein Outlook-Administrator der Anwendung einmalig die erforderlichen Microsoft-Graph-Berechtigungen erteilen (Admin-Zustimmung). Den Link dafür zeigt die Workbench an, solange die Zustimmung fehlt. Kopieren Sie ihn mit „Link kopieren“ und schicken Sie ihn an Ihren Outlook-Administrator. | Variante | Wo der Link steht | Wer ihn sieht | |---|---|---| | Shared Smart Inbox | „Einstellungen“ → Navigation links unter „Workflow-Tools“ → „Smart Inbox“ | Benutzer mit der Rolle Manager oder Admin | | Persönliche Smart Inbox | Name links unten → „Dein Profil“ → Bereich „Persönliche Smart Inbox für Outlook“ | Benutzer mit der Rolle Member, Manager, IT oder Admin | Bringt Workist neue Funktionen, die weitere Berechtigungen brauchen (z. B. benutzerdefinierte Kategorien), zeigt die Workbench den Hinweis „Administratorgenehmigung erforderlich“ mit einem neuen Link. Die Rollen sind unter [Benutzer und Rollen](/docs/administration/users-and-roles.md) beschrieben. ## Shared Smart Inbox einrichten Nach der Admin-Zustimmung verbinden Benutzer mit der Rolle Manager oder Admin die Postfächer unter „Einstellungen“ → „Workflow-Tools“ → „Smart Inbox“ → „Integration konfigurieren“. Dabei legen Sie Name und Postfachadresse fest und wählen für jede Dokumentart (Bestellung, Auftragsbestätigung, Preisanfrage, Rechnung) den Kanal, in dem Workist die Dokumente anlegt. Die Kanäle lassen sich später nicht mehr ändern. Über das Menü eines Postfachs → „Verwalten“ passen Sie das Verhalten an: - **Unverarbeitete Dokumente:** E-Mails, die eines der angegebenen Stichwörter enthalten oder von einer der angegebenen Adressen oder Domains kommen, legt Workist nicht als Dokument an. Sie bleiben zur manuellen Bearbeitung im Postfach. - **Ereignisse:** Für jede Dokumentart legen Sie fest, was in Outlook passiert, wenn ein Dokument z. B. angelegt, abgeschlossen, verworfen oder gelöscht wurde: E-Mail in einen Outlook-Ordner verschieben und/oder als gelesen markieren. - **Benutzerdefinierte Kategorien:** siehe nächster Abschnitt. ## Benutzerdefinierte Kategorien Für E-Mails, die keine Bestellung, Preisanfrage, Rechnung oder Auftragsbestätigung sind, können Sie eigene Kategorien anlegen, zum Beispiel für Lieferreklamationen oder Fragen zu fehlenden Auftragsbestätigungen. Eine KI ordnet jede dieser E-Mails höchstens einer aktiven Kategorie zu, und nur, wenn sie eindeutig passt. Sie finden die Kategorien beim Postfach unter „Verwalten“ → „Benutzerdefinierte Kategorien“ → „Kategorie erstellen“. Als Startpunkt bietet Workist „Empfohlene Kategorien“ an (z. B. „Auftragsbestätigung“ und „Lieferreklamation“). Eine eigene Kategorie beschreiben Sie mit: - **Name** - **Erkennungskriterien:** welche E-Mails dazugehören, in eigenen Worten - **Unterstützende Schlüsselwörter** (optional), die die Erkennung verbessern Für jede Kategorie legen Sie fest, was mit erkannten E-Mails passiert: | Aktion | Wirkung | |---|---| | „Outlook-Tag hinzufügen“ | Die E-Mail erhält in Outlook ein Tag (ein Tag pro Kategorie, Farbe wählbar). | | „In Outlook-Ordner verschieben“ | Die E-Mail wird in den gewählten Outlook-Ordner verschoben. | | „Als gelesen markieren“ | Die E-Mail wird in Outlook als gelesen markiert. | | „Auto-Weiterleitung aktivieren“ | Die E-Mail wird an E-Mail-Adressen weitergeleitet oder in einem Workist-Kanal als Dokument angelegt. | Mit „Pausieren“ und „Fortsetzen“ schalten Sie eine Kategorie vorübergehend ab und wieder an, mit „Löschen“ entfernen Sie sie. Kategorien mit der Kennzeichnung „Agent“ gehören zu einem [KI-Agenten](/docs/agents.md). ## Persönliche Smart Inbox Die Persönliche Smart Inbox ist in der Workbench als **Beta** gekennzeichnet. Jeder Benutzer mit der Rolle Member, Manager, IT oder Admin richtet sie unter „Dein Profil“ für das eigene Postfach ein: 1. „Mit Outlook verbinden“ und bei Microsoft anmelden. 2. Die Kanäle für Bestellungen und Preisanfragen wählen, in die Workist erkannte Dokumente legt. Unter „Ausgeschlossener Inhalt“ geben Sie Schlüsselwörter sowie E-Mail-Adressen oder Domains an. Passende E-Mails bleiben in Ihrem Posteingang und gehen nicht an Workist. Mit „Pausieren“ und „Fortsetzen“ unterbrechen Sie die Weiterleitung vorübergehend, mit „Trennen“ beenden Sie sie. Verliert Workist den Zugriff auf Ihr Postfach, sehen Sie im Profil einen Hinweis und erhalten eine E-Mail (sofern Sie [E-Mail-Benachrichtigungen](/docs/administration/notifications.md) erhalten). Trennen Sie die Persönliche Smart Inbox dann und verbinden Sie sie neu. --- Source: https://docs.workist.com/docs/ai-assistants.md # KI-Assistenten Damit KI-Assistenten Fragen zu Workist anhand dieser Dokumentation beantworten statt aus dem Gedächtnis, stellt Workist einen Skill bereit. Unabhängig davon steht jede Seite als Markdown zur Verfügung. ## Skill „workist-docs“ Der Skill gibt Claude und anderen KI-Agenten Anweisungen für Fragen zu Workist: - Er liest zu jeder Frage die passenden Seiten dieser Dokumentation und antwortet mit dem Pfad in der Kanal-Konfiguration, den exakten Bezeichnungen der Einstellungen und einem Link auf die Seite. - Bevor eine kundenspezifische Anpassung, ein Workaround oder ein Ticket geplant wird, prüft er, ob sich die Anforderung bereits per Konfiguration umsetzen lässt. - Er antwortet in der Sprache der Frage. Der Skill enthält keine Inhalte der Dokumentation, sondern ruft sie bei jeder Frage neu ab. Änderungen an der Dokumentation wirken deshalb sofort; neu installieren müssen Sie den Skill nur, wenn sich der Skill selbst ändert. | Datei | Verwendung | | --- | --- | | [workist-docs.skill](/skills/workist-docs.skill) | Claude Desktop, Installation per Doppelklick | | [workist-docs.zip](/skills/workist-docs.zip) | Upload in Claude im Browser | | [SKILL.md](/skills/workist-docs/SKILL.md) | Claude Code und andere KI-Agenten | ## Einrichtung ### Claude Desktop 1. Laden Sie [workist-docs.skill](/skills/workist-docs.skill) herunter. 2. Öffnen Sie die Datei per Doppelklick. Sie öffnet sich in Claude Desktop. 3. Bestätigen Sie den Import und prüfen Sie unter **Customize → Skills**, dass der Skill aktiviert ist. 4. Geben Sie docs.workist.com frei, siehe [Netzwerkzugriff](#netzwerkzugriff). ### Claude im Browser 1. Laden Sie [workist-docs.zip](/skills/workist-docs.zip) herunter. 2. Öffnen Sie in Claude **Customize → Skills** und laden Sie die ZIP-Datei hoch. 3. Aktivieren Sie den Skill. 4. Geben Sie docs.workist.com frei, siehe [Netzwerkzugriff](#netzwerkzugriff). In Team- und Enterprise-Plänen können Admins den Skill mit **Publish to org** für die gesamte Organisation freigeben. ### Netzwerkzugriff Damit Claude Desktop und Claude im Browser die Dokumentation abrufen können, muss docs.workist.com freigegeben sein: Erlauben Sie die Domain unter **Settings → Capabilities** bei **Allow network egress**. In Team- und Enterprise-Plänen legt das der Owner der Organisation unter **Organization settings → Capabilities** fest. ### Claude Code Für alle Ihre Projekte: ```sh mkdir -p ~/.claude/skills/workist-docs curl -fsSL https://docs.workist.com/skills/workist-docs/SKILL.md -o ~/.claude/skills/workist-docs/SKILL.md ``` Für ein einzelnes Repository legen Sie die Datei stattdessen unter `.claude/skills/workist-docs/SKILL.md` im Repository ab. Dann steht der Skill allen zur Verfügung, die in diesem Repository arbeiten. Damit Claude Code die Dokumentation ohne Rückfrage abrufen darf, erlauben Sie die Domain in `~/.claude/settings.json` oder in `.claude/settings.json` des Repositorys: ```json { "permissions": { "allow": ["WebFetch(domain:docs.workist.com)"] } } ``` ### Andere KI-Agenten Werkzeuge, die den offenen Standard [Agent Skills](https://agentskills.io) unterstützen, zum Beispiel Cursor, GitHub Copilot, Gemini CLI und OpenAI Codex, installieren den Skill mit: ```sh npx skills add https://docs.workist.com/skills/workist-docs/SKILL.md ``` ## Dokumentation als Markdown Für KI-Assistenten ohne den Skill steht die Dokumentation nach dem Standard [llms.txt](https://llmstxt.org) bereit: | Datei | Inhalt | | --- | --- | | [llms.txt](https://docs.workist.com/llms.txt) (Deutsch), [llms.txt](https://docs.workist.com/en/llms.txt) (Englisch) | Verzeichnis aller Seiten mit Kurzbeschreibung | | [llms-full.txt](https://docs.workist.com/llms-full.txt) (Deutsch), [llms-full.txt](https://docs.workist.com/en/llms-full.txt) (Englisch) | Die gesamte Dokumentation in einer Datei | | Adresse einer Seite mit der Endung `.md` | Die einzelne Seite als Markdown, zum Beispiel `https://docs.workist.com/docs/ai-assistants.md` | --- Source: https://docs.workist.com/docs/implementation-guide.md # Implementierungsleitfaden Dieser Leitfaden führt Sie Schritt für Schritt durch die Selbst-Einrichtung von Workist. Folgen Sie den fünf Schritten in der angegebenen Reihenfolge. 1. **[Schritt 1: Verbindung herstellen](/docs/implementation-guide/step-1-establish-connection.md)** 2. **[Schritt 2: Stammdaten konfigurieren und hochladen](/docs/implementation-guide/step-2-configure-and-upload-master-data.md)** 3. **[Schritt 3: Verarbeitungskanal konfigurieren](/docs/implementation-guide/step-3-configure-processing-channel.md)** 4. **[Schritt 4: Ausgabeformat konfigurieren](/docs/implementation-guide/step-4-configure-output-format.md)** 5. **[Schritt 5: Testen](/docs/implementation-guide/step-5-test.md)** --- Source: https://docs.workist.com/docs/implementation-guide/step-1-establish-connection.md # Schritt 1: Verbindung herstellen Bevor Daten zwischen Ihrem ERP-System und Workist ausgetauscht werden können, muss eine Verbindung eingerichtet werden. Workist bietet hierfür zwei Optionen, zwischen denen Sie frei wählen können: | Option | Empfohlen für | |--------|---------------| | **[SFTP](#option-a-sftp)** | Datei-basierter Austausch (z. B. CSV/XML-Exporte aus dem ERP), keine eigene Integration nötig | | **[API](#option-b-api)** | Programmatische Integration und eigene Anwendungen; mit [Webhooks](/docs/data-exchange/webhooks.md) auch ereignisgesteuert | Beide Optionen können auch in Kombination genutzt werden — z. B. Stammdaten per SFTP, Ausgaben per API. Für beide Optionen benötigen Sie ein Workbench-Konto mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). --- ## Option A: SFTP {#option-a-sftp} Workist stellt im Standard einen SFTP-Server bereit, der mittels Public-Key-Authentifizierung gesichert ist. Detaillierte Informationen zu Verzeichnisstruktur, Dateiablage und Testbefehlen finden Sie in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md). Die Einrichtung erfolgt in drei Teilschritten: 1. [SSH-Schlüsselpaar erzeugen](#a1-ssh-schluesselpaar-erzeugen) 2. [Öffentlichen Schlüssel in der Workbench hinterlegen](#a2-oeffentlichen-schluessel-hinterlegen) 3. [Verbindung testen](#a3-verbindung-testen) ### A1 — SSH-Schlüsselpaar erzeugen {#a1-ssh-schluesselpaar-erzeugen} Erzeugen Sie auf Ihrem System ein neues SSH-Schlüsselpaar. Auf macOS oder Linux genügt folgender Befehl: ```bash ssh-keygen -t rsa -b 4096 -C "ihr-team@example.com" -f ~/.ssh/workist_sftp ``` Damit entstehen zwei Dateien: - `~/.ssh/workist_sftp` — der **private** Schlüssel. Diese Datei bleibt ausschließlich auf Ihrem System und darf niemals weitergegeben werden. - `~/.ssh/workist_sftp.pub` — der **öffentliche** Schlüssel. Der Inhalt wird in Schritt A2 in die Workbench eingefügt. Weitere Plattformen (z. B. Windows mit PuTTY) sind in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md#erstellen-eines-ssh-key-pairs) beschrieben. :::warning Sicherheit Geben Sie ausschließlich den **öffentlichen** Schlüssel weiter. Der private Schlüssel darf nicht an Workist oder Dritte übermittelt werden. ::: ### A2 — Öffentlichen Schlüssel in der Workbench hinterlegen {#a2-oeffentlichen-schluessel-hinterlegen} Sobald der öffentliche Schlüssel in Ihrem Workist-Konto hinterlegt ist, kann sich der dazugehörige private Schlüssel ohne Passwort am SFTP-Server anmelden. Schlüssel können **hinzugefügt** und **gelöscht**, aber nicht bearbeitet werden. **Voraussetzungen** - Ein Workbench-Konto mit der Rolle IT oder Admin. Andere Rollen sehen den Bereich **Integrationen** nicht. - Ein öffentlicher SSH-Schlüssel im OpenSSH-Format (Schlüsseltext beginnt mit `ssh-rsa`). **1. In der Workbench anmelden** Öffnen Sie die Workbench in Ihrem Browser und melden Sie sich mit Ihrem Workist-Konto an. Nach der Anmeldung landen Sie auf der Übersichtsseite für eingehende Dokumente. ![Übersichtsseite nach der Anmeldung](/img/sftp-public-key/01-dashboard.png) **2. Einstellungen öffnen** Klicken Sie in der linken Navigationsleiste unten auf **Einstellungen**. Es erscheint ein kleines Menü, z. B. mit den Bereichen *Organisation*, *Teams*, *Mitarbeiter\*innen* und *Integrationen*. Welche Einträge Sie sehen, hängt von Ihrer Rolle ab. ![Einstellungen-Menü](/img/sftp-public-key/02-einstellungen-popover.png) Wählen Sie dort **Integrationen**. **3. Bereich „Integrationen" öffnen** Sie befinden sich nun im Einstellungsbereich. Auf der linken Seite sehen Sie die Unter-Navigation mit allen Einstellungskategorien. Unter dem Abschnitt **Entwickler-Tools** finden Sie den Eintrag **Öffentliche SFTP-Schlüssel**. ![Einstellungen mit Unter-Navigation](/img/sftp-public-key/03-integrationen-seite.png) Klicken Sie auf **Öffentliche SFTP-Schlüssel**. **4. Seite „Öffentliche SFTP-Schlüssel"** Oben auf der Seite zeigt eine Karte die Verbindungsdaten des SFTP-Servers von Workist: Host, Port, RSA-Fingerprint, IP-Adressen und Ihren Benutzernamen. Über das Kopier-Symbol in jeder Zeile übernehmen Sie einen Wert in die Zwischenablage. Darunter folgt das Formular **SFTP-Öffentlichen Schlüssel hinzufügen**. Sofern bereits Schlüssel hinterlegt sind, werden diese zusätzlich in einer Tabelle oberhalb des Formulars angezeigt. Über das Mülleimer-Symbol in der jeweiligen Zeile lässt sich ein bestehender Schlüssel löschen. ![Leeres Schlüsselformular](/img/sftp-public-key/04-sftp-schluessel-seite.png) **5. Öffentlichen Schlüssel einfügen** Öffnen Sie die Datei `workist_sftp.pub` (bzw. Ihre `.pub`-Datei) in einem Texteditor und kopieren Sie den **gesamten Inhalt**. Fügen Sie den Schlüssel anschließend in das Feld **Öffentlicher Schlüssel (im OpenSSH-Format, beginnend mit 'ssh-rsa')** ein. Beispiel für einen gültigen Schlüssel: ``` ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1zFZpL9a6bVQMWS20u3y3WzVCq6tbm... ihr-team@example.com ``` ![Schlüssel im Formular eingefügt](/img/sftp-public-key/05-schluessel-eingefuegt.png) :::tip Der Schlüssel ist eine einzelne lange Zeile. Achten Sie darauf, dass beim Kopieren keine zusätzlichen Zeilenumbrüche entstehen. ::: **6. Schlüssel hinzufügen** Klicken Sie unten rechts in der Karte auf **Hinzufügen**. Bei Erfolg erscheint eine grüne Bestätigungsmeldung und der neue Schlüssel wird in der Tabelle oberhalb des Formulars mit dem Zeitstempel der Hinzufügung angezeigt. **Schlüssel wieder entfernen** Auf derselben Seite befindet sich in jeder Zeile ein Mülleimer-Symbol. Ein Klick darauf entfernt den Schlüssel **sofort** vom SFTP-Server — eine Rückfrage erscheint nicht. Prüfen Sie daher vor dem Löschen, dass Sie den richtigen Schlüssel ausgewählt haben. ### A3 — Verbindung testen {#a3-verbindung-testen} Host und Benutzername stehen in der Karte mit den Verbindungsdaten oben auf der Seite **Öffentliche SFTP-Schlüssel**. ```bash sftp -i ~/.ssh/workist_sftp @ftp.workist.com ``` Beim ersten Verbinden zeigt Ihr Client den Fingerprint des Servers. Vergleichen Sie ihn mit dem RSA-Fingerprint aus der Karte, bevor Sie bestätigen. Weitere Testbefehle und die Verzeichnisstruktur finden Sie in der [SFTP-Dokumentation](/docs/data-exchange/sftp.md#verbindung-testen). --- ## Option B: API {#option-b-api} Workist stellt eine REST-API für den Datenaustausch bereit. Über die API laden Sie Dokumente hoch, rufen verarbeitete Dokumente ab, melden das Ergebnis des Imports zurück und übertragen Stammdaten. Den API-Schlüssel erstellen Sie in der Workbench unter **Einstellungen** → **Integrationen** → **API-Integrationen**. Der [Quickstart](/docs/api-documentation/quickstart.md) führt Sie durch diesen Schritt und den ersten Aufruf. Alle Operationen beschreibt die [Dokumenten-API](/docs/api-documentation/document-api.md), die Übertragung von Stammdaten die [Stammdaten-API](/docs/api-documentation/master-data-api.md). Die API arbeitet nach dem Abrufprinzip: Ihr System fragt Workist nach neuen Ergebnissen. Soll Workist Ihr System bei Ereignissen benachrichtigen, z. B. wenn ein Dokument abgeschlossen ist, richten Sie zusätzlich [Webhooks](/docs/data-exchange/webhooks.md) ein. --- ## Hilfe und Support Wenn die Verbindung trotz hinterlegtem Schlüssel scheitert oder der API-Zugang nicht wie erwartet funktioniert, wenden Sie sich bitte an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den Kurznamen Ihrer Organisation - bei SFTP: den Fingerabdruck Ihres Schlüssels (`ssh-keygen -lf ~/.ssh/workist_sftp.pub`) - den Zeitpunkt des letzten Verbindungsversuchs sowie die Fehlermeldung Ihres Clients --- Source: https://docs.workist.com/docs/implementation-guide/step-2-configure-and-upload-master-data.md # Schritt 2: Stammdaten konfigurieren und hochladen Damit Workist eingehende Dokumente korrekt auflösen kann (z. B. Artikelnummern, Kunden, Lieferadressen), benötigt das System eine aktuelle Kopie Ihrer Stammdaten. Dieser Schritt beschreibt, **welche Daten zu liefern sind**, **wie Sie den Import im Master Data Hub einrichten** und **auf welchem Weg** Sie die Daten übertragen. ## Welche Stammdaten werden benötigt? Welche Stammdatenlisten nötig sind, hängt von Ihrem Anwendungsfall ab. Für nahezu jede Konfiguration brauchen Sie **Kunden** und **Artikel**. | Stammdatenliste | Typischer Bedarf | | --- | --- | | [Kunden (Auftraggeber / Debitor)](/docs/master-data/customers.md) | Pflicht | | [Artikel](/docs/master-data/articles.md) | Pflicht | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | optional | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | optional | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | optional | | [Kundenspezifische Artikel](/docs/master-data/articles.md) | optional | | [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | optional, wenn Workist Einheiten umrechnen soll | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | optional, nur für Anfragen und Bestellungen | | [Angebote](/docs/master-data/quotes.md) | optional, nur für Bestellungen | | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | optional, für Auftragsbestätigungen und Rechnungen | Dazu kommen je nach Dokumenttyp eine Empfängerliste (Format wie Kunden) und eine Liste interner Kontakte (Format wie Kundenkontakte). Welcher Dokumenttyp welche Liste nutzt, zeigt die Tabelle unter [Welcher Dokumenttyp welche Liste nutzt](/docs/master-data.md#listen-pro-dokumenttyp). Bereiten Sie pro Liste einen aktuellen Export aus Ihrem ERP-System vor — idealerweise als **CSV (UTF-8, `;` oder `,` als Trennzeichen)**. Excel-Dateien (`.xls`, `.xlsx`) können Sie per SFTP liefern. :::tip Beginnen Sie mit einem **vollständigen** Stammdaten-Export, nicht mit einem Delta. Jeder Import ersetzt die gesamte Liste — Zeilen, die nicht in der neuesten Datei enthalten sind, werden aus dem aktiven Datensatz entfernt. Delta-Importe richtet Workist auf Anfrage ein (siehe [Wie ein Import Ihre Daten ersetzt](/docs/master-data.md#importverhalten)). ::: ## Wer Stammdaten einrichten kann Den [Master Data Hub](/docs/master-data/master-data-hub.md) nutzen Benutzer mit der Rolle **Manager**, **IT** oder **Admin** (siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md)). Benutzer mit der Rolle **IT** erhalten außerdem eine E-Mail, wenn ein Import mit einem Fehler fehlschlägt, den Sie selbst beheben können. --- ## Ablauf im Überblick 1. **Liste anlegen:** Legen Sie im [Master Data Hub](/docs/master-data/master-data-hub.md#liste-anlegen) eine Liste pro Stammdatenliste an. Beim Anlegen eines Kanals legt Workist für die wichtigsten Felder bereits leere Listen an; prüfen Sie diese zuerst. 2. **Kanälen zuordnen:** Ordnen Sie jede Liste den Kanälen und Feldern zu, die sie nutzen sollen (siehe [Kanälen zuordnen](/docs/master-data/master-data-hub.md#kanaele-zuordnen)). 3. **Import konfigurieren:** Legen Sie Dateinamensmuster, Trennzeichen, Codierung und Spaltenzuordnung fest (siehe [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md)). 4. **Mit einem Probelauf testen:** Prüfen Sie die Konfiguration mit einer Beispieldatei, bevor Sie speichern (siehe [Probelauf](/docs/master-data/master-data-hub.md#probelauf)). 5. **Daten liefern:** per SFTP, über die API oder als Upload in der Workbench (siehe unten). 6. **Ergebnis prüfen:** in der [Importhistorie](/docs/master-data/master-data-hub.md#importhistorie) (Status, Zeilen, Fehlermeldung) und im [Datenexplorer](/docs/master-data/master-data-hub.md#datenexplorer). --- ## Übertragungsweg wählen Stammdaten lassen sich auf drei Wegen an Workist übergeben: | Option | Empfohlen für | | --- | --- | | **[SFTP](#option-a-sftp)** | Regelmäßige, datei-basierte Exporte aus dem ERP — keine eigene Integration nötig | | **[API](#option-b-api)** | Programmatische Anbindung, ereignisgesteuertes Aktualisieren, große Datenmengen | | **[Upload in der Workbench](#option-c-workbench)** | Erster Test und gelegentliche manuelle Aktualisierungen | Alle Wege laufen durch dieselbe Importkonfiguration der Liste und erzeugen denselben aktiven Datensatz. --- ## Option A: SFTP {#option-a-sftp} Beim SFTP-Import legt Ihr ERP-System die Stammdaten-Dateien in regelmäßigen Abständen im Verzeichnis `/export` des Workist-SFTP-Servers ab (siehe [Schritt 1](/docs/implementation-guide/step-1-establish-connection.md)). Workist importiert eine Datei sofort, wenn ihr Name zum Dateinamensmuster einer Liste passt. Temporäre Dateien und weitere Regeln beschreibt die [SFTP-Dokumentation](/docs/data-exchange/sftp.md#stammdaten). :::info Wichtig Ohne passendes Dateinamensmuster wird eine eingehende Datei zwar im SFTP-Verzeichnis abgelegt, aber **nicht importiert**. Stellen Sie die Importkonfiguration daher fertig, bevor Sie produktive Lieferungen starten. ::: ### Ablauf 1. Stammdaten-Datei pro Liste aus dem ERP exportieren. 2. Importkonfiguration der Liste im Master Data Hub einrichten (Dateinamensmuster, Trennzeichen/Codierung, Spaltenzuordnung) und mit einem Probelauf testen. 3. Datei in das SFTP-Verzeichnis `/export` hochladen — Workist erkennt sie automatisch und startet den Import. 4. Ergebnis in der Importhistorie der Liste prüfen. Nach einer Änderung der Importkonfiguration importieren Sie die zuletzt gelieferte Datei mit dem [Import aus dem SFTP-Verzeichnis](/docs/master-data/master-data-hub.md#import-aus-sftp) erneut, ohne sie noch einmal hochzuladen. --- ## Option B: API {#option-b-api} Über die [Stammdaten-API](/docs/api-documentation/master-data-api.md) lassen sich Stammdaten auf drei Arten übertragen: - **Als CSV-Datei** (höchstens 10 MB). Die API nimmt nur CSV-Dateien an; Excel-Dateien liefern Sie per SFTP. - **Als Link** zu einer öffentlich erreichbaren CSV-Datei. - **Als Liste von Objekten im JSON-Format** (höchstens 10.000 Zeilen pro Anfrage), für größere Mengen in mehreren Blöcken. :::note Alle Varianten durchlaufen die Importkonfiguration der Liste. JSON-Daten wandelt Workist vorher in eine kommagetrennte CSV-Datei (UTF-8) um, deren Spalten die Schlüssel Ihrer Objekte sind. Verwenden Sie bei JSON-Lieferungen deshalb die Workist-Spaltennamen als Schlüssel und lassen Sie in der Importkonfiguration Trennzeichen und Spaltenzuordnung leer. Ohne Importkonfiguration liest Workist jede Datei kommagetrennt und mit den Workist-Spaltennamen. ::: Für API-Importe brauchen Sie die ID der Liste aus dem Master Data Hub. Authentifizierung, Endpunkte, Datenmodelle und Hinweise zu Massen-Importen finden Sie unter [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- ## Option C: Upload in der Workbench {#option-c-workbench} Für den ersten Test — bevor SFTP-Lieferungen oder die API-Integration produktiv laufen — laden Sie Stammdaten direkt im Master Data Hub hoch. So testen Sie eine neue Importkonfiguration, ohne auf den nächsten ERP-Export warten zu müssen. 1. Öffnen Sie den [Master Data Hub](/docs/master-data/master-data-hub.md): unten in der linken Navigationsleiste **Einstellungen** und dann den Eintrag für die Stammdaten. 2. Öffnen Sie die gewünschte Liste und wechseln Sie auf den Reiter für die Importe. 3. Ziehen Sie eine **CSV-Datei** in die Karte zum Hochladen und klicken Sie auf die Schaltfläche zum Importieren. 4. Prüfen Sie das Ergebnis in der Importhistorie auf demselben Reiter. ### Wichtige Hinweise - **Nur CSV.** Der Upload in der Workbench nimmt ausschließlich `.csv`-Dateien an. Excel-Dateien liefern Sie per SFTP. - **Dieselbe Importkonfiguration.** Trennzeichen, Codierung und Spaltenzuordnung ergeben sich aus der Konfiguration der Liste. Wenn die Konfiguration `;` als Trennzeichen erwartet, muss Ihre CSV-Datei dieses Trennzeichen verwenden. - **Erst testen, dann importieren.** Ein erfolgreicher Import ersetzt die bisher aktive Version **unmittelbar** — es gibt keinen Entwurfs- oder Freigabemodus. Testen Sie Ihre Datei deshalb vorher mit einem [Probelauf](/docs/master-data/master-data-hub.md#probelauf): Er wandelt die Datei um, ohne etwas zu importieren. - **Bestätigung ≠ Importerfolg.** Die grüne Bestätigung im Browser bedeutet lediglich, dass die Datei angenommen wurde. Fehler erscheinen erst später in der Importhistorie als fehlgeschlagener Lauf. - **Vollimport löscht Fehlendes.** Zeilen, die in der neuen Datei nicht mehr enthalten sind, werden aus dem aktiven Datensatz entfernt. Laden Sie also keine gekürzte Testdatei in eine Liste, die ein produktiver Kanal nutzt. --- ## Hilfe und Support Wenn ein Stammdaten-Import scheitert oder die Werte nicht wie erwartet im Workist-Schema landen, prüfen Sie zuerst die [Fehlermeldung in der Importhistorie](/docs/master-data/master-data-hub.md#fehlermeldungen). Wenden Sie sich sonst an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den **Namen der Liste** im Master Data Hub und den **Stammdatentyp** (z. B. „Artikel“), - den **Zeitpunkt** des fehlgeschlagenen Imports (Spalte **Importiert am** in der Importhistorie), - die **Eingabedatei** des Imports (in der Importhistorie verlinkt), - die **Fehlermeldung** des Imports bzw. das Ergebnis eines Probelaufs. --- Source: https://docs.workist.com/docs/implementation-guide/step-3-configure-processing-channel.md # Schritt 3: Verarbeitungskanal konfigurieren In diesem Schritt richten Sie den **Verarbeitungskanal** ein: Sie legen fest, wie Dokumente in den Kanal gelangen, welche Felder Workist extrahiert, ab welcher Sicherheit automatisiert wird und welche Stammdaten für den Abgleich verwendet werden. Die vollständige Beschreibung aller Einstellungen finden Sie im Bereich **[Kanal-Konfiguration](/docs/channel-configuration.md)**. Diese Seite führt Sie in der richtigen Reihenfolge durch die wichtigsten Punkte. ## Voraussetzungen - Die Berechtigung, Kanäle zu konfigurieren (Rollen **Manager** und **Admin**), siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). - Ihre Stammdaten aus [Schritt 2](/docs/implementation-guide/step-2-configure-and-upload-master-data.md). ## 1. Kanal anlegen Nutzen Sie einen vorhandenen Kanal oder legen Sie einen neuen an: Klicken Sie in der linken Navigation auf das Produkt (z. B. **Bestellungen**) und in der Ansicht **Alle Kanäle** auf **Kanal hinzufügen**. Mit **Kanal duplizieren** (Drei-Punkte-Menü ⋮ im Kanal) übernehmen Sie alle Einstellungen eines bestehenden Kanals. Details: [Kanäle anlegen und duplizieren](/docs/channel-configuration.md#kanaele-anlegen-und-duplizieren). :::warning Ein neuer Kanal ist sofort aktiv - Das **E-Mail-Postfach** des Kanals nimmt ab dem Anlegen E-Mails an. - Die **Automatisierung** ist ausgeschaltet: Jedes Dokument wartet in der Assistenz. - Die **Übertragung** ist eingeschaltet: Sobald jemand ein Dokument abschließt, legt Workist die Ergebnisse auf dem Workist-verwalteten SFTP-Server ab. Richten Sie deshalb den Ausgang in [Schritt 4](/docs/implementation-guide/step-4-configure-output-format.md) ein, bevor Sie Dokumente abschließen. ::: Die Kanal-Konfiguration öffnen Sie im Kanal über das Drei-Punkte-Menü (⋮) → **Kanal verwalten**. ## 2. Allgemeine Angaben festlegen Unter **[Allgemein](/docs/channel-configuration/general.md)** vergeben Sie den Kanalnamen und das zuständige Team. Nur Mitglieder dieses Teams sehen den Kanal und seine Dokumente. ## 3. Eingang einrichten Unter **[Eingehende Dokumente](/docs/channel-configuration/incoming-documents.md)** legen Sie fest, wie Dokumente in den Kanal kommen: - **E-Mail**: Prüfen Sie den Postfachnamen und damit die Adresse des Kanals. Ihre Absender:innen schicken Dokumente an diese Adresse, oder Sie leiten ein bestehendes Postfach dorthin weiter. Welche Anhänge Workist verarbeitet, steht unter [Welche Dateien verarbeitet Workist?](/docs/channel-configuration/incoming-documents.md#welche-dateien-verarbeitet-workist). - **Selbstbedienungsformulare** (nur Bestellkanäle): Ihre Kund:innen erfassen Bestellungen in einem Webformular. Sprachagenten richten Sie in einem eigenen Bereich ein, siehe [Sprachagenten](/docs/agents/voice-agents.md). ## 4. Dokumentenverarbeitung konfigurieren Unter **[Dokumentenverarbeitung](/docs/channel-configuration/document-processing.md)** legen Sie fest, welche Felder Workist extrahiert, welche Stammdaten es für den Abgleich nutzt und welche Prüfungen laufen. Weisen Sie dort insbesondere die Stammdaten aus Schritt 2 zu. Lassen Sie die **Automatisierung** vorerst ausgeschaltet. Sie schalten sie erst ein, wenn die Ergebnisse beim [Testen](/docs/implementation-guide/step-5-test.md) stimmen. ## Nächster Schritt Richten Sie in **[Schritt 4](/docs/implementation-guide/step-4-configure-output-format.md)** ein, wie und in welchem Format die Ergebnisse in Ihr System gelangen. --- Source: https://docs.workist.com/docs/implementation-guide/step-4-configure-output-format.md # Schritt 4: Ausgabeformat konfigurieren In diesem Schritt legen Sie fest, **wie** die Ergebnisse eines Kanals in Ihr System gelangen und **in welchem Format**. Alle Einstellungen dazu finden Sie in der Kanal-Konfiguration unter **[Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md)**. :::warning Die Übertragung ist bereits eingeschaltet Ohne weitere Einstellungen überträgt ein Kanal jedes abgeschlossene Dokument per SFTP in den Ordner `/incoming` auf dem Workist-verwalteten SFTP-Server, als Ausgabedatei plus PDF. Prüfen Sie die folgenden Punkte, bevor Sie Dokumente abschließen. ::: ## Voraussetzungen - Die Verbindung aus [Schritt 1](/docs/implementation-guide/step-1-establish-connection.md) (SFTP-Schlüssel oder API-Zugang). - Ein Kanal aus [Schritt 3](/docs/implementation-guide/step-3-configure-processing-channel.md). - Die Berechtigung, Kanäle zu konfigurieren (Rollen **Manager** und **Admin**). ## 1. Übertragungsweg wählen Öffnen Sie im Kanal das Drei-Punkte-Menü (⋮) → **Kanal verwalten** → **Upload** und wählen Sie unter **Wie sollen die Dokumente übertragen werden? (SFTP, AS2)** den passenden Weg: | Ihr System … | Übertragungsweg | Was Sie zusätzlich brauchen | | --- | --- | --- | | liest Dateien von einem SFTP-Server | **SFTP** (Standard) | Workist-verwalteter Server: nur Ihren SSH-Schlüssel aus Schritt 1. Eigener Server: Verbindungsdaten unter **SFTP**. | | empfängt EDI-Nachrichten per AS2 | **AS2** | Verbindungsdaten und Zertifikate Ihres AS2-Partners unter **AS2**. | | ruft die Ergebnisse selbst ab | **API** | Ihren API-Zugang; optional [Webhooks](/docs/data-exchange/webhooks.md), damit Ihr System erfährt, wann ein Ergebnis bereitsteht. | | ist ein ERP-System mit Workist-Konnektor | ERP-Integration | Die eingerichtete Integration, siehe [Konnektoren](/docs/data-exchange/connectors.md). Der Weg wird automatisch gesetzt, wenn Sie den Kanal in der Integration auswählen. | | bekommt die Daten auf anderem Weg | Manuell oder Sonstige | Nichts. Workist überträgt bei diesen Wegen nichts. | Klicken Sie auf **Speichern**. ## 2. Dateiformat festlegen Unter **Ausgabedatei** legen Sie fest, was in der Datei steht. Die Felder beschreibt [Schritt 4 — Ausgabedatei](/docs/channel-configuration/exported-documents.md#ausgabedatei) im Detail. - **Format**: Lassen Sie das Feld für das Serialisierungsmodul leer, erzeugt Workist das Standardformat des Produkts, z. B. Workist-XML für Bestellungen. Aufbau und Felder jedes Formats stehen unter [Ausgabeformate](/docs/output-formats.md). Andere Formate richten Sie gemeinsam mit Workist ein. - **Zusätzliche Felder**: Unter **Zusätzliche Kopfzeilendatenfelder** und **Zusätzliche Positionszeilenfelder** ergänzen Sie weitere Felder. Geben Sie nur Feldnamen ein, die das Format kennt; ein unbekannter Name lässt die Erzeugung der Ausgabedatei für jedes Dokument fehlschlagen. - **Optionale Elemente**: `` (Dateiname der mitgesendeten PDF), `` (Link in die Workbench), `` (E-Mail-Adresse des Absenders), außerdem kurze Dateinamen. - **Bestellkanäle**: Soll die Datei aus einer individuellen Zuordnung (Output Mapper) entstehen, richtet Workist diese mit Ihnen ein. Klicken Sie auf **Speichern**, auch wenn Sie nichts geändert haben: Erst dann gelten die Schalter für die optionalen Elemente. ## 3. Begleitdateien und Zielordner festlegen Zurück unter **Upload** legen Sie fest, welche Dateien neben der Ausgabedatei mitgehen: - **Originaldokument hochladen** (Standard: an): das verarbeitete Dokument, meist als PDF, mit demselben Dateinamen wie die Ausgabedatei. - **Originale E-Mail hochladen** (nur SFTP): die ursprüngliche E-Mail als `.eml`. - **Zusätzliche Dateien** (nur Bestellkanäle): weitere Anhänge derselben E-Mail, z. B. Lieferscheine oder Angebote. - **Zielordner für generierte Dateien** und **Zielordner für ausgehende Dokumente** (nur SFTP): leer = `/incoming`. ## 4. Verbindung einrichten | Übertragungsweg | Einrichtung | | --- | --- | | SFTP, Workist-verwaltet | Seite **SFTP** leer lassen. Ihr öffentlicher SSH-Schlüssel muss unter **Einstellungen → Öffentliche SFTP-Schlüssel** hinterlegt sein, siehe [Schritt 1](/docs/implementation-guide/step-1-establish-connection.md). | | SFTP, eigener Server | Unter **SFTP** Host, Port (Pflicht), Benutzername, Hostkey im Format ` ` und Passwort eintragen. Ohne Passwort meldet sich Workist mit seinem eigenen SSH-Schlüssel an, den Sie auf Ihrem Server freigeben. | | AS2 | Unter **AS2** Endpunkt, AS2-Name und Zertifikate Ihres Partners eintragen. Ihr Partner hinterlegt die AS2-ID und Zertifikate von Workist. Workist signiert und verschlüsselt und erwartet eine synchrone MDN. | | API | Keine Verbindungsdaten im Kanal nötig. Ihr System ruft die Ergebnisse über die [API](/docs/data-exchange/api.md) ab. | | ERP-Integration | Wird in den Einstellungen der Integration eingerichtet, siehe [Konnektoren](/docs/data-exchange/connectors.md). | ## 5. Verstehen, wie Workist zustellt - Workist überträgt, sobald ein Dokument abgeschlossen ist: von Hand in der Assistenz oder automatisch, wenn die Automatisierung eingeschaltet ist. - Wie die Dateien auf dem SFTP-Server entstehen (Dateinamen, Reihenfolge, Teildateien, Überschreiben), beschreibt [Datenaustausch mittels SFTP](/docs/data-exchange/sftp.md). Richten Sie Ihren Import danach ein. - Schlägt die Übertragung fehl, zeigt das Dokument ein rotes Fehlerbanner. Nach dem Beheben der Ursache übertragen Sie es erneut, siehe [Zustellfehler](/docs/channel-configuration/exported-documents.md#zustellfehler). - Ist **Upload aktivieren** ausgeschaltet, überträgt Workist nichts, auch nicht nachträglich. ## Checkliste - [ ] Übertragungsweg gewählt und gespeichert. - [ ] Seite **Ausgabedatei** mindestens einmal gespeichert. - [ ] Begleitdateien und Zielordner wie gewünscht. - [ ] Verbindungsdaten eingetragen bzw. SSH-Schlüssel hinterlegt. - [ ] Ihr System liest aus dem richtigen Ordner bzw. ruft die richtigen Ergebnisse ab. - [ ] Festgelegt, wohin Testergebnisse gehen sollen (siehe [Schritt 5](/docs/implementation-guide/step-5-test.md)). ## Wo finde ich die erzeugte Datei? Öffnen Sie ein abgeschlossenes Dokument und klicken Sie oben auf das Symbol **Verarbeitungsverlauf anzeigen**. In der Seitenleiste laden Sie die Ausgabedatei über **Ergebnis herunterladen** herunter. ## Nächster Schritt Testen Sie den Kanal in **[Schritt 5](/docs/implementation-guide/step-5-test.md)**. --- Source: https://docs.workist.com/docs/implementation-guide/step-5-test.md # Schritt 5: Testen Bevor Sie live gehen, schicken Sie echte Beispieldokumente durch den Kanal und prüfen die Ergebnisse in der Workbench und in Ihrem System. :::warning Testdokumente sind echte Dokumente Workist hat keinen Testmodus für Kund:innen: Sie können Dokumente nicht als Test markieren. Die Übertragung ist standardmäßig eingeschaltet. Jedes Testdokument, das Sie abschließen, überträgt Workist wie ein echtes, an das Ziel, das unter **Upload** eingestellt ist. Legen Sie deshalb vor dem ersten Test fest, wohin Testergebnisse gehen. ::: ## Voraussetzungen - Ein eingerichteter Kanal aus [Schritt 3](/docs/implementation-guide/step-3-configure-processing-channel.md) und [Schritt 4](/docs/implementation-guide/step-4-configure-output-format.md). - Einige echte Beispieldokumente, z. B. Bestellungen verschiedener Kund:innen, mit unterschiedlichen Layouts, mehrseitig und mit mehreren Anhängen. ## 1. Festlegen, wohin Testergebnisse gehen Wählen Sie eine der folgenden Möglichkeiten. Alle Einstellungen finden Sie in der Kanal-Konfiguration unter **[Upload](/docs/channel-configuration/exported-documents.md#upload)**. | Möglichkeit | So geht's | Beachten Sie | | --- | --- | --- | | **Nur in der Workbench prüfen** | Neue Kanäle haben die Automatisierung ausgeschaltet. Workist überträgt also nichts, bevor jemand ein Dokument in der Assistenz abschließt. Prüfen Sie die Extraktion und löschen Sie Testdokumente über das Zeilenmenü (**Löschen**), statt sie abzuschließen. | Testet nur die Extraktion, nicht die Ausgabedatei und die Zustellung. | | **Eigener Testordner** (SFTP) | Tragen Sie unter **Zielordner für generierte Dateien** und **Zielordner für ausgehende Dokumente** einen Ordner ein, den Ihr Produktivimport nicht liest, z. B. `/test`. Bei AS2 tragen Sie stattdessen den Testendpunkt Ihres Partners ein. | Stellen Sie die produktiven Ziele vor dem Go-live wieder ein. | | **Übertragung ausschalten** | Schalten Sie **Upload aktivieren** aus oder wählen Sie als Übertragungsweg *Manuell*. Workist verarbeitet die Dokumente, überträgt aber nichts. Die Ausgabedatei laden Sie im Verarbeitungsverlauf herunter. | Dokumente, die Sie in dieser Zeit abschließen, überträgt Workist auch später nicht. Nach *Manuell* müssen Sie **Upload aktivieren** beim Zurückwechseln wieder einschalten. | | **Testkanal** | Duplizieren Sie den Kanal (⋮ → **Kanal duplizieren**) und ändern Sie in der Kopie **sofort** die Ziele (Testordner, AS2-Testendpunkt) oder schalten Sie dort die Übertragung aus. Schicken Sie Testdokumente an die Adresse der Kopie. | Die Kopie liefert zunächst an dieselben Ziele wie das Original. Kanäle löschen kann nur Workist; deaktivieren Sie nach dem Test das Postfach der Kopie. | Bei **API** überträgt Workist nichts aktiv. Läuft Ihr Abrufprozess schon produktiv, holt er aber auch Testergebnisse ab. Testen Sie deshalb, bevor Sie ihn produktiv schalten, oder prüfen Sie die Ergebnisse dort von Hand. ## 2. Testdokumente senden - **Per E-Mail**: Schicken oder leiten Sie Beispieldokumente an die Adresse des Kanals. Die Adresse kopieren Sie in der Dokumentenübersicht über **Datei senden...** → **E-Mail Adresse kopieren**. - **Per Upload**: Klicken Sie in der Dokumentenübersicht auf **Datei senden...** → **Vom Computer hochladen**. Eine hochgeladene `.eml`- oder `.msg`-Datei behandelt Workist wie eine eingegangene E-Mail; so testen Sie echte Kundenmails samt Anhängen. Welche Dateien und Anhänge Workist verarbeitet, steht unter [Welche Dateien verarbeitet Workist?](/docs/channel-configuration/incoming-documents.md#welche-dateien-verarbeitet-workist). ## 3. Ergebnis in der Workbench prüfen 1. Das Dokument erscheint im **Eingang** des Kanals. Bei ausgeschalteter Automatisierung wartet es in der Assistenz. 2. Prüfen Sie die extrahierten Kopf- und Positionsdaten und den Abgleich mit Ihren Stammdaten (Kunde, Artikel, Adressen). 3. Schließen Sie das Dokument mit **Abschließen** ab, wenn Sie auch die Ausgabedatei prüfen wollen. 4. Öffnen Sie über das Symbol **Verarbeitungsverlauf anzeigen** die Seitenleiste und laden Sie die Datei über **Ergebnis herunterladen** herunter. 5. Vergleichen Sie die Datei mit der Beschreibung Ihres Formats unter [Ausgabeformate](/docs/output-formats.md). ## 4. Konfiguration anpassen und erneut prüfen - Passen Sie die [Kanal-Konfiguration](/docs/channel-configuration.md) oder Ihre Stammdaten an. - Dokumente, die noch in der Assistenz liegen, extrahiert Workist mit **Erneut verarbeiten** (Zeilenmenü) neu, mit der aktuellen Konfiguration und den aktuellen Stammdaten. Ihre Änderungen am Dokument gehen dabei verloren. - Änderungen unter **Upload** und **Ausgabedatei** gelten für das nächste Dokument, das Sie abschließen. ## 5. Zustellung prüfen | Übertragungsweg | Woran Sie den Erfolg erkennen | | --- | --- | | SFTP | Die Dateien liegen im Zielordner. Ihr Import liest nur vollständig geschriebene Dateien, siehe [Datenaustausch mittels SFTP](/docs/data-exchange/sftp.md). | | AS2 | Ihr Partner bestätigt den Empfang. | | ERP-Integration | Der Beleg erscheint in Ihrem ERP-System. | | API | Ihr System ruft das Ergebnis ab. | Schlägt die Zustellung fehl, zeigt das Dokument ein rotes Fehlerbanner mit der Antwort des Zielsystems. Beheben Sie die Ursache und übertragen Sie erneut, siehe [Zustellfehler](/docs/channel-configuration/exported-documents.md#zustellfehler). ## 6. Live gehen - [ ] Produktive Ziele eingestellt (Zielordner bzw. AS2-Endpunkt), richtiger Übertragungsweg gewählt, **Upload aktivieren** eingeschaltet. - [ ] Testkanäle deaktiviert (Postfach und Übertragung aus). - [ ] Absender:innen informiert bzw. Weiterleitung auf die Adresse des Kanals eingerichtet. - [ ] **Automatisierung aktiviert** eingeschaltet, sobald die Ergebnisse zuverlässig stimmen, am besten in Absprache mit Ihrer Ansprechperson bei Workist. Siehe [Dokument → Automatisierung](/docs/channel-configuration/document-processing/document.md). - [ ] Automatisierungsrate in den [Statistiken](/docs/administration/analytics.md) beobachten (im Kanal: ⋮ → **Kanalanalysen anzeigen**). ## Hilfe und Support Wenn ein Test nicht das erwartete Ergebnis liefert, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie bereit: - den **Kanalnamen** und das betroffene **Dokument** (Betreff oder Zeitpunkt), - was Sie erwartet haben und was Workist geliefert hat, - bei Zustellproblemen den Text des **Fehlerbanners**. --- Source: https://docs.workist.com/docs/channel-configuration.md # Kanal-Konfiguration Diese Anleitung beschreibt die **Kanal-Konfiguration** in der Workbench. Jeder Kanal in Workist (z. B. ein Bestellungs-, Rechnungs- oder Preisanfragen-Kanal) bündelt alle Einstellungen, die für die Verarbeitung eines bestimmten Dokumentenstroms benötigt werden: wie Dokumente **eintreffen**, wie sie **verarbeitet** werden und wohin die fertig verarbeiteten Daten **exportiert** werden. In der Kanal-Konfiguration legen Sie unter anderem fest, welches Team für den Kanal zuständig ist, welche Felder Workist aus dem Dokument extrahieren soll, ab welcher Konfidenz die Automatisierung greift, welche Stammdaten verwendet werden und wie die fertige Ausgabedatei in Ihr System gelangt (SFTP, AS2, API oder ERP-Integration). Da die Konfiguration umfangreich ist, ist sie auf mehrere Themenbereiche aufgeteilt. Diese Seite gibt Ihnen einen Überblick und verlinkt auf die jeweiligen Detailseiten. ## Voraussetzungen - Ein Workbench-Konto mit der Berechtigung, Kanäle zu konfigurieren. Diese Berechtigung haben die Rollen **Manager** und **Admin**, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). Ohne diese Berechtigung ist der Menüeintrag **Kanal verwalten** ausgegraut. - Mindestens ein angelegter Kanal (siehe [Kanäle anlegen und duplizieren](#kanaele-anlegen-und-duplizieren)). ## Kanal-Konfiguration öffnen 1. Wählen Sie in der linken Navigation Ihr Produkt aus (z. B. **Bestellungen**) und öffnen Sie den gewünschten Kanal. 2. Öffnen Sie oben rechts das Drei-Punkte-Menü (⋮). 3. Wählen Sie **Kanal verwalten**. Sie sehen anschließend die Konfigurationsseite mit dem Navigationsmenü in der Mitte. Über den Kanalnamen oben links kehren Sie zur Dokumentenübersicht des Kanals zurück. Die mittlere Spalte enthält die **Navigation** der Kanal-Konfiguration. Die Einträge sind in vier Bereiche gruppiert: | Bereich | Einträge | Was darin konfiguriert wird | | --- | --- | --- | | **[Allgemein](/docs/channel-configuration/general.md)** | Allgemein | Kanalname, zuständiges Team, E-Mail-Postfachadresse, Zeit pro Dokument vor Workist. | | **[Eingehende Dokumente](/docs/channel-configuration/incoming-documents.md)** | Email, Selbstbedienungsformulare | Wie Dokumente in den Kanal kommen. Selbstbedienungsformulare gibt es nur in Bestellkanälen. | | **[Dokumentenverarbeitung](/docs/channel-configuration/document-processing.md)** | Dokument, Kopffelder, Positionzeilenfelder, Agentische Kopfzeilenextraktion, Agentische Positionsextraktion, Stammdaten, Verwerfen | Was Workist mit den eingehenden Dokumenten macht. Zusätzlich erscheint ein Eintrag für Anpassungsparameter. Er ist nur relevant, wenn Workist für Ihre Organisation eine kundenspezifische Anpassung gebaut hat; sonst enthält er keine Einstellungen. | | **[Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md)** | AS2, SFTP, Upload, Ausgabedatei | Wie die Ergebnisse in Ihr System gelangen und welches Format die erzeugte Datei hat. | Je nach Produkt können einzelne Einträge fehlen. Kanäle für Leistungsverzeichnisse haben zum Beispiel keine Einträge unter *Eingehende Dokumente*. :::note Sprachagenten Sprachagenten richten Sie nicht in der Kanal-Konfiguration ein, sondern in einem eigenen Bereich. Siehe [Sprachagenten](/docs/agents/voice-agents.md). ::: ## Kanäle anlegen und duplizieren {#kanaele-anlegen-und-duplizieren} Für beide Aktionen brauchen Sie dieselbe Berechtigung wie für die Kanal-Konfiguration. **Neuen Kanal anlegen:** Klicken Sie in der linken Navigation auf das Produkt (z. B. **Bestellungen**). In der Ansicht **Alle Kanäle** klicken Sie oben rechts auf **Kanal hinzufügen** und geben einen Namen ein. Der neue Kanal - erhält automatisch ein E-Mail-Postfach (bei Bestellkanälen `orders`, `orders-1`, … je nach bereits vergebenen Namen). Das Postfach ist sofort aktiv. - startet mit ausgeschalteter Automatisierung: Jedes Dokument wartet in der Assistenz, bis jemand es abschließt. - überträgt abgeschlossene Dokumente standardmäßig auf den von Workist verwalteten SFTP-Server, siehe [Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md). **Kanal duplizieren:** Öffnen Sie im Kanal das Drei-Punkte-Menü (⋮) und wählen Sie **Kanal duplizieren**. Die Kopie übernimmt **alle** Einstellungen des Originals: Felder, Stammdaten, Team, E-Mail-, AS2-, SFTP- und Upload-Einstellungen. Sie erhält ein eigenes E-Mail-Postfach (Postfachname des Originals plus Name der Kopie). :::warning Kopie liefert an dieselben Ziele Ein duplizierter Kanal überträgt an dieselben SFTP-Ordner bzw. denselben AS2-Empfänger wie das Original. Ändern Sie die Ziele im Bereich [Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md), bevor Sie Dokumente in die Kopie schicken, wenn deren Ergebnisse nicht in Ihrem Produktivsystem landen sollen. ::: Kanäle löschen kann nur Workist. Wenden Sie sich dazu an Ihre Ansprechperson. ## Aufbau der einzelnen Konfigurationsseiten Alle Unterseiten der Kanal-Konfiguration folgen demselben Muster: - Oben steht der **Titel** der Konfiguration (z. B. „E-Mail-Konfiguration", „SFTP Konfiguration"). - Darunter folgen die **Formularfelder** mit den Einstellungen. - Eine **Speichern**-Schaltfläche schreibt die Änderungen in den Kanal. Ohne Klick auf *Speichern* werden Änderungen verworfen, sobald Sie auf eine andere Seite wechseln. Einige Bereiche (z. B. *Upload*, *Ausgabedatei*, *Verwerfen*) haben bei einem neuen Kanal noch keine gespeicherte Konfiguration. Workist arbeitet dann mit Standardwerten. Die Konfiguration wird beim ersten Klick auf **Speichern** angelegt; eine eigene Schaltfläche zum Aktivieren gibt es nicht. :::note Wann greifen Änderungen? Jede Einstellung wirkt ab dem Verarbeitungsschritt, der sie liest: - Einstellungen zum **Eingang** und zur **Extraktion** gelten für Dokumente, die nach dem Speichern eintreffen. - Einstellungen zu **Upload** und **Ausgabedatei** gelten für jedes Dokument, das nach dem Speichern abgeschlossen wird, auch für Dokumente, die schon vorher in der Assistenz lagen. - Dokumente, die noch in der Assistenz liegen, können Sie mit der aktuellen Konfiguration und den aktuellen Stammdaten neu extrahieren lassen: Zeilenmenü **Erneut verarbeiten**. Ihre bisherigen Änderungen am Dokument gehen dabei verloren. ::: ## Detailseiten pro Bereich Für jeden der vier Bereiche gibt es eine eigene Anleitung: - **[Allgemein](/docs/channel-configuration/general.md)** — Kanalname, Team, E-Mail-Postfach, Zeit pro Dokument vor Workist. - **[Eingehende Dokumente](/docs/channel-configuration/incoming-documents.md)** — E-Mail-Empfang, unterstützte Dateitypen, Selbstbedienungsformulare, Hochladen von Dateien. - **[Dokumentenverarbeitung](/docs/channel-configuration/document-processing.md)** — Feldkonfiguration, Konfidenzschwellen, agentische Extraktion mit KI, Stammdatenabgleich, Verwerfen-Regeln. Mit ausführlichen Detailseiten: - [Dokument](/docs/channel-configuration/document-processing/document.md) — Lokalisierung, Automatisierung, Datenformatierung, Einheitenumrechnung, Validierung, Dokumenttypspezifisches, Auffüllen, Dokumentenfilterung. - [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md) — Kopfdatenfelder konfigurieren. - [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md) — Positionsfelder konfigurieren, mit Lookup- und Längenoptionen. - [Agentische Kopfzeilenextraktion](/docs/channel-configuration/document-processing/agentic-extraction.md) — KI-gestützte Extraktion zusätzlicher Kopfdaten. - [Agentische Positionsextraktion](/docs/channel-configuration/document-processing/agentic-extraction.md) — KI-gestützte Extraktion und Operationen auf Positionsebene. - **[Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md)** — Übertragungsweg (SFTP, AS2, API, ERP-Integration), Format der Ausgabedatei, Zustellfehler. ## Wichtigste Einstellungen im Überblick Wenn Sie einen neuen Kanal einrichten oder einen bestehenden Kanal prüfen, sind die folgenden Einstellungen am wichtigsten: | Einstellung | Bereich | Wirkung | | --- | --- | --- | | **Kanalname** und **Team** | Allgemein | Wem der Kanal angezeigt wird und wer Dokumente bearbeitet. | | **Aktiviert** | Eingang → Email | Ob der Kanal E-Mails an seine Postfachadresse annimmt. Bei neuen Kanälen eingeschaltet. | | **Postfachname** | Eingang → Email | Bestimmt die E-Mail-Adresse des Kanals. | | Konfidenzschwellenwerte für Kopfdaten und Positionen | Verarbeitung → Dokument | Welche Konfidenz extrahierte Werte erreichen müssen, damit ein Dokument ohne Assistenz verarbeitet werden kann. | | **Automatisierung aktiviert** | Verarbeitung → Dokument | Globaler Schalter für die End-to-End-Automatisierung dieses Kanals. Bei neuen Kanälen ausgeschaltet. | | Lookup-IDs | Verarbeitung → Stammdaten | Welche Stammdaten (Artikel, Kunden, Adressen, …) für den Abgleich verwendet werden. | | Validierungsprüfungen | Verarbeitung → Dokument | Welche fachlichen Prüfungen (Summenabgleich, eindeutige Bestellnummer, …) laufen. | | **Wie sollen die Dokumente übertragen werden? (SFTP, AS2)** | Ausgang → Upload | Übertragungsweg: SFTP (Standard), AS2, API, ERP-Integration, manuell oder sonstige. | | **Upload aktivieren** | Ausgang → Upload | Ob Workist Ergebnisse per SFTP, AS2 oder ERP-Integration aktiv überträgt. Standardmäßig eingeschaltet. | | **Zielordner für generierte Dateien** / **Zielordner für ausgehende Dokumente** | Ausgang → Upload | In welche SFTP-Ordner Workist die Dateien legt (nur bei SFTP). | | **Serialisierung aktivieren** | Ausgang → Ausgabedatei | Ob Workist eine Ausgabedatei erzeugt. | ## Hilfe und Support Wenn eine Einstellung in Ihrem Kanal nicht den erwarteten Effekt zeigt, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den **Kanalnamen** sowie das **Produkt** (Bestellungen, Rechnungen, …), - den **Bereich**, in dem die Einstellung sitzt (z. B. *Dokumentenverarbeitung → Stammdaten*), - den genauen **Namen des Feldes**, das nicht wie erwartet wirkt, - bei Verarbeitungsfehlern: ein Beispiel-Dokument und den **Zeitpunkt** der Verarbeitung. --- Source: https://docs.workist.com/docs/channel-configuration/general.md # Kanal-Konfiguration — Allgemein Die Seite **Allgemein** ist die Einstiegsseite der Kanal-Konfiguration. Hier hinterlegen Sie die grundlegenden Angaben zum Kanal: den **Namen**, das zuständige **Team**, die **E-Mail-Postfachadresse** und die **Zeit pro Dokument vor Workist**. Diese Einstellungen sind produktunabhängig. Sie wirken auf jeden Kanal gleich, egal ob es sich um einen Bestellungs-, Rechnungs- oder Preisanfragen-Kanal handelt. ## Voraussetzungen - Die Berechtigung, Kanäle zu konfigurieren (Rollen **Manager** und **Admin**), siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). - Mindestens ein **Team**, dem Sie den Kanal zuordnen können. Teams werden unter **Einstellungen → Teams** verwaltet; dafür brauchen Sie die Berechtigung, Mitarbeitende und Teams zu verwalten (Rollen **Manager** und **Admin**). ## Schritt 1 — Den Bereich „Allgemein" öffnen Öffnen Sie die [Kanal-Konfiguration](/docs/channel-configuration.md) und wählen Sie in der mittleren Navigation unter **Allgemein** den gleichnamigen Eintrag aus. Es erscheint das Formular mit den vier Grundeinstellungen. ![Bereich „Allgemein" der Kanal-Konfiguration](/img/channel-config/01-allgemein.png) ## Schritt 2 — Die Felder einstellen | Feld | Pflicht | Bedeutung | | --- | --- | --- | | **Kanalname** | Ja | Der für Benutzer:innen sichtbare Name des Kanals (z. B. „Bestellungen DE", „Eingangsrechnungen Sammelkonto"). Erscheint in der Seitenleiste und in der Übersicht. | | **Team** | Ja | Welches Team die Dokumente dieses Kanals bearbeitet. Nur Mitglieder dieses Teams sehen den Kanal und seine Dokumente. Das Standardteam erscheint in der Auswahl unter dem Namen Ihrer Organisation. Details zur Sichtbarkeit: [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). | | **E-Mail-Postfachadresse** | — | Die Adresse, an die E-Mails für diesen Kanal geschickt werden. **Nicht editierbar**: Sie setzt sich aus dem Kurznamen Ihrer Organisation und dem Postfachnamen aus der [E-Mail-Konfiguration](/docs/channel-configuration/incoming-documents.md) zusammen. Die Adresse wird auch angezeigt, wenn das E-Mail-Postfach deaktiviert ist. | | **Zeit pro Dokument vor Workist (in Sekunden)** | Nein | Wie lange ein Mitarbeitender vor Einführung von Workist im Schnitt pro Dokument gebraucht hat. Workist verwendet den Wert in den [Statistiken](/docs/administration/analytics.md), um die Zeitersparnis zu berechnen. **Standardwert: 270 Sekunden (4,5 Minuten).** Sie können den Wert ändern, aber nicht leeren: Ein leeres Feld oder 0 wird beim Speichern ignoriert, der bisherige Wert bleibt erhalten. | :::note Teamwechsel wirkt sofort Dokumente gehören keinem Team selbst, sondern sind über ihren Kanal sichtbar. Wenn Sie das **Team** ändern, wechseln **alle** Dokumente des Kanals sofort zum neuen Team: offene Dokumente in der Assistenz ebenso wie abgeschlossene im Archiv. Mitglieder des alten Teams verlieren den Zugriff sofort. ::: ## Schritt 3 — Speichern Klicken Sie unten rechts auf **Speichern**. Bei Erfolg erscheint kurz eine Bestätigung („Der Kanal wurde erfolgreich aktualisiert."). Wenn **Kanalname** oder **Team** leer gelassen werden, blockiert das Formular das Speichern und zeigt einen entsprechenden Hinweis. ## Häufige Fragen **Kann ich die E-Mail-Postfachadresse ändern?** Nicht in diesem Bereich. Die Postfachadresse wird über den **Postfachnamen** im Bereich [Eingehende Dokumente → E-Mail](/docs/channel-configuration/incoming-documents.md) gesteuert und automatisch zusammengesetzt. **Wie kopiere ich die E-Mail-Adresse des Kanals?** In der Dokumentenübersicht des Kanals über **Datei senden...** → **E-Mail Adresse kopieren**. **Wo lege ich neue Teams an?** Unter **Einstellungen → Teams**. Erst dort angelegte Teams stehen in der Auswahl im Feld *Team* zur Verfügung. **Warum brauche ich „Zeit pro Dokument vor Workist"?** Ausschließlich für die Auswertung der Zeitersparnis in den **Statistiken**. Auf die Verarbeitung der Dokumente selbst hat dieser Wert keinen Einfluss. Wenn Sie keine eigene Vergleichszahl haben, rechnet Workist mit dem Standardwert von 270 Sekunden. ## Hilfe und Support Wenn der Kanalname falsch in Übersichten erscheint, Mitarbeitende den Kanal nicht sehen oder das E-Mail-Postfach nicht funktioniert, wenden Sie sich an Ihre Ansprechperson bei Workist und nennen Sie: - den **Kanalnamen**, - das gewünschte und das aktuell hinterlegte **Team**, - bei E-Mail-Problemen den **Postfachnamen** aus dem Bereich [Eingehende Dokumente → E-Mail](/docs/channel-configuration/incoming-documents.md). --- Source: https://docs.workist.com/docs/channel-configuration/incoming-documents.md # Kanal-Konfiguration — Eingehende Dokumente Im Bereich **Eingehende Dokumente** legen Sie fest, **wie** Dokumente in einen Kanal gelangen. Es gibt drei Wege: - **E-Mail** — Dokumente kommen als Anhang (oder als E-Mail-Text selbst) über das Postfach des Kanals. - **Selbstbedienungsformulare** — Ihre Kund:innen erfassen Bestellungen direkt in einem Webformular. Nur in Bestellkanälen. - **Datei hochladen** — Sie laden Dateien selbst in der Workbench hoch, z. B. zum Testen. Sprachagenten richten Sie in einem eigenen Bereich ein, siehe [Sprachagenten](#sprachagenten). ## Voraussetzungen - Die Berechtigung, Kanäle zu konfigurieren (Rollen **Manager** und **Admin**), siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). - Für **E-Mail**: Ihre Absender:innen kennen die Adresse des Kanals, oder Sie richten in Ihrem Postfach eine Weiterleitung dorthin ein. - Für **Selbstbedienungsformulare**: ein Bestellkanal und die Berechtigung, Selbstbedienungsformulare einzurichten (Rollen **Manager** und **Admin**). Kundenstammdaten sind hilfreich, aber nicht nötig. ## Schritt 1 — E-Mail-Konfiguration Wählen Sie in der Navigation unter **Eingehende Dokumente** den Eintrag **Email**. ![E-Mail-Konfiguration eines Kanals](/img/channel-config/02-eingang-email.png) Ein neuer Kanal erhält automatisch einen Postfachnamen, und sein Postfach ist **sofort aktiv**. Der Kanal nimmt also ab dem Anlegen E-Mails an. | Feld | Standard | Bedeutung | | --- | --- | --- | | **Aktiviert** | an | Hauptschalter. Solange er ausgeschaltet ist, verarbeitet der Kanal keine E-Mails, die an seine Adresse gehen. | | **Postfachname** | automatisch vergeben (z. B. `orders`, `orders-1`) | Der individuelle Teil der Eingangsadresse. Die vollständige Adresse lautet `-@inbox.workist.com` und wird kleingeschrieben. Beispiel: Kurzname `muster`, Postfachname `orders-5` ergibt `muster-orders-5@inbox.workist.com`. Der Postfachname muss innerhalb Ihrer Organisation eindeutig sein. | | **Erkennen Sie auch den zugeordneten Benutzer anhand des Absendernamens** | aus | Workist ordnet jede eingehende E-Mail automatisch einem **Workbench-Benutzer Ihrer Organisation** zu, wenn die Absenderadresse dessen E-Mail-Adresse oder einem seiner E-Mail-Aliasse entspricht. Dieser Benutzer wird als Ersteller eingetragen und das Dokument wird ihm zugewiesen. Mit diesem Schalter sucht Workist zusätzlich den vollständigen Namen eines Benutzers im Absendernamen oder seine E-Mail-Adresse im Betreff, z. B. bei weitergeleiteten E-Mails. Workist ordnet nur zu, wenn genau ein Benutzer passt. Kund:innen aus Ihren Stammdaten werden über diesen Schalter nicht erkannt. | | **Verarbeiten Sie E-Mails ohne Anhänge als Dokument** | an (Rechnungskanäle: aus) | Wenn aktiv, verarbeitet Workist auch E-Mails, die keinen verwertbaren Anhang haben (siehe [Welche Dateien verarbeitet Workist?](#welche-dateien-verarbeitet-workist)). Die Daten werden dann aus dem E-Mail-Text gelesen. | | **E-Mail-Konversationsnachrichten nach Dokumenttyp filtern** | an | Nur in Bestell- und Preisanfragekanälen. Wenn eine E-Mail Teil einer Konversation (Thread) ist, betrachtet Workist zuerst nur die Nachrichten, deren Inhalt zum Dokumenttyp passt. Nützlich bei langen Threads. | | **Nur aus der obersten übereinstimmenden Konversationsnachricht extrahieren** | aus | Nur in Bestell- und Preisanfragekanälen. Verschärfte Variante des Filters: Workist betrachtet nur eine einzige Nachricht (die oberste passende), nicht die gesamte Konversation. | :::note Wann ändert sich die Postfachadresse? Die im Bereich *Allgemein* angezeigte **E-Mail-Postfachadresse** wird aus dem *Postfachnamen* automatisch zusammengesetzt. Wenn Sie den *Postfachnamen* ändern, ändert sich auch die Eingangsadresse. Informieren Sie in diesem Fall Ihre Absender:innen und passen Sie Weiterleitungen an. ::: :::tip Adresse kopieren Die vollständige Adresse kopieren Sie in der Dokumentenübersicht des Kanals über **Datei senden...** → **E-Mail Adresse kopieren**. ::: Erhält der Kanal dieselbe E-Mail (gleiche Message-ID) ein zweites Mal, solange das Dokument aus der ersten Zustellung noch offen ist, legt Workist kein zweites Dokument an. Klicken Sie auf **Speichern**. ## Welche Dateien verarbeitet Workist? {#welche-dateien-verarbeitet-workist} Workist verarbeitet die folgenden Dateitypen, als E-Mail-Anhang ebenso wie beim [Hochladen](#dateien-direkt-hochladen): | Dateityp | Endungen | Hinweis | | --- | --- | --- | | PDF | `.pdf` | Wird immer berücksichtigt, auch wenn sie in den E-Mail-Text eingebettet ist. | | Bilder | `.png`, `.jpg`, `.jpeg`, `.bmp`, `.tif`, `.tiff` | Nur als echter Anhang und ab 640 × 640 Pixel. Kleinere Bilder und in den E-Mail-Text eingebettete Bilder (z. B. Logos in der Signatur) werden ignoriert. | | Tabellen | `.xls`, `.xlsx`, `.xlsm`, `.ods`, `.csv` | | | Textdokumente | `.doc`, `.docx`, `.rtf`, `.html`, `.htm` | | | Reiner Text | `.txt` | Wird in HTML umgewandelt und dann verarbeitet. | | XML | `.xml`, `.x83` | | | E-Mails | `.eml`, `.msg` | Eine angehängte E-Mail wird wie ein eigener Anhang behandelt. `.msg` (Outlook) wird vorher in `.eml` umgewandelt. | | Archive | `.zip`, `winmail.dat` | Werden entpackt; jede enthaltene Datei wird nach denselben Regeln geprüft. | Für E-Mails gelten außerdem diese Regeln: - **Ein Anhang, ein Dokument.** Jeder verwertbare Anhang wird zu einem eigenen Dokument im Kanal. - **PDFs haben Vorrang.** Hat eine E-Mail mehrere verwertbare Anhänge und ist mindestens eine PDF darunter, verarbeitet Workist nur die PDFs. - **Dokumentenfilterung.** Ist die [Dokumentenfilterung](/docs/channel-configuration/document-processing/document.md) eingeschaltet (Standard bei neuen Bestellkanälen), entscheidet Workist bei mehreren Anhängen anhand ihres Inhalts, welche zum Dokumenttyp des Kanals passen. Ein einzelner Anhang wird immer verarbeitet. - **Kein verwertbarer Anhang.** Bleibt kein Anhang übrig, liest Workist die Daten aus dem E-Mail-Text. - **Ignoriert** werden leere Dateien, Signaturen (`.p7s`), Visitenkarten (`.vcf`), Kalendereinladungen (`.ics`), ausführbare Dateien und alle anderen oben nicht aufgeführten Dateitypen sowie Dateien, die in den E-Mail-Text eingebettet sind (außer PDF). ## Schritt 2 — Selbstbedienungsformulare Selbstbedienungsformulare gibt es nur in **Bestellkanälen**. Wählen Sie in der Navigation unter **Eingehende Dokumente** den Eintrag **Selbstbedienungsformulare**. Zum Einrichten brauchen Sie die Berechtigung, Selbstbedienungsformulare einzurichten (Rollen **Manager** und **Admin**), siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). Über ein Selbstbedienungsformular erfassen Ihre Kund:innen Bestellungen in einer Webseite statt per E-Mail. Jede Eingabe legt im Kanal eine Bestellung an. :::note Formulareingaben gehen direkt in die Assistenz Workist extrahiert Formulareingaben nicht und verarbeitet sie nie automatisch. Jede Eingabe landet als Bestellung in der Assistenz und muss dort von Ihrem Team geprüft und abgeschlossen werden. Eine Eingabe kann bis zu 500 Positionen enthalten. ::: Die Einrichtung hat zwei Ebenen: **Formulare** (Vorlagen) und **Kundenlinks** (ein persönlicher Link pro Kunde). ### Formular anlegen Ein Formular legt fest, was Ihre Kund:innen sehen. Füllen Sie unten auf der Seite das Formular für ein neues Formular aus und speichern Sie es. | Einstellung | Standard | Bedeutung | | --- | --- | --- | | Name | — | Interner Name, an dem Sie das Formular erkennen. | | Einleitungstext (optional) | leer | Text oben im Formular, z. B. Hinweise zu Lieferzeiten. | | Formularfelder | alle sichtbar | Die Kopf- und Positionsfelder aus der Feldkonfiguration des Kanals. Entfernen Sie das Häkchen bei Feldern, die im Formular nicht erscheinen sollen. | | Formularanfragen erlauben | an | Kund:innen können über die öffentliche Anfrageseite des Formulars einen eigenen Link anfordern (siehe unten). | | Anfragen automatisch bestätigen | aus | Anfragen, deren E-Mail-Adresse genau einem Kontakt in Ihren Stammdaten entspricht, werden automatisch bestätigt, und der Link wird sofort verschickt. | :::note Welche Felder im Formular erscheinen können, hängt von der Feldkonfiguration in [Dokumentenverarbeitung → Kopffelder / Positionzeilenfelder](/docs/channel-configuration/document-processing.md) ab. Wenn ein Feld fehlt, aktivieren Sie es zuerst dort. ::: ### Kundenlink anlegen Ein Kundenlink ist ein persönlicher Link für genau einen Kunden. Wählen Sie in der Formularliste beim gewünschten Formular die Aktion zum Hinzufügen eines Kundenlinks und füllen Sie aus: - den Kunden: Suchen Sie ihn in Ihren Stammdaten. Ist für den Kanal noch keine Kunden-Stammdatenquelle eingerichtet, geben Sie die Kundennummer (`client_id1`) von Hand ein. - den Anzeigenamen des Kunden: Er wird oben im Formular angezeigt und bei Auswahl aus den Stammdaten automatisch gefüllt. Nach dem Anlegen kopieren Sie den Link aus der Liste und schicken ihn an den Kunden. Wer den Link öffnet, bestellt für diesen Kunden und sieht dessen kundenspezifische Stammdaten (z. B. Preise). ### Links über die Anfrageseite anfordern lassen Jedes Formular hat eine **öffentliche Anfrageseite**, deren Adresse Sie aus der Formularliste kopieren. Diesen Link können Sie offen teilen, z. B. auf Ihrer Website. Kund:innen geben dort ihre E-Mail-Adresse, optional Telefonnummer und eine Notiz ein. Workist sucht daraufhin in Ihren Stammdaten nach einem passenden Kontakt: | Ergebnis der Suche | Was passiert | | --- | --- | | E-Mail-Adresse entspricht genau einem Kontakt | Der Kunde wird vorbelegt. Ist die automatische Bestätigung eingeschaltet, legt Workist den Kundenlink an und schickt ihn sofort an die anfragende Person. Sonst wartet die Anfrage auf Ihre Prüfung. | | Nur die E-Mail-Domain passt zu einem Kunden | Der Kunde wird vorbelegt, die Anfrage wartet **immer** auf Ihre Prüfung. | | Kein Treffer | Die Anfrage wartet auf Ihre Prüfung; Sie wählen den Kunden beim Bestätigen aus. | Offene Anfragen erscheinen oben auf der Seite. Bestätigen Sie eine Anfrage, legt Workist den Kundenlink an und schickt ihn per E-Mail an die anfragende Person. Lehnen Sie sie ab, wird kein Link verschickt. Benutzer:innen mit der Rolle **Manager** erhalten für jede neue Anfrage, die auf Prüfung wartet, eine E-Mail. Fragt dieselbe E-Mail-Adresse erneut an, entsteht keine zweite Anfrage; war der Link schon bestätigt, wird er erneut verschickt. ### Formular oder Link löschen Löschen Sie einen Kundenlink, funktioniert er sofort nicht mehr. Löschen Sie ein Formular, funktionieren seine Anfrageseite und alle zugehörigen Kundenlinks sofort nicht mehr. Beides lässt sich nicht rückgängig machen. ## Sprachagenten {#sprachagenten} Sprachagenten (Zusatzleistung) nehmen Bestellungen und Preisanfragen am Telefon entgegen. Sie sind kein Teil der Kanal-Konfiguration mehr, sondern haben einen eigenen Bereich in der Workbench. Ein Sprachagent legt seine Dokumente in dem Bestell- bzw. Preisanfragekanal an, den Sie in seiner Konfiguration auswählen. Einrichtung und Voraussetzungen: [Sprachagenten](/docs/agents/voice-agents.md). ## Dateien direkt hochladen {#dateien-direkt-hochladen} Sie können Dateien auch selbst in einen Kanal hochladen, z. B. um die Konfiguration zu testen: 1. Öffnen Sie die Dokumentenübersicht des Kanals. 2. Klicken Sie oben rechts auf **Datei senden...** → **Vom Computer hochladen**. 3. Wählen Sie eine oder mehrere Dateien aus oder ziehen Sie sie in das Fenster, und klicken Sie auf **Hochladen**. Es gelten dieselben Dateitypen wie oben. Eine hochgeladene `.eml`- oder `.msg`-Datei verarbeitet Workist wie eine E-Mail, die im Postfach eingegangen ist, einschließlich ihrer Anhänge. Workist trägt Sie als Ersteller:in ein und weist Ihnen das Dokument zu. ## Häufige Fragen **Kann ich E-Mail und Sprachagent parallel nutzen?** Ja. Ein Sprachagent ist unabhängig vom E-Mail-Postfach. Wählen Sie in der Konfiguration des Sprachagenten denselben Kanal, landen telefonisch erfasste Bestellungen als eigene Dokumente neben den E-Mail-Dokumenten in diesem Kanal. Siehe [Sprachagenten](/docs/agents/voice-agents.md). **Was passiert, wenn ich die E-Mail-Konfiguration deaktiviere?** Bereits eingegangene E-Mails bleiben erhalten und in Bearbeitung. Neue E-Mails an die Adresse werden nicht mehr verarbeitet. Stimmen Sie die Umstellung mit Ihren Absender:innen und Ihrer Ansprechperson bei Workist ab. **Werden Formulareingaben automatisch verarbeitet?** Nein. Jede Formulareingabe landet als Bestellung in der Assistenz und muss von Ihrem Team abgeschlossen werden, auch wenn die Automatisierung des Kanals eingeschaltet ist. **Wer sieht den Link zum Selbstbedienungsformular?** Ein **Kundenlink** enthält einen zufälligen, geheimen Schlüssel, keine Kundendaten. Er ist aber fest an einen Kunden gebunden und zeigt dessen kundenspezifische Stammdaten (z. B. Preise). Geben Sie ihn nur an diesen Kunden weiter und löschen Sie ihn, wenn er in falsche Hände geraten ist. Den Link zur **Anfrageseite** eines Formulars können Sie offen teilen; er zeigt keine Kundendaten. ## Hilfe und Support Wenn ein Eingangsweg nicht wie erwartet funktioniert, halten Sie beim Kontakt zu Workist folgende Informationen bereit: - den **Kanalnamen** und welchen **Eingang** (E-Mail / Formular / Hochladen) es betrifft, - bei E-Mail-Problemen: den **Postfachnamen** und die Absenderadresse, von der eine Testmail kam, - bei Formular-Problemen: den **Namen des Formulars**, den **Kunden**, dem der Link zugeordnet ist, und ggf. den Link, den die kundenseitige Person geöffnet hat. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing.md # Kanal-Konfiguration — Dokumentenverarbeitung Im Bereich **Dokumentenverarbeitung** legen Sie fest, **was Workist mit einem eingehenden Dokument macht**, sobald es im Kanal angekommen ist — welche Felder extrahiert werden, ab welcher Sicherheit die Verarbeitung automatisch passiert, welche Stammdaten herangezogen werden und wie mit Dokumenten umgegangen wird, die nicht in den Kanal gehören. Diese Seite gibt einen Überblick über die Einträge der Navigation unter **Dokumentenverarbeitung**, in ihrer Reihenfolge: 1. **[Dokument](/docs/channel-configuration/document-processing/document.md)** — allgemeine Verarbeitungs-Einstellungen pro Kanal (Lokalisierung, Automatisierung, Benutzerzuweisung, Datumsformat, Validierung, …). 2. **[Kopffelder](/docs/channel-configuration/document-processing/header-fields.md)** — welche Kopfdaten extrahiert werden und mit welchen Optionen. 3. **[Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md)** — welche Felder pro Position extrahiert werden. 4. **[Agentische Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md)** — optionale LLM-basierte Extraktion zusätzlicher Felder. In der Navigation als zwei Einträge **Agentische Kopfzeilenextraktion** und **Agentische Positionsextraktion**; beide sind in einer gemeinsamen Anleitung beschrieben. 5. **Stammdaten** — welche Stammdaten (Lookups) für Artikel, Kunden, Adressen, … verwendet werden (siehe Schritt 5). 6. **Verwerfen** — was mit verworfenen Dokumenten passiert (siehe Schritt 6). Zwei Referenzseiten ergänzen diese Anleitungen: - **[Validierungsprüfungen und Assistenzgründe](/docs/channel-configuration/document-processing/validation-checks.md)** — wann Workist automatisiert, alle Prüfungen und die Assistenzgründe in Analytics. - **[Abgleich mit Bestell- und Angebotsdaten](/docs/channel-configuration/document-processing/matching.md)** — Angebots- und Bestellabgleich, Vorbefüllen leerer Dokumente. ## Voraussetzungen - Zugriff auf die Kanal-Konfiguration (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). - Für **Stammdaten**: vorab eingerichtete Stammdaten im [Master Data Hub](/docs/master-data/master-data-hub.md). - Für **Agentische Extraktion**: Verständnis darüber, welche zusätzlichen Felder die KI extrahieren soll und welche Datenquellen ihr dafür zur Verfügung stehen. ## Schritt 1 — Dokument: zentrale Verarbeitungs-Einstellungen Wählen Sie in der Navigation unter **Dokumentenverarbeitung** den Eintrag **Dokument**. Diese Seite ist nach Themen sortiert. Jeder Themenblock hat einen **Speichern**-Button; jeder davon speichert alle Änderungen auf der Seite. ![Dokument-Konfiguration mit den Blöcken Lokalisierung und Automatisierung](/img/channel-config/05-verarbeitung-dokument.png) | Themenblock | Wichtigste Einstellungen | | --- | --- | | **Lokalisierung** | **Zeitzone** und **Feiertagskalender** des Kanals. Überschreibt die Einstellungen auf Kundenebene für diesen Kanal. | | **Automatisierung** | **Automatisierung aktiviert** als globaler Schalter. **Konfidenzschwellenwert der Kopfdaten/Positionzeilen (%)**: Jedes Feld muss diesen Wert einzeln erreichen, damit das Dokument ohne Assistenz übergeben wird. Ohne gespeicherten Wert gilt 100 %. | | **Benutzerzuweisung** | Weist Dokumente automatisch der verantwortlichen Person aus Ihren Stammdaten zu. | | **Datenformatierung** | **Datumsformat**, **Adressformat** (Straßenname zuerst / Straßennummer zuerst) und **Dezimaltrennzeichen** der Ausgabedatei. | | **Einheitenumrechnung** | **Konversionsstil** (Keine / Aufrunden / 30 %-Regel), Optionen zum Überschreiben der Originalfelder, für bestmögliche und für kundenspezifische Umrechnung. | | **Validierung** | **Validierungsprüfungen** — Mehrfachauswahl aus den fachlichen Prüfungen (Gesamtbetrag, Positionssumme, Positionsnummer, …), Regeln für Mindestmengen und Artikelstatus sowie **Schlüsselwörter zur Unterstützung**. Alle Prüfungen: [Validierungsprüfungen](/docs/channel-configuration/document-processing/validation-checks.md). | | **Dokumenttypspezifisch** | Einstellungen, die nur den jeweiligen Dokumenttyp betreffen (z. B. **Bestellformulare unterstützen**, **Frachtkostenpositionen entfernen**, Factur-X bei Rechnungen). | | **Auffüllen** | **Mit E-Mail-Daten auffüllen** und **Dokumentformate für das Auffüllen** — fehlende Kopffelder füllt Workist aus dem E-Mail-Text auf, sofern am Feld **Auffüllen aktiviert** eingeschaltet ist. | | **Dokumentenfilterung** | **Dokumenttypen aussortieren** und **Filterempfindlichkeit** — bei E-Mails mit mehreren Anhängen entscheidet Workist, welche Anhänge zu einem Dokument werden. | :::warning Automatisierung wird mit Workist eingerichtet Die Automatisierung (globaler Schalter und Konfidenzschwellen) wird normalerweise gemeinsam mit Ihrer Ansprechperson bei Workist eingerichtet und konfiguriert. Eigene Anpassungen hier sind **nicht empfohlen** und erfolgen auf eigene Gefahr. ::: Die vollständige Schritt-für-Schritt-Anleitung zu allen Themenblöcken finden Sie unter **[Dokument](/docs/channel-configuration/document-processing/document.md)**. ## Schritt 2 — Kopffelder Wählen Sie in der Navigation unter **Dokumentenverarbeitung** den Eintrag **Kopffelder**. Hier legen Sie fest, welche Kopfdatenfelder (z. B. Auftragsart, Bestellnummer, Kundenkontakt) Workist aus dem Dokument extrahiert und welche Eigenschaften jedes Feld hat. ![Konfiguration der Kopffelder mit Feldliste links und Optionen rechts](/img/channel-config/06-verarbeitung-kopffelder.png) Der Aufbau ist zweispaltig: links die Liste der **konfigurierten Felder**, rechts die **Konfigurationsoptionen** für das gerade ausgewählte Feld. Im Alltag legen Sie hier vor allem fest, **welche** Standardfelder extrahiert werden, ob ein Feld **erforderlich** ist und in welcher **Reihenfolge** die Felder in der Assistenz erscheinen. Viele Felder haben zusätzlich eigene Optionen, z. B. Adress-Fallbacks, Regeln für das Lieferdatum oder einen Ersatz für eine fehlende Belegnummer. Vollständige Anleitung: **[Kopffelder](/docs/channel-configuration/document-processing/header-fields.md)**. ## Schritt 3 — Positionzeilenfelder Wählen Sie in der Navigation unter **Dokumentenverarbeitung** den Eintrag **Positionzeilenfelder**. Die Bedienlogik ist identisch zu den Kopffeldern; gegenüber den Kopffeldern kommen einige positionszeilen-spezifische Optionen hinzu. ![Konfiguration der Positionzeilenfelder, hier Artikelnummer mit Lookup-Optionen](/img/channel-config/07-verarbeitung-positionzeilenfelder.png) Hier finden Sie u. a. **Lookups durchführen**, **Ungültige IDs zulassen**, **Externe Artikelnummer beibehalten** und **Imperfekte Artikelübereinstimmungen zurücksetzen** an der Artikelnummer sowie **Dezimalmengen erlauben**, **Nullmengen erlauben** und **Maximalwert** an der Menge. Die **Maximale Feldlänge** gibt es an allen Textfeldern, auch bei den Kopffeldern. Vollständige Anleitung: **[Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md)**. ## Schritt 4 — Agentische Extraktion In der Navigation finden Sie unter **Dokumentenverarbeitung** zwei Einträge: **Agentische Kopfzeilenextraktion** (pro Dokument) und **Agentische Positionsextraktion** (pro Position). Hier hinterlegen Sie **LLM-gestützte Extraktoren**, die zusätzlich zur regulären Feldextraktion arbeiten — typischerweise für Felder, die mit klassischer Extraktion schwer zu erfassen sind (z. B. fließtextbasierte Anweisungen, dokumentspezifische Klauseln). ![Agentische Kopfzeilenextraktion, leerer Zustand vor Anlegen der ersten Konfiguration](/img/channel-config/08-verarbeitung-llm-kopf.png) :::tip Wann sich agentische Extraktion lohnt Wenn ein Feld nicht immer an derselben Stelle steht, in Freitext eingebettet ist oder kombinierte Logik erfordert (z. B. „Bestellart ableiten aus Marke + Versandadresse"). Für straff strukturierte Felder reicht die reguläre Extraktion in *Kopffelder* / *Positionzeilenfelder*. ::: Beide Varianten sind in einer gemeinsamen Anleitung beschrieben: **[Agentische Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md)**. ## Schritt 5 — Stammdaten Wählen Sie in der Navigation unter **Dokumentenverarbeitung** den Eintrag **Stammdaten**. Hier legen Sie fest, welche Stammdaten der Kanal für den Abgleich verwendet. ![Stammdaten-Konfiguration des Kanals](/img/channel-config/10-verarbeitung-stammdaten.png) Die Seite hat drei Blöcke: | Block | Einträge (Auswahl) | | --- | --- | | **Stammdaten Lookups** | **Client-Lookup-ID** (Kunden), **Kontakt-Lookup-ID**, **Rechnungsadressen-Lookup-ID**, **Lieferadressen-Lookup-ID**, **Artikel-Lookup-ID**, **Debitorenartikel-Lookup-ID** (kundenspezifische Artikel), **Umrechnungsfaktor-Lookup-ID**, **ID der Rahmenvertragsuche** | | **Stammdaten Mappings** | Gespeicherte Zuordnungen aus der Assistenz, z. B. **Artikelmapping-Lookup-ID** | | **Stammdatenabgleich** | **Bestellabgleich-Lookup-ID** und **Angebotsabgleich-Lookup-ID** für den [Abgleich](/docs/channel-configuration/document-processing/matching.md) | Pro Eintrag wählen Sie aus einer Liste die passenden Stammdaten Ihres Unternehmens aus; angeboten werden nur Stammdaten des passenden Typs. Das **Zahnrad-Symbol** rechts daneben öffnet diese Stammdaten im [Master Data Hub](/docs/master-data/master-data-hub.md) in einem neuen Tab. Dort laden Sie Dateien hoch und richten den Import ein. Das Symbol sehen nur Benutzer:innen, die Stammdaten verwalten dürfen. :::note Was passiert, wenn keine Artikel-Stammdaten hinterlegt sind? Der Abgleich findet nicht statt. Bei der Artikelnummer heißt das: Ist am Positionsfeld *Artikelnummer* **Ungültige IDs zulassen** aus (Standard), bleibt die Artikelnummer leer, sofern Workist sie nicht aus gelernten Zuordnungen kennt. Ist die Option an, übernimmt Workist die Nummer aus dem Dokument unverändert. ::: Klicken Sie nach Änderungen auf **Speichern**. ## Schritt 6 — Verwerfen Wählen Sie in der Navigation unter **Dokumentenverarbeitung** den Eintrag **Verwerfen**. Hier regeln Sie, wer benachrichtigt wird, wenn ein Dokument im Kanal verworfen wird (z. B. weil eine Bearbeiter:in es manuell verwirft). ![Verwerfen-Konfiguration mit Weiterleitungsadressen und Rücksende-Schalter](/img/channel-config/11-verarbeitung-verwerfen.png) | Feld | Bedeutung | | --- | --- | | **E-Mail-Adressen der Empfänger** | Adressen, an die verworfene Dokumente mit Grund, Kanal und Link weitergeleitet werden — typischerweise ein internes Postfach für manuelle Sichtung. Bestätigen Sie jede Adresse einzeln. | | **E-Mail an den ursprünglichen Absender zurücksenden** | Wenn aktiv und der Absender des Dokuments ein Workbench-Benutzer Ihres Unternehmens ist, geht die Benachrichtigung an ihn **statt** an die Empfänger oben. Externe Absender erhalten nichts. | :::tip Empfehlung Hinterlegen Sie immer mindestens eine Weiterleitungsadresse. Sonst wird beim Verwerfen niemand benachrichtigt; die Dokumente sind nur in der Workbench als verworfen sichtbar. Anhänge, die die [Dokumentenfilterung](/docs/channel-configuration/document-processing/document.md#schritt-9--dokumentenfilterung) aussortiert, werden kein Dokument und lösen keine Benachrichtigung aus. ::: ## Häufige Fragen **In welcher Reihenfolge laufen die Konfigurationen?** Pro eingehender E-Mail: Dokumentenfilterung (welche Anhänge zu Dokumenten werden) → klassische Feldextraktion (Kopffelder / Positionzeilenfelder) einschließlich Stammdatenabgleich für Kunde, Kontakt, Adressen und Artikel; die agentische Positionsextraktion läuft dabei pro Position nach dem Artikelabgleich → agentische Kopfzeilenextraktion → Validierungsprüfungen und Abgleich → Entscheidung über Automatisierung oder Assistenz. Die Regel dafür steht unter [Wann wird automatisiert?](/docs/channel-configuration/document-processing/validation-checks.md#wann-wird-automatisiert). **Was ist der Unterschied zwischen Datenbezeichnungsname und Feldbezeichnungsname?** Beide gibt es bei benutzerdefinierten Feldern. Der **Datenbezeichnungsname** ist der technische Name in der Ausgabedatei und nach dem ersten Speichern fest. Der **Feldbezeichnungsname** ist nur das Label, das in der Workbench (Assistenz, Formulare) erscheint, und kann jederzeit geändert werden. Bei Standardfeldern ändern Sie das Label über den Anzeigenamen (**Display name**). ## Hilfe und Support Bei Problemen mit der Verarbeitung halten Sie folgende Informationen bereit: - den **Kanalnamen** und den Bereich (Dokument, Kopffelder, …), - die ID oder Bezeichnung eines konkreten **Beispiel-Dokuments**, das nicht wie erwartet verarbeitet wurde, - bei Stammdaten-Themen: die betroffenen **Stammdaten** und idealerweise die zuletzt importierte Datei, - bei agentischer Extraktion: den **Konfigurationsnamen**, ggf. den Prompt und die letzten erfolgreichen / fehlgeschlagenen Beispiele. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/document.md # Kanal-Konfiguration — Dokument Im Reiter **Dokument** der Kanal-Konfiguration legen Sie die zentralen Verarbeitungs-Einstellungen für einen einzelnen Kanal fest: Zeitzone, Automatisierungsschwellen, die automatische Zuweisung an Bearbeiter:innen, Datums- und Zahlenformate, Einheitenumrechnung, Validierungsprüfungen, dokumenttypspezifische Optionen, das Auffüllen fehlender Werte sowie das Aussortieren unpassender Anhänge. Die Seite ist in Themenblöcke gegliedert. Jeder Block hat einen eigenen **Speichern**-Button. Jeder dieser Buttons speichert **alle** Änderungen auf der Seite, auch die in anderen Blöcken. Ungespeicherte Änderungen gehen erst verloren, wenn Sie die Seite verlassen. ![Übersicht der Dokument-Konfiguration mit den Blöcken Lokalisierung und Automatisierung](/img/channel-config/dokument/01-uebersicht.png) ## Voraussetzungen - Ein Workbench-Konto mit Zugriff auf die Kanal-Konfiguration des betreffenden Kanals. - Klarheit darüber, welche Felder, Validierungen und Dokumenttypen für diesen Kanal relevant sind. Wenn Sie unsicher sind, fragen Sie Ihre Ansprechperson bei Workist — viele Werte sind ab Einrichtung sinnvoll vorbelegt und müssen nicht zwingend angepasst werden. :::note Die Einstellungen wirken **nur auf diesen Kanal**. Sie überschreiben gegebenenfalls Werte, die auf Kundenebene konfiguriert sind (z. B. die Zeitzone). Sollen mehrere Kanäle dieselben Einstellungen haben, müssen Sie sie pro Kanal pflegen. ::: ## Aufruf der Seite Öffnen Sie in der Workbench den gewünschten Kanal, klicken Sie auf **Kanal-Konfiguration** und wählen Sie unter der Gruppe **Dokumentenverarbeitung** den Eintrag **Dokument**. Die Seite zeigt die Themenblöcke von oben nach unten in derselben Reihenfolge, in der sie in dieser Anleitung beschrieben sind. ## Schritt 1 — Lokalisierung Im Block **Lokalisierung** stellen Sie die zeitliche und kalendarische Verortung des Kanals ein. ![Block „Lokalisierung" mit den Feldern Zeitzone und Feiertagskalender](/img/channel-config/dokument/02-lokalisierung.png) | Feld | Bedeutung | | --- | --- | | **Zeitzone** | Zeitzone des Kanals. Standardmäßig wird die auf Kundenebene angegebene Zeitzone verwendet. Hier können Sie sie für diesen Kanal überschreiben — relevant für die Interpretation und Anzeige von Datums- und Lieferzeitfeldern. | | **Feiertagskalender** | Welcher gesetzliche Feiertagskalender in den **Verarbeitungsregeln** für das Lieferdatum (Kopf- und Positionsfeld *Lieferdatum*) herangezogen wird, etwa um Werktage zu zählen. Wählbar sind Länder-, Bundesland- und US-Staat-Kalender (z. B. *Deutschland - Bayern* oder *USA - Kalifornien*). | Klicken Sie auf **Speichern**, sobald Sie die gewünschten Werte eingetragen haben. :::note Lassen Sie Zeitzone und Feiertagskalender leer, wenn die Kundeneinstellungen passen. Eingetragene Werte überschreiben die Vorgabe **nur für diesen Kanal** — eine versehentliche Abweichung kann zu falschen Lieferdaten führen. ::: ## Schritt 2 — Automatisierung Im Block **Automatisierung** wird festgelegt, **ob** und **ab welcher Sicherheit** Dokumente vollautomatisch ohne menschliche Assistenz an das Zielsystem übergeben werden. :::warning Automatisierung wird mit Workist eingerichtet Die Automatisierung wird normalerweise gemeinsam mit Ihrer Ansprechperson bei Workist eingerichtet und konfiguriert. Eigene Anpassungen an diesem Schalter und an den Konfidenzschwellen sind **nicht empfohlen** und erfolgen auf eigene Gefahr. Die folgende Beschreibung dient dem Verständnis der Werte. ::: ![Block „Automatisierung" mit Schalter und zwei Schwellenwert-Slidern](/img/channel-config/dokument/03-automatisierung.png) | Feld | Bedeutung | | --- | --- | | **Automatisierung aktiviert** | Globaler Schalter. Wenn aus, geht jedes Dokument in die Assistenz — unabhängig von den Schwellenwerten. | | **Konfidenzschwellenwert der Kopfdaten (%)** | **Jedes** Kopffeld muss mindestens diese Konfidenz erreichen. Es gibt keinen Durchschnitt: Ein einziges Feld darunter genügt, damit das Dokument in die Assistenz geht. | | **Konfidenzschwellenwert der Positionzeilen (%)** | **Jedes** Positionsfeld in **jeder** Position muss mindestens diese Konfidenz erreichen. | Ist kein Wert gespeichert, gilt für beide Schwellen **100 %**. Optionale Felder zählen nur, wenn sie einen Wert enthalten. Felder mit **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** zählen nicht. Auch bei erreichten Schwellen geht ein Dokument in die Assistenz, sobald eine Validierungsprüfung anschlägt. Die vollständige Regel finden Sie unter [Wann wird automatisiert?](/docs/channel-configuration/document-processing/validation-checks.md#wann-wird-automatisiert). Die beiden Schwellenwerte lassen sich getrennt einstellen — typischerweise wird der Wert für Positionzeilen etwas niedriger gewählt als der für Kopfdaten, weil eine Position oft uneindeutiger ist als z. B. die Bestellnummer. ![Beide Konfidenz-Slider hervorgehoben](/img/channel-config/dokument/04-automatisierung-schwellenwerte.png) ## Schritt 3 — Benutzerzuweisung Im Block für die Benutzerzuweisung legen Sie fest, ob Workist eingehende Dokumente automatisch einer verantwortlichen Person zuweist. Die Person steht in Ihren Stammdaten, in den Zusatzdaten (`extra_data`) des Kunden- bzw. Lieferantendatensatzes oder des abgeglichenen Angebots bzw. der abgeglichenen Bestellung. Der Block und seine Felder sind in der Workbench derzeit nur auf Englisch beschriftet. | Feld | Bedeutung | | --- | --- | | **Assign documents based on master data** | Schaltet die automatische Zuweisung ein. Standard: aus. | | **Responsible user source** | Woher die Person kommt: **Customer/supplier master data** (Kunden- bzw. Lieferanten-Stammdaten) oder **Matched order/offer data** (das über die Belegnummer abgeglichene Angebot bzw. die Bestellung; nur bei Bestellungen, Rechnungen und Auftragsbestätigungen, siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md)). | | **Master data field for responsible user** | Name des Felds in den Zusatzdaten, das die Person nennt — per E-Mail-Adresse oder vollem Namen (Vor- und Nachname in beliebiger Reihenfolge). Standard: `responsible_user`. | | **Default assignee email** | E-Mail-Adresse der Person, die das Dokument bekommt, wenn in den Stammdaten niemand steht. Leer: Solche Dokumente bleiben unzugewiesen. | Workist sucht die Person unter den aktiven Benutzer:innen Ihres Unternehmens. Gibt es sie nicht, bleibt das Dokument unzugewiesen, und die Prüfung **Assigned user not found** schlägt an. Damit geht das Dokument in die Assistenz (siehe [Validierungsprüfungen](/docs/channel-configuration/document-processing/validation-checks.md#automatische-prüfungen)). ## Schritt 4 — Datenformatierung Im Block **Datenformatierung** stellen Sie ein, **wie** extrahierte Werte in die Ausgabedatei geschrieben werden. ![Block „Datenformatierung" mit Datumsformat, Adressformat und Dezimaltrennzeichen](/img/channel-config/dokument/05-datenformatierung.png) | Feld | Bedeutung | | --- | --- | | **Datumsformat** | Wie Datumswerte in die Ausgabe geschrieben werden. Vorbelegt sind `%d.%m.%Y` (z. B. 31.01.2026), `%d/%m/%Y`, `%d-%m-%Y` und `%m/%d/%Y`. Über **Benutzerdefiniert…** lässt sich ein eigenes Datumsformat eintragen. | | **Adressformat** | Reihenfolge in Straßenangaben: **Straßenname zuerst** (z. B. *Main Street 123*) oder **Straßennummer zuerst** (z. B. *123 Main Street*). | | **Dezimaltrennzeichen** | Welches Zeichen in der Ausgabe als Dezimaltrennzeichen verwendet wird: **Komma** (`567,89`) oder **Punkt** (`567.89`). Hat keinen Einfluss darauf, wie das Dokument gelesen wird — nur auf die ausgehende Datei. | Jede dieser Einstellungen zeigt rechts neben der Auswahl eine kleine **Beispielausgabe** mit Ihren aktuellen Werten — so sehen Sie sofort, wie das resultierende Datum bzw. der formatierte Betrag aussehen wird. :::note Das Datums- und Dezimalformat muss zum **Zielsystem** passen, nicht zum Dokumentinhalt. Workist erkennt eingehende Werte automatisch in den gängigen Schreibweisen und konvertiert sie hier nur für die Ausgabedatei. Optionen wie **Dezimalmengen erlauben** oder **Ungültige IDs zulassen** finden Sie an den einzelnen Feldern unter [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md). ::: ## Schritt 5 — Einheitenumrechnung Wenn die Mengeneinheit im Dokument von der Bestelleinheit Ihres Zielsystems abweicht (z. B. *Stück* statt *Karton à 12*), rechnet Workist anhand der hinterlegten Umrechnungsfaktoren um. In diesem Block bestimmen Sie, **wie** diese Umrechnung erfolgt. :::note Setzt Stammdaten voraus Eine Einheitenumrechnung kann nur stattfinden, wenn für den Kanal entsprechende [Stammdaten zur Einheitenkonvertierung](/docs/master-data/unit-conversion.md) hinterlegt sind. Ohne diese Stammdaten bleibt die Konfiguration in diesem Block wirkungslos. ::: ![Block „Einheitenumrechnung" mit Konversionsstil und drei zusätzlichen Schaltern](/img/channel-config/dokument/06-einheitenumrechnung.png) | Feld | Bedeutung | | --- | --- | | **Konversionsstil** | Wie Workist mit krummen Ergebnissen umgeht (siehe unten). Drei Optionen stehen zur Auswahl, sowie ein freies Feld **Benutzerdefiniert…**. | | **Konversion überschreibt Originalfelder** | Wenn aktiv, ersetzt Workist die Originalwerte (Menge und Einheit aus dem Dokument) mit den umgerechneten Werten. Wenn aus, werden die Originalwerte zusätzlich neben den umgerechneten Werten ausgeliefert. | | **Bestmögliche Konversion** | Greift nur, wenn Workist keinen Umrechnungsfaktor findet. **An:** Die umgerechnete Menge wird mit der Originalmenge vorbelegt, die umgerechnete Einheit mit der ersten Verkaufseinheit des Artikels — als Vorschlag mit Konfidenz 0. **Aus:** Die umgerechneten Felder bleiben leer. In beiden Fällen prüft eine Bearbeiter:in die Werte in der Assistenz. | | **Partition-spezifische Einheitkonversion** | Wenn aktiv, nutzt Workist Umrechnungsfaktoren, die für den erkannten **Kunden** (seine Kundennummer) hinterlegt sind. Hilfreich, wenn ein Artikel je nach Kunde unterschiedliche Bestelleinheiten hat. | Die drei Optionen unter **Konversionsstil** unterscheiden sich darin, wie mit nicht-ganzzahligen Ergebnissen umgegangen wird: ![Alle drei Konversionsstile, der mittlere ist ausgewählt](/img/channel-config/dokument/07-konversionsstil-optionen.png) - **Keine Umrechnung** — die im Dokument stehende Menge und Einheit werden 1:1 übernommen. Nutzen Sie diese Option, wenn Sie Mengen aus externer Logik bereits passend bekommen. - **Aufrunden der umgerechneten Menge auf den nächsten ganzzahligen Wert** — jedes nicht-ganzzahlige Ergebnis wird auf die nächste volle Einheit aufgerundet. Sinnvoll, wenn das Zielsystem keine Dezimalmengen akzeptiert und Sie lieber etwas zu viel als zu wenig liefern. - **Mathematisch runden und das Vertrauen senken, wenn sich die gerundete Menge um mehr als 30% von der ursprünglichen Menge unterscheidet** — klassisches kaufmännisches Runden. Weicht das Ergebnis stark vom Ausgangswert ab, senkt Workist zusätzlich die Konfidenz, damit das Dokument eher in die Assistenz geht. :::note Wenn Sie **Konversion überschreibt Originalfelder** aktivieren, ist der Originalwert nach der Verarbeitung nicht mehr in der Ausgabe enthalten. Aktivieren Sie diese Option nur, wenn Ihr Zielsystem mit dem umgerechneten Wert weiterarbeiten kann. Rundet die Umrechnung eine Menge auf 0, muss die Menge in der Assistenz korrigiert werden. ::: ## Schritt 6 — Validierung Im Block **Validierung** stellen Sie ein, welche fachlichen Prüfungen Workist während der Verarbeitung auf das Dokument anwendet, und hinterlegen Schlüsselwörter, die das Dokument in die Assistenz schicken. ![Block „Validierung" mit Liste aller verfügbaren Prüfungen](/img/channel-config/dokument/08-validierung.png) ### Validierungsprüfungen Die **Validierungsprüfungen** sind eine Mehrfachauswahl. Schlägt eine aktivierte Prüfung an, geht das Dokument in die Assistenz und die Bearbeiter:in sieht den Hinweis — auch wenn die Prüfung nicht blockierend ist. Blockierende Prüfungen müssen zusätzlich vor dem Abschließen behoben sein. ![Alle Validierungsprüfungen im Überblick](/img/channel-config/dokument/09-validierungspruefungen.png) Welche Prüfungen zur Auswahl stehen, hängt vom Dokumenttyp ab. Bei neuen Kanälen sind **Vergessene Posten** und **Tausendertrennzeichen bei Mengen** eingeschaltet. Was jede Prüfung auslöst, für welche Dokumenttypen es sie gibt und welche Prüfungen immer oder automatisch laufen, steht in der Referenz [Validierungsprüfungen und Assistenzgründe](/docs/channel-configuration/document-processing/validation-checks.md). ### Regeln für Mindestmengen und Artikelstatus Schalten Sie die Prüfung **Min quantity** oder **Article status** ein, erscheint darunter ein Regel-Editor (**Min quantity rules** bzw. **Article status rules**). Dort legen Sie fest, welcher Wert aus den Artikel-Stammdaten geprüft wird und ob ein Verstoß blockiert. Die Einstellungen sind unter [Mindestmengen-Regeln](/docs/channel-configuration/document-processing/validation-checks.md#mindestmengen-regeln) und [Artikelstatus-Regeln](/docs/channel-configuration/document-processing/validation-checks.md#artikelstatus-regeln) beschrieben. Ohne Regel prüft Workist nichts. ### Schlüsselwörter zur Unterstützung Hinterlegen Sie Begriffe (jeweils mit Enter bestätigen), bei deren Vorkommen im Dokument **oder im E-Mail-Text** das Dokument **immer** in die Assistenz geht — unabhängig von der Konfidenz. Groß-/Kleinschreibung und Satzzeichen spielen keine Rolle; Begriffe aus mehreren Wörtern müssen direkt hintereinander stehen. Geeignet z. B. für „Eilauftrag“, „Korrektur“, „Bitte Rücksprache“. :::note Wörter, die bei der Kundenerkennung ignoriert werden Diese Einstellung finden Sie nicht hier, sondern als Option am Kopffeld *Kunde* (bzw. *Zulieferer*, *Absender / Lieferant*, *Kundenkontakt*) unter [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md). Workist ignoriert dann jeden Textbereich, der ein solches Wort enthält. ::: :::note Aktivieren Sie nur die Validierungsprüfungen, die für Ihren Anwendungsfall sinnvoll sind. Jede zusätzliche Prüfung erhöht die Anzahl der Dokumente in der Assistenz. Beobachten Sie nach jeder Änderung, ob die Trefferquote der jeweiligen Prüfung den Mehraufwand rechtfertigt. ::: ## Schritt 7 — Dokumenttypspezifisch Dieser Block erscheint nur bei Kanälen, deren Dokumenttyp eigene Optionen mitbringt (insbesondere Bestellungen und Rechnungen). Er enthält Einstellungen, die nur für genau diesen Dokumenttyp sinnvoll sind. ![Block „Dokumenttypspezifisch" für Bestellungen](/img/channel-config/dokument/10-dokumenttypspezifisch.png) | Feld | Bedeutung | | --- | --- | | **Trainingsbeispiele für Variantenextraktion** | Eingabefeld für Beispielzuordnungen zur Variantenextraktion. Wird in der Regel gemeinsam mit Ihrer Ansprechperson bei Workist gepflegt. | | **Standardwährung** | Welche Währung verwendet wird, wenn das Dokument keine Währung explizit nennt. Vorbelegt sind **EUR** und **USD**; eigene Codes lassen sich über **Benutzerdefiniert…** eintragen. | | **Länderkennzeichen des Dokumentempfängers** | Wird als Reserve für das Datumsgebietsschema verwendet (z. B. um `07/04/2026` als 4. Juli statt 7. April zu interpretieren). Setzen Sie das Land, in dem Ihre belieferte Niederlassung steht. | | **Frachtkostenpositionen entfernen** | Wenn aktiv, prüft ein Sprachmodell die **letzte** Position eines Dokuments mit mindestens zwei Positionen anhand ihrer Beschreibung. Ist sie eine Frachtkostenposition, entfernt Workist sie. Der Betrag wird nicht in ein Kopffeld übernommen. | | **Bestellformulare unterstützen** | Wenn aktiv, verarbeitet Workist auch klassische Bestellformulare (Templates mit Ankreuzfeldern und Mengenspalten neben einer Artikelliste). | | **Factur-X-Erkennung aktivieren** (nur Rechnungen) | Liest die eingebetteten XML-Daten hybrider PDF/A-Rechnungen (**ZUGFeRD**, **Factur-X**). Rechnungen, die als reine XML-Datei ankommen (XRechnung, ZUGFeRD CII), liest Workist immer aus dem XML; dafür ist keine Einstellung nötig. | :::note Welche Felder sichtbar sind, hängt vom Dokumenttyp des Kanals ab. Fehlt Ihnen ein hier dokumentiertes Feld, ist es für Ihren Kanaltyp deaktiviert und nicht relevant. Die Option, die Kommissionsnummer aus dem Kopf als Fallback zu verwenden, finden Sie am Positionsfeld *Kommissionsnummer* unter [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md). ::: ## Schritt 8 — Auffüllen Wenn ein Kopffeld im Dokument leer bleibt, kann Workist es aus dem **E-Mail-Text** der Nachricht **auffüllen**, mit der das Dokument eingegangen ist. ![Block „Auffüllen" mit Schalter und Format-Auswahl](/img/channel-config/dokument/11-auffuellen.png) | Feld | Bedeutung | | --- | --- | | **Mit E-Mail-Daten auffüllen** | Schaltet das Auffüllen aus dem E-Mail-Text für den Kanal ein. | | **Dokumentformate für das Auffüllen** | Bei welchen Dokumenten aufgefüllt wird, abhängig vom Format der eingegangenen Datei: **Alle Dokumententypen**, **PDF-Dateien** oder **Excel-Dateien**. Ohne Auswahl gilt: alle. | Aufgefüllt werden nur Kopffelder, bei denen die Feldoption **Auffüllen aktiviert** eingeschaltet ist. Diese Option erscheint an den Feldern unter [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md), sobald **Mit E-Mail-Daten auffüllen** für den Kanal aktiv ist. Ohne sie füllt Workist nichts auf. Werte, die im Dokument gefunden wurden, werden nie überschrieben. :::tip Das Auffüllen aus E-Mail-Daten ist besonders nützlich, wenn Ihre Kunden Bestellnummern oder Liefertermine regelmäßig im Mail-Text angeben. Schalten Sie es testweise zu, aktivieren Sie **Auffüllen aktiviert** an den betreffenden Kopffeldern und beobachten Sie, ob die Trefferquote steigt. ::: ## Schritt 9 — Dokumentenfilterung Workist macht aus jedem Anhang einer E-Mail ein eigenes Dokument. Mit der **Dokumentenfilterung** entscheiden Sie, welche Anhänge **nicht** zu einem Dokument werden sollen: Workist klassifiziert jeden Anhang (Bestellung, Rechnung, Lieferschein, …) und sortiert Anhänge eines anderen Typs aus, bevor die Verarbeitung startet. Im inaktiven Zustand ist nur der Umschalter rechts oben sichtbar. Klicken Sie auf den Umschalter, um die Filterung zu aktivieren — darunter erscheinen dann zwei zusätzliche Felder: ![Aktivierter Block „Dokumentenfilterung" mit Dokumenttypen und Filterempfindlichkeit](/img/channel-config/dokument/13-dokumentenfilterung-aktiviert.png) | Feld | Bedeutung | | --- | --- | | **Dokumenttypen aussortieren** | Liste aller Dokumenttypen. Aktivieren Sie pro Typ den Schalter, wenn Anhänge dieses Typs aussortiert werden sollen. Der eigene Dokumenttyp des Kanals (z. B. *Bestellung*) ist dauerhaft deaktiviert. Anhänge, die keinem Dokumenttyp entsprechen, sortiert Workist immer aus. | | **Filterempfindlichkeit** | Wie sicher die Klassifikation sein muss: **Streng** (95 % Vertrauen), **Ausgewogen** (90 %) oder **Leicht** (80 %). Ein Anhang wird nur aussortiert, wenn die Sicherheit **über** diesem Wert liegt. | ![Hervorgehobene Mehrfachauswahl der Dokumenttypen](/img/channel-config/dokument/15-dokumenttypen-aussortieren.png) Die Liste der Dokumenttypen umfasst: - **Lieferschein** - **Rechnung** - **Angebot** - **Bestellung** - **Bestellbestätigung** - **Preisanfragen** So wirkt die Filterung: - Sie greift nur bei E-Mails mit **mehreren** Anhängen. Ein einzelner Anhang wird immer verarbeitet. - Aussortierte Anhänge werden **kein Dokument**. Sie durchlaufen nicht den Verwerfen-Workflow und werden nicht weitergeleitet. - Bleibt kein Anhang übrig, verarbeitet Workist trotzdem etwas: Bei Bestellkanälen die aussortierten Lieferscheine, sonst die aussortierten PDF-Anhänge oder, wenn es keine gibt, den E-Mail-Text. - Sind unter den verbleibenden Anhängen PDF-Dateien, verarbeitet Workist nur diese. ![Filterempfindlichkeit mit drei Stufen und Prozentsätzen](/img/channel-config/dokument/14-filterempfindlichkeit.png) Die drei Empfindlichkeitsstufen unterscheiden sich darin, **wie sicher** die Klassifikation sein muss, damit ein Anhang aussortiert wird: - **Streng (95 % Vertrauen)** — sortiert nur dann aus, wenn Workist sich nahezu sicher ist. Risiko: Ein paar unpassende Anhänge rutschen trotzdem durch. - **Ausgewogen (90 % Vertrauen)** — Standardempfehlung. - **Leicht (80 % Vertrauen)** — sortiert auch bei mittlerer Sicherheit aus. Risiko: gelegentlich werden auch passende Anhänge aussortiert. :::tip Wenn Sie die Dokumentenfilterung neu aktivieren, beginnen Sie mit **Ausgewogen** und prüfen Sie über zwei bis drei Tage, ob aus E-Mails mit mehreren Anhängen die richtigen Dokumente entstehen. Erst danach entscheiden Sie, ob Sie strenger oder leichter filtern wollen. Aussortierte Anhänge finden Sie weiterhin in der ursprünglichen E-Mail. ::: ## Häufige Fragen **Muss ich nach jeder Änderung explizit speichern?** Ja. Klicken Sie auf einen der **Speichern**-Buttons; er speichert alle Änderungen auf der Seite. Wenn Sie die Seite ohne Speichern verlassen, gehen Ihre Änderungen verloren. **Warum sehe ich den Block „Dokumenttypspezifisch" nicht?** Der Block erscheint nur, wenn der Dokumenttyp Ihres Kanals entsprechende Optionen mitbringt. Bei einigen Dokumenttypen (z. B. reinen Lieferscheinkanälen) ist er nicht relevant und wird automatisch ausgeblendet. **Kann ich für einzelne Felder einen eigenen Konfidenzschwellenwert setzen?** Nein. Die beiden Schwellen gelten für jedes Kopf- bzw. Positionsfeld. Pro Feld können Sie nur die Konfidenzprüfung ganz abschalten: mit **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** unter [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md) bzw. [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md). **Was passiert mit Anhängen, die hier aussortiert wurden?** Sie werden kein Dokument und tauchen nicht in der Workbench-Übersicht auf. Der Reiter **Verwerfen** gilt nur für Dokumente, die verworfen werden, nicht für aussortierte Anhänge. ## Hilfe und Support Wenn Sie unsicher sind, welche Einstellung für Ihren Kanal sinnvoll ist, oder wenn nach einer Änderung Dokumente nicht mehr wie erwartet verarbeitet werden, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie folgende Informationen bereit: - den **Kanalnamen**, - den betreffenden **Themenblock** (Lokalisierung, Automatisierung, …), - die **vorgenommenen Änderungen** (welcher Wert vorher, welcher Wert jetzt), - ein **konkretes Beispiel-Dokument**, an dem das Problem auftritt, - bei Validierungsthemen: die genaue **Validierungsprüfung**, die fälschlich anschlägt oder nicht anschlägt. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/header-fields.md # Kanal-Konfiguration — Kopffelder Auf der Seite **Kopffelder** legen Sie fest, **welche Kopfdaten Workist aus einem eingehenden Dokument extrahiert** und wie jedes Feld sich in der weiteren Verarbeitung verhält: - ob es ein **Pflichtfeld** ist (also fehlende Werte das Dokument in die Assistenz lenken), - ob das Feld die **Automatisierung blockieren** darf, wenn seine Konfidenz unter dem Schwellenwert des Kanals liegt, - wie Workist das Feld erkennt, ergänzt oder in den Stammdaten nachschlägt (**feldspezifische Optionen**), - in welcher **Reihenfolge** die Felder in der Assistenz erscheinen. :::note Benutzerdefinierte Felder Diese Anleitung beschreibt die Bearbeitung der **bereits vorhandenen Standard-Kopffelder** (Auftragsart, Kunde, Bestellnummer, …). Den vollständigen Workflow für **eigene** Felder — Anlegen über „Benutzerdefiniertes Feld", Datentyp, Optionen einschränken, Datenbezeichnungsname und Anweisungen für die KI — finden Sie in der Anleitung zur agentischen Extraktion unter [Benutzerdefinierte Felder als Ziel der agentischen Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). Eigene Kopffelder werden in der Regel über die LLM-Extraktion befüllt; der Anlege-Vorgang gehört deshalb thematisch dorthin. ::: ## Voraussetzungen - Ein Workbench-Konto mit Zugriff auf den Kanal. - Sie wissen, welche Standard-Kopffelder Ihr Zielsystem in der Kopfzeile der Ausgabedatei erwartet. - Vor strukturellen Änderungen empfiehlt sich eine kurze Abstimmung mit Ihrer Ansprechperson bei Workist. ## Schritt 1 — Aufbau der Seite Wechseln Sie in der Workbench zu Ihrem Kanal, öffnen Sie unter **Dokumentenverarbeitung** den Eintrag **Kopffelder**. ![Kopffelder-Seite mit Feldliste links und Konfigurationsoptionen rechts](/img/channel-config/kopffelder/01-overview.png) Die Seite ist **zweispaltig**: - **Links — „Konfigurierte Felder".** Liste aller Kopffelder, die für diesen Kanal aktiviert sind. Jeder Eintrag zeigt den Feldnamen und darunter den Status: | Status | Bedeutung | | --- | --- | | **Erforderlich** | Pflichtfeld. Fehlt der Wert, geht das Dokument in die Assistenz. | | **Optional** | Kein Pflichtfeld; ein leerer Wert blockiert die Automatisierung nicht. Ein Wert, der unter dem Konfidenzschwellenwert liegt, blockiert sie dagegen schon. | | *Zahl* (z. B. „3", „7") | Das Feld hat **Unterfelder** (z. B. *Lieferadresse → Firma, Name, Straße und Nr.*). Die Zahl gibt die Anzahl konfigurierter Unterfelder an. | Das gerade ausgewählte Feld ist farbig hinterlegt. Über das **„+"-Symbol** oben rechts in dieser Spalte fügen Sie ein weiteres Feld hinzu, über das **„×"-Symbol** in einer Zeile entfernen Sie das jeweilige Feld. - **Rechts — „Konfigurationsoptionen für ``".** Die detaillierten Einstellungen des links ausgewählten Felds. Welche Optionen erscheinen, hängt vom Feld ab — nicht jedes Feld unterstützt jede Option. Unten rechts auf der Seite finden Sie die zentrale Schaltfläche **Speichern**. Sie sichert alle Änderungen an allen Feldern in einem Schritt; verlassen Sie die Seite nicht, ohne vorher zu speichern, sonst gehen Bearbeitungen verloren. :::tip Reihenfolge Die Reihenfolge der Feldliste links ist die Reihenfolge, in der die Felder in der Assistenz erscheinen. Sie lässt sich per Drag-and-Drop ändern (mit der Maus über einen Eintrag fahren, das Greif-Symbol links anklicken und verschieben). ::: ## Schritt 2 — Ein bestehendes Feld bearbeiten Klicken Sie in der linken Spalte auf das Feld, das Sie ändern möchten — in unserem Beispiel **„Auftragsart"**. Die rechte Seite wechselt automatisch zu **„Konfigurationsoptionen für Auftragsart"**. ### 2.1 — Erforderlich Ganz oben in den Optionen finden Sie den Schalter **„Erforderlich"**. ![Schalter „Erforderlich" für das Feld Auftragsart hervorgehoben](/img/channel-config/kopffelder/02-feld-auftragsart-erforderlich.png) - **Aktiviert** — das Feld muss befüllt sein. Findet die Extraktion keinen Wert, geht das Dokument in die Assistenz, damit eine Bearbeiter:in den Wert manuell setzen kann. Der Wert muss außerdem den Konfidenzschwellenwert der Kopfdaten erreichen. - **Deaktiviert** — das Feld ist optional. Ein leerer Wert blockiert die Automatisierung nicht. Enthält das Feld einen Wert, muss dieser den Konfidenzschwellenwert erreichen. Sobald Sie den Schalter umlegen, ändert sich auch der Status des Eintrags in der linken Feldliste zwischen **Erforderlich** und **Optional**. ### 2.2 — Anzeigename und weitere Optionen Bei den vorbereiteten **Standardfeldern** sind alle weiteren Eigenschaften bereits sinnvoll vorbelegt. Über die Option für den Anzeigenamen (in der Workbench derzeit **Display name**) können Sie die Beschriftung des Felds in der Assistenz ändern. Bleibt sie leer, gilt die Standardbezeichnung. Die Ausgabedatei ändert sich dadurch nicht. Weitere Eigenschaften wie **Datentyp**, **Datenbezeichnungsname**, **Feldbezeichnungsname**, eine eingeschränkte Werteliste oder **Anweisungen für Datenbezeichnungen** gibt es nur bei **eigenen (benutzerdefinierten) Feldern**. Den vollständigen Workflow dazu finden Sie unter [Benutzerdefinierte Felder als Ziel der agentischen Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). ### 2.3 — Automatisierungs-Verhalten ![Toggle „Feld sollte die Automatisierung nicht blockieren" auf der Lieferadresse hervorgehoben](/img/channel-config/kopffelder/07-konfidenz-und-blockier-toggle.png) | Option | Bedeutung | | --- | --- | | **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** | Wenn aktiv, prüft Workist die Konfidenz dieses Felds nicht. Ein unsicher erkannter Wert schickt das Dokument dann **nicht** in die Assistenz. Ist das Feld erforderlich und leer, geht das Dokument trotzdem in die Assistenz. Sinnvoll für Felder, deren Wert für Sie zwar interessant, aber **nicht kritisch** ist. | :::note Kein eigener Schwellenwert pro Feld Der Konfidenzschwellenwert gilt für alle Kopffelder gemeinsam und wird unter [Dokument → Automatisierung](/docs/channel-configuration/document-processing/document.md#schritt-2--automatisierung) eingestellt. Jedes Feld muss ihn einzeln erreichen. Pro Feld können Sie die Prüfung nur mit der Option oben abschalten. Die vollständige Regel steht unter [Wann wird automatisiert?](/docs/channel-configuration/document-processing/validation-checks.md#wann-wird-automatisiert). ::: ### 2.4 — Auffüllen aktiviert Ist unter [Dokument → Auffüllen](/docs/channel-configuration/document-processing/document.md#schritt-8--auffüllen) die Option **Mit E-Mail-Daten auffüllen** eingeschaltet, erscheint an den Kopffeldern die Option **Auffüllen aktiviert**. Nur Felder, bei denen sie aktiv ist, füllt Workist aus dem E-Mail-Text auf, wenn das Dokument keinen Wert liefert. Standard: aus. ### 2.5 — Maximale Feldlänge Bei Textfeldern legen Sie fest, wie viele Zeichen ein Wert haben darf. | Option | Bedeutung | | --- | --- | | **Maximale Feldlänge** | Maximale Anzahl Zeichen, z. B. weil Ihr Zielsystem für das Feld nur eine feste Länge erlaubt. Leer: keine Begrenzung. | | **Automatisierung blockieren, wenn die maximale Feldlänge überschritten wird** | **An** (Standard): Ein zu langer Wert bleibt unverändert; die Bearbeiter:in muss ihn kürzen, bevor sie das Dokument abschließt. **Aus:** Workist kürzt den Wert auf die maximale Länge und zeigt einen Hinweis. Das Dokument geht trotzdem in die Assistenz, kann dort aber ohne Änderung abgeschlossen werden. | ### 2.6 — Feldspezifische Optionen Viele Standardfelder haben eigene Optionen. Die folgende Tabelle listet alle, die an Kopffeldern angeboten werden. Welche Sie sehen, hängt vom Dokumenttyp des Kanals ab. Optionen ohne deutsche Bezeichnung erscheinen in der Workbench mit dem englischen Namen. | Feld | Option | Wirkung | Dokumenttypen | | --- | --- | --- | --- | | AB Nr | **Document number fallback** | Hat das Dokument keine Belegnummer: **Processing date** setzt Datum und Uhrzeit der Verarbeitung ein. **Email subject** (Standard) und **Email timestamp** greifen nur, wenn die E-Mail selbst das Dokument ist, nicht bei Anhängen. | Auftragsbestätigung | | Absender / Lieferant | **Words to ignore when extracting this field** | Textbereiche, die eines dieser Wörter enthalten (ganzes Wort, ohne Groß-/Kleinschreibung), werden bei der Erkennung **komplett ignoriert**. Gedacht für Angaben zu Ihrem eigenen Unternehmen im Dokument (Firmenname, eigene Ansprechpersonen). Keine Rechtsformen wie „GmbH“ eintragen – damit fallen fast alle Firmennamen weg. | Rechnung | | Absender: Kontakt | **Lookups durchführen** | Sucht die Kontaktperson in den Kontakt-Stammdaten. Standard: an. | Rechnung | | Absender: Kontakt | **Ungültige IDs zulassen** | Wie beim Kunden: An lässt Kontakte zu, die nicht in den Stammdaten stehen. | Rechnung | | Absender: Kontakt | **Words to ignore when extracting this field** | Textbereiche, die eines dieser Wörter enthalten (ganzes Wort, ohne Groß-/Kleinschreibung), werden bei der Erkennung **komplett ignoriert**. Gedacht für Angaben zu Ihrem eigenen Unternehmen im Dokument (Firmenname, eigene Ansprechpersonen). Keine Rechtsformen wie „GmbH“ eintragen – damit fallen fast alle Firmennamen weg. | Rechnung | | Anfragenummer | **Document number fallback** | Hat das Dokument keine Belegnummer: **Processing date** setzt Datum und Uhrzeit der Verarbeitung ein. **Email subject** (Standard) und **Email timestamp** greifen nur, wenn die E-Mail selbst das Dokument ist, nicht bei Anhängen. | Preisanfrage | | Auftragsart | **Wert** | Fester Wert für alle Dokumente des Kanals. Ist er gesetzt, liest Workist die Auftragsart nicht aus dem Dokument. | Bestellung | | Bestellnummer | **Document number fallback** | Hat das Dokument keine Belegnummer: **Processing date** setzt Datum und Uhrzeit der Verarbeitung ein. **Email subject** (Standard) und **Email timestamp** greifen nur, wenn die E-Mail selbst das Dokument ist, nicht bei Anhängen. | Bestellung | | Entladearten | **Zuordnung** | Zuordnung von Schreibweisen im Dokument zu Ihren Entladearten. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Incoterm | **Zuordnung** | Zuordnung von Schreibweisen im Dokument zu Ihren Incoterm-Werten. | Bestellung, Auftragsbestätigung, Lieferschein | | Kunde | **Numeric locale per client** | Zahlenformat (Dezimaltrennzeichen) je Kundennummer, z. B. `[{"client_id": "12345", "locale_numeric": "en"}]`. Hat Vorrang vor Stammdaten und automatischer Erkennung. | Bestellung, Preisanfrage | | Kunde | **Words to ignore when extracting this field** | Textbereiche, die eines dieser Wörter enthalten (ganzes Wort, ohne Groß-/Kleinschreibung), werden bei der Erkennung **komplett ignoriert**. Gedacht für Angaben zu Ihrem eigenen Unternehmen im Dokument (Firmenname, eigene Ansprechpersonen). Keine Rechtsformen wie „GmbH“ eintragen – damit fallen fast alle Firmennamen weg. | Bestellung, Preisanfrage | | Kunde → Nummer | **Lookups durchführen** | Sucht den Geschäftspartner in den Kunden- bzw. Lieferantenstammdaten. Standard: an. | Bestellung, Preisanfrage | | Kunde → Nummer | **Ungültige IDs zulassen** | Aus (Standard): Wird kein Stammdatensatz gefunden, bleibt die Nummer leer, und in der Assistenz muss ein Eintrag aus den Stammdaten gewählt werden. An: Die Nummer aus dem Dokument bleibt stehen. | Bestellung, Preisanfrage | | Kundenkontakt | **Lookups durchführen** | Sucht die Kontaktperson in den Kontakt-Stammdaten. Standard: an. | Bestellung, Preisanfrage | | Kundenkontakt | **Ungültige IDs zulassen** | Wie beim Kunden: An lässt Kontakte zu, die nicht in den Stammdaten stehen. | Bestellung, Preisanfrage | | Kundenkontakt | **Words to ignore when extracting this field** | Textbereiche, die eines dieser Wörter enthalten (ganzes Wort, ohne Groß-/Kleinschreibung), werden bei der Erkennung **komplett ignoriert**. Gedacht für Angaben zu Ihrem eigenen Unternehmen im Dokument (Firmenname, eigene Ansprechpersonen). Keine Rechtsformen wie „GmbH“ eintragen – damit fallen fast alle Firmennamen weg. | Bestellung, Preisanfrage | | Käufer → Nummer | **Lookups durchführen** | Sucht den Geschäftspartner in den Kunden- bzw. Lieferantenstammdaten. Standard: an. | Auftragsbestätigung | | Käufer → Nummer | **Ungültige IDs zulassen** | Aus (Standard): Wird kein Stammdatensatz gefunden, bleibt die Nummer leer, und in der Assistenz muss ein Eintrag aus den Stammdaten gewählt werden. An: Die Nummer aus dem Dokument bleibt stehen. | Auftragsbestätigung | | Lieferadresse | **Kundenadresse als Fallback verwenden** | Steht keine Adresse im Dokument, übernimmt Workist die Adresse des erkannten Kunden. Standard bei Bestellungen: an für die Rechnungsadresse, aus für die Lieferadresse. | Bestellung, Preisanfrage | | Lieferadresse | **Käuferadresse als Fallback verwenden** | Steht keine Lieferadresse im Dokument, übernimmt Workist die Adresse des Käufers. | Auftragsbestätigung, Lieferschein | | Lieferadresse | **Lieferadressen-Schwellenwert entfernen (%)** | Ist die Lieferadresse der Adresse des Kunden (bei Auftragsbestätigungen und Lieferscheinen: des Lieferanten) mindestens so ähnlich wie dieser Wert, leert Workist die Lieferadresse. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Lieferadresse | **Nur Adressen aus Stammdaten zulassen** | Eine Lieferadresse ohne Treffer in den Adress-Stammdaten wird geleert. | Bestellung, Auftragsbestätigung, Lieferschein | | Lieferadresse | **Stammdaten Adresse als Fallback verwenden (wenn eindeutig)** | Steht keine Adresse im Dokument und hat der Kunde in den Adress-Stammdaten genau eine Adresse dieser Art, übernimmt Workist sie. | Bestellung, Preisanfrage | | Lieferbestätigungsnummer | **Document number fallback** | Hat das Dokument keine Belegnummer: **Processing date** setzt Datum und Uhrzeit der Verarbeitung ein. **Email subject** (Standard) und **Email timestamp** greifen nur, wenn die E-Mail selbst das Dokument ist, nicht bei Anhängen. | Lieferschein | | Lieferdatum | **Allow past delivery date** | Aus (Standard): Daten vor dem Bestelldatum werden nicht als Lieferdatum übernommen. An: erlaubt sie und schaltet die Prüfung *Bestelldatum* ab. | Bestellung, Auftragsbestätigung, Preisanfrage | | Lieferdatum | **Leeres Lieferdatum automatisch füllen** | Findet Workist kein Lieferdatum, setzt es das Verarbeitungsdatum plus diese Anzahl Werktage ein (Konfidenz 100 %). Leer: kein Auffüllen. | Bestellung, Auftragsbestätigung, Lieferschein | | Lieferdatum | **Lieferdatumsbereich verwenden** | An: Ein Lieferzeitraum im Dokument (z. B. eine Kalenderwoche) wird als Start- und Enddatum übernommen. Aus (Standard): Workist setzt ein einzelnes Datum innerhalb des Zeitraums. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Lieferdatum | **Lieferzeitraum mit Wochentag ersetzen** | Bei ausgeschaltetem Lieferdatumsbereich: der Wochentag im Zeitraum, der als Lieferdatum gesetzt wird (Standard: Freitag). | Bestellung | | Lieferdatum | **Verarbeitungsregeln** | Regeln aus Bedingung und Ausdruck, die das Lieferdatum anpassen, z. B. je Kunde oder unter Berücksichtigung des Feiertagskalenders. Die erste zutreffende Regel gilt. Richten Sie Regeln gemeinsam mit Workist ein. | alle | | Rechnungsadresse | **Kundenadresse als Fallback verwenden** | Steht keine Adresse im Dokument, übernimmt Workist die Adresse des erkannten Kunden. Standard bei Bestellungen: an für die Rechnungsadresse, aus für die Lieferadresse. | Bestellung | | Rechnungsadresse | **Stammdaten Adresse als Fallback verwenden (wenn eindeutig)** | Steht keine Adresse im Dokument und hat der Kunde in den Adress-Stammdaten genau eine Adresse dieser Art, übernimmt Workist sie. | Bestellung | | Rechnungsnummer | **Document number fallback** | Hat das Dokument keine Belegnummer: **Processing date** setzt Datum und Uhrzeit der Verarbeitung ein. **Email subject** (Standard) und **Email timestamp** greifen nur, wenn die E-Mail selbst das Dokument ist, nicht bei Anhängen. | Rechnung | | Zulieferer | **Numeric locale per client** | Zahlenformat (Dezimaltrennzeichen) je Kundennummer, z. B. `[{"client_id": "12345", "locale_numeric": "en"}]`. Hat Vorrang vor Stammdaten und automatischer Erkennung. | Auftragsbestätigung, Lieferschein | | Zulieferer | **Words to ignore when extracting this field** | Textbereiche, die eines dieser Wörter enthalten (ganzes Wort, ohne Groß-/Kleinschreibung), werden bei der Erkennung **komplett ignoriert**. Gedacht für Angaben zu Ihrem eigenen Unternehmen im Dokument (Firmenname, eigene Ansprechpersonen). Keine Rechtsformen wie „GmbH“ eintragen – damit fallen fast alle Firmennamen weg. | Auftragsbestätigung, Lieferschein | | Zulieferer → Nummer | **Lookups durchführen** | Sucht den Geschäftspartner in den Kunden- bzw. Lieferantenstammdaten. Standard: an. | Auftragsbestätigung | | Zulieferer → Nummer | **Ungültige IDs zulassen** | Aus (Standard): Wird kein Stammdatensatz gefunden, bleibt die Nummer leer, und in der Assistenz muss ein Eintrag aus den Stammdaten gewählt werden. An: Die Nummer aus dem Dokument bleibt stehen. | Auftragsbestätigung | ## Schritt 3 — Ein Standardfeld hinzufügen Möchten Sie ein **weiteres Kopffeld** in den Kanal aufnehmen, klicken Sie in der linken Spalte oben rechts auf das **„+"-Symbol**. ![Geöffnetes Dropdown-Menü mit auswählbaren Standard- und benutzerdefinierten Feldern](/img/channel-config/kopffelder/08-plus-dropdown.png) Das Dropdown listet zwei Arten von Einträgen: - **„Benutzerdefiniertes Feld"** (oberster Eintrag, abgesetzt durch eine Trennlinie) — legt ein **eigenes Feld** an, das Sie frei benennen können. Den vollständigen Workflow dazu finden Sie unter [Benutzerdefinierte Felder als Ziel der agentischen Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). - **Vorbereitete Standardfelder** (z. B. *„(voraussichtl.) Warenausgangsdatum"*, *„Anbieter des Carriers"*, *„Auftragsart"*, *„Carrier-Kontonummer"*, *„Dokument Typ"*, …). Diese sind in der Standardlogik von Workist bereits unterstützt und Sie müssen nur noch deren Optionen einstellen. Wählen Sie ein **Standardfeld** aus. Es erscheint sofort in der Feldliste links — markiert und ausgewählt — und die rechte Seite zeigt seine (vorbelegten) Konfigurationsoptionen. ![Neu hinzugefügtes Feld in der Liste links, Optionen mit Standardwerten rechts](/img/channel-config/kopffelder/09-neues-feld-formular.png) Bei einem **Standardfeld** sind die wichtigen Optionen vorbelegt — Sie können in den meisten Fällen direkt auf **Speichern** klicken. Möchten Sie das Feld als optional kennzeichnen, schalten Sie zuvor **„Erforderlich"** aus. :::note Solange Sie nicht auf **Speichern** klicken, ist die Änderung nicht übernommen. Verlassen Sie die Seite vor dem Speichern, verwirft die Workbench den neuen Eintrag. ::: ## Schritt 4 — Ein Feld entfernen Möchten Sie ein Feld **nicht mehr** extrahieren, fahren Sie in der linken Liste mit der Maus über den entsprechenden Eintrag — am rechten Rand erscheint dann ein **„×"-Symbol**. ![„×"-Symbol auf dem Eintrag „Bestellnummer" hervorgehoben](/img/channel-config/kopffelder/10-entfernen-affordanz.png) Klicken Sie das **„×"** an, um das Feld zu entfernen. Bei Feldern mit Unterfeldern (z. B. *Lieferadresse*) werden alle Unterfelder mitentfernt. :::warning Spätere Auswirkungen Wird ein Feld entfernt, extrahiert Workist es ab der nächsten Verarbeitung **nicht mehr**; in der Ausgabedatei bleibt es leer oder fehlt. Wenn Ihr Zielsystem das Feld weiterhin erwartet, schlagen die nachgelagerten Imports fehl. Entfernen Sie Felder daher nur in Abstimmung mit Ihren ERP-/Zielsystem-Verantwortlichen. ::: Auch das Entfernen wird erst durch **Speichern** wirksam. ## Schritt 5 — Speichern Klicken Sie unten rechts auf **Speichern**, um alle Änderungen zu übernehmen. ![Speichern-Schaltfläche unten rechts hervorgehoben](/img/channel-config/kopffelder/11-speichern-button.png) - Alle Änderungen an **allen** Feldern (Hinzufügen, Entfernen, Bearbeiten, Sortierung) werden in einem Speichervorgang übernommen. - Findet Workist beim Speichern einen Fehler (z. B. einen doppelten Datenbezeichnungsnamen, ein leeres Pflichtfeld), markiert die Workbench das betroffene Feld rot — der Speichervorgang wird in diesem Fall abgebrochen. - Nach erfolgreichem Speichern wirkt die neue Konfiguration **ab dem nächsten** eingehenden Dokument. Bereits verarbeitete Dokumente werden **nicht** rückwirkend neu ausgewertet. ## Wann welche Einstellung? | Ihre Situation | Empfohlene Einstellung | | --- | --- | | Ihr Zielsystem erwartet das Feld zwingend, sonst bricht der Import. | **Erforderlich = ein**. Lassen Sie *„Feld sollte die Automatisierung nicht blockieren …"* **aus**. | | Das Feld ist nett zu haben, ein leerer oder unsicherer Wert ist aber okay. | **Erforderlich = aus**, *„… nicht blockieren …"* **ein**. | | Es darf nur einen festen Wertebereich geben (z. B. nur 4 erlaubte Auftragsarten). | Bei eigenen Feldern: alle erlaubten Werte unter **„Optionen einschränken"** hinterlegen — siehe [Agentische Kopfzeilenextraktion → Benutzerdefinierte Felder](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). Bei Standardfeldern mit **Zuordnung** (z. B. Incoterm): Schreibweisen dort zuordnen. | | Sie möchten ein eigenes Feld in der Ausgabe sehen, das im Standard nicht enthalten ist. | [„+" → Benutzerdefiniertes Feld](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion) — Workflow in der LLM-Kopf-Anleitung. | | Workist erkennt Ihr eigenes Unternehmen als Kunden. | Tragen Sie Ihren Firmennamen am Feld *Kunde* unter **Words to ignore when extracting this field** ein. | | Ihr Zielsystem lässt nur eine begrenzte Zeichenzahl zu. | **Maximale Feldlänge** setzen; mit **Automatisierung blockieren …** entscheiden, ob gekürzt wird. | ## Häufige Fragen **Warum kann ich den Datenbezeichnungsnamen nicht mehr bearbeiten?** Den Datenbezeichnungsnamen gibt es nur bei benutzerdefinierten Feldern. Nach dem ersten Speichern ist er fix, weil er als Schlüssel in der Ausgabedatei verwendet wird. Soll er sich wirklich ändern, legen Sie ein neues Feld mit dem gewünschten Namen an und entfernen das alte — und stimmen Sie das **vorab** mit der Stelle ab, die das Zielsystem betreut. **Was passiert, wenn ich „Optionen einschränken" leer lasse?** Workist akzeptiert dann beliebige Werte des konfigurierten Datentyps. Die Liste ist also rein optional. **Kann ich für ein einzelnes Feld einen eigenen Konfidenzschwellenwert setzen?** Nein. Der Schwellenwert gilt für alle Kopffelder und wird unter *Dokumentenverarbeitung → Dokument → Automatisierung* eingestellt. Pro Feld können Sie die Konfidenzprüfung nur mit **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** abschalten. **Wie wirkt sich die Reihenfolge der Feldliste links aus?** Die Reihenfolge bestimmt die **Anzeigereihenfolge in der Assistenz**. Wie die Felder in der Ausgabedatei angeordnet sind, legt das Ausgabeformat fest. **Was ist der Unterschied zwischen „Erforderlich" und dem Konfidenzschwellenwert?** **„Erforderlich"** wirkt auf den **Wert** (fehlt der Wert? → Assistenz). Der **Konfidenzschwellenwert** wirkt auf die **Sicherheit** der Extraktion (Wert ist da, aber Workist ist sich nicht sicher? → Assistenz). Beides gilt zusammen. Mit **Feld sollte die Automatisierung nicht blockieren …** schalten Sie nur die Konfidenzprüfung ab; ein leeres Pflichtfeld schickt das Dokument weiterhin in die Assistenz. **Wo sehe ich, welche Kopffelder die Standardlogik bereits unterstützt?** Im Dropdown des **„+"-Symbols**. Alles oberhalb der Trennlinie ist *Benutzerdefiniertes Feld*; alles darunter ist ein vorbereitetes Standardfeld. ## Hilfe und Support Wenn ein Feld nach einer Änderung nicht wie erwartet extrahiert oder ausgegeben wird, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den **Kanalnamen** und den Reiter (*Kopffelder*), - den **Feldnamen** in der Workbench sowie den **Datenbezeichnungsnamen** in der Ausgabedatei, - ein konkretes **Beispiel-Dokument**, das das Problem zeigt, - bei Pflichtfeld-Themen: ob das Feld auf **Erforderlich** steht und ob der Wert in der Quelle eindeutig zu erkennen ist, - bei agentenbasierten Themen: ob das Feld zusätzlich in **Agentische Kopfzeilenextraktion** referenziert ist. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/line-item-fields.md # Kanal-Konfiguration — Positionzeilenfelder Diese Anleitung beschreibt, wie Sie unter **Kanal-Konfiguration → Dokumentenverarbeitung → Positionzeilenfelder** festlegen, welche Felder Workist **pro Position** (z. B. pro Bestellzeile) aus Ihren Dokumenten extrahiert und wie diese Felder geprüft, abgeglichen und an Ihr Zielsystem übergeben werden. Während die **Kopffelder** dokumentweit gelten (Bestellnummer, Bestelldatum, Lieferadresse, …), wird die **Positionzeilenfeld**-Konfiguration auf **jede einzelne Zeile** Ihrer Bestellung, Rechnung, Auftragsbestätigung oder Preisanfrage angewendet. Das wichtigste Feld hier ist üblicherweise die **Artikelnummer** — sie ist der Schlüssel, über den Workist Ihre Stammdaten (Artikel-Lookup) mit den Daten aus dem Dokument verknüpft. :::note Beziehung zu den Kopffeldern Aufbau und Bedienung sind identisch — die linke Spalte listet die konfigurierten Felder, die rechte Spalte zeigt die Optionen des ausgewählten Feldes. Es kommen jedoch positions-spezifische Optionen hinzu (Artikelabgleich, Mengen, Einheiten, Lieferdatum je Position). ::: ## Voraussetzungen - Ein Workbench-Konto mit Zugriff auf die Konfiguration des jeweiligen Kanals. - **Für den Artikelabgleich:** Im Bereich **Stammdaten** desselben Kanals ist eine **Artikel-Lookup-ID** hinterlegt und die Artikelliste importiert. **Lookups durchführen** ist an der Artikelnummer standardmäßig aktiv. Gibt es keine Artikel-Stammdaten, entscheidet **Ungültige IDs zulassen**, ob die Artikelnummer aus dem Dokument erhalten bleibt (siehe Schritt 2.3). Wie Sie Stammdaten konfigurieren, ist in der [Dokumentenverarbeitung-Übersicht](/docs/channel-configuration/document-processing.md) und in der [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md) beschrieben. - Bei Änderungen, die Auswirkungen auf das Datenformat in der Ausgabedatei haben (Datenbezeichnungsname, Datentyp), stimmen Sie sich vor dem Speichern mit Ihrer Ansprechperson bei Workist ab — diese Felder sind Teil eines Mappings zum Zielsystem. ## Schritt 1 — Aufbau der Seite Öffnen Sie in der Kanal-Navigation den Bereich **Dokumentenverarbeitung** und wählen Sie den Reiter **Positionzeilenfelder**. Die Seite ist in zwei Spalten aufgeteilt: - **Links — „Konfigurierte Felder":** Die Felder, die für diesen Kanal aktuell pro Position extrahiert werden. Jeder Eintrag zeigt unter dem Namen einen kurzen Hinweis (**Erforderlich** oder **Optional**). Über das **+**-Symbol oben rechts in dieser Spalte können Sie weitere Felder hinzufügen. - **Rechts — „Konfigurationsoptionen für …":** Die Optionen des Feldes, das in der linken Spalte gerade ausgewählt ist. Welche Optionen erscheinen, hängt vom **Feld** ab (siehe Schritt 3). ![Übersicht der Positionzeilenfelder-Seite mit linker Feldliste und rechter Optionsspalte](/img/channel-config/positionzeilenfelder/01-uebersicht.png) Felder lassen sich per Drag-and-Drop sortieren. Die Reihenfolge bestimmt, in welcher Reihenfolge die Felder in der Assistenz erscheinen. :::note Pflicht versus optional Der Hinweis unter jedem Feldnamen (*Erforderlich* / *Optional*) ergibt sich aus dem Schalter **Erforderlich** in den Optionen rechts. Ein erforderliches Feld blockiert die Automatisierung, wenn es leer ist oder seine Konfidenz unter dem Schwellenwert liegt. Ein optionales Feld blockiert nur, wenn es einen Wert mit zu niedriger Konfidenz enthält. ::: ## Schritt 2 — Ein Feld auswählen und Optionen anpassen Klicken Sie in der linken Spalte auf das Feld, das Sie bearbeiten möchten, z. B. **Artikelnummer**. Die rechte Spalte zeigt nun **„Konfigurationsoptionen für Artikelnummer"** mit allen Optionen, die für dieses Feld verfügbar sind. ![Optionspanel für das Feld „Artikelnummer"](/img/channel-config/positionzeilenfelder/02-artikelnummer-optionen.png) Im Folgenden sind die Optionen nach Themenblöcken sortiert. Bedenken Sie: **Nicht alle Optionen erscheinen bei jedem Feld** (siehe Schritt 3). ### 2.1 — Allgemeine Eigenschaften Diese Optionen finden Sie bei nahezu allen Feldern. | Option | Bedeutung | | --- | --- | | **Erforderlich** | Wenn aktiv, **muss** der Wert in jeder Position vorhanden sein und den Konfidenzschwellenwert erreichen. Sonst geht das Dokument in die Assistenz. | | **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** | Wenn aktiv, prüft Workist die Konfidenz dieses Felds nicht. Ein unsicher erkannter Wert schickt das Dokument dann nicht in die Assistenz. Ein erforderliches Feld, das leer ist, schickt es trotzdem in die Assistenz. | | Anzeigename (in der Workbench derzeit **Display name**) | Ändert die Beschriftung des Felds in der Assistenz. Leer: Standardbezeichnung. | ![Mit Markierung: der Schalter „Erforderlich" und der Schalter „Feld sollte die Automatisierung nicht blockieren …"](/img/channel-config/positionzeilenfelder/03-erforderlich-und-schwellenwert.png) :::note Kein eigener Schwellenwert pro Feld Der Schwellenwert für Positionszeilen gilt für alle Positionsfelder gemeinsam und wird im Reiter **Dokument** unter **Automatisierung** gesetzt (*Konfidenzschwellenwert der Positionzeilen (%)*). Der Schalter oben schaltet die Konfidenzprüfung für genau dieses Feld ab. Die vollständige Regel steht unter [Wann wird automatisiert?](/docs/channel-configuration/document-processing/validation-checks.md#wann-wird-automatisiert). ::: ### 2.2 — Feldlänge Diese Optionen gibt es bei allen Textfeldern, auch bei Kopffeldern. | Option | Bedeutung | | --- | --- | | **Maximale Feldlänge** | Maximale Anzahl Zeichen, die das Feld enthalten darf. Sinnvoll für Felder mit fester Länge im Zielsystem (z. B. Artikelnummern in SAP, die nur 18 Zeichen lang sein dürfen). | | **Automatisierung blockieren, wenn die maximale Feldlänge überschritten wird** | **An** (Standard): Ein zu langer Wert bleibt unverändert; die Bearbeiter:in muss ihn vor dem Abschließen kürzen. **Aus:** Workist kürzt den Wert bei der Verarbeitung auf die maximale Länge und zeigt einen Hinweis. Das Dokument geht trotzdem in die Assistenz, kann dort aber ohne Änderung abgeschlossen werden. | ![Mit Markierung: „Maximale Feldlänge" und „Automatisierung blockieren, wenn die maximale Feldlänge überschritten wird"](/img/channel-config/positionzeilenfelder/06-maximale-feldlaenge.png) ### 2.3 — Artikelspezifische Optionen Diese Optionen erscheinen an der **Artikelnummer**. Sie steuern den **Stammdatenabgleich** mit Ihrer Artikelliste. So arbeitet der Abgleich: 1. Mit **Lookups durchführen** (Standard: an) sucht Workist die Artikelnummer bzw. Beschreibung in den Artikel-Stammdaten und in gelernten Zuordnungen aus früheren Assistenzen. 2. Findet Workist einen Artikel, übernimmt es dessen Nummern und Daten. Mit **Imperfekte Artikelübereinstimmungen zurücksetzen** übernimmt es nur exakte Treffer. 3. Findet Workist nichts, bleibt die Artikelnummer leer, und in der Assistenz muss ein Artikel aus den Stammdaten gewählt werden. Ist **Ungültige IDs zulassen** aktiv, bleibt stattdessen die Nummer aus dem Dokument stehen, und Bearbeiter:innen dürfen auch Nummern eintragen, die nicht in den Stammdaten stehen. Das gilt auch, wenn der Kanal gar keine Artikel-Stammdaten hat: Ohne **Ungültige IDs zulassen** leert Workist dann jede Artikelnummer, die es nicht aus gelernten Zuordnungen kennt. ![Mit Markierung: der Block der artikelspezifischen Optionen am Feld „Artikelnummer"](/img/channel-config/positionzeilenfelder/05-artikel-spezifische-optionen.png) **Externe Artikelnummer beibehalten** betrifft die **kundenspezifische Artikelnummer** (die Nummer Ihres Kunden für Ihren Artikel). Sie steht nur dann zusätzlich zu Ihrer Artikelnummer in der Ausgabe, wenn dieses Feld als Positionzeilenfeld konfiguriert ist. Alle Artikel-Optionen mit ihrer Wirkung finden Sie in der Tabelle unter [2.6 — Feldspezifische Optionen](#26--feldspezifische-optionen). ### 2.4 — Datenbenennung, Datentyp und Anweisungen Bei **benutzerdefinierten Feldern** erscheinen zusätzlich die Optionen **Datenbezeichnungsname**, **Datentyp**, **Geben Sie Optionen an, …** (*choices*), **Feldbezeichnungsname** und **Anweisungen für Datenbezeichnungen**. Sie definieren, wie das Feld in der Ausgabedatei heißt und wie der Wert geprüft wird. Da diese Optionen in der Praxis fast immer im Zusammenhang mit **agentischer Extraktion** verwendet werden, ist die ausführliche Schritt-für-Schritt-Anleitung — inklusive Datentyp-Auswahl, `choices`-Liste, sinnvollen KI-Anweisungen und Einbindung als Ausgabefeld — dort dokumentiert: **[Benutzerdefinierte Felder als Ziel der agentischen Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion)**. Der dort beschriebene Workflow gilt **identisch** für Positionzeilenfelder — Sie arbeiten lediglich auf dieser Seite statt auf *Kopffelder*, und das angelegte Feld erscheint anschließend **pro Position** statt einmal pro Dokument. :::warning „Datenbezeichnungsname" ist nach Speichern unveränderlich Der Name ist Teil des Mappings zum Zielsystem (ERP/SAP/…) — wird er nach dem Go-Live geändert, bricht die nachgelagerte Verarbeitung. ::: ### 2.5 — Zuordnung (Mapping) Einige Felder bieten zusätzlich eine **Zuordnung** an — eine Tabelle, die Werte aus dem Dokument auf Ihre Werte abbildet. Beispiel **Einheit**: Die im Dokument stehenden Texte (`Stk`, `STK`, `St`, `Stück`, …) werden auf eine einheitliche Einheit (`STK`) abgebildet. Dasselbe gibt es für die **Preiseinheit**. ![Zuordnungstabelle am Feld „Einheit"](/img/channel-config/positionzeilenfelder/08-einheit-zuordnung.png) Die **Reihenfolge** der Einträge ist wichtig: Zuerst aufgelistete Einheiten werden bevorzugt, wenn mehrere gültige Einheiten gefunden werden. ### 2.6 — Feldspezifische Optionen Die folgende Tabelle listet alle feldspezifischen Optionen, die an Positionzeilenfeldern angeboten werden. Welche Sie sehen, hängt vom Dokumenttyp des Kanals ab. Optionen ohne deutsche Bezeichnung erscheinen in der Workbench mit dem englischen Namen. | Feld | Option | Wirkung | Dokumenttypen | | --- | --- | --- | --- | | Artikelnummer | **Debitor Artikel bei unterschiedlichen perfekten Übereinstimmungen** | Gibt es mehrere exakte Treffer, gewinnt der kundenspezifische Artikel. | Bestellung, Preisanfrage | | Artikelnummer | **Externe Artikelnummer beibehalten** | Betrifft die kundenspezifische Artikelnummer. An: Die Nummer aus dem Dokument bleibt, auch wenn die Stammdaten eine andere liefern. Aus (Standard): Bei exaktem Treffer kommt sie aus den Stammdaten. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Artikelnummer | **Imperfekte Artikelübereinstimmungen zurücksetzen** | An: Nur exakte Treffer werden übernommen; unscharfe Treffer werden verworfen. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Artikelnummer | **Keep ambiguous external article numbers** | An: Kundenspezifische Artikelnummern bleiben, auch wenn dieselbe Nummer im Dokument zu verschiedenen Artikeln führt. Aus (Standard): Sie werden in allen betroffenen Positionen geleert. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Artikelnummer | **Lookups durchführen** | Gleicht die Artikelnummer mit den Artikel-Stammdaten ab. Standard: an. | alle | | Artikelnummer | **Search article also in referenced offer** | Artikelnummern werden auch mit den Artikeln des referenzierten Angebots abgeglichen, selbst wenn diese nicht in den Artikel-Stammdaten stehen. | Bestellung | | Artikelnummer | **Ungültige IDs zulassen** | Aus (Standard): Findet Workist die Nummer weder in den Stammdaten noch in gelernten Zuordnungen, bleibt das Feld leer, und in der Assistenz muss ein Artikel aus den Stammdaten gewählt werden. An: Die Nummer aus dem Dokument bleibt stehen. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Artikelnummer | **Use learned article mappings from other clients** | Gibt es für den Kunden keine gelernte Artikelzuordnung, schlägt Workist Zuordnungen anderer Kunden mit geringerer Konfidenz vor. Nach Bestätigung in der Assistenz gilt sie auch für diesen Kunden. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Einheit | **Zuordnung** | Zuordnung von Einheiten-Schreibweisen im Dokument zu Ihren Einheiten. Zuerst gelistete Einheiten werden bevorzugt. | alle | | Einzelpreis | **Allow overriding unit price with catalog price (via button)** | Zusammen mit der Prüfung *Unit price / gross price mismatch check*: In der Assistenz übernimmt die Schaltfläche **Use catalog price** den Preis aus den Stammdaten. | Bestellung | | Kommissionsnr. | **Kommssionsnummer aus der Kopfzeile als Fallback verwenden** | Hat eine Position keine Kommissionsnummer, übernimmt Workist die aus den Kopfdaten. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Lieferdatum | **Leeres Lieferdatum automatisch füllen** | Findet Workist kein Lieferdatum, setzt es das Verarbeitungsdatum plus diese Anzahl Werktage ein (Konfidenz 100 %). Leer: kein Auffüllen. | Bestellung, Auftragsbestätigung | | Lieferdatum | **Lieferdatumsbereich verwenden** | An: Ein Lieferzeitraum im Dokument (z. B. eine Kalenderwoche) wird als Start- und Enddatum übernommen. Aus (Standard): Workist setzt ein einzelnes Datum innerhalb des Zeitraums. | Bestellung, Auftragsbestätigung | | Lieferdatum | **Lieferzeitraum mit Wochentag ersetzen** | Bei ausgeschaltetem Lieferdatumsbereich: der Wochentag im Zeitraum, der als Lieferdatum gesetzt wird (Standard: Freitag). | Bestellung | | Lieferdatum | **Verarbeitungsregeln** | Regeln aus Bedingung und Ausdruck, die das Lieferdatum anpassen, z. B. je Kunde oder unter Berücksichtigung des Feiertagskalenders. Die erste zutreffende Regel gilt. Richten Sie Regeln gemeinsam mit Workist ein. | Bestellung, Auftragsbestätigung, Preisanfrage | | Menge | **Dezimalmengen erlauben** | Aus: Mengen mit Nachkommastellen blockieren den Abschluss (Prüfung *Dezimalmenge*). Standard: an. | alle | | Menge | **Maximalwert** | Obergrenze für die Prüfung **Maximale Menge** (Standard 999). Wirkt nur bei Bestellungen und Preisanfragen, wo es diese Prüfung gibt. | Bestellung, Auftragsbestätigung, Lieferschein, Preisanfrage | | Menge | **Nullmengen erlauben** | Aus: Menge 0 blockiert den Abschluss (Prüfung *Nullmenge*). Standard: an. | Bestellung, Rechnung, Auftragsbestätigung, Lieferschein | | Preiseinheit | **Zuordnung** | Zuordnung von Preiseinheiten im Dokument (z. B. „pro 100 Stück“) zu Ihren Werten. | Bestellung, Rechnung, Auftragsbestätigung, Lieferschein | ## Schritt 3 — Welche Optionen erscheinen wann? Welche Optionen auf der rechten Seite angezeigt werden, hängt vom gerade ausgewählten Feld ab. Klicken Sie zum Vergleich in der linken Spalte auf ein Mengenfeld — Sie sehen sofort, dass die artikelspezifischen Optionen fehlen. ![Optionspanel für das Feld „Menge": ohne Lookup- und Artikel-Optionen](/img/channel-config/positionzeilenfelder/07-menge-keine-artikel-optionen.png) Grobe Orientierung: | Feld | Typische Optionen | | --- | --- | | **Artikelnummer** | Allgemeine Eigenschaften, Feldlänge, **artikelspezifische Optionen** (Lookups, ungültige IDs, externe Nummer, imperfekte Treffer, …). | | **Menge** | Allgemeine Eigenschaften, **Dezimalmengen erlauben**, **Nullmengen erlauben**, **Maximalwert**. | | **Einheit**, **Preiseinheit** | Allgemeine Eigenschaften, Feldlänge, **Zuordnung**. | | **Lieferdatum** (am Positionsfeld) | Allgemeine Eigenschaften, **Leeres Lieferdatum automatisch füllen**, **Lieferdatumsbereich verwenden**, **Lieferzeitraum mit Wochentag ersetzen**, **Verarbeitungsregeln**. | | **Benutzerdefiniertes Feld** | Erforderlich, **Datenbezeichnungsname**, **Datentyp**, **Feldbezeichnungsname**, **Anweisungen für Datenbezeichnungen**. Vollständige Anleitung: [Agentische Kopfzeilenextraktion → Benutzerdefinierte Felder](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). | Wenn eine im Abschnitt 2 beschriebene Option an einem konkreten Feld **nicht** erscheint, bedeutet das: Sie ist für dieses Feld nicht relevant — Sie müssen nichts tun. ## Schritt 4 — Ein Standardfeld hinzufügen Klicken Sie auf das **+**-Symbol in der Kopfzeile der linken Spalte („Konfigurierte Felder"). Es öffnet sich eine Auswahl mit allen Feldern, die für diesen Dokumenttyp angeboten werden, aber noch nicht konfiguriert sind. ![Geöffnetes Menü zum Hinzufügen eines Feldes, mit „Benutzerdefiniertes Feld" oben](/img/channel-config/positionzeilenfelder/09-feld-hinzufuegen-menue.png) Das Menü unterteilt sich in zwei Bereiche: - Ganz oben **„Benutzerdefiniertes Feld"** (durch eine Trennlinie abgesetzt) — damit legen Sie ein eigenes Feld an, das nicht im Standard-Katalog enthalten ist. Den vollständigen Workflow finden Sie unter [Benutzerdefinierte Felder als Ziel der agentischen Extraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion). - Darunter die **Standardfelder** des Dokumenttyps, die noch nicht aktiviert sind. Wählen Sie ein **Standardfeld** aus. Das Feld erscheint sofort in der linken Spalte und ist rechts mit seinen vorbelegten Optionen geöffnet. :::note Reihenfolge Neu hinzugefügte Felder werden ans Ende der Liste eingefügt. Bei Bedarf können Sie sie per Drag-and-Drop am Grip-Symbol links neben dem Namen an die gewünschte Stelle verschieben. ::: Um ein Feld wieder zu entfernen, klicken Sie auf das **×** rechts neben dem Feldnamen in der linken Spalte. ## Schritt 5 — Speichern Klicken Sie unten rechts auf **Speichern**, um Ihre Änderungen zu übernehmen. ![„Speichern"-Button unten rechts](/img/channel-config/positionzeilenfelder/10-speichern.png) Erst nach dem Speichern werden die neuen Einstellungen für die nachfolgende Dokumentverarbeitung wirksam. Bereits verarbeitete Dokumente werden **nicht** rückwirkend neu extrahiert. :::warning Wenn das Speichern fehlschlägt Häufige Ursachen sind: - leerer **Datenbezeichnungsname** bei einem benutzerdefinierten Feld; - identischer **Datenbezeichnungsname** in zwei Feldern (muss eindeutig sein); - eine ungültige **Zuordnung** oder **Verarbeitungsregel**. Fehlertexte erscheinen direkt unter dem betroffenen Feld in rot. ::: ## Tipps zum Zusammenspiel mit Stammdaten Die Positionzeilenfeld-Konfiguration entfaltet ihr volles Potenzial erst zusammen mit Ihren Stammdaten. Drei häufige Ausgangspunkte: - **Sie haben noch keine Artikelliste hochgeladen.** Schalten Sie an der Artikelnummer **„Ungültige IDs zulassen"** ein. Sonst leert Workist jede Artikelnummer, die es nicht kennt. Laden Sie dann Ihre Artikelliste über den [Master Data Hub](/docs/master-data/master-data-hub.md) hoch und hinterlegen Sie sie unter **Stammdaten** (siehe [Dokumentenverarbeitung-Übersicht](/docs/channel-configuration/document-processing.md)). - **Sie wollen eine bestehende Artikelliste mit anderen Spaltennamen einlesen.** Hier hilft die [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md) — sie ist der Hebel, mit dem Sie Spalten Ihrer Datei auf das Workist-Schema abbilden. - **Sie haben unscharfe Treffer in der Artikelliste.** Aktivieren Sie **„Imperfekte Artikelübereinstimmungen zurücksetzen"**, wenn Sie lieber leere Felder als falsche Treffer akzeptieren wollen — oder verwenden Sie **„Ungültige IDs zulassen"**, um die Nummer aus dem Dokument zu behalten, wenn kein Treffer gefunden wird. ## Häufige Fragen **Warum sehe ich bei „Menge" keine Lookup-Optionen?** Lookup-Optionen sind an Felder gebunden, die Stammdaten referenzieren — typischerweise die Artikelnummer. Bei reinen Zahlenfeldern wie der Menge ergibt ein Lookup keinen Sinn und die Optionen werden ausgeblendet. **Was passiert, wenn ich „Erforderlich" für ein Feld deaktiviere, das im Dokument fehlen kann?** Ein leeres Feld blockiert die Automatisierung dann nicht mehr. Enthält das Feld aber einen Wert mit zu niedriger Konfidenz, geht das Dokument weiterhin in die Assistenz. Setzen Sie zusätzlich **„Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts"**, wenn auch unsicher extrahierte Werte nicht zur Assistenz führen sollen. **Kann ich den „Datenbezeichnungsname" nachträglich ändern?** Nein. Den Datenbezeichnungsnamen gibt es nur bei benutzerdefinierten Feldern, und er ist nach dem ersten Speichern unveränderlich, weil er Teil des Mappings zum Zielsystem ist. Falls sich ein Tippfehler eingeschlichen hat, wenden Sie sich an Ihre Ansprechperson bei Workist. **Was bedeutet das `*` neben einem Feldnamen?** In der rechten Spalte markiert `*` ein **Pflichtfeld**, das Sie vor dem Speichern ausfüllen müssen. **Greift die neue Konfiguration sofort?** Sie greift, sobald das nächste Dokument verarbeitet wird. Bereits abgeschlossene Dokumente werden nicht rückwirkend neu extrahiert. ## Hilfe und Support Wenn Sie unsicher sind, welche Optionen für Ihr Zielsystem die richtigen sind, halten Sie bitte folgende Informationen für Ihre Ansprechperson bei Workist bereit: - den **Kanalnamen** und den Dokumenttyp (z. B. „Bestellungen, Test"), - das **Feld**, um das es geht (z. B. „Artikelnummer"), - die **gewünschte Wirkung** im Zielsystem (z. B. „SAP-Artikelnummer beibehalten, aber zusätzlich unsere interne Nummer ausgeben"), - gegebenenfalls ein **Beispiel-Dokument**, an dem das Verhalten beobachtet werden kann. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/validation-checks.md # Validierungsprüfungen und Assistenzgründe Diese Seite beschreibt, wann Workist ein Dokument ohne Assistenz abschließt, welche Prüfungen ein Dokument in die Assistenz schicken und welche Gründe dafür in Analytics erscheinen. Die auswählbaren Prüfungen schalten Sie im Kanal unter [Dokument → Validierung](/docs/channel-configuration/document-processing/document.md#schritt-6--validierung) ein. ## Wann wird automatisiert? Workist schließt ein Dokument nur dann automatisch ab und übergibt es an Ihr Zielsystem, wenn **alle** folgenden Bedingungen erfüllt sind. Ist eine davon nicht erfüllt, geht das Dokument in die Assistenz. 1. **Automatisierung aktiviert** ist im Block *Automatisierung* der Seite [Dokument](/docs/channel-configuration/document-processing/document.md#schritt-2--automatisierung) eingeschaltet. 2. **Jedes Kopffeld** erreicht den **Konfidenzschwellenwert der Kopfdaten (%)**, **jedes Positionsfeld in jeder Position** den **Konfidenzschwellenwert der Positionzeilen (%)**. Workist prüft jedes Feld einzeln (Konfidenz ≥ Schwellenwert); es gibt keinen Durchschnitt. - **Erforderliche** Felder müssen befüllt sein und den Schwellenwert erreichen. - **Optionale** Felder dürfen leer sein. Enthalten sie einen Wert, muss auch dieser den Schwellenwert erreichen. - Bei Feldern mit **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** prüft Workist die Konfidenz nicht. Ein erforderliches Feld muss trotzdem befüllt sein. 3. Das Dokument hat mindestens eine Position, sofern mindestens ein Positionsfeld erforderlich ist. 4. **Keine Validierungsprüfung ist angeschlagen** – weder eine blockierende noch eine nicht blockierende. 5. Bei aktivem Bestell- oder Angebotsabgleich weicht kein verglichenes Feld von den Stammdaten ab (siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md)). 6. Das Dokument enthält keine Unterpositionen. Unterpositionen entstehen nur durch strukturelle Positions-Operationen der [agentischen Positionsextraktion](/docs/channel-configuration/document-processing/agentic-extraction.md#besonderheiten-der-positionsextraktion). :::note Schwellenwerte ohne gespeicherten Wert Ist für einen Kanal kein Schwellenwert gespeichert, gilt **100 %**. Dann wird nur automatisiert, wenn jedes geprüfte Feld vollständig sicher ist. Einen eigenen Schwellenwert pro Feld gibt es nicht. ::: ### Blockierend und nicht blockierend Jede angeschlagene Prüfung verhindert die Automatisierung – auch eine nicht blockierende. Der Unterschied zeigt sich erst in der Assistenz: - **Nicht blockierend:** Die Prüfung ist ein Hinweis. Bearbeiter:innen können das Dokument abschließen, ohne etwas zu ändern. - **Blockierend:** Das Dokument lässt sich erst abschließen, wenn der betroffene Wert korrigiert ist. ### Was zum Abschließen in der Assistenz nötig ist In der Assistenz spielt die Konfidenz keine Rolle mehr. Ein Dokument lässt sich abschließen, sobald - alle erforderlichen Felder befüllt und gültig sind, - keine blockierende Prüfung mehr anschlägt, - jedes abweichende Feld aus dem Bestell- oder Angebotsabgleich korrigiert oder mit **Abweichung akzeptieren** bestätigt ist. Einige Prüfungen laufen erneut, wenn Bearbeiter:innen ein betroffenes Feld ändern (z. B. Mindestmenge, Artikelstatus, Einzelpreis, Belegnummer). Der Hinweis verschwindet dann, sobald der Wert passt. ## Prüfungen Die Prüfungen sind in drei Gruppen eingeteilt: - **Auswählbare Prüfungen** schalten Sie unter *Dokument → Validierung → Validierungsprüfungen* ein oder aus. Welche angeboten werden, hängt vom Dokumenttyp des Kanals ab. - **Immer aktive Prüfungen** laufen für jedes Dokument des jeweiligen Typs. Ihr Verhalten steuern Sie über Feldoptionen oder Schlüsselwörter. - **Automatische Prüfungen** entstehen durch Feldoptionen, Stammdaten oder andere Funktionen des Kanals. Die Spalte *Hinweis an* zeigt, wo die Workbench den Hinweis in der Assistenz anzeigt. Prüfungen ohne deutsche Bezeichnung erscheinen in der Workbench mit dem englischen Namen. ### Auswählbare Prüfungen | Prüfung | Dokumenttypen | Schlägt an, wenn … | Hinweis an | Blockierend | | --- | --- | --- | --- | --- | | **Gesamtbetrag** | Bestellung, Rechnung, Auftragsbestätigung, Lieferschein | Der Nettogesamtbetrag weicht um mehr als 0,10 von der Summe der Positionsgesamtpreise ab. Fehlen der Gesamtbetrag oder alle Positionsgesamtpreise, wird nicht geprüft. | Gesamtbetrag (netto) | Nein | | **Position Summe** | Bestellung, Auftragsbestätigung, Lieferschein | Menge × Einzelpreis weicht vom Positionsgesamtpreis ab (Toleranz 1 Cent oder 0,25 %). Rabatte werden nicht berücksichtigt. Die Konfidenz der Menge sinkt auf 0. | Menge der Position | Nein | | **Positionsnummer** | Bestellung, Auftragsbestätigung, Lieferschein | Die Spanne der Positionsnummern passt nicht zur Anzahl erkannter Positionen (z. B. Positionen 1–5, aber nur 4 erkannt). Schrittweiten wie 10, 20, 30 werden erkannt. | Dokument | Nein | | **Vergessene Posten** | alle | Auf einer Seite stehen mehr als zwei positionstypische Angaben (Artikelnummer, Menge, Preis …) außerhalb der erkannten Positionen. Bei neuen Kanälen aktiv. | Dokument | Nein | | **Unvollständige Posten** | alle | Artikelnummer, Menge oder Positionsnummer ist nur bei einem Teil der Positionen vorhanden. Bei nur einer Position: solche Angaben stehen auf der Seite außerhalb dieser Position. | Dokument | Nein | | **Maximale Menge** | Bestellung, Preisanfrage | Eine Menge liegt über dem **Maximalwert** des Positionsfelds *Menge* (Standard 999). Die Konfidenz der Menge sinkt auf 30 %. | Menge | Nein | | **Min quantity** | Bestellung, Preisanfrage | Eine Menge unterschreitet die Mindestmenge oder ist kein Vielfaches der Verpackungseinheit, die in den Zusatzdaten des Artikels steht. Siehe [Mindestmengen-Regeln](#mindestmengen-regeln). | Menge bzw. umgerechnete Menge | Je Regel (Standard: ja) | | **Massenbestellzusammenfassung entfernen** | Bestellung | Workist entfernt die letzten Positionen, wenn sie eine Zusammenfassung sind (für jeden Artikel ist die letzte Menge die Summe der vorherigen). Findet Workist keine solche Zusammenfassung, schlägt die Prüfung an – auch bei gewöhnlichen Bestellungen. | Dokument | Nein | | **Repeated positions (e.g. appended summary or order confirmation)** | Bestellung, Preisanfrage | Die letzten Positionen wiederholen frühere Positionen (gleiche Artikelnummer, Artikelnummer 2 und Menge), z. B. durch eine angehängte Zusammenfassung oder Auftragsbestätigung. | Artikelnummer der wiederholten Positionen | Nein | | **Kundeninterne Notiz** | alle | Für den erkannten Kunden bzw. Lieferanten steht in den Stammdaten eine interne Notiz (`internal_note`). Der Dokumenttext wird nicht ausgewertet. | Dokument | Nein | | **ERP-Sperre** | Bestellung | Die Bestellung ist bei der Verarbeitung bereits als „für die Weiterverarbeitung gesperrt“ markiert. Das geschieht nur durch eine kundenspezifische Anpassung. | Dokument | Nein | | **Mehrere Vertriebsorganisationen** | Bestellung | Für den Artikel einer Position gibt es in den Stammdaten mehr als eine Vertriebsorganisation. Eine Bearbeiter:in wählt die passende aus. | Vertriebsorganisation der Position | Nein | | **Tausendertrennzeichen bei Mengen** | alle | Menge und Preise verwenden unterschiedliche Trennzeichen, und Menge × 1.000 bzw. Menge ÷ 1.000 passt zu Gesamtpreis ÷ Einzelpreis. Eine Schreibweise wie `1.000` allein löst die Prüfung nicht aus. Bei neuen Kanälen aktiv. | Menge | Nein | | **Abgleich von Artikelbeschreibungen (experimentell)** | Bestellung, Preisanfrage | Ein Sprachmodell bewertet, ob die Artikelbeschreibung aus dem Dokument und die aus den Stammdaten denselben Artikel meinen. Unter 50 % Wahrscheinlichkeit schlägt die Prüfung an. | Artikelbeschreibung | Nein | | **Article status** | Bestellung, Preisanfrage | Der zugeordnete Artikel hat in den Stammdaten (`article_status`) einen Status, der in einer Artikelstatus-Regel steht. Siehe [Artikelstatus-Regeln](#artikelstatus-regeln). | Artikelnummer | Je Regel (Standard: ja) | | **Angebotsabgleich** | Bestellung | Die Bestellung nennt eine Angebotsnummer, und Werte weichen vom Angebot ab, die Angebotsnummer ist unbekannt, oder die Bestellung hat weniger Positionen als das Angebot. Siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md). | Abweichende Felder | Bis korrigiert oder akzeptiert | | **Offene Angebotsprüfung (nur wenn Angebotsabgleich aktiviert ist)** | Bestellung | Die Bestellung enthält keine Angebotsnummer, aber für den Kunden gibt es Angebote in den [Angebots-Stammdaten](/docs/master-data/quotes.md). | Angebotsnummer | Nein | | **Unique document number** | alle | Im selben Kanal gibt es aus den letzten 30 Tagen ein Dokument mit derselben Belegnummer und derselben Kunden- bzw. Lieferantennummer. Verworfene, abgelehnte und gelöschte Dokumente zählen nicht. Fehlt eine der beiden Nummern, wird nicht geprüft. | Belegnummer | Nein | | **Unit price / gross price mismatch check** | Bestellung | Der Einzelpreis einer Position ist nicht genau der Preis des Artikels aus den Stammdaten (`gross_price`), oder der Artikel hat dort keinen Preis. | Einzelpreis | Ja | | **Bestellabgleich** | Rechnung, Auftragsbestätigung | Werte weichen von der Bestellung in den Bestelldaten ab, oder die Bestellnummer ist dort unbekannt. Siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md). | Abweichende Felder | Bis korrigiert oder akzeptiert | | **Order matching: Partial confirmations** | Auftragsbestätigung | Keine eigene Prüfung: erlaubt Auftragsbestätigungen mit weniger Positionen als die Bestellung. Ohne diese Option schlägt der Bestellabgleich dann an. | – | – | :::warning Massenbestellzusammenfassung entfernen Diese Prüfung schlägt bei jeder Bestellung an, die **keine** Zusammenfassung am Ende enthält. Schalten Sie sie nur für Kanäle ein, deren Bestellungen immer eine solche Zusammenfassung haben. ::: :::tip Einzelpreis aus dem Katalog übernehmen Ist am Positionsfeld *Einzelpreis* die Option **Allow overriding unit price with catalog price (via button)** aktiv, übernehmen Bearbeiter:innen bei der Prüfung *Unit price / gross price mismatch check* den Preis aus den Stammdaten mit der Schaltfläche **Use catalog price**. ::: ### Immer aktive Prüfungen | Prüfung | Dokumenttypen | Schlägt an, wenn … | Hinweis an | Blockierend | | --- | --- | --- | --- | --- | | **Schlüsselwörter zur Unterstützung** | alle | Ein Begriff aus **Schlüsselwörter zur Unterstützung** steht im Dokument oder im E-Mail-Text. | Dokument | Nein | | Feldlänge | alle | Ein Wert ist länger als die **Maximale Feldlänge** des Felds. Ist **Automatisierung blockieren, wenn die maximale Feldlänge überschritten wird** aus, kürzt Workist den Wert; der Hinweis bleibt. | Betroffenes Feld | Je Feld | | **Bestelldatum** | Bestellung | Ein Lieferdatum (Kopf oder Position) liegt vor dem Bestelldatum. Nur wenn das Bestelldatum und ein Lieferdatumsfeld konfiguriert sind; entfällt mit der Option für vergangene Lieferdaten am Kopffeld Lieferdatum. | Lieferdatum | Nein | | Kunde aus Angebot | Bestellung | Nur mit Angebotsabgleich: Das Angebot gehört zu einem anderen Kunden als dem erkannten. Workist hat den Kunden aus dem Angebot übernommen; eine Bearbeiter:in bestätigt, welcher stimmt. | Kunde | Nein | Schlüsselwörter vergleicht Workist wortweise, ohne Groß-/Kleinschreibung und ohne Satzzeichen. Begriffe aus mehreren Wörtern müssen in dieser Reihenfolge direkt hintereinander stehen. ### Automatische Prüfungen | Prüfung | Dokumenttypen | Schlägt an, wenn … | Hinweis an | Blockierend | | --- | --- | --- | --- | --- | | **Assigned user not found** | alle | Die [Benutzerzuweisung](/docs/channel-configuration/document-processing/document.md#schritt-3--benutzerzuweisung) ist aktiv, aber die verantwortliche Person aus den Stammdaten (bzw. die Standard-E-Mail) ist kein aktiver Workbench-Benutzer. | Dokument | Nein | | Dezimalmenge | alle | Eine Menge hat Nachkommastellen, obwohl **Dezimalmengen erlauben** am Positionsfeld *Menge* aus ist. | Menge | Ja | | Nullmenge | alle | Eine Menge ist 0, obwohl **Nullmengen erlauben** am Positionsfeld *Menge* aus ist (Standard: an; bei Preisanfragen nicht einstellbar) – oder die Einheitenumrechnung hat eine positive Menge auf 0 gerundet (immer). | Menge | Ja | | USt-IdNr. | Bestellung, Preisanfrage | Nur wenn das Kopffeld USt-IdNr. konfiguriert ist und der Kunde aus einem EU-Land außer Deutschland kommt: Es gibt keine USt-IdNr. im Dokument oder in den Kundenstammdaten, das Format ist ungültig, oder die Online-Prüfung bestätigt Nummer, Name und Adresse nicht. Die Konfidenz des Felds sinkt auf 0. | USt-IdNr. | Nein | | Nummer in Abgleichsdaten | Bestellung, Rechnung, Auftragsbestätigung | Nur mit Bestell- oder Angebotsabgleich: Die Nummer steht nicht in den Abgleichsdaten. | Bestell- bzw. Angebotsnummer | Nein | | Positionsanzahl Angebot | Bestellung | Nur mit Angebotsabgleich: Die Bestellung hat weniger Positionen als das Angebot. | Dokument | Nein | | Positionsanzahl Bestellung | Rechnung, Auftragsbestätigung | Nur mit Bestellabgleich: Die Anzahl der Positionen weicht von der Bestellung ab (Regeln siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md#anzahl-der-positionen)). | Dokument | Nein | | Mehrdeutige Positionen | Auftragsbestätigung | Nur mit Bestellabgleich: Zwei oder mehr Positionen sind in allen Abgleichsfeldern identisch und lassen sich keiner Bestellposition eindeutig zuordnen. | Dokument | Nein | | Agentische Extraktion fehlgeschlagen | alle | Eine [agentische Konfiguration](/docs/channel-configuration/document-processing/agentic-extraction.md) konnte technisch nicht ausgeführt werden. Die Werte der Standardextraktion bleiben; ihre Konfidenz sinkt auf 0. Der Hinweis allein verhindert die Automatisierung nicht. | Dokument | Nein | | Wissensdatei zu groß | alle | Eine Wissensdatei einer agentischen Konfiguration ist zu groß (über 200.000 Tokens); die Konfiguration läuft nicht. Wirkung wie oben. | Dokument | Nein | ### Mindestmengen-Regeln Ist die Prüfung **Min quantity** eingeschaltet, erscheint im Block *Validierung* der Regel-Editor **Min quantity rules**. Jede Regel vergleicht die Menge jeder Position mit einem Wert aus den Zusatzdaten (`extra_data`) des zugeordneten Artikels in den [Artikel-Stammdaten](/docs/master-data/articles.md). Die Einstellungen der Regeln sind in der Workbench derzeit nur auf Englisch beschriftet. | Einstellung | Bedeutung | | --- | --- | | **Extra data field** | Pflicht. Name des Felds in den Zusatzdaten des Artikels, das den Wert enthält, z. B. `min_quantity`. | | **Check type** | **Minimum**: Die Menge muss mindestens dem Wert entsprechen. **Multiple**: Die Menge muss ein ganzzahliges Vielfaches des Werts sein (z. B. eine Verpackungseinheit); damit ist der Wert zugleich die Mindestmenge. | | **Quantity to check** | **Quantity** (Menge aus dem Dokument) oder **Converted quantity** (Menge nach der Einheitenumrechnung). | | **Number format in master data** | Wie der Wert in den Stammdaten geschrieben ist: **English (1,000.5)** (Standard; `10.500` ist 10,5) oder **German (1.000,5)** (`10.500` ist 10.500). | | **Blocking** | Standard: an. Eine unterschrittene Menge muss vor dem Abschließen korrigiert werden. Aus: nur ein Hinweis. | | **Article list (lookup definition ID)** | Optional. Liest den Wert aus dieser Artikelliste statt aus dem zugeordneten Artikel. Ein kundenspezifischer Eintrag hat Vorrang vor dem allgemeinen. | Workist prüft alle Regeln. Verletzt eine Position mehrere Regeln, zeigt die Workbench die erste in der Reihenfolge des Editors. Artikel ohne Wert im angegebenen Feld, mit dem Wert 0 oder mit einem nicht lesbaren Wert werden nicht geprüft. Der Hinweis erscheint am Feld *Menge* und nennt die Menge, die geforderte Menge und die Artikelnummer. ### Artikelstatus-Regeln Ist die Prüfung **Article status** eingeschaltet, erscheint im Block *Validierung* der Regel-Editor **Article status rules**. Grundlage ist die Spalte `article_status` der [Artikel-Stammdaten](/docs/master-data/articles.md), z. B. „gesperrt“, „ausgelaufen“ oder „Gefahrgut“. Die Einstellungen sind in der Workbench derzeit nur auf Englisch beschriftet. | Einstellung | Bedeutung | | --- | --- | | **Article statuses** | Pflicht. Ein oder mehrere Status, jeweils mit Tab oder Enter bestätigen. Groß-/Kleinschreibung spielt keine Rolle. | | **Blocking** | Standard: an. Der Artikel muss vor dem Abschließen getauscht werden. Aus: nur ein Hinweis. | Workist prüft die Regeln der Reihe nach; es gilt die erste Regel, die den Status des Artikels enthält. So können Sie z. B. „gesperrt“ blockierend und „Auslaufartikel“ nur als Hinweis einstellen. Artikel ohne Status oder mit einem Status, den keine Regel nennt, werden nicht geprüft. Der Hinweis erscheint an der Artikelnummer der Position. ## Assistenzgründe in Analytics Für jedes Dokument, das in die Assistenz geht, speichert Workist die Gründe. Die häufigsten zeigt [Analytics](/docs/administration/analytics.md) unter **Top 5 Gründe für Unterstützung**. Ein Dokument kann mehrere Gründe haben. | Grund in Analytics | Bedeutung | | --- | --- | | „Ungültiges Feld …“ | Ein erforderliches Feld (oder Unterfeld) ist leer, oder eine blockierende Prüfung an diesem Feld ist angeschlagen. | | „Unsicheres Feld …“ | Die Konfidenz des Felds liegt unter dem Schwellenwert – bei einem erforderlichen Feld oder bei einem optionalen Feld mit Wert. | | „Validierungsprüfung … fehlgeschlagen“ | Eine Validierungsprüfung ist angeschlagen, blockierend oder nicht. Der Name der Prüfung wird angezeigt. | | „Keine Positionen“ | Es wurde keine Position erkannt, obwohl mindestens ein Positionsfeld erforderlich ist. | | „… weicht von der Bestellung ab“ | Ein abgeglichenes Feld weicht von den Bestell- bzw. Angebotsdaten ab (siehe [Abgleich](/docs/channel-configuration/document-processing/matching.md)). | | Unterpositionen vorhanden | Das Dokument enthält Unterpositionen. Sie entstehen nur durch strukturelle Positions-Operationen der agentischen Positionsextraktion. Solche Dokumente werden nie automatisch abgeschlossen. | :::tip Mit den Gründen nachsteuern - Viele **unsichere Felder** desselben Typs: Prüfen Sie, ob das Feld wirklich erforderlich ist, ob die Stammdaten den Wert enthalten oder ob **Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts** passt. - Viele **fehlgeschlagene Validierungsprüfungen** desselben Namens: Prüfen Sie, ob die Prüfung für den Kanal nötig ist. Nicht blockierende Prüfungen verhindern die Automatisierung ebenfalls. ::: ## Häufige Fragen **Alle Felder waren sicher, trotzdem ging das Dokument in die Assistenz. Warum?** Meist hat eine nicht blockierende Prüfung angeschlagen, z. B. *Vergessene Posten* oder *Unique document number*. Der Hinweis steht oben im Dokument bzw. am betroffenen Feld. Auch ein befülltes optionales Feld mit niedriger Konfidenz verhindert die Automatisierung. **Kann ich eine Prüfung nur als Hinweis verwenden, ohne die Automatisierung zu stoppen?** Nein. Jede angeschlagene Prüfung schickt das Dokument in die Assistenz. „Nicht blockierend“ bedeutet nur, dass Bearbeiter:innen das Dokument ohne Änderung abschließen können. **Gibt es einen Konfidenzschwellenwert pro Feld?** Nein. Es gibt einen Schwellenwert für alle Kopffelder und einen für alle Positionsfelder. Pro Feld können Sie die Konfidenzprüfung nur ganz abschalten (**Feld sollte die Automatisierung nicht blockieren, wenn unterhalb des Schwellenwerts**). --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/matching.md # Abgleich mit Bestell- und Angebotsdaten Workist kann Dokumente mit Daten aus Ihrem System abgleichen: Bestellungen mit Ihren **Angeboten**, Rechnungen und Auftragsbestätigungen mit Ihren **Bestellungen**. Stimmt alles überein, kann das Dokument automatisch durchlaufen. Weicht etwas ab, geht es in die Assistenz, und die Abweichung ist am Feld markiert. Dieselben Daten nutzt Workist auch, um leere Dokumente mit Positionen vorzubefüllen und um Bestellungen den richtigen Kunden zuzuordnen. | Dokumenttyp | Abgleich mit | Referenz im Dokument | Stammdaten | Validierungsprüfung | | --- | --- | --- | --- | --- | | Bestellung | Angebot | Angebotsnummer | [Angebote](/docs/master-data/quotes.md) | **Angebotsabgleich** | | Rechnung | Bestellung | Bestellnummer | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | **Bestellabgleich** | | Auftragsbestätigung | Bestellung | Bestellnummer | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | **Bestellabgleich** | ## Voraussetzungen - Die Stammdaten (Angebote bzw. abzugleichende Bestellungen) sind importiert und im Kanal unter **Stammdaten** im Block **Stammdatenabgleich** als **Angebotsabgleich-Lookup-ID** bzw. **Bestellabgleich-Lookup-ID** hinterlegt. - Die Validierungsprüfung **Angebotsabgleich** bzw. **Bestellabgleich** ist unter [Dokument → Validierung](/docs/channel-configuration/document-processing/document.md#schritt-6--validierung) eingeschaltet. - Die Felder, die verglichen werden sollen, sind als [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md) bzw. [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md) im Kanal konfiguriert. Nicht konfigurierte Felder vergleicht Workist nicht. Welche Felder verglichen werden und welche Abweichungen erlaubt sind, legt Workist bei der Einrichtung gemeinsam mit Ihnen fest. ## Was verglichen wird Workist sucht den Datensatz mit der Nummer aus dem Dokument (Angebots- bzw. Bestellnummer) und vergleicht die Felder des Dokuments mit den Spalten dieses Datensatzes. Ohne besondere Einrichtung gilt: - Verglichen werden die Felder mit „Ja“ in der Spalte *Standardmäßig verglichen*. - Ein Feld wird nur verglichen, wenn die Stammdaten dafür einen Wert enthalten. Leere Spalten übergeht Workist. - Die Werte müssen genau übereinstimmen. Je nach Einrichtung kann Workist auch weitere Felder vergleichen, Abweichungen innerhalb einer Toleranz akzeptieren (absolut, in Prozent, in Kalender- oder Werktagen oder als Textähnlichkeit) und Werte vor dem Vergleich bereinigen (z. B. Groß-/Kleinschreibung, Leerzeichen, Zahlenformat). **Bestellung ↔ Angebot** | Ebene | Feld im Dokument | Spalte in den Stammdaten | Standardmäßig verglichen | | --- | --- | --- | --- | | Kopf | Angebotsreferenz | `offer_number` | Ja | | Kopf | Kunde | `partition_id` | Ja | | Position | Position | `position_number` | Nein | | Position | Artikelnummer | `article_id1` | Ja | | Position | Artikelnummer 2 | `article_id2` | Nein | | Position | Artikelnummer 3 | `article_id3` | Nein | | Position | Menge | `quantity` | Nein | | Position | Einheit | `unit` | Nein | | Position | Artikelbeschreibung | `article_description` | Nein | **Rechnung ↔ Bestellung** | Ebene | Feld im Dokument | Spalte in den Stammdaten | Standardmäßig verglichen | | --- | --- | --- | --- | | Kopf | Bestellnummer | `order_number` | Ja | | Kopf | Absender / Lieferant | `partition_id` | Ja | | Kopf | Rechnungsdatum | `order_date` | Ja | | Kopf | Empfängeradresse | `delivery_address` | Ja | | Kopf | Kundennummer des Empfängers | `receiver_number` | Ja | | Kopf | IBAN | `iban` | Ja | | Kopf | BIC | `swift` | Ja | | Kopf | Verwendungszweck | `account` | Ja | | Kopf | Skonto | `payment_terms_discount` | Ja | | Kopf | Zahlungsziel (Tage) | `payment_terms_due_days` | Ja | | Kopf | Zahlungsbedingungsart | `payment_terms_type` | Ja | | Kopf | Zahlungsbedingungen | `payment_terms_type` | Ja | | Position | Position | `position_number` | Ja | | Position | Artikelnummer | `article_id1` | Ja | | Position | Kundenspezifische Artikelnummer | `article_id2` | Ja | | Position | Artikelnummer 3 | `article_id3` | Ja | | Position | Einzelpreis | `article_price` | Ja | | Position | Preiseinheit | `price_unit` | Ja | | Position | Menge | `quantity` | Ja | | Position | Gesamtpreis | `total_price` | Ja | | Position | Einheit | `unit` | Ja | **Auftragsbestätigung ↔ Bestellung** | Ebene | Feld im Dokument | Spalte in den Stammdaten | Standardmäßig verglichen | | --- | --- | --- | --- | | Kopf | Bestellnummer | `order_number` | Ja | | Kopf | Zulieferer | `partition_id` | Ja | | Kopf | Lieferdatum | `delivery_date` | Ja | | Kopf | Lieferadresse | `delivery_address` | Ja | | Kopf | Käufer | `receiver_number` | Ja | | Kopf | Gesamtbetrag (netto) | `order_total_price` | Ja | | Position | Position | `position_number` | Ja | | Position | Artikelnummer | `article_id1` | Ja | | Position | Artikelnummer 2 | `article_id2` | Ja | | Position | Artikelnummer 3 | `article_id3` | Ja | | Position | Einzelpreis | `article_price` | Ja | | Position | Preiseinheit | `price_unit` | Ja | | Position | Menge | `quantity` | Ja | | Position | Gesamtpreis | `total_price` | Ja | | Position | Lieferdatum | `delivery_date` | Ja | | Position | Einheit | `unit` | Ja | | Position | Artikelbeschreibung | `article_description` | Nein | Bei Kunde, Lieferant und Käufer vergleicht Workist die Kunden- bzw. Lieferantennummer, bei Adressen die Adressnummer. ### Zuordnung der Positionen Bei Bestellungen und Auftragsbestätigungen ordnet Workist jede Position des Dokuments der am besten passenden Position aus den Stammdaten zu. Dafür nutzt es die verglichenen Felder und die Artikelbeschreibung. Bei Auftragsbestätigungen ordnet zusätzlich ein Sprachmodell Positionen zu, die danach noch übrig sind, etwa weil der Lieferant eigene Bezeichnungen verwendet. Unsichere Vorschläge verwirft Workist; die Position bleibt dann ohne Zuordnung. Sind zwei oder mehr Positionen einer Auftragsbestätigung in allen verglichenen Feldern identisch, kann Workist sie nicht eindeutig zuordnen. Das Dokument geht mit dem Hinweis auf mehrdeutige Positionen in die Assistenz. ### Anzahl der Positionen | Dokumenttyp | Hinweis, wenn … | | --- | --- | | Bestellung | die Bestellung **weniger** Positionen hat als das Angebot. Mehr Positionen sind erlaubt. | | Rechnung | die Anzahl der Positionen von der Bestellung abweicht. | | Auftragsbestätigung | die Auftragsbestätigung **mehr** Positionen hat als die Bestellung – außer die Zahl der Positionen mit eigenem Preis stimmt (Fracht, kostenlose Positionen und Unterpositionen zählen dann nicht mit). **Weniger** Positionen führen zum Hinweis, außer die Option **Order matching: Partial confirmations** ist unter *Validierungsprüfungen* eingeschaltet. | ## Ergebnis des Abgleichs **Übereinstimmung:** Das Feld erhält eine Konfidenz von 100 %. In der Assistenz zeigt die Erklärung am Feld, dass der Wert zu Ihren Bestell- bzw. Angebotsdaten passt, und wann diese zuletzt aktualisiert wurden. **Abweichung:** Das Dokument geht in die Assistenz. Am abweichenden Feld zeigt die Workbench den erwarteten Wert aus den Stammdaten. Bearbeiter:innen - korrigieren den Wert, oder - bestätigen den Wert aus dem Dokument mit **Abweichung akzeptieren**, oder - schalten für eine einzelne Position den Abgleich mit **Abgleich ignorieren** ab (rückgängig mit **Abgleich wiederherstellen**). Erst dann lässt sich das Dokument abschließen. In Analytics erscheint die Abweichung als Assistenzgrund „… weicht von der Bestellung ab“ (siehe [Validierungsprüfungen und Assistenzgründe](/docs/channel-configuration/document-processing/validation-checks.md#assistenzgründe-in-analytics)). **Nummer nicht gefunden:** Steht die Angebots- bzw. Bestellnummer nicht in den Stammdaten, ist das Nummernfeld markiert, und alle verglichenen Felder zeigen „keine Daten gefunden“. Das Dokument geht in die Assistenz. Korrigiert eine Bearbeiter:in die Nummer, läuft der Abgleich erneut. :::note Gültigkeit von Angeboten Die Spalten `valid_from` und `valid_until` der Angebots-Stammdaten wertet Workist beim Abgleich nicht aus. Auch abgelaufene Angebote werden gefunden. Importieren Sie nur gültige Angebote oder filtern Sie abgelaufene beim Import heraus (siehe [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md)). ::: ## Bestellungen: Kunde und Positionsdaten aus dem Angebot Ist der Angebotsabgleich aktiv und gehört das Angebot genau einem Kunden (`partition_id`), übernimmt Workist diesen Kunden in die Bestellung: - Wurde kein Kunde erkannt, setzt Workist den Kunden aus dem Angebot ein. - Wurde ein anderer Kunde erkannt, ersetzt Workist ihn durch den Kunden aus dem Angebot und markiert das Feld *Kunde*. Eine Bearbeiter:in bestätigt, welcher Kunde stimmt. Nach dem Abgleich übernimmt Workist für jede zugeordnete Position die Angebotsnummer und die Positionsnummer aus dem Angebot. So kann Ihr ERP jede Bestellposition der Angebotsposition zuordnen. ## Leere Dokumente vorbefüllen Enthält ein Dokument eine Nummer, aber **keine Positionen**, übernimmt Workist die Positionen aus den Stammdaten (höchstens 100). Das ist z. B. bei Bestellungen der Fall, die nur auf ein Angebot verweisen, oder bei Sammel-Auftragsbestätigungen, die Bestellungen nur per Nummer bestätigen. | Dokument | Voraussetzung | Übernommene Werte | | --- | --- | --- | | Bestellung | Angebotsnummer vorhanden, Angebotsabgleich aktiv | Artikelnummer, Menge, Einheit, Positionsnummer, Angebotsnummer, Artikelbeschreibung | | Auftragsbestätigung | Bestellnummer vorhanden, Bestellabgleich aktiv | Artikelnummern 1–3, Positionsnummer, Bestellnummer, Menge, Einzelpreis, Gesamtpreis, Einheit, Preiseinheit, Lieferdatum, Artikelbeschreibung | - Workist übernimmt nur Positionen, die dem erkannten Kunden bzw. Lieferanten zugeordnet sind oder keinem Partner zugeordnet sind. - Bei Angeboten übernimmt Workist von Set-Artikeln nur den Hauptartikel. Set-Bestandteile erkennt es am Eintrag `higher_level_position` in den Zusatzdaten (`extra_data`) der Angebotsposition. - Anschließend ergänzt Workist die Positionen aus den Artikel-Stammdaten und rechnet Einheiten um. - Vorbefüllte Werte stammen aus Ihren Stammdaten und haben eine Konfidenz von 100 %. - Das Vorbefüllen passiert auch, wenn eine Bearbeiter:in die Nummer in der Assistenz einträgt oder ändert, solange das Dokument noch keine Positionen hat. Rechnungen werden nicht vorbefüllt. ## Erneuter Abgleich nach einem Stammdatenimport Bestelldaten kommen oft später in Workist an als die Auftragsbestätigung. Deshalb gleicht Workist Auftragsbestätigungen nach jedem erfolgreichen Import der Bestelldaten erneut ab. Betroffen sind Auftragsbestätigungen aller Kanäle, die diese Bestelldaten nutzen, wenn sie - in den letzten 3 Tagen eingegangen sind, - in der Assistenz warten und noch nicht bearbeitet wurden, - eine Bestellnummer enthalten und - deren Bestellung beim letzten Abgleich nicht gefunden wurde. Findet Workist die Bestellung jetzt, aktualisiert es die Abgleichsergebnisse am Dokument. Das Dokument bleibt in der Assistenz. Rechnungen und Bestellungen werden nicht erneut abgeglichen. ## Benutzerzuweisung über Abgleichsdaten Für Bestellungen, Rechnungen und Auftragsbestätigungen kann die [Benutzerzuweisung](/docs/channel-configuration/document-processing/document.md#schritt-3--benutzerzuweisung) die verantwortliche Person aus dem abgeglichenen Angebot bzw. der abgeglichenen Bestellung lesen. Workist liest sie aus den Zusatzdaten (`extra_data`) des Datensatzes. ## Häufige Fragen **Warum wird ein Feld nicht verglichen, obwohl die Spalte in den Stammdaten gefüllt ist?** Das Feld ist im Kanal nicht als Kopf- oder Positionzeilenfeld konfiguriert, oder es gehört nicht zu den Feldern, die für Ihren Kanal verglichen werden. Sprechen Sie Ihre Ansprechperson bei Workist an. **Die Bestellung war beim Eingang der Auftragsbestätigung noch nicht in den Stammdaten. Muss ich etwas tun?** Nein, sofern die Bestelldaten innerhalb von 3 Tagen importiert werden und die Auftragsbestätigung noch unbearbeitet in der Assistenz liegt. Workist gleicht sie dann automatisch erneut ab. Andernfalls verarbeiten Sie das Dokument erneut; dabei gehen manuelle Änderungen am Dokument verloren. --- Source: https://docs.workist.com/docs/channel-configuration/document-processing/agentic-extraction.md # Kanal-Konfiguration — Agentische Extraktion Die **agentische Extraktion** ergänzt die klassische, regelbasierte Feldextraktion (**Kopffelder** und **Positionzeilenfelder**) durch einen **KI-Agenten**, dem Sie in natürlicher Sprache vorgeben, welche zusätzlichen Felder er aus einem Dokument lesen soll. Das ist besonders sinnvoll, wenn Informationen **in Freitext eingebettet** sind, sich **inhaltlich zusammensetzen** lassen oder **kontextuell** hergeleitet werden müssen. Es gibt zwei Varianten, die in der Navigation unter *Dokumentenverarbeitung* als getrennte Einträge erscheinen: | Variante | Wirkebene | Typische Felder | | --- | --- | --- | | **Agentische Kopfzeilenextraktion** | Pro Dokument | Bestellnummer, Lieferdatum, Auftragsart … | | **Agentische Positionsextraktion** | Pro **Position** (Bestellzeile, Rechnungszeile, …) | Artikelnummer, Menge, Einheit, Beschreibung … | **Bedienung und Konfiguration sind nahezu identisch.** Diese Seite beschreibt beide gemeinsam — alles, was nicht ausdrücklich als positions- oder kopfspezifisch markiert ist, gilt für beide Varianten gleichermaßen. Die Besonderheiten der Positionsextraktion fasst der Abschnitt [Besonderheiten der Positionsextraktion](#besonderheiten-der-positionsextraktion) zusammen. :::tip Wann sich agentische Extraktion lohnt Wenn ein Feld nicht immer an derselben Stelle steht, in Freitext eingebettet ist oder kombinierte Logik erfordert (z. B. „Bestellart ableiten aus Marke + Versandadresse" oder „Verpackungseinheit aus dem Beschreibungstext lesen"). Für straff strukturierte Felder reicht die klassische Extraktion in [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md) bzw. [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md). ::: ## Voraussetzungen Bevor Sie eine agentische Extraktion anlegen, sollten Sie: - Wissen, **welches Feld** der KI-Agent zusätzlich extrahieren soll. Das Feld muss bereits als Ausgabefeld bekannt sein: bei der Kopfzeilenextraktion in den [Kopffeldern](/docs/channel-configuration/document-processing/header-fields.md), bei der Positionsextraktion in den [Positionzeilenfeldern](/docs/channel-configuration/document-processing/line-item-fields.md). Die agentische Konfiguration kann nur Felder befüllen, die Workist auch als Ausgabe kennt. - Wissen, **welche Datenquellen** der Agent zur Verfügung haben soll (E-Mail-Text, OCR-Text, bereits extrahierte Felder, …). - Optional: **Referenzdateien** vorbereiten (z. B. eine Liste gängiger Klausel-Formulierungen, eine Sortimentsliste), die der Agent als zusätzlichen Kontext nutzen darf. :::note Eine agentische Extraktion ersetzt nicht die klassische Feldextraktion. Sie wirkt ergänzend: Workist führt zuerst die reguläre Extraktion aus und übergibt deren Ergebnis an den KI-Agenten, der dann zusätzliche Felder ergänzt oder ersetzt. Pro Kanal kann es **eine** Standardkonfiguration je Variante geben — die Standardkonfiguration der Kopfzeilenextraktion ist getrennt von der der Positionsextraktion. Sie können also beide gleichzeitig betreiben. ::: ## Schritt 1 — Die passende Seite öffnen Wählen Sie im Kanal in der Unter-Navigation unter **Dokumentenverarbeitung** den passenden Eintrag — **Agentische Kopfzeilenextraktion** oder **Agentische Positionsextraktion**. Solange für diesen Kanal noch keine Konfiguration angelegt wurde, sehen Sie nur den Hinweis **„Keine Konfiguration vorhanden. Klicken Sie auf ‚Neue Konfiguration', um eine zu erstellen."**. ![Leerer Zustand der agentischen Extraktion](/img/channel-config/llm-kopf/01-uebersicht.png) Am oberen Rand finden Sie zwei Bedienelemente: - **Konfigurations-Auswahl** *(„Wählen Sie eine Konfiguration aus")* — hier wechseln Sie zwischen mehreren bestehenden Konfigurationen. - **+ Neue Konfiguration** — legt eine neue, leere Konfiguration für diesen Kanal an und öffnet sie direkt zum Bearbeiten. ## Schritt 2 — Eine neue Konfiguration anlegen Klicken Sie auf **+ Neue Konfiguration**. Workist legt eine leere Konfiguration an, wählt sie automatisch aus und zeigt das Bearbeitungsformular darunter an. ![Bearbeitungsformular nach Klick auf „Neue Konfiguration"](/img/channel-config/llm-kopf/02-editor-oben.png) Eine Konfiguration besteht immer aus einem Block grundlegender Einstellungen (Name, Geltungsbereich, Aktivierung) und einem Block mit der eigentlichen Logik (Anweisungen, Felder, Wissen). ### Konfigurationsname Neben der Auswahl finden Sie ein **Stift-Symbol**. Damit schalten Sie das Eingabefeld **„Konfigurationsnamen bearbeiten"** frei und tragen einen sprechenden Namen ein (z. B. *„Lieferpriorität aus Freitext"* oder *„Variantenextraktion aus Beschreibungstext"*). Der Name erscheint anschließend in der Auswahlliste oben — wählen Sie ihn so, dass Sie und Kolleg:innen mehrere Konfigurationen für denselben Kanal auseinanderhalten können. ### Standard- vs. Kundenkonfiguration Der erste Umschalter im Formular heißt **„Standardkonfiguration"**. ![Standardkonfiguration-Schalter mit Beschreibungstext](/img/channel-config/llm-kopf/03-standardkonfiguration-toggle.png) Die Beschreibung in der Workbench lautet: *„Standardkonfigurationen funktionieren für alle Dokumente. Deaktivieren, um eine kundenspezifische Konfiguration zu erstellen."* - **Aktiv (Standardkonfiguration):** Die Konfiguration läuft auf **allen** Dokumenten dieses Kanals — unabhängig davon, von welchem Kunden sie stammen. - **Deaktiviert (Kundenkonfiguration):** Die Konfiguration läuft nur für Dokumente bestimmter Geschäftspartner. Sobald Sie den Schalter deaktivieren, blendet die Workbench das zusätzliche Eingabefeld **„Client-IDs"** ein. ![Eingabefeld Client-IDs nach Deaktivierung der Standardkonfiguration](/img/channel-config/llm-kopf/04-client-ids.png) Geben Sie hier eine oder mehrere **Kundennummern** aus Ihren Stammdaten ein (bei Rechnungen, Auftragsbestätigungen und Lieferscheinen: **Lieferantennummern**) und bestätigen Sie jede einzelne mit **Tab** oder **Enter**. Workist vergleicht sie mit der Nummer des Kunden bzw. Lieferanten, den es im Dokument erkannt hat. Mehrere Nummern in **einer** Konfiguration bedeuten, dass diese Konfiguration **für diese Partner gemeinsam** verwendet wird. :::note Pro Kanal nur eine Standardkonfiguration Wenn für diesen Kanal (und diese Variante) bereits eine Standardkonfiguration existiert, ist der Schalter **„Standardkonfiguration"** in jeder weiteren Konfiguration ausgegraut. Der Hinweistext lautet dann: *„Für diesen Kanal existiert bereits eine Standardkonfiguration."* Eine Standardkonfiguration, die schon Ausgabefelder oder Agentenanweisungen hat, lässt sich nicht mehr in eine Kundenkonfiguration umwandeln; legen Sie dafür eine neue Konfiguration an. ::: :::note Ausführungsreihenfolge Workist führt **zuerst die Standardkonfiguration** aus und danach **höchstens eine** Kundenkonfiguration: die, deren Client-IDs die Nummer des erkannten Kunden bzw. Lieferanten enthalten. Werte aus der Kundenkonfiguration **überschreiben** die Werte aus der Standardkonfiguration. Eine Nummer kann deshalb nur in einer Kundenkonfiguration pro Kanal und Variante stehen; überschneidende Client-IDs lehnt die Workbench beim Speichern ab. ::: ### Aktivierung Über den Schalter **„Aktiviert"** schalten Sie die Konfiguration scharf. Ist er ausgeschaltet, wird die Konfiguration während der Dokumentenverarbeitung nicht ausgeführt — praktisch, um eine Konfiguration zu „parken", ohne sie zu löschen. ### Agentenanweisungen (der Prompt) Im Feld **„Agentenanweisungen"** beschreiben Sie in natürlicher Sprache, **was** der KI-Agent tun soll. Dieser Text wird dem Modell als Anweisung mitgegeben. ![Agentenanweisungen mit Beispielprompt](/img/channel-config/llm-kopf/05-agentenanweisungen.png) Ein guter Prompt … 1. **benennt das Ziel klar** — „Extrahiere …", 2. **nennt das Quellmaterial** — „… aus dem Freitext der Bestellung …", 3. **legt das gewünschte Format fest** — „… als ‚dringend', ‚normal' oder ‚unbestimmt' …". Beispiel (Kopfzeilenextraktion): > Extrahiere die Lieferpriorität aus dem Freitext der Bestellung. Gib ‚dringend' zurück, wenn der Text Begriffe wie „eilig", „dringend", „ASAP" oder „sofortige Lieferung" enthält, andernfalls ‚normal'. Enthält die Bestellung keine Hinweise auf die Priorität, gib ‚unbestimmt' zurück. Beispiel (Positionsextraktion): > Extrahiere aus dem Freitext jeder Position die Verpackungseinheit (z. B. Karton, Palette, Stück) und die Menge je Einheit. Ist keine Einheit angegeben, lass das Feld leer. :::tip Wenn Sie im Prompt Bezug auf ein **Eingabefeld** oder **Ausgabefeld** nehmen möchten, geben Sie `/` ein — die Workbench öffnet ein kleines Menü mit den Feldern, die Sie bereits als Eingabe- oder Ausgabefeld ausgewählt haben, und fügt das gewählte Feld als Referenz ein. Wählen Sie die Felder deshalb zuerst aus. ::: ### Eingabefelder vs. Ausgabefelder Dies ist das **wichtigste Konzept** dieser Seite — bitte hier besonders sorgfältig lesen. **Eingabefelder** sind die **Datenquellen**, die dem Agenten zur Verfügung gestellt werden. Sie geben dem Modell den Inhalt, **aus dem** es etwas extrahieren soll: E-Mail-Text, OCR-Text des Anhangs, bereits regulär extrahierte Felder, Anhang-Bilder, usw. ![Eingabefelder mit geöffnetem Auswahl-Menü](/img/channel-config/llm-kopf/06-eingabefelder-dropdown.png) Über **+ Eingabefeld hinzufügen** öffnet sich ein Menü mit allen verfügbaren Datenquellen. Klicken Sie auf einen Eintrag, um ihn hinzuzufügen; über das Mülleimer-Symbol entfernen Sie ihn wieder. **Ausgabefelder** sind die **Zielfelder**, in die der Agent seine Ergebnisse schreibt. Genau diese Werte landen am Ende in Ihrer Ausgabedatei bzw. Ihrem Zielsystem. ![Ausgabefelder mit geöffnetem Auswahl-Menü](/img/channel-config/llm-kopf/07-ausgabefelder-dropdown.png) Über **+ Ausgabefeld hinzufügen** wählen Sie ein oder mehrere Felder aus den konfigurierten Feldern des Kanals — bei der Kopfzeilenextraktion aus den **Kopffeldern**, bei der Positionsextraktion aus den **Positionzeilenfeldern**. Es stehen nur dort konfigurierte Felder zur Verfügung; agentische Konfigurationen können keine neuen Feldnamen erfinden. Faustregel: | Frage | Antwort | | --- | --- | | „Woher kommt die Information für den Agenten?" | Eingabefelder | | „Wohin soll das Ergebnis des Agenten geschrieben werden?" | Ausgabefelder | Eingabe- und Ausgabefelder können auch **identisch** sein: Wenn ein Feld bereits durch die reguläre Extraktion belegt ist, der Agent diesen Wert aber **prüfen und ggf. überschreiben** soll, listen Sie es in beiden Bereichen. :::tip Tipp für die Auswahl der Eingabefelder Geben Sie dem Agenten **nur** die Eingaben, die er wirklich benötigt. Je weniger Datenquellen, desto fokussierter und schneller arbeitet der Agent. ::: ### Benutzerdefinierte Felder als Ziel der agentischen Extraktion Bisher haben wir nur Felder verwendet, die im Kanal bereits als **Kopffelder** oder **Positionzeilenfelder** konfiguriert sind. Für agentische Extraktion wollen Sie aber oft **neue Felder** anlegen, die es im Standard-Schema gar nicht gibt — etwa „Lieferpriorität", „Variantencode der Position" oder „Auftragsklassifikation". Genau dafür gibt es **benutzerdefinierte Felder**. Benutzerdefinierte Felder leben in den regulären Bereichen [Kopffelder](/docs/channel-configuration/document-processing/header-fields.md) und [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md), sind dort aber leer — sie werden nicht durch die klassische Extraktion gefüllt. Stattdessen werden sie typischerweise **erst durch eine agentische Konfiguration mit Inhalt belegt**, indem Sie sie als **Ausgabefelder** auswählen. Der folgende Workflow gilt **identisch** für beide Varianten — für ein kopfweites Feld arbeiten Sie auf **Kopffelder**, für ein positionsweites Feld auf **Positionzeilenfelder**. #### Schritt A — „Benutzerdefiniertes Feld" anlegen Öffnen Sie in der Kanal-Navigation **Kopffelder** (oder **Positionzeilenfelder**, je nachdem, ob das neue Feld pro Dokument oder pro Position vorkommen soll). Klicken Sie oben rechts neben der Überschrift **„Konfigurierte Felder"** auf das **+**-Symbol. Es öffnet sich ein Auswahl-Menü mit zwei Bereichen: ganz oben **„Benutzerdefiniertes Feld"** mit Pluszeichen, darunter — durch eine Trennlinie abgesetzt — die Liste der noch nicht hinzugefügten Standardfelder. ![Geöffnetes „+"-Menü mit „Benutzerdefiniertes Feld" als oberster Eintrag](/img/channel-config/llm-kopf/cf-01-plus-menu.png) Klicken Sie auf **„Benutzerdefiniertes Feld"**. Sofort wird in der linken Liste ein neuer Eintrag mit dem Platzhalternamen **„Unbenanntes Feld"** angelegt und automatisch ausgewählt. Auf der rechten Seite erscheinen die zugehörigen Eingabefelder. ![Frisch hinzugefügtes benutzerdefiniertes Feld: links „Unbenanntes Feld", rechts leere Optionen](/img/channel-config/llm-kopf/cf-02-leeres-feld.png) :::note Solange Sie noch nicht gespeichert haben, ist das Feld nur in Ihrer Sitzung sichtbar. Wechseln Sie ohne **Speichern** auf eine andere Seite, ist das Feld weg. ::: #### Schritt B — Die Pflichtfelder ausfüllen Bei einem benutzerdefinierten Feld sind **vier** Eingaben Pflicht (in der UI mit `*` gekennzeichnet): die drei folgenden und der **Datentyp** (vorbelegt mit *Zeichenkette*, siehe unten). Der Schalter **Erforderlich** ist bei neuen benutzerdefinierten Feldern aus. ![Markierte Pflichtfelder: Datenbezeichnungsname, Feldbezeichnungsname, Anweisungen für Datenbezeichnungen](/img/channel-config/llm-kopf/cf-03-pflichtfelder-markiert.png) | Pflichtfeld | Bedeutung | | --- | --- | | **Datenbezeichnungsname** | Der Name des Feldes in der **Ausgabedatei** (z. B. `delivery_priority`). Muss **ausgefüllt** und **eindeutig im Kanal** sein. Leerzeichen ersetzt die Workbench beim Tippen durch Unterstriche. **Einmal gespeichert, ist dieser Wert nicht mehr änderbar** — er ist Teil Ihres Datenvertrags mit dem Zielsystem. | | **Feldbezeichnungsname** | Der Name, unter dem das Feld in der **Workbench-Assistenz** erscheint (z. B. „Lieferpriorität"). Kann jederzeit geändert werden, ohne die Ausgabedatei zu brechen. | | **Anweisungen für Datenbezeichnungen** | Kurzer Kontext für die KI, **wie und wo** sie das Feld in Ihren Dokumenten erkennen soll. Maximal 500 Zeichen. Beispiel: *„Die Lieferpriorität steht oben rechts im Briefkopf. Erlaubte Werte: hoch, mittel, niedrig."* | :::tip Benennung des Datenbezeichnungsnamens Wir empfehlen **`snake_case`** (Kleinbuchstaben, Wörter durch Unterstriche getrennt, z. B. `delivery_priority`, `customer_internal_note`, `variant_code`). Die Workbench erzwingt das nicht. Vermeiden Sie Umlaute, Bindestriche und Großbuchstaben — dieselbe Konvention erwarten die meisten Zielsysteme. Da der Wert **nach dem ersten Speichern unveränderlich** ist, lohnt es sich, ihn vorab kurz mit Ihrer Ansprechperson bei Workist abzustimmen. ::: :::warning Speichern erfordert einen Wert Solange das Feld **Datenbezeichnungsname** leer ist, lässt sich das benutzerdefinierte Feld **nicht speichern** — die Workbench bricht den Speichervorgang ab und markiert das Feld rot. Tragen Sie den Wert daher gleich beim Anlegen ein. ::: Zusätzlich wählen Sie den **Datentyp**, der bestimmt, wie Workist den extrahierten Wert interpretiert und validiert: ![Geöffnetes Datentyp-Dropdown mit allen fünf Optionen](/img/channel-config/llm-kopf/cf-04-datentyp-dropdown.png) | Datentyp | Wann verwenden? | | --- | --- | | **Zeichenkette** | Freitext oder kategorische Werte (z. B. „hoch / mittel / niedrig", Status-Codes, Klassifikationen). | | **Dezimalzahl** | Beträge, Preise, Mengen mit Nachkommastellen. | | **Ganzzahl** | Stückzahlen, Wochenzahlen, ID-ähnliche Zahlen ohne Dezimalstellen. | | **Datum** | Datumsangaben. Liegt ein Datum viele Monate vom Dokumentdatum entfernt, senkt Workist die Konfidenz und erklärt das am Feld. | | **Boolesch** | Ja/Nein-Antworten („Ist eilig?", „Frachtfrei?"). | Bei **Zeichenkette** erscheint zusätzlich das Feld **„Geben Sie Optionen an, wenn Sie die möglichen Werte des Feldes einschränken möchten"**. Geben Sie hier eine Liste erlaubter Werte ein, wenn die KI sich auf einen festen Wortschatz festlegen soll. ![Choices-Feld erscheint nur bei Datentyp „Zeichenkette"](/img/channel-config/llm-kopf/cf-05-choices-bei-zeichenkette.png) :::note Das Choices-Feld erscheint **nur** bei **Zeichenkette**. Bei numerischen Datentypen oder Datum macht die Begrenzung keinen Sinn und wird ausgeblendet. ::: Sobald Sie den **Feldbezeichnungsnamen** eingegeben haben, übernimmt die linke Liste den neuen Namen automatisch — aus „Unbenanntes Feld" wird beispielsweise „Lieferpriorität". ![Nach Eingabe des Feldbezeichnungsnamens aktualisiert sich der Eintrag links](/img/channel-config/llm-kopf/cf-06-feldbezeichnung-erscheint-links.png) #### Schritt C — Anweisungen sorgfältig formulieren Die **Anweisungen für Datenbezeichnungen** sind der Hebel, mit dem Sie die Trefferquote Ihres Custom-Feldes steuern. Schreiben Sie **knapp und konkret**: ![Anweisungen-Feld mit Beispiel-Prompt, Zeichenzähler 105/500](/img/channel-config/llm-kopf/cf-07-anweisungen-prompt.png) **Was eine gute Anweisung enthält:** - **Wo** im Dokument steht der Wert (oben rechts? in der Tabelle? in einer bestimmten Spalte?). - **Wie sieht der Wert typischerweise aus** (kurze Beispiele, erlaubte Werte, übliche Formulierungen). - **Was er NICHT ist** (Anti-Beispiele, damit die KI Verwechslungen vermeidet). **Was Sie weglassen sollten:** - Lange Hintergrundgeschichten zum Geschäftsprozess. - Anweisungen an die KI, wie sie „denken" soll — das gehört in die **Agentenanweisungen** der Konfiguration, nicht in die Feldanweisungen. :::note Begrenzung Maximal 500 Zeichen pro Feld. Wenn Ihre Anweisung länger werden müsste, prüfen Sie, ob ein Teil der Information stattdessen als **Wissen** (Datei-Upload, siehe weiter unten) beigesteuert werden kann. ::: #### Schritt D — Speichern und als Ausgabefeld einbinden Klicken Sie unten auf **Speichern**. Workist übernimmt das Feld als regulär konfiguriertes Feld — aber zunächst **ohne Werte**, da die klassische Extraktion nicht weiß, wie sie das neue Feld füllen soll. Wechseln Sie jetzt zurück auf die agentische Konfiguration, öffnen Sie Ihre Konfiguration (oder legen Sie eine neue an) und klicken Sie unter **Ausgabefelder** auf **+ Ausgabefeld hinzufügen**. In der Auswahlliste erscheint Ihr neues benutzerdefiniertes Feld neben allen anderen Feldern des Kanals. ![Auswahlliste „Ausgabefeld hinzufügen" mit allen verfügbaren Feldern](/img/channel-config/llm-kopf/cf-08-als-ausgabefeld-im-llm.png) Fügen Sie das Feld hinzu, ergänzen Sie passende **Eingabefelder** (z. B. den E-Mail-Text), geben Sie die **Agentenanweisungen** an und klicken Sie auf **Speichern**. Ab dem nächsten Dokument füllt der Agent das neue Feld automatisch. :::tip Faustregel Pro Feld nur **eine** primäre Quelle der Wahrheit — entweder klassisch (über Lookups oder feste Mappings) **oder** agentisch (über Ausgabefelder). Die agentische Extraktion läuft nach der klassischen und **überschreibt** jedes Feld, das als **Ausgabefeld** ausgewählt ist — egal, ob es auch Eingabefeld ist. ::: #### Schritt E — Benutzerdefiniertes Feld wieder entfernen Wenn Sie ein benutzerdefiniertes Feld nicht mehr brauchen, klicken Sie in der linken Feldliste rechts neben dem Feldnamen auf das **×** und anschließend auf **Speichern**. Entfernen Sie das Feld **vorher** aus allen agentischen Konfigurationen, in denen es als Ausgabefeld geführt ist. Andernfalls schlägt die Verarbeitung neuer Dokumente in diesem Kanal fehl. :::warning Wenn das Feld bereits in der Ausgabedatei produktiver Dokumente steht, entfernt es das Löschen nicht rückwirkend. Bereits exportierte Daten bleiben unverändert; nur neue Dokumente enthalten das Feld nicht mehr. ::: ### Wissen (Referenzdateien) Im Bereich **„Wissen"** können Sie Dateien hochladen, die dem Agenten als zusätzlicher Kontext zur Verfügung gestellt werden — zum Beispiel eine Liste Ihrer Auftragsarten, ein Auszug aus dem Sortimentskatalog oder eine Abkürzungstabelle mit kundeninternen Kürzeln. ![Wissens-Drop-Zone für Referenzdateien](/img/channel-config/llm-kopf/08-wissen.png) Erlaubte Dateiformate sind **.txt**, **.csv**, **.md** und **.json**. Ziehen Sie die Dateien in den Bereich **„Dateien hier ablegen oder klicken, um hochzuladen"** oder klicken Sie hinein, um den Dateiauswahl-Dialog zu öffnen. Die Workbench zeigt pro Datei die geschätzte Anzahl Tokens. Dateien über der Größengrenze oder mit mehr als **200.000 Tokens** werden nicht hochgeladen. Ist eine Wissensdatei bei der Verarbeitung zu groß, läuft die Konfiguration nicht; die Ausgabefelder behalten die Werte der klassischen Extraktion mit Konfidenz 0, und das Dokument zeigt einen Hinweis. :::warning Vertraulichkeit Hochgeladene Wissensdateien werden bei jeder Extraktion **in den Prompt** an die KI mitgegeben. Sie sind also **nicht „geheim"** gegenüber dem Modell. Laden Sie nur Inhalte hoch, deren Weitergabe an den von Workist eingesetzten KI-Anbieter unproblematisch ist (keine Passwörter, keine personenbezogenen Daten, die nicht ohnehin Teil des Dokuments wären, …). ::: :::tip Halten Sie Wissensdateien **schlank**. Je größer die Datei, desto teurer und langsamer wird jede einzelne Extraktion — und der Agent kann sich in irrelevanten Details verlieren. ::: ### RAG für Few-Shot-Learning Ganz unten in der Konfiguration finden Sie die Option **„Verwenden Sie Retrieval Augmented Generation (RAG) für Few-Shot-Learning"**. ![RAG-Auswahl mit zwei Optionen](/img/channel-config/llm-kopf/10-rag-auswahl.png) Sie haben zwei Optionen: - **Frühere Unterstützungen zur Abfrage hinzufügen** — Workist sucht zu jedem neuen Dokument die bis zu fünf ähnlichsten Fälle aus demselben Kanal und stellt sie dem KI-Agenten als Beispiele zur Verfügung. Als Beispiel gespeichert wird ein Dokument, bei dem eine Bearbeiter:in in der **Assistenz** eines der Ausgabefelder der Konfiguration geändert hat. Das verbessert in vielen Fällen die Treffergenauigkeit spürbar, sobald genügend Lernmaterial vorliegt. - **Keine früheren Unterstützungen einbeziehen** — der Agent arbeitet ausschließlich mit dem aktuellen Dokument und den Anweisungen. Bei der **Kopfzeilenextraktion** beginnen Sie typischerweise mit **„Keine"** und schalten RAG später dazu, sobald sich in der Assistenz ein Erfahrungsschatz aufgebaut hat. Bei der **Positionsextraktion** lohnt sich RAG meist von Anfang an, weil häufig auftretende Sonderfälle einzelner Kunden so wiedererkannt werden. ### Werkzeuge Im Bereich **„Werkzeuge"** wählen Sie über **Werkzeug hinzufügen** aus, welche Abfragen der Agent während der Extraktion selbst ausführen darf. Die Werkzeuge greifen auf die Stammdaten des Kanals zu: Artikel suchen und abfragen, Kunden, Kontakte, Liefer- und Rechnungsadressen nachschlagen sowie die vorhandenen Werte von Artikelmerkmalen auflisten. Geben Sie dem Agenten nur die Werkzeuge, die er für seine Aufgabe braucht. :::note Von Workist verwaltete Einstellungen Modell, Temperatur und Denkaufwand des KI-Agenten werden von Workist verwaltet und sind in Ihrer Workbench-Anmeldung nicht sichtbar. Wenn Sie hier eine Anpassung wünschen, sprechen Sie bitte Ihre Ansprechperson bei Workist an. ::: ## Schritt 3 — Speichern und aktivieren Klicken Sie am Ende der Konfiguration auf **Speichern**. Im Erfolgsfall erscheint eine Bestätigung; die Konfiguration ist anschließend für nachfolgende Dokumente aktiv, sofern der Schalter **Aktiviert** eingeschaltet ist. ![Speichern-Button am Ende des Formulars](/img/channel-config/llm-kopf/11-werkzeuge-und-speichern.png) :::note Wann greift die neue Konfiguration? Erst beim **nächsten** eingehenden Dokument. Bereits verarbeitete Dokumente werden nicht rückwirkend neu extrahiert. ::: ### Empfohlene Reihenfolge mit der Standardkonfiguration Wenn Sie sowohl eine **Standardkonfiguration** als auch eine oder mehrere **Kundenkonfigurationen** für denselben Kanal pflegen: 1. Halten Sie die Standardkonfiguration **bewusst einfach** — sie beschreibt das, was für **alle** Kunden gelten soll. 2. Verwenden Sie **Kundenkonfigurationen nur dort**, wo ein einzelner Kunde oder eine kleine Gruppe von Kunden **gezielt abweichende Logik** brauchen. 3. Denken Sie daran: Die Kundenkonfiguration **überschreibt** die Werte aus der Standardkonfiguration. Doppelt extrahierte Felder gewinnen also immer aus der **kundenspezifischen** Konfiguration. ## Schritt 4 — Konfigurationen wechseln, umbenennen, löschen Mehrere Konfigurationen erscheinen oben in der **Auswahlliste**. Klicken Sie auf die Liste, um eine andere Konfiguration zu laden — das Formular darunter aktualisiert sich automatisch. - **Umbenennen:** Stift-Symbol neben der Auswahl klicken, neuen Namen eingeben und **Speichern**. - **Löschen:** **Mülleimer-Symbol** rechts neben **+ Neue Konfiguration**. Workist fragt vor dem Löschen sicherheitshalber nach. Das Löschen ist endgültig — eine gelöschte Konfiguration (inklusive aller hochgeladenen Wissensdateien) lässt sich nicht wiederherstellen. Wenn Sie nur kurz pausieren möchten, schalten Sie stattdessen den Umschalter **„Aktiviert"** aus. ## Besonderheiten der Positionsextraktion Die agentische Positionsextraktion folgt allen oben beschriebenen Schritten — mit drei Unterschieden: - **Sie läuft pro Position.** Die Konfiguration wird auf **jede einzelne Zeile** des Dokuments angewendet. Das macht sie mächtig, aber auch langsamer und teurer als die Kopf-Variante (jede Position erzeugt einen eigenen KI-Aufruf). - **Ausgabefelder kommen aus den Positionzeilenfeldern.** Möchten Sie ein Feld extrahieren, das es dort noch nicht gibt, legen Sie es zuerst als [benutzerdefiniertes Feld](#benutzerdefinierte-felder-als-ziel-der-agentischen-extraktion) in den Positionzeilenfeldern an. - **Strukturelle Positions-Operationen** kann Workist auf Anfrage freischalten — der Agent darf dann Positionen **hinzufügen**, **löschen**, **aufteilen** oder hierarchisch als **Unterelemente** verknüpfen (z. B. „2 Paletten à 24 Stück" in mehrere logische Zeilen aufteilen). Diese Operationen sind von Workist verwaltet und nicht selbst konfigurierbar. Dokumente mit Unterpositionen gehen **immer** in die Assistenz (siehe [Wann wird automatisiert?](/docs/channel-configuration/document-processing/validation-checks.md#wann-wird-automatisiert)). :::warning Überschreibt die klassische Extraktion Wenn sowohl die klassische Extraktion **als auch** die agentische Positionsextraktion dasselbe Feld befüllen, **überschreibt der Agent den klassisch extrahierten Wert**. Wählen Sie als Ausgabefelder deshalb bevorzugt solche, die die klassische Extraktion **nicht** zuverlässig erfasst. ::: **Empfohlene Reihenfolge** beim Aufsetzen eines neuen Kanals: zuerst [Positionzeilenfelder](/docs/channel-configuration/document-processing/line-item-fields.md) vollständig konfigurieren, dann beobachten, welche Felder regelmäßig leer bleiben oder schlecht erkannt werden, und erst danach eine agentische Positionsextraktion gezielt für diese Problemfelder anlegen. ## Häufige Fragen **Muss ich für jedes Feld eine eigene Konfiguration anlegen?** Nein. Eine Konfiguration kann beliebig viele **Ausgabefelder** gleichzeitig befüllen. Es ist meistens sinnvoll, fachlich zusammenhängende Felder in **einer** Konfiguration zu bündeln — dann „sieht" der Agent den Gesamtkontext. **Was passiert, wenn ich die Konfiguration deaktiviere?** Workist überspringt sie bei der nächsten Verarbeitung. Bestehende Ausgabewerte aus früheren Läufen bleiben unverändert. **Was passiert, wenn der Agent ein Feld nicht extrahieren kann?** Findet der Agent keinen Wert, liefert er ein leeres Ergebnis — und das **überschreibt** den Wert der klassischen Extraktion. Den klassischen Wert behält Workist nur, wenn die Konfiguration technisch nicht ausgeführt werden konnte. Dann bleiben die Werte stehen, ihre Konfidenz wird auf 0 gesetzt, und das Dokument zeigt den Hinweis, dass die KI-Regel nicht ausgeführt wurde. **Wie viele Konfigurationen kann ich anlegen?** Eine Standardkonfiguration je Variante und beliebig viele Kundenkonfigurationen je Kanal. Jede Client-ID darf nur in einer Kundenkonfiguration stehen; pro Dokument läuft höchstens eine Kundenkonfiguration. **Werden meine Wissensdateien an die KI weitergegeben?** Ja — Wissensdateien werden in den Prompt der KI eingebettet. Laden Sie also keine Inhalte hoch, die nicht zur Extraktion gehören oder die Sie nicht an Workists KI-Anbieter weitergeben möchten. ## Hilfe und Support Wenn eine Konfiguration nicht das gewünschte Ergebnis liefert, wenden Sie sich an Ihre Ansprechperson bei Workist. Halten Sie folgende Informationen bereit: - den **Kanalnamen** und den **Konfigurationsnamen** sowie die Variante (Kopfzeilen- oder Positionsextraktion), - ob es sich um eine **Standard-** oder **Kundenkonfiguration** handelt (bei Kundenkonfiguration: die betroffenen **Client-IDs**, also Kunden- bzw. Lieferantennummern), - ein **Beispieldokument**, auf dem die Konfiguration ein falsches Ergebnis lieferte, - den **Wert**, den der Agent geliefert hat, und den **Wert**, den Sie erwartet hätten. --- Source: https://docs.workist.com/docs/channel-configuration/exported-documents.md # Kanal-Konfiguration — Exportierte verarbeitete Dokumente Im Bereich **Exportierte verarbeitete Dokumente** legen Sie fest, **wie** die fertig verarbeiteten Daten in Ihr System gelangen und **in welchem Format**. Vier Unterseiten arbeiten dabei zusammen: 1. **AS2** — Verbindungsdaten für den Versand über das EDI-Protokoll AS2. 2. **SFTP** — Verbindungsdaten für Ihren eigenen SFTP-Server. Für den Workist-verwalteten SFTP-Server bleibt diese Seite leer. 3. **Upload** — der Übertragungsweg (SFTP, AS2, API, ERP-Integration, …), ob Workist aktiv überträgt, Zielordner und mitgesendete Dateien. 4. **Ausgabedatei** — Format und Inhalt der erzeugten Datei (z. B. XML nach Workist-Schema). :::warning Standardverhalten: Workist überträgt sofort Ein neuer Kanal überträgt auch ohne gespeicherte Upload-Konfiguration. Die Standardwerte sind: Übertragungsweg **SFTP**, **Upload aktivieren** eingeschaltet, **Originaldokument hochladen** eingeschaltet. Jedes abgeschlossene Dokument landet als Ausgabedatei plus PDF im Ordner `/incoming` Ihres Bereichs auf dem von Workist verwalteten SFTP-Server. Neue Kanäle starten mit ausgeschalteter Automatisierung. Übertragen wird also erst, wenn jemand ein Dokument in der Assistenz abschließt. Wie Sie testen, ohne dass Testdokumente in Ihrem Produktivsystem landen: [Schritt 5: Testen](/docs/implementation-guide/step-5-test.md). ::: ## Voraussetzungen - Die Berechtigung, Kanäle zu konfigurieren (Rollen **Manager** und **Admin**), siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). - Für **AS2**: Endpunkt, AS2-Name und Zertifikate Ihres AS2-Partners. Ihr Partner muss umgekehrt die AS2-ID und die Zertifikate von Workist hinterlegen; diese erhalten Sie von Ihrer Ansprechperson bei Workist. - Für einen **eigenen SFTP-Server**: Host, Port, Benutzername, Hostkey und ein Passwort (oder Sie hinterlegen den öffentlichen SSH-Schlüssel von Workist auf Ihrem Server). - Für den **Workist-verwalteten SFTP-Server**: Ihr öffentlicher SSH-Schlüssel unter **Einstellungen → Öffentliche SFTP-Schlüssel**, siehe [Schritt 1: Verbindung herstellen](/docs/implementation-guide/step-1-establish-connection.md) und [Datenaustausch mittels SFTP](/docs/data-exchange/sftp.md). - Für die **Ausgabedatei**: Für das Workist-Standardformat ist nichts nötig. Andere Formate richten Sie gemeinsam mit Ihrer Ansprechperson bei Workist ein. ## Schritt 1 — AS2-Konfiguration {#as2} Wählen Sie in der Navigation unter **Exportierte verarbeitete Dokumente** den Eintrag **AS2**. ![AS2-Konfiguration eines Kanals](/img/channel-config/12-ausgang-as2.png) | Feld | Bedeutung | | --- | --- | | **AS2 Absendername (leer lassen für Standard-Workist AS2 Absendername)** | Der AS2-Name, mit dem Workist sich beim Empfänger meldet. Solange das Feld leer bleibt, verwendet Workist seinen Standardnamen, der für die meisten Fälle ausreicht. | | **AS2 Empfängerendpunkt** | Die URL des AS2-Endpunkts auf der Gegenstelle. | | **AS2 Empfängername** | Der AS2-Identifier der Gegenstelle. Muss exakt mit dem übereinstimmen, was die Gegenstelle vergibt; Tippfehler führen zu Ablehnungen. | | **AS2 Empfänger-Verifizierungszertifikat** | Öffentliches Zertifikat (PEM-Format), mit dem Workist die digitalen Signaturen der Gegenstelle prüft. Wird Ihnen vom Empfänger bereitgestellt. | | **AS2 Empfänger-Verschlüsselungszertifikat** | Öffentliches Zertifikat (PEM-Format), mit dem Workist die ausgehenden Nachrichten an die Gegenstelle verschlüsselt. | | **Empfängerzertifikate validieren?** | Standard: an. Wenn aktiv, prüft Workist die Gültigkeit der hinterlegten Empfängerzertifikate. | Klicken Sie auf **Speichern**. :::note Die AS2-Konfiguration allein sorgt **nicht** dafür, dass Dokumente übertragen werden. Stellen Sie zusätzlich im Bereich **Upload** den Übertragungsweg auf **AS2**. ::: Was Ihr AS2-Partner wissen muss: - Workist **signiert und verschlüsselt** jede Nachricht (Verschlüsselung 3DES, Signatur SHA-1) und erwartet eine **synchrone, signierte MDN**. - Jede Datei geht als eigene Nachricht: zuerst das Originaldokument, dann ggf. zusätzliche Dateien, zuletzt die Ausgabedatei. - Bei Verbindungsfehlern oder einer Antwort mit HTTP-Status 5xx versucht Workist es insgesamt dreimal im Abstand von 10 Sekunden. Danach gilt die Übertragung als fehlgeschlagen, siehe [Zustellfehler](#zustellfehler). - Die Original-E-Mail kann per AS2 nicht mitgesendet werden. ## Schritt 2 — SFTP-Konfiguration {#sftp} Wählen Sie in der Navigation unter **Exportierte verarbeitete Dokumente** den Eintrag **SFTP**. Diese Seite brauchen Sie nur für Ihren **eigenen** SFTP-Server. ![SFTP-Konfiguration eines Kanals](/img/channel-config/13-ausgang-sftp.png) | Feld | Bedeutung | | --- | --- | | **Host (leer lassen für Workist-verwalteten SFTP Server)** | Hostname Ihres eigenen SFTP-Servers. Solange das Feld leer ist, verwendet Workist den eigenen verwalteten SFTP-Server. | | **Hostkey (leer lassen für Workist-verwalteten SFTP Server)** | Öffentlicher Hostschlüssel Ihres Servers im Format ` `, z. B. `ssh-ed25519 AAAAC3Nza…`, ohne Hostname und ohne Kommentar. Unterstützte Typen: `ssh-rsa`, `ssh-dss`, `ecdsa-…`, `ssh-ed25519`. Bleibt das Feld leer, prüft Workist den Hostschlüssel nicht. | | **Port (leer lassen für Workist-verwalteten SFTP Server)** | Port Ihres eigenen SFTP-Servers. Bei einem eigenen Server **Pflicht**: Es gibt keinen Standardwert, auch nicht 22. | | **Benutzername (leer lassen für Workist-verwalteten SFTP-Server)** | SFTP-Benutzername auf Ihrer Seite. | | **Passwort (leer lassen für Workist-verwalteten SFTP-Server)** | Ist ein Passwort hinterlegt, meldet sich Workist damit an. Ohne Passwort meldet sich Workist mit seinem eigenen SSH-Schlüssel an, den Sie auf Ihrem Server freigeben müssen. Das Feld zeigt den hinterlegten Wert nicht an. Ein neuer Wert überschreibt das Passwort; ein leeres Feld behält das gespeicherte Passwort bei. Löschen lässt es sich hier nicht. | :::tip Workist-verwalteter SFTP-Server (Standardfall) Lassen Sie alle Felder leer. Hinterlegen Sie stattdessen Ihren öffentlichen SSH-Schlüssel unter **Einstellungen → Öffentliche SFTP-Schlüssel**, siehe [Schritt 1: Verbindung herstellen](/docs/implementation-guide/step-1-establish-connection.md). ::: Wie Workist die Dateien auf dem SFTP-Server ablegt (Dateinamen, Reihenfolge, Überschreiben gleichnamiger Dateien), beschreibt [Datenaustausch mittels SFTP](/docs/data-exchange/sftp.md). Klicken Sie auf **Speichern**. ## Schritt 3 — Upload-Konfiguration {#upload} Wählen Sie in der Navigation unter **Exportierte verarbeitete Dokumente** den Eintrag **Upload**. Hier legen Sie fest, **wie** die Ergebnisse zu Ihnen kommen und welche Dateien mitgehen. Welche Felder erscheinen, hängt vom gewählten Übertragungsweg ab. ### Übertragungsweg wählen Das erste Feld, **Wie sollen die Dokumente übertragen werden? (SFTP, AS2)**, ist ein Pflichtfeld. Zur Auswahl stehen sechs Wege: | Übertragungsweg | Was passiert | | --- | --- | | **SFTP** (Standard) | Workist legt die Dateien auf dem SFTP-Server ab: dem Workist-verwalteten oder Ihrem eigenen aus [Schritt 2](#sftp). | | **AS2** | Workist sendet die Dateien an den AS2-Empfänger aus [Schritt 1](#as2). | | **API** | Ihr System holt die Ergebnisse über die [Workist-API](/docs/data-exchange/api.md) ab. Workist überträgt nichts aktiv. Über [Webhooks](/docs/data-exchange/webhooks.md) kann Ihr System erfahren, wann ein Ergebnis bereitsteht. | | ERP-Integration | Workist überträgt die Ergebnisse direkt in Ihr verbundenes ERP-System, siehe [Konnektoren](/docs/data-exchange/connectors.md). Dieser Weg wird automatisch eingestellt, wenn Sie den Kanal in einer ERP-Integration auswählen. Dabei schaltet Workist die Serialisierung der Ausgabedatei aus, weil die Daten direkt ins ERP gehen. | | Manuell | Die Ergebnisse werden manuell übertragen. Workist überträgt nichts. | | Sonstige | Ein anderer Übertragungsweg. Workist überträgt nichts. | ### Felder | Feld | Erscheint bei | Standard | Bedeutung | | --- | --- | --- | --- | | **Upload aktivieren** | SFTP, AS2, ERP-Integration | an | Ob Workist die Ergebnisse aktiv überträgt. Ist der Schalter aus, verarbeitet Workist die Dokumente weiter, überträgt aber nichts, und ein Hinweis zeigt an, dass die Übertragung pausiert ist. Dokumente, die in dieser Zeit abgeschlossen werden, überträgt Workist auch später nicht. | | **Zielordner für generierte Dateien** | SFTP | leer = `/incoming` | Ordner für die Ausgabedatei. Auf dem Workist-verwalteten Server liegt der Ordner in Ihrem Bereich. | | **Zielordner für ausgehende Dokumente** | SFTP | leer = `/incoming` | Ordner für Originaldokument und Original-E-Mail. | | **Originaldokument hochladen** | SFTP, AS2 | an | Sendet zusätzlich zur Ausgabedatei das verarbeitete Dokument. Hat Workist das Dokument per Texterkennung gelesen, ist das die PDF, die Workist dabei erzeugt hat, auch wenn das Original z. B. ein Bild war. Sonst, z. B. bei XML-E-Rechnungen, wird die Originaldatei gesendet. Der Dateiname entspricht dem der Ausgabedatei, nur mit anderer Endung. | | **Originale E-Mail hochladen** | SFTP | aus | Sendet die ursprüngliche E-Mail als `.eml`-Datei mit demselben Namen wie die Ausgabedatei. Nur für Dokumente, die per E-Mail eingegangen sind. | :::note Übergabe per API Wählen Sie **API** als Übertragungsweg und speichern Sie. Weitere Einstellungen sind nicht nötig: Workist blendet die übrigen Felder aus und setzt sie beim Speichern zurück, auch **Upload aktivieren**. Wechseln Sie später zurück zu SFTP, AS2 oder ERP-Integration, schalten Sie **Upload aktivieren** wieder ein. Dasselbe gilt für *Manuell* und *Sonstige*. ::: ### Zusätzliche Dateien (nur Bestellkanäle) In Bestellkanälen gibt es unter dem Upload-Formular einen eigenen Bereich **Zusätzliche Dateien** (bei SFTP und AS2). Damit sendet Workist weitere Anhänge derselben E-Mail mit, die es als einen der gewählten Typen erkannt hat: - **Zusätzliche Dateitypen**: Lieferschein, Rechnung, Angebot, Bestellbestätigung, Preisanfragen, Andere. - **Zielordner für zusätzliche Dateien** (nur SFTP): eigener Ordner. Leer = derselbe Ordner wie für ausgehende Dokumente. Die mitgesendeten Dateien sind in der Workist-XML unter `` aufgeführt, siehe [Ausgabeformat Bestellungen](/docs/output-formats/orders.md). Ob der Bereich erscheint, hängt von der Einrichtung des E-Mail-Postfachs ab; bei neuen Bestellkanälen ist er vorhanden. Klicken Sie auf **Speichern**. ## Schritt 4 — Ausgabedatei {#ausgabedatei} Wählen Sie in der Navigation unter **Exportierte verarbeitete Dokumente** den Eintrag **Ausgabedatei**. ![Ausgabedatei-Konfiguration mit aktivierter Serialisierung](/img/channel-config/15-ausgang-ausgabedatei.png) Hier legen Sie fest, **was** Workist in die Ausgabedatei schreibt, unabhängig davon, **wie** sie übertragen wird. | Feld | Standard | Bedeutung | | --- | --- | --- | | Schalter für den Output Mapper (nur Bestellkanäle) | aus | Wenn an, erzeugt Workist die Datei aus einer Zuordnung, die Workist für Sie einrichtet; die Serialisierungsfelder werden ausgeblendet. Gibt es noch keine Zuordnung, erscheint eine Warnung und es wird keine Ausgabedatei erzeugt. Schalten Sie ihn nur in Absprache mit Workist ein. | | **Serialisierung aktivieren** | an | Wenn aus, erzeugt Workist keine Ausgabedatei. Ist zugleich SFTP oder AS2 mit **Upload aktivieren** eingestellt, schlägt die Übertragung fehl und das Dokument zeigt einen Fehler. Bei ERP-Integrationen ist der Schalter bewusst aus. | | **Python-Serialisierungsmodule z.B. …** | leer | Bestimmt das Dateiformat. Leer = das Standardformat des Produkts: Workist-XML für Bestellungen, Preisanfragen und Rechnungen, openTRANS für Lieferscheine und Auftragsbestätigungen, SAP IDoc BOMMAT07 für Leistungsverzeichnisse (siehe [Ausgabeformate](/docs/output-formats.md)). Andere Formate richtet Workist gemeinsam mit Ihnen ein. Ändern Sie den Wert nicht ohne Rücksprache. | | **Zusätzliche Kopfzeilendatenfelder** | leer | Weitere Kopfdatenfelder für die Ausgabedatei, die nicht standardmäßig enthalten sind. Geben Sie den technischen Feldnamen ein und bestätigen Sie mit der Eingabetaste. **Achtung:** Ein Feldname, den das Format nicht kennt, lässt die Erzeugung der Ausgabedatei für jedes Dokument fehlschlagen. | | **Zusätzliche Positionszeilenfelder** | leer | Wie oben, aber für Felder pro Position. | | **Verweis auf die analysierte Datei einfügen (Element ``)** | an | Schreibt den **Dateinamen** der PDF, die Workist mitsendet, in die Ausgabedatei (gleicher Name wie die Ausgabedatei, Endung `.pdf`). Es ist kein Link und keine URL. Sinnvoll zusammen mit **Originaldokument hochladen**. | | **Link zur Workbench einfügen (Element ``)** | aus | Fügt einen Link ein, mit dem Empfänger:innen das Dokument direkt in der Workbench öffnen. | | **E-Mail-Absenderinformationen einfügen (Element ``)** | aus | Schreibt die **E-Mail-Adresse des Absenders** der ursprünglichen E-Mail in die Ausgabedatei. | | **Kurzen externen Dateinamen verwenden** | aus | Verwendet eine 22-stellige statt einer 36-stelligen ID als Dateinamen, für die Ausgabedatei und die mitgesendete PDF. Nützlich, wenn das Empfangssystem die Länge von Dateinamen begrenzt. | Klicken Sie auf **Speichern**. :::note Vor dem ersten Speichern Solange die Seite noch nie gespeichert wurde, erzeugt Workist die Standarddatei **ohne** die Elemente ``, `` und ``, auch wenn das Formular den Schalter für `` als eingeschaltet anzeigt. Speichern Sie die Seite einmal, damit Ihre Auswahl gilt. ::: :::note Welche Felder landen in der Ausgabe? Bei der Workist-XML enthält die Ausgabedatei die Felder, die in [Dokumentenverarbeitung → Kopffelder / Positionzeilenfelder](/docs/channel-configuration/document-processing.md) aktiviert sind, plus die zusätzlichen Felder von dieser Seite. Andere Formate haben einen festen Aufbau, siehe [Ausgabeformate](/docs/output-formats.md). ::: ## Wie die vier Seiten zusammenspielen Ein kompletter Export-Lauf nach dem Abschließen eines Dokuments: 1. **Ausgabedatei** erzeugt die Datei aus den extrahierten Werten. 2. **Upload** bestimmt den Übertragungsweg und ob Workist aktiv überträgt. 3. **AS2** **oder** **SFTP** liefert die Verbindungsdaten für den gewählten Weg. 4. Optional ergänzen **Originaldokument hochladen**, **Originale E-Mail hochladen** und **Zusätzliche Dateien** den Versand um begleitende Dateien. :::tip Faustregel Wenn ein Empfänger eine erwartete Datei nicht erhält, öffnen Sie zuerst das Dokument und lesen Sie die Fehlermeldung (siehe [Zustellfehler](#zustellfehler)). Prüfen Sie dann in dieser Reihenfolge: *Upload → Übertragungsweg* → *Upload → Upload aktivieren* → *Ausgabedatei → Serialisierung aktivieren* → die Verbindungsdaten unter **AS2** oder **SFTP**. ::: ## Zustellfehler {#zustellfehler} Kann Workist die Ergebnisse nicht übertragen, bleibt das Dokument mit einem Fehlerstatus im **Eingang**. Im Dokument erscheint oben ein rotes Banner: „Ihr System hat das Dokument mit der folgenden Antwort abgelehnt:", gefolgt von **Referenz**, **Status** und **Nachricht**. Bei ERP-Integrationen ist das die Antwort Ihres ERP-Systems, bei SFTP und AS2 die technische Fehlermeldung. Workist wiederholt eine Übertragung nur kurz: Den Verbindungsaufbau zu einem SFTP-Server versucht es bis zu zehnmal im Abstand von einer Sekunde, eine AS2-Übertragung dreimal im Abstand von zehn Sekunden. Danach versucht Workist es nicht mehr automatisch. So beheben Sie einen Zustellfehler: | Ursache | Vorgehen | | --- | --- | | Technisches Problem, z. B. Server nicht erreichbar, falsche Zugangsdaten, falscher Zielordner | Beheben Sie die Ursache (ggf. in **SFTP**, **AS2** oder **Upload**). Wählen Sie dann in der Dokumentenliste im Zeilenmenü des Dokuments **Nochmal probieren**. Workist überträgt erneut, mit den aktuellen Einstellungen. | | Ihr System lehnt den Inhalt ab, z. B. eine unbekannte Kundennummer | Klicken Sie im Banner auf **Erneut assistieren**. Das Dokument kehrt in die Assistenz zurück; korrigieren Sie es und schließen Sie es erneut ab. Workist erzeugt die Ausgabedatei dann neu und überträgt sie. | | Die Ausgabedatei konnte nicht erzeugt werden, z. B. wegen eines unbekannten Feldnamens unter **Zusätzliche Kopfzeilendatenfelder** | Korrigieren Sie die Konfiguration unter **Ausgabedatei** und wählen Sie dann **Nochmal probieren**. | **Erneut verarbeiten** (Zeilenmenü) ist etwas anderes: Es gilt nur für Dokumente, die in der Assistenz liegen, und extrahiert sie mit der aktuellen Konfiguration und den aktuellen Stammdaten neu. Ihre bisherigen Änderungen am Dokument gehen dabei verloren. Nutzen Sie es nach Änderungen an der Feldkonfiguration oder an den Stammdaten. ## Häufige Fragen **Kann ein Kanal über AS2 und SFTP gleichzeitig versenden?** Nein. Pro Kanal gibt es genau einen Übertragungsweg. Wenn Sie parallele Wege brauchen, sprechen Sie mit Ihrer Ansprechperson bei Workist. **Was passiert, wenn der SFTP-Server temporär nicht erreichbar ist?** Workist versucht den Verbindungsaufbau etwa zehn Sekunden lang. Ist der Server dann noch nicht erreichbar, schlägt die Übertragung fehl und das Dokument zeigt das Fehlerbanner. Eine spätere automatische Wiederholung gibt es nicht. Sobald der Server wieder erreichbar ist, wählen Sie im Zeilenmenü der betroffenen Dokumente **Nochmal probieren**, siehe [Zustellfehler](#zustellfehler). **Werden Dokumente nachträglich übertragen, die abgeschlossen wurden, während „Upload aktivieren" aus war?** Nein. Workist überträgt sie auch nach dem Einschalten nicht. Die Ausgabedatei können Sie bei Bedarf aus dem Verarbeitungsverlauf des Dokuments herunterladen. **Wo finde ich die generierte Datei zur Kontrolle?** Öffnen Sie das Dokument und klicken Sie oben auf das Symbol **Verarbeitungsverlauf anzeigen**. In der Seitenleiste laden Sie die Datei über **Ergebnis herunterladen** herunter. ## Hilfe und Support Bei Problemen mit Export oder Übertragung halten Sie folgende Informationen bereit: - den **Kanalnamen** und welche Konfiguration es betrifft (AS2, SFTP, Upload, Ausgabedatei), - den Text des **Fehlerbanners** aus dem betroffenen Dokument, - bei AS2: den **AS2 Empfängerendpunkt** und den **AS2 Empfängername**, - bei SFTP: **Host**, **Port** und **Benutzername** und ob Sie den Workist-verwalteten oder Ihren eigenen SFTP-Server nutzen, - bei Inhalt der Ausgabedatei: den genauen **Feldnamen** (technischer Name aus [Dokumentenverarbeitung → Kopffelder](/docs/channel-configuration/document-processing/header-fields.md)) und ein Beispiel, wie der Wert in der Datei aktuell aussieht und wie er aussehen sollte. --- Source: https://docs.workist.com/docs/data-exchange.md # Datenaustausch Zwischen Ihren Systemen und Workist fließen drei Arten von Daten: eingehende Dokumente, Stammdaten und die Ergebnisse der Verarbeitung. Für jede Richtung gibt es mehrere Wege, die Sie kombinieren können, z. B. Stammdaten per SFTP und Ergebnisse per API. ## Dokumente an Workist senden {#dokumente} - **E-Mail:** Jeder Kanal hat eine eigene Eingangsadresse. Siehe [Eingehende Dokumente](/docs/channel-configuration/incoming-documents.md). - **Outlook-Add-in:** Mitarbeitende senden E-Mails und Anhänge direkt aus Outlook an einen Kanal. Siehe [Outlook-Add-in](/docs/data-exchange/outlook-add-in.md). - **API:** Ihr System lädt Dateien per [Dokumenten-API](/docs/api-documentation/document-api.md#hochladen) hoch. - **Workbench:** Benutzer laden Dateien direkt im Kanal hoch. ## Stammdaten an Workist übertragen {#stammdaten} - **[SFTP](/docs/data-exchange/sftp.md#stammdaten):** Ihr System legt Dateien im Ordner `/export` des Workist-SFTP-Servers ab. - **[API](/docs/api-documentation/master-data-api.md):** Ihr System sendet Dateien oder JSON-Daten an die Stammdaten-API. - **Workbench:** Benutzer laden Dateien im [Stammdaten-Hub](/docs/master-data/master-data-hub.md) hoch. - **[Konnektoren](/docs/data-exchange/connectors.md):** Einige ERP-Konnektoren gleichen Stammdaten automatisch ab. ## Ergebnisse an Ihr System übertragen {#ergebnisse} Wie ein Kanal seine Ergebnisse überträgt, legen Sie im Kanal unter **Upload** fest: SFTP, AS2, API, ERP-Integration, manuell oder auf anderem Weg. Neue Kanäle übertragen im Standard per SFTP in den Ordner `/incoming` des Workist-Servers. - **[SFTP](/docs/data-exchange/sftp.md#ergebnisse):** auf den Workist-SFTP-Server oder auf [Ihren eigenen SFTP-Server](/docs/data-exchange/sftp.md#eigener-server). - **AS2:** an Ihren AS2-Empfänger. Siehe [Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md). - **[API](/docs/data-exchange/api.md):** Ihr System ruft die Ergebnisse ab und meldet zurück, ob der Import geklappt hat. - **[Konnektoren](/docs/data-exchange/connectors.md):** Die Ergebnisse gelangen direkt in ausgewählte ERP-Systeme. Für Sage 100, Business Central und SAP ECC/S/4HANA wird dafür eine Erweiterung im ERP installiert. Alle anderen Konnektoren richten Sie in der Workbench ein, ohne Installation im ERP. - **[Webhooks](/docs/data-exchange/webhooks.md):** Workist benachrichtigt Ihr System bei Ereignissen, z. B. wenn ein Dokument abgeschlossen ist. Webhooks ergänzen die API. ![Übersicht Datenaustausch: SFTP, API und Konnektoren](/img/data-exchange.png) --- Source: https://docs.workist.com/docs/data-exchange/sftp.md # Datenaustausch mittels SFTP Server Workist stellt im Standard einen SFTP-Server bereit. Ihr System legt dort Stammdaten ab und holt die Ergebnisse der Dokumentverarbeitung ab. Der Server ist mit Public-Key-Authentifizierung gesichert: Sie erzeugen ein SSH-Schlüsselpaar und hinterlegen den öffentlichen Schlüssel in der Workbench. Alternativ überträgt Workist die Ergebnisse auf Ihren eigenen SFTP-Server, siehe [Eigener SFTP-Server](#eigener-server). ## Verbindungsdetails {#verbindungsdetails} | | | |---|---| | Host | `ftp.workist.com` | | Port | `22` | | Benutzername | Kurzname Ihrer Organisation | | Anmeldung | SSH-Schlüssel, kein Passwort | | RSA-Fingerprint des Servers | `LNe5eKZc2plvysmcr+1sZjfhjn63/K+L+0FtLbGjpXM` (SHA256) | | IP-Adressen des Servers | `63.34.88.144`, `54.220.170.13`, `52.49.47.193` | Dieselben Angaben mit Kopier-Symbol, einschließlich Ihres Benutzernamens, zeigt die Workbench oben auf der Seite **Öffentliche SFTP-Schlüssel** (**Einstellungen** → **Integrationen** → **Öffentliche SFTP-Schlüssel**). Maßgeblich sind die Angaben in der Workbench. Beim ersten Verbinden zeigt Ihr SFTP-Client den Fingerprint des Servers an, z. B. als `SHA256:LNe5eK…`. Vergleichen Sie ihn mit dem Wert oben, bevor Sie die Verbindung bestätigen. ## Zugang einrichten {#zugang} 1. [SSH-Schlüsselpaar erzeugen](#erstellen-eines-ssh-key-pairs). 2. Den öffentlichen Schlüssel in der Workbench unter **Öffentliche SFTP-Schlüssel** hinterlegen. Das dürfen Benutzer mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). Die Schritte mit Screenshots stehen in [Schritt 1: Verbindung herstellen](/docs/implementation-guide/step-1-establish-connection.md#a2-oeffentlichen-schluessel-hinterlegen). 3. [Verbindung testen](#verbindung-testen). Sie können mehrere Schlüssel hinterlegen, z. B. einen je System. Ein gelöschter Schlüssel funktioniert sofort nicht mehr. ## Verzeichnisstruktur {#verzeichnisstruktur} | Verzeichnis | Verwendungszweck | |-------------|-----------------| | `/export` | Stammdaten, die Ihr System für Workist ablegt (aus dem ERP exportiert) | | `/incoming` | Ergebnisse von Workist: Ausgabedatei (z. B. XML), Originaldokument und weitere Dateien | | `/archive` | Für Ihre eigene Ablage. Workist nutzt den Ordner im Standard nicht. | ## Stammdaten ablegen {#stammdaten} - Dateien, die Sie in `/export` oder einen Unterordner davon hochladen, importiert Workist sofort, wenn der Dateiname zu einem Dateinamenmuster einer Lookup-Definition passt. Die Muster legen Sie im [Stammdaten-Hub](/docs/master-data/master-data-hub.md) fest (siehe auch [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md)). Uploads in andere Ordner lösen keinen Import aus. - Jeder Import ersetzt den gesamten Bestand der Lookup-Definition. Legen Sie immer die vollständige Liste ab. - Workist ignoriert Dateien, deren Pfad `.PART`, `.partfile`, `.filepart`, `.ffs_tmp` oder `/Testsystem/` enthält. Wenn Ihr Programm Dateien unter einem vorläufigen Namen hochlädt und danach umbenennt, verwenden Sie eine dieser Endungen. So liest Workist keine halb geschriebene Datei. - Wurden für eine Lookup-Definition in der letzten Stunde mehr als 12 Importe angelegt, überspringt Workist weitere Uploads ohne Meldung (siehe [Grenzen der Stammdaten-API](/docs/api-documentation/master-data-api.md#grenzen)). ## Ergebnisse abholen {#ergebnisse} Wenn ein Kanal die Ergebnisse per SFTP überträgt, legt Workist für jedes abgeschlossene Dokument diese Dateien ab: | Datei | Dateiname | Wann | |---|---|---| | Ausgabedatei (z. B. XML) | `.` | immer | | Originaldokument | `.pdf`, bei E-Rechnungen im XML-Format (XRechnung, CII) `.xml` | wenn **Originaldokument hochladen** aktiv ist (Standard) | | Original-E-Mail | `.eml` | wenn **Originale E-Mail hochladen** aktiv ist und das Dokument per E-Mail kam | | Zusätzliche Dateien | `_file_1.`, `_file_2.` … | wenn **Zusätzliche Dateien** aktiv ist (nur Bestellungen) | `` ist der Name der Ausgabedatei ohne Endung. Dateien mit demselben `` gehören zum selben Dokument. Das Originaldokument ist die PDF-Datei, die Workist aus dem Eingang erzeugt hat; Bilder und Office-Dateien kommen deshalb als `.pdf` an. Ordner: Standard ist `/incoming`. In der **Upload**-Konfiguration des Kanals legen Sie eigene Ordner fest: **Zielordner für generierte Dateien** (Ausgabedatei), **Zielordner für ausgehende Dokumente** (Originaldokument und E-Mail) und **Zielordner für zusätzliche Dateien** (ohne Angabe: der Ordner für ausgehende Dokumente). Details: [Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md). ### So schreibt Workist die Dateien {#schreibweise} - Workist schreibt jede Datei zuerst als `.PART` und benennt sie nach vollständiger Übertragung um. **Ignorieren Sie beim Abholen alle Dateien mit der Endung `.PART`.** - Reihenfolge: Originaldokument, Original-E-Mail, zusätzliche Dateien, zuletzt die Ausgabedatei. Wenn die Ausgabedatei da ist, sind alle Dateien des Dokuments vollständig. Lösen Sie Ihren Import deshalb über die Ausgabedatei aus. - Liegt bereits eine Datei mit demselben Namen im Ordner, überschreibt Workist sie. - Workist löscht abgeholte Dateien nicht. Verschieben oder löschen Sie sie selbst, z. B. nach `/archive`. - Scheitert die Übertragung, zeigt das Dokument in der Workbench eine Fehlermeldung. Nach Behebung der Ursache wählen Sie im Menü der Dokumentzeile **Nochmal probieren**. ## Eigener SFTP-Server {#eigener-server} Statt auf den Workist-Server kann Workist die Ergebnisse auf Ihren SFTP-Server übertragen. Tragen Sie die Verbindung im Kanal unter **Kanal verwalten** → **SFTP** ein und wählen Sie unter **Upload** die Übertragungsart **SFTP**. Stammdaten legen Sie weiterhin auf dem Workist-Server ab oder übertragen sie per [API](/docs/api-documentation/master-data-api.md). - **Host** und **Benutzername** Ihres Servers. - **Port**: Pflicht, auch wenn Ihr Server Port 22 verwendet. - **Hostkey**: der öffentliche Schlüssel Ihres Servers im Format ` `, ohne Hostnamen und ohne Kommentar, z. B. `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…`. Unterstützt: `ssh-rsa`, `ssh-ed25519`, `ecdsa-…` und `ssh-dss`. `ssh-keyscan -t ed25519 ` gibt den Schlüssel mit vorangestelltem Hostnamen aus; übernehmen Sie nur die beiden letzten Teile. Ohne Hostkey prüft Workist die Identität Ihres Servers nicht. - **Passwort**: Mit Passwort meldet sich Workist per Passwort an. Ohne Passwort meldet sich Workist mit einem eigenen RSA-Schlüssel an; den öffentlichen Schlüssel dafür erhalten Sie von Ihrer Ansprechperson bei Workist. - **Zielordner** sind Pfade auf Ihrem Server, Standard `/incoming`. Die Ordner müssen existieren. Workist schreibt auf Ihren Server genauso wie auf den eigenen: erst `.PART`, dann umbenennen, Ausgabedatei zuletzt. ## Verbindung testen {#verbindung-testen} Verwenden Sie `sftp`. Der Workist-Server spricht nur das SFTP-Protokoll, ältere `scp`-Versionen funktionieren deshalb nicht. ```bash sftp -i ~/.ssh/workist_sftp @ftp.workist.com sftp> put stammdaten.csv /export/stammdaten.csv sftp> ls /incoming sftp> get /incoming/ . sftp> bye ``` --- ## Erstellen eines SSH Key Pairs {#erstellen-eines-ssh-key-pairs} Die Workbench erwartet einen RSA-Schlüssel im OpenSSH-Format. Der öffentliche Schlüssel beginnt mit `ssh-rsa`. ### Windows, Linux und Mac ```shell ssh-keygen -t rsa -b 4096 -C "ihre_email@beispiel.com" -f ~/.ssh/workist_sftp ``` Folgen Sie den Eingabeaufforderungen: 1. Optionale Passphrase eingeben. 2. Der Schlüssel wird erzeugt: `~/.ssh/workist_sftp` (privat) und `~/.ssh/workist_sftp.pub` (öffentlich). > **Hinweis:** `ssh-keygen` erfordert, dass OpenSSH installiert ist. Unter Windows 10 und 11 ist es in der Regel vorhanden. ### PuTTY (Windows) 1. PuTTY von der offiziellen Website herunterladen. 2. PuTTY Key Generator öffnen. 3. **RSA** auswählen, **4096** Bits einstellen, auf „Generate" klicken und die Maus über den leeren Bereich bewegen. 4. Den öffentlichen Schlüssel aus dem Feld „Public key for pasting into OpenSSH authorized_keys file" kopieren. 5. Den privaten Schlüssel speichern: **Conversions → Export OpenSSH Key**. ### Verwendung des Key Pairs - Hinterlegen Sie den **öffentlichen Schlüssel** (Dateiendung `.pub`) in der Workbench unter **Öffentliche SFTP-Schlüssel**. - Speichern Sie den **privaten Schlüssel** (ohne Dateiendung) auf dem System, das mit dem SFTP-Server kommuniziert. Geben Sie ihn nicht weiter, auch nicht an Workist. --- Source: https://docs.workist.com/docs/data-exchange/api.md # Datenaustausch mittels Workist API Workist stellt eine REST-API für den Datenaustausch bereit. Über die API: - laden Sie Dokumente in einen Kanal hoch, - rufen Sie verarbeitete Dokumente ab und melden das Ergebnis des Imports in Ihr System zurück, - setzen Sie Absender und Betreff, weisen Dokumente Benutzern zu oder löschen sie, - übertragen Sie Stammdaten. Die API arbeitet nach dem Abrufprinzip: Ihr System fragt Workist nach neuen Ergebnissen. Wenn Workist Ihr System bei Ereignissen benachrichtigen soll, richten Sie zusätzlich [Webhooks](/docs/data-exchange/webhooks.md) ein. Weitere Informationen zur Nutzung der API finden Sie in der [API Dokumentation](/docs/api-documentation.md). ## Lookup-IDs für die API abrufen {#lookup-ids} Jeder Stammdaten-Import gehört zu einer Lookup-Definition. Lookup-Definitionen legen Benutzer mit der Rolle Manager, IT oder Admin im [Stammdaten-Hub](/docs/master-data/master-data-hub.md) selbst an (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). Die ID einer Lookup-Definition finden Sie an zwei Stellen. **Im Stammdaten-Hub:** Die Übersicht zeigt alle Lookup-Definitionen mit ihrer ID. Die ID steht auch auf der Detailseite der Lookup-Definition. **Im Kanal:** 1. Öffnen Sie die Workist-Oberfläche: [https://wb.workist.com/](https://wb.workist.com/) 2. Wählen Sie den Kanal, öffnen Sie rechts oben das 3-Punkt-Menü und klicken Sie auf „Kanal verwalten". 3. Wählen Sie in der Liste den Punkt „Stammdaten". 4. Unter jeder ausgewählten Lookup-Definition steht ihre ID. Ein Klick auf die ID kopiert sie in die Zwischenablage. --- Source: https://docs.workist.com/docs/data-exchange/webhooks.md # Webhooks Ein Webhook ruft eine Adresse in Ihrem System auf, sobald bei einem Dokument ein bestimmtes Ereignis eintritt, z. B. wenn es abgeschlossen ist. Ihr System muss die [Dokumenten-API](/docs/api-documentation/document-api.md) dann nicht regelmäßig abfragen. Webhooks gibt es für Bestellungen, Auftragsbestätigungen, Angebotsanfragen, Rechnungen und Lieferscheine. ## Voraussetzungen {#voraussetzungen} - Ein Workbench-Konto mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). - Eine Adresse in Ihrem System, die aus dem Internet erreichbar ist und `POST`-Anfragen mit JSON annimmt. Verwenden Sie HTTPS. ## Webhook einrichten {#einrichten} 1. Klicken Sie in der linken Navigationsleiste auf **Einstellungen** und wählen Sie **Integrationen**. 2. Wählen Sie in der Unter-Navigation unter **Workflow-Tools** den Eintrag **Webhooks**. 3. Klicken Sie auf **Webhook hinzufügen**. 4. Füllen Sie die Felder aus (siehe Tabelle) und klicken Sie auf **Webhook erstellen**. | Feld | Bedeutung | |---|---| | **Name** | Name zur Unterscheidung in der Liste. | | **Aktiviert** | Nur aktivierte Webhooks werden aufgerufen. | | **URL** | Adresse Ihres Empfängers. Workist sendet `POST`-Anfragen mit JSON. | | **Auth-Typ** | Präfix des Header-Werts, z. B. `Bearer`. Optional. | | **Auth-Zugangsdaten** | Geheimer Wert für den Header, z. B. ein Token. | | **Auth-Header** | Name des Headers. Standard: `Authorization`. | | **Benutzername** | Benutzername für HTTP Basic Auth. Wenn gesetzt, gilt Basic Auth statt des Headers oben. | | **Passwort** | Passwort für HTTP Basic Auth. | | **Ereignisse** | Ereignisse, die den Webhook auslösen. Mindestens eines. | | **Unfertige Daten anzeigen** | `data` enthält die Dokumentdaten auch vor dem Abschluss. | | **Kanäle** | Kanäle je Dokumenttyp. Keine Auswahl: alle Kanäle aller Typen. | Die Liste zeigt alle Webhooks mit Status, URL und Anzahl der Ereignisse. Über das Stift-Symbol bearbeiten Sie einen Webhook, über das Papierkorb-Symbol löschen Sie ihn. **Auth-Zugangsdaten** und **Passwort** bleiben nach dem Speichern verborgen; lassen Sie die Felder beim Bearbeiten leer, bleibt der gespeicherte Wert erhalten. ### Authentifizierung {#authentifizierung} Workist sendet bei jedem Aufruf genau einen Header zur Authentifizierung: - **Basic Auth:** Wenn **Benutzername** ausgefüllt ist, sendet Workist `Authorization: Basic `. - **Eigener Header:** Sonst sendet Workist den Header aus **Auth-Header** (Standard `Authorization`) mit dem Wert ` `, z. B. `Authorization: Bearer abc123`. Ohne **Auth-Typ** steht nur der Wert aus **Auth-Zugangsdaten** im Header. Workist signiert die Anfragen nicht. Prüfen Sie den Header in Ihrem System und nehmen Sie nur Anfragen über HTTPS an. ### Kanäle {#kanaele} - Ohne Auswahl gilt der Webhook für alle Kanäle aller Dokumenttypen. - Wählen Sie Kanäle aus, gilt der Webhook nur für diese Kanäle. Dokumenttypen, bei denen Sie keinen Kanal ausgewählt haben, lösen ihn dann nicht aus. ## Ereignisse {#ereignisse} Der Name eines Ereignisses setzt sich aus Dokumenttyp und Ereignis zusammen, z. B. `order.finished` oder `invoice.assistance_needed`. | Ereignis | Name | Bedeutung | Wird gesendet für | |---|---|---|---| | **Unterstützung benötigt** | `assistance_needed` | Das Dokument wartet auf Bearbeitung in der Workbench. | alle Dokumenttypen | | **Unterstützt** | `assisted` | Ein Benutzer hat die Bearbeitung abgeschlossen oder das Dokument verworfen. | alle Dokumenttypen | | **Vor der Ausgabeerzeugung** | `before_generate_output` | Workist beginnt, die Ausgabedatei zu erzeugen. | alle Dokumenttypen | | **Ausgabe erzeugt** | `output_generated` | Die Ausgabedatei ist erzeugt. | alle Dokumenttypen | | **Vor dem Senden der Ausgabe** | `before_send_output` | Workist beginnt mit der Übertragung. | Bestellungen, Angebotsanfragen | | **Ausgabe gesendet** | `output_sent` | Die Übertragung ist abgeschlossen. | derzeit nie | | **Abgeschlossen** | `finished` | Die Verarbeitung ist beendet: abgeschlossen, verworfen oder in einen anderen Kanal weitergeleitet. | alle Dokumenttypen | | Dokumenttyp | Präfix | |---|---| | Bestellungen | `order.` | | Auftragsbestätigungen | `order_confirmation.` | | Angebotsanfragen | `rfq.` | | Rechnungen | `invoice.` | | Lieferscheine | `delivery_note.` | Hinweise: - **Ausgabe gesendet** wird derzeit nicht ausgelöst. Verwenden Sie **Abgeschlossen** und prüfen Sie `data.status`: `DELIVERED` heißt, Workist hat das Ergebnis per SFTP, AS2 oder ERP-Integration übertragen. - **Abgeschlossen** kommt auch für verworfene Dokumente (`data.status` ist dann `DISCARDED`). Schlägt die Übertragung fehl, sendet Workist kein **Abgeschlossen**. - Für die meisten Integrationen genügt **Abgeschlossen**. **Unterstützung benötigt** eignet sich, um Mitarbeitende auf offene Dokumente hinzuweisen. ## Inhalt der Anfrage {#inhalt} Workist sendet eine `POST`-Anfrage mit `Content-Type: application/json`: | Feld | Inhalt | |---|---| | `timestamp` | Zeitpunkt des Ereignisses als Unix-Zeitstempel in Sekunden. | | `event` | Name des Ereignisses, `.`, z. B. `order.finished`. | | `user` | Derzeit immer ein leeres Objekt. | | `data` | Das Dokument im selben Format wie in der [Dokumenten-API](/docs/api-documentation/document-api.md). Bei Rechnungen nur `{"id": ...}`. | | `payload` | Für die auswählbaren Ereignisse immer ein leeres Objekt. | Beispiel (gekürzt): ```json { "timestamp": 1760000000, "event": "order.finished", "user": {}, "data": { "id": "3f2a9c1e-7d1b-4c55-9a43-0e6f1b2c8d90", "channel": "8b1d2f40-5c3e-4a7a-9e21-6d4c3b2a1f00", "status": "FINISHED", "subject": "Bestellung 4500012345", "finished_at": "2026-10-09T08:15:42Z", "workbench_url": "https://wb.workist.com/...", "data": { "order_number": "4500012345", "line_items": [] } }, "payload": {} } ``` - `data.data` ist leer (`{}`), solange das Dokument weder bearbeitet noch abgeschlossen ist. Aktivieren Sie **Unfertige Daten anzeigen**, wenn Sie bei frühen Ereignissen schon die Zwischenstände brauchen. - Bei **Rechnungen** enthält `data` nur die ID. Rufen Sie die Rechnung mit `GET /invoices/{id}` über die [Dokumenten-API](/docs/api-documentation/document-api.md) ab. - Links zu Dateien in `data` sind höchstens 30 Minuten gültig. ## Zustellung und Fehler {#zustellung} - Workist sendet Webhooks im Hintergrund, kurz nach dem Ereignis. Die Reihenfolge mehrerer Ereignisse ist nicht garantiert. Ordnen Sie Ereignisse über `timestamp` und `data.id` zu. - **Nicht erreichbar:** Kommt keine Verbindung zustande, versucht Workist es bis zu zehnmal erneut, mit wachsendem Abstand von 1, 2, 4 bis 512 Sekunden (zusammen etwa 17 Minuten). Danach verwirft Workist das Ereignis. - **Fehlerantwort:** Antwortet Ihr System mit einem Fehlerstatus (`4xx` oder `5xx`), wiederholt Workist den Aufruf nicht. - Die Workbench zeigt kein Protokoll der Aufrufe. Wenn Ihr System ein Ereignis verpasst hat, holen Sie die Dokumente über die [Dokumenten-API](/docs/api-documentation/document-api.md#ablauf) ab, z. B. mit `finished=true&imported=false`. - Antworten Sie schnell mit einem `2xx`-Status und verarbeiten Sie die Daten danach. Verarbeiten Sie Ereignisse so, dass ein doppelter Aufruf keinen Schaden anrichtet. --- Source: https://docs.workist.com/docs/data-exchange/outlook-add-in.md # Outlook-Add-In Mit dem Workist-Add-In für Microsoft Outlook schicken Ihre Mitarbeitenden eine geöffnete E-Mail mit einem Klick an einen Workist-Kanal, statt sie weiterzuleiten. Arbeitet in Ihrem Unternehmen ein Inbox-Agent, zeigt das Add-In außerdem seinen Antwortentwurf zur E-Mail. ## Was Benutzer in Outlook tun - **E-Mail an Workist senden:** Der Benutzer öffnet eine E-Mail, öffnet das Add-In und wählt einen Kanal. Workist verarbeitet die E-Mail mit ihren Anhängen so, als wäre sie an die E-Mail-Adresse des Kanals geschickt worden, siehe [Eingehende Dokumente](/docs/channel-configuration/incoming-documents.md). Enthält die E-Mail nichts, was Workist verarbeiten kann, legt Workist kein Dokument an. - **Status sehen:** Für eine bereits übergebene E-Mail zeigt das Add-In die entstandenen Dokumente mit Kanal, Status und Link in die Workbench. Unterstützt werden Kanäle für Bestellungen, Rechnungen, Auftragsbestätigungen, Preisanfragen und Lieferscheine. ## Add-In anlegen Add-Ins legen Benutzer mit den Rollen **IT** und **Admin** an, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md#permissions). 1. Öffnen Sie **Einstellungen** → **Integrationen** und wählen Sie links unter **Workflow-Tools** den Eintrag **Outlook-Add-Ins**. 2. Klicken Sie auf **Add-In hinzufügen** und füllen Sie das Formular aus: | Feld | Bedeutung | | --- | --- | | **Name** | Name des Add-Ins, wie er in Outlook erscheint. | | **Kanalmodus** | Welche Kanäle das Add-In anbietet, siehe [Kanalmodus](#kanalmodus). | | **Bestellungskanäle** | Bestellkanäle, die das Add-In anbietet. Nur bei den Kanalmodi **Add-In** und **Manuell**. | | **Rechnungskanäle** | Rechnungskanäle, die das Add-In anbietet. Nur bei den Kanalmodi **Add-In** und **Manuell**. | | **Bestätigungskanäle für Aufträge** | Kanäle für Auftragsbestätigungen, die das Add-In anbietet. Nur bei den Kanalmodi **Add-In** und **Manuell**. | | **Kanäle für Angebotsanfragen** | Kanäle für Preisanfragen, die das Add-In anbietet. Nur bei den Kanalmodi **Add-In** und **Manuell**. | | **Lieferschein-Kanäle** | Lieferschein-Kanäle, die das Add-In anbietet. Nur bei den Kanalmodi **Add-In** und **Manuell**. | 3. Klicken Sie auf **Add-in Erstellen**. 4. Laden Sie über das Download-Symbol in der Zeile des Add-Ins die Manifest-Datei (XML) herunter. ### Kanalmodus {#kanalmodus} | Kanalmodus | Was Outlook-Benutzer sehen | Neues Manifest nötig? | | --- | --- | --- | | **Alle Kanäle** | Alle Kanäle, die der Workist-Benutzer mit der E-Mail-Adresse des Outlook-Postfachs sieht (nach seinen Teams). | Nein, Kanaländerungen wirken sofort. | | **Add-In** | Die im Add-In ausgewählten Kanäle. Workist lädt sie beim Öffnen des Add-Ins. | Nein, Kanaländerungen wirken sofort. | | **Manuell** | Die im Add-In ausgewählten Kanäle. Sie stehen fest in der Manifest-Datei. | Ja, nach jeder Änderung der Kanäle. | Beim Modus **Alle Kanäle** braucht jeder Outlook-Benutzer ein Workist-Konto mit derselben E-Mail-Adresse, siehe [Teams und Sichtbarkeit](/docs/administration/users-and-roles.md#teams). :::warning Manifest-Datei vertraulich behandeln Die Manifest-Datei enthält einen Zugangsschlüssel für Ihr Workist-Konto. Geben Sie sie nur an die Personen weiter, die das Add-In verteilen. Wenn Sie das Add-In löschen, wird der Schlüssel ungültig und das verteilte Add-In funktioniert nicht mehr. ::: ## Add-In in Microsoft 365 verteilen Das Add-In verteilt ein Administrator Ihres Microsoft-365-Mandanten: 1. Öffnen Sie im Microsoft 365 Admin Center **Einstellungen** → **Integrierte Apps**. 2. Wählen Sie **Benutzerdefinierte Apps hochladen**, als App-Typ das Office-Add-In, und laden Sie die Manifest-Datei hoch. 3. Wählen Sie die Benutzer oder Gruppen aus, die das Add-In erhalten sollen, und schließen Sie die Bereitstellung ab. Bis das Add-In in Outlook erscheint, kann es einige Stunden dauern. Workist empfiehlt die Verteilung an die ganze Organisation oder an alle betroffenen Teams. **Änderungen:** Bei jedem Speichern erhöht Workist die Version des Add-Ins. Wenn Sie den Namen, den Kanalmodus oder im Modus **Manuell** die Kanäle ändern, laden Sie die neue Manifest-Datei herunter und aktualisieren Sie die App im Microsoft 365 Admin Center. ## Antwortentwürfe von Inbox-Agenten {#inbox-agents} :::info Zusatzleistung Diese Funktion ist nur verfügbar, wenn sie in Ihrem Workist-Vertrag enthalten ist (**Inbox-Agenten**). Ihre Ansprechperson bei Workist schaltet sie für Sie frei. ::: Bearbeitet ein Inbox-Agent die E-Mails eines Postfachs, zeigt das Add-In zur geöffneten E-Mail das Ergebnis des Agenten: einen Antwortentwurf oder eine interne Zusammenfassung. Der Benutzer kann den Entwurf bearbeiten und übersetzen lassen, Dateien anhängen oder entfernen, daraus einen Antwortentwurf in Outlook erstellen oder die Antwort direkt senden, das Ergebnis bewerten und dem Agenten Rückfragen zur E-Mail stellen. Legt ein Manager oder Admin einen Inbox-Agenten an, erzeugt Workist dafür automatisch ein Add-In mit dem Namen des Agenten und dem Kanalmodus **Add-In**. Laden Sie dessen Manifest-Datei herunter und verteilen Sie es wie oben beschrieben. Wenn Sie dieses Add-In löschen, löscht Workist auch den Agenten. Mehr zu Agenten unter [Agenten](/docs/agents.md). --- Source: https://docs.workist.com/docs/data-exchange/connectors.md # Konnektoren für ERP-Systeme Ein Konnektor verbindet Workist direkt mit Ihrem ERP-System. Workist übernimmt Stammdaten aus dem ERP und legt verarbeitete Belege dort an. Für Systeme ohne Konnektor tauschen Sie Stammdaten und Ergebnisse per [SFTP](/docs/data-exchange/sftp.md) oder [API](/docs/data-exchange/api.md) aus. ## Konnektoren mit Installation im ERP-System Für diese Systeme wird eine Erweiterung in Ihrem ERP-System installiert. - **[Sage 100](/docs/data-exchange/connectors/sage-100.md)**: Sie installieren die Workist API-Erweiterung in Sage 100. Workist liest darüber Stammdaten und legt Verkaufsbelege an. Ab Version 8 der Erweiterung auch Preisprüfung, offene Angebote und die ERP-Funktionen der Agenten. - **[Microsoft Dynamics 365 Business Central](/docs/data-exchange/connectors/business-central.md)**: Die App „Workist Integrator“ sendet Stammdaten an Workist und übernimmt abgeschlossene Belege, zum Beispiel als Verkaufsaufträge. - **[SAP ECC und SAP S/4HANA](/docs/data-exchange/connectors/sap.md)**: Ein ABAP-Paket, das unser Partner Syncwork AG in Ihrem SAP installiert, sendet Stammdaten an Workist und legt abgeschlossene Bestellungen als Kundenaufträge an. Auch für SAP R/3. ## Konnektoren ohne Installation im ERP-System Bei diesen Systemen verbindet sich Workist mit der Schnittstelle Ihres ERP-Systems. In Ihrem ERP wird nichts installiert. Die Verbindung richten Sie in der Workbench ein, siehe [Was alle Konnektoren gemeinsam haben](#common-behaviour). - **[SAP Business One](/docs/data-exchange/connectors/sap-business-one.md)**: liest Geschäftspartner und Artikel, legt Bestellungen als Kundenaufträge an. - **[Microsoft Dynamics 365 Finance & Operations](/docs/data-exchange/connectors/dynamics-365-finance-operations.md)**: liest Debitoren und freigegebene Produkte, legt Verkaufsaufträge und Verkaufsangebote an. - **[microtech büro+](/docs/data-exchange/connectors/microtech-buero-plus.md)**: liest Adressen, Artikel und offene Angebote, legt Bestellungen und Anfragen als Vorgänge an. - **[ORDAT.ERP](/docs/data-exchange/connectors/further-connectors.md#ordat-erp)**: liest Kunden, Artikel und Einheiten, legt Aufträge und Angebote an. - **[NetSuite](/docs/data-exchange/connectors/further-connectors.md#netsuite)**: liest Kunden und Artikel, legt Sales Orders, Estimates und Vendor Bills an. - **[QuickBooks Desktop](/docs/data-exchange/connectors/further-connectors.md#quickbooks-desktop)**: liest Kunden und Artikel, legt Sales Orders an. QuickBooks Online wird nicht unterstützt. - **[OrderWise](/docs/data-exchange/connectors/further-connectors.md#orderwise)**: legt Sales Orders und Quotes an und prüft Einzelpreise gegen OrderWise. - **[Weclapp](/docs/data-exchange/connectors/further-connectors.md#weclapp)**: liest Kunden und Artikel, legt Kundenaufträge an und übernimmt E-Mails aus Weclapp-Tickets. - **[Sage 200 Professional](/docs/data-exchange/connectors/further-connectors.md#sage-200-professional)**: Sage 200 für Großbritannien. ## Was alle Konnektoren gemeinsam haben {#common-behaviour} Dieser Abschnitt gilt für die Konnektoren ohne Installation im ERP-System. Für die übrigen Konnektoren steht der Ablauf auf ihren eigenen Seiten. **Einrichtung in der Workbench** Benutzer mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)) richten die Verbindung unter **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** ein: beim gewünschten System auf **Verbinden** klicken, die Zugangsdaten eintragen und die Kanäle auswählen, deren Belege in das ERP-System übertragen werden. Für die ausgewählten Kanäle stellt Workist die Übertragung auf die ERP-Integration um und schaltet die Ausgabedatei ab. Die Option „Upload aktivieren“ in der Upload-Konfiguration des Kanals muss eingeschaltet bleiben, sonst überträgt Workist nichts. **Stammdaten** - Workist liest die Stammdaten einmal täglich aus dem ERP-System. Die Uhrzeit steht auf der Seite des jeweiligen Konnektors. - Mit **Stammdaten Update starten** auf der Seite der Integration stoßen Sie einen Abgleich sofort an. - Workist schreibt die Stammdaten in die Stammdaten-Lookups, die den verbundenen Kanälen zugeordnet sind (siehe [Master Data Hub](/docs/master-data/master-data-hub.md)). Jeder Lauf ersetzt den bisherigen Stand. - Neu angelegte Kunden und Artikel kennt Workist ab dem nächsten Lauf. **Belege** - Sobald ein Beleg abgeschlossen ist, automatisch oder nach Ihrer Bearbeitung, legt Workist ihn im ERP-System an. - Die Belegnummer aus dem ERP-System steht danach als Referenz am Beleg in der Workbench. Sie können in der Belegliste danach suchen. - Workist legt Belege neu an. Bestehende Belege im ERP-System ändert Workist nur dort, wo es die Seite des Konnektors beschreibt, zum Beispiel wenn ein Angebot in einen Auftrag umgewandelt wird. **Fehler** Lehnt das ERP-System einen Beleg ab, erscheint er wieder unter den offenen Belegen. Am Beleg steht „Ihr System hat das Dokument mit der folgenden Antwort abgelehnt:“ mit der Meldung des ERP-Systems. Workist versucht die Übertragung nicht automatisch erneut. Beheben Sie die Ursache, zum Beispiel fehlende Stammdaten im ERP-System, öffnen Sie den Beleg mit **Erneut assistieren**, korrigieren Sie ihn bei Bedarf und schließen Sie ihn wieder ab. Workist überträgt ihn dann neu. ## Fragen Für Details zur Anbindung Ihres ERP-Systems wenden Sie sich an Ihre Ansprechperson bei Workist oder schreiben Sie an [support@workist.com](mailto:support@workist.com). --- Source: https://docs.workist.com/docs/data-exchange/connectors/sage-100.md # Sage 100 Konnektor ## Überblick Die Anbindung setzt eine unterstützte Sage 100-Version voraus. Danach sind es zwei Dinge: Sie richten den Zugang in Ihrer Sage 100 ein, und Sie teilen uns drei Angaben mit, die wir bei Workist hinterlegen. **[Voraussetzung an Ihre Sage 100](#unterstützte-sage-100-versionen)** Sage 100 der Sage GmbH (Deutschland, Österreich, Schweiz), ab Version 9.0.8, sowie eine Lizenz **3rd Party Gateway**. **[In Ihrer Sage 100 einzurichten](/docs/data-exchange/connectors/sage-100-installation.md)** | Schritt | Wo | | --- | --- | | Sage Connectivity Gateway verbinden | Sage Server Manager → **Externe API** | | Workist API-Erweiterung installieren | AppDesigner (Metadatenimport) | | Berechtigungen und Workist-Felder einspielen | AppDesigner bzw. SQL Server Management Studio | | Datenbanken für die Konnektivität freigeben | Sage 100 Administrator | | Workist Client-ID als Benutzer eintragen und berechtigen | Sage 100 Administrator | | Applikationsserver neu starten | Sage Server Manager | Die vollständige Schritt-für-Schritt-Anleitung mit Downloads, Client-ID, Berechtigungen und Fehlerbehebung steht unter [Sage 100 – Installation](/docs/data-exchange/connectors/sage-100-installation.md). **[Angaben, die Workist von Ihnen benötigt](#angaben-für-die-workist-konfiguration)** | Angabe | Wo Sie sie finden | | --- | --- | | **EntitlementID** | Sage Server Manager → **Externe API** → **Konfiguration** | | **DataSet** | Sage 100 Administrator | | **Belegart** | Sage 100 Warenwirtschaft | | **Version der Workist API-Erweiterung** | AppDesigner | Mit Version 8 der Erweiterung kommen Preisprüfung, offene Angebote, Bestellungen mit Angebotsbezug und die ERP-Funktionen der Agenten dazu – siehe [Funktionen ab Version 8](#funktionen-ab-version-8-der-erweiterung). ## Unterstützte Sage 100-Versionen Der Konnektor arbeitet mit der **Sage 100 der Sage GmbH** – der Ausprägung für Deutschland, Österreich und die Schweiz. Unterstützt werden diese Versionen: | Sage 100-Version | Unterstützt | | --- | --- | | 9.0.11 | ja | | 9.0.10 | ja | | 9.0.9 | ja | | 9.0.8 | ja | | 9.0.7 und älter | nein | Die [Workist API-Erweiterung](/docs/data-exchange/connectors/sage-100-installation.md#downloads) enthält für jede dieser Versionen ein eigenes Paket. Installiert wird ausschließlich das Paket, das zu Ihrer Sage 100-Version passt – die Pakete sind nicht untereinander austauschbar. Welche Version bei Ihnen im Einsatz ist, nennt Ihnen Ihr Sage 100-Partner. Läuft Ihre Sage 100 auf einer älteren Version, ist ein Update auf mindestens 9.0.8 Voraussetzung für die Anbindung. Ist Ihre Version hier nicht aufgeführt, sprechen Sie uns an – wir prüfen die Verfügbarkeit des passenden Pakets. :::note Berechtigungen vor Version 9.0.9 Ab Version 9.0.9 werden die Berechtigungen beim Metadatenimport erzeugt. In früheren Versionen müssen sie über ein mitgeliefertes SQL-Skript eingespielt werden – siehe [Installation, Schritt 4](/docs/data-exchange/connectors/sage-100-installation.md#schritt-4-berechtigungen-einspielen). ::: :::warning Andere Produkte mit dem Namen „Sage 100" Sage vertreibt in anderen Märkten eigenständige Produkte unter demselben Namen – etwa Sage 100 in den USA (früher Sage MAS 90 bzw. MAS 200) oder Sage 100 Comptabilité und Gestion Commerciale in Frankreich. Diese haben ein anderes Datenmodell und eine eigene Versionszählung. Mit ihnen ist der Workist Sage 100-Konnektor **nicht** kompatibel. ::: ## Einrichtung in Ihrer Sage 100 Damit Workist Daten aus Ihrer Sage 100 lesen und Belege anlegen kann, werden zusätzliche API-Endpunkte in Sage 100 installiert. Die Einrichtung nimmt in der Regel Ihre IT oder Ihr Sage 100-Partner vor, meist gemeinsam mit Workist. Planen Sie dafür ein Wartungsfenster ein: Zum Abschluss muss der Applikationsserver neu gestartet werden. Alle Schritte, die Downloads und die Fehlerbehebung finden Sie unter [Sage 100 – Installation](/docs/data-exchange/connectors/sage-100-installation.md). ## Angaben für die Workist-Konfiguration Damit Workist Ihre Sage 100 ansprechen kann, brauchen wir drei Angaben von Ihnen. Alle drei entnehmen Sie Ihrer Sage 100 – an der Schnittstelle selbst müssen Sie nichts einrichten. Dazu kommt die Version der installierten Workist API-Erweiterung. | Angabe | Wo Sie sie finden | Wofür | | --- | --- | --- | | **EntitlementID** | Server Manager → **Externe API** → **Konfiguration** | Identifiziert Ihre Installation im Connectivity Gateway | | **DataSet** | Sage 100 Administrator, Statusleiste oder Anmeldedialog | Datenbankname, „;" und Mandantennummer, z. B. `WAWI_DB;1` – bestimmt Datenbank und Mandant | | **Belegart** | Sage 100 Warenwirtschaft | Bestimmt, welche Belegart Workist anlegt | | **Version der Erweiterung** | AppDesigner | Bestimmt, welche Felder und Funktionen Workist nutzt | ### EntitlementID Die EntitlementID identifiziert Ihre Sage 100-Installation gegenüber dem Connectivity Gateway. Sie entsteht bei der Lizenzierung des 3rd Party Gateway und ist im Sage 100 Server Manager unter **Externe API** → **Konfiguration** einsehbar. Im selben Dialog legen Sie fest, an welchen Applikationsserver Anfragen weitergeleitet werden, und hinterlegen bei Bedarf einen Proxy. ### DataSet Das DataSet bestimmt, in welcher Datenbank und in welchem Mandanten Ihrer Sage 100 Workist liest und schreibt. Es besteht aus dem Datenbanknamen, einem Semikolon und der Mandantennummer – etwa `WAWI_DB;1`. Schreiben Sie den Datenbanknamen genau so, wie er in Sage 100 steht, ohne Leerzeichen. Datenbankname und Mandantennummer finden Sie an diesen Stellen: - **Statusleiste** – ganz unten im Hauptfenster der geöffneten Sage 100 - **Anmeldedialog** – bei der Auswahl des Mandanten steht die Mandantennummer direkt vor dem Firmennamen - **Sage 100 Administrator** – im linken Baum unter **Mandanten** Eine Verbindung arbeitet in genau einem Mandanten. Dessen Datenbank muss im Sage 100 Administrator ausdrücklich für die Konnektivität freigegeben sein – siehe [Installation, Schritt 6](/docs/data-exchange/connectors/sage-100-installation.md#schritt-6-datenbanken-freigeben). Für Test- und Produktivdatenbank legt Workist jeweils eine eigene Verbindung an. ### Belegart Welche Belegart Workist anlegt, legen Sie fest – in der Regel Ihr Vertrieb oder Ihre Auftragsbearbeitung. Technisch wird sie über ein Kennzeichen angesprochen. Anlegen lassen sich ausschließlich **Verkaufs**-Initialbelegarten; Einkaufsbelege wie eine Bestellung an einen Lieferanten sind nicht möglich. Im Standard von Sage 100 sind das diese Belegarten: | Kennzeichen | Bezeichnung | | --- | --- | | `VFR` | Rechnung | | `VLL` | Lieferschein | | `VPA` | Angebot | | `VPM` | Musterbeleg | | `VSD` | Direktrechnung | | `VSL` | Sofortrechnung | | `VSS` | Sofortauftrag | | `VVA` | Auftragsbestätigung | Maßgeblich ist, welche Belegarten in Ihrer Sage 100 konfiguriert sind – auch selbst angelegte Initialbelegarten mit eigenem Kennzeichen lassen sich verwenden. Geben Sie keine Belegart an, legt Workist **Sofortaufträge** (`VSS`) an. Sie können auch eine eigene Belegart anlegen – etwa mit dem Kennzeichen `VVK` und der Bezeichnung „Workist-Bestellung" –, damit Belege aus Workist in Sage 100 auf einen Blick erkennbar sind. Hinterlegt wird in Workist immer das **Kennzeichen**, nicht die Bezeichnung. Gibt es das Kennzeichen im Mandanten nicht, lehnt Sage 100 den Beleg mit der Meldung ab, der Wert sei für das Feld Belegtyp-Kennzeichen nicht gültig. Statt direkt eine Auftragsbestätigung anzulegen, kann sich auch ein wirkungsloser Vorbeleg lohnen, den Ihre Auftragsbearbeitung prüft und dann in eine Auftragsbestätigung übernimmt. Ändern Sie die Belegart nachträglich, prüfen Sie am nächsten übertragenen Beleg, ob die Änderung greift. Eine Verbindung legt genau eine Belegart an. Sollen etwa Bestellungen und Preisanfragen als unterschiedliche Belegarten ankommen, richtet Workist dafür getrennte Verbindungen mit jeweils eigenen Kanälen ein. Die vollständige Übersicht führt Sage in der Dokumentation der Beleg-API: Beleg API – Sage Dokumentation ↗ ### Version der Workist API-Erweiterung Welche Version der Erweiterung installiert ist, zeigt der AppDesigner. Workist hinterlegt sie in der Verbindung (*Sage 100 API Version*: Version 5, 7 oder 8). Ohne Angabe arbeitet Workist wie mit Version 5. | Version | Was Workist zusätzlich nutzt | | --- | --- | | 5 | Grundumfang: Stammdaten lesen, Verkaufsbelege anlegen | | 7 | Die Lieferbedingung aus dem Dokument (Incoterm) wird an den Beleg übergeben | | 8 | Alle [Funktionen ab Version 8](#funktionen-ab-version-8-der-erweiterung) | Workist liest die Version nicht selbst aus Ihrer Sage 100. Geben Sie uns nach einem Update der Erweiterung Bescheid, damit wir die Version in der Verbindung anpassen. :::note Lieferbedingung ab Version 7 Mit Version 7 übergibt Workist die Lieferbedingung aus dem Dokument in das Feld **Lieferbedingung** des Belegs. Sage 100 nimmt dort nur Lieferbedingungen an, die in Ihrem Mandanten angelegt sind. Prüfen Sie das an einem Testbeleg, bevor die Version umgestellt wird. ::: ### Angebots-Belegart Für den Abgleich mit [offenen Angeboten](#offene-angebote) liest Workist die Angebote einer Belegart, im Standard `VPA` (Angebot). Verwenden Sie für Angebote ein eigenes Kennzeichen, hinterlegt Workist dieses (*Sage 100 Offer Document Type*). Benötigt Version 8 der Erweiterung. ## Funktionen ab Version 8 der Erweiterung Mit Version 8 der [Workist API-Erweiterung](/docs/data-exchange/connectors/sage-100-installation.md#downloads) liest Workist zusätzlich Preise, Lagerbestände und Verkaufsbelege aus Ihrer Sage 100. In Workist stehen die folgenden Funktionen nur zur Verfügung, wenn die Verbindung auf Version 8 steht. Bei älteren Versionen sind die zugehörigen Einstellungen ausgegraut. | Funktion | Einstellung in der Verbindung | Im Standard | | --- | --- | --- | | [Preisprüfung mit der Sage-Preisfindung](#preisprüfung-mit-der-sage-preisfindung) | *Check order prices against Sage 100*, *Compare against* | aus | | [Offene Angebote](#offene-angebote) | *Sage 100 Offer Document Type* | `VPA` | | [Bestellungen mit Angebotsbezug](#bestellungen-mit-angebotsbezug) | Feld Angebotsnummer im Kanal | – | | [Hinweistext als Belegmemo](#hinweistext-als-belegmemo) | Feld Hinweistext (*Note Text*) im Kanal | – | | [Belege als Entwurf](#belege-als-entwurf) | *Save documents in Sage 100 as drafts* | aus | | [ERP-Funktionen der Agenten](#erp-funktionen-der-agenten) | *Allow agentic writes* (nur für das Schreiben) | Schreiben aus | ### Preisprüfung mit der Sage-Preisfindung Workist fragt für jede Bestellposition den Preis ab, den Sage 100 für diesen Kunden, Artikel, diese Menge und Mengeneinheit ermittelt – mit Ihren Preislisten, Staffelpreisen und Kundenrabatten. Gegen diesen Preis prüft Workist den bestellten Einzelpreis. Ändert jemand in der Workbench Menge, Einheit, Artikel oder Kunde, fragt Workist den Preis erneut ab. - **Compare against** legt fest, womit verglichen wird: mit dem Einzelpreis vor Rabatt (Standard) oder mit dem Nettopreis nach Kundenrabatt. - Im Kanal muss die Einzelpreis-Prüfung eingeschaltet sein. - Kann Sage 100 eine Position nicht bepreisen, etwa weil der Artikel fehlt, prüft Workist diese Position ohne Zielpreis. ### Offene Angebote Workist liest mit der Stammdatenaktualisierung alle offenen Angebote der [Angebots-Belegart](#angebots-belegart), über alle Kunden. Jede Artikelposition wird ein Eintrag für den [Angebotsabgleich](/docs/channel-configuration/document-processing/matching.md): - Angebotsnummer als Belegjahr und -nummer, z. B. `2026-30006` - Kunde, Angebotsdatum - Position, Artikel, Bezeichnung, Menge und Mengeneinheit Offen ist ein Angebot, solange in Sage 100 nichts daraus entstanden ist. Ein Angebot, das in einen Auftrag übernommen wurde, liest Workist nicht mehr. Abgelehnte oder abgelaufene Angebote kann Workist nicht erkennen, weil Sage 100 den Angebotsstatus und das Gültigkeitsdatum über die Schnittstelle nicht bereitstellt. Ein Angebot ohne Ablaufdatum gilt in Workist ab dem Angebotsdatum. Workist liest die Angebote nur, wenn in einem Kanal der Verbindung eine Angebots-Stammdatenliste eingerichtet ist. ### Bestellungen mit Angebotsbezug Ist im Kanal das Feld **Angebotsnummer** eingerichtet und nennt eine Bestellung ein offenes Angebot aus Sage 100, legt Workist den Beleg mit Bezug auf dieses Angebot an. Sage 100 führt Angebot und Auftrag dann im selben Vorgang und setzt das Angebot auf **Angenommen**. - Die Positionen kommen aus der Bestellung, nicht aus dem Angebot. - Nennen die Positionen unterschiedliche Angebote oder ist das Angebot nicht mehr offen, legt Workist den Beleg ohne Bezug an. - Das Feld **Beleg zu** im Auftrag bleibt leer: Sage 100 übernimmt den Bezug über die Schnittstelle nur in den Vorgang. ### Hinweistext als Belegmemo Ist im Kanal das Kopffeld **Hinweistext** (*Note Text*) eingerichtet, übernimmt Workist dessen Inhalt in das **Memo** des Belegs. ### Belege als Entwurf Mit *Save documents in Sage 100 as drafts* legt Workist Belege **geparkt** an statt gespeichert. Geparkte Belege erhalten eine Nummer aus dem Nummernkreis für geparkte Belege und werden in Sage 100 von Ihren Mitarbeitenden fertiggestellt. Die Einstellung gilt für alle Belege, die Workist in Sage 100 anlegt – aus Bestellungen ebenso wie von Agenten. ### ERP-Funktionen der Agenten Mit Version 8 greifen [Worki](/docs/agents/worki.md), [Inbox-Agenten](/docs/agents/inbox-agents.md) und [Sprachagenten](/docs/agents/voice-agents.md) live auf Ihre Sage 100 zu: | Funktion | Was der Agent liefert | Worki | Inbox-Agent | Sprachagent | | --- | --- | --- | --- | --- | | Preis | Nettopreis des Kunden nach Rabatt, mit Staffelpreisen | ja | ja | ja | | Verfügbarkeit | Lagerbestand über alle Lager | ja | ja | ja | | Liefertermin | Liefertermin einer Bestellung | ja | ja | – | | Versanddatum | Datum des ersten Folgebelegs einer Bestellung, meist des Lieferscheins | ja | – | – | | Offene Angebote und Belege | Offene Angebote und offene Belege einer Belegart, für einen oder alle Kunden | ja | – | – | | Auftragsstatus | Bestellung mit den daraus entstandenen Belegen | ja | – | – | | Beleg lesen | Beliebiger Verkaufsbeleg mit Positionen und den Belegen desselben Vorgangs | ja | – | – | | Beleg anlegen | Verkaufsbeleg direkt in Sage 100 | ja | – | – | | Angebot in Auftrag übernehmen | Auftrag mit den Positionen und Preisen des Angebots, im Vorgang des Angebots | ja | – | – | | Kunde anlegen | Kunde direkt in Sage 100, mit der nächsten freien Kundennummer eines Nummernkreises | ja | – | – | - **Schreiben ist im Standard aus.** Belege, Angebotsübernahmen und Kunden legt Worki nur an, wenn in der Verbindung *Allow agentic writes* eingeschaltet ist, und erst nachdem der Benutzer bestätigt hat. Sonst antwortet Worki, dass das Schreiben ausgeschaltet ist. - **Preise gibt es nur für einen bekannten Kunden.** Sage 100 ermittelt Preise nur mit Kundennummer. Einem nicht erkannten Anrufer nennt der Sprachagent deshalb keinen Preis. - **Verfügbarkeit ist der Lagerbestand.** Reservierungen und Zugänge liefert die Schnittstelle nicht. Bestände in Sperrlagern zählen mit. - **Offen** heißt bei Belegen: Es ist noch kein Folgebeleg daraus entstanden. Teillieferungen erkennt Workist nicht. - Belegarten werden über ihr Kennzeichen angesprochen. Welche Kennzeichen es in Ihrem Mandanten gibt, sieht der Agent an den Belegen, die er liest. #### Einrichtung in den Agenten :::info Zusatzleistungen Worki, Inbox-Agenten und Sprachagenten werden jeweils separat lizenziert. Ihre Ansprechperson bei Workist schaltet sie frei – siehe [Freischaltung](/docs/agents.md#freischaltung). ::: | Agent | So verbinden Sie ihn mit Ihrer Sage 100 | Lizenz | | --- | --- | --- | | [Inbox-Agent](/docs/agents/inbox-agents.md) | Im Agenten unter **Integrationen** → **ERP** Sage 100 und, bei mehreren, die Verbindung wählen. Unter **Fähigkeiten** Preis-Anfrage, Verfügbarkeit und Lieferdatum einschalten. | Inbox-Agenten | | [Worki](/docs/agents/worki.md) | Das Gespräch im [Projekt eines Inbox-Agenten](/docs/agents/worki.md#projekte-von-inbox-agenten) führen, der mit Sage 100 verbunden ist. Worki nutzt dann dessen Verbindung, einschließlich der Funktionen zum Lesen und Anlegen von Belegen. | Worki (Chat-Agenten) | | [Sprachagent](/docs/agents/voice-agents.md) | Unter **Werkzeuge** im Bereich ERP-Liveverbindung Sage 100 und die Verbindung wählen und die Werkzeuge Artikelpreis und Artikelverfügbarkeit einschalten. | Sprachagenten | Damit Worki in Sage 100 schreibt, muss außerdem in der Sage 100-Verbindung *Allow agentic writes* eingeschaltet sein. ## Was Workist in Ihrer Sage 100 berührt Für die Einführung ist weniger die Schnittstelle selbst relevant als das Datenmodell dahinter: welche Tabellen Workist liest, wo geschrieben wird und was die Installation an Ihrem Datenbestand verändert. ### Gelesene Daten Workist liest, um Angaben aus dem eingehenden Dokument gegen Ihr System zu validieren: Stammdaten zu Kunde, Artikel, Lieferadresse, Projekt. Ab Version 8 der Erweiterung liest Workist zusätzlich Preise, Lagerbestände und Verkaufsbelege. | Bereich | Sage 100-Tabellen | Wofür Workist es liest | | --- | --- | --- | | Kundenstamm | Kundenstamm (Sage-Datensatz `recKundenstamm`) | Kundenerkennung | | Lieferanschriften | `KHKAdressen`, `KHKAdressenverweise`, `KHKKontokorrent` | Auflösen der Lieferadresse | | Ansprechpartner | `KHKAnsprechpartner` + dieselben Adresstabellen | Ansprechpartner am Beleg | | Artikel | `KHKArtikel`, `KHKArtikelVarianten` (+ `KHKArtikelgruppen`, `KHKVariantenAnzeigeTexte` u. a.) | Artikelerkennung, Mengeneinheiten | | Projekte | `KHKProjekte` | Rahmenverträge | | Verkaufsbelege (ab Version 8) | `KHKVKBelege`, `KHKVKBelegePositionen` | Offene Angebote, Bestellungen mit Angebotsbezug, Agenten | | Preise (ab Version 8) | Preisfindung von Sage 100 | Preisprüfung, Agenten | | Lagerbestände (ab Version 8) | Lagerplatzbestände und Lager | Agenten | Alle Lesezugriffe erfolgen mandantenbezogen – die Abfragen filtern auf den Mandanten des angesprochenen DataSets. ### Geschriebene Daten Workist schreibt **nicht per SQL** in Ihre Tabellen. Belege entstehen über die Belegerfassung von Sage 100, Kunden über den Kundenstamm. Damit greifen Ihre Nummernkreise, Preisfindung, Steuerlogik und Validierungen unverändert. | Was Workist anlegt | Über | Ergebnis in Sage 100 | | --- | --- | --- | | Verkaufsbeleg mit Positionen | Belegerfassung | Beleg in `KHKVKBelege` / `KHKVKBelegePositionen`, gespeichert oder geparkt | | Auftrag aus einem Angebot (ab Version 8) | Belegerfassung | Beleg im Vorgang des Angebots | | Kunde (ab Version 8, durch Worki) | Kundenstamm | Datensatz im Kundenstamm | Bestehende Belege werden **nicht** geändert oder gelöscht – es gibt ausschließlich die Anlage. Legt Workist einen Auftrag mit Bezug auf ein Angebot an, setzt Sage 100 selbst das Angebot auf **Angenommen**. ### Zusätzliche Felder in Ihren Tabellen Die Installation legt zwei benutzerdefinierte Felder an. Sie werden über das mitgelieferte Skript `…-UpdateUserFields-Workist.sql` erzeugt und dienen der Rückverfolgbarkeit. | Feld | Bezeichnung in Sage 100 | Typ | Tabellen | | --- | --- | --- | --- | | `USER_WorkistBearbeiter` | Bearbeitet von in Workist | varchar(200) | `KHKVKBelege`, `KHKArchivVKBelege`, `tKHKPrintBelegKopfVK` | | `USER_WorkistReferenz` | Workist Referenz | varchar(200) | `KHKVKBelege`, `KHKArchivVKBelege`, `tKHKPrintBelegKopfVK` | Zusätzlich werden die Felder in `USysClassFields` für die Klasse `VKBeleg` registriert, damit sie in Sage 100 verfügbar sind. :::warning Nicht im Metadatenimport enthalten Diese beiden Felder werden **nicht** über den Metadatenimport angelegt. Das Skript `…-UpdateUserFields-Workist.sql` aus dem Paketordner `SKRIPTE` muss auf den betroffenen Datenbanken ausgeführt werden – siehe [Installation, Schritt 5](/docs/data-exchange/connectors/sage-100-installation.md#schritt-5-workist-felder-anlegen). ::: ## Feldreferenz Welche Felder Workist im Einzelnen in den Verkaufsbeleg schreibt und welche Stammdatenfelder Workist aus Ihrer Sage 100 liest, steht in der [Sage 100 Feldreferenz](/docs/data-exchange/connectors/sage-100-fields.md). --- Source: https://docs.workist.com/docs/data-exchange/connectors/sage-100-installation.md # Sage 100 – Installation Diese Seite führt Schritt für Schritt durch die Einrichtung der Workist-Anbindung in Ihrer Sage 100. Was der Konnektor liest und schreibt und welche Angaben Workist von Ihnen benötigt, steht unter [Sage 100 Konnektor](/docs/data-exchange/connectors/sage-100.md). ## Ablauf im Überblick Die Einrichtung nehmen in der Regel Ihre IT oder Ihr Sage 100-Partner vor – meist gemeinsam mit Workist in einem Termin. Ihr Partner kann die Schritte 1–9 auch allein durchführen und uns danach die [Angaben aus Schritt 10](#schritt-10-verbindung-in-workist-anlegen) mitteilen. Rechnen Sie mit etwa einer Stunde für die Installation, zuzüglich des Neustarts des Applikationsservers. Endpunkte müssen Sie nicht von Hand einrichten – sie kommen mit der Workist API-Erweiterung. Danach prüfen wir zusammen, ob Stammdaten ankommen und ein Testbeleg richtig in Ihrer Sage 100 landet. | Phase | Schritte | Wer | | --- | --- | --- | | [Vorbereitung](#vorbereitung) | Lizenz, Version, Zugänge, Wartungsfenster | Ihre IT / Ihr Sage 100-Partner | | [Einrichtung in Sage 100](#einrichtung-in-ihrer-sage-100) | Schritte 1–9 | Ihre IT / Ihr Sage 100-Partner | | [Verbindung in Workist](#schritt-10-verbindung-in-workist-anlegen) | Schritt 10 | Workist, gemeinsam mit Ihnen | | [Test](#schritt-11-verbindung-prüfen) | Stammdaten und Testbeleg | gemeinsam | :::tip Mit der Testumgebung beginnen Richten Sie die Anbindung zuerst auf einer Testdatenbank Ihrer Sage 100 ein. Erst wenn Stammdaten und Testbelege dort sauber durchlaufen, wird die Produktivdatenbank angebunden – siehe [Wechsel in die Produktivumgebung](#wechsel-in-die-produktivumgebung). ::: ## Vorbereitung Klären Sie diese Punkte vor dem Einrichtungstermin. Fehlt einer davon, kommt die Einrichtung meist an genau dieser Stelle zum Stehen. | Punkt | Warum | | --- | --- | | **Lizenz 3rd Party Gateway** liegt vor | Ohne sie ist die Sage 100 API von außen nicht erreichbar – siehe [Lizenz](#voraussetzung-3rd-party-gateway-lizenz) | | **Sage 100-Version** ist bekannt (z. B. 9.0.9) | Bestimmt, welches Paket der Workist API-Erweiterung installiert wird – siehe [Unterstützte Versionen](/docs/data-exchange/connectors/sage-100.md#unterstützte-sage-100-versionen) | | **Sage ID des Hauptansprechpartners** ist zur Hand | Mit ihr wird das Connectivity Gateway verbunden (Schritt 1) und Workist als externer API-Benutzer zugelassen (Schritt 8). Bei Zwei-Faktor-Authentifizierung muss der Hauptansprechpartner während der Einrichtung erreichbar sein. | | **Administrativer Zugriff** auf Server Manager, AppDesigner, Sage 100 Administrator und SQL Server Management Studio | Alle Schritte finden auf dem Sage 100-Server statt | | **Wartungsfenster** ist eingeplant | Der Applikationsserver muss neu gestartet werden; währenddessen kann niemand in Sage 100 arbeiten (Schritt 9) | | **Belegart** ist festgelegt | Bestimmt, als welcher Beleg Workist-Bestellungen in Sage 100 entstehen – siehe [Belegart](/docs/data-exchange/connectors/sage-100.md#belegart). Die Entscheidung trifft Ihr Vertrieb bzw. Ihre Auftragsbearbeitung, nicht der Partner. Soll Workist eine eigene Belegart nutzen, etwa einen wirkungslosen Vorbeleg, muss Ihr Partner sie vor dem Test anlegen. | | **Andere API-Anbindungen** sind bekannt | Nutzt bereits ein anderes Produkt die Externe API, beeinflusst die Installation diese Anbindung – siehe Hinweis unten. Die Einrichtung für Workist ersetzt sie nicht: Auch dann sind alle Schritte nötig, insbesondere [Schritt 8](#schritt-8-workist-als-externen-api-benutzer-zulassen). | :::warning Neustart im laufenden Betrieb einplanen Der Neustart des Applikationsservers (Schritt 9) unterbricht die Arbeit aller Sage 100-Benutzer. Zudem lässt sich eine Datei der Erweiterung nicht austauschen, solange Sage 100 sie verwendet. Bei mehr als einer Handvoll Benutzern empfiehlt es sich, die Schritte 2–9 in ein Wartungsfenster außerhalb der Geschäftszeiten zu legen. ::: :::warning Andere API-Anbindungen auf demselben Server Sind weitere Anbindungen über die Sage 100 API aktiv, funktionieren sie zwischen dem Metadatenimport (Schritt 3) und dem Neustart (Schritt 9) unter Umständen nicht korrekt. Führen Sie Import und Neustart deshalb unmittelbar nacheinander im selben Wartungsfenster aus. Weil pro Installation nur eine Verbindung zum Connectivity Gateway möglich ist, teilen sich alle Anbindungen diese Verbindung – sprechen Sie uns vorab an, wenn ein anderes Produkt sie bereits nutzt. ::: ### Voraussetzung: 3rd Party Gateway-Lizenz Für die externe Nutzung der Sage 100 API wird eine Lizenz **3rd Party Gateway** benötigt – Sage empfiehlt eine Lizenz pro Kunde. Bei der Lizenzierung registriert Sage die E-Mail-Adresse Ihres Hauptansprechpartners zusammen mit einer KundenID – der [EntitlementID](/docs/data-exchange/connectors/sage-100.md#entitlementid) – im Entitlement Service. Die Lizenz beziehen Sie über Ihren Sage 100-Partner. Bestellen Sie die Lizenz frühzeitig – die Freischaltung durch Sage dauert erfahrungsgemäß einige Tage. Für die Freischaltung fragt Sage nach der Anwendung: Workist ist eine Webanwendung, die **Maschine-zu-Maschine** mit Ihrer Sage 100 kommuniziert. Prüfen Sie dabei, welche E-Mail-Adresse Sage für Ihr Entitlement hinterlegt hat – mit genau dieser Adresse wird in Schritt 1 angemeldet. ## Einrichtung in Ihrer Sage 100 Die offizielle Anleitung zum Sage Connectivity Gateway finden Sie in der Sage Dokumentation: Einrichtung der Sage 100 – Sage Dokumentation ↗ ### Schritt 1: Connectivity Gateway verbinden Im Sage 100 Server Manager unter **Externe API** → **Verbindung herstellen**: 1. Melden Sie sich über Sage ID mit der E-Mail-Adresse des Hauptansprechpartners an. 2. Wählen Sie das Entitlement aus. 3. Wählen Sie den Applikationsserver, an den Anfragen weitergeleitet werden. Bei Bedarf hinterlegen Sie im selben Dialog einen Proxy. Unter **Externe API** → **Konfiguration** sehen Sie anschließend die [EntitlementID](/docs/data-exchange/connectors/sage-100.md#entitlementid) – sie wird in Schritt 10 benötigt. :::note Eine Verbindung pro Installation Pro Kundeninstallation ist genau **eine** Verbindung zum Connectivity Gateway möglich. ::: ### Schritt 2: Passendes Paket auswählen Laden Sie die [Workist API-Erweiterung](#downloads) herunter und entpacken Sie sie. Sie enthält für jede unterstützte Sage 100-Version einen eigenen Ordner, jeweils mit den Unterordnern `METADATA`, `DLLS` und `SKRIPTE`. Verwenden Sie **ausschließlich** den Ordner, der zu Ihrer Sage 100-Version passt – die Pakete sind nicht untereinander austauschbar und nicht abwärtskompatibel. Maßgeblich sind die ersten drei Stellen der Version (9.0.X). Die Ordner heißen etwa `Workist-170163136-9.0.10.3`; die letzte Stelle bezeichnet den Stand der Erweiterung, nicht Ihren Patch-Stand. Bei Sage 100 9.0.10.4 verwenden Sie also den Ordner für 9.0.10. ### Schritt 3: Metadaten importieren Im AppDesigner unter **Metadaten** → **Import**: 1. Wählen Sie die Datei `100096740.WorkistAPI.….metadata` aus dem Ordner `METADATA` des passenden Pakets. 2. Ab Version 9.0.9: Aktivieren Sie die Option **Berechtigungen beim Import erzeugen und in der aktuellen Datenbank anwenden**. 3. Bestätigen Sie den Dialog. Der Import ist erst abgeschlossen, wenn der Aufbau des Metadaten-Index beendet ist. In der Übersicht erscheint die Workist-Erweiterung unter der Partnernummer **96740**. ### Schritt 4: Berechtigungen einspielen Wie die Berechtigungen der Erweiterung in Ihre Datenbanken kommen, hängt von der Version ab: | Sage 100-Version | Vorgehen | | --- | --- | | ab 9.0.9 | Werden beim Metadatenimport erzeugt (Schritt 3). Für weitere Datenbanken spielen Sie sie nach dem Import dort ebenfalls ein. Ab Version 8 der Erweiterung führen Sie zusätzlich das Skript aus – siehe unten. | | 9.0.8 | Führen Sie das Skript `…-Berechtigungen.sql` aus dem Ordner `SKRIPTE` im SQL Server Management Studio auf jeder betroffenen Datenbank aus. | Ab Version 8 der Erweiterung führen Sie das Skript `2026-10-06-Berechtigungen.sql` aus dem Ordner `SKRIPTE` **auf allen Sage 100-Versionen** aus: Version 8 bringt neue Endpunkte für Kostenstellen und Kostenträger mit (Bereich `API.Rewe`). Steht die Berechtigungsvergabe auf **Detailliert**, berechtigen Sie den Workist-Benutzer zusätzlich für diesen Bereich – siehe [Benötigte Berechtigungen](#benötigte-berechtigungen). ### Schritt 5: Workist-Felder anlegen Führen Sie das Skript `…-UpdateUserFields-Workist.sql` aus dem Ordner `SKRIPTE` im SQL Server Management Studio auf jeder Datenbank aus, die Workist ansprechen soll. Es legt die beiden Felder an, über die sich Workist-Belege zurückverfolgen lassen – siehe [Zusätzliche Felder in Ihren Tabellen](/docs/data-exchange/connectors/sage-100.md#zusätzliche-felder-in-ihren-tabellen). Nach dem Ausführen dauert es einen Moment, bis Sage 100 seinen Cache neu aufgebaut hat und die Felder bereitstehen. Beide Skriptnamen tragen ein vorangestelltes Datum, etwa `2026-06-29-UpdateUserFields-Workist.sql`. Ist der Ordner `SKRIPTE` leer, wenden Sie sich an uns. :::warning Nicht im Metadatenimport enthalten Dieses Skript wird **nicht** über den Metadatenimport ausgeführt und ist in der Installationsanleitung von Sage nicht aufgeführt. Ohne diesen Schritt fehlen die Felder. ::: ### Schritt 6: Datenbanken freigeben Geben Sie im Sage 100 Administrator jede Datenbank, die Workist erreichen soll, **ausdrücklich** für die Konnektivität frei. Eine Datenbank, die nicht freigegeben ist, ist für Workist nicht sichtbar – auch wenn alle anderen Schritte erledigt sind. ### Schritt 7: Workist-Benutzer anlegen und berechtigen Im Sage 100 Administrator: 1. Legen Sie einen Sage 100-Benutzer für Workist an. Vergeben Sie einen sprechenden Namen (etwa „Workist"), damit erkennbar bleibt, zu welchem Partner-Dienst der Benutzer gehört – wie er heißt, spielt für Workist keine Rolle. 2. Erteilen Sie dem Benutzer die [benötigten Berechtigungen](#benötigte-berechtigungen) im Bereich **API**. Steht die Berechtigungsvergabe in Ihrer Sage 100 auf **Detailliert** statt auf **Alle**, müssen die Berechtigungen pro Benutzer oder Gruppe gesetzt werden. Die Berechtigungen dieses Benutzers bestimmen, was Workist in Ihrer Sage 100 lesen und anlegen darf. Verbietet Ihre Gruppe **Public** den Bereich **API** bereits vollständig, erteilen Sie die Berechtigungen über eine eigene Gruppe, der Sie den Workist-Benutzer zuordnen. Dieser Benutzer ist ein technischer Benutzer – getrennt von der persönlichen Sage ID des Hauptansprechpartners aus Schritt 1. Workist braucht für ihn **kein** Kennwort: Schicken Sie uns keine Sage-Anmeldedaten. :::tip Fehlende Berechtigungen schnell eingrenzen Meldet die Verbindungsprüfung, dass der Zugriff auf Verkaufsbelege nicht erlaubt ist, liegt es fast immer an den Berechtigungen dieses Benutzers. Prüfen Sie zuerst die Bereiche aus der Tabelle [Benötigte Berechtigungen](#benötigte-berechtigungen). ::: ### Schritt 8: Workist als externen API-Benutzer zulassen Erst dieser Schritt verbindet Workist mit dem Benutzer aus Schritt 7. Fehlt er, weist Sage 100 jede Anfrage von Workist mit *Zugriff verweigert* (HTTP 401) ab – auch wenn alle anderen Schritte erledigt sind. In der Anleitung von Sage steht er nur in einer Abbildung und wird deshalb leicht übersehen. Im Sage 100 Administrator: 1. Öffnen Sie oben das Menü **Extras** → **Externe API-Benutzer verwalten**. 2. Melden Sie sich mit dem Sage-Konto an, mit dem das Connectivity Gateway verbunden ist (Schritt 1). Ist für dieses Konto eine Zwei-Faktor-Authentifizierung eingerichtet, muss der Hauptansprechpartner dafür erreichbar sein. 3. Fügen Sie die [Workist Client-ID](#workist-client-id) als externen API-Benutzer hinzu. In der Liste erscheint Workist nicht mit Namen, sondern als diese Zeichenfolge. 4. Ordnen Sie ihn dem Workist-Benutzer aus Schritt 7 zu. 5. Starten Sie anschließend den Applikationsserver neu (Schritt 9). Erst danach greift die Freigabe. :::warning Eine bestehende API-Anbindung ersetzt diesen Schritt nicht Jedes Produkt, das die Sage 100 API nutzt, meldet sich mit einer eigenen Client-ID an. Ist in der Liste bereits ein anderer externer API-Benutzer eingetragen – etwa für einen Webshop oder ein anderes Partnerprodukt –, gilt diese Freigabe nicht für Workist. Die Workist Client-ID muss zusätzlich eingetragen werden. ::: ### Schritt 9: Applikationsserver neu starten Erst mit dem Neustart werden die Dateien der Erweiterung verteilt und die neuen Endpunkte aktiv. 1. Stoppen Sie im Sage Server Manager unter **Server** → **Verwaltung** → **Dienste** den Dienst **Sage Application Server**. 2. Prüfen Sie im Task-Manager, ob alle Prozesse `Sagede.ApplicationServer.IsolationProcess.exe` beendet sind. Beenden Sie verbliebene Prozesse von Hand. 3. Starten Sie den Dienst wieder. 4. Prüfen Sie im Shared-Verzeichnis Ihrer Sage 100 (Standard: `C:\Program Files (x86)\Sage\Sage 100\9.0\Shared`), ob diese Dateien vorhanden sind: | Datei | Prüfung | | --- | --- | | `PSDev.Sage100.Workist.BusinessLogic.dll` | Dateiversion passt zur Sage 100-Version | | `PSDev.Sage100.Workist.Core.dll` | Dateiversion passt zur Sage 100-Version | | `PSDev.Sage100.Workist.DataAccess.dll` | Dateiversion passt zur Sage 100-Version | | `PSDev.Sage100.Workist.RealTimeData.dll` | Dateiversion passt zur Sage 100-Version | | `Newtonsoft.Json.dll` | vorhanden | Die Dateiversion setzt sich aus Major, Minor und Build Ihrer Sage 100 sowie dem Stand der Erweiterung zusammen – etwa `9.0.9173.1` für Sage 100 9.0.8: | Sage 100-Version | Major.Minor | Build | | --- | --- | --- | | 9.0.8 | 9.0 | 9173 | | 9.0.9 | 9.0 | 9670 | | 9.0.10 | 9.1 | 268 | | 9.0.11 | 9.1 | 866 | Fehlen die Dateien nach dem Neustart, kopieren Sie sie aus dem Ordner `DLLS` des passenden Pakets in das Shared-Verzeichnis. Ist eine Datei – meist `Newtonsoft.Json.dll` – in Benutzung, lässt sie sich erst ersetzen, wenn Sage 100 und der Applikationsserver beendet sind. Anschließend starten Sie den Applikationsserver erneut. ### Checkliste vor der Übergabe an Workist Haken Sie diese Punkte ab, bevor Sie uns die Angaben für Schritt 10 schicken: - [ ] Connectivity Gateway verbunden, EntitlementID notiert (Schritt 1) - [ ] Paket zur Sage 100-Version importiert, Berechtigungen und Workist-Felder eingespielt (Schritte 2–5) - [ ] Jede Datenbank für Workist freigegeben (Schritt 6) - [ ] Workist-Benutzer angelegt und im Bereich **API** berechtigt (Schritt 7) - [ ] Workist Client-ID unter **Externe API-Benutzer verwalten** eingetragen und dem Workist-Benutzer zugeordnet (Schritt 8) - [ ] Applikationsserver **nach** Schritt 8 neu gestartet, DLLs vorhanden (Schritt 9) - [ ] Belegart angelegt und Kennzeichen bekannt ([Belegart](/docs/data-exchange/connectors/sage-100.md#belegart)) ## Schritt 10: Verbindung in Workist anlegen Mit den folgenden Angaben legt Workist die Verbindung zu Ihrer Sage 100 an – in Workist unter **Einstellungen** → **Integrationen** → **Sage 100**: | Angabe | Beispiel | Erläuterung | | --- | --- | --- | | **Name** | `Sage 100 Test` | Frei wählbar. Ein Name, der Test- und Produktivumgebung unterscheidet, erleichtert später den Wechsel. | | **EntitlementID** | – | Aus Schritt 1 – siehe [EntitlementID](/docs/data-exchange/connectors/sage-100.md#entitlementid) | | **DataSet** | `WAWI_DB;1` | Datenbankname, Semikolon, Mandantennummer – siehe [DataSet](/docs/data-exchange/connectors/sage-100.md#dataset), dort auch, wo Sie beide Werte finden | | **Belegart** | `VVA` | Kennzeichen der Belegart – siehe [Belegart](/docs/data-exchange/connectors/sage-100.md#belegart) | | **Kanäle** | – | Die Workist-Kanäle, deren Bestellungen in diese Sage 100 übertragen werden | | **Version der Erweiterung** (*Sage 100 API Version*) | `8` | Installierte Version der Workist API-Erweiterung – siehe [Version](/docs/data-exchange/connectors/sage-100.md#version-der-workist-api-erweiterung) | | **Angebots-Belegart** (*Sage 100 Offer Document Type*) | `VPA` | Kennzeichen der Angebote für den Angebotsabgleich, ab Version 8 – siehe [Angebots-Belegart](/docs/data-exchange/connectors/sage-100.md#angebots-belegart) | Ab Version 8 stellen Sie in derselben Verbindung außerdem die Preisprüfung, das Anlegen als Entwurf und das Schreiben durch Agenten ein – siehe [Funktionen ab Version 8](/docs/data-exchange/connectors/sage-100.md#funktionen-ab-version-8-der-erweiterung). Alle drei sind im Standard ausgeschaltet. :::warning DataSet genau so schreiben, wie es in Sage 100 steht Datenbankname und Mandantennummer werden durch ein **Semikolon** getrennt, ohne Leerzeichen. Ein Tippfehler im Datenbanknamen oder ein vertauschtes Trennzeichen führt dazu, dass Workist keine Verbindung zur Datenbank bekommt. ::: ## Schritt 11: Verbindung prüfen ### Stammdaten Nach dem Anlegen der Verbindung stößt Workist den ersten Stammdatenimport an. Danach aktualisiert Workist die Stammdaten **einmal täglich** automatisch. Den Stand sehen Sie in Workist unter **Einstellungen** → **Integrationen** → **Sage 100**: Dort stehen der Status der Verbindung, der Zeitpunkt der letzten Stammdatenaktualisierung und – während ein Import läuft – der Hinweis auf die laufende Datenaktualisierung. Laden Sie die Seite neu, um den aktuellen Stand zu sehen. Über dieselbe Seite lässt sich eine Aktualisierung auch von Hand anstoßen. Der erste Import kann je nach Datenmenge einige Zeit dauern. Prüfen Sie danach unter **Stammdaten verwalten** im jeweiligen Kanal, ob die Anzahl an Kunden, Lieferadressen und Artikeln plausibel ist. :::note Änderungen in Sage 100 erreichen Workist mit dem nächsten Import Was Sie tagsüber in Sage 100 ändern – etwa einen neu angelegten Artikel – steht in Workist erst nach der nächsten Stammdatenaktualisierung zur Verfügung. ::: ### Testbeleg Schicken Sie eine echte Bestellung als Test durch Workist und schließen Sie sie ab. Prüfen Sie in Sage 100: - Ist der Beleg in der hinterlegten Belegart entstanden? - Stehen Kunde, Bestellnummer, Artikel und Mengen in den richtigen Feldern? - Wurde eine Lieferadresse übernommen? Ist auf der Bestellung keine angegeben, setzt Sage 100 die Standard-Lieferadresse des Kunden. Testbelege entstehen in der **Testdatenbank** – suchen Sie sie dort, nicht in der Vorgangsauskunft Ihrer Produktivdatenbank. Löschen Sie sie nach dem Test. Eine eigene Test-Belegart ohne weitere Wirkung macht Testbelege zusätzlich leicht erkennbar. Workist legt einen Beleg nur an, wenn eine **Kundennummer** ermittelt wurde. Lehnt Sage 100 den Beleg ab, zeigt Workist die Meldung von Sage 100 am Dokument an. Nach der Korrektur lässt sich die Übertragung direkt am Dokument erneut anstoßen – Sie müssen das Dokument nicht noch einmal an Workist senden. ## Wechsel in die Produktivumgebung Laufen Stammdaten und Testbelege in der Testumgebung sauber, wird die Produktivdatenbank angebunden. Planen Sie dafür einen eigenen kurzen Termin mit Ihrem Sage 100-Partner und Workist ein. 1. Führen Sie die Schritte 4–7 auf der Produktivdatenbank aus, sofern noch nicht geschehen: Die Datenbank muss freigegeben sein, und der Workist-Benutzer braucht dort dieselben Berechtigungen wie in der Testdatenbank. 2. Teilen Sie uns das DataSet der Produktivdatenbank mit. Die EntitlementID bleibt dieselbe. 3. Workist legt eine Verbindung mit dem DataSet der Produktivdatenbank an oder stellt die bestehende um. Die Umstellung nehmen wir in Workist vor – in Sage 100 ist dafür nichts weiter zu tun. 4. Ihre Mitarbeitenden leiten Bestellungen ab jetzt an die Adresse des **produktiven** Kanals weiter, nicht mehr an die des Testkanals. Steht Ihnen kein eigenes Testsystem zur Verfügung, genügt eine Kopie der Datenbank auf dem produktiven Applikationsserver – sofern die Schritte 4–7 auch auf der Kopie ausgeführt wurden. ## Neue Version der Workist API-Erweiterung Erweitert Workist den Konnektor, erhalten Sie eine neue Version der Erweiterung. Installieren Sie sie genauso wie die erste Version – Schritte 2–5 und 9, einschließlich der Skripte und des Neustarts im Wartungsfenster. Welche Version installiert ist, zeigt der AppDesigner. Geben Sie uns Bescheid, sobald die neue Version installiert ist. Version 8 ergänzt die Belegfelder Speicherstatus, Belegdatum, Matchcode, Memo, Kostenstelle und Kostenträger – siehe [Feldreferenz](/docs/data-exchange/connectors/sage-100-fields.md#weitere-felder-ab-version-8-der-erweiterung). Führen Sie beim Update auf Version 8 das Berechtigungsskript aus ([Schritt 4](#schritt-4-berechtigungen-einspielen)). Danach stellt Workist die Verbindung auf Version 8 um; erst dann stehen die [Funktionen ab Version 8](/docs/data-exchange/connectors/sage-100.md#funktionen-ab-version-8-der-erweiterung) zur Verfügung. ## Nach einem Sage 100-Update Die Erweiterung ist an Ihre Sage 100-Version gebunden. Planen Sie ein Update von Sage 100, gehört die Erweiterung dazu: Nach dem Update installieren Sie das Paket für die **neue** Version erneut (Schritte 2–5 und 9). Steht für die neue Version noch kein Paket bereit, sprechen Sie uns vor dem Update an. ## Fehlerbehebung | Meldung oder Verhalten | Ursache | Lösung | | --- | --- | --- | | *Es konnte kein Handler für ENDPUNKT ermittelt werden.* | Die Endpunkte der Erweiterung oder die Freigabe aus Schritt 8 sind im Applikationsserver noch nicht aktiv. | Applikationsserver neu starten – [Schritt 9](#schritt-9-applikationsserver-neu-starten). | | *Websocket client 'NUMMER' has not been connected to the WebSocket Server.* | Der Dienst **Sage Cloud Connectivity Client** läuft nicht, oder die Externe API ist nicht konfiguriert. | Dienst starten; Externe API im Server Manager prüfen – [Schritt 1](#schritt-1-connectivity-gateway-verbinden). | | Kein Zugriff auf Verkaufsbelege | Dem Workist-Benutzer fehlen Berechtigungen. | Berechtigungen prüfen – [Schritt 7](#schritt-7-workist-benutzer-anlegen-und-berechtigen). | | *Der Wert … ist für das Feld Belegtyp-Kennzeichen nicht gültig.* | Die hinterlegte Belegart gibt es in diesem Mandanten nicht. | Kennzeichen der Belegart prüfen – [Belegart](/docs/data-exchange/connectors/sage-100.md#belegart). | | *Der Wert … ist für das Feld … nicht gültig.* (etwa für die Lieferbedingung) | Sage 100 akzeptiert nur Werte, die in Ihrem Mandanten hinterlegt sind – in genau dieser Schreibweise. | Wert in Sage 100 anlegen oder die Schreibweise abgleichen. | | Zugriff verweigert (HTTP 401 oder 403), beim ersten Verbinden oder nach dem Wechsel auf die Produktivdatenbank | Die Anmeldung von Workist wird abgewiesen – bei HTTP 401 meist, weil Workist nicht als externer API-Benutzer zugelassen ist. | Prüfen Sie zuerst: Client-ID unter **Externe API-Benutzer verwalten** eingetragen und dem Workist-Benutzer zugeordnet, danach Applikationsserver neu gestartet ([Schritt 8](#schritt-8-workist-als-externen-api-benutzer-zulassen)). Danach: Berechtigungen dieses Benutzers in **dieser** Datenbank, Datenbank freigegeben ([Schritt 6](#schritt-6-datenbanken-freigeben)), Dienst **Sage Cloud Connectivity Client** läuft, Entitlement und Applikationsserver ausgewählt ([Schritt 1](#schritt-1-connectivity-gateway-verbinden)), andere Produkte auf demselben Gateway. | | Fehler beim Datenbankzugriff nur bei Ansprechpartnern, alle anderen Daten kommen an | Fehler in älteren Versionen der Erweiterung bei benutzerdefinierten Feldern der Adressentabelle | Aktuelle Version der Erweiterung installieren – siehe [Neue Version](#neue-version-der-workist-api-erweiterung). Kunden, Artikel und Belege sind davon nicht betroffen. | | Beleg wird abgelehnt, weil ein Wert zu lang ist | Sage 100 begrenzt die Feldlänge – der Name einer Lieferadresse etwa ist auf 50 Zeichen beschränkt. | Wert im Dokument kürzen und die Übertragung erneut anstoßen. | | Abweichende Lieferadresse kommt nicht in Sage 100 an | Ohne Namen übernimmt Sage 100 eine abweichende Lieferadresse nicht. | Namen der Lieferadresse im Dokument ergänzen. | | Belege werden abgelehnt, oder die letzte Stammdatenaktualisierung liegt mehrere Tage zurück | Der API-Dienst auf Ihrem Sage 100-Server reagiert nicht mehr. | Dienste **Sage Application Server** und **Sage Cloud Connectivity Client** neu starten. Behalten Sie den Zeitpunkt der letzten Stammdatenaktualisierung in Workist im Blick – er zeigt früh, wenn die Verbindung hängt. | | Verbindung schlägt fehl, obwohl alle Schritte erledigt sind | DataSet falsch geschrieben, Datenbank nicht freigegeben, Workist nicht als externer API-Benutzer zugelassen oder Applikationsserver noch nicht neu gestartet. | [DataSet](/docs/data-exchange/connectors/sage-100.md#dataset), [Schritt 6](#schritt-6-datenbanken-freigeben), [Schritt 8](#schritt-8-workist-als-externen-api-benutzer-zulassen) und [Schritt 9](#schritt-9-applikationsserver-neu-starten) prüfen. | | Datei im Shared-Verzeichnis lässt sich nicht ersetzen | Die Datei ist in Benutzung. | Sage 100 und Applikationsserver beenden, Datei ersetzen, Applikationsserver starten. | ### Protokolle für den Support Die genaue Fehlerursache gibt die Sage 100 API nicht nach außen weiter – sie steht im TraceLog Ihrer Sage 100. Brauchen wir oder Sage für die Analyse ein Protokoll: 1. Packen Sie den gesamten Protokollordner als ZIP-Datei (Standard: `C:\SageLog\Default`). 2. Nennen Sie uns den ungefähren Zeitpunkt des Fehlers. Wurde am betreffenden Tag noch keine Protokolldatei geschrieben, starten Sie zuvor den Dienst **Sage Logging Service** neu. Das ist auch im laufenden Betrieb möglich. ## Referenz ### Downloads | Datei | Inhalt | | --- | --- | | [Workist API-Erweiterung Version 8 (ZIP)](/files/sage-100/workist-api-erweiterung.zip) | Je ein Paket pro unterstützter Sage 100-Version | | [Workist API Installationsanleitung (PDF)](/files/sage-100/workist-api-installationsanleitung.pdf) | Anleitung von Sage: Metadatenimport, Dateiverteilung, Fehleranalyse | ### Workist Client-ID Workist authentifiziert sich gegenüber Ihrem Sage 100-System über **Sage ID** mittels OpenID Connect im Maschine-zu-Maschine-Betrieb (M2M). Die Workist Client-ID lautet: `WPw9RlvT5I5XCX25kAsOKB3REYv98FRq` :::note Die Client-ID ist kein Passwort Die Client-ID ist eine öffentliche Anwendungskennung und für alle Workist-Kunden identisch. Es gibt kein Passwort und kein Client Secret, das Sie hinterlegen müssten. Im M2M-Betrieb tritt die Client-ID **an die Stelle der Sage ID-E-Mail-Adresse** als Identität des aufrufenden Systems. Sie wird also dort hinterlegt, wo bei einem interaktiven Benutzer das Sage-Konto eingetragen wird – nicht als Kennwort, nicht als Lizenzschlüssel und nicht als Eingabe im Server Manager. Wo genau, steht in [Schritt 8](#schritt-8-workist-als-externen-api-benutzer-zulassen). ::: ### Benötigte Berechtigungen Die für die API relevanten Berechtigungen werden im Sage 100 Administrator im Bereich **API** aufgeführt: | Bereich | Berechtigungen | | --- | --- | | `API.VK` | Verkaufsbeleg, Verkaufsbelegposition, VKBeleg, VKBelegePositionen, VKBelegPositionLager, VKArtikelPreisfinding | | `API.EK` | EKBeleg, EKBelegPosition, EKBelegPositionLager | | `API.Artikel` | Artikel, Lagerplatzbestände | | `API.Kunden` | Kunde | | `API.Ansprechpartner` | Ansprechpartner | | `API.Lager` | Lagersuche | | `API.Lieferanschriften` | Lieferanschriften | | `API.Projekte` | Projekte | | `API.Rewe` | Suche Kostenstelle, Suche Kostenträger (ab Version 8) | Zusätzlich legt die API-Erweiterung Berechtigungen im Bereich **SData-Dienste** an (Stammdaten, Bewegungsdaten und Realtime-Data). --- Source: https://docs.workist.com/docs/data-exchange/connectors/sage-100-fields.md # Sage 100 – Feldreferenz Diese Seite führt im Detail auf, welche Felder Workist in den Verkaufsbeleg schreibt und welche Stammdatenfelder Workist aus Ihrer Sage 100 liest. Den Überblick über Einrichtung und Konfiguration finden Sie unter [Sage 100 Konnektor](/docs/data-exchange/connectors/sage-100.md). ## Was Workist in den Verkaufsbeleg schreibt Workist übergibt den Beleg als ein Objekt: Kopffelder, darin die Positionen. Aufgeführt sind ausschließlich die Felder, die **Workist selbst befüllt**. Was Sage 100 beim Anlegen selbst setzt – Belegnummer, Belegjahr, Netto- und Bruttobetrag sowie der Gesamtpreis der Position – steht hier bewusst nicht. ### Belegkopf | Feld | Sage 100 | Hinweis | | --- | --- | --- | | `belegdatum` | Belegdatum | Bestelldatum aus dem Dokument. Übernommen ab Version 8 der [Erweiterung](/docs/data-exchange/connectors/sage-100-installation.md#downloads); ältere Versionen setzen das Tagesdatum | | `kennzeichen` | Belegtyp | Schlüssel für die Belegart — aus den [Belegarten](/docs/data-exchange/connectors/sage-100.md#belegart) | | `a0Konto` | Kunde | Die Kundennummer ist ein Pflichtfeld für die Anlage des Belegs | | `ansprechpartnerHandle` | Ansprechpartner-Nummer | Ansprechpartnernummer des A0Konto | | `referenznummer` | Ihre Belegnummer | Referenznummer bzw. Ihre Belegnummer | | `referenzzeichen` | Ihr Zeichen | Ihr Zeichen | | `liefertermin` | Lieferdatum | Liefertermin für den Beleg | | `zKDBezeichnung` | Zahlungskondition | Bezeichnung der Zahlungskond — aus den Zahlungskonditionen | | `projektnummer` | Projektnummer | Projektnummer | | `referenzBelegHandle` | ReferenzBelegHandle | Bei einer [Bestellung mit Angebotsbezug](/docs/data-exchange/connectors/sage-100.md#bestellungen-mit-angebotsbezug) das Angebot (ab Version 8). Sage 100 führt beide Belege dann im selben Vorgang | | `lieferbedingung` | Lieferbedingung | Lieferbedingung (Incoterm) aus dem Dokument, ab [Version 7](/docs/data-exchange/connectors/sage-100.md#version-der-workist-api-erweiterung). Muss in Ihrem Mandanten angelegt sein | ### Adressfelder Sage 100 führt am Verkaufsbeleg drei Adressrollen, erkennbar am Feldpräfix: | Rolle | Präfix | Wo die Daten herkommen | | --- | --- | --- | | Kunde (Auftraggeber) | `a0` | Kundenstamm, über `a0Konto` | | Lieferadresse | `a1` | Lieferanschrift des Kunden – oder Freitext | | Rechnungsadresse | `a2` | Nur bei abweichender Anschrift: bestehendes Konto – oder Freitext | Die Zuordnung zu einem hinterlegten Konto erfolgt über diese Felder: | Feld | Sage 100 | Hinweis | | --- | --- | --- | | `a1AdressNummer` | Lieferanschrift | Lieferadresse des A0Konto | | `a1AnsprechpartnerHandle` | Ansprechpartner | Ansprechpartnernummer des A0Konto — aus den Ansprechpartnern der Lieferadresse | | `a2Konto` | Rechnungsanschrift | Pflichtfeld bei abw. Rechnungsadresse | | `a2AnsprechpartnerHandle` | Ansprechpartner | aus den Ansprechpartnern der Rechnungsadresse | Alle übrigen Adressfelder sind in beiden Blöcken gleich aufgebaut und landen in den `A1*`- bzw. `A2*`-Spalten von `KHKVKBelege`: | Feld (Liefer- / Rechnungsadresse) | Sage 100 | Hinweis | | --- | --- | --- | | `a1Anrede` / `a2Anrede` | Anrede | | | `a1Name1` / `a2Name1` | Name | Pflichtfeld bei Freitext Lieferadressenangabe; Steuert Übernahme von sonstigen A1 Feldern; Nur wenn A1AdressNummer nicht verwendet | | `a1Name2` / `a2Name2` | Namenszusatz | | | `a1Zusatz` / `a2Zusatz` | Zusatz | | | `a1Strasse` / `a2Strasse` | Straße/Postfach | | | `a1Postleitzahl` / `a2Postleitzahl` | Postleitzahl | | | `a1Ort` / `a2Ort` | Ort | aus den Orten zu Land und PLZ | | `a1Land` / `a2Land` | Land | | ### Positionen | Feld | Sage 100 | Hinweis | | --- | --- | --- | | `artikelnummer` | Artikel | Die Artikelnummer ist ein Pflichtfeld für die Artikelposition. Das Feld AuspraegungsHandle ist Schlüsselbestandteil zum Artikel (s. Feld AuspraegungsHandle) | | `auspraegungsHandle` | – | Für eine Artikelvariante wird hier der Schlüssel für die Variante laut Feld AuspraegungID im Artikel benutzt. Falls keine Artikelvariante benutzt wird, so ist das Feld optional oder mit 0 zu füllen | | `bezeichnung` | Bezeichnung | Artikelbezeichnung | | `menge` | Menge | Eingabe der Menge. Artikel mit Mengenberechnung (z. B. Länge x Breite x Höhe) werden aktuell nicht unterstützt. Bei Zubehörartikeln werden die zugehörigen Artikel nicht automatisch hinzugefügt | | `mengeneinheit` | ME | Mengeneinheit - Entweder Basismenge oder Verkaufsmenge — aus den Mengeneinheiten | | `einzelpreis` | Einzelpreis | Falls das Feld nicht mitgegeben wird, so wird der Wert über die Preisfindung automatisch ermittelt | | `rabatt` | Rabatt (%) | Eingabe des Positionsrabatts in Prozent | | `liefertermin` | Liefertermin | Liefertermin | | `memo` | Memo | Memo - internes Beschreibungsfeld | ### Weitere Felder ab Version 8 der Erweiterung Mit Version 8 der [Workist API-Erweiterung](/docs/data-exchange/connectors/sage-100-installation.md#downloads) nimmt Sage 100 die folgenden Felder zusätzlich an. Speicherstatus und Memo befüllt Workist, wenn die Verbindung auf Version 8 steht. Die übrigen befüllt Workist im Standard **nicht** – sie lassen sich als kundenspezifische Anpassung nutzen. In älteren Versionen der Erweiterung gibt es sie nicht. | Feld | Ebene | Sage 100 | Hinweis | | --- | --- | --- | --- | | `speicherstatus` | Belegkopf | Speicherstatus | `0` = gespeichert (Standard), `1` = geparkt, wenn [Belege als Entwurf](/docs/data-exchange/connectors/sage-100.md#belege-als-entwurf) eingeschaltet ist | | `matchcode` | Belegkopf | Matchcode | Bis zu 50 Zeichen. Befüllt Workist nicht | | `memo` | Belegkopf | Memo | Der [Hinweistext](/docs/data-exchange/connectors/sage-100.md#hinweistext-als-belegmemo) aus dem Dokument, wenn das Feld im Kanal eingerichtet ist. Das `memo` der Position (siehe oben) ist davon unabhängig | | `kostenstelle` | Belegkopf und Position | Kostenstelle | Leer oder eine in Ihrer Sage 100 angelegte Kostenstelle. Befüllt Workist nicht | | `kostentraeger` | Belegkopf und Position | Kostenträger | Leer oder ein in Ihrer Sage 100 angelegter Kostenträger. Befüllt Workist nicht | ## Stammdaten, die Workist liest Workist liest Stammdaten, um Angaben aus dem eingehenden Dokument gegen Ihr System aufzulösen. Diese Daten werden **ausschließlich gelesen** und nicht verändert. Aufgeführt ist nur, was Workist im Standard tatsächlich auswertet. | Stammdaten in Sage 100 | Wird in Workist zu | Verwendete Felder | | --- | --- | --- | | Kunden | Kunden | `kto`, `matchcode`, `name1`, `name2`, `lieferStrasse`, `lieferPLZ`, `lieferOrt`, `lieferLand` | | Ansprechpartner | Ansprechpartner | `kto`, `nummer`, `vorname`, `nachname`, `telefon`, `eMail` | | Lieferanschriften | Lieferadressen | `kto`, `adresse`, `matchcode`, `name1`, `name2`, `strasse`, `pLZ`, `ort`, `land` | | Projekte | Rahmenverträge | `kto`, `projektnummer`, `matchcode` | | Offene Angebote (ab Version 8) | [Angebote](/docs/master-data/quotes.md), je Artikelposition | Kopf: `belegjahr`, `belegnummer`, `belegdatum`, `a0Empfaenger`; Position: `artikelnummer`, `bezeichnung1`, `menge`, `mengeneinheit` – siehe [Offene Angebote](/docs/data-exchange/connectors/sage-100.md#offene-angebote) | | Artikel | Artikel und Umrechnungsfaktoren | siehe unten | ### Artikel Aus dem Artikelstamm liest Workist gezielt die folgenden Felder: | Feld in Sage 100 | Verwendung in Workist | | --- | --- | | `Artikelnummer` | Artikelnummer – die führende Kennung für die Zuordnung | | `EANNummer` | zweite Artikelkennung für die Erkennung | | `Bezeichnung1` | Artikelbezeichnung | | `Langtext`, `Bezeichnung2` | ergänzender Text, verbessert die Trefferqualität bei der Erkennung | | `IstVerkaufsartikel` | steuert, ob der Artikel als aktiv oder inaktiv geführt wird | | `KalkulatorischerEK` | Preis am Artikel | | `Basismengeneinheit`, `Lagermengeneinheit`, `Verkaufsmengeneinheit`, `VerpackungseinheitVK` | die zulässigen Bestelleinheiten des Artikels; die Verkaufsmengeneinheit zusätzlich als Verkaufseinheit | | `UmrechnungsFaktorLME`, `UmrechnungsfaktorVK`, `UmrechnungsfaktorVPVK`, `UmrechnungsfaktorGP` | rechnen die übrigen Einheiten auf die Basismengeneinheit um | Die vier Mengeneinheiten werden gemeinsam ausgewertet: Sie ergeben die Liste der Einheiten, in denen bestellt werden kann, und über die Umrechnungsfaktoren die Menge in der Basiseinheit. So lässt sich eine Menge aus dem Dokument – etwa „2 Paletten" – in Ihre Basiseinheit übertragen. :::note Weitere Felder auf Anfrage Die Schnittstelle stellt darüber hinaus zahlreiche weitere Artikel- und Kundenfelder bereit, etwa Artikelgruppen, Gewichte, Steuerklassen oder die Herstellerartikelnummer. Im Standard werden sie nicht ausgewertet – eine Auswertung wäre eine kundenspezifische Anpassung. ::: --- Source: https://docs.workist.com/docs/data-exchange/connectors/business-central.md # 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. ![Architektur: Kommunikation zwischen der Business-Central-Installation (Workist BC App) und der Workist SaaS-Cloud über die REST-API – „Pull Master Data" und „Push Orders" via HTTPS](/img/business-central/architecture.png) ### 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](#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. - Eine **Business-Central-Integration in der Workbench** (siehe [Integration in der Workbench anlegen](#integration-in-der-workbench-anlegen)). Im Dialog **Setup-Daten anzeigen** dieser Integration finden Sie den **API-Schlüssel** und die benötigten **Lookup-IDs**. ### Datenfluss Die App sendet Stammdaten an Workist. Für diese Stammdaten zeigt Workist im Dialog **Setup-Daten anzeigen** je verbundenem Kanal eine Lookup-ID an. Welche davon die App befüllt, legen Sie in der App fest (siehe [Einrichtung](#einrichtung)). | Stammdaten in Workist | Lookup-ID im Dialog „Setup-Daten anzeigen“ | | --- | --- | | [Kunden](/docs/master-data/customers.md) | „Client-Lookup-ID“ | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | „Kontakt-Lookup-ID“ | | [Artikel](/docs/master-data/articles.md) | „Artikel-Lookup-ID“ | | [Kundenspezifische Artikelnummern](/docs/master-data/articles.md) | „Debitorenartikel-Lookup-ID“ | | [Einheitenumrechnung](/docs/master-data/unit-conversion.md) | „Umrechnungsfaktor-Lookup-ID“ | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | „ID der Rahmenvertragsuche“ | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | „Rechnungsadressen-Lookup-ID“ | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | „Lieferadressen-Lookup-ID“ | Die Lookup-ID für den Angebotsabgleich steht nicht in diesem Dialog, sondern in der Stammdatenkonfiguration des Kanals („Angebotsabgleich-Lookup-ID“). Die App übernimmt abgeschlossene Belege aus den Kanälen, die Sie in der Integration verbunden haben: | Belege aus Kanälen für | Auswahl in der Integration | „In externer Anwendung öffnen“ führt zu | | --- | --- | --- | | Bestellungen | „Bestellungskanäle“ | Verkaufsauftrag | | Auftragsbestätigungen | „Bestätigungskanäle für Aufträge“ | Einkaufsbestellung | ## 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*). ![Installationsoptionen beim Hochladen der Erweiterung](/img/business-central/001-pte-install.png) Auf der Seite **„Status der Erweiterungsinstallation"** (*Extension Installation Status*) können Sie den Fortschritt verfolgen. Im Fehlerfall finden Sie hier ebenfalls detaillierte Informationen. :::warning 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. ::: :::note 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, legen Sie in der Workbench eine Business-Central-Integration an und richten danach die App in Business Central ein. ### Integration in der Workbench anlegen Benutzer mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)) legen die Integration an: 1. Öffnen Sie **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** und klicken Sie bei Microsoft Business Central auf **Verbinden**. 2. Tragen Sie ein: | Feld | Inhalt | | --- | --- | | Name der Integration | frei wählbar | | Business Central-URL | Adresse Ihrer Business-Central-Umgebung im Browser | | Bestellungskanäle | Kanäle, deren Bestellungen die App als Verkaufsaufträge übernimmt | | Bestätigungskanäle für Aufträge | Kanäle, deren Auftragsbestätigungen die App übernimmt | 3. Klicken Sie auf **Erstellen**. Für die verbundenen Kanäle schaltet Workist die Ausgabedatei und den Upload ab, weil die App die Belege selbst abholt. Mit **Setup-Daten anzeigen** in der Zeile der Integration öffnen Sie die Angaben für die App: unter **Auth-Token** die API-Schlüssel, darunter je verbundenem Kanal die Kanal-ID und die Lookup-IDs. Ein Klick auf einen Wert kopiert ihn. **Auth-Token verwalten** führt zu den API-Integrationen, in denen Sie Schlüssel anlegen. An jedem übertragenen Beleg führt **In externer Anwendung öffnen** direkt zum Verkaufsauftrag bzw. bei Auftragsbestätigungen zur Einkaufsbestellung in Business Central. Dafür nutzt Workist die eingetragene Business Central-URL. ### Workist Integrator in Business Central einrichten Suchen Sie in Business Central nach **„Workist Integrator-Einrichtung"**. Dort finden Sie alle relevanten Einstellungen zur Workist-Integration. Die Werte, die Sie dort eintragen, kopieren Sie aus dem Dialog **Setup-Daten anzeigen** in der Workbench. ![Die Einrichtungsseite des Workist Integrator](/img/business-central/002-setup-page.png) ### 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. Vorhandene Schlüssel sehen Sie im Dialog **Setup-Daten anzeigen** unter **Auth-Token**. Wie Sie einen Token erstellen, beschreibt der Abschnitt [API-Schlüssel erstellen](/docs/api-documentation/quickstart.md#api-schluessel) 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 im Dialog **Setup-Daten anzeigen** als „Client-Lookup-ID“ finden. 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* ein („Artikel-Lookup-ID“ im Dialog **Setup-Daten anzeigen**) 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 („Debitorenartikel-Lookup-ID“ im Dialog **Setup-Daten anzeigen**) 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 und die Lieferantenartikelnummer als zweite Artikelnummer, sodass Workist die Artikelkennung des Lieferanten als alternativen Suchschlüssel erkennt. Kann bei der Auftrags- oder Rechnungsanlage eine Artikelnummer aus Workist 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 Angebotsreferenz, 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* ein. Sie steht nicht im Dialog **Setup-Daten anzeigen**, sondern in der Stammdatenkonfiguration des Kanals als „Angebotsabgleich-Lookup-ID“. Danach aktivieren Sie 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* ein („Rechnungsadressen-Lookup-ID“ im Dialog **Setup-Daten anzeigen**) und aktivieren anschließend die Synchronisierung der Rechnungsadressen (standardmäßig alle 1.440 Minuten, anpassbar). Die Synchronisierung sendet alle nicht gesperrten Debitoren als Rechnungsadressen an Workist. Die Debitorennummer (`No.`) dient dabei sowohl zur Zuordnung zum Kunden als auch als 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 fasst Straße und Hausnummer in einem Feld beliebiger Länge zusammen. 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 den Daten von Workist geschrieben (also wenn kein BC-Datensatzcode bzw. keine ID Vorrang hat), teilt der Integrator Straße und Hausnummer 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:** Sind Straße und Hausnummer 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 die Adressnummer der Lieferadresse aus Workist mit einer vorhandenen Lieferadresse (Ship-to Address) in Business Central überein, wird der Code auf den Verkaufsauftrag übernommen. 2. **Name und Adresszusatz:** Name und Adresszusatz der Lieferadresse 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. | Lieferadresse in Workist | BC-Feld | Immer übertragen | | --- | --- | --- | | Adressnummer | Ship-to Code | wenn Treffer gefunden | | Name | Ship-to Contact | ✓ ja | | Adresszusatz | Ship-to Name 2 | ✓ ja | | Straße und Hausnummer | Ship-to Address | wenn kein Code passt | | Postleitzahl | Ship-to Post Code | wenn kein Code passt | | Ort | 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](#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), meldet der Workist Integrator den Fehler an Workist zurück. Der Auftrag erscheint dann wieder unter den offenen Belegen in der Workbench, mit der Meldung aus Business Central. Die App ruft ihn nicht erneut ab. - **Automatische Wiederholung:** Gelingt die Rückmeldung an Workist nicht, wiederholt die App sie **bis zu fünfmal**. 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:** Fehlerantworten von Workist, Netzwerkfehler oder Zeitüberschreitungen sowie vorübergehende Nichtverfügbarkeit von Workist. Sind nach fünf Versuchen alle Wiederholungen erschöpft, gilt: 1. **Status in Workist:** Der Auftrag bleibt in Workist zur Abholung bereit und erscheint nicht unter den offenen Belegen. 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. ### Auftrag in Workist korrigieren Öffnen Sie einen abgelehnten Auftrag in der Workbench mit **Erneut assistieren**. Workist setzt dabei den Übertragungsstatus zurück. Korrigieren Sie den Auftrag bei Bedarf und schließen Sie ihn wieder ab. Der nächste Lauf des Auftragsimports in Business Central übernimmt ihn dann neu. Wird der Auftrag nicht mehr benötigt, verwerfen Sie ihn. ### 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:** Stammdatenprobleme in Business Central beheben (fehlende Kunden, Artikel usw.); den Auftrag in Workist korrigieren und erneut abschließen (siehe [Auftrag in Workist korrigieren](#auftrag-in-workist-korrigieren)); bei anhaltenden 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) 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. :::info 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](mailto:support@workist.com). ::: --- Source: https://docs.workist.com/docs/data-exchange/connectors/sap.md # SAP-Konnektor Der Workist SAP-Konnektor für SAP R/3, SAP ECC und SAP S/4HANA ist ein ABAP-Entwicklungspaket, das unser Partner **Syncwork AG** im Auftrag von Workist in Ihrem SAP-System installiert und einrichtet. Er überträgt die benötigten Stammdaten aus SAP an Workist und legt in der Workbench abgeschlossene Bestellungen als Kundenaufträge in SAP an. Für SAP Business One gibt es einen eigenen Konnektor ohne Installation in SAP, siehe [SAP Business One](/docs/data-exchange/connectors/sap-business-one.md). ## Überblick **Anforderungen an Ihr SAP** - SAP R/3, SAP ECC oder SAP S/4HANA (On-Premise oder Private Cloud Edition), in dem eigene ABAP-Entwicklungen installiert werden können. SAP S/4HANA Cloud Public Edition wird nicht unterstützt. Bei SAP R/3 klären Sie vor Projektstart mit Syncwork, ob Kernel und Kryptobibliothek Ihres Systems TLS 1.2 und SNI unterstützen. - Ausgehende HTTPS-Verbindungen mit TLS 1.2 oder höher und Server Name Indication (SNI), siehe [Kommunikation](#kommunikation). **Was Sie bereitstellen** | Angabe | Wofür | | --- | --- | | [Zugang für Syncwork](#zugang-für-syncwork) zu Entwicklungs- und Testsystem | Installation, Einrichtung und Wartung | | [Freigabe ausgehender HTTPS-Verbindungen](#kommunikation) zu `api.workist.com` und `documents.workist.com` | Datenaustausch mit Workist | | [Werte für die Auftragsanlage](#customizing-der-auftragsanlage) | Verkaufsbelegart, Verkaufsorganisation, Vertriebsweg, Sparte und weitere | | [Technischer Benutzer für die Hintergrundjobs](#hintergrundjobs) | Anlage der Kundenaufträge | | [Häufigkeit der Übertragung](#hintergrundjobs) | Einplanung der Hintergrundjobs | | Technischer Ansprechpartner | Hinweise zur Erneuerung der [Zertifikate](#zertifikate-strust) | **Was in Ihrem SAP eingerichtet wird** | Schritt | Transaktion | | --- | --- | | Entwicklungspaket installieren und transportieren | SE80, SE01, STMS | | Workist-Zertifikate importieren | STRUST | | Verbindungen zu Workist anlegen | SM59 | | Customizing der Auftragsanlage pflegen | SM30 | | Hintergrundjobs einplanen | SM36, SM37 | ## Funktionsweise Die beiden Programme des Pakets laufen als Hintergrundjobs in Ihrem SAP-System und bauen jede Verbindung selbst auf. Die Workist-Plattform verbindet sich nie mit Ihrem SAP. Workist und Syncwork arbeiten in Ihrem SAP nur über den Zugang, den Sie für Installation, Einrichtung und Wartung bereitstellen, siehe [Zugang für Syncwork](#zugang-für-syncwork). ![Architektur: Der Workist SAP-Konnektor in Ihrem SAP-System liest Stammdaten und legt Kundenaufträge an; alle Verbindungen zu api.workist.com und documents.workist.com gehen per HTTPS ausgehend von Ihrem SAP aus](/img/sap/architecture-de.png) - **Stammdaten:** Der Stammdatenversand liest die Stammdaten aus SAP und sendet sie über die Workist REST-API an Workist. Jeder Lauf überträgt die vollständige Auswahl. Preise werden nicht übertragen. - **Bestellungen:** Die Auftragsanlage ruft die in der Workbench abgeschlossenen Bestellungen ab und legt daraus Kundenaufträge an. Sofern nicht anders vereinbart, verwendet sie dafür den SAP-Baustein `BAPI_SALESORDER_CREATEFROMDAT2` und schreibt den Kundenauftrag nicht direkt in SAP-Standardtabellen. Der Kundenauftrag durchläuft damit die Standardverarbeitung von SAP wie bei der Erfassung in VA01, einschließlich Nummernvergabe und Unvollständigkeitsprüfung. Ihre eigenen Erweiterungen der Auftragsbearbeitung greifen, soweit sie auch ohne Dialog laufen. - **Dokumente:** Das Bestelldokument (PDF) und die Original-E-Mail werden an den Kundenauftrag angehängt. Wo die Anlagen in SAP abgelegt werden, stimmt Syncwork bei der Einrichtung mit Ihnen ab. - **Rückmeldung:** Nach der Anlage markiert der Konnektor die Bestellung in Workist als übertragen. Lehnt SAP den Auftrag ab, erscheint die Bestellung wieder in der Workbench, in der Regel mit der Meldung aus SAP, siehe [Meldungen aus SAP](#meldungen-aus-sap). Bei einigen Installationen stellt Workist die Bestellung zusätzlich als [SAP IDoc ORDERS05](/docs/output-formats/orders.md#sap-idoc) bereit, und der Konnektor verarbeitet sie in dieser Form. Welche Variante eingesetzt wird, stimmen Workist und Syncwork bei der Einrichtung mit Ihnen ab. ## Was wir aus SAP lesen | Stammdaten | Wofür in Workist | | --- | --- | | Auftraggeber | Kunden erkennen | | Warenempfänger | Lieferadresse zuordnen | | Rechnungsempfänger | Rechnungsadresse zuordnen | | Ansprechpartner (nach Absprache) | Besteller zuordnen | | Material | Artikel erkennen und zuordnen | | Kunden-Material-Infosatz | Artikelnummern Ihrer Kunden übersetzen | | Alternative Mengeneinheiten | Bestelleinheiten in Verkaufseinheiten umrechnen | Welche Datensätze übertragen werden, zum Beispiel nur bestimmte Verkaufsorganisationen oder Materialarten, und ob Ansprechpartner übertragen werden, legt Syncwork bei der Einrichtung mit Ihnen fest. Die Auswahl lässt sich später [anpassen](#anpassungen). Neu angelegte Kunden und Materialien kennt Workist ab dem nächsten Stammdatenlauf. ## Was wir in SAP schreiben | Objekt | Inhalt | | --- | --- | | Kundenauftrag | Kopfdaten, Partner und Positionen aus der verarbeiteten Bestellung; Vertriebsdaten aus dem [Customizing](#customizing-der-auftragsanlage) | | Anlagen am Kundenauftrag | Bestelldokument (PDF) und Original-E-Mail | | Protokolltabelle `ZWI_ORDER_DOC` | je angelegtem Auftrag: Debitor, Workist-Kanal, Workist-ID der Bestellung, Verkaufsbeleg, Datum, Uhrzeit, Benutzer | Der Konnektor legt nur neue Kundenaufträge an. Änderungen und Stornierungen bestehender Bestellungen überträgt er nicht: Wird eine Änderung als Bestellung abgeschlossen, von Hand oder automatisch, entsteht ein weiterer Kundenauftrag. Verwerfen Sie Änderungen und Stornierungen deshalb in der Workbench und bearbeiten Sie sie direkt in SAP. Ist bereits ein weiterer Kundenauftrag entstanden, stornieren Sie ihn dort. ## Was die Installation anlegt Syncwork installiert ein eigenes Entwicklungspaket im Kundennamensraum. Es enthält im Standard: - zwei Programme, eines für den Stammdatenversand und eines für die Auftragsanlage - eine Klasse mit der Logik zur Auftragsanlage und zum Anhängen der Dokumente - die Customizing-Tabelle `ZWI_SALES_ORDER` - die Protokolltabelle `ZWI_ORDER_DOC` mit den angelegten Aufträgen - die zugehörigen Dictionary-Objekte Je nach Projekt kommen weitere Customizing-Tabellen hinzu, etwa für die Stammdatenauswahl. Das Paket wird im Entwicklungssystem angelegt und über Ihre Transportlandschaft in Test- und Produktivsystem übernommen. ## Einrichtung Syncwork richtet den Konnektor im Entwicklungs- und Testsystem ein. Schritte, für die Syncwork keine Berechtigung erhält, zum Beispiel in STRUST oder SM59, übernimmt Ihre SAP-Basis. Wer das Produktivsystem einrichtet, stimmen Sie im Projekt ab. Zertifikate und Verbindungen gelten mandantenübergreifend und werden in jedem System eingerichtet. Customizing und Hintergrundjobs gelten je Mandant. :::warning Eigene Workist-Kanäle je System und Mandant Jedes SAP-System und jeder Mandant, der Bestellungen abruft, braucht eigene Workist-Kanäle. Rufen zwei Systeme denselben Kanal ab, landen Produktivaufträge im Testsystem oder werden doppelt angelegt. Senden zwei Systeme Stammdaten an dieselben Stammdaten-IDs, ersetzt jeder Lauf die Stammdaten des anderen. Passen Sie nach einer Kopie des Produktivsystems die Kanal-IDs und Stammdaten-IDs in der Kopie an, bevor die Jobs dort wieder laufen. ::: ### Zugang für Syncwork Für Installation und Einrichtung, später auch für Wartung und Anpassungen, benötigen die Syncwork-Berater: - VPN-Zugang zu Ihrem Entwicklungs- und Testsystem oder einen bereitgestellten Rechner mit diesem Zugang - je einen SAP-Benutzer mit Entwicklungsberechtigung, in SAP R/3 und ECC zusätzlich mit Entwicklerschlüssel - Zugriff auf diese Transaktionen: | Transaktion | Zweck | Bedarf | | --- | --- | --- | | SE80 | Entwicklung | erforderlich | | SE16 | Tabelleninhalte prüfen | erforderlich | | SM59 | Verbindungen anlegen | empfohlen | | SE01 | Transportaufträge anlegen | empfohlen | | STMS | Transport vom Entwicklungs- ins Testsystem | empfohlen | | STRUST | Zertifikate importieren | empfohlen | | SM30 | Customizing der Auftragsanlage pflegen | empfohlen | | SM36, SM37 | Hintergrundjobs einplanen und prüfen | empfohlen | | VA05 | angelegte Kundenaufträge prüfen | empfohlen | Im Testsystem benötigen die Syncwork-Berater zusätzlich eine Debugger-Berechtigung, nach Möglichkeit mit der Berechtigung, Feldwerte zu ändern. Übernimmt Syncwork die Einrichtung im Produktivsystem, braucht Syncwork auch dort einen Zugang. Für Einrichtung und Support erhalten die Syncwork-Berater außerdem einen Benutzer in Ihrem Workist-Konto. Die Namen der Berater nennen wir Ihnen im Kick-off. ### Kommunikation Der Konnektor verbindet sich ausschließlich ausgehend per HTTPS: | Host | Port | Wofür | | --- | --- | --- | | `api.workist.com` | 443 | Stammdaten senden, Bestellungen abrufen und zurückmelden | | `documents.workist.com` | 443 | Bestelldokument, E-Mail und gegebenenfalls IDoc abrufen | - Für den Datenaustausch sind keine eingehenden Verbindungen zu Ihrem SAP nötig. - Geben Sie die Hosts über den Namen frei, nicht über IP-Adressen, weil sich diese ändern können. Die Freigabe gilt für alle Anwendungsserver, auf denen die Hintergrundjobs laufen können. Ohne Proxy müssen diese die Namen per DNS auflösen können. - Geht Ihr SAP nur über einen Proxy ins Internet, wird dieser in den Verbindungen oder zentral über **Globale Konfiguration** in SM59 hinterlegt. Bricht Ihr Proxy TLS-Verbindungen zur Prüfung auf, nehmen Sie die beiden Workist-Hosts davon aus. - Beide Hosts setzen TLS 1.2 oder höher und Server Name Indication (SNI) voraus. Ohne SNI liefert `documents.workist.com` ein fremdes Zertifikat, und `api.workist.com` nimmt die Verbindung nicht an. Ab Kernel-Release 7.77 ist SNI im Standard aktiv. Bei älteren Kernels schaltet Ihre SAP-Basis es ein, in der Regel mit dem Profilparameter `icm/HTTPS/client_sni_enabled = TRUE` (SAP-Hinweis 2124480), bei Kernel 7.21 und 7.22 gegebenenfalls mit `ssl/client_sni_enabled = TRUE` (SAP-Hinweis 2384290). Welcher Parameter und welcher Patch-Stand nötig sind, nennen die beiden Hinweise. - Ältere Systeme brauchen für TLS 1.2 gegebenenfalls eine aktuelle CommonCryptoLib und angepasste Werte im Profilparameter `ssl/client_ciphersuites` (SAP-Hinweis 510007). `documents.workist.com` nimmt nur Cipher-Suites mit ECDHE an. ### Zertifikate (STRUST) Damit SAP den Workist-Servern vertraut, werden in der Transaktion STRUST die Zertifikate beider Workist-Hosts in die Zertifikatsliste der PSE **SSL-Client (Standard)** aufgenommen: den Knoten der PSE selbst wählen, nicht einen einzelnen Anwendungsserver, dann **Zertifikat importieren**, **In Zert.-Liste aufnehmen** und **Sichern**. Bis SAP NetWeaver 7.01 wird die Änderung erst nach einem Neustart des ICM (SMICM) wirksam. | Zertifikat | Gültig bis | | --- | --- | | [api.workist.com](/files/sap/api-workist-com.crt) | 28.03.2027 | | [documents.workist.com](/files/sap/documents-workist-com.crt) | 28.03.2027 | SHA-256-Fingerabdrücke zum Abgleich: ```text api.workist.com 1A:51:8E:DD:1E:20:1D:1C:1F:21:1D:F7:29:34:6A:10:38:C8:EB:54:31:EE:5E:59:7B:B0:42:74:40:A2:4E:3A documents.workist.com F0:A3:10:E7:E6:C1:4A:B8:F1:6D:88:A6:40:69:54:D1:B3:DB:E9:E8:C2:C0:3D:A6:19:A2:77:FE:5B:0C:5C:0A ``` :::warning Zertifikate rechtzeitig erneuern Die Serverzertifikate sind nur wenige Monate gültig, und ihre Laufzeit sinkt bis 2029 schrittweise auf 47 Tage. Vor jeder geplanten Erneuerung informieren wir den technischen Ansprechpartner, den Sie uns im Projekt nennen, und stellen die neuen Zertifikate bereit. Widerruft die Zertifizierungsstelle ein Zertifikat vorzeitig, kann die Frist kurz sein. Importieren Sie die neuen Zertifikate vor der angekündigten Umstellung und behalten Sie die bisherigen bis dahin in der Liste, sonst kann Ihr SAP keine Verbindung zu Workist aufbauen. ::: ### Verbindungen (SM59) Unter **HTTP-Verbindungen zu ext. Server** werden die Verbindungen zu beiden Workist-Hosts mit diesen Einstellungen angelegt: | Einstellung | Wert | | --- | --- | | Verbindungstyp | G – HTTP-Verbindung zu ext. Server | | Host | `api.workist.com` bzw. `documents.workist.com` | | Port | 443 | | Anmeldung mit Benutzer | Keinen Benutzer verwenden | | SSL | aktiv, SSL-Zertifikat **DFAULT SSL-Client (Standard)** | | HTTP-Version | HTTP 1.1 | Prüfen Sie jede Verbindung mit **Verbindungstest**. Jeder HTTP-Statuscode von Workist, auch 400 oder 404, zeigt, dass Zertifikat und TLS stimmen. Läuft die Verbindung über einen Proxy, kann der Statuscode auch vom Proxy stammen, zum Beispiel 407, wenn die Anmeldung am Proxy fehlt. Eine SSL-Fehlermeldung weist auf ein fehlendes Zertifikat, fehlendes SNI, fehlende Unterstützung für TLS 1.2 oder die nötigen Cipher-Suites oder einen Proxy hin, der TLS-Verbindungen aufbricht. ### API-Schlüssel Der Konnektor authentifiziert sich an `api.workist.com` mit einem API-Schlüssel, den er bei jeder Anfrage mitsendet. Dokumente ruft er über zeitlich begrenzte, signierte Links von `documents.workist.com` ab. In den Verbindungen wird deshalb kein Benutzer hinterlegt. Der Schlüssel gehört zu Ihrem Workist-Konto. In der Workbench unter **API-Integrationen** sehen Benutzer mit Berechtigung für Integrationen die Integration des Konnektors. Ist sie auf einzelne Kanäle beschränkt, ruft der Konnektor nur deren Bestellungen ab. Wird dort der Schlüssel erneuert oder die Integration gelöscht, überträgt der Konnektor nichts mehr, bis ein neuer Schlüssel im Konnektor hinterlegt ist. Stimmen Sie beides deshalb vorab mit Workist ab. Legen Sie für diese Integration kein Ablaufdatum fest, sonst stoppt die Übertragung an diesem Tag. ### Customizing der Auftragsanlage In der Tabelle `ZWI_SALES_ORDER` (Pflege über SM30) wird festgelegt, mit welchen Vertriebsdaten die Kundenaufträge angelegt werden. Die Werte liefern Sie, die Einträge legt Syncwork bei der Einrichtung an. Schlüssel eines Eintrags sind der Auftraggeber und der Workist-Kanal. Ein Kanal entspricht in der Regel einer Verkaufsorganisation. | Feld | Bedeutung | Hinweis | | --- | --- | --- | | `KUNNR` | Debitor | Schlüssel, Debitorennummer des Auftraggebers | | `CHANNEL` | Workist-Kanal | Schlüssel, Kanal-ID aus Workist | | `AUART` | Verkaufsbelegart | für jeden Auftrag erforderlich | | `VKORG` | Verkaufsorganisation | für jeden Auftrag erforderlich | | `VTWEG` | Vertriebsweg | für jeden Auftrag erforderlich | | `SPART` | Sparte | für jeden Auftrag erforderlich | | `WAERS` | Währung | | | `ISOCD` | ISO-Code der Währung | | | `WERKS` | Werk | nach Möglichkeit pflegen, damit der Auftrag in sich konsistent ist | | `PROFIT_CTR` | Profitcenter | | | `LIFSK` | Liefersperre | | `ZWI_SALES_ORDER` ist eine mandantenabhängige Customizing-Tabelle. Ob die Einträge per Customizing-Auftrag übernommen oder in jedem System direkt gepflegt werden, legt Syncwork bei der Einrichtung mit Ihnen fest. In jedem Mandanten stehen dort die Workist-Kanäle, die dieser Mandant abruft. ### Hintergrundjobs Die beiden Programme laufen als Hintergrundjobs mit Programmvarianten, die Syncwork bei der Einrichtung anlegt. Eingeplant werden sie in SM36, die Läufe sehen Sie in SM37. Die Jobs laufen unter dem SAP-Benutzer, der beim Einplanen im Jobschritt eingetragen wird. Dafür stellen Sie in der Regel einen technischen Benutzer (Benutzertyp System) bereit. Er legt die Kundenaufträge an, erscheint darin als Erfasser und braucht deshalb die Berechtigung, Kundenaufträge für die hinterlegten Verkaufsbelegarten und Verkaufsbereiche (Verkaufsorganisation, Vertriebsweg, Sparte) anzulegen. Die weiteren Berechtigungen stimmt Syncwork bei der Einrichtung mit Ihrer SAP-Basis ab. Wie oft Stammdaten und Bestellungen übertragen werden, legen Sie fest. Bewährt haben sich ein täglicher Stammdatenlauf und ein Auftragslauf alle 5 bis 15 Minuten. SM36 verhindert nicht von selbst, dass ein periodischer Job startet, während der vorige Lauf noch aktiv ist. Wählen Sie den Abstand deshalb deutlich größer als die Laufzeiten, die SM37 für den Auftragsjob zeigt. ## Betrieb ### Meldungen aus SAP Kann SAP einen Auftrag nicht anlegen, meldet der Konnektor das an Workist zurück. Die Bestellung erscheint dann wieder unter den offenen Bestellungen in der Workbench, in der Regel mit der Meldung aus SAP, und wird nicht automatisch erneut übertragen. Liegt die Ursache in SAP, zum Beispiel in den Stammdaten, beheben Sie sie dort. Öffnen Sie die Bestellung anschließend erneut zur Bearbeitung, korrigieren Sie sie bei Bedarf und schließen Sie sie wieder ab. Der nächste Lauf überträgt sie neu. Wird der Auftrag nicht mehr benötigt, verwerfen Sie die Bestellung. Die Meldungen stammen aus Ihrem SAP-System: aus dem SAP-Standard oder aus Prüfungen, die Ihre IT eingerichtet hat. Erster Ansprechpartner ist deshalb Ihre SAP-IT. Lässt sich eine Meldung nicht einordnen, schreiben Sie an [support@workist.com](mailto:support@workist.com). Wir ziehen Syncwork hinzu. Kommen abgeschlossene Bestellungen nicht in SAP an und zeigt die Workbench keine Meldung, prüfen Sie die Jobläufe in SM37. Mögliche Ursachen sind ein Job, der nicht läuft, oder eine Verbindung, die scheitert, zum Beispiel wegen eines Zertifikats oder eines ungültigen API-Schlüssels. ### Wartung Das Paket wird von Syncwork im Auftrag von Workist gewartet. Neue Workist-Serverzertifikate importieren Sie selbst vor der angekündigten Umstellung, siehe [Zertifikate (STRUST)](#zertifikate-strust). Planen Sie ein Upgrade Ihres SAP-Systems oder eine Umstellung auf SAP S/4HANA, informieren Sie Ihren Workist-Ansprechpartner rechtzeitig, damit Syncwork das Paket vorab prüfen kann. Für einen weiteren Workist-Kanal legt Workist den Kanal an, gibt ihn für die API-Integration des Konnektors frei und nennt Ihnen die Kanal-ID. Hinterlegen Sie sie in Ihrem SAP selbst oder mit Syncwork. ### Anpassungen Zusätzliche Felder oder abweichende Logik bei der Auftragsanlage sind möglich. Je nach Anforderung passt Workist die Verarbeitung in Workist an oder Syncwork das Paket in Ihrem SAP, oft beides. Auch Änderungen an den Feldern eines Workist-Kanals stimmen Sie vorab mit Workist ab, weil der Konnektor die Bestelldaten in einer festen Struktur erwartet. Sprechen Sie dafür Ihren Workist-Ansprechpartner an oder schreiben Sie an [support@workist.com](mailto:support@workist.com). Wir klären mit Ihnen Umsetzung und Aufwand. --- Source: https://docs.workist.com/docs/data-exchange/connectors/sap-business-one.md # SAP Business One Workist verbindet sich über den Service Layer von SAP Business One mit Ihrer Firmendatenbank. Workist liest Geschäftspartner und Artikel als Stammdaten und legt abgeschlossene Bestellungen als Kundenaufträge an. In SAP Business One wird nichts installiert. Diese Seite gilt für SAP Business One. Für SAP ECC und SAP S/4HANA siehe [SAP-Konnektor](/docs/data-exchange/connectors/sap.md). ## Überblick **Voraussetzungen** - SAP Business One mit Service Layer. Workist muss den Service Layer über das Internet erreichen. - Ein Service-Layer-Benutzer, der Geschäftspartner, Artikel und Katalognummern lesen sowie Kundenaufträge und Anlagen anlegen darf. - Die Auftragsanlage ist derzeit auf eine bestimmte Feldstruktur in SAP Business One abgestimmt. Stimmen Sie die Einrichtung deshalb vorab mit Ihrer Ansprechperson bei Workist ab. **Datenfluss** | Richtung | Inhalt | Zeitpunkt | | --- | --- | --- | | SAP Business One → Workist | Geschäftspartner, Ansprechpartner, Adressen, Artikel, Katalognummern | täglich um 01:30 UTC und auf Knopfdruck | | Workist → SAP Business One | Kundenauftrag mit Positionen und Anlagen | sobald eine Bestellung abgeschlossen ist | ## Was wir aus SAP Business One lesen | Stammdaten in Workist | Quelle in SAP Business One | | --- | --- | | [Kunden](/docs/master-data/customers.md) | Geschäftspartner (Kunden) | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | Ansprechpartner der Geschäftspartner | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Adressen der Geschäftspartner vom Typ Lieferadresse (`bo_ShipTo`) | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Adressen der Geschäftspartner vom Typ Rechnungsadresse (`bo_BillTo`) | | [Artikel](/docs/master-data/articles.md) | Artikel | | [Kundenspezifische Artikelnummern](/docs/master-data/articles.md) | Katalognummern der Geschäftspartner (`AlternateCatNum`) | - Mit den Filterabfragen der Integration grenzen Sie ein, welche Geschäftspartner und Artikel Workist liest. Ohne Filter liest Workist alle. - Preise, Einheitenumrechnungen, Rahmenverträge und Angebote liest Workist nicht aus SAP Business One. - Geschäftspartner ohne Automatisierungskennzeichen: Tragen Sie in der Integration eine Geschäftspartner-Eigenschaft ein (zum Beispiel `Properties50`) und einen Text. Geschäftspartner, bei denen diese Eigenschaft nicht gesetzt ist, erhalten den Text als interne Notiz in den Workist-Stammdaten. Ist die Prüfung „Kundeninterne Notiz“ im Kanal aktiv, gehen ihre Bestellungen in die manuelle Bearbeitung, siehe [Prüfungen](/docs/channel-configuration/document-processing/validation-checks.md). Welche Felder Workist im Einzelnen übernimmt, steht in der [Feldreferenz](#feldreferenz). ## Was wir in SAP Business One schreiben Für jede abgeschlossene Bestellung legt Workist einen Kundenauftrag an: - **Kopf**: Kunde, Bestellnummer, Bestelldatum, Lieferdatum, Kundenkontakt, Hinweistext und die Liefer- und Rechnungsadresse. - **Positionen**: Artikelnummer und Menge. Den Preis setzt SAP Business One. Ausnahmen: Ist beim Geschäftspartner die Eigenschaft 51 gesetzt, übernimmt Workist den Einzelpreis aus dem Dokument. Ist „Preise bei Auftragserstellung mit der API berechnen?“ aktiv, fragt Workist Preis und Rabatt bei der Preisfindung von SAP Business One ab und schreibt sie in die Position. - **Adressen**: Hat Workist die Adresse einer Adress-ID aus den Stammdaten zugeordnet, verweist der Auftrag auf diese Adresse. Sonst überträgt Workist die Adresse als Text in den Auftrag. Enthält das Dokument keine Adresse, nimmt Workist die Standardadresse des Geschäftspartners. - **Anlagen**: Auf Wunsch hängt Workist das Bestelldokument an den Auftrag. Die Original-E-Mail und einen mitgeschickten Lieferschein hängt Workist an, wenn Sie dafür einen Dokumentennamen eintragen. - Der Auftrag wird als nicht bestätigt angelegt. Als Referenz am Beleg in der Workbench speichert Workist den internen Schlüssel des Kundenauftrags (`DocEntry`), nicht die in SAP Business One angezeigte Belegnummer. Workist legt nur neue Kundenaufträge an und ändert keine bestehenden Belege. ## Einrichtung in der Workbench 1. Öffnen Sie **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** und klicken Sie bei SAP Business One auf **Verbinden**. 2. Tragen Sie die Verbindung ein: | Feld | Inhalt | | --- | --- | | Name der Integration | frei wählbar | | Service Layer URL | Adresse Ihres Service Layers | | SAP Business One Firmen-DB | Name der Firmendatenbank | | Service Layer Benutzer, Service Layer Passwort | Zugang des Service-Layer-Benutzers | | Bestellungskanäle | Kanäle, deren Bestellungen als Kundenaufträge angelegt werden | 3. Optional: | Feld | Wirkung | | --- | --- | | Filterabfrage, um die zu synchronisierenden Kunden zu filtern | Filter für die Geschäftspartner, die Workist liest | | Filterabfrage, um die zu synchronisierenden Artikel zu filtern | Filter für die Artikel, die Workist liest | | Liefertermine in der Vergangenheit vermeiden | fehlt das Lieferdatum oder liegt es in der Vergangenheit, setzt Workist den nächsten Tag | | Preise bei Auftragserstellung mit der API berechnen? | Workist fragt beim Anlegen für jede Position Preis und Rabatt aus der Preisfindung von SAP Business One ab | | Standardversandmethode für den Positionseintrag überschreiben | Versandart, die Workist in jede Position schreibt | | Geschäftspartner-Eigenschaft und Text für nicht automatisierte Geschäftspartner | siehe [Was wir aus SAP Business One lesen](#was-wir-aus-sap-business-one-lesen) | | Originalbestellung zu Business One hochladen? | hängt das Bestelldokument an den Auftrag | | Benutzerdefinierter Dokumentenname für E-Mails bzw. für Lieferscheine zum Hochladen | hängt zusätzlich die Original-E-Mail bzw. einen mitgeschickten Lieferschein an | | Benutzerdefiniertes Dokumententyp-Feld in Business One | schreibt den jeweiligen Dokumentennamen (Bestellung, E-Mail, Lieferschein) in dieses Feld der Anlage | 4. Klicken Sie auf **Erstellen**. Mit **Stammdaten Update starten** laden Sie die Stammdaten sofort. Wie die Stammdaten in den Kanälen ankommen und wie Workist die Kanäle umstellt, steht unter [Was alle Konnektoren gemeinsam haben](/docs/data-exchange/connectors.md#common-behaviour). ## Fehlerbehandlung Lehnt SAP Business One den Kundenauftrag ab, erscheint die Bestellung wieder unter den offenen Belegen, mit der Meldung des Service Layers. Workist versucht es nicht automatisch erneut. Beheben Sie die Ursache und schließen Sie die Bestellung nach **Erneut assistieren** wieder ab. Kann Workist die Preisfindung beim Anlegen nicht abfragen, legt Workist den Auftrag trotzdem an. Den Preis setzt dann SAP Business One. ## Einschränkungen - Workist überträgt nur Bestellungen. Anfragen, Rechnungen und andere Belegarten unterstützt der Konnektor nicht. - Workist prüft vor dem Anlegen nicht, ob es zur Bestellung schon einen Kundenauftrag gibt. Wird eine Bestellung erneut abgeschlossen, entsteht ein weiterer Kundenauftrag. ## Feldreferenz ### Gelesene Felder #### Kunden | Workist-Spalte | Aus SAP Business One | | --- | --- | | `client_id1` | `CardCode` | | `internal_note` | Text aus der Einstellung für nicht automatisierte Geschäftspartner, wenn die dort genannte Eigenschaft beim Geschäftspartner nicht gesetzt ist | | `client_contact_person1` | `MailAddress` | | `company_name` | `CardName` | | `address1` | `Address` | | `address2` | `MailAddress` | | `zip_code` | `ZipCode` | | `city` | `City` | | `country_subdivision` | `County` | | `country` | `Country` | | `extra_data` | benutzerdefinierte Felder (`U_…`), Standard-Rechnungsadresse (`BilltoDefault`), Standard-Lieferadresse (`ShipToDefault`), Eigenschaften 11, 51 und 52 | #### Kundenkontakte | Workist-Spalte | Aus SAP Business One | | --- | --- | | `partition_id` | `CardCode` | | `contact_id` | `InternalCode` | | `first_name` | `FirstName` | | `last_name` | `LastName` | | `phone` | `Phone1` | | `email` | `E_Mail` | #### Liefer- und Rechnungsadressen Beide Adressarten haben dieselben Felder. | Workist-Spalte | Aus SAP Business One | | --- | --- | | `partition_id` | `BPCode` | | `address_id1` | `AddressName` | | `address_id2` | `GlobalLocationNumber` | | `name` | `AddressName2` | | `address1` | `Street` + `StreetNo` | | `zip_code` | `ZipCode` | | `city` | `City` | | `country_subdivision` | `County` | | `country` | `Country` | | `misc` | `BuildingFloorRoom` | #### Artikel | Workist-Spalte | Aus SAP Business One | | --- | --- | | `article_id1` | `ItemCode` | | `description` | `ItemName` + `User_Text` | | `description_boosted` | `User_Text` – sonst `ItemName` | | `order_units` | `SalesUnit` | | `sales_units` | `SalesUnit` | | `extra_data` | benutzerdefinierte Felder (`U_…`), Eigenschaft 12 | #### Kundenspezifische Artikelnummern | Workist-Spalte | Aus SAP Business One | | --- | --- | | `partition_id` | `CardCode` | | `article_id1` | `ItemCode` | | `article_id2` | `Substitute` | | `description` | `ItemName` + `User_Text` | | `description_boosted` | `ItemName` | | `order_units` | `SalesUnit` | | `sales_units` | `SalesUnit` | | `extra_data` | benutzerdefinierte Felder (`U_…`), Eigenschaft 12 | ### Geschriebene Felder Aufgeführt sind die Felder, die Workist befüllt. Belegnummer, Preise ohne Preisfindung, Summen und Steuern setzt SAP Business One selbst. #### Kundenauftrag – Kopf | Feld im Kundenauftrag | Inhalt | | --- | --- | | `AttachmentEntry` | Anlage mit dem Bestelldokument (nur wenn „Originalbestellung zu Business One hochladen?“ aktiv ist); Original-E-Mail und mitgeschickter Lieferschein, wenn dafür ein Dokumentenname eingetragen ist | | `DocDate` | Bestelldatum | | `TaxDate` | Eingangsdatum des Dokuments in Workist | | `DocDueDate` | Lieferdatum. Mit „Liefertermine in der Vergangenheit vermeiden“: der nächste Tag, wenn das Lieferdatum fehlt oder in der Vergangenheit liegt | | `CardCode` | Kunde (Kundennummer) | | `NumAtCard` | Bestellnummer | | `ContactPersonCode` | Kundenkontakt, wenn zugeordnet | | `Confirmed` | fest: `N` (nicht bestätigt) | | `Comments` | Hinweis Text, wenn vorhanden | | `BillToCode` | Standard-Rechnungsadresse des Geschäftspartners, wenn das Dokument keine Rechnungsadresse enthält | | `PayToCode` | Rechnungsadresse (Adress-ID aus den Stammdaten) – sonst die Standard-Rechnungsadresse des Geschäftspartners | | `ShipToCode` | Lieferadresse (Adress-ID aus den Stammdaten) – sonst die Standard-Lieferadresse des Geschäftspartners | #### Kundenauftrag – Positionen | Feld in der Position | Inhalt | | --- | --- | | `LineNum` | Position (fortlaufend ab 0) | | `ItemCode` | Artikelnummer | | `Quantity` | Menge | | `UnitPrice` | Einzelpreis aus dem Dokument, wenn beim Geschäftspartner die Eigenschaft 51 gesetzt ist – sonst Preis aus der Preisfindung von SAP Business One (nur mit „Preise bei Auftragserstellung mit der API berechnen?“) – sonst setzt SAP Business One den Preis | | `DiscountPercent` | Rabatt aus derselben Preisfindung | | `ShippingMethod` | Wert aus „Standardversandmethode für den Positionseintrag überschreiben“, wenn gesetzt | #### Kundenauftrag – Adresse als Text Nur wenn die Adresse im Dokument keiner Adress-ID aus den Stammdaten zugeordnet ist. | Feld | Inhalt | | --- | --- | | `BillToStreet` / `ShipToStreet` | Straße und Hausnummer | | `BillToCity` / `ShipToCity` | Ort | | `BillToZipCode` / `ShipToZipCode` | Postleitzahl | | `BillToCountry` / `ShipToCountry` | Land | | `BillToAddress2` / `ShipToAddress2` | Firmenname | | `BillToAddress3` / `ShipToAddress3` | Name | --- Source: https://docs.workist.com/docs/data-exchange/connectors/dynamics-365-finance-operations.md # Microsoft Dynamics 365 Finance & Operations Workist verbindet sich über die Datenentitäten von Dynamics 365 Finance & Operations (F&O) mit Ihrer Umgebung. Workist liest Debitoren und freigegebene Produkte als Stammdaten, legt abgeschlossene Bestellungen als Verkaufsaufträge an und Anfragen als Verkaufsangebote. In F&O wird nichts installiert. ## Überblick **Voraussetzungen** - Eine App-Registrierung in Microsoft Entra ID mit Client-Secret. Workist meldet sich damit ohne Benutzerinteraktion an. - Die App ist in F&O als Anwendung freigegeben und einem Benutzer zugeordnet, der diese Datenentitäten nutzen darf: - lesen: `CustomersV3`, `ContactPersons`, `CDSCustomerContactPersons`, `CustomerPostalAddresses`, `CDSReleasedDistinctProducts`, `CustomerProductDescriptionsV2` - anlegen: `SalesOrderHeadersV2` bzw. `SalesOrderHeadersV4`, `SalesOrderLines`, `SalesOrderHeaderDocumentAttachmentsV2`, `SalesQuotationHeaders`, `SalesQuotationLines` - löschen: `SalesOrderHeadersV2` bzw. `SalesOrderHeadersV4`, damit Workist einen unvollständigen Auftrag zurücknehmen kann - Workist muss Ihre F&O-Umgebung über das Internet erreichen, direkt oder über ein API-Gateway. **Datenfluss** | Richtung | Inhalt | Zeitpunkt | | --- | --- | --- | | F&O → Workist | Debitoren, Kontaktpersonen, Postadressen, freigegebene Produkte, externe Artikelnummern | täglich um 06:00 Uhr deutscher Zeit und auf Knopfdruck | | Workist → F&O | Verkaufsauftrag mit Positionen, Bestelldokument (PDF) und Original-E-Mail | sobald eine Bestellung abgeschlossen ist | | Workist → F&O | Verkaufsangebot mit Positionen | sobald eine Anfrage abgeschlossen ist | ## Was wir aus Finance & Operations lesen | Stammdaten in Workist | Quelle in Finance & Operations | Datenentitäten | | --- | --- | --- | | [Kunden](/docs/master-data/customers.md) | Debitoren | `CustomersV3`, `ContactPersons`, `CDSCustomerContactPersons` | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | Kontaktpersonen der Debitoren | `ContactPersons`, `CDSCustomerContactPersons` | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Postadressen der Debitoren | `CustomerPostalAddresses` | | [Artikel](/docs/master-data/articles.md) | Freigegebene Produkte | `CDSReleasedDistinctProducts` | | [Kundenspezifische Artikelnummern](/docs/master-data/articles.md) | Externe Artikelnummern der Debitoren (nur einem Debitor zugeordnete, nicht Debitorengruppen) | `CustomerProductDescriptionsV2` | - Ist in der Integration eine Data Area ID eingetragen, liest Workist nur diese juristische Person. Ohne Data Area ID liest Workist alle. - Mit den Optionen der Integration lassen sich die Produkte eingrenzen: nur Lagerartikel (`IsStockedProduct` = Ja) und nur Produkte, bei denen Verkaufs- und Lagereinheit gepflegt sind. - Rechnungsadressen, Einheitenumrechnungen, Rahmenverträge und Angebote liest Workist nicht aus F&O. Welche Felder Workist im Einzelnen übernimmt, steht in der [Feldreferenz](#feldreferenz). ## Was wir in Finance & Operations schreiben **Verkaufsauftrag** (aus Bestellungen) 1. Workist legt den Auftragskopf an: Debitor, Bestellnummer als Bestellanforderung des Kunden, Lieferadresse, Kundenkontakt und Lieferdatum. 2. Workist legt die Positionen an: Artikelnummer, Menge, Einheit, Produktdimensionen aus den Artikel-Stammdaten und Lieferdatum. Preise ermittelt F&O selbst. 3. Workist hängt das Bestelldokument (PDF) und, bei E-Mail-Eingang, die Original-E-Mail (.eml) an den Auftrag. Auf Wunsch hält Workist jeden Auftrag in F&O an (`IsSalesProcessingStopped`), damit er vor der Weiterverarbeitung geprüft wird. **Verkaufsangebot** (aus Anfragen) Workist legt den Angebotskopf mit dem Debitor an und danach die Positionen mit Artikelnummer, Menge, Einheit und Produktdimensionen. **Daten im Detail** - Lieferdaten überträgt Workist nur, wenn das Feld im Kanal aktiviert ist. Liegt ein Lieferdatum in der Vergangenheit, setzt Workist das heutige Datum, weil F&O Daten in der Vergangenheit ablehnt. - Die juristische Person (Data Area ID) nimmt Workist aus den Kunden-Stammdaten, sonst aus der Integration. - Als Referenz am Beleg in der Workbench speichert Workist die Auftrags- bzw. Angebotsnummer aus F&O. Über **In externer Anwendung öffnen** springen Sie direkt zum Auftrag bzw. Angebot in F&O. ## Einrichtung in der Workbench 1. Legen Sie die App-Registrierung in Microsoft Entra ID an und geben Sie die App in F&O frei (siehe [Voraussetzungen](#überblick)). 2. Öffnen Sie in der Workbench **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** und klicken Sie bei Microsoft Dynamics 365 Finance and Operations auf **Verbinden**. 3. Tragen Sie die Verbindung ein: | Feld | Inhalt | | --- | --- | | Name der Integration | frei wählbar | | Tenant-ID | ID Ihres Entra-ID-Mandanten | | Umgebungs-URL | URL Ihrer F&O-Umgebung | | API Data URL (optional) | Adresse eines API-Gateways vor F&O; leer lassen, wenn Workist direkt auf die Umgebung zugreift | | Client-ID (in der deutschen Oberfläche „Mandanten-ID (Anwendungs-ID)“), Client-Secret | aus der App-Registrierung | | Datenbereichs-ID | juristische Person, zum Beispiel `usmf` | | Bestellungskanäle | Kanäle, deren Bestellungen als Verkaufsaufträge angelegt werden | | Kanäle für Angebotsanfragen | Kanäle, deren Anfragen als Verkaufsangebote angelegt werden | 4. Optional: | Option | Wirkung | | --- | --- | | Nur Artikel importieren, bei denen IsStockedProduct auf "Ja" gesetzt ist | liest nur Lagerartikel | | Nur Artikel importieren, bei denen sowohl SalesUnitSymbol als auch InventoryUnitSymbol gesetzt sind | liest nur Produkte mit Verkaufs- und Lagereinheit | | Articles have multiple versions | für Produkte mit mehreren Versionen: Workist nutzt die versionierte Produktnummer als Artikelnummer und überträgt die Artikelnummer 2 | | Sales order header entity | V2 (Standard) oder V4; V4 kennt zusätzlich Auftragserfasser und Retail-Kanal | | Order taker personnel number, Retail channel RecId | Personalnummer des Auftragserfassers bzw. Retail-Kanal für jeden Auftrag (nur mit V4) | | Put every pushed sales order on hold in F&O | setzt jeden Auftrag auf angehalten | | Delete the sales order again if creating its lines fails | Standard: an. Siehe [Fehlerbehandlung](#fehlerbehandlung) | | Delete the whole sales order if uploading an attachment (PDF/email) fails | Standard: aus. Siehe [Fehlerbehandlung](#fehlerbehandlung) | | Disable master data transfer | Workist liest keine Stammdaten aus F&O, weder geplant noch auf Knopfdruck | 5. Klicken Sie auf **Erstellen**. Mit **Stammdaten Update starten** laden Sie die Stammdaten sofort. Wie die Stammdaten in den Kanälen ankommen und wie Workist die Kanäle umstellt, steht unter [Was alle Konnektoren gemeinsam haben](/docs/data-exchange/connectors.md#common-behaviour). ## Fehlerbehandlung Lehnt F&O einen Beleg ab, erscheint er wieder unter den offenen Belegen, mit der Meldung aus F&O. Workist versucht es nicht automatisch erneut. Beheben Sie die Ursache und schließen Sie den Beleg nach **Erneut assistieren** wieder ab. - **Bestellung ohne Kundennummer**: Workist überträgt sie nicht und meldet den Fehler am Beleg. - **Fehler beim Anlegen einer Position**: Workist versucht alle Positionen und meldet jede fehlgeschlagene Position mit Artikelnummer. Danach löscht Workist den Auftrag wieder. Ist „Delete the sales order again if creating its lines fails“ aus, bleibt der unvollständige Auftrag in F&O stehen und seine Nummer steht am Beleg. Vervollständigen oder löschen Sie ihn dann in F&O, bevor Sie die Bestellung erneut abschließen. - **Fehler beim Anhängen von PDF oder E-Mail**: Im Standard bleibt der Auftrag bestehen und der Beleg gilt als übertragen; die Meldung steht am Beleg. Ist „Delete the whole sales order if uploading an attachment (PDF/email) fails“ an, löscht Workist den Auftrag und markiert den Beleg als fehlgeschlagen. - Kann Workist einen Auftrag nicht wieder löschen, steht ein Hinweis mit der Auftragsnummer am Beleg. Entfernen Sie den Auftrag dann von Hand. - **Fehlende Berechtigung**: Meldet F&O fehlende Rechte, steht das am Beleg. Ein erneuter Versuch hilft erst, wenn der Benutzer der App die Rechte hat. ## Einschränkungen - Verkaufsangebote legt Workist derzeit mit der Währung `USD` und der Sprache `en-US` an. - Scheitert eine Angebotsposition, löscht Workist das bereits angelegte Verkaufsangebot nicht. Es bleibt unvollständig in F&O stehen. - Workist prüft vor dem Anlegen nicht, ob es zur Bestellung schon einen Auftrag gibt. Wird eine Bestellung erneut abgeschlossen, entsteht ein weiterer Auftrag. ## Feldreferenz ### Gelesene Felder #### Kunden | Workist-Spalte | Aus Finance & Operations | | --- | --- | | `client_id1` | `CustomerAccount` | | `client_id2` | `PartyNumber` | | `client_contact_person1` | `FirstName` + `LastName` der ersten Kontaktperson des Debitors | | `company_name` | `OrganizationName` | | `address1` | `AddressStreet` | | `zip_code` | `AddressZipCode` | | `city` | `AddressCity` | | `country` | `AddressCountryRegionId` | | `extra_data` | `dataAreaId`, `EmployeeResponsibleNumber` | #### Kundenkontakte | Workist-Spalte | Aus Finance & Operations | | --- | --- | | `partition_id` | Debitorenkonto, dem die Kontaktperson zugeordnet ist (`CustomerAccountNumber`) | | `contact_id` | `ContactPersonId` – sonst `ContactPersonPartyNumber` | | `first_name` | `FirstName` | | `last_name` | `LastName` | | `phone` | `PrimaryPhoneNumber` | | `email` | `PrimaryEmailAddress` | #### Lieferadressen | Workist-Spalte | Aus Finance & Operations | | --- | --- | | `partition_id` | `CustomerAccountNumber` | | `address_id1` | `AddressLocationId` | | `name` | `AddressDescription` | | `address1` | `AddressStreet` | | `zip_code` | `AddressZipCode` | | `city` | `AddressCity` | | `country` | `AddressCountryRegionId` | #### Artikel | Workist-Spalte | Aus Finance & Operations | | --- | --- | | `article_id1` | `ItemNumber`; mit „Articles have multiple versions“: `ProductNumber` | | `article_id2` | `ProductNumber`; mit „Articles have multiple versions“: `ItemNumber` | | `description` | `ProductName`, ergänzt um Größe, Farbe, Stil und Version, wenn vorhanden | | `description_boosted` | `ProductDescription` | | `gross_price` | `SalesPrice` | | `order_units` | `SalesUnitSymbol` | | `sales_units` | `SalesUnitSymbol` | | `extra_data` | Produktdimensionen `ProductSizeId`, `ProductColorId`, `ProductStyleId`, `ProductVersionId`, `ProductConfigurationId` (gehen in die Auftragsposition) sowie `CurrencyCode`, `SalesUnitSymbol`, `SalesPrice`, `InventoryUnitSymbol`, `UnitCost`, `IsStockedProduct` | #### Kundenspezifische Artikelnummern | Workist-Spalte | Aus Finance & Operations | | --- | --- | | `partition_id` | `CustomerAccountNumber` | | `article_id1` | `ItemNumber` | | `article_id2` | `CustomerProductNumber` | | `description` | `CustomerProductDescription` | | `extra_data` | `ProductSizeId`, `ProductColorId`, `ProductVersionId`, `ProductStyleId`, `ProductConfigurationId`, `dataAreaId` | ### Geschriebene Felder Aufgeführt sind die Felder, die Workist befüllt. Auftrags- und Angebotsnummer, Preise, Summen und alle übrigen Felder setzt F&O selbst. #### Verkaufsauftrag – Kopf | Feld | Inhalt | | --- | --- | | `OrderingCustomerAccountNumber` | Kunde (Kundennummer) | | `dataAreaId` | Data Area ID aus den Kunden-Stammdaten – sonst „Data Area ID“ der Integration | | `DeliveryAddressLocationId` | Lieferadresse (Adress-ID aus den Stammdaten) | | `RequestedShippingDate` | Lieferdatum (Kopf); ein Datum in der Vergangenheit wird durch das heutige ersetzt | | `ContactPersonId` | Kundenkontakt, wenn zugeordnet | | `CustomerRequisitionNumber` | Bestellnummer | | `IsSalesProcessingStopped` | `Yes`, wenn „Put every pushed sales order on hold“ aktiv ist – sonst nicht gesendet | | `OrderTakerPersonnelNumber` | „Order taker personnel number“ (nur mit Kopf-Entität V4) | | `RetailChannelTable` | „Retail channel RecId“ (nur mit Kopf-Entität V4) | #### Verkaufsauftrag – Positionen | Feld | Inhalt | | --- | --- | | `ItemNumber` | Artikelnummer (mit „Articles have multiple versions“: Artikelnummer 2) | | `OrderedSalesQuantity` | Menge | | `SalesUnitSymbol` | Einheit | | `ProductSizeId` `ProductColorId` `ProductStyleId` `ProductVersionId` `ProductConfigurationId` | Produktdimension aus den Artikel-Stammdaten | | `RequestedShippingDate` | Lieferdatum der Position – sonst Lieferdatum des Kopfs | #### Verkaufsangebot – Kopf | Feld | Inhalt | | --- | --- | | `dataAreaId` | Data Area ID aus den Kunden-Stammdaten – sonst „Data Area ID“ der Integration | | `RequestingCustomerAccountNumber` | Kunde (Kundennummer) | | `CurrencyCode` | fest: `USD` | | `LanguageId` | fest: `en-US` | #### Verkaufsangebot – Positionen | Feld | Inhalt | | --- | --- | | `LineCreationSequenceNumber` | Position (fortlaufend ab 1) | | `ItemNumber` | Artikelnummer (mit „Articles have multiple versions“: Artikelnummer 2) | | `RequestedSalesQuantity` | Menge | | `SalesUnitSymbol` | Einheit | | `ProductColorId` `ProductSizeId` `ProductStyleId` `ProductVersionId` `ProductConfigurationId` | Produktdimension aus den Artikel-Stammdaten | --- Source: https://docs.workist.com/docs/data-exchange/connectors/microtech-buero-plus.md # microtech büro+ Workist verbindet sich über die GraphQL-Schnittstelle von microtech büro+ mit Ihrer Installation. Workist liest Adressen, Artikel und offene Angebote als Stammdaten und legt abgeschlossene Bestellungen und Anfragen als Vorgänge an. In büro+ wird nichts installiert. ## Überblick **Voraussetzungen** - microtech büro+ mit freigeschalteter GraphQL-Schnittstelle und einem Client (Client-ID und Client-Secret) für den Zugriff von Workist. - Workist muss die Schnittstelle Ihrer Installation erreichen. Wie die Verbindung hergestellt wird, stimmen Sie mit Ihrer Ansprechperson bei Workist ab. - Die Vorgangsarten, die Workist anlegen soll, zum Beispiel „Auftragsbestätigung“ und „Anfrage“, sind in büro+ eingerichtet. **Datenfluss** | Richtung | Inhalt | Zeitpunkt | | --- | --- | --- | | büro+ → Workist | Kunden, Ansprechpartner, Anschriften, Artikel, offene Angebote | täglich um 04:00 Uhr deutscher Zeit und auf Knopfdruck | | Workist → büro+ | Vorgang der eingestellten Vorgangsart mit Positionen, Bestelldokument (PDF) und Original-E-Mail | sobald eine Bestellung oder Anfrage abgeschlossen ist | ## Was wir aus microtech büro+ lesen | Stammdaten in Workist | Quelle in microtech büro+ | | --- | --- | | [Kunden](/docs/master-data/customers.md) | Adressen mit Kundenkennzeichen (`fnIsCustomer`) | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | Ansprechpartner | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Anschriften (alle Anschriften jeder Adresse) | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Anschriften (dieselben wie bei den Lieferadressen) | | [Artikel](/docs/master-data/articles.md) | Artikel | | [Offene Angebote](/docs/master-data/quotes.md) | Offene Vorgänge der Vorgangsart aus „Angebot Sync Vorgangsart“, je Position | - Workist liest alle Artikel, auch als historisch gekennzeichnete. - Offene Angebote liest Workist nur, wenn eine Angebots-Vorgangsart eingetragen ist. Als erledigt markierte Vorgänge liest Workist nicht. - Kundenspezifische Artikelnummern, Einheitenumrechnungen, Rahmenverträge und Preise liest Workist nicht aus büro+. Welche Felder Workist im Einzelnen übernimmt, steht in der [Feldreferenz](#feldreferenz). ## Was wir in microtech büro+ schreiben **Neuer Vorgang** Für jede abgeschlossene Bestellung legt Workist einen Vorgang der „Bestell-Vorgangsart“ an, für jede Anfrage einen Vorgang der „Anfrage-Vorgangsart“: - **Kopf**: Kunde, Belegdatum, Bestell- bzw. Anfragenummer als Herkunfts- und Auftragsnummer, eine Bezeichnung wie „Workist Order #4711“ und das Lieferdatum. - **Anschriften**: Rechnungs- und Lieferanschrift aus dem Dokument. Jede Angabe, die im Dokument steht, überschreibt die Standardanschrift, die büro+ aus der Kundenadresse vorbelegt. - **Positionen**: Artikelnummer, Menge, Einheit und Lieferdatum. Preise berechnet büro+. - **Dokumente**: Ist eine Dokumenten-Systemart eingetragen, hängt Workist das Bestelldokument (PDF) und, bei E-Mail-Eingang, die Original-E-Mail an den Vorgang. **Angebot wandeln** Passt die Angebotsreferenz einer Bestellung zu einem offenen Angebot aus büro+, legt Workist keinen neuen Vorgang an. Stattdessen wandelt Workist das Angebot mit der Prozesskette von büro+ in die „Bestell-Vorgangsart“ um und hängt die Dokumente an. Wie Workist Angebotsreferenzen abgleicht, steht unter [Abgleich](/docs/channel-configuration/document-processing/matching.md). Als Referenz am Beleg in der Workbench speichert Workist die Belegnummer des Vorgangs aus büro+. ## Einrichtung in der Workbench 1. Öffnen Sie **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** und klicken Sie bei microtech büro+ auf **Verbinden**. 2. Tragen Sie die Verbindung ein: | Feld | Inhalt | | --- | --- | | Name der Integration | frei wählbar | | Installations-Basis-URL | Adresse Ihrer Installation bis einschließlich der Instanz-ID | | Client-ID, Client-Secret | Zugang für Workist aus büro+ | | Bestell-Vorgangsart | Bezeichnung der Vorgangsart für Bestellungen, zum Beispiel „Auftragsbestätigung“ | | Anfrage-Vorgangsart | Bezeichnung der Vorgangsart für Anfragen, zum Beispiel „Anfrage“ | | Angebot Sync Vorgangsart | Bezeichnung der Vorgangsart, deren offene Vorgänge Workist als Angebote liest, zum Beispiel „Angebot“ | | Bestelldokument Systemart, Anfrage-Dokument Systemart | Dokumenten-Systemart für die angehängten Dokumente; leer lassen, wenn Workist nichts anhängen soll | | Bestellungskanäle, Kanäle für Angebotsanfragen | Kanäle, deren Belege Workist an büro+ überträgt | 3. Klicken Sie auf **Erstellen**. Workist prüft dabei die Zugangsdaten bei büro+. Lehnt büro+ sie ab, wird die Integration nicht gespeichert. Den Stand der Anmeldung zeigt der Integrationsstatus. 4. Mit **Stammdaten Update starten** laden Sie die Stammdaten sofort. Wenn Sie die Integration später bearbeiten, prüft Workist beim Speichern, ob es die eingetragenen Vorgangsarten und Dokumenten-Systemarten in büro+ gibt. Client-ID und Client-Secret lassen Sie leer, wenn sie gleich bleiben. Neue Zugangsdaten prüft Workist beim Speichern. Wie die Stammdaten in den Kanälen ankommen und wie Workist die Kanäle umstellt, steht unter [Was alle Konnektoren gemeinsam haben](/docs/data-exchange/connectors.md#common-behaviour). ## Fehlerbehandlung Lehnt büro+ einen Vorgang ab, erscheint der Beleg wieder unter den offenen Belegen, mit der Meldung aus büro+. Workist versucht es nicht automatisch erneut. Beheben Sie die Ursache und schließen Sie den Beleg nach **Erneut assistieren** wieder ab. - Gibt es eine eingetragene Vorgangsart in büro+ nicht mehr, überträgt Workist nichts und meldet das am Beleg. - Scheitert das Anhängen der Dokumente, ist der Vorgang in büro+ bereits angelegt. Workist markiert den Beleg trotzdem als fehlgeschlagen und nennt die Belegnummer. Schließen Sie den Beleg dann nicht erneut ab, sonst entsteht ein zweiter Vorgang. Hängen Sie die Dokumente in büro+ an oder verwerfen Sie den Beleg in Workist. - Scheitert das Wandeln eines Angebots, legt Workist keinen neuen Vorgang an, damit in büro+ keine Doppelten entstehen. ## Einschränkungen - Beim Wandeln eines Angebots übernimmt büro+ die Positionen aus dem Angebot. Abweichende Mengen oder zusätzliche Positionen der Bestellung überträgt Workist dabei nicht. - Positionen ohne Artikelnummer überträgt Workist nicht. - Workist prüft vor dem Anlegen nicht, ob es zur Bestellung schon einen Vorgang gibt. Wird eine Bestellung erneut abgeschlossen, entsteht ein weiterer Vorgang. ## Feldreferenz ### Gelesene Felder #### Kunden | Workist-Spalte | Aus microtech büro+ | | --- | --- | | `client_id1` | `fldAdrNr` | | `company_name` | `fldSuchBeg` – sonst `fldNa1` + `fldNa2` + `fldNa3` der Anschrift | | `address1` | `fldStr` der Standard-Rechnungsanschrift – sonst der Standard-Lieferanschrift | | `zip_code` | `fldPLZ` (wie oben) | | `city` | `fldOrt` (wie oben) | | `po_box` | `fldPostf` (wie oben) | | `country` | `fldLandKennz` – sonst `fldLand` (wie oben) | #### Kundenkontakte | Workist-Spalte | Aus microtech büro+ | | --- | --- | | `partition_id` | `fldAdrNr` | | `contact_id` | `fldID` – sonst `fldAspNr` | | `first_name` | `fldVNa` | | `last_name` | `fldNNa` | | `phone` | `fldTel1` – sonst `fldMTel` | | `email` | `fldEMail1` | #### Liefer- und Rechnungsadressen Beide Adressarten haben dieselben Felder. | Workist-Spalte | Aus microtech büro+ | | --- | --- | | `partition_id` | `fldAdrNr` | | `address_id1` | `fldAnsNr` | | `name` | `fldNa1` + `fldNa2` + `fldNa3` | | `address1` | `fldStr` | | `zip_code` | `fldPLZ` | | `city` | `fldOrt` | | `po_box` | `fldPostf` | | `country` | `fldLandKennz` – sonst `fldLand` | | `phone` | `fldTel` | #### Artikel | Workist-Spalte | Aus microtech büro+ | | --- | --- | | `article_id1` | `fldArtNr` | | `article_id3` | `fldBarCd` | | `description` | `fldKuBez1` | | `order_units` | `fldEinh` | #### Offene Angebote | Workist-Spalte | Aus microtech büro+ | | --- | --- | | `partition_id` | `fldAdrNr` | | `offer_number` | `fldBelegNr` | | `valid_from` | `fldDat` (Belegdatum) | | `position_number` | `fldPosNr` | | `article_id1` | `fldArtNr` | | `article_description` | `fldBez` der Position (Text ohne RTF-Formatierung) | | `quantity` | `fldMge` | | `unit` | `fldEinh` | Positionen ohne Artikelnummer übernimmt Workist nicht in die Angebote. ### Geschriebene Felder Aufgeführt sind die Felder, die Workist befüllt. Belegnummer, Preise, Summen und alle übrigen Felder setzt büro+ selbst. #### Vorgang – Kopf | Feld | Inhalt | | --- | --- | | `fldArt` | Vorgangsart aus „Bestell-Vorgangsart“ bzw. „Anfrage-Vorgangsart“ | | `fldAdrNr` | Kunde (Kundennummer) | | `fldDat` | Bestelldatum bzw. Anfragedatum – sonst das heutige Datum | | `fldHerkBelegNr` | Bestellnummer bzw. Anfragenummer | | `fldAuftrNr` | Bestellnummer bzw. Anfragenummer | | `fldBez` | `Workist Order #` bzw. `Workist RFQ #` | | `fldLiefDat` | Lieferdatum, wenn vorhanden | #### Vorgang – Rechnungs- und Lieferanschrift Nur Felder, die im Dokument gefüllt sind. | Feld | Inhalt | | --- | --- | | `fldReNa1` / `fldLiNa1` | Name – sonst Firmenname | | `fldReNa2` / `fldLiNa2` | Firmenname 2 | | `fldReNa3` / `fldLiNa3` | Firmenname 3 | | `fldReStr` / `fldLiStr` | Straße und Hausnummer | | `fldRePLZ` / `fldLiPLZ` | Postleitzahl | | `fldReOrt` / `fldLiOrt` | Ort | | `fldReLandKennz` / `fldLiLandKennz` | Land | #### Vorgang – Positionen | Feld | Inhalt | | --- | --- | | `fldArtNr` | Artikelnummer (Positionen ohne Artikelnummer werden nicht übertragen) | | `fldMge` | Menge | | `fldEinh` | Einheit | | `fldLiefDat` | Lieferdatum der Position | --- Source: https://docs.workist.com/docs/data-exchange/connectors/further-connectors.md # Weitere Konnektoren Diese Konnektoren laufen bei Workist und verbinden sich mit der Schnittstelle Ihres ERP-Systems. In Ihrem ERP wird nichts installiert. Sie richten sie in der Workbench unter **Einstellungen** → **Geschäftssysteme (ERP)** → **Integrationen** ein. Stammdatenabgleich, Übertragung und Fehlerbehandlung funktionieren wie unter [Was alle Konnektoren gemeinsam haben](/docs/data-exchange/connectors.md#common-behaviour) beschrieben. Die Tabellen nennen, welche Stammdaten Workist aus dem ERP-System liest und welche Belege Workist dort anlegt. Für eine genaue Feldzuordnung wenden Sie sich an Ihre Ansprechperson bei Workist. ## ORDAT.ERP {#ordat-erp} Workist verbindet sich mit dem Webservice von ORDAT.ERP (FOSS). | | | | --- | --- | | Liest | Kunden, Kundenkontakte, Lieferadressen, Rechnungsadressen, Artikel, kundenspezifische Artikelnummern, Einheitenumrechnung | | Schreibt | Bestellungen → Auftrag; Anfragen → Angebot | | Stammdatenabgleich | täglich um 04:00 Uhr deutscher Zeit | | Kanäle | Bestellungen, Anfragen | - Aufträge legt Workist als Webshop-Auftrag an oder, je nach Einstellung, als Vorauftrag. - Vor dem Anlegen sucht Workist in ORDAT nach einem Auftrag desselben Kunden mit derselben Bestellnummer aus den letzten 30 Tagen, bei Anfragen nach einem Angebot mit derselben Anfragenummer. Gibt es ihn schon, legt Workist keinen zweiten an und übernimmt seine Nummer als Referenz. - Den Hinweistext des Dokuments schreibt Workist als Kopftext, Positionstexte als Positionstexte. Beides lässt sich abschalten. - Positionen ohne Artikelnummer überträgt Workist nur, wenn eine Ersatz-Sachnummer eingetragen ist. Sonst überträgt Workist den Beleg nicht. - Mit unteren und oberen Schwellenwerten vergleicht Workist nach dem Anlegen den Preis aus ORDAT mit dem Preis im Dokument. Abweichungen stehen als Hinweis am Beleg; der Auftrag bleibt bestehen. - Auf Wunsch hängt Workist das Bestelldokument und die Original-E-Mail an den Beleg in ORDAT. **Einrichtung**: Sie tragen die Webservice-URL, Benutzer und Passwort eines technischen ORDAT-Benutzers sowie Mandant, Geschäftsbereich und Unterbereich ein. Unter den erweiterten Einstellungen hinterlegen Sie bei Bedarf einen Proxy und ein eigenes CA-Zertifikat, falls der Webservice nur über Ihr Netz erreichbar ist oder ein eigenes Zertifikat nutzt. Mit dem Verbindungstest prüfen Sie, ob Workist den Webservice erreicht und welche Funktionen der Benutzer nutzen darf. ## NetSuite {#netsuite} Workist verbindet sich mit der REST-Schnittstelle von Oracle NetSuite. | | | | --- | --- | | Liest | Kunden, Kundenkontakte, Lieferadressen, Artikel | | Schreibt | Bestellungen → Sales Order; Anfragen → Estimate; Rechnungen → Vendor Bill (Lieferantenrechnung); Universelle Dokumente → keine Neuanlage: PDF wird an einen bestehenden Sales Order angehängt | | Stammdatenabgleich | täglich um 11:30 und 23:30 Uhr New Yorker Zeit | | Kanäle | Bestellungen, Anfragen, Universelle Dokumente, Rechnungen | - Im Stammdatenmodus „Rechnung“ liest Workist statt der Kunden die Lieferanten. Brauchen Sie beides, legen Sie zwei NetSuite-Integrationen an. - Universelle Dokumente hängt Workist als PDF an den Sales Order, dessen Nummer im Dokument steht. - Die Feldzuordnung für Lieferantenrechnungen wird im Output Studio der Integration hinterlegt. Stimmen Sie sie mit Ihrer Ansprechperson bei Workist ab. - Anhänge legt Workist im File Cabinet ab, wenn Sie dafür eine Ordner-ID eintragen. **Einrichtung**: Sie tragen Konto-ID, REST-Service-URL, Instanz-URL sowie Client-ID, Client-Secret, Token-ID und Token-Secret einer tokenbasierten Anmeldung (Token-Based Authentication) ein. Optional legen Sie je Belegart ein eigenes Formular und einen File-Cabinet-Ordner fest. ## QuickBooks Desktop {#quickbooks-desktop} Workist verbindet sich über den Dienst Conductor mit QuickBooks Desktop. QuickBooks Online wird nicht unterstützt. | | | | --- | --- | | Liest | Kunden, Lieferadressen, Artikel, Einheitenumrechnung | | Schreibt | Bestellungen → Sales Order | | Stammdatenabgleich | täglich um 19:30 UTC | | Kanäle | Bestellungen | - Workist liest aktive Kunden sowie aktive Lager- und Baugruppenartikel, denen ein Mengeneinheitensatz zugeordnet ist. - Während der Verarbeitung fragt Workist QuickBooks direkt ab: Workist berechnet den erwarteten Preis aus der Preisstufe des Kunden und vergleicht ihn mit dem Einzelpreis, markiert Bestellmengen über dem Lagerbestand und blockiert die Automatisierung, wenn das Kreditlimit des Kunden 0,00 ist. - Workist prüft alle 15 Minuten, ob die Verbindung steht, und zeigt den Status an der Integration. **Einrichtung**: Sie tragen den API-Schlüssel und die Endbenutzer-ID der Conductor-Verbindung ein. Optional wählen Sie eine Vorlage für den Sales Order. ## OrderWise {#orderwise} Workist verbindet sich mit der API von OrderWise. | | | | --- | --- | | Liest | – (nicht im Standard) | | Schreibt | Bestellungen → Sales Order; Anfragen → Quote (Angebot) | | Stammdatenabgleich | täglich um 05:00 Uhr deutscher Zeit | | Kanäle | Bestellungen, Anfragen | - Im Standard liest Workist keine Stammdaten aus OrderWise. Die Stammdaten kommen per [SFTP](/docs/data-exchange/sftp.md) oder [API](/docs/data-exchange/api.md) oder über einen Export, den Workist für Ihre Installation einrichtet. - Während der Verarbeitung vergleicht Workist den Einzelpreis jeder Position mit dem Kundenpreis aus OrderWise. Liegt er außerhalb der eingestellten Schwellenwerte, geht der Beleg in die manuelle Bearbeitung. Dafür brauchen die Stammdaten die OrderWise-IDs von Kunde und Artikel. - Auf Wunsch übergibt Workist die Anhänge mit dem Auftrag. **Einrichtung**: Sie tragen Basis-URL, Benutzername, Passwort und Sitzungs-ID von OrderWise ein. Den Proxy, über den Workist Ihre OrderWise-Installation erreicht, stimmen Sie mit Ihrer Ansprechperson bei Workist ab. ## Weclapp {#weclapp} Workist verbindet sich mit der API Ihres Weclapp-Mandanten. | | | | --- | --- | | Liest | Artikel, Kunden, kundenspezifische Artikelnummern | | Schreibt | Bestellungen → Kundenauftrag (aus einem passenden Angebot, sonst neu) | | Stammdatenabgleich | täglich um 10:00 UTC | | Kanäle | Bestellungen | - Passt die Angebotsreferenz einer Bestellung zu einem Angebot desselben Kunden in Weclapp, nimmt Workist das Angebot an und ergänzt den daraus entstandenen Auftrag um die übrigen Positionen. Sonst legt Workist einen neuen Kundenauftrag an. - Workist kann Bestellungen aus Weclapp-Tickets übernehmen: Tickets mit der eingestellten Kategorie und einem der eingestellten Status übernimmt Workist einmal täglich um 00:00 UTC als Belege und setzt sie auf den eingestellten Status für Tickets in Bearbeitung. Nach dem Anlegen des Auftrags setzt Workist Status und Kategorie des Tickets auf die Werte für abgeschlossene Tickets. - Ohne Kundennummer überträgt Workist eine Bestellung nicht. **Einrichtung**: Sie tragen Ihren Weclapp-Mandanten und einen API-Schlüssel ein und wählen die Bestellungskanäle. Für die Übernahme aus Tickets tragen Sie die IDs der Ticket-Kategorie und der Ticket-Status ein. ## Sage 200 Professional {#sage-200-professional} Für Sage 200 Professional (Großbritannien) liest Workist Kunden, Artikel und Lieferadressen und legt Bestellungen als Sales Orders an; die Einrichtung stimmen Sie mit Ihrer Ansprechperson bei Workist ab. --- Source: https://docs.workist.com/docs/agents.md # KI-Agenten Neben der Dokumentenverarbeitung bietet Workist drei KI-Agenten. Sie arbeiten mit denselben Kanälen, Stammdaten und ERP-Anbindungen wie die übrige Workbench und sehen nie mehr Daten, als ihre Einrichtung erlaubt. | Agent | Was er tut | Wer ihn nutzt | Wer ihn einrichtet | | --- | --- | --- | --- | | [Worki](/docs/agents/worki.md) | Chat-Assistent in der Workbench. Beantwortet Fragen zu Dokumenten, Bestellungen, Stammdaten und Auswertungen, legt Belege an, erstellt Excel-, Word- und PDF-Dateien und führt Aufgaben nach Zeitplan aus. | Benutzer mit der Rolle **Chat user** sowie **Admins** | **Admins** schalten Worki für das Unternehmen ein oder aus. | | [Sprachagenten](/docs/agents/voice-agents.md) | Nehmen Anrufe unter einer eigenen Rufnummer an. Beantworten Fragen aus Ihren Stammdaten und Ihrem ERP, verbinden mit Kolleginnen und Kollegen, buchen Termine und legen Bestellungen oder Preisanfragen in Ihren Kanälen an. | Ihre Anruferinnen und Anrufer | **Manager** und **Admins** | | [Inbox-Agenten](/docs/agents/inbox-agents.md) | Bearbeiten Kunden-E-Mails, die kein Beleg sind, etwa Preis-, Verfügbarkeits- oder Lieferterminanfragen. Erstellen dazu einen Antwortentwurf oder eine interne Zusammenfassung, die Sie im Workist-Add-in für Outlook sehen. | Mitarbeitende, deren Postfach über die Smart Inbox verbunden ist | **Manager** und **Admins** | Die Rollen sind unter [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md) beschrieben. ## Freischaltung | Agent | Voraussetzung im Vertrag | | --- | --- | | Worki | Zusatzleistung **Worki** (Chat-Agenten). Ohne Freischaltung zeigt die Workbench unter **Worki** einen Hinweis mit Kontakt zum Vertrieb. | | Sprachagenten | Zusatzleistung **Sprachagenten**. | | Inbox-Agenten | Keine eigene Freischaltung in der Workbench: **Manager** und **Admins** können Inbox-Agenten anlegen. Ob Inbox-Agenten in Ihrem Vertrag enthalten sind, klärt Ihre Ansprechperson bei Workist. | Zusatzleistungen schaltet Ihre Ansprechperson bei Workist für Ihr Unternehmen frei. ## Wie die Agenten zusammenarbeiten - **Belege landen in Ihren Kanälen.** Bestellungen, Preisanfragen und andere Belege, die ein Agent anlegt, durchlaufen dieselbe Verarbeitung wie ein per E-Mail eingegangenes Dokument: Extraktion, Prüfungen und bei Bedarf Unterstützung durch Ihr Team. - **Worki nutzt Inbox-Agenten.** Wählen Sie in Worki das Projekt eines Inbox-Agenten, greift Worki zusätzlich auf dessen ERP-Anbindung und Wissen zu. Automationen in Worki führt ebenfalls ein Inbox-Agent aus. - **Gemeinsame Verbindungen.** Eine Microsoft-SharePoint-Verbindung liefert Wissen für Worki-Projekte und Inbox-Agenten. Die Microsoft-Teams-Verbindung nutzen die Sprachagenten für Weiterleitung, Teams-Nachrichten und Gesprächszusammenfassungen. ## KI-Hinweis und Datenschutz Die Agenten erzeugen Antworten mit KI. Antworten können Fehler enthalten; prüfen Sie wichtige Angaben, bevor Sie sie weitergeben. Aktionen, die in Worki etwas verändern, führt Worki erst nach Ihrer Bestätigung aus. Wo Workist Ihre Daten verarbeitet, steht unter [Allgemeine Informationen](/docs/faq/general-information.md). Für Sprachagenten gelten zusätzliche Dienstleister, siehe [Sprachagenten](/docs/faq/general-information.md#sprachagenten). --- Source: https://docs.workist.com/docs/agents/worki.md # Worki :::info Zusatzleistung Diese Funktion ist nur verfügbar, wenn sie in Ihrem Workist-Vertrag enthalten ist (**Worki**). Ihre Ansprechperson bei Workist schaltet sie für Sie frei. ::: Worki ist der KI-Assistent in der Workbench. Sie schreiben eine Frage oder Aufgabe in normaler Sprache. Worki sucht die passenden Daten, antwortet und erledigt Aufgaben wie das Anlegen einer Bestellung oder das Erstellen einer Excel-Datei. Worki greift dabei nur auf die Kanäle Ihrer Teams zu, mit deren Dokumenten und Stammdaten. Für **Admins** sind das alle Kanäle des Unternehmens. ## Wer Worki nutzen kann Ein Benutzer kann Worki nutzen, wenn alle drei Bedingungen erfüllt sind: 1. Worki ist in Ihrem Vertrag enthalten. 2. Der Benutzer hat die Rolle **Chat user** oder **Admin**. Die Rollen **Member**, **Manager** und **IT** enthalten Worki nicht. Vergeben Sie bei Bedarf zusätzlich **Chat user**, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). 3. Ein Admin hat Worki für das Unternehmen nicht ausgeschaltet, siehe [Worki für das Unternehmen ein- und ausschalten](#worki-ein-ausschalten). Fehlt eine dieser Bedingungen, zeigt der Navigationseintrag **Worki** einen Hinweis statt des Chats. Hat ein Admin Worki ausgeschaltet, sagt der Hinweis das ausdrücklich; Ihre Gespräche bleiben erhalten. Benutzer, die nur die Rolle **Chat user** haben, sehen in der Workbench ausschließlich Worki und ihre eigenen Einstellungen. ## Worki öffnen Klicken Sie unten in der linken Navigation auf **Worki**. Links stehen Ihre Gespräche, in der Mitte das aktuelle Gespräch mit dem Eingabefeld. Über das Plus-Symbol im Eingabefeld hängen Sie Dateien an und wählen vor der ersten Nachricht ein [Projekt](#projekte). In einem Gespräch mit Projekt schalten Sie dort auch einzelne Werkzeuge ab. ## Was Worki kann Welche Werkzeuge Worki hat, hängt davon ab, was in Ihrem Konto eingerichtet ist. | Bereich | Beispiele | Voraussetzung | | --- | --- | --- | | Dokumente in Workist | „Welche Bestellungen brauchen gerade meine Unterstützung?" · Ein Dokument mit seiner Vorgangsnummer vollständig lesen · Das Originaldokument anzeigen · Ein Dokument verwerfen oder in einen anderen Kanal verschieben | Kanäle Ihrer Teams | | Belege anlegen | Bestellung, Preisanfrage, Auftragsbestätigung, Rechnung oder Lieferschein aus einer Nachricht, E-Mail oder Datei anlegen · Aus einer Datei mit mehreren Belegen je Beleg ein eigenes Dokument anlegen · Eine hochgeladene Datei, eine E-Mail aus Ihrem Posteingang oder das Original eines vorhandenen Dokuments unverändert als neues Dokument einreichen | Ein Kanal des Belegtyps, den Sie sehen. Sehen Sie mehrere, fragt Worki nach dem Kanal. | | Auswertungen | Anzahl und Wert verarbeiteter Belege · Automatisierungsquote · Stärkste Kunden · Vergleich pro Monat · Gründe für Unterstützung · Diagramme | Abgeschlossene Dokumente in Ihren Kanälen | | Stammdaten | Artikelnummer zu einer Beschreibung finden · Kunde und Kundennummer suchen · Offene Angebote · Offene Bestellungen | Stammdaten, die in Ihren Kanälen hinterlegt sind | | E-Mail | Posteingang nach Absender oder Betreff durchsuchen · Antwort senden oder als Entwurf speichern · E-Mail als gelesen markieren | Ihre eigene, verbundene Persönliche [Smart Inbox](/docs/smart-inbox.md) | | ERP-Livedaten | Preis, Verfügbarkeit, Liefertermin und Sendungsverfolgung · Mit microtech büro+ zusätzlich Belege lesen, anlegen, ändern und weiterführen sowie Kunden, Adressen und Ansprechpartner pflegen · Mit [Sage 100](/docs/data-exchange/connectors/sage-100.md#erp-funktionen-der-agenten) zusätzlich offene Angebote und Belege, Auftragsstatus, Belege lesen und anlegen, Angebote in Aufträge übernehmen und Kunden anlegen | Ein Projekt eines [Inbox-Agenten](/docs/agents/inbox-agents.md) mit ERP-Anbindung, siehe [Projekte](#projekte) | | Dateien erstellen | Excel-Tabelle, Word-Dokument oder PDF, z. B. aus einer Auswertung | – | | Gedächtnis | „Merke dir, dass ich hauptsächlich im Kanal Bestellungen Süd arbeite." Worki merkt sich bis zu 50 solcher Hinweise pro Benutzer. | – | Belege, die Worki anlegt, durchlaufen die normale Verarbeitung des Kanals wie ein per E-Mail eingegangenes Dokument. ## Aktionen bestätigen Bevor Worki etwas verändert, zeigt es eine Karte mit allen Angaben zur Aktion. Erst wenn Sie bestätigen, führt Worki sie aus. Das gilt für: - Belege anlegen und Dateien als Dokument einreichen, - Dokumente verwerfen oder in einen anderen Kanal verschieben, - E-Mails senden oder als gelesen markieren (die Karte zeigt, ob die E-Mail sofort gesendet oder als Entwurf gespeichert wird), - Änderungen direkt im ERP. ## Dateien anhängen Ziehen Sie Dateien in das Eingabefeld oder hängen Sie sie über das Plus-Symbol an. Worki liest: - PDF, CSV und E-Mails (.eml), - Excel (.xlsx, .xls), - Bilder (PNG, JPEG, GIF, WebP). Eine Datei darf höchstens 5 MB groß sein. ## Beispiele Die Beispielsammlung enthält fertige Fragen, sortiert nach Themen wie Fälle und Dokumente, Auswertungen, Dateien erstellen, Stammdaten, E-Mail und ERP-Livedaten. Ersetzen Sie die Platzhalter in eckigen Klammern durch Ihre Werte. Beispiele, die ein Postfach oder ein ERP brauchen, sind entsprechend gekennzeichnet. ## Gespräche verwalten - **Suchen und anheften:** Die Gesprächsliste lässt sich durchsuchen. Angeheftete Gespräche stehen oben. - **Nachricht ändern:** Bearbeiten Sie eine eigene Nachricht und senden Sie sie erneut. Worki antwortet ab dieser Stelle neu. - **Feedback:** Bewerten Sie ein Gespräch als hilfreich oder nicht hilfreich. - **Teilen:** Sie teilen ein ganzes Gespräch oder nur eine Frage mit Antwort. Empfänger sind Personen oder Teams aus Ihren eigenen Teams, die Worki nutzen dürfen. Sie erhalten eine Momentaufnahme zum Lesen; spätere Nachrichten sind nicht enthalten. Auf Wunsch geben Sie eine Notiz mit. Empfänger können die Momentaufnahme in einem eigenen Gespräch fortsetzen. Sie können die Freigabe jederzeit entziehen. ## Projekte Ein Projekt bündelt Anweisungen und Wissen für Gespräche zu einem Thema, etwa „Vertriebsinnendienst". Jedes Gespräch, das Sie in einem Projekt führen, nutzt dessen Anweisungen und Wissensdateien. Ein Projekt erweitert nie den Datenzugriff: Jedes Mitglied sieht weiterhin nur die Dokumente und Auswertungen, die es auch ohne Projekt sehen darf. Ein Projekt hat drei Bereiche: | Bereich | Inhalt | | --- | --- | | Grundlagen | Name und Beschreibung. Die Beschreibung erscheint auf der Projektkarte und bei der Projektauswahl. | | Wissen | Anweisungen an Worki, wie es in diesem Projekt antworten soll, sowie Wissensdateien, Webseiten und die SharePoint-Verbindung, siehe unten. | | Freigabe | Nur ich, alle Mitglieder eines Teams oder bestimmte Personen. Zur Auswahl stehen nur Ihre eigenen Teams und deren Mitglieder (Admins: alle Teams). Das Standardteam des Unternehmens wird nicht angeboten. | Wissen in einem Projekt: - **Wissensdateien:** .c, .cpp, .cs, .css, .csv, .doc, .docx, .go, .html, .java, .js, .json, .md, .pdf, .php, .pptx, .py, .rb, .sh, .tex, .ts, .txt. Jedes Mitglied darf Dateien hinzufügen und seine eigenen wieder löschen. - **Webseiten:** bis zu 10 Adressen, die mit `https://` beginnen, z. B. Produktkataloge oder Datenblätter auf Ihrer Website. Workist aktualisiert den Inhalt alle paar Stunden. - **SharePoint-Verbindung:** Ordner und Dateien aus Microsoft SharePoint, z. B. Preislisten oder technische Dokumentation. Synchronisierte Dateien erscheinen in der Dateiliste. Die Verbindung im Projekt richten nur Benutzer ein, die zusätzlich Agenten oder Integrationen konfigurieren dürfen (**Manager**, **IT**, **Admin**); alle anderen sehen, was synchronisiert wird. Name, Anweisungen und Freigabe ändert der Eigentümer des Projekts oder ein Admin. Ein gelöschtes Projekt entfernt auch seine Wissensdateien; Gespräche, die es genutzt haben, laufen ohne Projekt weiter. Um ein Projekt zu nutzen, wählen Sie es vor der ersten Nachricht über das Plus-Symbol im Eingabefeld aus. Ein laufendes Gespräch lässt sich keinem anderen Projekt zuordnen. ### SharePoint verbinden Die Verbindung zu SharePoint legt ein Benutzer mit der Rolle **IT** oder **Admin** einmal für das Unternehmen an: 1. Öffnen Sie **Einstellungen** › **Integrationen** › **Microsoft SharePoint**. 2. Klicken Sie auf **SharePoint verbinden**, vergeben Sie einen **Namen der Integration** und klicken Sie auf **Mit Microsoft verbinden**. 3. Melden Sie sich mit Ihrem Microsoft-Konto an. Danach wählen Sie im Projekt die **SharePoint-Verbindung**, die **Website**, die **Dokumentenbibliothek** und die Ordner oder Dateien, die Worki kennen soll. ### Projekte von Inbox-Agenten Jeder [Inbox-Agent](/docs/agents/inbox-agents.md) hat ein eigenes Projekt. Es ist in Worki mit dem Namen des Agenten gekennzeichnet und lässt sich dort nur lesen; eingerichtet wird es beim Agenten. Führen Sie ein Gespräch in diesem Projekt, nutzt Worki zusätzlich die ERP-Anbindung des Agenten. ## Zeitpläne Mit einem Zeitplan führt Worki eine Anfrage regelmäßig aus, z. B. jeden Montag eine Auswertung der Vorwoche. 1. Fahren Sie über eine eigene Nachricht und klicken Sie auf das Uhr-Symbol. Alternativ legen Sie in der Gesprächsliste im Bereich der geplanten Anfragen einen neuen Zeitplan an. 2. Vergeben Sie einen Namen und prüfen Sie den Text der Anfrage. 3. Wählen Sie die Häufigkeit: täglich zu einer Uhrzeit, wöchentlich an einem Wochentag, stündlich oder alle X Minuten (mindestens alle 5 Minuten). Uhrzeiten gelten in der Zeitzone Ihres Unternehmens. 4. Wählen Sie die Werkzeuge für diesen Zeitplan. Das Ergebnis erscheint im Gespräch. Jeder Benutzer kann bis zu 10 aktive Zeitpläne haben. :::warning Keine Rückfrage Ein geplanter Lauf fragt nicht nach Bestätigung. Werkzeuge, die Sie für den Zeitplan auswählen, führt Worki direkt aus, auch solche, die im Chat eine Bestätigung verlangen, etwa das Senden einer E-Mail. ::: Schlägt ein Lauf fehl, zeigt das Gespräch den Fehler; der Zeitplan bleibt aktiv. Ist Ihr Nutzungslimit erreicht oder Worki ausgeschaltet, entfällt der Lauf. ## Automationen Eine Automation lässt einen [Inbox-Agenten](/docs/agents/inbox-agents.md) E-Mails bestimmter Absender bearbeiten, statt sie normal zu verarbeiten. Automationen anlegen können Worki-Benutzer, die zusätzlich Agenten konfigurieren dürfen (**Admin**, oder **Manager** mit zusätzlicher Rolle **Chat user**). Es muss mindestens ein aktiver Inbox-Agent existieren. Sie öffnen die Automationen über das Blitz-Symbol in der Gesprächsliste. Pro Automation legen Sie fest: | Einstellung | Bedeutung | | --- | --- | | Name | Frei wählbar. | | Agent | Der Inbox-Agent, der die Anweisung ausführt (nur bei mehreren Agenten). | | Auslöser | Eingehende E-Mail. | | Kanal | Der Kanal, den die Automation überwacht. Zur Auswahl stehen die Kanäle, die Sie sehen. | | Absender | Eine oder mehrere E-Mail-Adressen oder Domains. Eine genau passende Adresse hat Vorrang vor einer Domain. | | Anweisung | Was der Agent mit der E-Mail tun soll. | | Aktiv | Schalten Sie die Automation aus, um sie zu pausieren, ohne sie zu löschen. | :::warning Die normale Verarbeitung entfällt Trifft im überwachten Kanal eine E-Mail von einem der Absender ein, verarbeitet Workist sie nicht als Dokument. Workist verwirft das Dokument und übergibt die E-Mail dem Inbox-Agenten, der Ihre Anweisung ohne Rückfrage ausführt. Das Ergebnis steht im Verlauf des Inbox-Agenten. ::: ## Nutzungslimit Jeder Benutzer hat ein monatliches Budget für Worki. Wie viel davon verbraucht ist, zeigt die Gesprächsliste in Prozent. - Bei 100 % beantwortet Worki keine neuen Nachrichten mehr, und Ihre Zeitpläne laufen nicht. Ab dem ersten Tag des nächsten Monats steht Worki wieder zur Verfügung. Ihre Gespräche bleiben erhalten. - Auch ein einzelnes Gespräch hat ein Limit. Ist es erreicht, beginnen Sie ein neues Gespräch. ## KI-Hinweis Worki erzeugt Antworten mit KI. Unter dem Eingabefeld steht deshalb der Hinweis, dass die Antworten KI-generiert sind und Fehler enthalten können. Prüfen Sie Zahlen und Angaben, bevor Sie sie weitergeben. ## Worki für das Unternehmen ein- und ausschalten {#worki-ein-ausschalten} Worki ist für das Unternehmen eingeschaltet, sobald es in Ihrem Vertrag enthalten ist. Ein **Admin** kann Worki für alle Benutzer ausschalten: 1. Öffnen Sie **Einstellungen** und im Bereich Ihres Unternehmens den Eintrag für Agenten. 2. Schalten Sie Worki aus oder ein. 3. Klicken Sie auf **Speichern**. Solange Worki ausgeschaltet ist, kann niemand im Unternehmen Worki nutzen, und Zeitpläne laufen nicht. Gespräche bleiben erhalten und sind nach dem Einschalten wieder verfügbar. --- Source: https://docs.workist.com/docs/agents/voice-agents.md # Sprachagenten :::info Zusatzleistung Diese Funktion ist nur verfügbar, wenn sie in Ihrem Workist-Vertrag enthalten ist (**Sprachagenten**). Ihre Ansprechperson bei Workist schaltet sie für Sie frei. ::: Ein Sprachagent nimmt Anrufe unter einer eigenen Rufnummer an und führt das Gespräch mit KI. Er beantwortet Fragen aus Ihren Stammdaten und Ihrem ERP, verbindet Anrufer mit Kolleginnen und Kollegen, bucht Termine und legt Bestellungen oder Preisanfragen in Ihren Kanälen an. Nach jedem Anruf finden Sie Aufzeichnung, Transkript und Zusammenfassung in der Anrufhistorie; auf Wunsch geht die Zusammenfassung per E-Mail oder Microsoft Teams an Ihr Team. Sprachagenten sind ein eigener Bereich der Workbench und nicht Teil der Kanal-Konfiguration. Ein Unternehmen kann mehrere Sprachagenten haben, etwa für Vertrieb und Kundendienst. :::note Englische Oberfläche Die Oberfläche der Sprachagenten ist derzeit nur auf Englisch verfügbar. Auf dieser Seite stehen die englischen Bezeichnungen in Klammern. ::: ## Wer Sprachagenten einrichtet Sprachagenten anlegen, ändern und die Anrufhistorie sehen können Benutzer mit der Rolle **Manager** oder **Admin**, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). Sie finden den Bereich in der linken Navigation (*Voice Agents*). ## Ablauf eines Anrufs 1. Der Anrufer wählt die Rufnummer des Sprachagenten. 2. Ist eine Anrufererkennung eingerichtet, sucht Workist die Telefonnummer des Anrufers in Ihren [Kundenkontakten](/docs/master-data/customer-contacts.md). Festnetz- und Mobilnummer werden beide geprüft. 3. Der Agent begrüßt den Anrufer. Ist der Anrufer erkannt, verwendet er die personalisierte Begrüßung. 4. Der Agent stellt die Einwilligungsfrage zur Aufzeichnung. Stimmt der Anrufer nicht zu, beendet der Agent das Gespräch oder leitet den Anrufer an die Weiterleitungsnummer weiter. 5. Ist ein zweiter Faktor eingerichtet, fragt der Agent danach, bevor er Kundendaten nennt oder Bestellungen aufnimmt. 6. Der Agent führt das Gespräch nach Ihrem Prompt und nutzt die eingeschalteten Werkzeuge. 7. Der Agent beendet das Gespräch, verbindet auf Wunsch mit einem Menschen, oder der Anruf endet nach der maximalen Gesprächsdauer. 8. Nach dem Anruf: Aufzeichnung, Transkript und Zusammenfassung stehen in der Anrufhistorie. Angelegte Bestellungen und Preisanfragen laufen in Ihren Kanälen in die Verarbeitung. Die Zusammenfassung geht an die eingerichteten Empfänger. ## Sprachagent anlegen Klicken Sie im Bereich der Sprachagenten auf die Schaltfläche zum Anlegen (*Create voice agent*). Ein Assistent führt Sie durch sieben Schritte. Die Schritte Gesprächszusammenfassungen und Wissen können Sie überspringen und später ergänzen. Beim Anlegen richtet Workist den Agenten und seine Rufnummer ein. Das dauert bis zu einer Minute; lassen Sie das Fenster so lange geöffnet. Alle Einstellungen ändern Sie später auf der Konfigurationsseite des Agenten. Sie hat dieselben Bereiche wie der Assistent; speichern Sie dort mit *Save*. ### Schritt 1: Details (*Details*) | Einstellung | Bedeutung | | --- | --- | | Name (*Name*) | Pflichtfeld, z. B. „Vertriebshotline". | | Team (*Team*) | Das Team, zu dem der Agent gehört. | | Sprache (*Language*) | Deutsch oder Englisch. Der Agent spricht und versteht nur diese Sprache. Standard ist Deutsch. | ### Schritt 2: Stimme und Anruf (*Voice & call*) | Einstellung | Bedeutung | | --- | --- | | Begrüßung (*Greeting*) | Der erste Satz, den der Agent sagt. | | Personalisierte Begrüßung (*Personalized greeting*, optional) | Ersetzt die Begrüßung, wenn der Anrufer erkannt ist. Als Platzhalter steht nur der Name des Anrufers zur Verfügung: `{{caller_name}}`. Fügen Sie ihn über die Liste unter dem Feld oder durch Eingabe von `/` ein. Der Firmenname lässt sich in der Begrüßung nicht verwenden. Mit zweitem Faktor nutzt der Agent immer die normale Begrüßung. | | Einwilligungsfrage (*Recording consent question*) | Pflichtfeld. Der Agent stellt die Frage zu Beginn des Anrufs und fährt nur fort, wenn der Anrufer zustimmt. | | Anrufer ohne Einwilligung weiterleiten (*Forward callers who deny consent*) | Wer der Aufzeichnung nicht zustimmt, wird an die Weiterleitungsnummer verbunden, statt dass der Agent auflegt. Nur verfügbar, wenn eine Weiterleitungsnummer eingetragen ist. | | Rufnummer (*Phone number*) | Die Nummer, die Anrufer wählen, im Format `+49…`. Die Nummer stellt Workist bereit; tragen Sie die Nummer ein, die Sie von Ihrer Ansprechperson erhalten haben. | | Weiterleitungsnummer (*Transfer number*) | Hierhin verbindet der Agent, wenn der Anrufer einen Menschen sprechen möchte. Leer lassen, wenn der Agent nicht weiterleiten soll. | | Anrufererkennung (*Caller identification lookup*) | Die [Kundenkontakte](/docs/master-data/customer-contacts.md), in denen Workist die Telefonnummer des Anrufers sucht. Ohne diese Einstellung erkennt der Agent niemanden. | | Nur erkannte Anrufer zulassen (*Only allow identified callers*) | Anrufer, deren Nummer in den Kundenkontakten fehlt, hören den Ablehnungstext (*Caller rejection message*), danach endet der Anruf. Setzt die Anrufererkennung voraus. | | Zweiter Faktor (*Verify identified callers*) | Siehe [Zweiter Faktor](#zweiter-faktor). Setzt die Anrufererkennung voraus. | | Hintergrundstimmen ignorieren (*Background voice detection*) | Der Agent ignoriert Sprache im Hintergrund, die nicht an ihn gerichtet ist. Standardmäßig an. | | Stimme (*Voice*) | Gesprächsstimme (*Conversational voice*): ausdrucksstärker. Schnelle Stimme (*Fast voice*): antwortet schneller; nur hier lässt sich das Sprechtempo (*Voice speed*) zwischen 0,7 und 1,2 einstellen. | | Maximale Gesprächsdauer (*Maximum call duration*) | Danach endet der Anruf automatisch. 1 bis 60 Minuten, Standard 20 Minuten. | | Website-Rückrufe (*Website call requests*) | Siehe [Rückruf über Ihre Website](#rückruf-über-ihre-website). | #### Zweiter Faktor Die Telefonnummer allein beweist nicht, wer anruft. Mit dem zweiten Faktor nennt ein erkannter Anrufer zusätzlich eine Angabe, die nur er kennen sollte. Erst danach nennt der Agent Kundendaten oder nimmt Bestellungen auf. | Einstellung | Bedeutung | | --- | --- | | Prüfmerkmal (*Verification attribute*) | Die Kundennummer oder ein Attribut aus den Zusatzdaten (`extra_data`) des Kundenkontakts. Für ein Attribut geben Sie dessen Schlüssel an (*Extra data key*). | | Prüffrage (*Verification question*) | Wortlaut der Frage. Für die Kundennummer gilt ohne Eingabe „Bitte nennen Sie mir Ihre Kundennummer.", für ein Attribut ist die Frage Pflicht. | | Versuche pro Anruf (*Attempts per call*) | 1 bis 5, Standard 3. | | Text nach Fehlversuchen (*Message after failed verification*) | Was der Agent sagt, bevor er auflegt. Ohne Eingabe formuliert er selbst. | Der Agent kennt die richtige Antwort nie; Workist prüft sie. Hat eine Telefonnummer innerhalb von 24 Stunden dreimal alle Versuche verbraucht, lehnt der Agent weitere Anrufe dieser Nummer ab. Für Agenten, über die Außendienstmitarbeitende Daten verschiedener Kunden abfragen, ist der zweite Faktor nicht geeignet. ### Schritt 3: Werkzeuge (*Tools*) Hier legen Sie fest, was der Agent während eines Anrufs tun darf. Die Werkzeuge sind in Bereiche gruppiert. Werkzeuge, deren Voraussetzung fehlt, lassen sich nicht einschalten. | Bereich | Werkzeug | Was der Agent damit tut | Voraussetzung | Vorausgewählt | | --- | --- | --- | --- | --- | | Produkte & Stammdaten | Artikelsuche (*Article search*) | Sucht im Artikelkatalog nach Artikelnummer oder Beschreibung. | Artikel-Stammdaten des Bestellkanals oder eine eigene Artikel-Stammdatenquelle | ja | | Produkte & Stammdaten | Bestellhistorie (*Order history*) | Liest die bisherigen Bestellungen des anrufenden Kunden. | Erkannter Kunde. Quelle: eine eigene Stammdatenquelle für Bestellabgleich, sonst die von Workist verarbeiteten Bestellungen | ja | | Produkte & Stammdaten | Bestellauskunft für nicht erkannte Anrufer (*Order lookup (unidentified callers)*) | Sucht eine einzelne Bestellung über die genannte Bestellnummer, ohne dass der Anrufer erkannt sein muss. Der Agent nennt nur Bestelldatum und Artikel, keine Firma, Preise oder Lieferadresse, und lässt sich vorher die letzten drei Ziffern der Kundennummer bestätigen. | Eigene Stammdatenquelle für Bestellabgleich (Pflicht) | nein | | Produkte & Stammdaten | Offene Angebote (*Open offers*) | Liest offene Angebote des Kunden. | Erkannter Kunde; Angebots-Stammdaten im Bestellkanal | ja | | Produkte & Stammdaten | Lieferadressen (*Delivery address lookup*) | Liest die bekannten Lieferadressen des Kunden. | Erkannter Kunde; Lieferadress-Stammdaten im Bestellkanal | ja | | Produkte & Stammdaten | Kundensuche (*Client search*) | Findet einen Kunden über Firmenname oder Kundennummer und nennt Kundennummer und Adresse, z. B. als Lieferadresse. Ohne zweiten Faktor kann so jeder Anrufer Daten beliebiger Kunden erfragen. | Bestätigung des Risikos beim Einschalten | nein | | Kontakte & Weiterleitung | Interne Kontaktsuche (*Internal contact lookup*) | Findet einen internen Ansprechpartner (z. B. den Außendienst) über Name, E-Mail oder Telefonnummer. | Stammdaten für interne Kontakte im Bestellkanal | nein | | Kontakte & Weiterleitung | Weiterleiten an internen Kontakt (*Forward to internal contact*) | Verbindet den Anrufer mit dem gefundenen internen Kontakt. Ist die Teams-Statusprüfung an, nur bei grünem oder gelbem Status. | Interne Kontaktsuche | nein | | Kontakte & Weiterleitung | Teams-Statusprüfung (*Teams status check*) | Prüft vor dem Weiterleiten den Teams-Status (grün, gelb, rot, offline) des internen Kontakts. | Verbundenes Microsoft-Teams-Konto | nein | | Kontakte & Weiterleitung | Teams-Nachricht senden (*Send Teams message*) | Schickt dem internen Kontakt eine Teams-Chatnachricht, z. B. wenn er nicht erreichbar ist. | Verbundenes Microsoft-Teams-Konto | nein | | Kontakte & Weiterleitung | E-Mail senden (*Send email*) | Schickt einem internen Kontakt eine E-Mail (Absender Workist), z. B. mit dem Anliegen des Anrufers. | Ersatz-E-Mail-Adresse; optional erlaubte Empfänger-Domains | nein | | Termine (Calendly) | Freie Termine (*Meeting availability*) | Liest freie Termine aus Ihrem Calendly-Terminlink. | Calendly-Terminlink und Calendly-API-Token | nein | | Termine (Calendly) | Termin buchen (*Book meeting*) | Bucht einen Calendly-Termin für den Anrufer. Calendly verschickt Einladung und Bestätigung. | Calendly-Terminlink und Calendly-API-Token | nein | | Belege erstellen | Bestellung anlegen (*Create order*) | Legt aus dem Gespräch eine Bestellung im gewählten Bestellkanal an. | Bestellkanal | ja | | Belege erstellen | Preisanfrage anlegen (*Create RFQ*) | Legt aus dem Gespräch eine Preisanfrage im gewählten Preisanfragen-Kanal an. | Preisanfragen-Kanal | nein | | ERP-Liveverbindung | Artikelpreis (*Article price*) | Nennt den Preis des Anrufers für einen Artikel (Preisliste, Mengenrabatt, Sonderpreis) direkt aus dem ERP. | Angebundenes ERP-System (Auswahl im Bereich ERP) | nein | | ERP-Liveverbindung | Artikelverfügbarkeit (*Article availability*) | Nennt die lieferbare Menge: Lagerbestand abzüglich der bereits anderen Aufträgen zugesagten Menge. | Angebundenes ERP-System (Auswahl im Bereich ERP) | nein | Unabhängig von dieser Auswahl kann der Agent das Gespräch immer beenden. Ist eine Weiterleitungsnummer eingetragen oder das Weiterleiten an interne Kontakte eingeschaltet, kann er Anrufer außerdem verbinden. **Belegkanäle.** Für *Create order* wählen Sie einen Bestellkanal (*Order channel*), für *Create RFQ* einen Preisanfragen-Kanal (*RFQ channel*). Der Bestellkanal liefert außerdem die Stammdaten für die Werkzeuge im Bereich Produkte & Stammdaten und für die interne Kontaktsuche. Pro Belegtyp wählen Sie, welche Kopf- und Positionsfelder der Agent erfragt. Kunde, Ansprechpartner und Lieferadresse erfragt er immer. **E-Mail senden.** Die Ersatz-E-Mail-Adresse (*Fallback notification email*) erhält Rückrufwünsche und Nachrichten, wenn der Agent keinen internen Kontakt mit E-Mail-Adresse findet. Andere Empfänger erreicht der Agent nur, wenn ihre Domain unter den erlaubten Empfänger-Domains (*Allowed recipient domains*) steht; Subdomains tragen Sie einzeln ein. **Calendly.** Tragen Sie den öffentlichen Link des Termintyps (*Calendly meeting link*) und einen persönlichen Zugriffstoken des Calendly-Kontos ein (*Calendly API token*). Der Token lässt sich nach dem Speichern nicht mehr anzeigen. Optional nennen Sie eine Frage Ihres Calendly-Termintyps (*Call summary question*); dort trägt der Agent bei der Buchung eine kurze Zusammenfassung des Gesprächs ein. **ERP.** Wählen Sie im Bereich ERP-Liveverbindung zuerst das ERP-System und, falls mehrere Verbindungen bestehen, die Verbindung. Welche Angaben die angebundenen ERP-Systeme liefern: | ERP-System | Preis | Verfügbarkeit | | --- | --- | --- | | Oracle NetSuite | ja | ja | | SAP Business One | ja | – | | microtech büro+ | ja | ja | | Sage 100 | ja | ja | Liefert ein ERP eine Angabe nicht, bekommt der Agent dafür keine Daten. Ist der zweite Faktor eingeschaltet, nennt der Agent einem noch nicht bestätigten Anrufer nur allgemeine Preise und Bestände, einem bestätigten die seines Kunden. Sage 100 (ab Version 8 der Workist API-Erweiterung) ermittelt Preise nur für einen erkannten Kunden; einem unbekannten Anrufer nennt der Agent dort keinen Preis. ### Schritt 4: Gesprächszusammenfassungen (*Call summaries*) Nach jedem Anruf, in dem der Anrufer etwas gesagt hat, erstellt der Agent eine Zusammenfassung: Anrufer, Kunde, Zeitpunkt, Dauer, Ergebnis, Inhalt, angelegte Belege und ein Link zum Anruf in der Workbench. Die Zusammenfassung ist in der Sprache des Agenten. | Weg | Einstellung | | --- | --- | | E-Mail (*Email*) | Empfängeradressen (*Recipients*). Alle Empfänger erhalten eine gemeinsame E-Mail von Workist. | | Microsoft Teams (*Microsoft Teams*) | Ein Kanal (*Channel*) eines Teams, in dem das verbundene Teams-Konto Mitglied ist. Setzt die [Teams-Verbindung](#microsoft-teams-verbinden) voraus. | Schlägt die Zustellung fehl, versucht Workist es nach 1, 5 und 15 Minuten erneut. Den Zustellstatus je Weg sehen Sie in den Anrufdetails. ### Schritt 5: Prompt (*Prompt*) Im Systemprompt (*System prompt*) beschreiben Sie, wie sich der Agent verhält: Rolle, Ton, Ablauf und wann er welches Werkzeug nutzt. Der Assistent füllt eine Vorlage in der Sprache des Agenten vor; über *Reset to template* kehren Sie zu ihr zurück. - Mit `/` oder über die Listen unter dem Editor fügen Sie Variablen und Werkzeuge ein. Variablen stehen in doppelten geschweiften Klammern; der Agent ersetzt sie während des Anrufs. - Über *Edit with AI* beschreiben Sie eine Änderung in eigenen Worten, z. B. „Lies Artikelnummern und Adressen immer zur Bestätigung vor". Der Prompt wird neu geschrieben und erscheint im Editor; prüfen und speichern Sie ihn. - Workist ergänzt Ihren Prompt um feste Regeln, etwa zum Beenden des Gesprächs, zum zweiten Faktor und zur Bestellauskunft für nicht erkannte Anrufer. Diese Regeln können Sie nicht ändern. Verfügbare Variablen: | Variable | Inhalt | In der Begrüßung | | --- | --- | --- | | `{{caller_name}}` | Name des Anrufers aus der Anrufererkennung | ja | | `{{caller_phone_number}}` | Telefonnummer des Anrufers | – | | `{{client_name}}` | Name des erkannten Kunden (Firma) | – | | `{{client_id}}` | Kundennummer des Anrufers | – | | `{{contact_id}}` | ID des Ansprechpartners | – | | `{{client_street}}` | Straße des Kunden | – | | `{{client_zip_code}}` | Postleitzahl des Kunden | – | | `{{client_city}}` | Ort des Kunden | – | | `{{client_country}}` | Land des Kunden | – | | `{{internal_contact_id}}` | ID des internen Kontakts, als der der Anrufer erkannt wurde (z. B. Außendienst) | – | | `{{internal_contact_name}}` | Name dieses internen Kontakts | – | | `{{internal_contact_email}}` | E-Mail-Adresse dieses internen Kontakts | – | | `{{internal_contact_phone}}` | Telefonnummer dieses internen Kontakts | – | | `{{system__conversation_id}}` | ID des Gesprächs (vom Sprachdienst gesetzt) | – | | `{{system__caller_id}}` | Telefonnummer des Anrufers (vom Sprachdienst gesetzt) | – | | `{{system__call_sid}}` | ID des Anrufs beim Telefonieanbieter | – | Firmenname und Adresse des Kunden sind erst gefüllt, wenn der Agent den Kunden während des Gesprächs über die Kundensuche gefunden hat. ### Schritt 6: Wissen (*Knowledge*) Laden Sie optional Dateien hoch, auf die der Agent im Gespräch zurückgreift, z. B. Lieferbedingungen oder Sortimentslisten. Erlaubte Formate: .txt, .html, .md, .pdf, .doc, .docx. :::warning Inhalte sind für Anrufer hörbar Der Agent gibt Inhalte der Wissensdateien an Anrufer weiter. Laden Sie keine internen oder vertraulichen Dokumente hoch. ::: ### Schritt 7: Zusammenfassung (*Summary*) Prüfen Sie die Einstellungen und legen Sie den Agenten an. ## Sprachagent testen Öffnen Sie in der Übersicht das Menü des Agenten und wählen Sie den Testlink (*Open test link*). Optional tragen Sie Angaben zu einem Anrufer ein, um einen erkannten Anrufer zu simulieren. Danach erzeugen Sie den Link und führen das Testgespräch im Browser. ## Sprachagenten verwalten Die Übersicht zeigt jeden Agenten mit seinem Status, aktiv (*Active*) oder pausiert (*Paused*). Über das Menü eines Agenten: - **Konfiguration** (*Configuration*): alle Einstellungen ändern. - **Testlink** (*Open test link*): siehe oben. - **Pausieren** und **Fortsetzen** (*Pause*, *Resume*): Ein pausierter Agent nimmt keine Rückrufwünsche über Ihre Website an. - **Löschen** (*Delete*): löscht den Agenten, deaktiviert ihn und gibt seine Rufnummer frei. ## Anrufhistorie Klicken Sie auf einen Agenten, um seine Anrufe zu sehen: Anrufer, angelegte Belege, Ergebnis, Stimmung, Dauer und Zeitpunkt. Ein Klick auf einen Anruf öffnet die Details: - Ergebnis, Stimmung des Anrufers, Gesprächsende und angerufene Nummer, - angelegte Belege mit Link, - Zustellstatus der Zusammenfassung je Weg (ausstehend, gesendet, fehlgeschlagen), - die Zusammenfassung, - Aufzeichnung und Transkript. Mögliche Ergebnisse: Einwilligung verweigert, aufgelegt, Termin gebucht, weitergeleitet, Bestellung angelegt, Preisanfrage angelegt, Nachricht gesendet, Frage beantwortet. ## Wo Bestellungen und Preisanfragen landen Ein Sprachagent legt Bestellungen im Bestellkanal und Preisanfragen im Preisanfragen-Kanal an, die Sie im Schritt Werkzeuge gewählt haben. Workist erstellt dazu ein Dokument mit den im Gespräch erfassten Angaben. Es durchläuft die Verarbeitung des Kanals wie ein per E-Mail eingegangenes Dokument. Im Kanal erkennen Sie es am Betreff: eine Nummer, die mit `WVO-` beginnt, gefolgt vom Kundennamen. Das E-Mail-Postfach des Kanals bleibt davon unberührt; E-Mails und Anrufe kommen als getrennte Dokumente an. ## Rückruf über Ihre Website Mit Website-Rückrufen (*Website call requests*) trägt ein Besucher Ihrer Website seine Telefonnummer in ein Rückruf-Widget ein, und der Agent ruft ihn an. | Einstellung | Bedeutung | Standard | | --- | --- | --- | | Erlaubte Ländervorwahlen (*Allowed country prefixes*) | Nur Nummern mit diesen Vorwahlen werden angerufen. Sperrt Sonderrufnummern und fremde Märkte. | +49, +43, +41 | | Tageslimit (*Daily call cap*) | Höchstzahl der Website-Rückrufe pro Tag. | 50 | | Wartezeit pro Nummer (*Cooldown per number*) | Sekunden, bevor dieselbe Nummer erneut einen Rückruf anfordern kann. 0 schaltet die Wartezeit ab. | 3600 | | Einwilligungsfrage auch bei Website-Rückrufen (*Ask for recording consent on website calls*) | Der Besucher hat mit der Anfrage bereits eingewilligt; daher entfällt die Frage normalerweise. Schalten Sie sie hier wieder ein. | aus | Gehen innerhalb einer Minute mehr Anfragen ein als ein Zehntel des Tageslimits, schaltet Workist die Website-Rückrufe des Agenten zum Schutz vor Missbrauch ab. Sie schalten die Funktion in der Konfiguration wieder ein. Die Workbench zeigt keinen Einbettungscode für das Widget an. Sprechen Sie dazu Ihre Ansprechperson bei Workist an. ## Microsoft Teams verbinden Die Teams-Verbindung brauchen die Teams-Statusprüfung, Teams-Nachrichten und Zusammenfassungen in einem Teams-Kanal. Ihr Unternehmen hat genau eine Teams-Verbindung. Der Agent handelt im Namen des verbundenen Kontos: Teams-Nachrichten und Kanalbeiträge erscheinen als Nachrichten dieses Kontos. Ein Benutzer mit der Rolle **Manager** oder **Admin** richtet sie ein: 1. Öffnen Sie **Einstellungen** › **Profil**. Auf der Karte **Microsoft Teams** kopieren Sie den Link zur Administratorzustimmung. 2. Schicken Sie den Link an Ihren Microsoft-365-Administrator. Er stimmt den Berechtigungen für Ihre Organisation zu. 3. Verbinden Sie danach auf derselben Karte das Konto (*Connect to Teams*) und melden Sie sich mit dem Microsoft-Konto an, in dessen Namen der Agent handeln soll. Die App fordert diese Berechtigungen von Microsoft Graph an: | Berechtigung | Wofür | | --- | --- | | `User.Read` | Anmeldung des verbundenen Kontos | | `User.ReadBasic.All` | Interne Kontakte per E-Mail-Adresse finden | | `Presence.Read.All` | Teams-Status interner Kontakte lesen | | `Chat.Create` | Chat mit einem internen Kontakt beginnen | | `Chat.ReadWrite` | Nachricht in diesen Chat schreiben | | `offline_access` | Verbindung ohne erneute Anmeldung aufrechterhalten | | `Team.ReadBasic.All` | Teams für die Kanalauswahl auflisten (nur für Zusammenfassungen in Teams) | | `Channel.ReadBasic.All` | Kanäle für die Kanalauswahl auflisten (nur für Zusammenfassungen in Teams) | | `ChannelMessage.Send` | Gesprächszusammenfassungen in den Kanal posten (nur für Zusammenfassungen in Teams) | Wurde das Konto verbunden, bevor Zusammenfassungen in Teams-Kanäle möglich waren, zeigt die Karte einen Hinweis. Lassen Sie die erweiterten Berechtigungen über den Link erneut bestätigen und verbinden Sie das Konto neu (*Reconnect to Teams*). Über *Disconnect* trennen Sie die Verbindung; danach funktionieren die Teams-Werkzeuge und Zusammenfassungen in Teams nicht mehr. ## Datenschutz - Der Agent zeichnet Anrufe nur nach Einwilligung auf. Aufzeichnung und Transkript sehen Benutzer mit Zugriff auf die Sprachagenten in der Anrufhistorie. - Sprachagenten laufen standardmäßig in der EU-Umgebung des Sprachdienstleisters. Welche Dienstleister beteiligt sind, steht unter [Allgemeine Informationen › Sprachagenten](/docs/faq/general-information.md#sprachagenten). - Antworten des Agenten sind KI-generiert und können Fehler enthalten. Belege aus Anrufen prüfen Sie wie andere Dokumente in der Verarbeitung. ## Häufige Fragen **Kann ich E-Mail-Eingang und Sprachagent parallel nutzen?** Ja. Der Sprachagent legt seine Belege in dem Kanal an, den Sie im Schritt Werkzeuge gewählt haben. Das E-Mail-Postfach des Kanals arbeitet unabhängig davon weiter. **Warum begrüßt der Agent einen Anrufer nicht mit Namen?** Der Anrufer wurde nicht erkannt: Entweder ist keine Anrufererkennung eingerichtet, oder seine Telefonnummer fehlt in den Kundenkontakten. Mit zweitem Faktor nutzt der Agent immer die normale Begrüßung. **Welche Sprachen spricht ein Sprachagent?** Deutsch oder Englisch, eine Sprache pro Agent. Für beide Sprachen legen Sie zwei Agenten an. **Was tue ich bei Problemen mit einem Anruf?** Halten Sie den Namen des Agenten, die angerufene Rufnummer und den ungefähren Zeitpunkt des Anrufs bereit und wenden Sie sich an Ihre Ansprechperson bei Workist. --- Source: https://docs.workist.com/docs/agents/inbox-agents.md # Inbox-Agenten Ein Inbox-Agent bearbeitet Kunden-E-Mails, die kein Beleg sind: Fragen nach Preisen, Verfügbarkeit, Lieferterminen, Sendungsverfolgung oder Produktdaten. Er erkennt das Anliegen, sucht die Antwort in Ihrem ERP, Ihren Stammdaten und Ihren Wissensdateien und erstellt einen Antwortentwurf oder eine interne Zusammenfassung. Das Ergebnis sehen Ihre Mitarbeitenden im [Workist-Add-in für Outlook](/docs/data-exchange/outlook-add-in.md) neben der E-Mail. Inbox-Agenten richten **Manager** und **Admins** ein. Ob Inbox-Agenten in Ihrem Vertrag enthalten sind, klärt Ihre Ansprechperson bei Workist. ## So funktioniert es 1. Ein Postfach ist über die [Smart Inbox](/docs/smart-inbox.md) mit Workist verbunden, meist die Persönliche Smart Inbox eines Mitarbeitenden, und mit einem Inbox-Agenten verknüpft. 2. Die Smart Inbox ordnet jede eingehende E-Mail ein. Bestellungen, Preisanfragen, Rechnungen und Auftragsbestätigungen gehen wie gewohnt in Ihre Kanäle. 3. Alle übrigen E-Mails gehen an den Inbox-Agenten, auch solche, die Sie über Ausschlussregeln der Smart Inbox von der Belegverarbeitung ausgenommen haben. 4. Der Agent erkennt die Anliegen der E-Mail, ruft die nötigen Daten ab und schreibt seine Antwort. 5. Öffnet der Mitarbeitende die E-Mail in Outlook, zeigt das Add-in das Ergebnis. Er kann daraus einen Antwortentwurf erstellen, ihn im Chat mit dem Agenten anpassen lassen und das Ergebnis bewerten. Den Absender ordnet der Agent über seine E-Mail-Adresse einem Kunden und Ansprechpartner aus Ihren Stammdaten zu. Preise und Auskünfte gelten dann für diesen Kunden. ## Voraussetzungen - Rolle **Manager** oder **Admin** zum Anlegen und Ändern, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md). - Mindestens ein über die Smart Inbox verbundenes Postfach. Ein Postfach kann nur mit einem Agenten verknüpft sein. - Das [Workist-Add-in für Outlook](/docs/data-exchange/outlook-add-in.md) bei den Mitarbeitenden, die die Ergebnisse nutzen sollen, idealerweise unternehmensweit verteilt. - Für Preis-, Verfügbarkeits-, Liefertermin- und Tracking-Anfragen ein angebundenes ERP, siehe [Fähigkeiten](#schritt-2-fähigkeiten). ## Inbox-Agent anlegen Öffnen Sie in der linken Navigation **Agenten** und klicken Sie auf **Agent erstellen**. Ein Assistent führt Sie durch sieben Schritte. ### Schritt 1: Grundlagen | Einstellung | Bedeutung | | --- | --- | | **Name** | Pflichtfeld. | | **Zweck** | Nur zur Orientierung, z. B. „Preisanfragen Vertrieb Süd". | | **Team** | Steuert, wer den Agenten sieht: Mitglieder dieses Teams; **Admins** sehen alle Agenten. | ### Schritt 2: Fähigkeiten Wählen Sie, welche Anliegen der Agent bearbeitet: | Fähigkeit | Was der Agent liefert | Voraussetzung | | --- | --- | --- | | **Preis-Anfrage** | Preis eines Artikels für den Kunden | ERP mit Preisabfrage | | **Verfügbarkeit** | Ob ein Artikel verfügbar ist | ERP mit Bestandsabfrage | | **Lieferdatum** | Erwarteter Liefertermin zu einer Bestellung | ERP mit Lieferterminabfrage | | **Tracking-Link** | Link oder Nummer zur Sendungsverfolgung zu einer Bestellung | ERP mit Sendungsverfolgung | | **Produktspezifikation** | Technische Angaben aus Ihren Wissensdateien; der Agent hängt die passende Datei an die Antwort | Wissensdateien und eingeschaltete Dateianhänge (Schritt Wissen) | Kann Ihr ERP eine Fähigkeit nicht bedienen, zeigt der Assistent den Hinweis, dass Ihr ERP die erforderlichen Funktionen nicht bietet. Welche Angaben die ERP-Systeme liefern: | ERP-System | Preis | Verfügbarkeit | Liefertermin | Sendungsverfolgung | | --- | --- | --- | --- | --- | | Oracle NetSuite | ja | ja | ja | ja | | SAP Business One | ja | – | – | ja | | microtech büro+ | ja | ja | ja | ja | | Sage 100 | ja | ja | ja | – | Bei microtech büro+ liefert die Sendungsverfolgung nur Ergebnisse, wenn Workist in Ihrer Integration das Feld für den Tracking-Link eingerichtet hat. Sage 100 setzt Version 8 der Workist API-Erweiterung voraus, siehe [Sage 100](/docs/data-exchange/connectors/sage-100.md#erp-funktionen-der-agenten). ### Schritt 3: Integrationen | Integration | Bedeutung | | --- | --- | | ERP | Das ERP-System und, bei mehreren, die Verbindung. Zur Auswahl stehen die ERP-Integrationen Ihres Unternehmens. | | **Stammdaten** | Ein Kanal, dessen Stammdaten der Agent nutzt, um Absender, Artikel, Kontakte und Adressen zu finden. | | **Bestellhistorie** | Frühere Bestellungen desselben Absenders als Kontext für die Antwort. | | **Microsoft SharePoint** | Synchronisiert Ordner und Dateien aus SharePoint als Wissen, z. B. Preislisten oder technische Dokumentation. Wählen Sie **SharePoint-Verbindung**, **Website**, **Dokumentenbibliothek** und die Wissensquellen. Die Verbindung legt ein **Admin** oder ein Benutzer mit der Rolle **IT** unter **Einstellungen** › **Integrationen** › **Microsoft SharePoint** an. | | Belegerstellung | Standardkanäle für Bestellungen, Auftragsbestätigungen, Preisanfragen, Rechnungen und Lieferscheine. Hierhin reicht der Agent Belege ein: im Add-in, wenn eine E-Mail doch eine Bestellung oder Preisanfrage ist, und bei [Automationen in Worki](/docs/agents/worki.md#automationen). | Ohne Integrationen stützt sich der Agent nur auf Wissensdateien und Expert\*innenwissen; die Ergebnisse sind dann weniger genau. ### Schritt 4: Wissen | Einstellung | Bedeutung | | --- | --- | | **Expert\*innenwissen** | Regeln, die nicht in Ihren Daten stehen, in eigenen Abschnitten. Zum Beispiel „Kunde ABC erhält immer 15 % Rabatt" oder „Artikel, die mit A beginnen, haben eine Bearbeitungsgebühr von 5 €". | | **Wissensdateien** | Erlaubte Formate: .c, .cpp, .cs, .css, .csv, .doc, .docx, .go, .html, .java, .js, .json, .md, .pdf, .php, .pptx, .py, .rb, .sh, .tex, .ts, .txt. | | Webseiten | Bis zu 10 Adressen, die mit `https://` beginnen, z. B. Produktkataloge oder Datenblätter. Workist aktualisiert den Inhalt alle paar Stunden. | | Dateianhänge | Der Agent darf passende Wissensdateien an Antworten anhängen. Das funktioniert nur, wenn die Smart Inbox des Postfachs die aktuelle Administratorzustimmung hat. | ### Schritt 5: Antwort | Einstellung | Bedeutung | | --- | --- | | **Antwort** | Automatisch: Der Agent entscheidet pro E-Mail; einen Entwurf, wenn er die Anfrage beantworten konnte, sonst eine interne Zusammenfassung. **Entwurf einer E-Mail**: immer ein Antwortentwurf an den Kunden. **Zusammenfassung**: immer eine interne Zusammenfassung zur Prüfung. | | **Ausgabeanweisungen** | Ton, Stil und Tabus der Antwort, z. B. „Förmlich bleiben" oder „In der Sprache des Kunden antworten". | ### Schritt 6: Benutzer Wählen Sie die Postfächer, deren E-Mails der Agent bearbeitet. Hier erscheinen nur Postfächer, die über die Smart Inbox verbunden sind. Mitarbeitende mit eingerichteter Persönlicher Smart Inbox können sich außerdem auf ihrer Profilseite selbst mit einem Agenten ihres Teams verbinden oder trennen. Ist ein Postfach bereits mit einem anderen Agenten verknüpft, wechselt es beim Verbinden zu diesem Agenten. ### Schritt 7: Zusammenfassung Prüfen Sie die Einstellungen und legen Sie den Agenten an. Die Zusammenfassung verweist auf die Einstellungen des Outlook-Add-ins, über die Sie das Add-in in Ihrem Unternehmen verteilen. ## Agenten verwalten Unter **Agenten** sehen Sie alle Agenten Ihrer Teams mit ihrem Status **Aktiv** oder **Pausiert**. Über das Menü eines Agenten: - Einstellungen öffnen (im Verlauf des Agenten: **Agent verwalten**): alle Bereiche aus dem Assistenten ändern; speichern mit **Speichern**. - **Pausieren** und **Fortsetzen**: Ein pausierter Agent bearbeitet keine neuen E-Mails. - **Löschen**: entfernt den Agenten endgültig. Das Projekt des Agenten mit Anweisungen und Wissen steht auch in [Worki](/docs/agents/worki.md#projekte-von-inbox-agenten) zur Verfügung. ## Verlauf Ein Klick auf einen Agenten öffnet seinen **Verlauf**: alle bearbeiteten E-Mails mit Absender, Betreff, Status und Dauer. Filtern Sie nach Status, Absender, Ersteller und Zeitraum oder suchen Sie nach dem Betreff. | Status | Bedeutung | | --- | --- | | **Denken** | Der Agent arbeitet noch. | | **Antwort bereit** | Das Ergebnis liegt vor. | | **Keine Aktionen erkannt** | Die E-Mail enthielt kein Anliegen, das der Agent bearbeiten kann. | | **Fehler** | Die Bearbeitung ist fehlgeschlagen. | Ein Klick auf einen Eintrag zeigt **Empfangene Daten**, **Identifizierte Aktionen**, **Generierter Antworttext**, die **Agentenlogik** und das **Feedback** der Mitarbeitenden. Über das Menü eines Eintrags wählen Sie **Erneut versuchen** (bei Fehlern), **Erneut verarbeiten** (mit den aktuellen Einstellungen) oder **Löschen**. ## KI-Hinweis Antworten des Agenten sind KI-generiert und können Fehler enthalten. Auf eingehende E-Mails antwortet der Agent nicht selbst: Ihre Mitarbeitenden prüfen den Entwurf im Add-in und senden ihn. Ausnahme sind [Automationen in Worki](/docs/agents/worki.md#automationen); dort führt der Agent Ihre Anweisung ohne Rückfrage aus. --- Source: https://docs.workist.com/docs/master-data.md # Stammdaten Stammdaten bilden die Basis für eine korrekte automatische Verarbeitung. Workist gleicht alle extrahierten Dokumentinformationen gegen Ihre Stammdaten ab. Sie verwalten Ihre Stammdaten im [Master Data Hub](/docs/master-data/master-data-hub.md): Dort legen Sie Stammdatenlisten an, ordnen sie Kanälen zu, konfigurieren den Import und prüfen die importierten Daten. Wie Sie die erste Lieferung einrichten, beschreibt [Schritt 2 des Implementierungsleitfadens](/docs/implementation-guide/step-2-configure-and-upload-master-data.md). ## Stammdaten-Typen | Typ | Beschreibung | |-----|-------------| | [Kunden & Lieferanten](/docs/master-data/customers.md) | Stammdaten zur Erkennung von Kunden bzw. Lieferanten | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | Stammdaten zur Erkennung von Ansprechpersonen | | [Liefer- und Rechnungsempfänger](/docs/master-data/delivery-and-invoice-recipients.md) | Adressen für Lieferung und Rechnung | | [(Kundenspezifische) Artikel](/docs/master-data/articles.md) | Artikellisten (mindestens eine ist Pflicht) | | [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | Umrechnungsquotienten für Einheiten | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | Stammdaten zur Validierung von Rahmenvertragsnummern | | [Angebote](/docs/master-data/quotes.md) | Stammdaten zum Abgleich von Bestellungen mit Ihren Angeboten | | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | Stammdaten zum Abgleich von Auftragsbestätigungen und Rechnungen mit Ihren Bestellungen | :::warning Auch wenn Kundendaten in vielen Systemen als eine Art von Adressen behandelt werden, gilt in Workist für Kunden ein eigenes Format! ::: ## Welcher Dokumenttyp welche Liste nutzt {#listen-pro-dokumenttyp} Ein Kanal verweist in seiner Konfiguration pro Feld auf eine Stammdatenliste. Dieselbe Liste kann in mehreren Kanälen verwendet werden. Liefer- und Rechnungsadressen sowie allgemeine und kundenspezifische Artikel haben jeweils dieselbe Struktur; welche Rolle eine Liste spielt, legt erst das Feld im Kanal fest. Die Zuordnung nehmen Sie im [Master Data Hub](/docs/master-data/master-data-hub.md#kanaele-zuordnen) vor. | Stammdatenliste | Feld im Kanal | Anfragen | Bestellungen | Auftragsbestätigungen | Rechnungen | Lieferscheine | Leistungsverzeichnisse | | --- | --- | --- | --- | --- | --- | --- | --- | | [Kunden](/docs/master-data/customers.md) | Client-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | [Empfänger (Kundenliste)](/docs/master-data/customers.md) | Empfänger-Lookup-ID | | | ✓ | | ✓ | | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | Kontakt-Lookup-ID | ✓ | ✓ | | ✓ | | ✓ | | [Interne Kontakte (Kontaktliste)](/docs/master-data/customer-contacts.md) | – | ✓ | ✓ | | | | | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | ID der Rahmenvertragsuche | ✓ | ✓ | | | | | | [Rechnungsadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Rechnungsadressen-Lookup-ID | ✓ | ✓ | | ✓ | | ✓ | | [Lieferadressen](/docs/master-data/delivery-and-invoice-recipients.md) | Lieferadressen-Lookup-ID | ✓ | ✓ | ✓ | | ✓ | ✓ | | [Artikel (allgemeine Liste)](/docs/master-data/articles.md) | Artikel-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | [Kundenspezifische Artikel](/docs/master-data/articles.md) | Debitorenartikel-Lookup-ID | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | | [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | Umrechnungsfaktor-Lookup-ID | ✓ | ✓ | | | ✓ | | | [Abzugleichende Bestellungen](/docs/master-data/orders-to-be-matched.md) | Bestellabgleich-Lookup-ID | | | ✓ | ✓ | | | | [Angebote](/docs/master-data/quotes.md) | Angebotsabgleich-Lookup-ID | | ✓ | | | | | Daneben gibt es Felder für gelernte Zuordnungen (Mappings). Diese Listen füllt Workist selbst, siehe [Gelernte Daten](/docs/master-data/master-data-hub.md#gelernte-daten). ## Dateiformat {#dateiformat} Workist importiert CSV-Dateien. Per SFTP gelieferte Dateien dürfen auch Excel-Dateien (`.xls`, `.xlsx`) sein. Die erste Zeile enthält die Spaltennamen. Trennzeichen und Codierung legen Sie in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) der Liste fest. Ohne Angabe liest Workist die Datei kommagetrennt und als UTF-8. Beim Import erkennt Workist das Trennzeichen nicht automatisch; der [Probelauf](/docs/master-data/master-data-hub.md#probelauf) schlägt aber passende Werte vor. Vorschlag von Workist: | Parameter | Wert | |-----------|------| | Trennzeichen | `;` oder `,` | | Escape-Zeichen | `\` | | Anführungszeichen | `"` | | Codierung | UTF-8 | ## Wie Workist Werte beim Import vereinheitlicht {#werte-vereinheitlichen} - **Leerzeichen und Zeilenumbrüche:** Leerzeichen am Anfang und Ende von Werten und Spaltennamen entfernt Workist. Zeilenumbrüche innerhalb einer Zelle ersetzt es durch Leerzeichen. - **Doppelte Zeilen:** Identische Zeilen importiert Workist nur einmal. - **Zahlen** (Preise, Mengen): Komma und Punkt sind als Dezimaltrennzeichen erlaubt. Enthält ein Wert beides, gilt das zuletzt stehende Zeichen als Dezimaltrennzeichen: `1.234,56` und `1,234.56` ergeben beide 1234,56. Ein einzelnes Trennzeichen liest Workist immer als Dezimaltrennzeichen: `1.000` ergibt 1. Ausnahme: Der `conversion_quotient` der [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) braucht einen Punkt als Dezimaltrennzeichen. - **Datumsangaben:** `JJJJ-MM-TT` (z. B. `2024-12-31`) oder mit dem Tag zuerst (z. B. `31.12.2024`). Datumsangaben, die Workist nicht lesen kann, bleiben leer. - **Länder** (`country`): Ländernamen und Ländercodes wandelt Workist in den zweistelligen ISO-Code um (z. B. `Deutschland` → `DE`). Nicht erkannte Werte bleiben leer. - **Domains** (`domain`): Workist schreibt Domains klein und verwirft Freemail-Domains wie `gmail.com`. - **Einheitenlisten** (`order_units`, `sales_units`): als Liste in einer Zelle, z. B. `["KAR","ST"]` oder `['KAR','ST']`. Ein einzelner Wert wird zu einer Liste mit einem Eintrag; `KAR,ST` ohne eckige Klammern ist eine einzige Einheit. Eine leere Zelle wird als `["ST"]` importiert. - **`partition_id`:** Eine leere `partition_id` speichert Workist als `main`, siehe nächster Abschnitt. ## Zuordnung zu Kunden: `partition_id` {#partition-id} Viele Listen haben eine Spalte `partition_id`. Sie enthält die `client_id1` des Kunden (bzw. Geschäftspartners), zu dem eine Zeile gehört. Workist sucht dann nur unter den Zeilen des erkannten Kunden, was die Erkennung deutlich verbessert. - **Leere `partition_id`:** Workist speichert die Zeile mit der Partition `main`. Kontakte, Adressen, Rahmenverträge, Angebote und Bestellungen mit `main` bietet Workist bei jedem Kunden an, zusätzlich zu den Zeilen des erkannten Kunden. - **Artikel:** Hier gibt es keinen Rückfall auf `main`. Zeilen mit einer `partition_id` gelten nur für diesen Kunden. Die allgemeine Artikelliste pflegen Sie ohne `partition_id`. - **Einheitenkonvertierung:** Die `partition_id` wirkt nur, wenn im Kanal die partitionsspezifische Einheitenkonversion aktiv ist. Findet Workist für den Kunden keine Umrechnung, verwendet es die Umrechnungen ohne `partition_id`. - **Keine Prüfung:** Workist prüft beim Import nicht, ob es zur `partition_id` einen Kunden gibt. ## Wie ein Import Ihre Daten ersetzt {#importverhalten} - **Vollimport (Standard):** Jeder erfolgreiche Import ersetzt den gesamten Inhalt der Liste. Zeilen, die in der neuen Datei fehlen, entfernt Workist. Die neue Version ist sofort aktiv; einen Entwurfs- oder Freigabemodus gibt es nicht. - **Delta-Import (auf Anfrage):** Auf Wunsch richtet Workist für eine Liste Delta-Importe ein. Ihre Datei enthält dann nur geänderte Zeilen und eine Statusspalte: Zeilen mit dem Status `A` legt Workist an oder aktualisiert sie, Zeilen mit einem anderen Status (z. B. `X`) löscht es, und Zeilen, die nicht in der Datei stehen, bleiben unverändert. Welche Spalten eine Zeile eindeutig kennzeichnen und wie die Statusspalte heißt, legt Workist bei der Einrichtung mit Ihnen fest. Fehlt die Statusspalte in einer Datei oder ist sie leer, behandelt Workist die Datei als Vollimport. - **Leere Datei:** Enthält eine Datei nach dem Einlesen keine Datenzeilen, bricht Workist den Import ab und behält die bisherigen Daten. - **Unveränderte Datei:** Haben sich Datei und Importkonfiguration seit dem letzten erfolgreichen Import nicht geändert, übernimmt Workist dessen Ergebnis, ohne die Datei erneut zu verarbeiten. - **Neuere Lieferung:** Kommt für eine Liste eine neue Datei an, während ein älterer Import noch wartet, bricht Workist den älteren Import ab und importiert die neue Datei. - **Höchstens etwa 12 Importe pro Stunde:** Pro Liste startet Workist höchstens etwa 12 Importe pro Stunde. Darüber hinaus per SFTP gelieferte Dateien überspringt Workist; über die API und beim Import aus dem SFTP-Verzeichnis im Master Data Hub erhalten Sie eine Fehlermeldung. ## Datenmodell Die Listen sind über Nummern miteinander verknüpft. Es sind lose Verweise: Workist prüft beim Import nicht, ob eine referenzierte Nummer existiert. `client_id1` und `article_id1` müssen nicht eindeutig sein; ein Artikel kann z. B. pro Kunde oder pro Vertriebsorganisation mehrfach vorkommen. Liefer- und Rechnungsadressen (`DeliveryAddress`, `InvoiceAddress`) haben dieselbe Struktur, ebenso allgemeine und kundenspezifische Artikel (`Article`, `ClientArticle`). Die Spalte `extra_data` ist der Übersicht halber nicht dargestellt. ```mermaid classDiagram class Client{ client_id1 client_id2 client_id3 company_name address1 street_name street_number address2 zip_code city country_subdivision country po_box misc client_type client_contact_person1 domain iln vat iban swift locale_numeric locale internal_note partition_id } class Contact{ contact_id first_name last_name phone mobile_phone email partition_id } class DeliveryAddress{ partition_id address_id1 address_id2 address_id3 name address1 street_name street_number address2 zip_code city country_subdivision country po_box misc contact_person phone } class InvoiceAddress{ partition_id address_id1 address_id2 address_id3 name address1 street_name street_number address2 zip_code city country_subdivision country po_box misc contact_person phone } class FrameworkContract{ partition_id client_id client_name contract_id1 contract_id2 contract_name } class Article{ partition_id article_id1 article_id2 article_id3 description article_status gross_price order_units sales_units sales_organisation variants } class ClientArticle{ partition_id article_id1 article_id2 article_id3 description article_status gross_price order_units sales_units sales_organisation variants } class ConversionFactor{ partition_id article_id source_unit target_unit conversion_quotient } class Order{ partition_id order_number external_reference order_date delivery_address receiver_number order_total_price iban swift account payment_terms_type payment_terms_discount payment_terms_due_days position_number article_id1 article_id2 article_id3 article_description article_price price_unit quantity unit total_price delivery_date } class Offer{ partition_id offer_number valid_from valid_until position_number article_id1 article_id2 article_id3 article_description quantity unit } Client "0..1" -- "*" Contact : partition_id Client "0..1" -- "*" DeliveryAddress : partition_id Client "0..1" -- "*" InvoiceAddress : partition_id Client "0..1" -- "*" FrameworkContract : partition_id Client "1" -- "*" ClientArticle : partition_id ClientArticle "*" --> "1" Article : article_id1 Client "0..1" -- "*" ConversionFactor : partition_id ConversionFactor "*" --> "1" Article : article_id Client "0..1" -- "*" Order : partition_id Order "*" --> "0..1" Article : article_id1 Order "*" --> "0..1" DeliveryAddress : delivery_address Order "*" --> "0..1" Client : receiver_number Client "0..1" -- "*" Offer : partition_id Offer "*" --> "0..1" Article : article_id1 ``` --- Source: https://docs.workist.com/docs/master-data/master-data-hub.md # Master Data Hub Im Master Data Hub verwalten Sie alle Stammdatenlisten Ihrer Organisation an einer Stelle. Sie legen Listen an, ordnen sie Kanälen zu, konfigurieren den Import, laden Dateien hoch, durchsuchen die importierten Daten und prüfen, ob Importe erfolgreich waren. Den Master Data Hub nutzen Benutzer mit der Rolle **Manager**, **IT** oder **Admin** (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). Andere Benutzer sehen ihn nicht. ## Master Data Hub öffnen - Klicken Sie unten in der linken Navigationsleiste auf **Einstellungen** und wählen Sie den Eintrag für die Stammdaten. - Aus einem Kanal: Öffnen Sie im Kanal das Menü und wählen Sie **Stammdaten verwalten**. Sie sehen die **Stammdatenimporte** aller Listen des Kanals. Das Zahnrad am Ende einer Zeile (**Import konfigurieren**) öffnet die Liste im Master Data Hub in einem neuen Tab. - Aus der Kanal-Konfiguration: Unter **Stammdaten** steht neben jedem Feld ein Zahnrad, das die zugeordnete Liste im Master Data Hub öffnet. ## Übersicht Die Übersicht hat zwei Reiter: einen für die Daten, die Sie bereitstellen (Ihre importierten Stammdatenlisten), und einen für die [gelernten Daten](#gelernte-daten). Die Tabelle zeigt pro Liste den Namen, den Typ, die ID, die Anzahl der Einträge, die Anzahl der Kanäle, die die Liste verwenden, und den Zeitpunkt der letzten Aktualisierung. Sie können nach Typ und nach Kanal filtern und nach Name oder letzter Aktualisierung sortieren. Ein Klick auf den Namen öffnet die Detailseite der Liste. Die ID einer Liste benötigen Sie, wenn Sie Daten über die [Stammdaten-API](/docs/api-documentation/master-data-api.md) liefern. ## Liste anlegen {#liste-anlegen} 1. Klicken Sie in der Übersicht oben rechts auf die Schaltfläche zum Hinzufügen einer Liste. 2. Wählen Sie den Typ: **Artikel**, **Kunden**, **Kundenkontakte**, **Adressen**, **Einheitenkonvertierung**, **Rahmenverträge**, **Bestellungen** oder **Angebote**. 3. Geben Sie einen Namen ein und bestätigen Sie. Workist öffnet die Detailseite der neuen Liste. Für jede Rolle im Kanal brauchen Sie eine eigene Liste. Liefer- und Rechnungsadressen sind zwei Listen vom Typ **Adressen**, die allgemeine und die kundenspezifische Artikelliste zwei Listen vom Typ **Artikel**. Welche Liste ein Dokumenttyp nutzt, zeigt die Tabelle unter [Welcher Dokumenttyp welche Liste nutzt](/docs/master-data.md#listen-pro-dokumenttyp). :::tip Beim Anlegen eines neuen Kanals legt Workist für die wichtigsten Felder bereits leere Listen an und ordnet sie dem Kanal zu. Prüfen Sie in der Übersicht mit dem Kanalfilter, welche Listen ein Kanal schon hat, bevor Sie neue anlegen. ::: ## Detailseite einer Liste Die Detailseite hat bis zu vier Reiter: | Inhalt des Reiters | Was Sie dort tun | | --- | --- | | Allgemeine Angaben | Name ändern, Typ, ID, Anzahl der Einträge und letzte Aktualisierung einsehen, [Kanälen zuordnen](#kanaele-zuordnen), [Liste löschen](#liste-loeschen) | | Daten | Importierte Datensätze im [Datenexplorer](#datenexplorer) durchsuchen | | Importe | [Importhistorie](#importhistorie) einsehen, [aus dem SFTP-Verzeichnis importieren](#import-aus-sftp), [Datei hochladen](#datei-hochladen) | | Konfiguration | [Importkonfiguration](/docs/master-data/transformer-configuration.md) bearbeiten und mit einem [Probelauf](#probelauf) testen | Listen mit gelernten Daten haben nur die ersten beiden Reiter. ### Kanälen zuordnen {#kanaele-zuordnen} Im Bereich für die Kanalzuordnung auf dem ersten Reiter sehen Sie pro Dokumenttyp die Felder, in denen dieser Listentyp verwendet werden kann, z. B. **Client-Lookup-ID** oder **Artikel-Lookup-ID**. 1. Klicken Sie in das Feld und wählen Sie einen Kanal. Workist trägt die Liste sofort in die Kanal-Konfiguration ein. 2. Verweist das Feld im Kanal bereits auf eine andere Liste, zeigt Workist eine Warnung. Bestätigen Sie, um die bisherige Liste zu ersetzen, oder brechen Sie ab. 3. Um eine Zuordnung aufzuheben, entfernen Sie den Kanal aus dem Feld. Alternativ wählen Sie die Liste in der Kanal-Konfiguration unter **Stammdaten** im jeweiligen Feld aus. ### Liste umbenennen Ändern Sie auf dem ersten Reiter den Namen und speichern Sie. Der Name dient nur der Übersicht; Kanäle verweisen über die ID auf die Liste. ### Liste löschen {#liste-loeschen} Im rot markierten Bereich am Ende des ersten Reiters löschen Sie eine Liste mit allen ihren Daten. Das lässt sich nicht rückgängig machen. Solange die Liste einem Kanal zugeordnet ist, können Sie sie nicht löschen: Heben Sie vorher alle Zuordnungen auf. ## Import konfigurieren Auf dem Reiter für die Konfiguration legen Sie fest, welche Datei Workist liest, wie es sie einliest und wie die Spalten Ihrer Datei auf die Spalten von Workist abgebildet werden. Die Konfiguration gilt für alle Lieferwege: SFTP, API und Upload in der Workbench. Die Schritt-für-Schritt-Anleitung finden Sie unter [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md). Änderungen markiert Workist als ungespeichert. Probeläufe verwenden ungespeicherte Änderungen bereits, Importe erst nach dem Speichern. ### Probelauf {#probelauf} Mit einem Probelauf testen Sie die aktuelle Konfiguration, einschließlich ungespeicherter Änderungen. Workist liest die Datei ein und wandelt sie um wie bei einem echten Import, importiert und speichert aber nichts. 1. Wählen Sie die Eingabedatei: - die zuletzt importierte Datei je Dateinamensmuster, wie bei einem regulären Import, - die neueste Datei im SFTP-Verzeichnis je Dateinamensmuster, auch wenn sie noch nicht importiert wurde, oder - eine Datei von Ihrem Computer (CSV oder Excel, zusammen höchstens 25 MB). Die Datei wird nicht gespeichert. 2. Starten Sie den Probelauf. Ergebnis: - Bei Erfolg zeigt Workist die Anzahl der umgewandelten Zeilen und einige Beispielzeilen so, wie sie importiert würden. Der Probelauf verarbeitet höchstens 100 Zeilen; Fehler in späteren Zeilen erkennt er nicht. - Bei einem Fehler zeigt Workist die Fehlermeldung. Ein ausklappbares Protokoll zeigt die einzelnen Verarbeitungsschritte. - Workist schlägt außerdem eine Konfiguration vor: Es liest Trennzeichen, Codierung und Anführungszeichen aus der Datei und ordnet Spalten zu, die genau wie eine Workist-Spalte heißen. Weicht das von Ihrer Konfiguration ab, zeigt Workist die Unterschiede und übernimmt sie auf Wunsch ins Formular. Spalten der Datei ohne passende Workist-Spalte fügt es als nicht zugeordnete Zeilen hinzu, die Sie selbst zuordnen. Nicht zugeordnete Zeilen entfernt Workist beim Speichern. Für Listen mit einem individuellen Importskript schlägt der Probelauf keine Konfiguration vor. Speichern Sie die Konfiguration erst, wenn der Probelauf erfolgreich war. ## Daten importieren Workist importiert eine Datei automatisch, sobald sie im SFTP-Verzeichnis ankommt oder über die API geliefert wird. Auf dem Reiter für die Importe können Sie außerdem selbst einen Import starten. ### Import aus dem SFTP-Verzeichnis {#import-aus-sftp} Die Karte zeigt pro Dateinamensmuster die neueste passende Datei in Ihrem SFTP-Verzeichnis mit Name, Muster, Größe und Änderungsdatum. Ein Klick auf die Schaltfläche zum Importieren importiert diese Dateien sofort. Für Muster ohne Datei im SFTP-Verzeichnis verwendet Workist die zuletzt importierte Datei. So wenden Sie eine geänderte Konfiguration an, ohne die Datei erneut hochzuladen. Liegt keine passende Datei im SFTP-Verzeichnis, ist die Schaltfläche deaktiviert. ### Datei hochladen {#datei-hochladen} 1. Ziehen Sie eine CSV-Datei in die Karte zum Hochladen oder klicken Sie, um sie auszuwählen. Die Karte zeigt die Spalten, die eine Datei für diesen Listentyp enthalten kann. 2. Klicken Sie auf die Schaltfläche zum Importieren. Workist verarbeitet die Datei mit der Importkonfiguration der Liste und ersetzt nach erfolgreichem Import die bisherigen Daten (siehe [Wie ein Import Ihre Daten ersetzt](/docs/master-data.md#importverhalten)). Die Bestätigung im Browser bedeutet nur, dass die Datei angenommen wurde; das Ergebnis sehen Sie in der Importhistorie. Excel-Dateien liefern Sie per SFTP. ### Importhistorie {#importhistorie} Die Importhistorie zeigt alle Importläufe der Liste mit Status, **Importiert am**, **Dauer**, **Gestartet über** (Workbench, SFTP, API oder Workist-Kundensupport), **Eingabedatei** und **Ausgabedatei** mit jeweils Zeilen und Größe. Die Ausgabedatei enthält die Daten so, wie Workist sie nach der Umwandlung importiert hat; damit prüfen Sie Ihre Spaltenzuordnung. Ein Haken markiert den Import, dessen Daten aktuell verwendet werden. Mit **Nur aktive Stammdaten anzeigen** blenden Sie alle anderen Läufe aus. Dieselbe Tabelle sehen Sie für alle Listen eines Kanals unter **Stammdaten verwalten** im Kanal. | Status | Bedeutung | | --- | --- | | **Ausstehend** | Der Import wartet auf den Start. | | **Laufend** | Workist verarbeitet die Datei. Bei sehr vielen neuen Zeilen bleibt ein Import länger in diesem Status. | | **Abgeschlossen** | Die Daten sind aktiv. | | **Fehler** | Der Import ist fehlgeschlagen. Schlägt das Einlesen oder Umwandeln der Datei fehl, bleiben die bisherigen Daten aktiv. | | **Abgebrochen** | Ein neuerer Import für dieselbe Liste hat diesen ersetzt, oder die Datei enthielt keine Datenzeilen. Die bisherigen Daten bleiben aktiv. | ### Fehlermeldungen {#fehlermeldungen} Bei einem fehlgeschlagenen Import zeigt Workist am Status eine Erklärung. Über das Fragezeichen daneben öffnen Sie die vollständige Fehlermeldung. | Fehler | Ursache | Was Sie tun können | Benachrichtigung | | --- | --- | --- | --- | | **Unerwartete Datei-Kodierung** | Die Datei hat nicht die Codierung aus der Importkonfiguration. | Datei in der erwarteten Codierung liefern oder die Codierung in der Konfiguration anpassen. | E-Mail an die Rolle IT | | **Unerwartetes Trennzeichen** | Die Datei verwendet ein anderes Trennzeichen als in der Konfiguration eingestellt. | Datei mit dem erwarteten Trennzeichen liefern oder das Trennzeichen in der Konfiguration anpassen. | E-Mail an die Rolle IT | | **Unerwartetes Dateiformat** | Eine Spalte aus der Spaltenzuordnung fehlt in der Datei. | Spalte in der Datei ergänzen oder die Spaltenzuordnung anpassen. | E-Mail an die Rolle IT | | **Nicht verarbeitbarer Wert** | Ein Wert lässt sich nicht umwandeln, z. B. Text in einer Preisspalte, oder die Datei ist leer. | Wert in der genannten Zeile und Spalte korrigieren. | E-Mail an die Rolle IT | | **Nicht verarbeitbare Zeile** | Eine Zeile hat zu viele oder zu wenige Trennzeichen oder fehlerhafte Anführungszeichen. | Zeile prüfen und korrigieren. | E-Mail an die Rolle IT | | **Unbekannte Datei** | Die Datei passt zu keiner Liste. | – | Workist | | **Fehlende Datei** | Die Liste braucht mehrere Dateien, eine davon fehlt. | Die genannte Datei liefern. | Workist | | **Nicht standardisiertes Dateiformat** | Die umgewandelte Datei entspricht nicht dem Workist-Format. | – | Workist | | **Temporäre Unverfügbarkeit** | Workist war vorübergehend nicht erreichbar. | Datei erneut liefern. | Workist | | Sonstige Fehler | z. B. eine fehlerhafte Importkonfiguration | Konfiguration mit einem [Probelauf](#probelauf) prüfen. | Workist | ### E-Mail bei fehlgeschlagenem Import Bei den Fehlern, die Sie selbst beheben können (in der Tabelle mit „E-Mail an die Rolle IT“), erhalten alle Benutzer mit der Rolle **IT** eine E-Mail mit der Fehlermeldung und einem Link zu den Stammdatenimporten des Kanals. Voraussetzung ist, dass die Liste mindestens einem Kanal zugeordnet ist. Alle anderen Fehler meldet das System direkt an Workist. ## Daten durchsuchen {#datenexplorer} Der Datenexplorer auf dem Reiter für die Daten zeigt die Datensätze der aktiven Version als Tabelle. Über die Suchfelder in den Spaltenköpfen filtern Sie nach einzelnen Spalten. Weitere Datensätze laden Sie am Ende der Tabelle nach. Zusätzliche Angaben aus `extra_data` zeigt Workist in einer eigenen Spalte. ## Gelernte Daten {#gelernte-daten} Der zweite Reiter der Übersicht listet die gelernten Daten: Zuordnungen, die Workist aus Ihren Korrekturen in der Assistenz lernt, z. B. welcher Kunde, Kontakt, Artikel oder welche Adresse zu einem Wert auf dem Dokument gehört. Diese Listen pflegt Workist selbst; Sie importieren nichts. Auf der Detailseite sehen Sie die gelernten Einträge. Im rot markierten Bereich können Sie alle Einträge löschen, die vor einem gewählten Datum entstanden sind, z. B. nachdem sich Ihre Stammdaten grundlegend geändert haben. Das lässt sich nicht rückgängig machen. ## Stammdatenstand im Dokument Im Dokument zeigt die Schaltfläche **Stammdaten anzeigen** oben in der Assistenz den **Stammdaten-Status**: mit welchem Stand jeder Liste Workist das Dokument verarbeitet hat (**Importiert am**) und ob das noch die **Neueste Version** oder eine **Veraltete Version** ist. **Details anzeigen** öffnet die Stammdatenimporte. Gibt es neuere Stammdaten, weist Workist darauf hin. Mit **Dokument erneut verarbeiten** verarbeitet Workist das Dokument mit den aktuellen Stammdaten neu. --- Source: https://docs.workist.com/docs/master-data/customers.md # Kunden- und Lieferantenstammdaten Stammdaten zur Erkennung von Kunden oder Lieferanten. Bei Auftragsbestätigungen (OC) und Rechnungen wird der Geschäftspartner in der Regel als Kunde geführt, bei Lieferscheinen kann er je nach Anwendungsfall als Kunde oder als Lieferant auftreten. Bei der Ausgabe wird in der Regel nur die `client_id1` zurückgegeben. Die anderen Informationen helfen der KI, den richtigen Kunden bzw. Lieferanten zu identifizieren. Eine Liste dieses Typs kann im Kanal auch als Empfängerliste (Feld **Empfänger-Lookup-ID**) dienen. Damit erkennt Workist bei Auftragsbestätigungen und Lieferscheinen den Käufer bzw. Empfänger. Welche Liste welcher Dokumenttyp nutzt, steht unter [Welcher Dokumenttyp welche Liste nutzt](/docs/master-data.md#listen-pro-dokumenttyp). ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `client_id1` | Pflichtfeld | Primäre Kunden- bzw. Lieferantennummer. Diese Nummer gibt Workist in der Ausgabe zurück. | | 2 | `client_id2` | Optional | Sekundäre Kunden- bzw. Lieferantennummer | | 3 | `client_id3` | Optional | Tertiäre Kunden- bzw. Lieferantennummer | | 4 | `company_name` | Empfohlen | Name des Kunden bzw. Lieferanten | | 5 | `address1` | Empfohlen | Straße und Hausnummer in einer Spalte (z. B. Musterstraße 1) | | 6 | `street_name` | Optional | Straßenname, wenn Straße und Hausnummer getrennt vorliegen. Alternative zu `address1`. | | 7 | `street_number` | Optional | Hausnummer, wenn getrennt von `street_name` | | 8 | `address2` | Optional | Weitere Adresszeile | | 9 | `zip_code` | Empfohlen | Postleitzahl | | 10 | `city` | Empfohlen | Stadt | | 11 | `country_subdivision` | Optional | Bundesland bzw. Region | | 12 | `country` | Empfohlen | Land. Ländernamen und drei- oder einstellige Ländercodes wandelt Workist in den zweistelligen ISO-Code um (z. B. `Deutschland` → `DE`). Nicht erkannte Werte bleiben leer. | | 13 | `po_box` | Optional | Postfach | | 14 | `misc` | Optional | Zusätzliche Informationen zur Adresse | | 15 | `client_type` | Optional | Kategorie oder Typ des Kunden bzw. Lieferanten | | 16 | `client_contact_person1` | Optional | Kontaktperson als einzelnes Textfeld. Bei mehreren Kontakten pro Kunde liefern Sie besser eine eigene [Kontaktliste](/docs/master-data/customer-contacts.md). | | 17 | `domain` | Optional | Internetdomäne des Kunden, z. B. `muster.de`. Workist schreibt sie klein; Freemail-Domains wie `gmail.com` verwirft Workist beim Import. | | 18 | `iln` | Optional | Internationale Lokationsnummer (GLN/ILN) | | 19 | `vat` | Optional | Umsatzsteuer-Identifikationsnummer | | 20 | `iban` | Optional | IBAN des Kunden bzw. Lieferanten | | 21 | `swift` | Optional | BIC des Kunden bzw. Lieferanten | | 22 | `locale_numeric` | Optional | Zahlenformat auf den Dokumenten dieses Kunden: `de` (1.234,56) oder `en` (1,234.56). Hilft Workist, Mengen und Preise richtig zu lesen. | | 23 | `locale` | Optional | Sprache und Region der Dokumente dieses Kunden, z. B. `de_DE`. Workist liest damit Datumsangaben und nutzt sie als Zahlenformat, wenn `locale_numeric` leer ist. | | 24 | `internal_note` | Optional | Interne Anmerkungen oder Notizen | | 25 | `partition_id` | Optional | In der Kundenliste in der Regel leer lassen. | | 26 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `client_list.csv` ```csv client_id1;client_id2;company_name;address1;zip_code;city;country K001;10001;Muster GmbH;Musterstraße 1;12345;Berlin;DE K002;10002;Beispiel AG;Beispielweg 5;20099;Hamburg;DE K003;;Test & Co. KG;Testplatz 3;80331;München;DE ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/clients_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/customer-contacts.md # Kundenkontakte Stammdaten zur Erkennung und des Abgleichs von Kundenkontakten oder Ansprechpersonen am Dokument. Bei Anfragen und Bestellungen kann der Kanal eine zweite Kontaktliste verwenden: die internen Kontakte, also Ihre eigenen Mitarbeitenden, die Kunden auf dem Dokument als Ansprechperson angeben (z. B. aus dem Innendienst). Beide Listen haben dieselbe Struktur. Welche Liste welcher Dokumenttyp nutzt, steht unter [Welcher Dokumenttyp welche Liste nutzt](/docs/master-data.md#listen-pro-dokumenttyp). ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `contact_id` | Pflichtfeld | Primäre Kontaktnummer | | 2 | `first_name` | Empfohlen | Vorname. Workist erkennt Kontakte vor allem über den Namen. | | 3 | `last_name` | Empfohlen | Nachname | | 4 | `phone` | Optional | Festnetznummer | | 5 | `mobile_phone` | Optional | Mobilfunknummer | | 6 | `email` | Optional | E-Mail-Adresse | | 7 | `partition_id` | Optional | `client_id1` des Kunden, zu dem der Kontakt gehört. Damit wählt Workist nur unter den Kontakten dieses Kunden aus, was die Erkennungsrate deutlich erhöht. Kontakte ohne `partition_id` bietet Workist bei allen Kunden an. | | 8 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | Die Importkonfiguration zeigt `partition_id`, `first_name` und `last_name` immer als Zeilen mit `*` an. Der Import prüft diese Spalten nicht; ohne `partition_id` gilt der Kontakt für alle Kunden. ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `contact_list.csv` ```csv contact_id;first_name;last_name;phone;mobile_phone;email;partition_id C001;Max;Mustermann;0123/456789-89;+49 151 23456789;max.mustermann@muster.de;K001 C002;Erika;Beispiel;0321/689371-56;+49 160 7654321;erika.beispiel@beispiel.de;K002 C003;Hans;Test;;;hans.test@test.de;K003 ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/contacts_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/delivery-and-invoice-recipients.md # Liefer- und Rechnungsempfänger Stammdaten zur Erkennung von Adressen. Bei Workist meinen wir mit Adressen immer Liefer- und Rechnungsadressen. Für beide Adressarten verwenden wir in Workist die gleiche Datenstruktur. In der Regel benötigt Workist **2 separate Dateien**, falls sowohl Liefer- als auch Rechnungsadressen übergeben werden sollen. Im [Master Data Hub](/docs/master-data/master-data-hub.md) sind das zwei Listen vom Typ **Adressen**; welche Rolle eine Liste spielt, legt das Feld im Kanal fest (**Lieferadressen-Lookup-ID** bzw. **Rechnungsadressen-Lookup-ID**). :::warning Auch wenn Kundendaten in vielen Systemen als eine Art von Adressen behandelt werden, gilt in Workist für Kunden ein eigenes Format! Siehe [Kundenstammdaten](/docs/master-data/customers.md). ::: ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Optional | `client_id1` des Kunden, zu dem die Adresse gehört. Begrenzt die Auswahl auf die Adressen dieses Kunden und erhöht die Erkennungsrate deutlich. Adressen ohne `partition_id` bietet Workist bei allen Kunden an. | | 2 | `address_id1` | Pflichtfeld | Primäre Adressnummer. Diese Nummer gibt Workist in der Ausgabe zurück. | | 3 | `address_id2` | Optional | Sekundäre Adressnummer (z. B. GLN) | | 4 | `address_id3` | Optional | Tertiäre Adressnummer | | 5 | `name` | Empfohlen | Erste Adresszeile (z. B. Muster GmbH) | | 6 | `address1` | Empfohlen | Straße und Hausnummer (z. B. Musterstraße 1) | | 7 | `street_name` | Optional | Straßenname, wenn Straße und Hausnummer getrennt vorliegen. Alternative zu `address1`. | | 8 | `street_number` | Optional | Hausnummer, wenn getrennt von `street_name` | | 9 | `address2` | Optional | Weitere Adresszeile | | 10 | `zip_code` | Empfohlen | Postleitzahl | | 11 | `city` | Empfohlen | Stadt | | 12 | `country_subdivision` | Optional | Bundesland bzw. Region | | 13 | `country` | Empfohlen | Land. Ländernamen und drei- oder einstellige Ländercodes wandelt Workist in den zweistelligen ISO-Code um (z. B. `Deutschland` → `DE`). Nicht erkannte Werte bleiben leer. | | 14 | `po_box` | Optional | Postfach für die Zustellung | | 15 | `misc` | Optional | Sonstige Informationen zur Adresse (in manchen Systemen auch Abladestelle genannt, z. B. Tor 4) | | 16 | `contact_person` | Optional | Kontaktperson für die Adresse (z. B. z. H. Muster Person) | | 17 | `phone` | Optional | Telefonnummer, die mit der Adresse verbunden ist | | 18 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `address_list.csv` ```csv partition_id;address_id1;name;address1;zip_code;city;country;misc K001;A001;Muster GmbH - Lager;Lagerstraße 10;12345;Berlin;DE;Tor 2 K001;A002;Muster GmbH - Büro;Musterstraße 1;12345;Berlin;DE; K002;A003;Beispiel AG;Beispielweg 5;20099;Hamburg;DE; ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/addresses_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/articles.md # (Kundenspezifische) Artikel Stammdaten zur Erkennung von Artikeln. Bei Workist unterscheiden wir zwischen einer *kundenspezifischen Artikelliste* und einer *allgemeinen Artikelliste*. Für beide Artikellisten verwenden wir in Workist die gleiche Datenstruktur. In der Regel benötigt Workist **2 separate Dateien**, falls sowohl eine allgemeine als auch eine kundenspezifische Artikelliste übergeben werden soll. Im [Master Data Hub](/docs/master-data/master-data-hub.md) sind das zwei Listen vom Typ **Artikel**; im Kanal gehört die allgemeine Liste in das Feld **Artikel-Lookup-ID**, die kundenspezifische in das Feld **Debitorenartikel-Lookup-ID**. :::warning **Workist braucht mindestens immer eine Artikelliste!** ::: :::info Bei Übergabe einer kundenspezifischen Artikelliste **zusätzlich zur allgemeinen Artikelliste** reichen in der Regel die folgenden Spalten: `partition_id`, `article_id1`, `article_id2`, (optional) `article_id3` ::: :::note Falls Einheiten-Konvertierung in Workist realisiert werden soll, müssen die `order_units` und `sales_units` übermittelt werden. Siehe: [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) ::: ## Allgemeine und kundenspezifische Liste - **Allgemeine Liste:** alle Artikel, ohne `partition_id`. `article_id2` und `article_id3` sind weitere Nummern, unter denen Workist den Artikel findet. - **Kundenspezifische Liste:** eine Zeile pro Kunde und Artikel. `partition_id` enthält die `client_id1` des Kunden, `article_id1` Ihre Artikelnummer und `article_id2` die Artikelnummer, die dieser Kunde auf seinen Dokumenten verwendet. Workist findet den Artikel dann über die Nummer des Kunden und gibt Ihre `article_id1` aus. Die Nummer des Kunden zeigt Workist an der Position als externe Artikelnummer an. - Zeilen mit `partition_id` gelten nur für diesen Kunden; anders als bei anderen Listen bietet Workist sie keinem anderen Kunden an (siehe [Zuordnung zu Kunden](/docs/master-data.md#partition-id)). **Mehrere Vertriebsorganisationen:** Steht dieselbe `article_id1` mit verschiedenen `sales_organisation`-Werten in Ihren Artikellisten, als mehrere Zeilen oder in mehreren Artikellisten, bietet Workist an der Position die Vertriebsorganisationen zur Auswahl an. Bei Bestellungen markiert die Prüfung **Mehrere Vertriebsorganisationen** solche Positionen, damit eine Bearbeiter:in die passende wählt (siehe [Validierungsprüfungen](/docs/channel-configuration/document-processing/validation-checks.md)). ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Optional | Nur in der kundenspezifischen Liste: `client_id1` des Kunden, für den die Zeile gilt. In der allgemeinen Liste leer lassen. | | 2 | `article_id1` | Pflichtfeld | Ihre Artikelnummer. Diese Nummer gibt Workist in der Ausgabe zurück. In der kundenspezifischen Liste dieselbe Nummer wie in der allgemeinen Liste. | | 3 | `article_id2` | Optional | Allgemeine Liste: weitere Artikelnummer, unter der der Artikel gefunden werden soll. Kundenspezifische Liste: die Artikelnummer, die dieser Kunde verwendet. Workist zeigt sie an der Position als externe Artikelnummer an. | | 4 | `article_id3` | Optional | Weitere Artikelnummer, z. B. die EAN | | 5 | `description` | Pflichtfeld | Artikelbeschreibung. Workist erkennt Artikel auch über die Beschreibung, wenn auf dem Dokument keine Artikelnummer steht. In der kundenspezifischen Zusatzliste kann die Spalte leer bleiben. | | 6 | `article_status` | Optional | Status des Artikels, z. B. `gesperrt` oder `ausgelaufen`. Mit den Artikelstatus-Regeln des Kanals markiert Workist Positionen mit diesem Status zur Prüfung, siehe [Validierungsprüfungen](/docs/channel-configuration/document-processing/validation-checks.md). | | 7 | `gross_price` | Optional | Listenpreis des Artikels vor Abzügen oder Rabatten. Workist zeigt ihn an der Position als Information an. | | 8 | `order_units` | Empfohlen | Einheiten, in denen der Artikel bestellt werden kann, als Liste in einer Zelle, z. B. `["KAR","ST"]`. Steuert, welche Einheiten in der Workbench zur Auswahl stehen. Eine leere Zelle wird als `["ST"]` importiert. | | 9 | `sales_units` | Optional / Pflicht bei Konvertierung | Einheiten, in denen der Artikel verkauft wird, als Liste in einer Zelle. Erforderlich, wenn Workist Einheiten umrechnen soll: Bestellt ein Kunde in einer anderen Einheit, rechnet Workist die Menge in eine Verkaufseinheit um. | | 10 | `sales_organisation` | Optional | Vertriebsorganisation, die den Artikel verkauft. Steht dieselbe `article_id1` mit mehreren Vertriebsorganisationen in Ihren Artikellisten, bietet Workist an der Position eine Auswahl an. | | 11 | `variants` | Optional | Konfigurierbare Dimensionen des Artikels (z. B. Farbe, Größe), Format: `{'dimensions': [{'name': 'Farbe', 'values': ['rot', 'blau']}]}`. Wird nicht für die Erkennung verwendet, sondern als Information für nachgelagerte Systeme. | | 12 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | Mehrere Bestell- oder Verkaufseinheiten geben Sie immer als Liste in **einer** Zelle an. Doppelte Zeilen mit unterschiedlichen Einheiten führt Workist nicht zusammen: Jede Zeile wird ein eigener Datensatz. ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `article_list.csv` ```csv article_id1;article_id2;description;gross_price;order_units ART001;4001234;Schrauben M8x20 100er Pack;12.50;["Packung","Karton"] ART002;4005678;Dübel 8mm 50er Pack;5.90;["Packung"] ART003;4009999;Bohrmaschine XL Pro;149.99;["Stück"] ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/articles_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/unit-conversion.md # Einheitenkonvertierung Stammdaten zur Umrechnung von Einheiten. Workist kann Einheiten erkennen und automatisch in andere Mengen umrechnen. Um dies durchzuführen benötigt Workist eine Liste an Umrechnungsquotienten. :::warning Wenn Einheiten-Konvertierung in Workist verwendet werden soll, werden die `sales_units` und die `order_units` in der Artikelliste verpflichtend! → [Artikelstammdaten](/docs/master-data/articles.md) ::: ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Optional | `client_id1` des Kunden, für den die Umrechnung gilt. Wirkt nur, wenn im Kanal die partitionsspezifische Einheitenkonversion aktiv ist. Findet Workist für den Kunden keine Umrechnung, verwendet es die Umrechnungen ohne `partition_id`. | | 2 | `article_id` | Pflichtfeld | Artikelnummer. Muss dieselbe Nummer wie `article_id1` in den Artikelstammdaten sein. Workist sucht Umrechnungen immer zu einer bestimmten Artikelnummer. | | 3 | `source_unit` | Pflichtfeld | Ursprungseinheit der Umrechnung (die Bestelleinheit) | | 4 | `target_unit` | Pflichtfeld | Zieleinheit der Umrechnung (die Verkaufseinheit) | | 5 | `conversion_quotient` | Pflichtfeld | Umrechnungsquotient (in anderen Systemen oft als Faktor angegeben — hier muss es 1/Faktor sein) | | 6 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | Die Importkonfiguration zeigt `article_id` nicht als Zeile mit `*` an. Ordnen Sie die Spalte trotzdem zu: Umrechnungen ohne Artikelnummer findet Workist nicht. Beachten Sie beim `conversion_quotient`: - Jede Zeile braucht einen Wert, und der Wert braucht einen **Punkt** als Dezimaltrennzeichen (`0.125`, nicht `0,125`). Sonst schlägt der Import fehl. - Liegt in Ihrem System ein Faktor statt eines Quotienten vor, kann Workist die Umrechnung beim Import übernehmen. Sprechen Sie dazu Ihre Ansprechperson bei Workist an. Pro Artikel und Ursprungseinheit (und gegebenenfalls Kunde) darf es nur **eine** Zeile geben. Findet Workist mehrere Umrechnungen für dieselbe Kombination, kann es die Position nicht umrechnen. ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `conversion_factor_list.csv` ```csv partition_id;article_id;source_unit;target_unit;conversion_quotient ;ART001;Karton;Packung;0.1 ;ART002;Karton;Packung;0.05 K001;ART001;Karton;Packung;0.125 ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Im Beispiel enthält ein Karton von `ART001` 10 Packungen (`0.1`), für den Kunden `K001` 8 Packungen (`0.125`). Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/conversion_factors_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). ## Details zur Einheitenkonvertierung Für die Einheiten-Konvertierungen muss in Workist zuerst für jeden verfügbaren Artikel konfiguriert werden, in welchen Einheiten er bestellt und in welchen er verkauft werden kann. Bei Workist nennen wir dies die verfügbaren `order_units` und `sales_units` in den Artikelstammdaten. ### Anpassungen in den Artikelstammdaten Beispiel: `order_units` und `sales_units` für ein Bier konfigurieren: - `sales_units` wird auf `["Flaschen"]` gesetzt — Workist rechnet diesen Artikel in der Ausgabe immer auf Flaschen um. - `order_units` muss eine Liste aller Einheiten sein, in denen Kunden bestellen können, z.B. `["Kisten", "Sixpacks", "Flaschen"]`. ```csv article_id1;description;article_id2;order_units;sales_units 123;Bier;000123;["Kisten","Sixpacks","Flaschen"];["Flaschen"] abc;Orangensmoothie;000abc;["Flaschen"];["Flaschen"] 1234;Blaubeerwein;0001234;["Kisten","Flaschen"];["Flaschen"] 1122;Sprudelwasser;0001122;["Kisten","Flaschen"];["Flaschen"] ``` ### Konfiguration der Konvertierungsstammdaten Die Konvertierung wird als Quotient gespeichert. Im `conversion_quotient` muss hinterlegt werden: - 1 Flasche = 1/6 Sixpack → `0.16666...` - 1 Flasche = 1/24 Kiste → `0.04166...` ```csv article_id;source_unit;target_unit;conversion_quotient 123;Sixpacks;Flaschen;0.16666666666 123;Kisten;Flaschen;0.04166666666 1234;Kisten;Flaschen;0.125 1122;Kisten;Flaschen;0.08333333333 ``` Für jede Artikel- und `order_unit`-Kombination wird ein Eintrag in den Stammdaten benötigt (nicht für Einheiten, die nicht konvertiert werden müssen, z.B. Flaschen zu Flaschen). Wenn von einem Kunden 1 Sixpack bestellt wird, wird in Workist die Ausgabemenge in **6 Flaschen** umgewandelt. ### Wenn keine Umrechnung passt Bestellt ein Kunde bereits in einer Verkaufseinheit, rechnet Workist nicht um. Findet Workist für eine andere Einheit keine passende Umrechnung, setzt es die erste Verkaufseinheit des Artikels ein und markiert Menge und Einheit zur Prüfung in der Assistenz. Wie Workist das Ergebnis einer Umrechnung rundet, legen Sie in der Kanal-Konfiguration fest (siehe [Einheitenumrechnung](/docs/channel-configuration/document-processing/document.md)). --- Source: https://docs.workist.com/docs/master-data/framework-agreements.md # Rahmenverträge Stammdaten zum Validieren von Rahmenvertragsnummern. Workist kann Rahmenvertragsnummern erkennen und diese mit den bereitgestellten Stammdaten validieren. Rahmenverträge nutzt Workist bei Anfragen und Bestellungen. ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Pflichtfeld | `client_id1` des Kunden, zu dem der Vertrag gehört. Nötig, damit nur die Rahmenverträge dieses Kunden ausgewählt werden können. Bleibt das Feld leer, bietet Workist den Vertrag bei allen Kunden an. | | 2 | `client_id` | Optional | Alternative Kundennummer, falls der Vertrag zu einem übergeordneten Kunden gehört. Nur relevant, falls die Kundennummer des Vertrags in der Ausgabe von dem erkannten Kunden am Dokument abweichen kann. | | 3 | `client_name` | Optional | Name des Kunden | | 4 | `contract_id1` | Pflichtfeld | Vertragsnummer, die am Dokument gefunden werden soll bzw. die Workist in der Ausgabe mitgibt | | 5 | `contract_id2` | Optional | Alternative Vertragsnummer | | 6 | `contract_name` | Empfohlen | Name des Vertrags, der zur Anzeige verwendet wird | | 7 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `framework_contract_list.csv` ```csv partition_id;contract_id1;contract_id2;contract_name K001;RV-2024-001;FW001;Jahresvertrag Muster GmbH 2024 K002;RV-2024-002;;Rahmenvertrag Beispiel AG 2024 K001;RV-2024-003;;Sonderkonditionen Muster GmbH ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/framework_contracts_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/quotes.md # Angebote Stammdaten zum Validieren von Angebotsnummern. Workist kann Angebotsnummern erkennen und diese mit den bereitgestellten Stammdaten validieren. Angebote nutzt Workist bei Bestellungen: Es gleicht Bestellungen mit dem referenzierten Angebot ab, übernimmt den Kunden aus dem Angebot und füllt Bestellungen ohne Positionen aus dem Angebot vor. Wie das im Einzelnen funktioniert, beschreibt [Abgleich mit Bestell- und Angebotsdaten](/docs/channel-configuration/document-processing/matching.md). ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. ### Kopfebene | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Stark empfohlen | `client_id1` des Kunden. Nicht verpflichtend, aber sehr stark empfohlen, damit nur die Angebote dieses Kunden ausgewählt werden können. | | 2 | `offer_number` | Pflichtfeld | Angebotsnummer | | 3 | `valid_from` | Optional | Gültig ab. Wird beim Abgleich nicht geprüft. | | 4 | `valid_until` | Optional | Gültig bis. Wird beim Abgleich nicht geprüft: Auch abgelaufene Angebote werden gefunden. | ### Positionsebene Workist kann Angebote auch auf Positionsebene matchen. Hierzu müssen die Kopffelder für jede Position wiederholt werden. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `position_number` | Empfohlen | Positionsnummer im Angebot | | 2 | `article_id1` | Empfohlen | Artikelnummer | | 3 | `article_id2` | Optional | Alternative Artikelnummer 2 | | 4 | `article_id3` | Optional | Alternative Artikelnummer 3 | | 5 | `article_description` | Empfohlen | Artikelbeschreibung | | 6 | `quantity` | Empfohlen | Menge | | 7 | `unit` | Empfohlen | Einheit | | 8 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt. Nur importierbar, wenn Ihre Datei bereits die Workist-Spaltennamen verwendet und die Importkonfiguration keine Spaltenzuordnung hat. Den Eintrag `higher_level_position` nutzt Workist, um Set-Bestandteile zu erkennen. | :::note Abgelaufene Angebote Da Workist die Gültigkeit beim Abgleich nicht prüft, liefern Sie nur Angebote, die noch gelten. Abgelaufene Angebote entfernen Sie aus Ihrem Export; mit dem nächsten Vollimport verschwinden sie aus Workist. ::: Mengen speichert Workist mit höchstens zwei Nachkommastellen; weitere Stellen werden gerundet. ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `offer_list.csv` ```csv partition_id;offer_number;valid_from;valid_until;position_number;article_id1;article_description;quantity;unit K001;ANG-2024-001;2024-01-01;2024-12-31;1;ART001;Schrauben M8x20 100er Pack;500;Packung K001;ANG-2024-001;2024-01-01;2024-12-31;2;ART002;Dübel 8mm 50er Pack;200;Packung K002;ANG-2024-002;2024-01-01;2024-06-30;1;ART003;Bohrmaschine XL Pro;10;Stück ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Datumsangaben schreiben Sie als `JJJJ-MM-TT` oder mit dem Tag zuerst (`31.12.2024`), siehe [Wie Workist Werte beim Import vereinheitlicht](/docs/master-data.md#werte-vereinheitlichen). Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/offer_matching_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/orders-to-be-matched.md # Abzugleichende Bestellungen (für Auftragsbestätigungen und Rechnungen) Stammdaten zum Validieren von zugehörigen Bestellungen. Workist kann die Referenz zur Bestellung auf Auftragsbestätigungen und Rechnungen erkennen und das Dokument mit den bereitgestellten Bestelldaten abgleichen. Auftragsbestätigungen ohne Positionen füllt Workist aus den Bestelldaten vor, und nach jedem erfolgreichen Import gleicht es offene Auftragsbestätigungen erneut ab. Welche Werte Workist vergleicht und was bei Abweichungen passiert, beschreibt [Abgleich mit Bestell- und Angebotsdaten](/docs/channel-configuration/document-processing/matching.md). ## Spaltenbeschreibung > **Pflichtfeld:** Ohne diese Spalte kann Workist den Datensatz nicht verwenden. **Empfohlen:** verbessert die Erkennung deutlich. Der Import selbst prüft keine Spalten: Fehlt eine Spalte, bleibt das Feld leer. ### Kopfebene | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `partition_id` | Empfohlen | `client_id1` des Geschäftspartners (bei Auftragsbestätigungen und Rechnungen meist der Lieferant). Nicht verpflichtend, aber sehr stark empfohlen, damit nur die Bestellungen dieses Partners ausgewählt werden können. | | 2 | `order_number` | Pflichtfeld | Bestellnummer, auf die sich das Dokument bezieht | | 3 | `external_reference` | Optional | Zweite Referenz der Bestellung, z. B. die Bestellnummer Ihres Geschäftspartners. Workist sucht über `order_number` und `external_reference` gleichermaßen. | | 4 | `order_date` | Optional | Bestelldatum | | 5 | `delivery_address` | Optional | Nummer der Lieferadresse (`address_id1` aus den [Liefer- und Rechnungsempfängern](/docs/master-data/delivery-and-invoice-recipients.md)) | | 6 | `receiver_number` | Optional | Nummer des Käufers bzw. Rechnungsempfängers (`client_id1` aus der Empfängerliste des Kanals) | | 7 | `order_total_price` | Optional | Nettogesamtwert der Bestellung | | 8 | `iban` | Optional | IBAN, auf die gezahlt werden soll. Nur für Rechnungen. | | 9 | `swift` | Optional | BIC. Nur für Rechnungen. | | 10 | `account` | Optional | Zahlungsreferenz. Nur für Rechnungen. | | 11 | `payment_terms_type` | Optional | Zahlungsbedingung. Nur für Rechnungen. | | 12 | `payment_terms_discount` | Optional | Skonto. Nur für Rechnungen. | | 13 | `payment_terms_due_days` | Optional | Zahlungsziel in Tagen. Nur für Rechnungen. | ### Positionsebene Workist kann Auftragsbestätigungen und Rechnungen auch auf Positionsebene abgleichen. Hierzu müssen die Kopffelder für jede Position wiederholt werden. | # | Feldname | Status | Beschreibung | |---|----------|--------|--------------| | 1 | `position_number` | Empfohlen | Positionsnummer | | 2 | `article_id1` | Optional | Artikelnummer. Bei Textpositionen (Positionen ohne Material) leer lassen. | | 3 | `article_id2` | Optional | Alternative Artikelnummer 2 | | 4 | `article_id3` | Optional | Alternative Artikelnummer 3 | | 5 | `article_description` | Optional | Artikelbeschreibung | | 6 | `article_price` | Optional | Preis, bezogen auf die Preiseinheit (`price_unit`) | | 7 | `price_unit` | Optional | Preiseinheit des Preises, z. B. `1` oder `100` (Preis pro 100). Nicht mit der Mengeneinheit (`unit`, z. B. ST oder KG) verwechseln. | | 8 | `quantity` | Empfohlen | Menge | | 9 | `unit` | Optional | Einheit | | 10 | `total_price` | Optional | Gesamtpreis der Position | | 11 | `delivery_date` | Optional | Lieferdatum der Position. Bei Auftragsbestätigungen vergleicht Workist es auch mit dem Lieferdatum im Kopf. | | 12 | `extra_data` | Optional | Zusätzliche Angaben als JSON-Objekt, z. B. `{"Marke": "Muster"}`. Workist speichert sie mit dem Datensatz und zeigt sie im Datenexplorer an. Für die Erkennung nutzt Workist sie standardmäßig nicht. | Preise, Mengen und Beträge (`article_price`, `quantity`, `total_price`, `order_total_price`) speichert Workist mit höchstens zwei Nachkommastellen; weitere Stellen werden gerundet. Für Preise mit mehr Nachkommastellen geben Sie den Preis pro 10, 100 oder 1000 Stück an und setzen `price_unit` entsprechend. ## Format > Nicht benötigte Spalten können im Datenexport weggelassen werden. Beispieldateiname: `20240315_order_list.csv`. Damit Workist jeweils die neueste Datei importiert, verwenden Sie in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) das Dateinamensmuster `%Y%m%d_order_list.csv`. ```csv partition_id;order_number;order_date;position_number;article_id1;quantity K001;ORD-2024-0042;2024-03-15;1;ART001;10 K001;ORD-2024-0042;2024-03-15;2;ART002;5 K002;ORD-2024-0043;2024-03-16;1;ART003;2 ``` Das Beispiel verwendet `;` als Trennzeichen. Stellen Sie das Trennzeichen in der [Importkonfiguration](/docs/master-data/transformer-configuration.md) ein; ohne Angabe erwartet Workist ein Komma. Datumsangaben schreiben Sie als `JJJJ-MM-TT` oder mit dem Tag zuerst (`31.12.2024`), siehe [Wie Workist Werte beim Import vereinheitlicht](/docs/master-data.md#werte-vereinheitlichen). Per API übermitteln Sie dieselben Spalten als CSV-Datei oder als JSON. Endpunkt: [Swagger](https://api.workist.com/v1/swagger/#/Master%20Data/order_matching_imports_create), Grundlagen: [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/master-data/transformer-configuration.md # Transformer-Konfiguration für Stammdaten-Importe Diese Anleitung beschreibt, wie Sie im [Master Data Hub](/docs/master-data/master-data-hub.md) die **Importkonfiguration** (Transformer-Konfiguration) einer Stammdatenliste einsehen und anpassen. Sie bestimmt, **welche Datei** vom SFTP-Server gelesen wird, **wie sie eingelesen** wird (Codierung, Trennzeichen, …) und **wie die Spalten Ihrer Datei** auf das von Workist erwartete Zielschema abgebildet werden. Dieselbe Konfiguration gilt für Dateien, die Sie in der Workbench hochladen oder über die API liefern. Jede Stammdatenliste (Artikel, Kunden, Kundenkontakte, Adressen, Einheitenkonvertierung, Rahmenverträge, Bestellungen, Angebote) hat **eine eigene** Konfiguration. --- ## Voraussetzungen - Ein Workbench-Konto mit der Rolle **Manager**, **IT** oder **Admin** (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). - Eine Stammdatenliste im Master Data Hub. Wie Sie eine Liste anlegen, steht unter [Liste anlegen](/docs/master-data/master-data-hub.md#liste-anlegen). - Mindestens eine Beispieldatei, deren Spaltennamen Sie kennen — sonst können Sie die Zuordnung auf das Zielschema nicht vornehmen. :::note Individuelle Importskripte Für manche Listen richtet Workist ein individuelles Importskript ein, z. B. wenn mehrere Dateien zu einer Liste zusammengeführt werden. Dann wirken nur die Dateinamensmuster und die Dateileser-Parameter. Speichern Sie in diesem Fall keine Spaltenzuordnungen: Der Import schlägt sonst fehl. ::: --- ## Schritt 1 — Konfiguration öffnen Öffnen Sie die Liste im [Master Data Hub](/docs/master-data/master-data-hub.md) und wechseln Sie auf den Reiter für die Konfiguration. Sie gelangen auch aus einem Kanal dorthin: - über das Kanalmenü → **Stammdaten verwalten** und das Zahnrad (**Import konfigurieren**) in der Zeile der Liste, oder - über die Kanal-Konfiguration → **Stammdaten** und das Zahnrad neben dem Feld der Liste. Beide Zahnräder öffnen die Liste in einem neuen Tab. --- ## Schritt 2 — Aufbau der Seite Der Reiter besteht aus drei Teilen: 1. Die Importkonfiguration mit den Bereichen **Dateinamensmuster**, **Dateileser-Parameter** und **Spaltenzuordnungen**. 2. Den Probelauf, der die Konfiguration testet, ohne etwas zu importieren (siehe [Schritt 7](#schritt-7)). 3. Eine Leiste am unteren Rand, die zeigt, ob es ungespeicherte Änderungen gibt. Sie enthält die Schaltflächen zum Verwerfen und zum **Speichern**. --- ## Schritt 3 — Dateinamensmuster Im Abschnitt **Dateinamensmuster** legen Sie fest, welche Datei in Ihrem SFTP-Verzeichnis `/export` als Eingabe für diese Liste gilt. - **Fester Dateiname**, z. B. `customer_article_list.csv`. - **Wildcard** `*`, z. B. `articles_*_full.csv`. - **Datums- und Zeitplatzhalter** `%Y`, `%m`, `%d`, `%H`, `%M` und `%S`, z. B. `%Y%m%d_Artikel.csv` für `20240315_Artikel.csv`. Wildcards und Datumsplatzhalter lassen sich nicht in einem Muster kombinieren. - **Regulärer Ausdruck** mit dem Präfix `re:`, z. B. `re:Artikel_[0-9]+\.csv`. Passen mehrere Dateien auf das Muster, importiert Workist die neueste. Passt eine Datei auf die Muster mehrerer Listen, importiert Workist sie in jede dieser Listen. Tragen Sie pro Liste **ein** Muster ein. Mit **Muster hinzufügen** lassen sich zwar weitere Muster ergänzen, die Standardverarbeitung importiert aber nur eine Datei pro Liste; mit mehreren Mustern schlägt der Import fehl. Mehrere Dateien führt nur ein individuelles Importskript von Workist zusammen. Für Dateien, die Sie in der Workbench hochladen oder per API liefern, spielt der Dateiname keine Rolle. :::tip Verwenden Sie möglichst restriktive Muster. Ein zu breites Muster wie `*.csv` kann dazu führen, dass artikelfremde Dateien versehentlich als Artikelliste interpretiert werden. ::: --- ## Schritt 4 — Dateileser-Parameter Im Abschnitt **Dateileser-Parameter** stellen Sie ein, wie Workist Ihre Datei einliest. Jeder Parameter steht zunächst auf **Nicht gesetzt**; dann gilt der Standardwert. | Parameter | Bedeutung | Beispiel | | --- | --- | --- | | **Trennzeichen** | Spaltentrenner in CSV-Dateien. Standard ist das Komma. Workist erkennt das Trennzeichen beim Import nicht automatisch: Verwendet die Datei ein anderes Trennzeichen als eingestellt, schlägt der Import mit **Unerwartetes Trennzeichen** fehl. | `;` oder `,` | | **Codierung** | Zeichensatz der Datei. Standard ist UTF-8. Für CSV-Dateien aus Excel mit „UTF-8 mit BOM“ wählen Sie `utf-8-sig`. | `utf-8`, `utf-8-sig`, `utf-16`, `latin-1`, `cp1252`, `ascii` | | **Anführungszeichenzeichen** | Zeichen, mit dem Werte in der CSV-Datei eingefasst sind. Standard ist `"`. | `"` oder `'` | | **Escape-Zeichen** | Zeichen zum Maskieren des Anführungszeichens innerhalb eines Wertes. | `\` | Welche Werte zu Ihrer Datei passen, schlägt der [Probelauf](/docs/master-data/master-data-hub.md#probelauf) vor. :::note Für **Excel-Dateien** (`.xls`, `.xlsx`) lassen Sie alle Parameter auf **Nicht gesetzt**. Workist erkennt das Format an der Dateiendung; gesetzte Parameter lassen den Import von Excel-Dateien fehlschlagen. ::: --- ## Schritt 5 — Spaltenzuordnungen Im Abschnitt **Spaltenzuordnungen** ordnen Sie die Spalten Ihrer Eingabedatei den Spalten des Workist-Zielschemas zu. Jede Zeile besteht aus zwei Feldern: - **Spaltenname** — die Zielspalte, ausgewählt aus den Spalten des Stammdatentyps (siehe [Zielspalten je Stammdatentyp](#zielspalten)). - **Spaltenausdruck** — woher der Wert kommt. Fünf Ausdrucksarten sind möglich: | Ausdruck | Bedeutung | | --- | --- | | `Artikelnummer` | **Direkte Spaltenreferenz** — der Wert wird 1:1 aus der gleichnamigen Spalte übernommen. | | `{Bezeichnung1} {Bezeichnung2}` | **Vorlagen-Ausdruck** — Platzhalter in geschweiften Klammern werden durch Spaltenwerte ersetzt. | | `'STK'` | **Stringliteral** — der Wert wird fest hinterlegt (z. B. eine konstante Einheit). | | `PASS` | **Beibehalten, wenn vorhanden** — die gleichnamige Spalte wird durchgereicht; ist sie nicht da, wird die Zuordnung ignoriert. | | *(leer)* | **Keine Zuordnung** — die Zeile wird beim Speichern entfernt. | Beispiel für eine Artikelliste: | Spaltenname | Spaltenausdruck | | --- | --- | | `article_id1` * | `Artikelnummer` | | `description` * | `{Bezeichnung_DE} {Farbe}` | | `gross_price` | `Listenpreis` | | `order_units` | `Bestelleinheit` | Was Sie dabei beachten sollten: - **Nur zugeordnete Spalten werden importiert.** Sobald eine Zuordnung gespeichert ist, übernimmt Workist ausschließlich die zugeordneten Spalten; alle anderen Spalten der Datei ignoriert es. Ohne Zuordnungen übernimmt Workist die Spalten der Datei unverändert. Dann müssen sie bereits wie die Workist-Spalten heißen. - **Mit `*` markierte Zeilen** zeigt das Formular für jeden Stammdatentyp immer an; Sie können sie nicht entfernen. Lassen Sie den Spaltenausdruck leer, wenn Sie für eine solche Spalte keine Zuordnung brauchen. Der Import prüft nicht, ob diese Spalten gefüllt sind. Welche Spalten Workist für die Erkennung wirklich braucht, steht auf den Seiten der einzelnen [Stammdaten-Typen](/docs/master-data.md). - **`partition_id`** belegt das Formular mit `'main'` vor. `main` bedeutet: Die Zeile gilt für alle Kunden (siehe [Zuordnung zu Kunden](/docs/master-data.md#partition-id)). Enthält Ihre Datei eine Spalte mit der Kundennummer, ersetzen Sie `'main'` durch deren Namen. - **Nicht zugeordnete Zeilen** fügt der Probelauf für Spalten Ihrer Datei hinzu, die keiner Workist-Spalte entsprechen. Wählen Sie dafür eine Zielspalte; andernfalls entfernt Workist die Zeile beim Speichern. - **Ein orangefarbenes `!`** markiert eine Zielspalte, die es für diesen Stammdatentyp nicht gibt. Eine solche Zuordnung lässt den Import fehlschlagen; entfernen Sie die Zeile. Mit **Spaltenzuordnung hinzufügen** lassen sich weitere Zuordnungen ergänzen, bis alle Spalten des Zielschemas verwendet sind. Über das Mülleimer-Symbol kann jede optionale Zuordnung wieder entfernt werden. --- ## Schritt 6 — Reiter „Rohes JSON" für fortgeschrittene Felder Über den Reiter **Rohes JSON** sehen Sie die komplette Transformer-Konfiguration als JSON-Dokument und können sie direkt bearbeiten. ![Reiter „Rohes JSON" mit aktueller Konfiguration](/img/transformer-config/04-json-tab.png) Im JSON-Reiter sind insbesondere Felder verfügbar, die im Formular nicht angezeigt werden: - `apply_common_functions` — eine Liste vordefinierter Transformationen, die in der angegebenen Reihenfolge auf die Datei angewendet werden, z. B.: - `query` — Zeilen anhand einer Bedingung herausfiltern (`"query": "source_unit != target_unit"`). - `strip` — führende und folgende Leerzeichen entfernen. - `drop_column` — eine Spalte aus dem Ergebnis entfernen. - `remove_duplicated_rows` — doppelte Zeilen entfernen. - `remove_leading_zeros` — führende Nullen in einer Spalte abschneiden (häufig bei Artikelnummern). - `set_default_order_unit` / `set_default_order_unit_to_sales_unit` / `ensure_sales_unit_in_order_unit` — Bestelleinheiten standardisieren. - `eval_expression` — einen Ausdruck zur Berechnung eines neuen Spaltenwerts auswerten (z. B. zusammengesetzte Kundenbezeichnung). - `add_incremental_id` — eine fortlaufende ID als Spalte hinzufügen. - `filter_by_length` / `detect_chars` — Zeilen anhand der Länge oder eines Musters in einer Spalte filtern. - `replace_nan` — leere Werte einer Spalte durch einen Standardwert ersetzen. - `query` — globale Filter-Bedingung, die direkt nach dem Einlesen ausgewertet wird. Beispiel-JSON für eine Artikelliste mit Pflicht-Pflege: ```json { "file_name_patterns": ["customer_article_list.csv"], "file_reader_kwargs": { "encoding": "utf-8", "delimiter": ";" }, "columns": { "article_id1": "Artikelnummer", "description": "{Bezeichnung_DE} {Farbe}", "partition_id": "'main'", "gross_price": "Listenpreis", "order_units": "Bestelleinheit", "sales_units": "Verkaufseinheit" }, "apply_common_functions": [ { "strip": "description" }, { "remove_leading_zeros": "article_id1" }, { "remove_duplicated_rows": ["article_id1"] } ] } ``` Sobald Sie etwas am JSON ändern, erscheint unten ein roter Hinweis, falls das JSON syntaktisch nicht gültig ist. Über **JSON formatieren** lässt sich der Text einrücken und ordnen, ohne den Inhalt zu verändern. :::warning Die Spaltennamen auf der **linken** Seite von `"columns"` müssen aus dem Zielschema des jeweiligen Lookup-Typs stammen — andernfalls wird die Konfiguration beim Speichern abgelehnt. ::: --- ## Schritt 7 — Testen und speichern {#schritt-7} 1. Testen Sie die Konfiguration mit einem [Probelauf](/docs/master-data/master-data-hub.md#probelauf). Er verwendet auch ungespeicherte Änderungen und zeigt, wie Workist Ihre Datei umwandelt. Eine Zuordnung auf eine unbekannte Zielspalte oder eine fehlende Spalte in der Datei fällt hier auf, bevor ein echter Import scheitert. 2. Klicken Sie in der Leiste am unteren Rand auf **Speichern**. Workist lädt danach die gespeicherte Konfiguration neu. Ungespeicherte Änderungen können Sie dort auch verwerfen. :::info Wann greift die neue Konfiguration? Ab dem **nächsten** Import. Bereits importierte Daten verarbeitet Workist nicht automatisch neu. Um die neue Konfiguration sofort anzuwenden, starten Sie im Master Data Hub einen [Import aus dem SFTP-Verzeichnis](/docs/master-data/master-data-hub.md#import-aus-sftp), laden die Datei erneut hoch oder liefern sie erneut per SFTP. Auch eine unveränderte Datei verarbeitet Workist nach einer Konfigurationsänderung neu. ::: --- ## Zielspalten je Stammdatentyp {#zielspalten} Welche Spalten im **Spaltenname**-Feld zur Auswahl stehen, hängt vom Stammdatentyp ab. Was jede Spalte bedeutet und wofür Workist sie braucht, steht auf der jeweils verlinkten Seite. | Stammdatentyp | Im Formular immer angezeigt (`*`) | Weitere Zielspalten | | --- | --- | --- | | [Artikel](/docs/master-data/articles.md) | `article_id1`, `description` | `partition_id`, `article_id2`, `article_id3`, `article_status`, `gross_price`, `order_units`, `sales_units`, `sales_organisation`, `variants`, `extra_data` | | [Kunden](/docs/master-data/customers.md) | `client_id1` | `client_id2`, `client_id3`, `company_name`, `address1`, `street_name`, `street_number`, `address2`, `zip_code`, `city`, `country_subdivision`, `country`, `po_box`, `misc`, `client_type`, `client_contact_person1`, `domain`, `iln`, `vat`, `iban`, `swift`, `locale_numeric`, `locale`, `internal_note`, `partition_id`, `extra_data` | | [Kundenkontakte](/docs/master-data/customer-contacts.md) | `contact_id`, `first_name`, `last_name`, `partition_id` | `phone`, `mobile_phone`, `email`, `extra_data` | | [Adressen](/docs/master-data/delivery-and-invoice-recipients.md) | `address_id1` | `partition_id`, `address_id2`, `address_id3`, `name`, `address1`, `street_name`, `street_number`, `address2`, `zip_code`, `city`, `country_subdivision`, `country`, `po_box`, `misc`, `contact_person`, `phone`, `extra_data` | | [Einheitenkonvertierung](/docs/master-data/unit-conversion.md) | `source_unit`, `target_unit`, `conversion_quotient` | `partition_id`, `article_id`, `extra_data` | | [Rahmenverträge](/docs/master-data/framework-agreements.md) | `partition_id`, `contract_id1` | `client_id`, `client_name`, `contract_id2`, `contract_name`, `extra_data` | | [Bestellungen](/docs/master-data/orders-to-be-matched.md) | `order_number` | `partition_id`, `external_reference`, `order_date`, `delivery_address`, `receiver_number`, `order_total_price`, `iban`, `swift`, `account`, `payment_terms_type`, `payment_terms_discount`, `payment_terms_due_days`, `position_number`, `article_id1`, `article_id2`, `article_id3`, `article_description`, `article_price`, `price_unit`, `quantity`, `unit`, `total_price`, `delivery_date`, `extra_data` | | [Angebote](/docs/master-data/quotes.md) | `offer_number` | `partition_id`, `valid_from`, `valid_until`, `position_number`, `article_id1`, `article_id2`, `article_id3`, `article_description`, `quantity`, `unit` | Die mit `*` markierten Spalten zeigt das Formular immer an; Pflicht im Sinne einer Importprüfung sind sie nicht. Bei Artikeln enthält die Auswahl außerdem `description_boosted` und die `order_unit_conversion_*`-Spalten. Diese sind intern bzw. veraltet; für Einheiten nutzen Sie die [Einheitenkonvertierung](/docs/master-data/unit-conversion.md). Verwenden Sie nur die Zielspalten aus dieser Tabelle. --- ## Hilfe und Support Wenn der Import nach einer Änderung weiterhin scheitert oder die gewünschten Werte nicht im Workist-Schema landen, wenden Sie sich an Ihre Ansprechperson bei Workist und halten Sie die folgenden Informationen bereit: - den **Namen der Liste** im Master Data Hub und den **Stammdatentyp** (z. B. „Artikel“), - den **Zeitpunkt** des fehlgeschlagenen Imports (Spalte **Importiert am**), - die **Eingabedatei** des Imports (in der Importhistorie verlinkt), - die **Fehlermeldung** des Imports bzw. das Ergebnis eines Probelaufs. --- Source: https://docs.workist.com/docs/administration.md # Administration Dieser Bereich richtet sich an alle, die Workist für ihr Unternehmen einrichten und betreuen. | Seite | Inhalt | Für wen | | --- | --- | --- | | [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md) | Rollen und ihre Berechtigungen, Mitarbeitende einladen und verwalten, Teams und die Sichtbarkeit von Kanälen, Worki für das Unternehmen ein- und ausschalten | **Manager**, **Admin** | | [Anmeldung & Sicherheit](/docs/administration/login-and-security.md) | Passwort, Zwei-Faktor-Authentifizierung, MFA-Pflicht für das Unternehmen, Single Sign-On mit Microsoft Entra ID oder SAML, API-Schlüssel | alle Benutzer; Unternehmenseinstellungen: **Admin**, API-Schlüssel: **IT**, **Admin** | | [Benachrichtigungen](/docs/administration/notifications.md) | E-Mail-Zusammenfassungen und Browser-Benachrichtigungen zu Dokumenten in der Unterstützung | alle Benutzer; Zeitplan für das Unternehmen: **Admin** | | [Statistiken](/docs/administration/analytics.md) | Automatisierungsgrad, Zeitersparnis, häufigste Gründe für Unterstützung, Excel-Export | **Manager**, **Admin** | ## Wo Sie die Einstellungen finden Benutzer mit Verwaltungsrechten klicken unten in der linken Navigation auf **Einstellungen** und wählen einen Einstieg, z. B. **Organisation**, **Teams** oder **Mitarbeiter\*innen**. Alle anderen erreichen ihre persönlichen Einstellungen über ihren Namen unten links → **Dein Profil**. Innerhalb der Einstellungen wechseln Sie über die Leiste links zwischen den Seiten. Sie sehen dort nur die Einträge, für die Ihre Rollen eine Berechtigung enthalten: | Bereich | Eintrag | Sichtbar für | | --- | --- | --- | | Persönlich (Ihr Name) | **Profil** | alle Benutzer | | Persönlich (Ihr Name) | **Benachrichtigungen** | alle Benutzer | | Persönlich (Ihr Name) | **Passwort und Authentifizierung** | alle Benutzer | | Unternehmen (Firmenname) | **Firmenprofil** | Admin | | Unternehmen (Firmenname) | **Firmenbenachrichtigungen** | Admin | | Unternehmen (Firmenname) | **Agenten** (in der Oberfläche: *Agents*) | Admin | | Unternehmen (Firmenname) | **Teams** | Manager, Admin | | Unternehmen (Firmenname) | **Mitarbeiter\*innen** | Manager, Admin | | Unternehmen (Firmenname) | **Single Sign-On** | Admin | | Unternehmen (Firmenname) | **Mehrfaktor-Authentifizierung** | Admin | | Unternehmen (Firmenname) | **SAML** | Admin | | Unternehmen (Firmenname) | **Stammdaten** (in der Oberfläche: *Master data*) | Manager, IT, Admin | | Entwickler-Tools | **API-Integrationen** | IT, Admin | | Entwickler-Tools | **Öffentliche SFTP-Schlüssel** | IT, Admin | | Workflow-Tools | **Smart Inbox** | Manager, Admin | | Workflow-Tools | **Outlook-Add-Ins** | IT, Admin | | Workflow-Tools | **Webhooks** | IT, Admin | | Geschäftssysteme (ERP) | ERP-Integrationen | IT, Admin | Was die Rollen im Einzelnen dürfen, steht unter [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md#roles). Die Einrichtung des Outlook-Add-Ins beschreibt [Outlook-Add-In](/docs/data-exchange/outlook-add-in.md). --- Source: https://docs.workist.com/docs/administration/users-and-roles.md # Benutzer, Rollen & Teams Was ein Benutzer in Workist sieht und tun darf, hängt von zwei Dingen ab: - Seine **Rollen** legen fest, was er tun darf, z. B. Dokumente bearbeiten, Kanäle konfigurieren oder SSO einrichten. - Seine **Teams** legen fest, welche Kanäle und Dokumente er sieht. ## Rollen {#roles} Workist hat fünf Rollen. Ein Benutzer kann mehrere Rollen haben; er erhält dann alle Berechtigungen jeder dieser Rollen. | Rolle | Gedacht für | | --- | --- | | **Chat user** | Mitarbeitende, die nur mit [Worki](/docs/agents/worki.md) arbeiten. Sie sehen ausschließlich Worki und ihre eigenen Einstellungen. | | **Member** | Sachbearbeitung: Dokumente prüfen, korrigieren und abschließen. | | **Manager** | Fachliche Verantwortung: Kanäle, Mitarbeitende, Teams, Stammdaten, Smart Inbox und Statistiken. | | **IT** | Technische Anbindung: Integrationen, API-Schlüssel, SFTP-Schlüssel, Webhooks und Stammdaten. | | **Admin** | Alles, zusätzlich Unternehmenseinstellungen und Anmeldesicherheit. Sieht alle Kanäle des Unternehmens. | ### Berechtigungen je Rolle {#permissions} Dieselbe Übersicht zeigt Workist beim Einladen und Bearbeiten von Mitarbeitenden. | Berechtigung | Chat user | Member | Manager | IT | Admin | | --- | :---: | :---: | :---: | :---: | :---: | | **Nutzen** | | | | | | | Mit Worki chatten | ✓ | | | | ✓ | | Dokumente bearbeiten | | ✓ | ✓ | ✓ | ✓ | | Persönliche Smart Inbox nutzen | | ✓ | ✓ | ✓ | ✓ | | Statistiken ansehen | | | ✓ | | ✓ | | **Verwalten** | | | | | | | Kanäle konfigurieren | | | ✓ | | ✓ | | Mitarbeitende und Teams verwalten | | | ✓ | | ✓ | | Geteilte Smart Inbox konfigurieren | | | ✓ | | ✓ | | Agenten und Sprachagenten konfigurieren | | | ✓ | | ✓ | | Selbstbedienungsformulare einrichten | | | ✓ | | ✓ | | Stammdaten verwalten | | | ✓ | ✓ | ✓ | | Integrationen konfigurieren | | | | ✓ | ✓ | | SSO und MFA konfigurieren | | | | | ✓ | | Unternehmenseinstellungen verwalten | | | | | ✓ | Was die Berechtigungen umfassen: - **Mit Worki chatten:** Gespräche mit Worki führen, Dateien anhängen, Automationen planen. Worki muss in Ihrem Vertrag enthalten und für das Unternehmen eingeschaltet sein, siehe [Worki](/docs/agents/worki.md). **Member**, **Manager** und **IT** enthalten Worki nicht; vergeben Sie bei Bedarf zusätzlich **Chat user**. - **Dokumente bearbeiten:** Dokumente in den Kanälen der eigenen [Teams](#teams) ansehen, hochladen, bearbeiten und abschließen. - **Persönliche Smart Inbox nutzen:** das eigene Outlook-Postfach mit Workist verbinden, siehe [Smart Inbox](/docs/smart-inbox.md). - **Statistiken ansehen:** die [Statistiken](/docs/administration/analytics.md) öffnen und als Excel-Datei herunterladen. - **Kanäle konfigurieren:** Kanäle anlegen und über **Kanal verwalten** einrichten, siehe [Kanal-Konfiguration](/docs/channel-configuration.md). - **Mitarbeitende und Teams verwalten:** Mitarbeitende einladen, bearbeiten und löschen, Passwörter zurücksetzen, Rollen vergeben und [Teams](#teams) pflegen. - **Geteilte Smart Inbox konfigurieren:** Sammelpostfächer verbinden und E-Mail-Kategorien pflegen. - **Agenten und Sprachagenten konfigurieren:** [Agenten](/docs/agents.md) anlegen und einrichten, sofern sie in Ihrem Vertrag enthalten sind. - **Selbstbedienungsformulare einrichten:** Bestellformulare, die Ihre Kunden statt einer E-Mail ausfüllen. - **Stammdaten verwalten:** Stammdaten hochladen und konfigurieren, Importprotokolle ansehen, siehe [Stammdaten-Hub](/docs/master-data/master-data-hub.md). - **Integrationen konfigurieren:** ERP-Integrationen, API-Schlüssel, Webhooks, [Outlook-Add-Ins](/docs/data-exchange/outlook-add-in.md) und SFTP-Schlüssel. - **SSO und MFA konfigurieren:** Single Sign-On, SAML und die MFA-Pflicht für das Unternehmen, siehe [Anmeldung & Sicherheit](/docs/administration/login-and-security.md). - **Unternehmenseinstellungen verwalten:** Firmenprofil und Logo, [Firmenbenachrichtigungen](/docs/administration/notifications.md) und [Worki für das Unternehmen](#worki). Wer diese Berechtigung hat, sieht die Kanäle und Dokumente **aller** Teams. ### Wer Rollen vergeben darf {#grant-roles} | Rolle | Darf diese Rollen vergeben | | --- | --- | | Chat user | keine | | Member | keine | | Manager | Member, Manager | | IT | keine | | Admin | Chat user, Member, Manager, IT, Admin | Dazu gilt: - Ein **Manager** kann nur Mitarbeitende bearbeiten oder löschen, deren Rollen er selbst vergeben darf. Bei allen anderen ist das Menü ⋮ ausgegraut. - Ihr eigenes Konto können Sie immer bearbeiten, aber nicht löschen. - Ein **Admin** kann sich die Rolle **Admin** nicht selbst entziehen. - Der letzte **Admin** des Unternehmens kann weder die Rolle verlieren noch gelöscht werden. ## Mitarbeitende verwalten {#employees} Mitarbeitende verwalten Benutzer mit den Rollen **Manager** und **Admin** unter **Einstellungen** → **Mitarbeiter\*innen**. Die Liste zeigt Name, Rollen, Teams und den Status der Persönlichen Smart Inbox. Sie können suchen und nach Rolle oder Team filtern. Über **Kopiere … E-Mail-Adressen** kopieren Sie die Adressen aller Mitarbeitenden, die zum Rollen- und Teamfilter passen. ### Mitarbeitende einladen {#invite} 1. Klicken Sie auf **Mitarbeiter einladen**. 2. Füllen Sie das Formular aus: | Feld | Bedeutung | | --- | --- | | **Vorname** | Pflichtfeld. | | **Nachname** | Pflichtfeld. | | **Email** | Pflichtfeld. Die Adresse, mit der sich die Person anmeldet. Bei SSO muss sie genau der Adresse beim Identitätsanbieter entsprechen. | | **E-Mail-Aliase** (in der Oberfläche: *Email aliases*) | Weitere Adressen, von denen die Person Dokumente schickt. Workist ordnet Dokumente von diesen Adressen der Person zu. | | **Sprache** | Pflichtfeld. Sprache der Oberfläche und der E-Mails von Workist an diese Person. | | **Rollen** | Eine oder mehrere [Rollen](#roles); ohne Rolle hat die Person keine Berechtigungen. Rollen, die Sie nicht vergeben dürfen, sind ausgegraut. | | **Teams** | Teams, deren Kanäle die Person sieht. Das Standardteam ist immer ausgewählt. | 3. Klicken Sie auf **Erstellen**. Workist schickt der Person eine Einladung per E-Mail: - **Ohne SSO** enthält die E-Mail einen Link, mit dem die Person ihr Passwort setzt. Der Link ist 7 Tage gültig. Ist er abgelaufen, wählen Sie bei der Person ⋮ → **Passwort zurücksetzen**. - **Mit SSO** (Microsoft Entra ID oder SAML ist eingerichtet) meldet sich die Person über SSO an und erhält kein Workist-Passwort, siehe [Single Sign-On](/docs/administration/login-and-security.md#sso). Mit aktivierter Selbstregistrierung für Microsoft Entra ID legt Workist Konten auch selbst an, wenn sich jemand das erste Mal per SSO anmeldet. Diese Konten erhalten die Rolle **Member** und das Standardteam; weitere Rollen und Teams vergeben Sie hier. ### Bearbeiten, Passwort zurücksetzen, löschen Über das Menü ⋮ in der Zeile einer Person: - **Bearbeiten:** Name, E-Mail-Adresse, E-Mail-Aliase, Sprache, Rollen und Teams ändern, dann **Speichern**. - **Passwort zurücksetzen:** Workist schickt der Person eine E-Mail mit einem Link, um ein neues Passwort zu setzen. Personen ohne Workist-Passwort, weil sie sich per SSO anmelden, erhalten keine E-Mail. - **Smart Inbox verwalten:** erscheint, wenn die Person eine Persönliche Smart Inbox verbunden hat. - **Löschen:** Die Person kann sich nicht mehr anmelden. Ihre E-Mail-Adresse ist danach wieder frei; Sie können sie später erneut einladen. Die Zwei-Faktor-Authentifizierung einer Person können Sie nicht selbst zurücksetzen, siehe [Zugang verloren](/docs/administration/login-and-security.md#2fa-lost). ## Teams und Sichtbarkeit {#teams} Jeder Kanal gehört zu genau einem Team. Ein Benutzer sieht die Kanäle seiner Teams und deren Dokumente, in der Dokumentenübersicht ebenso wie in den [Statistiken](/docs/administration/analytics.md) und im [Outlook-Add-In](/docs/data-exchange/outlook-add-in.md). Benutzer mit der Rolle **Admin** sehen alle Kanäle aller Teams. :::tip Manager ohne Zugriff auf einen Kanal Auch ein **Manager** sieht nur die Kanäle seiner Teams. Soll er alle Kanäle sehen, nehmen Sie ihn in alle Teams auf oder vergeben Sie die Rolle **Admin**. ::: Das Team eines Kanals legen Sie in der Kanal-Konfiguration fest, siehe [Kanal-Konfiguration — Allgemein](/docs/channel-configuration/general.md). Ein Teamwechsel wirkt sofort für alle Dokumente des Kanals. ### Das Standardteam Jedes Unternehmen hat ein Standardteam mit dem Namen des Unternehmens. Alle Mitarbeitenden sind immer Mitglied; neue Mitarbeitende kommen automatisch hinzu. Das Standardteam lässt sich weder bearbeiten noch löschen. Kanäle, die alle sehen sollen, ordnen Sie dem Standardteam zu. ### Teams anlegen und pflegen Teams verwalten Benutzer mit den Rollen **Manager** und **Admin** unter **Einstellungen** → **Teams**. 1. Klicken Sie auf **Team erstellen**. 2. Geben Sie **Name** und optional eine **Beschreibung** ein und wählen Sie die **Mitarbeiter\*innen** aus. 3. Klicken Sie auf **Erstellen**. Über ⋮ → **Verwalten** ändern Sie ein Team, über **Löschen** entfernen Sie es. Ein Team, dem noch Kanäle zugeordnet sind, lässt sich nicht löschen; ordnen Sie die Kanäle vorher einem anderen Team zu. Die Teams einer einzelnen Person ändern Sie auch beim [Bearbeiten der Person](#employees). ## Worki für das Unternehmen ein- und ausschalten {#worki} Ein **Admin** kann Worki für alle Benutzer des Unternehmens ausschalten: 1. Öffnen Sie **Einstellungen** → **Organisation**. 2. Wählen Sie links den Eintrag für Agenten (in der Oberfläche: *Agents*). 3. Schalten Sie die Option für Worki aus (in der Oberfläche: *Worki is enabled for your organization*) und speichern Sie. Danach kann niemand im Unternehmen Worki nutzen. Mehr dazu unter [Worki](/docs/agents/worki.md). --- Source: https://docs.workist.com/docs/administration/login-and-security.md # Anmeldung & Sicherheit | Thema | Wer | Wo | | --- | --- | --- | | [Passwort](#password) und [Zwei-Faktor-Authentifizierung](#2fa) | jeder Benutzer für sich | Name unten links → **Dein Profil** → **Passwort und Authentifizierung** | | [MFA-Pflicht für das Unternehmen](#mfa) | **Admin** | **Einstellungen** → **Organisation** → **Mehrfaktor-Authentifizierung** | | [Single Sign-On mit Microsoft Entra ID](#entra-id) | **Admin** | **Einstellungen** → **Organisation** → **Single Sign-On** | | [Single Sign-On mit SAML](#saml) | **Admin** | **Einstellungen** → **Organisation** → **SAML** | | [API-Schlüssel](#api-keys) | **IT**, **Admin** | **Einstellungen** → **Integrationen** → **API-Integrationen** | ## Anmelden {#sign-in} Auf der Anmeldeseite melden Sie sich mit **E-Mail-Adresse** und **Passwort** an. Ist für Ihr Unternehmen Single Sign-On eingerichtet, klicken Sie stattdessen auf **Ohne Passwort anmelden (SSO)**, siehe [Anmeldung per SSO](#sso-sign-in). - Nach 10 Anmeldeversuchen innerhalb von 2 Minuten sperrt Workist weitere Versuche für diese E-Mail-Adresse kurzzeitig („Zu viele Versuche, bitte warte einen Moment."). - Haben Sie Ihr Passwort vergessen, klicken Sie auf **Passwort vergessen?**. Workist schickt Ihnen einen Link, mit dem Sie ein neues Passwort setzen. Der Link ist 7 Tage gültig. ## Passwort {#password} So ändern Sie Ihr Passwort: 1. Klicken Sie unten links auf Ihren Namen → **Dein Profil** und wählen Sie links **Passwort und Authentifizierung**. 2. Geben Sie unter **Passwort ändern** Ihr **Aktuelles Passwort** ein, dann zweimal das neue Passwort (**Neues Passwort**, **Neues Passwort bestätigen**). 3. Klicken Sie auf **Passwort ändern**. Ein Passwort muss mindestens 12 Zeichen lang sein, darf nicht nur aus Ziffern bestehen, kein häufig verwendetes Passwort sein und nicht zu sehr Ihrem Namen oder Ihrer E-Mail-Adresse ähneln. Benutzer mit den Rollen **Manager** und **Admin** können Mitarbeitenden eine E-Mail zum Zurücksetzen des Passworts schicken, siehe [Mitarbeitende verwalten](/docs/administration/users-and-roles.md#employees). Wer sich per SSO anmeldet, hat in der Regel kein Workist-Passwort und kann auch keines zurücksetzen, siehe [Single Sign-On](#sso). ## Zwei-Faktor-Authentifizierung {#2fa} Mit der Zwei-Faktor-Authentifizierung (2FA) fragt Workist bei der Anmeldung mit Passwort zusätzlich einen zweiten Faktor ab. Sie richten sie unter **Passwort und Authentifizierung** im Bereich **Zwei-Faktor-Authentifizierung** ein: | Methode | So funktioniert sie | | --- | --- | | Passkeys (Bereich **Passwörter**) | Sie bestätigen die Anmeldung per Fingerabdruck, Gesichtserkennung, Geräte-PIN oder Sicherheitsschlüssel. Klicken Sie auf **Hinzufügen** → **Passkey einrichten**, folgen Sie Ihrem Browser und klicken Sie auf **Speichern**. Ihr Browser muss Passkeys unterstützen. | | **Authentifikator-Apps** | Eine App oder Browser-Erweiterung erzeugt Einmalcodes. Klicken Sie auf **Hinzufügen**, scannen Sie den QR-Code oder geben Sie den Einrichtungsschlüssel ein, tragen Sie unter **Bestätigungscode eingeben** den aktuellen Code ein und klicken Sie auf **Speichern**. | | **Wiederherstellungscodes** | Sechs Codes für den Notfall, falls Sie keinen Zugriff auf Ihre anderen Methoden haben. Jeder Code gilt einmal. Bewahren Sie die Codes sicher auf. | Zum Hinzufügen und Entfernen einer Methode fragt Workist Ihr Workist-Passwort ab (**Gerät registrieren** bzw. **Gerät abmelden**). Jeder Methode können Sie einen Gerätenamen geben, damit Sie sie später wiedererkennen. **Erste Einrichtung:** Solange Sie keine Methode eingerichtet haben, zeigt Workist nach jeder Anmeldung mit Passwort die Seite **Zwei-Faktor-Authentifizierung**. Dort richten Sie einen Passkey oder eine Authentifikator-App ein, klicken auf **Weiter**, erstellen Ihre Wiederherstellungscodes und schließen mit **Ich habe die Codes gespeichert und möchte fortfahren** ab. Ohne MFA-Pflicht können Sie den Schritt mit **Ohne Zwei-Faktor-Authentifizierung fortfahren** überspringen. **Anmeldung:** Sobald Sie eine Methode eingerichtet haben, fragt Workist bei jeder Anmeldung mit Passwort den zweiten Faktor ab. Über **Anderes Gerät verwenden** wählen Sie eine andere Methode, z. B. einen Wiederherstellungscode. Bei der Anmeldung per SSO fragt Workist keinen zweiten Faktor ab. Diese Aufgabe übernimmt Ihr Identitätsanbieter. ### Zugang verloren {#2fa-lost} Haben Sie keinen Zugriff mehr auf Ihre Methoden, melden Sie sich mit einem Wiederherstellungscode an und richten danach eine neue Methode ein. Haben Sie auch keine Wiederherstellungscodes mehr, wenden Sie sich an den Workist-Support. Ein Admin Ihres Unternehmens kann die Zwei-Faktor-Authentifizierung nicht zurücksetzen. ## MFA für das ganze Unternehmen verlangen {#mfa} Ein **Admin** kann die Mehrfaktor-Authentifizierung für alle Mitarbeitenden verpflichtend machen: 1. Öffnen Sie **Einstellungen** → **Organisation** und wählen Sie links **Mehrfaktor-Authentifizierung**. 2. Aktivieren Sie **Multi-Faktor-Authentifizierung (MFA) ist für jeden Mitarbeiter erforderlich**. 3. Klicken Sie auf **Speichern**. Mitarbeitende ohne eingerichtete Methode werden nach ihrer nächsten Anmeldung zur Einrichtung aufgefordert. Bis sie eine Methode eingerichtet haben, können sie Workist nicht nutzen; überspringen lässt sich der Schritt nicht mehr. :::warning MFA-Pflicht und SSO Die MFA-Pflicht gilt auch für Benutzer, die sich per SSO anmelden. Zum Einrichten einer Methode fragt Workist das Workist-Passwort ab, und Benutzer, die sich per SSO anmelden, haben in der Regel keines. Sie können dann keine Methode einrichten und Workist nicht mehr nutzen. Wenn Sie SSO verwenden, lassen Sie die MFA-Pflicht in Workist ausgeschaltet und verlangen Sie die Mehrfaktor-Authentifizierung in Ihrem Identitätsanbieter. ::: ## Single Sign-On {#sso} Mit Single Sign-On (SSO) melden sich Ihre Mitarbeitenden mit ihrem Firmenkonto an statt mit einem Workist-Passwort. Workist unterstützt zwei Verfahren: - **Microsoft Entra ID** (ehemals Azure AD), eingerichtet auf der Seite **Single Sign-On** - **SAML 2.0** mit einem beliebigen Identitätsanbieter, eingerichtet auf der Seite **SAML** SSO richten nur Benutzer mit der Rolle **Admin** ein. Verwenden Sie für Ihr Unternehmen nur eines der beiden Verfahren: Workist meldet bestehende Benutzer immer über dieselbe Konfiguration Ihres Unternehmens an, unabhängig von der Domain ihrer E-Mail-Adresse. ### Anmeldung per SSO {#sso-sign-in} 1. Der Benutzer klickt auf der Anmeldeseite auf **Ohne Passwort anmelden (SSO)**. 2. Er gibt seine E-Mail-Adresse ein und klickt auf **Anmelden**. 3. Workist leitet ihn zu Ihrem Identitätsanbieter weiter und nach der Anmeldung zurück. Die eingegebene E-Mail-Adresse muss genau der Adresse entsprechen, die der Identitätsanbieter für diesen Benutzer meldet; bei Microsoft Entra ID ist das der Benutzerprinzipalname (UPN). Weichen die Adressen ab, schlägt die Anmeldung fehl. Gibt es für die Adresse keine passende Konfiguration oder kein Workist-Konto, zeigt Workist: „SSO ist für dein Unternehmen nicht konfiguriert oder dein Nutzer ist noch nicht für SSO freigeschaltet." ### Microsoft Entra ID einrichten {#entra-id} **Schritt 1: App in Microsoft Entra ID registrieren** 1. Legen Sie im Microsoft Entra Admin Center unter **App-Registrierungen** eine neue Registrierung an. Als Kontotyp genügen Konten in Ihrem Organisationsverzeichnis. 2. Tragen Sie als Umleitungs-URI für die Plattform **Web** ein: `https://wb.workist.com/login/providers/azure/authorized` 3. Erstellen Sie unter **Zertifikate & Geheimnisse** einen geheimen Clientschlüssel und kopieren Sie seinen **Wert**. Notieren Sie das Ablaufdatum. 4. Prüfen Sie unter **API-Berechtigungen**, dass die delegierte Berechtigung `User.Read` für Microsoft Graph vorhanden ist. Workist liest damit Name und Benutzerprinzipalnamen des angemeldeten Benutzers. 5. Notieren Sie in der **Übersicht** die **Anwendungs-ID (Client)** und die **Verzeichnis-ID (Mandant)**. **Schritt 2: Konfiguration in Workist anlegen** 1. Öffnen Sie **Einstellungen** → **Organisation** und wählen Sie links **Single Sign-On**. Die Seite listet die bestehenden Konfigurationen. 2. Klicken Sie auf die Schaltfläche zum Hinzufügen einer Konfiguration (in der Oberfläche: *Add SSO Configuration*) und füllen Sie das Formular aus: | Feld | Was Sie eintragen | | --- | --- | | **SSO ist für jeden Mitarbeiter erforderlich** | **Ja:** Mitarbeitende melden sich nur noch per SSO an. Die Anmeldung mit E-Mail und Passwort wird abgelehnt. | | **Anbieternamen** | Geben Sie `azure` ein (Microsoft Entra ID). | | **Domain** | Domain der E-Mail-Adressen, z. B. `firma.de`. Workist ordnet darüber neue Benutzer bei der Selbstregistrierung Ihrem Unternehmen zu. | | **Selbstregistrierung zulassen** | **Ja:** Wer eine E-Mail-Adresse dieser Domain hat, aber noch kein Workist-Konto, erhält bei der ersten SSO-Anmeldung automatisch eines (Rolle **Member**, Standardteam). **Nein:** Nur bereits angelegte Benutzer können sich anmelden. | | **Tenant-ID** | **Verzeichnis-ID (Mandant)** aus der App-Registrierung in Microsoft Entra ID. | | **Client-ID** | **Anwendungs-ID (Client)** der App-Registrierung. | | **Client-Secret** | **Wert** des geheimen Clientschlüssels. Workist zeigt ihn nach dem Speichern nicht mehr an. Lassen Sie das Feld leer, bleibt der gespeicherte Wert erhalten. | 3. Klicken Sie auf **Erstellen**. Über das Stift-Symbol einer Zeile bearbeiten Sie eine Konfiguration, über das Papierkorb-Symbol löschen Sie sie. **Schritt 3: Testen.** Melden Sie sich mit einem Testbenutzer per SSO an, bevor Sie **SSO ist für jeden Mitarbeiter erforderlich** aktivieren. **Mehrere Domains:** Jede Konfiguration gilt für eine Domain. Haben Ihre Mitarbeitenden E-Mail-Adressen mit verschiedenen Domains, legen Sie je Domain eine Konfiguration an, alle mit derselben App-Registrierung (gleiche Tenant-ID, Client-ID und Client-Secret) und derselben Einstellung für **SSO ist für jeden Mitarbeiter erforderlich**. **Was sich für Benutzer ändert:** - Nach der ersten Anmeldung per Microsoft Entra ID deaktiviert Workist das Workist-Passwort des Benutzers. Er meldet sich danach nur noch per SSO an; auch **Passwort vergessen?** hilft ihm nicht mehr. - Mitarbeitende, die Sie einladen, während SSO eingerichtet ist, erhalten kein Workist-Passwort, sondern eine Einladung zur Anmeldung per SSO. :::warning Client-Secret läuft ab Ein geheimer Clientschlüssel in Microsoft Entra ID hat ein Ablaufdatum. Danach kann sich niemand mehr per SSO anmelden. Erstellen Sie rechtzeitig einen neuen Schlüssel und tragen Sie seinen Wert in Workist unter **Client-Secret** ein. ::: ### SAML einrichten {#saml} **Schritt 1: Adressen von Workist abrufen** 1. Öffnen Sie **Einstellungen** → **Organisation** und wählen Sie links **SAML**. 2. Tragen Sie die **Domain** ein und klicken Sie auf **Speichern**. Danach zeigt die Seite, gegebenenfalls nach dem Neuladen, die **SP Metadaten-URL** und die **Assertion Consumer Service (ACS) URL**. **Schritt 2: Anwendung im Identitätsanbieter anlegen** Legen Sie in Ihrem Identitätsanbieter eine SAML-Anwendung an. Viele Identitätsanbieter übernehmen die Werte direkt von der **SP Metadaten-URL**. Sonst tragen Sie ein: - als Entity ID bzw. Audience die **SP Entity ID** von der Workist-Seite, - als Antwort-URL (ACS) die **Assertion Consumer Service (ACS) URL**, - als NameID die E-Mail-Adresse des Benutzers im Format `emailAddress`. Die E-Mail-Adresse muss genau der E-Mail-Adresse des Benutzers in Workist entsprechen. **Schritt 3: Angaben des Identitätsanbieters in Workist eintragen** | Feld | Was Sie eintragen | | --- | --- | | **SAML ist für jeden Mitarbeiter erforderlich** | **Ja:** Mitarbeitende melden sich nur noch per SAML an. Die Anmeldung mit E-Mail und Passwort wird abgelehnt. | | **Domain** | Domain der E-Mail-Adressen Ihrer Mitarbeitenden, z. B. `firma.de`. | | **Selbstregistrierung zulassen** | Hat bei SAML keine Wirkung. Anmelden können sich nur Benutzer, die in Workist bereits angelegt sind. | | **IdP Entity ID** | Entity ID (Aussteller) Ihres Identitätsanbieters. | | **IdP SSO URL** | Single-Sign-On-URL Ihres Identitätsanbieters für das HTTP-Redirect-Binding. | | **IdP SLO URL (Einzelabmeldung)** | Optional. | | **IdP X.509-Zertifikat** | Signaturzertifikat Ihres Identitätsanbieters (Base64). Workist zeigt es nach dem Speichern nicht mehr an. Lassen Sie das Feld leer, bleibt das gespeicherte Zertifikat erhalten. | | **SP Entity ID** | Nur lesbar. Kennung von Workist. Tragen Sie sie beim Identitätsanbieter als Entity ID bzw. Audience ein. | | **SP Name ID-Format** | Nur lesbar. Workist erwartet als NameID die E-Mail-Adresse (`emailAddress`). | | **SP Metadaten-URL** | Nur lesbar, erscheint nach dem ersten Speichern. Metadaten von Workist; viele Identitätsanbieter übernehmen die Einstellungen direkt von dieser Adresse. | | **Assertion Consumer Service (ACS) URL** | Nur lesbar, erscheint nach dem ersten Speichern. Antwort-URL, die Sie beim Identitätsanbieter eintragen. | | **Signierte Assertions erforderlich** | **Ja:** Workist akzeptiert nur signierte Assertions. Empfohlen. | | **Signierte Nachrichten erforderlich** | **Ja:** Workist verlangt zusätzlich, dass die gesamte SAML-Antwort signiert ist. | | **Attribut-Mapping (JSON)** | Optional. Nur nötig, wenn Ihr Identitätsanbieter die E-Mail-Adresse weder als NameID noch im Attribut `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` sendet. Beispiel: `{"email": "mail"}`. Workist liest aus der Antwort nur die E-Mail-Adresse. | Klicken Sie auf **Speichern**. **Schritt 4: Benutzer anlegen und testen.** Per SAML können sich nur Benutzer anmelden, die in Workist bereits angelegt sind. Laden Sie Ihre Mitarbeitenden ein, siehe [Mitarbeitende einladen](/docs/administration/users-and-roles.md#invite), und testen Sie die Anmeldung, bevor Sie **SAML ist für jeden Mitarbeiter erforderlich** aktivieren. Zu beachten: - Starten Sie die Anmeldung immer auf der Workist-Anmeldeseite über **Ohne Passwort anmelden (SSO)**. Eine Anmeldung aus dem Portal Ihres Identitätsanbieters heraus unterstützt Workist nicht. - Eine Anmeldung per SAML deaktiviert das Workist-Passwort nicht. Soll niemand mehr das Passwort verwenden, aktivieren Sie **SAML ist für jeden Mitarbeiter erforderlich**. ### Anmeldung nur per SSO erlauben {#sso-required} Mit **SSO ist für jeden Mitarbeiter erforderlich** (Microsoft Entra ID) bzw. **SAML ist für jeden Mitarbeiter erforderlich** lehnt Workist die Anmeldung mit E-Mail und Passwort für alle Benutzer Ihres Unternehmens ab, auch für Admins. Sie erhalten die Meldung „Anmeldung über SSO ist für dieses Konto erforderlich." Aktivieren Sie die Option erst, wenn die Anmeldung per SSO funktioniert. ## API-Schlüssel {#api-keys} Mit einem API-Schlüssel greifen Ihre Systeme über die [Workist-API](/docs/api-documentation.md) auf Workist zu. Ein Schlüssel gehört zum Unternehmen, nicht zu einer Person. Schlüssel verwalten Benutzer mit den Rollen **IT** und **Admin** unter **Einstellungen** → **Integrationen** → **API-Integrationen**: - **Anlegen:** **Integration konfigurieren** → **Integrationsname** eingeben, optional ein **Ablaufdatum** wählen und festlegen, für welche Kanäle der Schlüssel gilt: **Zugriff auf alle Kanäle gewähren** oder einzelne Kanäle je Dokumentart. Dann **Integration erstellen**. - **Schlüssel kopieren:** Workist zeigt den Schlüssel nur einmal an. Kopieren Sie ihn sofort und bewahren Sie ihn sicher auf. - **Ablaufdatum:** Nach dem Ablaufdatum lehnt Workist Anfragen mit diesem Schlüssel ab. Über **Integration bearbeiten** verlängern Sie das Datum. - **Erneuern:** **API-Schlüssel erneuern** erzeugt einen neuen Schlüssel. Der alte gilt ab sofort nicht mehr. - **Löschen:** **Integration löschen** macht den Schlüssel sofort ungültig. Schlüssel, die Workist für ein [Outlook-Add-In](/docs/data-exchange/outlook-add-in.md) erzeugt, erscheinen nicht in dieser Liste. --- Source: https://docs.workist.com/docs/administration/notifications.md # Benachrichtigungen Workist informiert Sie auf zwei Wegen über Dokumente, die Ihre Unterstützung brauchen: - **E-Mail-Zusammenfassungen** zu festen Zeiten. Den Zeitplan legt ein Admin für das ganze Unternehmen fest. Jeder Benutzer kann die E-Mails für sich abbestellen. - **Browser-Benachrichtigungen** für einzelne Dokumente, die Workist gerade verarbeitet. ## Firmenbenachrichtigungen: Zeitplan für das Unternehmen Den Zeitplan der E-Mail-Zusammenfassungen legen Benutzer mit der Rolle Admin fest (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). Er gilt für alle Benutzer des Unternehmens. 1. Öffnen Sie „Einstellungen“ → „Organisation“. 2. Wählen Sie in der Navigation links „Firmenbenachrichtigungen“. 3. Wählen Sie unter „E-Mail-Benachrichtigungsoption“ eine Option, ergänzen Sie gegebenenfalls Wochentag und Uhrzeit und klicken Sie auf „Speichern“. | Option | Wirkung | |---|---| | „Nie“ | Workist verschickt keine Zusammenfassungen. | | „Bei jeder fälligen Unterstützung“ | E-Mail-Benachrichtigungen sind eingeschaltet, aber ohne Zeitplan. Mit dieser Option verschickt Workist derzeit keine Zusammenfassungen. Wenn Sie E-Mails erhalten möchten, wählen Sie einen der beiden folgenden Zeitpläne. | | „An jedem Arbeitstag (Mo-Fr)“ | Montags bis freitags eine Zusammenfassung zur gewählten „Uhrzeit“. Unter „Zusätzliche Zeit“ können Sie eine zweite Uhrzeit am selben Tag wählen. | | „Einmal in der Woche“ | Eine Zusammenfassung pro Woche am gewählten „Wochentag“ (Montag bis Freitag) zur gewählten „Uhrzeit“. | Als Uhrzeit wählen Sie eine volle Stunde zwischen 06:00 und 20:00. Es gilt die Zeitzone aus dem „Firmenprofil“. Neue Unternehmen starten mit Zusammenfassungen an jedem Arbeitstag um 08:00 und 13:00. ### Inhalt der Zusammenfassung Die E-Mail listet jeden Kanal, für den Sie über Ihre Teams zuständig sind. Pro Kanal steht darin: - wie viele Dokumente auf Unterstützung warten und - wie viele Dokumente seit der letzten Zusammenfassung abgeschlossen wurden. Für jede Dokumentart (Bestellungen, Preisanfragen, Auftragsbestätigungen, Rechnungen, Lieferscheine) verschickt Workist eine eigene E-Mail. Ein Button in der E-Mail führt direkt in die Workbench. Workist schickt die Zusammenfassung an alle aktiven Mitglieder des Teams, dem ein Kanal zugeordnet ist. Für Kanäle anderer Teams erhalten Sie keine Zusammenfassung, auch nicht als Admin. ## Persönliche E-Mail-Benachrichtigungen Jeder Benutzer kann die E-Mails für sich ein- oder ausschalten: 1. Klicken Sie links unten auf Ihren Namen und wählen Sie „Dein Profil“. 2. Wählen Sie in der Navigation links „Benachrichtigungen“. 3. Stellen Sie „E-Mail-Benachrichtigungen erhalten“ auf „Ja, wenn für die Organisation aktiviert“ oder „Nein“ und klicken Sie auf „Speichern“. Für neue Benutzer ist „Ja, wenn für die Organisation aktiviert“ voreingestellt. Die Einstellung gilt außer für die Zusammenfassungen auch für diese E-Mails: - Hinweise auf fehlgeschlagene Stammdatenimporte (gehen an Benutzer mit der Rolle IT) - den Hinweis, dass Ihre [Persönliche Smart Inbox](/docs/smart-inbox.md) die Verbindung zu Outlook verloren hat E-Mails zu Einladungen und zum Zurücksetzen des Passworts erhalten Sie unabhängig von dieser Einstellung. ## Zusammenspiel von Firmen- und persönlicher Einstellung Sie erhalten eine Zusammenfassung nur, wenn alle drei Bedingungen erfüllt sind: 1. Die Firmenbenachrichtigungen stehen auf „An jedem Arbeitstag (Mo-Fr)“ oder „Einmal in der Woche“. 2. Ihre persönliche Einstellung steht auf „Ja, wenn für die Organisation aktiviert“. 3. Sie sind Mitglied des Teams, dem der Kanal zugeordnet ist. | Firmenbenachrichtigungen | Persönlich „Ja, wenn für die Organisation aktiviert“ | Persönlich „Nein“ | |---|---|---| | „An jedem Arbeitstag (Mo-Fr)“ oder „Einmal in der Woche“ | Zusammenfassungen nach Zeitplan | keine Zusammenfassungen | | „Nie“ oder „Bei jeder fälligen Unterstützung“ | keine Zusammenfassungen | keine Zusammenfassungen | ## Browser-Benachrichtigungen für einzelne Dokumente Öffnen Sie ein Dokument, das Workist noch verarbeitet (Status „Laufend“), zeigt die Workbench den Hinweis „Tipp: Aktivieren Sie Verarbeitungsbenachrichtigungen“. 1. Klicken Sie auf „Für Benachrichtigungen anmelden“. 2. Erlauben Sie Benachrichtigungen, wenn Ihr Browser danach fragt. Braucht das Dokument nach der Verarbeitung Ihre Unterstützung, zeigt Ihr Browser eine Benachrichtigung. Ein Klick darauf öffnet das Dokument. Verarbeitet Workist das Dokument vollautomatisch, kommt keine Benachrichtigung. - Die Anmeldung gilt nur für dieses eine Dokument und nur für den Browser, in dem Sie sie aktiviert haben. - Mit „Von Benachrichtigungen abmelden“ nehmen Sie die Anmeldung zurück. - Unterstützt Ihr Browser keine Push-Benachrichtigungen, erscheint der Hinweis nicht. - Browser-Benachrichtigungen sind unabhängig von den E-Mail-Einstellungen. --- Source: https://docs.workist.com/docs/administration/analytics.md # Statistiken Die Statistiken zeigen, wie viele Dokumente Workist verarbeitet hat, wie viele davon ohne Eingriff durchgelaufen sind, wie viel Zeit Ihr Team spart und warum Dokumente Unterstützung brauchen. ## Wer die Statistiken sieht Die Statistiken öffnen Benutzer mit den Rollen **Manager** und **Admin**, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md#permissions). Sie erreichen sie über **Statistiken** in der linken Navigation oder über das Menü ⋮ in der Dokumentenübersicht: **Analysen anzeigen** zeigt alle Kanäle der Dokumentart, **Kanalanalysen anzeigen** nur den geöffneten Kanal. Die Zahlen umfassen nur die Kanäle Ihrer Teams. Admins sehen die Zahlen aller Kanäle. ## Filter Oben wählen Sie den Reiter, die Dokumentart, die Kanäle und den Zeitraum: - **Reiter:** **Workbench** zeigt die Verarbeitung von Dokumenten, **Inbox** die [Smart Inbox](/docs/smart-inbox.md). - **Dokumentart:** Preisanfragen, Bestellungen, Bestellbestätigungen, Rechnungen, Lieferscheine oder Universal. Nicht freigeschaltete Dokumentarten sind ausgegraut. In der aktiven Dokumentart wählen Sie einzelne Kanäle, gruppiert nach **Automatisierte Kanäle** und **Nicht automatisierte Kanäle**. - **Zeitraum:** **Letzte 7 Tage**, **Letzte 30 Tage** (Standard), **Letzte 3 Monate**, **Letzte 6 Monate**, **Letzte 12 Monate** oder **Benutzerdefiniert...**. Ist für Ihr Unternehmen eine kürzere Aufbewahrungsdauer für Daten vereinbart, lassen sich nur Tage innerhalb dieser Dauer wählen. Workist ordnet jedes Dokument dem Tag zu, an dem es abgeschlossen, verworfen oder gelöscht wurde. Es gilt die Zeitzone aus dem **Firmenprofil**. ## Reiter Workbench {#workbench} | Kennzahl | Was sie zeigt | | --- | --- | | **Zeitaufwand für die Verarbeitung von Dokumenten** | Dauer der Dokumentenverarbeitung mit Workist im Vergleich zu vor der Nutzung von Workist. | | **Insgesamt verarbeitete Dokumente** | Anzahl der über Workist bearbeiteten Dokumente. | | **Zeitersparnis pro fertiggestelltem Dokument** | Zeitersparnis pro Dokument durch Workist im Vergleich zur manuellen Bearbeitung. | | **Gesamte Zeitersparnis** | Gesamte Zeitersparnis durch Workist im Vergleich zur manuellen Bearbeitung. | | **Assistenzzeit pro Dokument** | Durchschnittliche Zeit, welche die Benutzer:innen mit der Bearbeitung eines Dokuments verbringen, das Workist nicht automatisch verarbeiten konnte. | | **Dokumentenverarbeitung** | Aufschlüsselung aller über Workist verarbeiteten Dokumente nach Verarbeitungsart. | | **Feldextraktion** | Verhältnis von nicht unterstützten zu unterstützten Feldern. Kopfzeilenfelder können Unterfelder enthalten und werden als ein Datenpunkt gruppiert; jeder Einzelposten wird als einer gezählt. | | **Top 5 Gründe für Unterstützung** | Top-Felder, die vom KI-Agenten zur Unterstützung markiert wurden - mit Prozentangaben aller Unterstützungsgründe. | **Dokumentenverarbeitung** teilt die Dokumente in **Automatisiert**, **Unterstützt**, **Verworfen** und **Gelöscht**. Ein abgeschlossenes Dokument gilt als unterstützt, sobald ein Benutzer es in der Assistenz bearbeitet hat, sonst als automatisiert. **Insgesamt verarbeitete Dokumente** zählt die abgeschlossenen Dokumente ohne verworfene und gelöschte. ### So berechnet Workist die Zeiten {#times} - **Assistenzzeit:** Workist misst, wie lange Benutzer ein Dokument, das auf Unterstützung wartet, aktiv in der Assistenz geöffnet haben, und addiert diese Zeiten je Dokument. Die Kennzahl **Assistenzzeit pro Dokument** zeigt den Median über alle unterstützten Dokumente, nicht den Durchschnitt; einzelne Ausreißer verzerren den Wert so nicht. - **Ohne Workist:** **Zeit pro Dokument vor Workist** × Anzahl verarbeiteter Dokumente. Den Wert stellen Sie je Kanal ein, siehe [Kanal-Konfiguration — Allgemein](/docs/channel-configuration/general.md); Standard sind 270 Sekunden. Bei mehreren Kanälen verwendet Workist den Durchschnitt der Kanäle. - **Mit Workist:** Assistenzzeit pro Dokument × Anzahl unterstützter Dokumente. Automatisch verarbeitete Dokumente zählen mit null Sekunden. - **Gesamte Zeitersparnis:** Ohne Workist minus Mit Workist, mindestens null. **Zeitersparnis pro fertiggestelltem Dokument** teilt die gesamte Zeitersparnis durch die Anzahl verarbeiteter Dokumente. :::note Aufbewahrung der Assistenzzeiten Assistenzzeiten speichert Workist 12 Monate. Für ältere Zeiträume zeigen die Zeit-Kennzahlen **N/A**. ::: ### Top 5 Gründe für Unterstützung {#assistance-reasons} Die Liste zeigt die fünf häufigsten Gründe, aus denen Dokumente im Zeitraum Unterstützung brauchten, jeweils mit dem betroffenen Feld oder der betroffenen Prüfung und dem Anteil an allen Gründen. Ein Dokument kann mehrere Gründe haben. Klicken Sie auf einen Grund, zeigt Workist bis zu fünf betroffene Dokumente mit Link. | Grund in der Liste | Bedeutung | | --- | --- | | Unsicheres Feld *Feld* | Die Konfidenz des Feldes liegt unter dem Schwellenwert. | | Ungültiges Feld *Feld* | Ein Pflichtfeld ist leer oder der Wert ist ungültig. | | Validierungsprüfung *Prüfung* fehlgeschlagen | Eine Validierungsprüfung ist fehlgeschlagen. | | *Feld* weicht von der Bestellung ab | Der Wert weicht von der abgeglichenen Bestellung ab. | | Keine Positionen | Workist hat keine Positionen gefunden. | Welche Prüfungen es gibt und wie Sie Gründe für Unterstützung verringern, steht unter [Validierungsprüfungen](/docs/channel-configuration/document-processing/validation-checks.md). ## Reiter Inbox {#inbox} Der Reiter **Inbox** wertet E-Mails in Postfächern mit [Smart Inbox](/docs/smart-inbox.md) aus und vergleicht sie mit dem vorherigen Zeitraum gleicher Länge. Die Bezeichnungen erscheinen in der Oberfläche derzeit auf Englisch. | Kennzahl | Was sie zeigt | | --- | --- | | **E-Mail-Verteilung** (in der Oberfläche: *Email Distribution*) | Vergleicht das E-Mail-Volumen der Postfächer mit Smart Inbox mit allen anderen Postfächern. | | **Gesamtes Postfachvolumen** (in der Oberfläche: *Total Inbox Volume*) | Anzahl aller eingehenden E-Mails über alle Postfächer. | | **Smart-Inbox-Anteil** (in der Oberfläche: *Smart Inbox Share*) | Anteil Ihres gesamten E-Mail-Volumens, der in Postfächern mit aktiver Smart Inbox eingegangen ist. | | **Durchgängige Automatisierung** (in der Oberfläche: *Automation End-to-End*) | Anteil der Smart-Inbox-E-Mails, die ohne manuelle Aktion verarbeitet und weitergeleitet wurden. | | **Erkennungsrate** (in der Oberfläche: *Recognition Rate*) | Anteil der Smart-Inbox-E-Mails, die richtig klassifiziert und nicht von Benutzern verworfen oder gelöscht wurden. | | **Manuelle Weiterleitung** (in der Oberfläche: *Manual Forwarding*) | Anteil der E-Mails, die die Smart Inbox übersehen oder falsch klassifiziert hat und die Benutzer manuell weiterleiten mussten. | | **E-Mail-Kategorien** (in der Oberfläche: *Email Categories*) | Anteil jeder E-Mail-Kategorie an allen E-Mails. | | **Häufigste E-Mail-Kategorien** (in der Oberfläche: *Top N Email Categories*) | Die häufigsten E-Mail-Kategorien nach Anteil am Gesamtvolumen, mit Entwicklung. | ## Als Excel-Datei exportieren {#export} **Für Excel exportieren** lädt die Zahlen des aktiven Reiters mit den gewählten Filtern als Excel-Datei herunter. Tabellenblätter und Spalten sind englisch benannt, Zeiten stehen in Sekunden. | Export | Tabellenblatt | Spalten | | --- | --- | --- | | Reiter **Workbench** | Assistance Times | Time, MedianAssistanceTime (seconds), AssistedDocuments | | Reiter **Workbench** | Extraction Rate | Time, ExtractionRate | | Reiter **Workbench** | Top Assistance Reasons | Reason, FieldName, Percentage | | Reiter **Workbench** | Metrics | Metric, Value | | Reiter **Workbench** | Daily Metrics | Time, Metric, Value | | Reiter **Inbox** | Smart Inbox Share | Date, SmartInboxCount, NonSmartInboxCount | | Reiter **Inbox** | Performance Metrics | Metric, Total Documents, Rate (%) | | Reiter **Inbox** | Email Categories | Date, Category, Count | ## Fragen an Worki Wenn Sie [Worki](/docs/agents/worki.md) nutzen, können Sie Worki auch Fragen zu Ihren Statistiken stellen, z. B. nach der Entwicklung der Automatisierung in einem Kanal. --- Source: https://docs.workist.com/docs/api-documentation.md # API Dokumentation Die Workist-API verbindet Ihre Systeme direkt mit Workist. Über sie laden Sie Dokumente hoch, rufen verarbeitete Daten ab, melden Importergebnisse zurück und übertragen Stammdaten. - **Basis-URL:** `https://api.workist.com/v1` (gleichwertig: `https://api.workist.com/api/v1`) - **Swagger-Oberfläche:** [https://api.workist.com/v1/swagger/](https://api.workist.com/v1/swagger/), mit allen Endpunkten und Schemas - **Authentifizierung:** API-Schlüssel im Header `Authorization: Bearer ` ## Abschnitte - [Quickstart](/docs/api-documentation/quickstart.md): API-Schlüssel erstellen und den ersten Aufruf senden - [Dokumenten-API](/docs/api-documentation/document-api.md): Dokumente hochladen, abrufen und das Importergebnis zurückmelden, für alle Dokumenttypen - [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md): Stammdaten per API übertragen - [Webhooks](/docs/data-exchange/webhooks.md): Ihr System bei Ereignissen automatisch benachrichtigen Für Entwicklung mit KI-Assistenten: [KI-Assistenten](/docs/ai-assistants.md) — Skill und Markdown-Versionen dieser Dokumentation --- Source: https://docs.workist.com/docs/api-documentation/quickstart.md # Quickstart In vier Schritten zum ersten Aufruf der Workist-API. ## 1. API-Schlüssel erstellen {#api-schluessel} API-Schlüssel verwalten Benutzer mit der Rolle IT oder Admin (siehe [Benutzer und Rollen](/docs/administration/users-and-roles.md)). 1. Klicken Sie in der Workbench in der linken Navigationsleiste auf **Einstellungen** und wählen Sie **Integrationen**. Die Seite **API-Integrationen** öffnet sich. 2. Geben Sie in der Karte **Schnell-API-Integration erstellen** einen **Integrationsname** ein, z. B. den Namen des Systems, das die API nutzt, und klicken Sie auf **Integration erstellen**. 3. Die neue Integration erscheint in der Tabelle. Kopieren Sie den Schlüssel aus der Spalte **API-Schlüssel** und bewahren Sie ihn sicher auf. Er wird nur einmal angezeigt. 4. Optional: Klicken Sie auf **Integration bearbeiten**, um den Schlüssel auf einzelne Kanäle je Dokumenttyp zu beschränken (statt **Zugriff auf alle Kanäle gewähren**) oder ein **Ablaufdatum** zu setzen. Ab diesem Tag lehnt die API den Schlüssel ab. Über **Integration konfigurieren** legen Sie eine Integration direkt mit Kanälen und Ablaufdatum an. Den Schlüssel zeigt die Tabelle danach nicht an. Klicken Sie in diesem Fall auf **API-Schlüssel erneuern**, um einen Schlüssel zu erzeugen und anzuzeigen. Gut zu wissen: - Ein Schlüssel gehört zu Ihrer Organisation, nicht zu einer Person. Er funktioniert weiter, wenn der Benutzer, der ihn erstellt hat, das Unternehmen verlässt. - **API-Schlüssel erneuern** (Symbol in der Tabelle) erzeugt einen neuen Schlüssel. Der alte ist sofort ungültig. - Ein abgelaufener Schlüssel funktioniert wieder, sobald Sie das Ablaufdatum über **Integration bearbeiten** verschieben oder entfernen. ## 2. Ersten Aufruf senden {#erster-aufruf} Senden Sie den Schlüssel im Header `Authorization` mit dem Präfix `Bearer`: ```bash curl -H "Authorization: Bearer " \ "https://api.workist.com/v1/orders?finished=true&imported=false" ``` Alternativ testen Sie die API in der [Swagger-Oberfläche](https://api.workist.com/v1/swagger/): Klicken Sie auf **Authorize**, hinterlegen Sie Ihren Schlüssel und führen Sie `GET /orders` aus. :::warning Kein Schrägstrich am Ende Pfade enden ohne `/`. `GET /orders` funktioniert, `GET /orders/` liefert `404`. ::: ## 3. Kanal auf API umstellen {#kanal} Wenn Ihr System die Ergebnisse per API abholt, stellen Sie im Kanal unter **Kanal verwalten** → **Upload** die Übertragungsart **API** ein. Sonst überträgt Workist die Ergebnisse zusätzlich per SFTP, und erfolgreich übertragene Dokumente erscheinen nicht mehr unter `imported=false`. ## 4. Ablauf einrichten {#ablauf} 1. Dokumente gelangen per E-Mail, über die Workbench oder per `POST /orders` in den Kanal (siehe [Dokument hochladen](/docs/api-documentation/document-api.md#hochladen)). 2. Workist verarbeitet die Dokumente. Dokumente, die Workist nicht automatisch abschließen kann, bearbeiten Ihre Mitarbeitenden in der Workbench. 3. Ihr System fragt alle abgeschlossenen, noch nicht übergebenen Bestellungen ab: ``` GET /orders?finished=true&imported=false ``` Die Antwort enthält höchstens 10 Dokumente. Folgen Sie dem Link in `next`, bis er `null` ist (siehe [Seiten](/docs/api-documentation/document-api.md#seiten)). 4. Für jede Bestellung: - a) Import in Ihr System, z. B. als Auftrag im ERP. - b) Ergebnis zurückmelden mit `PUT /orders/{id}/mark_imported`: ```json {"status": "SUCCEEDED", "external_reference": "AB-2026-0815"} ``` Lehnt Ihr System die Bestellung ab, melden Sie `"status": "FAILED"` mit der Ursache in `external_message`. Die Bestellung geht dann zurück in die Workbench (siehe [Was nach `FAILED` passiert](/docs/api-documentation/document-api.md#failed)). Dieselben Schritte gelten für Rechnungen, Auftragsbestätigungen, Angebotsanfragen, Lieferscheine und Leistungsverzeichnisse, jeweils mit ihrer eigenen [Ressource](/docs/api-documentation/document-api.md#ressourcen). Statt regelmäßig abzufragen, können Sie sich per [Webhook](/docs/data-exchange/webhooks.md) benachrichtigen lassen. ## Fehler {#fehler} Die API antwortet bei Fehlern mit JSON, z. B. `{"detail": "Invalid token"}`. Die häufigsten Ursachen: - `401`: Schlüssel fehlt, ist falsch oder abgelaufen (`Integration has expired`). - `404`: Pfad mit `/` am Ende, oder das Dokument gehört zu einem Kanal, den der Schlüssel nicht sieht. - `400` bei `mark_imported`: Das Dokument ist noch nicht abgeschlossen (`Record not finished yet`) oder wurde bereits mit `SUCCEEDED` gemeldet. Alle Fehler sind in der [Dokumenten-API](/docs/api-documentation/document-api.md#fehler) beschrieben. ## Stammdaten-API {#stammdaten-api} Für die Übertragung von Stammdaten per API siehe [Benutzung der Stammdaten-API](/docs/api-documentation/master-data-api.md). --- Source: https://docs.workist.com/docs/api-documentation/document-api.md # Dokumenten-API Mit der Dokumenten-API laden Sie Dokumente in einen Kanal hoch, rufen die verarbeiteten Daten ab und melden Workist, ob der Import in Ihr System geklappt hat. Alle Dokumenttypen bieten dieselben Operationen. Die vollständigen Schemas aller Anfragen und Antworten stehen in der [Swagger-Oberfläche](https://api.workist.com/v1/swagger/). Diese Seite beschreibt, wie Sie die API einsetzen. ## Grundlagen {#grundlagen} - **Basis-URL:** `https://api.workist.com/v1` (gleichwertig: `https://api.workist.com/api/v1`). - **Kein Schrägstrich am Ende.** `GET /orders` funktioniert, `GET /orders/` liefert `404`. - **Authentifizierung:** Jeder Aufruf enthält den Header `Authorization: Bearer `. Wie Sie einen Schlüssel erstellen, steht im [Quickstart](/docs/api-documentation/quickstart.md#api-schluessel). - **Kanäle:** Ein API-Schlüssel sieht nur die Kanäle, die für ihn freigegeben sind. Dokumente anderer Kanäle liefert die API nicht aus. - **Format:** Antworten sind JSON. Uploads senden Sie als `multipart/form-data`, alle anderen Anfragen als JSON. - **Übertragungsart des Kanals:** Wenn Ihr System die Ergebnisse per API abholt, stellen Sie im Kanal unter **Upload** die Übertragungsart **API** ein. Sonst überträgt Workist die Ergebnisse zusätzlich per SFTP, und erfolgreich übertragene Dokumente erscheinen nicht mehr unter `imported=false`. ## Ressourcen {#ressourcen} | Dokumenttyp | Ressource | |---|---| | Bestellungen | `/orders` | | Rechnungen | `/invoices` | | Auftragsbestätigungen | `/order-confirmations` | | Angebotsanfragen | `/rfq` | | Lieferscheine | `/delivery-notes` | | Leistungsverzeichnisse | `/list-of-services` | ## Operationen {#operationen} Jede Ressource bietet dieselben sieben Operationen. Ersetzen Sie `{ressource}` durch den Pfad aus der Tabelle oben, z. B. `/orders`. | Methode | Pfad | Zweck | |---|---|---| | `GET` | `/{ressource}` | Dokumente auflisten (seitenweise, filterbar) | | `GET` | `/{ressource}/{id}` | Ein Dokument abrufen | | `POST` | `/{ressource}` | Datei in einen Kanal hochladen | | `DELETE` | `/{ressource}/{id}` | Dokument löschen | | `PATCH` | `/{ressource}/{id}/meta` | Absender und Betreff setzen | | `PUT` | `/{ressource}/{id}/mark_imported` | Ergebnis des Imports in Ihr System zurückmelden | | `PUT` | `/{ressource}/{id}/assign_user` | Dokument einem Benutzer zuweisen | | `POST` | `/list-of-services/{id}/generate-x94` | GAEB-X94-Angebotsdatei aus einem X83-Leistungsverzeichnis erzeugen | ## Typischer Ablauf {#ablauf} 1. Dokumente kommen per E-Mail, über die Workbench oder per `POST /{ressource}` in den Kanal. 2. Ihr System fragt regelmäßig alle abgeschlossenen, noch nicht übergebenen Dokumente ab, z. B. `GET /orders?finished=true&imported=false`, und liest alle Seiten (siehe [Seiten](#seiten)). 3. Für jedes Dokument importiert Ihr System die Daten und meldet das Ergebnis mit `PUT /orders/{id}/mark_imported`: `SUCCEEDED` mit Ihrer Belegnummer oder `FAILED` mit der Fehlermeldung. 4. Gemeldete Dokumente erscheinen in der Abfrage aus Schritt 2 nicht mehr. Mit `FAILED` gemeldete Dokumente kommen zurück, sobald ein Benutzer sie in der Workbench korrigiert und abgeschlossen hat (siehe [Import zurückmelden](#mark-imported)). Statt regelmäßig abzufragen, können Sie sich per [Webhook](/docs/data-exchange/webhooks.md) benachrichtigen lassen, sobald ein Dokument abgeschlossen ist, und es dann abrufen. ## Dokumente abrufen {#abrufen} ### Filter {#filter} `GET /{ressource}` akzeptiert folgende Query-Parameter: | Parameter | Bedeutung | |---|---| | `channel` | Kanal-ID. Nur Dokumente dieses Kanals. | | `assistance_needed` | `true`: nur Dokumente, die auf Bearbeitung in der Workbench warten. `false`: alle anderen. | | `finished` | `true`: abgeschlossene, nicht verworfene Dokumente. `false`: noch nicht abgeschlossene Dokumente. | | `imported` | `true`: erfolgreich übergeben (Rückmeldung `SUCCEEDED` oder erfolgreiche Übertragung per SFTP, AS2 oder ERP-Integration). `false`: noch nicht erfolgreich übergeben. Ohne `import_failed` gilt dabei `import_failed=false`. | | `import_failed` | `true`: Übergabe fehlgeschlagen (z. B. Rückmeldung `FAILED`). `false`: alle anderen. | | `created_by` | E-Mail-Adresse oder ID des Benutzers, der das Dokument hochgeladen hat. | | `assisted_by` | E-Mail-Adresse oder ID des Benutzers, der das Dokument bearbeitet hat. | | `date_from` | Erstellt ab diesem Zeitpunkt, ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). | | `date_to` | Erstellt bis zu diesem Zeitpunkt, ISO 8601. | | `show_unfinished_data` | `true`: `data` auch für Dokumente befüllen, die noch in Verarbeitung sind. Standard: `false`. | | `page` | Seitennummer, beginnend bei 1. | | `page_size` | Einträge pro Seite, höchstens 10. | `GET /{ressource}/{id}` akzeptiert ebenfalls `show_unfinished_data`. ### Seiten {#seiten} Die Liste liefert **höchstens 10 Dokumente pro Seite**, älteste zuerst. Die Antwort hat diese Form: ```json { "total_count": 37, "next": "https://api.workist.com/v1/orders?finished=true&imported=false&page=2", "previous": null, "items": [ ... ] } ``` - Rufen Sie `next` auf, bis der Wert `null` ist. Wer nur die erste Seite liest, verpasst Dokumente. - Wenn Sie Dokumente während des Blätterns zurückmelden, fallen sie aus dem Filter `imported=false` heraus und die folgenden Seiten verschieben sich. Rufen Sie in diesem Fall immer wieder die erste Seite ab, bis `items` leer ist. ### Datensatz {#datensatz} Jedes Dokument in `items` und jede Einzelabfrage hat diese Felder: | Feld | Inhalt | |---|---| | `id` | ID des Dokuments (UUID). | | `channel` | ID des Kanals. | | `status` | Verarbeitungsstatus, siehe [Status](#status). | | `sender` | Absender, z. B. Absender der E-Mail. | | `subject` | Betreff der E-Mail oder Dateiname. | | `created_at` | Zeitpunkt des Eingangs. | | `updated_at` | Zeitpunkt der letzten Änderung. | | `created_by` | Benutzer, der das Dokument hochgeladen hat (`first_name`, `last_name`, `email`). | | `assigned_to` | Zugewiesener Benutzer. | | `assisted_by` | Benutzer, der das Dokument bearbeitet hat. | | `assisted_at` | Zeitpunkt der Bearbeitung. | | `delivered_at` | Zeitpunkt der erfolgreichen Übertragung per SFTP, AS2 oder ERP-Integration. | | `finished_at` | Zeitpunkt des Abschlusses. | | `imported_at` | Zeitpunkt, zu dem Ihr System den Import mit `SUCCEEDED` bestätigt hat. | | `email_file_url` | Link zur Original-E-Mail, falls das Dokument per E-Mail kam. | | `input_file_url` | Link zur verarbeiteten Datei. | | `input_file_name` | Ursprünglicher Dateiname. | | `classified_files` | Weitere Anhänge derselben E-Mail mit `file_name`, `classification` und `url`. | | `additional_file_urls` | Links zu zusätzlichen Dateien, falls vorhanden. | | `workbench_url` | Link zum Dokument in der Workbench. | | `external_reference` | Referenz aus der letzten Rückmeldung, z. B. Ihre Belegnummer. | | `external_status` | Status aus der letzten Rückmeldung. | | `external_message` | Nachricht aus der letzten Rückmeldung, z. B. eine Fehlermeldung. | | `data` | Die extrahierten Dokumentdaten, siehe [Dokumentdaten](#dokumentdaten). | Die Links zu Dateien sind höchstens 30 Minuten gültig. Laden Sie die Dateien direkt nach dem Abruf herunter oder rufen Sie das Dokument erneut ab, um neue Links zu erhalten. ### Status {#status} | `status` | Bedeutung | |---|---| | `PENDING` | In Verarbeitung. | | `ON_HOLD` | In der Workbench zurückgestellt. | | `ASSISTANCE_NEEDED` | Wartet auf Bearbeitung in der Workbench. | | `ASSISTED` | Bearbeitet, die Verarbeitung läuft weiter. | | `FINISHED` | Abgeschlossen. | | `DELIVERED` | Per SFTP, AS2 oder ERP-Integration übertragen. | | `IMPORTED` | Ihr System hat den Import mit `SUCCEEDED` bestätigt. | | `FAILED` | Verarbeitung oder Übergabe fehlgeschlagen, auch nach einer Rückmeldung `FAILED`. | | `REJECTED` | Die Datei konnte nicht gelesen werden. | | `DISCARDED` | Verworfen. | | `DELETED` | Gelöscht. Gelöschte Dokumente liefert die API nicht aus. | ### Dokumentdaten {#dokumentdaten} `data` enthält die Kopffelder des Dokuments und die Positionen unter `line_items` (bei Leistungsverzeichnissen unter `positions`). Die Feldnamen je Dokumenttyp zeigt die [Swagger-Oberfläche](https://api.workist.com/v1/swagger/). - Es erscheinen nur Werte der Felder, die im Kanal aktiviert sind. Alle anderen Felder sind `null`. - Solange ein Dokument weder bearbeitet noch abgeschlossen ist, ist `data` leer (`{}`). Mit `show_unfinished_data=true` erhalten Sie den aktuellen Zwischenstand. - Mengen, Preise und Datumsangaben sind Texte, so wie sie in der Workbench stehen. ## Dokument hochladen {#hochladen} `POST /{ressource}` mit `multipart/form-data`: | Feld | Pflicht | Inhalt | |---|---|---| | `channel` | Ja | ID des Kanals, in dem das Dokument verarbeitet wird. | | `file` | Ja | Die Datei. | | `user` | Nein | E-Mail-Adresse oder ID eines Benutzers, der als Ersteller eingetragen wird. | - **Kanal-ID:** Sie steht in der Adresszeile der Workbench, wenn der Kanal geöffnet ist (`…/channels/`), und im Feld `channel` jedes Dokuments dieses Kanals. Der Kanal muss zum Dokumenttyp der Ressource passen. - **Dateitypen:** BMP, CSV, DOC, DOCX, EML, HTML, JPEG, ODS, PDF, PNG, RTF, TIFF, TXT, XLS, XLSM, XLSX und XML. ZIP-Archive, Outlook-Nachrichten (MSG) und `winmail.dat` packt Workist aus und verarbeitet den Inhalt. - **Antwort:** `201` mit dem neuen Dokument. Wenn eine Datei mehrere Dokumente ergibt (z. B. eine E-Mail mit mehreren Anhängen oder ein ZIP-Archiv), enthält die Antwort nur das erste. Die übrigen finden Sie über `GET /{ressource}`. ## Import zurückmelden {#mark-imported} Mit `PUT /{ressource}/{id}/mark_imported` melden Sie, ob Ihr System das Dokument übernommen hat. Alle Felder sind optional; ohne Inhalt gilt `SUCCEEDED`. | Feld | Inhalt | |---|---| | `status` | `SUCCEEDED` (Standard): Import erfolgreich, endgültig. `FAILED`: Import abgelehnt, das Dokument geht zurück in die Workbench. `PENDING`: Übergabe noch offen. | | `external_reference` | Referenz des Dokuments in Ihrem System, z. B. die Auftragsnummer. | | `external_status` | Status des Dokuments in Ihrem System. | | `external_message` | Freitext, z. B. die Fehlermeldung Ihres Systems. | ```json { "status": "FAILED", "external_reference": "", "external_status": "rejected", "external_message": "Artikel 4711 ist gesperrt" } ``` Regeln: - Nur abgeschlossene Dokumente können zurückgemeldet werden. Sonst antwortet die API mit `400` und `Record not finished yet`. - `SUCCEEDED` ist endgültig. Eine weitere Rückmeldung zum selben Dokument lehnt die API mit `400` und `Record already successfully delivered` ab. - `PENDING` lässt das Dokument in der Abfrage `imported=false`, z. B. wenn Ihr System es angenommen, aber noch nicht gebucht hat. - Jede Rückmeldung überschreibt `external_reference`, `external_status` und `external_message` der vorherigen. ### Was nach `FAILED` passiert {#failed} 1. Das Dokument erhält den Status `FAILED` und gilt nicht mehr als abgeschlossen. Es erscheint wieder in der Liste offener Dokumente in der Workbench. 2. Beim Öffnen sehen Benutzer den Hinweis „Ihr System hat das Dokument mit der folgenden Antwort abgelehnt:" mit Referenz, Status und Nachricht aus Ihrer Rückmeldung. 3. Ein Benutzer klickt auf **Erneut assistieren**, korrigiert die Daten und schließt das Dokument ab, oder er verwirft es mit **Verwerfen**. 4. Nach dem erneuten Abschluss erscheint das Dokument wieder in `GET /{ressource}?finished=true&imported=false`, und Ihr System kann es erneut importieren. Schreiben Sie deshalb eine verständliche Ursache in `external_message`. Sie ist das, was Ihre Kolleginnen und Kollegen in der Workbench lesen. ## Weitere Operationen {#weitere} ### Absender und Betreff setzen {#meta} `PATCH /{ressource}/{id}/meta` setzt Absender und Betreff, z. B. wenn Sie Dateien aus einem eigenen Postfach hochladen. Nur mitgesendete Felder werden geändert. | Feld | Inhalt | |---|---| | `sender` | Absender, z. B. Absender der Original-E-Mail. | | `subject` | Betreff, z. B. Betreff der Original-E-Mail. | ### Benutzer zuweisen {#assign-user} `PUT /{ressource}/{id}/assign_user` mit `{"user": ""}` weist das Dokument einem Benutzer Ihrer Organisation zu. Unbekannte Benutzer lehnt die API mit `400` und `{"user": ["User does not exist."]}` ab. ### Dokument löschen {#loeschen} `DELETE /{ressource}/{id}` löscht das Dokument und antwortet mit `204`. Die API liefert das Dokument danach nicht mehr aus. ### GAEB X94 erzeugen {#gaeb-x94} Für Leistungsverzeichnisse, die als GAEB-X83-Datei eingegangen sind, erzeugt `POST /list-of-services/{id}/generate-x94` eine X94-Angebotsdatei. Sie senden Ihre Preise je Position und Ihre Lieferantendaten, Workist liefert die XML-Datei zurück. - `items` (Pflicht): eine Liste mit einem Eintrag je Position. `source_id` ist die GAEB-ID der Position und muss zu einer Position des Leistungsverzeichnisses passen. Optional: `article_number`, `article_characteristics` (`normal`, `alternate` oder `provis`), `quantity`, `unit`, `vat`, `net_price`, `price_basis`, `offer_price`, `price_basis_unit`, `ean`, `article_description`. - `supplier_info` (Pflicht): `id_no`, `tax_no`, `reg_no` und `address` mit `name1`, `street`, `p_code`, `city`, `country`. Alle Unterfelder sind optional. - **Antwort:** `200` mit der X94-Datei (`application/xml`) als Download. - **Fehler:** `400` mit `{"error": "...", "message": "..."}`, z. B. wenn das Dokument keine gültige X83-Datei ist oder eine `source_id` nicht passt. ## Fehler {#fehler} | HTTP-Status | Ursache | Antwort | |---|---|---| | `400` | Ungültige Anfrage | `{"detail": ""}` oder je Feld `{"": [""]}`, z. B. `{"channel": ["Channel does not exist"]}` oder `{"file": ["Unsupported file type"]}` | | `401` | API-Schlüssel fehlt, ist unbekannt oder abgelaufen | `{"detail": "Authentication credentials were not provided."}`, `{"detail": "Invalid token"}` oder `{"detail": "Integration has expired"}` | | `404` | Dokument nicht gefunden, Kanal nicht für den Schlüssel freigegeben, Seite außerhalb des Bereichs oder Pfad mit `/` am Ende | `{"detail": ""}` | Ein abgelaufener Schlüssel funktioniert erst wieder, wenn Sie in der Workbench das Ablaufdatum ändern oder entfernen. --- Source: https://docs.workist.com/docs/api-documentation/master-data-api.md # Benutzung der Stammdaten-API Workist benötigt die Stammdaten aus Ihrem ERP-System. Per API übermitteln Sie sie: - als CSV-Datei, - als Link zu einer öffentlich erreichbaren CSV-Datei, - als Liste von Objekten im JSON-Format, bei großen Mengen in mehreren Blöcken. Jeder Import ersetzt den gesamten Bestand der Lookup-Definition: Zeilen, die im neuen Import fehlen, löscht Workist. Senden Sie deshalb immer den vollständigen Bestand. Delta-Importe richtet Workist auf Anfrage ein. API Dokumentation (Swagger): [https://api.workist.com/v1/swagger/](https://api.workist.com/v1/swagger/) ## Grundlagen {#grundlagen} - **Basis-URL:** `https://api.workist.com/v1/master-data` - **Authentifizierung:** derselbe API-Schlüssel wie für die Dokumenten-API, im Header `Authorization: Bearer ` (siehe [Quickstart](/docs/api-documentation/quickstart.md#api-schluessel)). - **Lookup-Definition:** Jeder Import gehört zu genau einer Lookup-Definition, angegeben mit `lookup_definition_id`. Wo Sie die ID finden, steht unter [Lookup Definition IDs](#lookup-definition-ids). - **Kein Schrägstrich am Ende** der Pfade. ## Endpunkte {#endpunkte} Für jeden Stammdatentyp gibt es einen eigenen Endpunkt, der einen Import anlegt. Die Lookup-Definition muss zum Typ des Endpunkts passen. Jeder Pfad führt zur Beschreibung des Endpunkts in Swagger. | Stammdaten | Endpunkt | Lookup-Typ | Spalten | |---|---|---|---| | Artikel und kundenspezifische Artikel | [`POST /master-data/articles/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/articles_imports_create) | `ARTICLE_LOOKUP` | [Beschreibung](/docs/master-data/articles.md) | | Kunden | [`POST /master-data/clients/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/clients_imports_create) | `CLIENT_LOOKUP` | [Beschreibung](/docs/master-data/customers.md) | | Kundenkontakte | [`POST /master-data/contacts/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/contacts_imports_create) | `CONTACT_LOOKUP` | [Beschreibung](/docs/master-data/customer-contacts.md) | | Liefer- und Rechnungsempfänger | [`POST /master-data/addresses/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/addresses_imports_create) | `ADDRESS_LOOKUP` | [Beschreibung](/docs/master-data/delivery-and-invoice-recipients.md) | | Einheitenkonvertierung | [`POST /master-data/conversion-factors/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/conversion_factors_imports_create) | `CONVERSION_FACTOR_LOOKUP` | [Beschreibung](/docs/master-data/unit-conversion.md) | | Rahmenverträge | [`POST /master-data/framework-contracts/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/framework_contracts_imports_create) | `FRAMEWORK_CONTRACT_LOOKUP` | [Beschreibung](/docs/master-data/framework-agreements.md) | | Abzugleichende Bestellungen | [`POST /master-data/order-matching/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/order_matching_imports_create) | `ORDER_MATCHING_LOOKUP` | [Beschreibung](/docs/master-data/orders-to-be-matched.md) | | Angebote | [`POST /master-data/offer-matching/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/offer_matching_imports_create) | `OFFER_MATCHING_LOOKUP` | [Beschreibung](/docs/master-data/quotes.md) | Dazu kommen allgemeine Endpunkte für alle Typen: | Methode | Pfad | Zweck | |---|---|---| | `GET` | [`/master-data/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/imports_list) | Importe auflisten (seitenweise, bis 1000 pro Seite) | | `POST` | [`/master-data/imports`](https://api.workist.com/v1/swagger/#/Master%20Data/imports_create) | Import anlegen, für jeden Stammdatentyp | | `GET` | [`/master-data/imports/{import_id}`](https://api.workist.com/v1/swagger/#/Master%20Data/imports_retrieve) | Status eines Imports abrufen | | `POST` | [`/master-data/imports/{import_id}/data`](https://api.workist.com/v1/swagger/#/Master%20Data/imports_data_create) | Weiteren Datenblock an einen Batch-Import anhängen | | `POST` | [`/master-data/imports/{import_id}/start`](https://api.workist.com/v1/swagger/#/Master%20Data/imports_start_create) | Batch-Import starten | ### Anfragefelder {#anfragefelder} Ein Import enthält genau eines der Felder `file`, `file_url` oder `data`. Senden Sie die Anfrage als `multipart/form-data` oder als JSON. Bei `multipart/form-data` übergeben Sie `data` als JSON-Text. | Feld | Inhalt | |---|---| | `lookup_definition_id` | ID der Lookup-Definition (Pflicht). | | `batched` | `true`: Batch-Import anlegen, der weitere Datenblöcke annimmt. Standard: `false` (Import startet sofort). | | `file` | CSV-Datei (Dateiendung `.csv`), höchstens 10 MB. | | `file_url` | Öffentlich erreichbarer `http`/`https`-Link auf eine CSV-Datei. Der Pfad endet auf `.csv`, die Datei hat höchstens 10 MB. | | `data` | Liste von Objekten (JSON), höchstens 10.000 Zeilen. Alle Objekte brauchen dieselben Felder. | Die Feldnamen der Objekte und CSV-Spalten sind die Spaltennamen der jeweiligen Stammdatenseite (Spalte „Spalten" oben). JSON-Daten wandelt Workist in eine kommagetrennte CSV-Datei um. Haben Sie für die Lookup-Definition eine [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md) hinterlegt, z. B. Spaltenzuordnungen oder ein anderes Trennzeichen, gilt sie auch für Importe per API. ## Antwort und Import-Status {#import-status} Workist verarbeitet Importe im Hintergrund. Jeder Aufruf, der einen Import anlegt, Daten anhängt oder startet, antwortet mit `202` und der Import-ID: ```json {"import_id": "0b7c6a52-5d0e-4f43-9a8e-3c2b1d0e9f11"} ``` Der Header `Location` enthält die Adresse für den Status. Fragen Sie ihn mit `GET /master-data/imports/{import_id}` ab, bis `status` den Wert `SUCCESS`, `FAILED` oder `CANCELED` hat: ```python import time url = f"{base_url}/imports/{import_id}" while True: run = requests.request("GET", url, headers=headers).json() if run["status"] in ("SUCCESS", "FAILED", "CANCELED"): break time.sleep(60) # z. B. {"import_id": "...", "status": "SUCCESS", "lookup_type": "ARTICLE_LOOKUP", ...} ``` Die Antwort enthält: | Feld | Inhalt | |---|---| | `import_id` | ID des Imports. | | `customer_id` | ID Ihrer Organisation. | | `lookup_type` | Stammdatentyp, z. B. `ARTICLE_LOOKUP`. | | `lookup_definition` | ID der Lookup-Definition. | | `ingestion_file_url` | Speicherort der zusammengeführten Importdatei. | | `ingestion_file_num_rows` | Anzahl der importierten Zeilen. | | `error_type` | Fehlerart, falls der Import fehlgeschlagen ist. | | `error_message` | Fehlermeldung, falls der Import fehlgeschlagen ist. | | `trigger` | Auslöser, z. B. `PUBLIC_API`, `SFTP_FILE_UPLOAD` oder `WORKBENCH_FILE_UPLOAD`. | | `created_at` | Angelegt am. | | `updated_at` | Zuletzt geändert am. | | `started_at` | Verarbeitung gestartet am. | | `finished_at` | Verarbeitung beendet am. | | `status` | Status, siehe unten. | | `input_file_url` | Speicherort der ersten übermittelten Datei bzw. des ersten Datenblocks. | | `input_file_num_rows` | Zeilen in dieser Datei. | | `status` | Bedeutung | |---|---| | `PENDING` | Angelegt, noch nicht gestartet (Batch-Import wartet auf Daten oder Start). | | `RUNNING` | Wird verarbeitet. | | `SUCCESS` | Erfolgreich abgeschlossen. | | `FAILED` | Fehlgeschlagen, siehe `error_type` und `error_message`. | | `CANCELED` | Abgebrochen. | Alle Importe, auch die per API, sehen Sie außerdem im [Stammdaten-Hub](/docs/master-data/master-data-hub.md) der Workbench. ## Grenzen {#grenzen} - **Pro Anfrage:** `data` mit höchstens 10.000 Zeilen, `file` und `file_url` mit höchstens 10 MB. Größere Bestände übertragen Sie als [Batch-Import](#massen-importe). - **Pro Stunde:** Wurden für eine Lookup-Definition in der letzten Stunde mehr als 12 Importe angelegt, lehnt die API weitere mit `400` ab (`Too many imports scheduled for this lookup definition recently`). Importe aus allen Quellen zählen mit, auch Uploads per SFTP. Ein SFTP-Upload über der Grenze wird ohne Meldung übersprungen. - **`file_url`:** nur `http` und `https`. Adressen, die auf interne oder private Netze zeigen, lehnt die API ab. Workist lädt die Datei während der Anfrage herunter. ## Batch-Importe {#massen-importe} Für Bestände über 10.000 Zeilen oder 10 MB legen Sie einen Batch-Import an und übertragen die Daten in Blöcken: 1. Batch-Import mit `"batched": true` anlegen, z. B. über `POST /master-data/articles/imports`. Die Antwort enthält die `import_id`. 2. Datenblöcke anhängen mit `POST /master-data/imports/{import_id}/data`, so oft wie nötig. CSV-Blöcke brauchen alle dieselbe Kopfzeile. 3. Import starten mit `POST /master-data/imports/{import_id}/start`. Danach nimmt der Import keine Daten mehr an. ```python import requests import json def chunk(it, size): from itertools import islice it = iter(it) return iter(lambda: tuple(islice(it, size)), ()) base_url = "https://api.workist.com/v1/master-data" lookup_definition_id = "
" token = "" headers = {"Authorization": f"Bearer {token}"} articles = [ {"article_id1": "123", "description": "abc", "order_units": ["PCS", "KG"]}, {"article_id1": "456", "description": "def", "order_units": ["KG"]}, {"article_id1": "789", "description": "def", "order_units": ["M"]} ] articles_chunked = list(chunk(articles, 10000)) url = f"{base_url}/articles/imports" response = requests.request("POST", url, headers=headers, data={ "lookup_definition_id": lookup_definition_id, "batched": True, }) import_id = response.json().get("import_id") for articles_batch in articles_chunked: url = f"{base_url}/imports/{import_id}/data" response = requests.request("POST", url, headers=headers, data={"data": json.dumps(articles_batch)}) url = f"{base_url}/imports/{import_id}/start" response = requests.request("POST", url, headers=headers) ``` ## Kunden {#kunden} ```python clients = [ {"client_id1": "C-001", "company_name": "Test SE", "address1": "Test street 1", ...}, {"client_id1": "C-002", "company_name": "Muster GmbH&Co. KG", ...} ] url = f"{base_url}/clients/imports" payload = {"lookup_definition_id": "", "data": json.dumps(clients)} response = requests.request("POST", url, headers=headers, data=payload) ``` ## Lieferadressen {#lieferadressen} Verknüpfung mit Kunden über `partition_id`. Das Feld für die Lieferadresse sollte ausschließlich Firmennamen enthalten. ```python delivery_addresses = [ {"partition_id": "C-001", "address_id1": "L-001", "name": "Tester 2 GmbH", "address1": "Test street 2", ...} ] url = f"{base_url}/addresses/imports" payload = {"lookup_definition_id": "", "data": json.dumps(delivery_addresses)} response = requests.request("POST", url, headers=headers, data=payload) ``` ## Artikel {#artikel} `order_units` muss als Array übermittelt werden (z. B. `["KG", "STK"]`). ```python articles = [ {"article_id1": "ART-001", "description": "Sensor Module", "order_units": ["PCE", "KG"]}, ] url = f"{base_url}/articles/imports" payload = {"lookup_definition_id": "", "data": json.dumps(articles)} response = requests.request("POST", url, headers=headers, data=payload) ``` ## Kundenspezifische Artikel {#kundenspezifische-artikel} Jeder Eintrag braucht `partition_id` (Kundenverweis) und `article_id1` (interner Artikel). `article_id2` enthält die Kundenartikelnummer. ```python client_articles = [ {"partition_id": "C-001", "article_id1": "ART-001", "article_id2": "CUST-ART-555"}, ] url = f"{base_url}/articles/imports" payload = {"lookup_definition_id": "", "data": json.dumps(client_articles)} response = requests.request("POST", url, headers=headers, data=payload) ``` ## Fehler {#fehler} | HTTP-Status | Ursache | Antwort | |---|---|---| | `400` | Ungültige Anfrage, z. B. fehlende `lookup_definition_id`, Datei keine CSV-Datei, zu viele Zeilen, Lookup-Definition passt nicht zum Endpunkt, Import nicht mehr im Status `PENDING`, zu viele Importe pro Stunde | `{"detail": ""}` oder `[""]` | | `401` | API-Schlüssel fehlt | `{"detail": "Authentication credentials were not provided or invalid."}` | | `503` | Die Anfrage hat länger als 30 Sekunden gedauert | `{"detail": "Please try again later"}` | ## Postman Collection {#postman-collection} Eine Postman Collection für die Stammdaten-API ist auf Anfrage verfügbar. Wenden Sie sich an Ihren Workist-Ansprechpartner oder an [support@workist.com](mailto:support@workist.com). ## Lookup Definition IDs {#lookup-definition-ids} Lookup-Definitionen legen Benutzer mit der Rolle Manager, IT oder Admin im [Stammdaten-Hub](/docs/master-data/master-data-hub.md) an. Die ID finden Sie an zwei Stellen: - im Stammdaten-Hub: in der Übersicht in der Spalte ID und auf der Detailseite der Lookup-Definition, - im Kanal unter **Kanal verwalten** → **Stammdaten**, unter der jeweils ausgewählten Lookup-Definition. Weitere Details: [Lookup-IDs abrufen](/docs/data-exchange/api.md#lookup-ids) --- Source: https://docs.workist.com/docs/output-formats.md # Ausgabeformate Workist erzeugt für jedes abgeschlossene Dokument eine Ausgabedatei und überträgt sie an Ihr System. Welches Format Ihr Kanal verwendet, legt Workist bei der Einrichtung mit Ihnen fest. Die Unterseiten zeigen für jedes Standardformat ein Beispiel und beschreiben jedes Element, das Workist schreibt. Die Beispiele wurden mit den Workist-Serialisierern erzeugt und zur Lesbarkeit eingerückt; die gelieferten Dateien sind standardmäßig nicht eingerückt. ## Verfügbare Formate | Dokumenttyp | Standardformate | |-------------|-----------------| | [Bestellungen](/docs/output-formats/orders.md) | Workist XML (Standard), SAP IDoc ORDERS05, openTRANS 2.1, cXML OrderRequest, ANSI X12 850 | | [Anfragen](/docs/output-formats/requests-for-quotation.md) | Workist XML (Standard), SAP IDoc (Nachrichtentyp REQOTE), openTRANS 2.1 | | [Rechnungen](/docs/output-formats/invoices.md) | Workist XML | | [Lieferscheine](/docs/output-formats/delivery-notes.md) | openTRANS 2.1 | | [Auftragsbestätigungen](/docs/output-formats/order-confirmations.md) | openTRANS 2.1 | | [Leistungsverzeichnisse](/docs/output-formats/list-of-services.md) | SAP IDoc BOMMAT07 (Standard), GAEB DA XML X94 über die API | Alle Dokumenttypen können Sie außerdem über die [Dokument-API](/docs/api-documentation/document-api.md) als JSON abrufen. Andere Formate baut Workist auf Anfrage, siehe [Individuelle Formate auf Anfrage](#custom-formats). ## Welche Felder in der Datei stehen {#fields-in-the-file} - **Workist XML** (Bestellungen, Anfragen, Rechnungen): Die Datei enthält die Kopf- und Positionsfelder, die in Ihrem Kanal konfiguriert sind, sowie die Felder unter **Zusätzliche Kopfzeilendatenfelder** und **Zusätzliche Positionszeilenfelder** in der [Ausgabedatei-Konfiguration](/docs/channel-configuration/exported-documents.md). Steht dort ein Feldname, den das Format nicht kennt, erzeugt Workist keine Datei. Bei Bestellungen und Anfragen lässt Workist leere Felder weg, bei Rechnungen schreibt es jedes konfigurierte Feld, auch wenn es leer ist. - **Alle anderen Formate** (SAP IDoc, openTRANS, cXML, X12) haben eine feste Struktur. Die Feldauswahl Ihres Kanals ändert sie nicht. Einzige Ausnahme: Das SAP IDoc für Bestellungen und Anfragen enthält den Rechnungsempfänger nur, wenn die Rechnungsadresse zu den Kopffeldern gehört. ### Optionen in der Ausgabedatei-Konfiguration {#options} | Option | Wirkung | Gilt für | |---|---|---| | **Verweis auf die analysierte Datei einfügen** (standardmäßig aktiv) | Schreibt den Dateinamen des mitgelieferten Originaldokuments in die Datei (`External_Document_Link` bzw. `MIME_INFO`) | Workist XML für Bestellungen und Anfragen, openTRANS für Auftragsbestätigungen | | **Link zur Workbench einfügen** | Schreibt einen Link zum Dokument in der Workbench (`Workist_URL` bzw. `ALT_CUSTOMER_ORDER_ID`) | Workist XML für Bestellungen und Anfragen, openTRANS für Auftragsbestätigungen | | **E-Mail-Absenderinformationen einfügen** | Schreibt die Absenderadresse der E-Mail, mit der das Dokument eingegangen ist (`Received_By`) | Workist XML für Bestellungen und Anfragen | | **Kurzen externen Dateinamen verwenden** | Verwendet eine kurze ID statt einer UUID im Dateinamen | Workist XML für Bestellungen und Anfragen, openTRANS für Lieferscheine und Auftragsbestätigungen | | **Position überschreiben** | Verwendet die Positionsnummer der zugeordneten Bestellposition | openTRANS für Auftragsbestätigungen | In allen anderen Formaten haben diese Optionen keine Wirkung. ## Dateinamen {#file-names} | Format | Dateiname | |---|---| | Workist XML (Bestellungen, Anfragen), openTRANS (Lieferscheine, Auftragsbestätigungen) | `.xml`; `` ist eine UUID oder mit **Kurzen externen Dateinamen verwenden** eine kurze ID | | Workist XML (Rechnungen), openTRANS (Bestellungen, Anfragen), cXML | `.xml` | | SAP IDoc ORDERS05 | `.xml` (16-stellig, fortlaufend) | | SAP IDoc BOMMAT07 | `BOM_.xml` | | ANSI X12 850 | `__.edi` in Kleinbuchstaben, z. B. `cust-12345_po-2025-0001_9f8c2b7e-4d1a-4c3e-9b6f-2a7d5e1c0b34.edi`; ohne Kunden- oder Bestellnummer nur `.edi` | Ist in der Upload-Konfiguration **Originaldokument hochladen** aktiv (Standard), überträgt Workist das Originaldokument mit demselben Namen wie die Ausgabedatei, in der Regel als `.pdf`. Mit **Originale E-Mail hochladen** legt Workist bei SFTP zusätzlich die E-Mail als `.eml` ab. Mit **Zusätzliche Dateien** übertragene Anhänge heißen `_file_.`. ## Datums- und Zahlenformate {#number-formats} | Format | Datum | Dezimalzahlen | |---|---|---| | Workist XML | `JJJJ-MM-TT` | Ohne Tausendertrennzeichen und ohne abschließende Nullen. Standardmäßig mit Dezimalkomma (`1487,5`); auf Wunsch stellt Workist Ihren Kanal auf Dezimalpunkt um (`1487.5`). | | openTRANS | `JJJJ-MM-TT` | Mit Dezimalpunkt (`12.5`) | | cXML | `JJJJ-MM-TT` mit Uhrzeit `T00:00:00+00:00` | Mit Dezimalpunkt (`12.5`) | | SAP IDoc, ANSI X12 | `JJJJMMTT` | – | Einzelne Felder weichen davon ab; die Feldtabellen der Formate nennen das. ## Wann keine Datei entsteht {#required-values} Fehlen bestimmte Werte, kann Workist die Datei nicht erzeugen: | Format | Pflichtangaben | |---|---| | Workist XML | Nur Feldnamen, die das Format kennt, in der Ausgabedatei-Konfiguration | | SAP IDoc ORDERS05 (Bestellungen, Anfragen) | Bestell- bzw. Anfragedatum und Liefertermin | | cXML, openTRANS (Anfragen, Lieferscheine, Auftragsbestätigungen) | Eine Menge je Position, die sich als Zahl lesen lässt | ## Individuelle Formate auf Anfrage {#custom-formats} Braucht Ihr System ein Format, das hier nicht als Standard aufgeführt ist, baut Workist es nach Ihrer Spezifikation. Das gilt zum Beispiel für: - EDIFACT (z. B. ORDERS in der Version, die Ihr System erwartet) - EDX - proALPHA (PAI, pAX) - Excel - eigene Layouts in JSON, CSV, TXT (mit frei wählbarem Trennzeichen) oder XLSX für Bestellungen und Leistungsverzeichnisse, mit frei zugeordneten Feldern, z. B. eine Zeile je Position Aufbau, Feldbelegung und Dateinamen stimmen Sie mit Ihrer Ansprechperson bei Workist ab. Auch die Standardformate kann Workist um Felder oder Logik erweitern. --- Source: https://docs.workist.com/docs/output-formats/orders.md # Bestellungen (Orders) Für Bestellungen gibt es diese Standardformate: [Workist XML](#workist-xml) (Standard), [SAP IDoc ORDERS05](#sap-idoc), [openTRANS 2.1](#opentrans), [cXML OrderRequest](#cxml) und [ANSI X12 850](#x12). Formate wie EDIFACT, EDX, proALPHA oder Excel baut Workist auf Anfrage, siehe [Individuelle Formate auf Anfrage](/docs/output-formats.md#custom-formats). Alle Beispiele auf dieser Seite wurden mit den Workist-Serialisierern aus denselben Beispieldaten erzeugt. Allgemeine Regeln zu Dateinamen, Datums- und Zahlenformaten finden Sie in der [Übersicht](/docs/output-formats.md). --- ## Workist XML {#workist-xml} **Dateiendung:** `.xml` **Dateiname:** `.xml` Das Standardformat für Bestellungen. Die Datei hat vier Bereiche: - `General`: Kopfdaten der Bestellung - `Invoicing`: Rechnungsadresse - `Shipping`: Lieferadresse und Liefertermine - `Line`: ein Element je Position Welche Elemente erscheinen, hängt von den Kopf- und Positionsfeldern Ihres Kanals ab. Leere Felder lässt Workist weg. Datumsangaben haben das Format `JJJJ-MM-TT`. Dezimalzahlen stehen standardmäßig mit Dezimalkomma und ohne abschließende Nullen in der Datei (`1487,5`). ### Vollständiges Beispiel ```xml CUST-12345 Acme Corporation CP-001 Max Mustermann max@acme.de +49 89 12345678 DE BY regular CP-007 Erika Versand shipping@acme.de +49 89 12345679 2025-03-15 DE123456789 PO-2025-0001 QT-2025-100 PRJ-500 10 standard DDP express net 30 1250 1487,5 FC-2025-200 08:00-16:00 Please deliver to loading dock B. Handle with care - fragile items, do not stack pallets. COM-999 DAP forklift 9f8c2b7e-4d1a-4c3e-9b6f-2a7d5e1c0b34.pdf https://wb.workist.com/orders/3f2b8c1e-5a7d-4e19-8c2f-6b0d9a4e7c15 max@acme.de false 9f8c2b7e-4d1a-4c3e-9b6f-2a7d5e1c0b34_file_1.pdf DELIVERY_NOTE delivery-schedule.pdf BILL-001 Accounts Payable Acme Corporation GmbH
Billing Strasse 10
Building C, 3rd Floor Munich 80331 DE BY +49 89 11111111 billing@acme.de SHIP-002 Warehouse Team Acme Corporation GmbH
Lager Strasse 5
Gate 3 Hamburg 20095 DE HH +49 40 22222222 warehouse@acme.de 2025-04-01 2025-04-05 08:00 16:00 2025-03-28 LOT-2025-A Industrial Sensor Module Type A PCE 100 12,5 1 1250 5 62,5 blue ART-001-A ART-001-A-ALT 4006381333931 CUST-ART-555 0,95 2025-04-01 08:00 12:00 2025-03-28 COM-LINE-01 1000 10 FC-2025-200 QT-2025-100 10 box SUB-ORD-001 CUST-67890 Acme Branch North Acme Branch North
Nordring 7
Hamburg 22303 DE EUR Pack individually A1 B2 ``` ### Allgemeine Felder (`General`) {#general-fields} | Element | Typ | Beschreibung | |---|---|---| | `Sell_to_Customer` | Block | Bestellender Kunde, gefüllt aus Ihren Kundenstammdaten | | `Sell_to_Customer/Customer_Number` | Text | Kundennummer | | `Sell_to_Customer/Name` | Text | Kundenname | | `Sell_to_Customer/Contact_Number` | Text | Nummer des Ansprechpartners beim Kunden | | `Sell_to_Customer/Contact` | Text | Name des Ansprechpartners | | `Sell_to_Customer/Contact_Email` | Text | E-Mail-Adresse des Ansprechpartners | | `Sell_to_Customer/Contact_Phone` | Text | Telefonnummer des Ansprechpartners | | `Sell_to_Customer/Country` | Text | Ländercode der Kundenadresse (z. B. `DE`) | | `Sell_to_Customer/Country_Subdivision` | Text | Bundesland- oder Regionscode der Kundenadresse (z. B. `BY`) | | `Sell_to_Customer/Customer_Type` | Text | Kundentyp aus Ihren Stammdaten | | `Dispatch_Contact` | Block | Versandkontakt beim Kunden. Nur vorhanden, wenn mindestens ein Wert erfasst ist | | `Dispatch_Contact/Contact_Number` | Text | Nummer des Versandkontakts | | `Dispatch_Contact/Contact` | Text | Name des Versandkontakts | | `Dispatch_Contact/Contact_Email` | Text | E-Mail-Adresse des Versandkontakts | | `Dispatch_Contact/Contact_Phone` | Text | Telefonnummer des Versandkontakts | | `Order_Date` | Datum | Bestelldatum | | `VAT_Registration_Number` | Text | USt-IdNr. des Kunden | | `Customer_Order_Number` | Text | Bestellnummer des Kunden | | `Quote_Reference_Number` | Text | Nummer des Angebots, auf das sich die Bestellung bezieht | | `Project_Number` | Text | Projektnummer | | `Distribution_Channel` | Text | Vertriebsweg bzw. Vertriebsorganisation | | `Order_Type` | Text | Auftragsart | | `Delivery_Terms` | Text | Lieferbedingungen | | `Shipping_Terms` | Text | Versandbedingungen | | `Payment_Terms` | Text | Zahlungsbedingungen | | `Total_Amount_Net` | Dezimal | Nettogesamtbetrag | | `Total_Amount` | Dezimal | Bruttogesamtbetrag | | `Framework_Contract_Number` | Text | Rahmenvertragsnummer | | `Goods_Receiving_Time` | Text | Warenannahmezeiten, wie auf der Bestellung angegeben | | `Info_Text` | Text | Freitext. Workist teilt ihn in Abschnitte zu 70 Zeichen auf, ein Element je Abschnitt, höchstens 5 Elemente; der Rest entfällt | | `Commission_Number` | Text | Kommissionsnummer | | `Incoterm` | Text | Incoterm (z. B. `DAP`) | | `Delivery_Unload_Method` | Text | Entladeart am Lieferort | | `External_Document_Link` | Text | Dateiname des Originaldokuments, das Workist zusammen mit der XML-Datei überträgt (`.pdf`). Kein Link | | `Workist_URL` | Text | Link zum Dokument in der Workbench | | `Received_By` | Text | Absenderadresse (*Von*) der E-Mail, mit der das Dokument bei Workist eingegangen ist | | `ERP_Locked` | Boolean | `true`, wenn ein Bearbeiter die Bestellung in der Workbench als für die Weiterverarbeitung gesperrt markiert hat, sonst `false` | | `Additional_Files` | Block | Weitere Anhänge derselben E-Mail, die Workist zusammen mit der Bestellung überträgt. Nur vorhanden, wenn zusätzliche Dateien aktiviert sind und passende Anhänge existieren | | `Additional_Files/Additional_File` | Block | Ein Element je Datei | | `Additional_Files/Additional_File/File_Name` | Text | Dateiname, unter dem Workist die Datei überträgt (`_file_.`) | | `Additional_Files/Additional_File/Classification` | Text | Dokumentart des Anhangs: `ORDER`, `ORDER_CONFIRMATION`, `REQUEST_FOR_QUOTATION`, `INVOICE`, `DELIVERY_NOTE`, `OFFER` oder `OTHER` | | `Additional_Files/Additional_File/File_Name_Original` | Text | Ursprünglicher Dateiname des Anhangs | ### Rechnungsadresse, Lieferadresse und Liefertermine `Invoicing` und `Shipping` erscheinen nur, wenn mindestens ein enthaltenes Feld gefüllt ist. | Element | Typ | Beschreibung | |---|---|---| | `Invoicing/Bill_to_Customer` | Block | Rechnungsadresse; Felder siehe [Adressfelder](#address-fields) | | `Shipping/Ship_to_Customer` | Block | Lieferadresse; Felder siehe [Adressfelder](#address-fields) | | `Shipping/Expected_Delivery_Date` | Datum | Gewünschter Liefertermin | | `Shipping/Expected_Delivery_End_Date` | Datum | Ende des Lieferzeitraums | | `Shipping/Expected_Delivery_Time_From` | Text | Beginn des Lieferzeitfensters (`HH:MM`) | | `Shipping/Expected_Delivery_Time_Until` | Text | Ende des Lieferzeitfensters (`HH:MM`) | | `Shipping/Goods_Issue_Date` | Datum | Warenausgangsdatum | ### Adressfelder {#address-fields} `Bill_to_Customer`, `Ship_to_Customer` und `Customer_Address` (bei Sammelbestellungen in `Line`) haben dieselbe Struktur. Ein Adressblock erscheint nur, wenn Name, Firma, Straße oder Ort erfasst sind. | Element | Typ | Beschreibung | |---|---|---| | `Code` | Text | Adressnummer aus Ihren Stammdaten | | `Name` | Text | Name des Empfängers; der Firmenname, wenn kein Name erfasst ist | | `Additional_Name_Info` | Text | Firmenname; nur vorhanden, wenn zusätzlich ein Name erfasst ist | | `Address` | Text | Straße und Hausnummer. Immer vorhanden, ggf. leer | | `Additional_Address_Info` | Text | Adresszusatz (z. B. Gebäude, Tor) | | `City` | Text | Ort. Immer vorhanden, ggf. leer | | `Post_Code` | Text | Postleitzahl. Immer vorhanden, ggf. leer | | `Country` | Text | Ländercode (z. B. `DE`). Immer vorhanden, ggf. leer | | `Country_Subdivision` | Text | Bundesland- oder Regionscode (z. B. `BY`) | | `Phone` | Text | Telefonnummer | | `Email` | Text | E-Mail-Adresse | ### Positionsfelder (`Line`) {#line-fields} Workist schreibt ein `Line`-Element je Position, sofern mindestens ein Positionsfeld konfiguriert ist. Die Artikelnummern stammen aus Ihren [Artikelstammdaten](/docs/master-data/articles.md). | Element | Typ | Beschreibung | |---|---|---| | `Batch_Number` | Text | Chargennummer | | `Description` | Text | Artikelbeschreibung | | `Unit_of_Measure` | Text | Mengeneinheit | | `Quantity` | Dezimal | Bestellmenge | | `Unit_Price` | Dezimal | Einzelpreis | | `Price_Unit` | Dezimal | Preiseinheit: Anzahl Einheiten, auf die sich der Einzelpreis bezieht (z. B. `1` oder `100`) | | `Total_Price` | Dezimal | Positionsgesamtpreis | | `Line_Discount_Percent` | Text | Rabatt in Prozent, so übernommen, wie in Workist erfasst | | `Line_Discount_Amount` | Text | Rabattbetrag, so übernommen, wie in Workist erfasst | | `Item_Variant` | Text | Artikelvariante | | `Common_Item_Number` | Text | Ihre Artikelnummer (`article_id1` aus Ihren Artikelstammdaten) | | `Common_Item_Number_2` | Text | Zweite Artikelnummer (`article_id2`) | | `Common_Item_Number_3` | Text | Dritte Artikelnummer (`article_id3`, z. B. EAN) | | `Customer_Item_Number` | Text | Artikelnummer des Kunden | | `Item_Number_Confidence` | Dezimal | Sicherheit der automatischen Artikelzuordnung zwischen 0 und 1, immer mit Dezimalkomma (z. B. `0,95`) | | `Expected_Delivery_Date` | Datum | Liefertermin der Position | | `Expected_Delivery_Time_From` | Text | Beginn des Lieferzeitfensters der Position (`HH:MM`) | | `Expected_Delivery_Time_Until` | Text | Ende des Lieferzeitfensters der Position (`HH:MM`) | | `Goods_Issue_Date` | Datum | Warenausgangsdatum der Position | | `Commission_Number` | Text | Kommissionsnummer der Position | | `Sales_Organisation` | Text | Verkaufsorganisation | | `Pos` | Text | Positionsnummer | | `Framework_Contract_Number` | Text | Rahmenvertragsnummer der Position | | `Quote_Reference_Number` | Text | Angebotsnummer der Position | | `Container_Quantity` | Text | Umgerechnete Menge (z. B. in Gebinden), so übernommen, wie in Workist erfasst | | `Container_Type` | Text | Umgerechnete Einheit (z. B. `box`) | | `Order_Number` | Text | Bestellnummer der Position (z. B. bei Sammelbestellungen) | | `Sell_to_Customer` | Block | Kunde dieser Position bei Sammelbestellungen | | `Sell_to_Customer/Customer_Number` | Text | Kundennummer | | `Sell_to_Customer/Name` | Text | Kundenname | | `Sell_to_Customer/Customer_Address` | Block | Adresse dieses Kunden; Felder siehe [Adressfelder](#address-fields) | | `Currency` | Text | Währung der Position (z. B. `EUR`) | | `Article_Comments` | Text | Bemerkung zur Position | | `Article_Markings` | Text | Markierung der Position; ein Element je Markierung | ### Optionale Elemente Einige Elemente schalten Sie in der Kanal-Konfiguration ein (siehe [Exportierte verarbeitete Dokumente](/docs/channel-configuration/exported-documents.md)): - `External_Document_Link`: **Verweis auf die analysierte Datei einfügen** (standardmäßig aktiv). Das Element enthält den Dateinamen des Originaldokuments, das Workist neben der XML-Datei ablegt. - `Workist_URL`: **Link zur Workbench einfügen**. - `Received_By`: **E-Mail-Absenderinformationen einfügen**. Ist das Dokument nicht per E-Mail eingegangen, fehlt das Element. - `ERP_Locked`: Tragen Sie `erp_locked` unter **Zusätzliche Kopfzeilendatenfelder** ein. Bearbeiter können eine Bestellung dann in der Workbench mit **Für die Weiterverarbeitung als gesperrt markieren** kennzeichnen. - `Additional_Files`: Aktivieren Sie in der Upload-Konfiguration **Zusätzliche Dateien** und wählen Sie unter **Zusätzliche Dateitypen** die Dokumentarten. Workist überträgt dann passende Anhänge derselben E-Mail zusammen mit der Bestellung und listet sie hier auf. --- ## SAP IDoc ORDERS05 {#sap-idoc} **Dateiendung:** `.xml` **Dateiname:** `.xml` Das IDoc-Format für die direkte Übernahme in SAP. Es besteht aus einem Kontrollsatz (`EDI_DC40`) und Datensegmenten für Kopf, Termine, Partner und Positionen. Dasselbe Format gibt es für [Anfragen](/docs/output-formats/requests-for-quotation.md#sap-idoc) mit dem Nachrichtentyp `REQOTE`. ### Vollständiges Beispiel In diesem Beispiel haben Liefer- und Rechnungsadresse eine Adressnummer, deshalb bleiben ihre Adressfelder leer. ```xml EDI_DC40 050 0000000000004711 30 2 ORDERS05 ORDERS 0 ORDERS WORKIST LS WORKIST XML_WKI LS SUPPLIER 20250315 143025 000 PO-2025-0001 SUPPLIER 012 20250315 002 20250401 AG CUST-12345 Z1 CP-001 Max Mustermann +49 89 12345678 max@acme.de WE SHIP-002 RE BILL-001 001 PO-2025-0001 20250315 0 001 100 PCE 002 20250401 000000 002 ART-001-A ``` ### Segmente | Element | Inhalt | |---|---| | `EDI_DC40` | Kontrollsatz. `TABNAM`, `STATUS` (`30`), `DIRECT` (`2`), `IDOCTYP` (`ORDERS05`), `STD` (`0`), `MESTYP` und `STDMES` (`ORDERS`) sind fest. `DOCNUM` ist eine fortlaufende 16-stellige IDoc-Nummer, `CREDAT`/`CRETIM` der Erstellungszeitpunkt (UTC). `MANDT`, `SNDPOR`, `SNDPRT`, `SNDPRN`, `RCVPOR`, `RCVPRT` und `RCVPRN` stellt Workist für Sie ein (siehe unten). | | `E1EDK01` | Belegkopf: `ACTION` = `000`, `BELNR` = Bestellnummer des Kunden (max. 35 Zeichen), `RECIPNT_NO` = Empfängernummer (einstellbar, max. 10). | | `E1EDK03` (`IDDAT` = `012`) | `IDDAT` = `012`, `DATUM` = Bestelldatum (`JJJJMMTT`). Pflichtangabe. | | `E1EDK03` (`IDDAT` = `002`) | `IDDAT` = `002`, `DATUM` = gewünschter Liefertermin (`JJJJMMTT`). Pflichtangabe. | | `E1EDKA1` (`PARVW` = `AG`) | Auftraggeber: `PARVW` = `AG`, `PARTN` = Kundennummer (max. 17 Zeichen). | | `E1EDKA1` (`PARVW` = `Z1`) | Ansprechpartner: `PARVW` = `Z1`, `PARTN` = Nummer (max. 30), `NAME1` = Name (max. 35), `TELF1` = Telefon (max. 25), `TELBX` = E-Mail-Adresse (max. 25, längere Adressen werden abgeschnitten). Nur vorhanden, wenn mindestens ein Wert erfasst ist. | | `E1EDKA1` (`PARVW` = `WE`) | Warenempfänger, immer vorhanden: `PARVW` = `WE`, `PARTN` = Adressnummer der Lieferadresse. `NAME1` = Firma, `NAME2` = Name, `STRAS` = Straße, `ORT01` = Ort (je max. 35 Zeichen), `PSTLZ` = Postleitzahl (max. 9), `LAND1` = Ländercode (max. 3). Ist eine Adressnummer vorhanden, bleiben diese Felder leer. | | `E1EDKA1` (`PARVW` = `RE`) | Rechnungsempfänger: `PARVW` = `RE`, `PARTN` = Adressnummer der Rechnungsadresse. `NAME1` = Firma, `NAME2` = Name, `STRAS` = Straße, `ORT01` = Ort (je max. 35 Zeichen), `PSTLZ` = Postleitzahl (max. 9), `LAND1` = Ländercode (max. 3). Ist eine Adressnummer vorhanden, bleiben diese Felder leer. Nur vorhanden, wenn die Rechnungsadresse zu den Kopffeldern Ihres Kanals gehört. | | `E1EDK02` (`QUALF` = `001`) | `QUALF` = `001`, `BELNR` = Bestellnummer, `DATUM` = Bestelldatum. | | `E1EDP01` | Eine je Position: `POSEX` = laufende Nummer ab `0` (nicht die Positionsnummer der Bestellung), `ACTION` = `001`, `MENGE` = Menge (max. 15 Zeichen), `MENEE` = Mengeneinheit, wie in Workist erfasst. | | `E1EDP03` (`IDDAT` = `002`) | Liefertermin der Position: `IDDAT` = `002`, `DATUM` (`JJJJMMTT`), `UZEIT` = `000000`. Nur, wenn die Position einen Liefertermin hat. | | `E1EDP19` (`QUALF` = `002`) | `QUALF` = `002`, `IDTNR` = Ihre Artikelnummer (max. 35 Zeichen). | ### Einstellungen Diese Werte stellt Workist bei der Einrichtung passend zu Ihrem SAP-System ein. Längere Werte werden abgeschnitten. | Feld | Standard | Max. Zeichen | |---|---|---| | `MANDT` | `050` | – | | `SNDPOR` | `WORKIST` | 10 | | `SNDPRT` | `LS` | 2 | | `SNDPRN` | `WORKIST` | 10 | | `RCVPOR` | `XML_WKI` | 10 | | `RCVPRT` | `LS` | 2 | | `RCVPRN` | `SUPPLIER` | 10 | | `RECIPNT_NO` | `SUPPLIER` | 10 | ### Hinweise - Bestelldatum und Liefertermin sind Pflicht. Fehlt einer der beiden Werte, erzeugt Workist keine Datei. - Je Position überträgt das IDoc nur Menge, Einheit, Liefertermin und Ihre Artikelnummer. Preise, Artikelbeschreibung und die Artikelnummer des Kunden sind nicht enthalten. - Die Mengeneinheit überträgt Workist so, wie sie in Workist erfasst ist, ohne Umschlüsselung auf ISO-Codes. - Die Feldauswahl Ihres Kanals ändert den Aufbau nicht. Einzige Ausnahme ist der Rechnungsempfänger (`RE`). --- ## openTRANS 2.1 {#opentrans} **Dateiendung:** `.xml` **Dateiname:** `.xml` Bestellung im openTRANS-2.1-Format (`ORDER`). Geschäftspartner stehen im Abschnitt `PARTIES` und werden über ihre `PARTY_ID` referenziert. ### Vollständiges Beispiel In diesem Beispiel ist für die Position eine umgerechnete Menge (10 `box`) erfasst, deshalb stehen in `QUANTITY` und `ORDER_UNIT` die umgerechneten Werte. ```xml Workist 2025-03-15T14:30:25.123456 QT-2025-100 PRJ-500 2025-03-15T14:30:25.123456 PO-2025-0001 2025-03-15 2025-04-01 2025-04-05 workist document_creator supplier supplier CUST-12345 buyer
Acme Corporation CP-001 Mustermann Max +49 89 12345678 max@acme.de Hauptstrasse 42 80331 Munich DE BY
SHIP-002 delivery
Acme Corporation GmbH Warehouse Team Gate 3 Lager Strasse 5 20095 Hamburg DE HH +49 40 22222222
BILL-001 invoice_recipient
Acme Corporation GmbH Accounts Payable Billing Strasse 10 80331 Munich DE BY +49 89 11111111
CUST-12345 supplier BILL-001 SHIP-002 EUR 10 ART-001-A CUST-ART-555 Industrial Sensor Module Type A 10 BOX 2025-04-01 2025-04-01 1 ``` ### Elemente | Element | Inhalt | |---|---| | `CONTROL_INFO` | `GENERATOR_INFO` = `Workist`, `GENERATION_DATE` = Erstellungszeitpunkt (UTC). | | `SOURCING_INFO` | Nur, wenn eine Angebots- oder Projektnummer erfasst ist: `QUOTATION_ID` = Angebotsnummer, `AGREEMENT_ID` = Projektnummer, `AGREEMENT_END_DATE` = Erstellungszeitpunkt (Pflichtangabe des Standards ohne fachliche Bedeutung). | | `ORDER_INFO` | `ORDER_ID` = Bestellnummer, `ORDER_DATE` = Bestelldatum, `CURRENCY` = immer `EUR`. | | `DELIVERY_DATE` | Nur mit Liefertermin: `DELIVERY_START_DATE` = Liefertermin, `DELIVERY_END_DATE` = Ende des Lieferzeitraums (sonst der Liefertermin). | | `PARTY` `document_creator` | Workist als Ersteller: `PARTY_ID` = `workist` (`type` = `party_specific`), `PARTY_ROLE` = `document_creator`. | | `PARTY` `supplier` | Sie als Lieferant, fester Platzhalter: `PARTY_ID` = `supplier` (`type` = `party_specific`), `PARTY_ROLE` = `supplier`. | | `PARTY` `buyer` | Bestellender Kunde: `PARTY_ID` = Kundennummer, `PARTY_ROLE` = `buyer`. Adresse: `NAME` = Name aus der Kundenadresse, `STREET`, `ZIP`, `CITY` (max. 35 Zeichen), `COUNTRY_CODED`, `COUNTRY_SUBDIVISION`. `CONTACT_DETAILS`, wenn ein Ansprechpartner erfasst ist: `CONTACT_ID`, `FIRST_NAME` = erstes Wort des Namens, `CONTACT_NAME` = restlicher Name, `PHONE`, `EMAIL`. | | `PARTY` `delivery` | Lieferadresse, wenn Firma, Name oder Adressnummer erfasst sind: `PARTY_ID` = Adressnummer, `PARTY_ROLE` = `delivery`; `NAME` = Firma, `NAME2` = Name, `NAME3` = Adresszusatz, `STREET`, `ZIP`, `CITY` (max. 35 Zeichen), `COUNTRY_CODED`, `COUNTRY_SUBDIVISION`, `PHONE`. | | `PARTY` `invoice_recipient` | Rechnungsadresse, wenn Firma, Name oder Adressnummer erfasst sind: `PARTY_ID` = Adressnummer, `PARTY_ROLE` = `invoice_recipient`; `NAME` = Firma, `NAME2` = Name, `STREET`, `ZIP`, `CITY` (max. 35 Zeichen), `COUNTRY_CODED`, `COUNTRY_SUBDIVISION`, `PHONE`. | | `ORDER_PARTIES_REFERENCE` | `BUYER_IDREF` = Kundennummer, `SUPPLIER_IDREF` = `supplier`, `INVOICE_RECIPIENT_IDREF` = Adressnummer der Rechnungsadresse, `DELIVERY_IDREF` = Adressnummer der Lieferadresse. | | `ORDER_ITEM` | Eine je Position: `LINE_ITEM_ID` = Positionsnummer (sonst laufende Nummer ab 1), `QUANTITY` und `ORDER_UNIT` = Menge (mit Dezimalpunkt) und Einheit (in Großbuchstaben). Sind umgerechnete Menge und Einheit erfasst, stehen hier die umgerechneten Werte. | | `PRODUCT_ID` | `SUPPLIER_PID` = Ihre Artikelnummer (`type` = `supplier_specific`), `BUYER_PID` = Artikelnummer des Kunden, `DESCRIPTION_LONG` = Artikelbeschreibung. | | `DELIVERY_DATE` (Position) | Liefertermin der Position in `DELIVERY_START_DATE` und `DELIVERY_END_DATE`. | | `ORDER_SUMMARY` | `TOTAL_ITEM_NUM` = Anzahl der Positionen. | ### Hinweise - Das Format enthält keine Preise, Positionssummen oder Gesamtbeträge. - Die Feldauswahl Ihres Kanals ändert den Aufbau nicht. --- ## cXML OrderRequest {#cxml} **Dateiendung:** `.xml` **Dateiname:** `.xml` Bestellung im cXML-Format (`OrderRequest`) mit Kopf, Lieferadresse, bestellendem Kunden, Ansprechpartner und Positionen mit Preisen. ### Vollständiges Beispiel ```xml
CUST-12345 supplier workist Workist Platform
1250
Acme Corporation GmbH warehouse@acme.de
Warehouse Team Gate 3 Lager Strasse 5 Hamburg HH 20095 DE
Acme Corp GmbH
Acme Corporation Finance Department Hauptstrasse 42 Munich BY 80331 DE Max Mustermann CP-001 Max Mustermann ART-001-A 12.5 Industrial Sensor Module Type A PCE PCE ``` ### Elemente | Element | Inhalt | |---|---| | `cXML` | `payloadID` = ID des Dokuments in Workist, `timestamp` = Erstellungszeitpunkt. | | `From` | `Credential` (`domain` = `SystemId`) = Kundennummer. | | `To` | `Credential` (`domain` = `SystemId`) = Empfänger-ID, standardmäßig `supplier`. | | `Sender` | `Credential` (`domain` = `SystemId`) = `workist`, `UserAgent` = `Workist Platform`. | | `Request`, `OrderRequest` | `deploymentMode` = `production` (oder `test`, siehe unten). | | `OrderRequestHeader` | `orderID` = Bestellnummer, `orderDate` = Bestelldatum mit Uhrzeit (`2025-03-15T00:00:00+00:00`), `orderType` = `regular`, `orderVersion` = `1`, `type` = `new`. | | `Total` | `Money` = Nettogesamtbetrag (`0.0`, wenn keiner erfasst ist), `currency` = Währung der Bestellung (sonst `EUR`). | | `ShipTo` | Lieferadresse, wenn Firma, Name oder Adressnummer erfasst sind. `Address`: `addressID` = Adressnummer, `isoCountryCode` = Ländercode, `Name` (`xml:lang` = `de`) = Firma, `Email`. `PostalAddress` (neben `Address`): `DeliverTo` = Name, zweites `DeliverTo` = Adresszusatz (wenn vorhanden), `Street`, `City`, `State` = Bundesland/Region, `PostalCode`, `Country` mit `isoCountryCode` (Standard `DE`). | | `BillTo` | Der bestellende Kunde aus Ihren Kundenstammdaten. `Address`: `addressID` = Kundennummer, `isoCountryCode`, `Name` (`xml:lang` = `de`) = Firmenname der Kundenadresse. `PostalAddress`: `DeliverTo` = Name, zweites `DeliverTo` = Adresszusatz, `Street`, `City`, `State`, `PostalCode`, `Country` mit `isoCountryCode`. `IdReference` mit `domain` = `buyerID` und `identifier` = Kundennummer. | | `Contact` | Ansprechpartner, wenn Name oder Nummer erfasst sind: `role` = `buyerCorporate`, `Name` (`xml:lang` = `de`). `PostalAddress` (`name` = Name): `DeliverTo` = Nummer, zweites `DeliverTo` = Name; `Street`, `City`, `State`, `PostalCode` und `Country` bleiben leer. | | `ItemOut` | Eine je Position, direkt unter `cXML`: `lineNumber` = Positionsnummer (sonst laufende Nummer ab 1), `quantity` = Menge mit Dezimalpunkt. `SupplierPartID` = Ihre Artikelnummer. `UnitPrice`: `Money` = Einzelpreis mit Dezimalpunkt, `currency` = Währung der Bestellung (sonst `EUR`). `Description` (`xml:lang` = `de`) = Artikelbeschreibung, `UnitOfMeasure` = Mengeneinheit. `ScheduleLine` wiederholt `lineNumber`, `quantity` und `UnitOfMeasure`; `requestedDeliveryDate` = Liefertermin der Position. | ### Einstellungen Diese Werte stellt Workist bei der Einrichtung für Sie ein: | Einstellung | Standard | Beschreibung | |---|---|---| | Empfänger-ID | `supplier` | Wert im `Credential` unter `To` | | Deployment-Modus | `production` | `deploymentMode` von `Request` und `OrderRequest`, z. B. `test` für Testsysteme | ### Hinweise - `BillTo` enthält den bestellenden Kunden. Die Rechnungsadresse der Bestellung überträgt cXML nicht. - Jede Position braucht eine Menge, die sich als Zahl lesen lässt, sonst erzeugt Workist keine Datei. - Die Feldauswahl Ihres Kanals ändert den Aufbau nicht. --- ## ANSI X12 850 {#x12} **Dateiendung:** `.edi` **Dateiname:** `__.edi` (siehe [Dateinamen](/docs/output-formats.md#file-names)) Das EDI-Format für Bestellungen, das vor allem in Nordamerika verbreitet ist. Datenelemente sind durch `*` getrennt, jedes Segment endet mit `~` und steht in einer eigenen Zeile. ### Vollständiges Beispiel ``` ISA*00* *00* *ZZ*CUST-12345 *ZZ*musterlieferant*250315*0000*U*00401*212075055*0*P*>~ GS*PO*CUST-12345* *20250315*0000*2120*X*004010~ ST*850*212075055~ BEG*00**PO-2025-0001**20250315~ PER*BD*Max Mustermann*TE*+49 89 12345678*EM*max@acme.de~ DTM*002*20250401~ MSG*Please deliver to loading dock B. Handle with care - fragile items, do not stack pallets.~ N1*ST*Acme Corporation**CUST-12345~ PO1*10*100*PCE*12.5**VN*ART-001-A~ PID*F****Industrial Sensor Module Type A~ CTT*1~ SE*10*212075055~ GE*1*2120~ IEA*1*212075055~ ``` ### Segmente | Segment | Inhalt | |---|---| | `ISA` | Interchange-Kopf: Absender-ID = Kundennummer, Empfänger-ID = Ihr Workist-Kurzname (je auf 15 Zeichen aufgefüllt), Datum (`JJMMTT`) = Bestelldatum, Uhrzeit `0000`, Version `00401`, Kontrollnummer | | `GS` | Funktionsgruppe `PO`, Absender = Kundennummer, Datum = Bestelldatum, Version `004010` | | `ST` | Transaktion `850` und Kontrollnummer | | `BEG` | `00` (Original), Bestellnummer, Bestelldatum (`JJJJMMTT`) | | `PER` | Ansprechpartner (`BD`): Name, Telefon (`TE`), E-Mail (`EM`) | | `DTM` | `002` = Liefertermin (`JJJJMMTT`) | | `MSG` | Freitext der Bestellung (nur, wenn vorhanden) | | `N1` | `ST`, Name und Nummer des bestellenden Kunden. Eine Lieferadresse wird nicht übertragen | | `PO1` | Position: Positionsnummer, Menge, Einheit, Einzelpreis, `VN` und Ihre Artikelnummer | | `PID` | `F` (Freitext) und Artikelbeschreibung | | `CTT` | Anzahl der Positionen | | `SE` | Anzahl der Segmente der Transaktion und Kontrollnummer | | `GE` | Anzahl der Transaktionen und Kontrollnummer | | `IEA` | Anzahl der Funktionsgruppen und Kontrollnummer | `PO1` und `PID` wiederholen sich für jede Position. Die Feldauswahl Ihres Kanals ändert den Aufbau nicht. --- Source: https://docs.workist.com/docs/output-formats/requests-for-quotation.md # Anfragen (Requests for Quotation) Für Anfragen gibt es diese Standardformate: [Workist XML](#workist-xml) (Standard), [SAP IDoc](#sap-idoc) mit dem Nachrichtentyp `REQOTE` und [openTRANS 2.1](#opentrans). Andere Formate baut Workist auf Anfrage, siehe [Individuelle Formate auf Anfrage](/docs/output-formats.md#custom-formats). Alle Beispiele auf dieser Seite wurden mit den Workist-Serialisierern aus denselben Beispieldaten erzeugt. Allgemeine Regeln zu Dateinamen, Datums- und Zahlenformaten finden Sie in der [Übersicht](/docs/output-formats.md). --- ## Workist XML {#workist-xml} **Dateiendung:** `.xml` **Dateiname:** `.xml` Das Standardformat für Anfragen. Es ist aufgebaut wie das [Workist XML für Bestellungen](/docs/output-formats/orders.md#workist-xml): `General` enthält die Kopfdaten, `Invoicing` und `Shipping` die Adressen und Liefertermine, und je Position folgt ein `Line`-Element. Welche Elemente erscheinen, hängt von den Kopf- und Positionsfeldern Ihres Kanals ab. Leere Felder lässt Workist weg. Ein `Line`-Element schreibt Workist für jede Position, auch wenn es leer bleibt, weil keine Positionsfelder konfiguriert sind. ### Vollständiges Beispiel ```xml CUST-12345 Acme Corporation CP-001 Max Mustermann max@acme.de +49 89 12345678 DE BY regular 2025-03-15 2025-03-31 RFQ-2025-0010 PRJ-500 Requesting quote for Q2 2025 order. COM-999 9f8c2b7e-4d1a-4c3e-9b6f-2a7d5e1c0b34.pdf https://wb.workist.com/rfqs/3f2b8c1e-5a7d-4e19-8c2f-6b0d9a4e7c15 max@acme.de BILL-001 Accounts Payable Acme Corporation GmbH
Billing Strasse 10
Building C, 3rd Floor Munich 80331 DE BY +49 89 11111111 billing@acme.de SHIP-002 Warehouse Team Acme Corporation GmbH
Lager Strasse 5
Gate 3 Hamburg 20095 DE HH +49 40 22222222 warehouse@acme.de 2025-05-01 2025-05-15 forklift Industrial Sensor Module Type A PCE 500 box 50 ART-001-A ART-001-A-ALT 4006381333931 CUST-ART-555 0,92 2025-05-01 COM-LINE-01 10 ``` ### Allgemeine Felder (`General`) | Element | Typ | Beschreibung | |---|---|---| | `Sell_to_Customer` | Block | Anfragender Kunde, gefüllt aus Ihren Kundenstammdaten | | `Sell_to_Customer/Customer_Number` | Text | Kundennummer | | `Sell_to_Customer/Name` | Text | Kundenname | | `Sell_to_Customer/Contact_Number` | Text | Nummer des Ansprechpartners beim Kunden | | `Sell_to_Customer/Contact` | Text | Name des Ansprechpartners | | `Sell_to_Customer/Contact_Email` | Text | E-Mail-Adresse des Ansprechpartners | | `Sell_to_Customer/Contact_Phone` | Text | Telefonnummer des Ansprechpartners | | `Sell_to_Customer/Country` | Text | Ländercode der Kundenadresse (z. B. `DE`) | | `Sell_to_Customer/Country_Subdivision` | Text | Bundesland- oder Regionscode der Kundenadresse (z. B. `BY`) | | `Sell_to_Customer/Customer_Type` | Text | Kundentyp aus Ihren Stammdaten | | `Request_Date` | Datum | Anfragedatum | | `Quote_Deadline` | Datum | Frist für die Angebotsabgabe | | `Customer_Request_number` | Text | Anfragenummer des Kunden | | `Project_Number` | Text | Projektnummer | | `Info_Text` | Text | Freitext. Workist teilt ihn in Abschnitte zu 70 Zeichen auf, ein Element je Abschnitt, höchstens 5 Elemente; der Rest entfällt | | `Commission_Number` | Text | Kommissionsnummer | | `External_Document_Link` | Text | Dateiname des Originaldokuments, das Workist zusammen mit der XML-Datei überträgt (`.pdf`). Kein Link | | `Workist_URL` | Text | Link zum Dokument in der Workbench | | `Received_By` | Text | Absenderadresse (*Von*) der E-Mail, mit der das Dokument bei Workist eingegangen ist | `External_Document_Link`, `Workist_URL` und `Received_By` schalten Sie in der [Ausgabedatei-Konfiguration](/docs/channel-configuration/exported-documents.md) ein, siehe [Optionen](/docs/output-formats.md#options). ### Rechnungsadresse, Lieferadresse und Liefertermine | Element | Typ | Beschreibung | |---|---|---| | `Invoicing/Bill_to_Customer` | Block | Rechnungsadresse; Felder wie bei [Bestellungen](/docs/output-formats/orders.md#address-fields) | | `Shipping/Ship_to_Customer` | Block | Lieferadresse; Felder wie bei [Bestellungen](/docs/output-formats/orders.md#address-fields) | | `Shipping/Expected_Delivery_Date` | Datum | Gewünschter Liefertermin | | `Shipping/Expected_Delivery_End_Date` | Datum | Ende des Lieferzeitraums | | `Shipping/Delivery_Unload_Method` | Text | Entladeart am Lieferort | ### Positionsfelder (`Line`) | Element | Typ | Beschreibung | |---|---|---| | `Description` | Text | Artikelbeschreibung | | `Unit_of_Measure` | Text | Mengeneinheit | | `Quantity` | Dezimal | Angefragte Menge | | `Converted_Unit_of_Measure` | Text | Umgerechnete Einheit (z. B. `box`) | | `Converted_Quantity` | Dezimal | Menge in der umgerechneten Einheit | | `Common_Item_Number` | Text | Ihre Artikelnummer (`article_id1` aus Ihren Artikelstammdaten) | | `Common_Item_Number_2` | Text | Zweite Artikelnummer (`article_id2`) | | `Common_Item_Number_3` | Text | Dritte Artikelnummer (`article_id3`, z. B. EAN) | | `Customer_Item_Number` | Text | Artikelnummer des Kunden | | `Item_Number_Confidence` | Dezimal | Sicherheit der automatischen Artikelzuordnung zwischen 0 und 1, immer mit Dezimalkomma (z. B. `0,92`) | | `Expected_Delivery_Date` | Datum | Liefertermin der Position | | `Commission_Number` | Text | Kommissionsnummer der Position | | `Pos` | Text | Positionsnummer | --- ## SAP IDoc (REQOTE) {#sap-idoc} **Dateiendung:** `.xml` **Dateiname:** `.xml` Anfragen im IDoc-Basistyp `ORDERS05` mit dem Nachrichtentyp `REQOTE`. Aufbau, Segmente und Feldlängen entsprechen dem [SAP IDoc ORDERS05 für Bestellungen](/docs/output-formats/orders.md#sap-idoc). Diese Punkte unterscheiden sich: | Element | Bestellung | Anfrage | |---|---|---| | `EDI_DC40/MESTYP`, `EDI_DC40/STDMES` | `ORDERS` | `REQOTE` | | `E1EDK01/BELNR`, `E1EDK02/BELNR` | Bestellnummer | Anfragenummer | | `E1EDK03` (`IDDAT` = `012`), `E1EDK02/DATUM` | Bestelldatum | Anfragedatum | | `EDI_DC40/SNDPOR`, `SNDPRT`, `SNDPRN` | einstellbar | fest `WORKIST`, `LS`, `WORKIST` | Anfragedatum und Liefertermin sind Pflicht. Fehlt einer der beiden Werte, erzeugt Workist keine Datei. Diese Werte stellt Workist bei der Einrichtung für Sie ein: | Feld | Standard | Max. Zeichen | |---|---|---| | `MANDT` | `050` | – | | `RCVPOR` | `XML_WKI` | 10 | | `RCVPRT` | `LS` | 2 | | `RCVPRN` | `SUPPLIER` | 10 | | `RECIPNT_NO` | `SUPPLIER` | 10 | --- ## openTRANS 2.1 {#opentrans} **Dateiendung:** `.xml` **Dateiname:** `.xml` Anfrage im openTRANS-2.1-Format (`RFQ`). Das Format hat eine feste Struktur: Die Feldauswahl Ihres Kanals und die Optionen der Ausgabedatei-Konfiguration ändern es nicht. Rechnungs- und Lieferadresse sind nicht enthalten. ### Vollständiges Beispiel ```xml Workist 2025-03-15T14:30:25.123456 RFQ-2025-0010 2025-03-15 2025-05-01 2025-05-15 forklift workist document_creator supplier supplier CUST-12345 buyer
Acme Corporation Hauptstrasse 42 80331 Munich DE
CUST-12345 supplier EUR 10 ART-001-A CUST-ART-555 Industrial Sensor Module Type A 500.0 PCE 2025-05-01 2025-05-01 1 ``` ### Elemente | Element | Inhalt | |---|---| | `CONTROL_INFO` | `GENERATOR_INFO` = `Workist`, `GENERATION_DATE` = Erstellungszeitpunkt (UTC). | | `RFQ_INFO` | `RFQ_ID` = Anfragenummer des Kunden, `RFQ_DATE` = Anfragedatum, `DELIVERY_UNLOAD_METHOD` = Entladeart (zusätzliches Element, nicht Teil des openTRANS-Standards; nur wenn erfasst), `CURRENCY` = immer `EUR`. | | `DELIVERY_DATE` | Nur mit Liefertermin: `DELIVERY_START_DATE` = Liefertermin, `DELIVERY_END_DATE` = Ende des Lieferzeitraums (sonst der Liefertermin). | | `PARTY` `document_creator` | Workist als Ersteller: `PARTY_ID` = `workist` (`type` = `party_specific`), `PARTY_ROLE` = `document_creator`. | | `PARTY` `supplier` | Sie als Lieferant, fester Platzhalter: `PARTY_ID` = `supplier` (`type` = `party_specific`), `PARTY_ROLE` = `supplier`. | | `PARTY` `buyer` | Anfragender Kunde: `PARTY_ID` = Kundennummer, `PARTY_ROLE` = `buyer`; `NAME` = Name aus der Kundenadresse, `STREET`, `ZIP`, `CITY`, `COUNTRY` (Ländercode). | | `ORDER_PARTIES_REFERENCE` | `BUYER_IDREF` = Kundennummer, `SUPPLIER_IDREF` = `supplier`. | | `RFQ_ITEM` | Eine je Position: `LINE_ITEM_ID` = Positionsnummer, `QUANTITY` = Menge mit Dezimalpunkt (z. B. `500.0`), `ORDER_UNIT` = Mengeneinheit. | | `PRODUCT_ID` | `SUPPLIER_PID` = Ihre Artikelnummer (`type` = `supplier_specific`), `BUYER_PID` = Artikelnummer des Kunden, `DESCRIPTION_LONG` = Artikelbeschreibung. | | `DELIVERY_DATE` (Position) | Liefertermin der Position in `DELIVERY_START_DATE` und `DELIVERY_END_DATE`. | | `RFQ_SUMMARY` | `TOTAL_ITEM_NUM` = Anzahl der Positionen. | Jede Position braucht eine Menge, die sich als Zahl lesen lässt, sonst erzeugt Workist keine Datei. --- Source: https://docs.workist.com/docs/output-formats/invoices.md # Rechnungen (Invoices) ## Workist XML {#workist-xml} **Dateiendung:** `.xml` **Dateiname:** `.xml` Das Standardformat für Rechnungen. Die Kopfdaten stehen direkt unter `invoice`, danach folgen `payment` (Zahlungsangaben), `summary` (Beträge) und `line_items` (Positionen). Anders als bei Bestellungen und Anfragen schreibt Workist jedes konfigurierte Kopf-, Zahlungs-, Summen- und Positionsfeld, auch wenn es leer ist (z. B. ``). Die Blöcke `payment`, `summary` und `line_items` sind immer vorhanden. In Adress- und Lieferantenblöcken stehen nur gefüllte Felder. Datumsangaben haben das Format `JJJJ-MM-TT`. Dezimalzahlen stehen standardmäßig mit Dezimalkomma und ohne abschließende Nullen in der Datei (`1487,5`), siehe [Datums- und Zahlenformate](/docs/output-formats.md#number-formats). Die Optionen **Verweis auf die analysierte Datei einfügen**, **Link zur Workbench einfügen**, **E-Mail-Absenderinformationen einfügen** und **Kurzen externen Dateinamen verwenden** wirken bei Rechnungen nicht. ### Vollständiges Beispiel ```xml INV-2025-0042 PO-2025-0001 DN-2025-300 2025-03-20 2025-04-19 2025-03-15 Invoice RCPT-001 Accounts Payable Hauptstrasse 42 Building A Acme Corp GmbH 80331 Munich DE BY invoices@acme.de +49 89 12345678
Best Supplier GmbH Lieferantenweg 10 20095 Hamburg DE info@bestsupplier.de +49 40 99999999
Best Supplier GmbH Werk Nord SUP-500 preferred Hans Mueller DE987654321 Pay only after goods receipt DE987654321 143/123/45678 SC-001 Hans Mueller hans@bestsupplier.de +49 40 88888888 Payment due within 30 days. Deutsche Bank AG DEUTDEFF DE89370400440532013000 SEPA credit transfer INV-2025-0042 DEUTDEFF 2% within 10 days 30 net Net 30 days EUR 1250 19 237,5 1487,5 1487,5 10 ART-001-A ART-001-A-ALT 4006381333931 SUP-ART-777 Industrial Sensor Module Type A 100 PCE 12,5 1250 1 19 237,5 ``` ### Kopffelder | Element | Typ | Beschreibung | |---|---|---| | `invoice_number` | Text | Rechnungsnummer | | `order_number` | Text | Bestellnummer, auf die sich die Rechnung bezieht | | `contract_number` | Text | Vertragsnummer | | `delivery_note_number` | Text | Lieferscheinnummer | | `invoice_date` | Datum | Rechnungsdatum | | `invoice_due_date` | Datum | Fälligkeitsdatum | | `delivery_date` | Datum | Liefer- bzw. Leistungsdatum | | `document_type` | Text | Belegart als Freitext, wie erkannt. Bei E-Rechnungen (ZUGFeRD, XRechnung) `Invoice` oder `Credit Note` | | `recipient_address` | Block | Rechnungsempfänger; Felder siehe [Adressfelder](#address-fields) | | `sender_supplier` | Block | Rechnungssteller, gefüllt aus Ihren Lieferantenstammdaten | | `sender_supplier/address` | Block | Adresse des Lieferanten; Felder siehe [Adressfelder](#address-fields) | | `sender_supplier/name` | Text | Name des Lieferanten | | `sender_supplier/misc` | Text | Zusätzliche Angaben aus den Lieferantenstammdaten (`misc`) | | `sender_supplier/customer_number` | Text | Lieferantennummer | | `sender_supplier/customer_type` | Text | Typ aus den Stammdaten | | `sender_supplier/contact_person` | Text | Kontaktperson aus den Stammdaten | | `sender_supplier/vat_id` | Text | USt-IdNr. aus den Stammdaten | | `sender_supplier/internal_note` | Text | Interne Anmerkung aus Ihren Stammdaten (`internal_note`) | | `sender_vat_id` | Text | USt-IdNr. des Lieferanten, wie auf der Rechnung angegeben | | `sender_tax_number` | Text | Steuernummer des Lieferanten | | `sender_contact` | Block | Ansprechpartner beim Lieferanten | | `sender_contact/contact_id` | Text | Nummer des Ansprechpartners | | `sender_contact/name` | Text | Name des Ansprechpartners | | `sender_contact/email` | Text | E-Mail-Adresse des Ansprechpartners | | `sender_contact/phone` | Text | Telefonnummer des Ansprechpartners | | `Info_Text` | Text | Freitext. Workist teilt ihn in Abschnitte zu 70 Zeichen auf, ein Element je Abschnitt, höchstens 5 Elemente; der Rest entfällt | ### Adressfelder {#address-fields} `recipient_address` und `sender_supplier/address` haben dieselbe Struktur. Workist schreibt nur die gefüllten Felder. | Element | Typ | Beschreibung | |---|---|---| | `Code` | Text | Adressnummer aus Ihren Stammdaten | | `name` | Text | Name | | `street_and_nr` | Text | Straße und Hausnummer | | `misc` | Text | Adresszusatz | | `company_name` | Text | Firmenname | | `postcode` | Text | Postleitzahl | | `city` | Text | Ort | | `country` | Text | Ländercode (z. B. `DE`) | | `country_subdivision` | Text | Bundesland- oder Regionscode | | `email` | Text | E-Mail-Adresse | | `phone` | Text | Telefonnummer | ### Zahlungsfelder (`payment`) | Element | Typ | Beschreibung | |---|---|---| | `payment_bank` | Text | Name der Bank | | `payment_bic` | Text | BIC | | `payment_iban` | Text | IBAN | | `payment_method` | Text | Zahlungsart als Freitext; bei E-Rechnungen die Bezeichnung des Zahlungsmittelcodes (z. B. `SEPA credit transfer`) | | `payment_reference` | Text | Verwendungszweck | | `payment_swift` | Text | SWIFT-Code | | `payment_terms_discount` | Text | Skontobedingungen | | `payment_terms_due_days` | Text | Zahlungsziel in Tagen | | `payment_terms_type` | Text | Art der Zahlungsbedingung | | `payment_terms` | Text | Zahlungsbedingungen im Wortlaut | ### Summenfelder (`summary`) | Element | Typ | Beschreibung | |---|---|---| | `currency` | Text | Währungscode (z. B. `EUR`) | | `net_amount` | Dezimal | Nettobetrag | | `tax_rate` | Dezimal | Steuersatz in Prozent | | `tax_amount` | Dezimal | Steuerbetrag | | `total_amount` | Dezimal | Bruttobetrag | | `total_due` | Dezimal | Zahlbetrag | ### Positionsfelder (`line_items/line_item`) Workist schreibt ein `line_item` je Position, sofern mindestens ein Positionsfeld konfiguriert ist. | Element | Typ | Beschreibung | |---|---|---| | `pos` | Text | Positionsnummer | | `article_id1` | Text | Ihre Artikelnummer (`article_id1` aus Ihren Artikelstammdaten) | | `article_id2` | Text | Zweite Artikelnummer (`article_id2`) | | `article_id3` | Text | Dritte Artikelnummer (`article_id3`, z. B. EAN) | | `article_partition_specific_number` | Text | Artikelnummer des Lieferanten | | `article_description` | Text | Artikelbeschreibung | | `quantity` | Dezimal | Menge | | `unit` | Text | Mengeneinheit | | `unit_price` | Dezimal | Einzelpreis | | `total_price` | Dezimal | Positionsgesamtbetrag | | `gross_price` | Dezimal | Bruttopreis aus Ihren Artikelstammdaten (`gross_price`) | | `price_unit` | Text | Preiseinheit (z. B. `1` oder `100`) | | `tax_rate` | Dezimal | Steuersatz der Position | | `tax_amount` | Dezimal | Steuerbetrag der Position | --- Source: https://docs.workist.com/docs/output-formats/delivery-notes.md # Lieferscheine (Delivery Notes) ## openTRANS 2.1 {#opentrans} **Dateiendung:** `.xml` **Dateiname:** `.xml` Lieferscheine liefert Workist im openTRANS-2.1-Format `ORDERRESPONSE`. Bei Lieferscheinen sind Sie der Käufer: Das Dokument kommt von Ihrem Lieferanten und bezieht sich auf Ihre Bestellung. Das Format hat eine feste Struktur. Die Feldauswahl Ihres Kanals ändert es nicht. Preise und Liefertermine je Position sind nicht enthalten. Die Lieferscheinnummer steht in `SUPPLIER_ORDER_ID`, das Lieferscheindatum in `ORDERRESPONSE_DATE`. Mit **Kurzen externen Dateinamen verwenden** erhält die Datei eine kurze ID statt einer UUID; die übrigen Optionen der Ausgabedatei-Konfiguration wirken bei Lieferscheinen nicht. Jede Position braucht eine Menge, die sich als Zahl lesen lässt, sonst erzeugt Workist keine Datei. ### Vollständiges Beispiel ```xml Workist 2025-03-15T14:30:25.123456 PO-2025-0001 2025-03-20 DN-2025-300 2025-03-20 2025-03-20 workist document_creator K-1001 buyer SUP-500 supplier
Best Supplier GmbH Lieferantenweg 10 20095 Hamburg DE HH
WH-01 delivery
Acme Corporation GmbH Goods Receipt Lager Strasse 5 20095 Hamburg DE HH
K-1001 SUP-500 10 SUP-ART-777 4006381333931 ART-001-A Industrial Sensor Module Type A 100.0 PCE 1 ``` ### Elemente | Element | Inhalt | |---|---| | `CONTROL_INFO` | `GENERATOR_INFO` = `Workist`, `GENERATION_DATE` = Erstellungszeitpunkt (UTC). | | `ORDERRESPONSE_INFO` | `ORDER_ID` = Ihre Bestellnummer, auf die sich der Lieferschein bezieht; `ORDERRESPONSE_DATE` = Lieferscheindatum; `SUPPLIER_ORDER_ID` = Lieferscheinnummer (wenn vorhanden). | | `DELIVERY_DATE` | Nur mit Lieferdatum: `DELIVERY_START_DATE` und `DELIVERY_END_DATE` = Lieferdatum. | | `PARTY` `document_creator` | Workist als Ersteller: `PARTY_ID` = `workist` (`type` = `party_specific`), `PARTY_ROLE` = `document_creator`. | | `PARTY` `buyer` | Sie als Käufer: `PARTY_ID` (`type` = `party_specific`) = Kundennummer des Käufers (Sie bzw. Ihre Niederlassung), sonst `buyer`; `PARTY_ROLE` = `buyer`. Ohne Adresse. | | `PARTY` `supplier` | Lieferant, wenn erkannt: `PARTY_ID` = Lieferantennummer aus Ihren Stammdaten, `PARTY_ROLE` = `supplier`; `NAME`, `STREET`, `ZIP`, `CITY`, `COUNTRY` (Ländercode), `COUNTRY_SUBDIVISION`. | | `PARTY` `delivery` | Lieferadresse: `PARTY_ID` = Adressnummer, `PARTY_ROLE` = `delivery`; `NAME` = Firma, `NAME2` = Name, `STREET`, `ZIP`, `CITY`, `COUNTRY` (Ländercode), `COUNTRY_SUBDIVISION`. | | `ORDER_PARTIES_REFERENCE` | `BUYER_IDREF` = `PARTY_ID` des Käufers, `SUPPLIER_IDREF` = Lieferantennummer. | | `ORDERRESPONSE_ITEM` | Eine je Position: `LINE_ITEM_ID` = Positionsnummer, `QUANTITY` = Menge mit Dezimalpunkt (z. B. `100.0`), `ORDER_UNIT` = Mengeneinheit. | | `PRODUCT_ID` | `SUPPLIER_PID` (`type` = `supplier_specific`) = Artikelnummer des Lieferanten, wie auf dem Dokument; `INTERNATIONAL_PID` = dritte Artikelnummer aus Ihren Stammdaten (`article_id3`, z. B. EAN); `BUYER_PID` = Ihre Artikelnummer (`article_id1`); `DESCRIPTION_LONG` = Artikelbeschreibung. | | `ORDERRESPONSE_SUMMARY` | `TOTAL_ITEM_NUM` = Anzahl der Positionen. | --- Source: https://docs.workist.com/docs/output-formats/order-confirmations.md # Auftragsbestätigungen (Order Confirmations) ## openTRANS 2.1 {#opentrans} **Dateiendung:** `.xml` **Dateiname:** `.xml` Auftragsbestätigungen liefert Workist im openTRANS-2.1-Format `ORDERRESPONSE`. Bei Auftragsbestätigungen sind Sie der Käufer: Das Dokument kommt von Ihrem Lieferanten und bestätigt Ihre Bestellung. Die Grundstruktur entspricht der des [Lieferscheins](/docs/output-formats/delivery-notes.md#opentrans). Zusätzlich enthält die Auftragsbestätigung Einzelpreise, Positionssummen, Liefertermine je Position und den Nettogesamtbetrag. Die Nummer der Auftragsbestätigung steht in `SUPPLIER_ORDER_ID`, ihr Datum in `ORDERRESPONSE_DATE`. Das Format hat eine feste Struktur. Die Feldauswahl Ihres Kanals ändert es nicht. Jede Position braucht eine Menge, die sich als Zahl lesen lässt, sonst erzeugt Workist keine Datei. Formate wie proALPHA baut Workist auf Anfrage, siehe [Individuelle Formate auf Anfrage](/docs/output-formats.md#custom-formats). ### Vollständiges Beispiel ```xml Workist 2025-03-15T14:30:25.123456 PO-2025-0001 2025-03-18 https://wb.workist.com/order-confirmations/3f2b8c1e-5a7d-4e19-8c2f-6b0d9a4e7c15 OC-2025-0042 2025-04-01 2025-04-01 workist document_creator K-1001 buyer SUP-500 supplier
Best Supplier GmbH Lieferantenweg 10 20095 Hamburg DE HH
WH-01 delivery
Acme Corporation GmbH Goods Receipt Lager Strasse 5 20095 Hamburg DE HH
K-1001 SUP-500 application/pdf 9f8c2b7e-4d1a-4c3e-9b6f-2a7d5e1c0b34.pdf original_document 10 SUP-ART-777 4006381333931 ART-001-A Industrial Sensor Module Type A 100.0 PCE 12.5 1250.0 2025-04-01 2025-04-01 1 1250.0 ``` ### Elemente | Element | Inhalt | |---|---| | `CONTROL_INFO` | `GENERATOR_INFO` = `Workist`, `GENERATION_DATE` = Erstellungszeitpunkt (UTC). | | `ORDERRESPONSE_INFO` | `ORDER_ID` = Ihre Bestellnummer, die bestätigt wird; `ORDERRESPONSE_DATE` = Datum der Auftragsbestätigung; `ALT_CUSTOMER_ORDER_ID` = Link zur Auftragsbestätigung in der Workbench (nur mit **Link zur Workbench einfügen**); `SUPPLIER_ORDER_ID` = Nummer der Auftragsbestätigung (wenn vorhanden). | | `DELIVERY_DATE` | Nur mit Liefertermin: `DELIVERY_START_DATE` und `DELIVERY_END_DATE` = bestätigter Liefertermin. | | `PARTY` `document_creator` | Workist als Ersteller: `PARTY_ID` = `workist` (`type` = `party_specific`), `PARTY_ROLE` = `document_creator`. | | `PARTY` `buyer` | Sie als Käufer: `PARTY_ID` (`type` = `party_specific`) = Kundennummer des Käufers (Sie bzw. Ihre Niederlassung), sonst `buyer`; `PARTY_ROLE` = `buyer`. Ohne Adresse. | | `PARTY` `supplier` | Lieferant, wenn erkannt: `PARTY_ID` = Lieferantennummer aus Ihren Stammdaten, `PARTY_ROLE` = `supplier`; `NAME`, `STREET`, `ZIP`, `CITY`, `COUNTRY` (Ländercode), `COUNTRY_SUBDIVISION`. | | `PARTY` `delivery` | Lieferadresse: `PARTY_ID` = Adressnummer, `PARTY_ROLE` = `delivery`; `NAME` = Firma, `NAME2` = Name, `STREET`, `ZIP`, `CITY`, `COUNTRY` (Ländercode), `COUNTRY_SUBDIVISION`. | | `ORDER_PARTIES_REFERENCE` | `BUYER_IDREF` = `PARTY_ID` des Käufers, `SUPPLIER_IDREF` = Lieferantennummer. | | `MIME_INFO` | Nur mit **Verweis auf die analysierte Datei einfügen**: `MIME_TYPE` = `application/pdf`, `MIME_SOURCE` = Dateiname des Originaldokuments, das Workist mitliefert (`.pdf`), `MIME_PURPOSE` = `original_document`. | | `ORDERRESPONSE_ITEM` | Eine je Position: `LINE_ITEM_ID` = Positionsnummer (mit **Position überschreiben** die Position der zugeordneten Bestellposition), `QUANTITY` = Menge mit Dezimalpunkt (z. B. `100.0`), `ORDER_UNIT` = Mengeneinheit, `PRICE_LINE_AMOUNT` = Positionsgesamtpreis (`0.0`, wenn keiner erfasst ist). | | `PRODUCT_ID` | `SUPPLIER_PID` (`type` = `supplier_specific`) = Artikelnummer des Lieferanten, wie auf dem Dokument; `INTERNATIONAL_PID` = dritte Artikelnummer aus Ihren Stammdaten (`article_id3`, z. B. EAN); `BUYER_PID` = Ihre Artikelnummer (`article_id1`); `DESCRIPTION_LONG` = Artikelbeschreibung. | | `PRODUCT_PRICE_FIX` | `PRICE_AMOUNT` = Einzelpreis mit Dezimalpunkt (`0.0`, wenn keiner erfasst ist). | | `DELIVERY_DATE` (Position) | Liefertermin der Position in `DELIVERY_START_DATE` und `DELIVERY_END_DATE` (wenn vorhanden). | | `ORDERRESPONSE_SUMMARY` | `TOTAL_ITEM_NUM` = Anzahl der Positionen, `TOTAL_AMOUNT` = Nettogesamtbetrag (wenn vorhanden). | ### Optionen Diese Optionen der [Ausgabedatei-Konfiguration](/docs/channel-configuration/exported-documents.md) wirken bei Auftragsbestätigungen: | Option | Wirkung | |---|---| | **Verweis auf die analysierte Datei einfügen** (standardmäßig aktiv) | Schreibt `MIME_INFO` mit dem Dateinamen des mitgelieferten Originaldokuments. | | **Link zur Workbench einfügen** | Schreibt den Link zur Auftragsbestätigung in der Workbench in `ALT_CUSTOMER_ORDER_ID`. | | **Position überschreiben** | Wurde eine Position beim [Abgleich mit Ihren Bestellungen](/docs/channel-configuration/document-processing/matching.md) einer Bestellposition zugeordnet, schreibt Workist deren Positionsnummer in `LINE_ITEM_ID`. Sonst bleibt die Positionsnummer der Auftragsbestätigung. | | **Kurzen externen Dateinamen verwenden** | Verwendet eine kurze ID statt einer UUID im Dateinamen. | --- Source: https://docs.workist.com/docs/output-formats/list-of-services.md # Leistungsverzeichnis (List of Services) Für Leistungsverzeichnisse gibt es diese Standardformate: [SAP IDoc BOMMAT07](#sap-idoc) als Ausgabedatei (Standard) und [GAEB DA XML X94](#gaeb-x94), das Ihr System über die API erzeugen lässt. Kopfdaten, Positionen und vorgeschlagene Artikel können Sie außerdem über die [Dokument-API](/docs/api-documentation/document-api.md) als JSON abrufen. Eigene Layouts in JSON, CSV, TXT oder XLSX, z. B. mit einer Zeile je vorgeschlagenem Artikel, baut Workist auf Anfrage, siehe [Individuelle Formate auf Anfrage](/docs/output-formats.md#custom-formats). --- ## SAP IDoc BOMMAT07 {#sap-idoc} **Dateiendung:** `.xml` **Dateiname:** `BOM_.xml` Das Standardformat für Leistungsverzeichnisse: ein SAP-Stücklisten-IDoc (Basistyp `BOMMAT07`). Workist schreibt einen Stücklistenkopf und je Artikel einer relevanten Position eine Stücklistenposition mit Text. Vortexte und als nicht relevant markierte Positionen sowie Positionen ohne Artikelnummer lässt Workist weg. Das Format hat eine feste Struktur. Die Feldauswahl Ihres Kanals ändert es nicht. ### Vollständiges Beispiel Im Beispiel hat das Leistungsverzeichnis einen Vortext, zwei relevante Positionen und eine nicht relevante Position. Nur die beiden relevanten Positionen erscheinen. ```xml EDI_DC40 050 0000000000004711 30 1 2 BOMMAT07 BOMMAT 0 BOMMAT SAPC11 LS WORKIST XML_WKI LS WORKIST 20250315 143025 OBJ-2025-17 CUST-12345 01 0000000001 1 01 1 0001 0000000000001 L 01.01.0010 ART-001-A 12 Stk 0001 L ART-001-A 01.01.0010 Industrial Sensor Module Type A L 01 0001 01.01.0020 ART-002-B 250 m 0001 L ART-002-B 01.01.0020 Cable duct 60x40 L 01 0001 ``` ### Segmente | Element | Inhalt | |---|---| | `EDI_DC40` | Kontrollsatz. Fest: `TABNAM`, `MANDT` (`050`), `STATUS` (`30`), `DIRECT` (`1`), `OUTMOD` (`2`), `IDOCTYP` (`BOMMAT07`), `MESTYP` und `STDMES` (`BOMMAT`), `STD` (`0`), `SNDPOR` (`SAPC11`), `SNDPRT` (`LS`), `SNDPRN` (`WORKIST`). `DOCNUM` = fortlaufende 16-stellige IDoc-Nummer, `CREDAT`/`CRETIM` = Erstellungszeitpunkt (UTC). `RCVPOR`, `RCVPRT` und `RCVPRN` stellt Workist für Sie ein (Standard `XML_WKI`, `LS`, `WORKIST`). | | `E1CSUMHDR` | Stücklistenkopf: `MATNR` = Objektnummer des Leistungsverzeichnisses, `WERKS` = Kundennummer. Fest: `STLAL` (`01`), `STLNR`, `STLAN` (`1`), `STLST` (`01`), `BOM_STATUS` (`1`), `AUTH_GROUP` (`0001`), `CHANGE_NO`, `ITEM_CAT` (`L`). `BASEQ`, `BASEU`, `DATUV` und `DATUB` bleiben leer. | | `E1STPOM` | Eine Stücklistenposition je Artikel einer relevanten Position: `POSNR` = Positionsnummer aus dem Leistungsverzeichnis, `IDNRK` = Artikelnummer (max. 35 Zeichen), `MENGE` = Menge (max. 10 Zeichen), `MEINS` = Mengeneinheit. Fest: `SORTF` (`0001`), `POSTP` (`L`); `DATUV` und `DATUB` bleiben leer. | | `E1STKOM` | Text zur Stücklistenposition: `IDNRK` und `POSNR` wie oben, `TEXT1` = Artikelbeschreibung. Fest: `POSTP` (`L`), `ALPGR` (`01`), `SORTF` (`0001`). | ### Einstellungen Diese Werte stellt Workist bei der Einrichtung passend zu Ihrem SAP-System ein. Längere Werte werden abgeschnitten. | Feld | Standard | Max. Zeichen | |---|---|---| | `RCVPOR` | `XML_WKI` | 10 | | `RCVPRT` | `LS` | 2 | | `RCVPRN` | `WORKIST` | 10 | --- ## GAEB DA XML X94 {#gaeb-x94} **Dateiendung:** `.xml` Ist das Leistungsverzeichnis als GAEB-Datei X83 (GAEB DA XML 3.3) eingegangen, kann Ihr System über die Workist-API ein Angebot im Format X94 erzeugen lassen. Details zum Aufruf finden Sie in der [Dokument-API](/docs/api-documentation/document-api.md). So funktioniert es: 1. Ihr System übermittelt je Position, die es anbieten möchte, die GAEB-ID der Position und Ihre Angebotsdaten: Artikelnummer, Positionsart (Normal-, Alternativ- oder Bedarfsposition), Menge, Einheit, Nettopreis, Angebotspreis, Preisbasis und Abrechnungseinheit, Umsatzsteuer, EAN und Langtext. 2. Dazu kommen Ihre Lieferantendaten: Lieferantennummer, Adresse, Steuernummer und Registrierungsnummer. 3. Workist erzeugt aus der ursprünglichen X83-Datei und Ihren Angaben eine X94-Datei, prüft sie gegen das GAEB-Schema und gibt sie zurück. Workist lehnt die Anfrage ab, wenn eine GAEB-ID zu keiner Position des Leistungsverzeichnisses gehört, wenn das Leistungsverzeichnis nicht als X83-Datei eingegangen ist oder wenn die erzeugte X94-Datei nicht schemakonform ist. --- Source: https://docs.workist.com/docs/faq.md # FAQ Willkommen auf unserer technischen FAQ-Seite! Hier finden Sie Antworten auf häufig gestellte Fragen rund um unser Produkt. - [Allgemeine Informationen zu Workist](/docs/faq/general-information.md) - [Allgemeine Fragen zur Workist Workbench](/docs/faq/workbench.md) - [Fragen in Bezug auf die Business Central App](/docs/faq/business-central.md) - [Funktionen in Workist](/docs/faq/features.md) - [Technische Konfigurationen](/docs/faq/technical-configurations.md) --- Source: https://docs.workist.com/docs/faq/general-information.md # Allgemeine Informationen zu Workist ## Hat der EU Artificial Intelligence Act Einfluss auf Workist und Firmen die Workist benutzen? Die von uns eingesetzte KI ist Teil einer Prozessautomatisierungssoftware, die Datenfelder aus Transaktionsdokumenten automatisch erfasst, extrahiert und weiterleitet. Sie ist eingeschätzt als „KI-System ohne Risiko oder begrenztem Risiko". Artikel 50 der KI-Verordnung folgend ist für Nutzer ersichtlich, welche Daten per KI ausgelesen werden. --- ## Informationssicherheit und Datenschutz bei Workist Workist betreibt ein **SOC2 Type II** auditiertes ISMS. Alle produktiven Systeme befinden sich ausschließlich in der EU/EWR. Einzige Ausnahme sind Sprachagenten, die auf Ihren Wunsch in der globalen Umgebung von ElevenLabs laufen (siehe [Sprachagenten](#sprachagenten)). Es besteht eine DSGVO-konforme AVV. ### Speicherort und EU-Exklusivität - Ausschließlich in Rechenzentren innerhalb der EU/EWR - Cloud-Provider: AWS (Irland/Frankfurt) und Microsoft Azure (Westeuropa, Nordeuropa, Deutschland West-Zentral, Schweden-Zentral) - Sub-Dienstleister sind in der AVV Annex IV aufgelistet ### Sprachagenten {#sprachagenten} Für [Sprachagenten](/docs/agents/voice-agents.md) setzt Workist zusätzlich diese Dienstleister ein: - **ElevenLabs** für Spracherkennung und Sprachausgabe. Standardmäßig läuft jeder Sprachagent in der EU-Umgebung von ElevenLabs. - **Twilio** für die Telefonie. Anrufe werden in Irland verarbeitet. Auf Ihren Wunsch stellt Workist einen Sprachagenten auf die globale Umgebung von ElevenLabs um. Ab dann werden die Anrufdaten dieses Sprachagenten auch außerhalb der EU verarbeitet. Sie selbst können diese Einstellung nicht ändern. ### Dauer der Speicherung - Transiente Daten werden nach Verarbeitung verworfen - Strukturierte Extraktionsergebnisse, manuelle Korrekturen und Originaldokument werden für die Vertragsdauer gespeichert - Auf Wunsch vereinbart Workist mit Ihnen eine kürzere Aufbewahrungsfrist in Tagen. Workist löscht dann täglich automatisch alle Dokumente, die älter als diese Frist sind, zusammen mit Originaldatei, E-Mail, Extraktionsergebnissen, Korrekturen und erzeugten Ausgabedateien. Das gilt auch für E-Mails aus der Smart Inbox und für ältere Stammdaten-Importdateien. - Nach Vertragsende: Workist deaktiviert alle Benutzerkonten und löscht 30 Tage danach alle Daten ### Übertragung und Schutz - TLS 1.2+ für Übertragung - AES-256 für Speicherung - Logische Mandantentrennung, rollenbasierte Zugriffskontrollen, Audit-Logs ### Verarbeitung an mehreren Standorten - Cross-Zone-Replikation und geo-redundante Backups innerhalb EU-Regionen ### Korrektheit der Ergebnisse (Qualitätssicherung) - Automatisierte Validierung gegen Kundenkataloge/Plausibilitätsregeln - Konfidenzwert-Schwellenwert-System - Manuelle Prüfung über Workist-Workbench bei Unterschreitung des Schwellenwerts --- Source: https://docs.workist.com/docs/faq/workbench.md # Allgemeine Fragen zur Workist Workbench (WB) ## Stammdaten {#stammdaten} ### Prüfen der Stammdaten in der WB Ihre Stammdaten verwalten Sie im **Master Data Hub**. Sie öffnen ihn im Menü „Einstellungen“ über den Eintrag für die Stammdaten. Dafür benötigen Sie die Rolle Manager, IT oder Admin. Der Master Data Hub listet alle Stammdatensätze Ihres Unternehmens, getrennt nach bereitgestellten Daten (Import per Datei-Upload, SFTP oder API) und gelernten Daten (von Workist aus Ihren Korrekturen in der Unterstützung gelernt). Zu jedem Stammdatensatz sehen Sie die Kanäle, die ihn verwenden, die aktuellen Daten und alle bisherigen Importe. Dort können Sie auch eine neue Datei importieren. Details stehen unter [Master Data Hub](/docs/master-data/master-data-hub.md). Die Importe für einen bestimmten Kanal erreichen Sie auch direkt aus dem Kanal: Menü rechts oben → „Stammdaten verwalten“. Die Liste „Stammdatenimporte“ zeigt jeden Import mit Status, der an Workist übermittelten Datei („Eingabedatei“) und der von Workist transformierten Datei („Ausgabedatei“). Mit dem Filter „Nur aktive Stammdaten anzeigen“ sehen Sie nur die Daten, die Workist gerade verwendet. --- ## Dokumentenverarbeitung {#dokumentenverarbeitung} ### Neu verarbeiten von Dokumenten mit aktualisierten Stammdaten Dokumente sind bei Workist immer mit dem Stand der aktiven Stammdaten zum Zeitpunkt des Uploads eingefroren. Falls Sie die neuesten Stammdaten verwenden möchten, kann ein Dokument neu verarbeitet werden. Workist liest das Dokument dann erneut aus, mit den aktuellen Stammdaten und der aktuellen Kanalkonfiguration. Das geht nur für Dokumente im Reiter „Eingang“, die auf Unterstützung warten (Status „Unterstützung“). :::warning Beim erneuten Verarbeiten gehen alle manuellen Änderungen am Dokument verloren. ::: **Vorgehen:** - **Einzelnes Dokument:** In der Übersicht im 3-Punkte-Menü des Dokuments → „Erneut verarbeiten“ → mit „Dokument erneut verarbeiten“ bestätigen. - **Mehrere Dokumente:** Dokumente in der Übersicht markieren → „Erneut verarbeiten“ in der Leiste über der Liste. - **Aus dem Dokument heraus:** Wurde ein Dokument mit veralteten Stammdaten verarbeitet, weist der „Stammdaten-Status“ im Dokument darauf hin und bietet die Schaltfläche „Dokument erneut verarbeiten“ an. --- ## Allgemeines / Einstellungen {#einstellungen} ### Deaktivieren von Mail Benachrichtigungen 1. Klicken Sie in der Workist Workbench links unten auf Ihren Namen und wählen Sie „Dein Profil“. 2. Wählen Sie in der Navigation links „Benachrichtigungen“. 3. Stellen Sie „E-Mail-Benachrichtigungen erhalten“ auf **Nein** und klicken Sie auf „Speichern“. Welche E-Mails Workist verschickt und wie Ihre Einstellung mit den Firmenbenachrichtigungen zusammenhängt, steht unter [Benachrichtigungen](/docs/administration/notifications.md). --- ## Positionsbezogene Fragen {#positionen} ### Einfügen von Positionen 1. Klicken Sie in der Positionsliste auf das ➕ Symbol („Position hinzufügen“). 2. Ziehen Sie im Dokument einen Rahmen um die neue Position. 3. Workist fügt die Position automatisch an der richtigen Stelle ein. ### Mehr Details zu Artikelpositionen 1. In die Artikelbeschreibung klicken 2. Ans Ende der Popup-Liste scrollen → „Mehr Ergebnisse anzeigen“ 3. Im neuen Fenster sind alle Artikeldaten einsehbar; mit der Suche oben finden Sie den richtigen Artikel. Über „Zur Seitenleistenansicht wechseln“ öffnen Sie die Stammdaten stattdessen als Seitenleiste neben dem Dokument. Workist merkt sich Ihre Wahl in diesem Browser. --- Source: https://docs.workist.com/docs/faq/business-central.md # Fragen in Bezug auf die Business Central App Die vollständige Dokumentation zur Business-Central-Integration – Übersicht, Installation, Einrichtung, Betrieb, Fehlerbehebung und technische Referenz – finden Sie im Konnektor-Handbuch: ➡️ **[Microsoft Dynamics 365 Business Central](/docs/data-exchange/connectors/business-central.md)** ## Workist Integrator in Business Central verwalten Suchen Sie in Business Central nach „Workist Integrator-Einrichtung". Dort finden Sie alle relevanten Einstellungen zur Workist-Integration. Details siehe [Einrichtung](/docs/data-exchange/connectors/business-central.md#einrichtung). ## Synchronisierungs-Jobs (Aufgabenwarteschlangenposten) stoppen / löschen Deaktivieren Sie den jeweiligen Job über die Umschalter auf der Workist Integrator-Einrichtung. Ein deaktivierter Job kann in der Detailansicht gelöscht werden, sobald er zuvor den Status „Abwarten" hat. Details siehe [Betrieb](/docs/data-exchange/connectors/business-central.md#synchronisierungs-jobs-verwalten). --- Source: https://docs.workist.com/docs/faq/features.md # Funktionen in Workist ## Dubletten-Prüfung in Workist :::info Wenn ein Kunde dasselbe Dokument zweimal schickt, zum Beispiel dieselbe Bestellung an zwei Empfänger, kann Workist die Dublette erkennen. Das Dokument wird in so einem Fall nicht automatisiert verarbeitet, sondern landet mit einer Warnung in der Unterstützung. Die Warnung blockiert nicht: Sie können das Dokument trotzdem abschließen. ::: ### So prüft Workist Ein Dokument gilt als Dublette, wenn es ein anderes Dokument gibt, das - dieselbe Belegnummer (z. B. Bestellnummer) und dieselbe Kunden- bzw. Lieferantennummer hat, - im selben Kanal liegt und - in den letzten 30 Tagen eingegangen ist. Verworfene, abgelehnte und gelöschte Dokumente zählen nicht. Dieselbe Belegnummer darf bei verschiedenen Kunden vorkommen. Workist prüft nur, wenn beide Nummern vorhanden sind. Fehlt die Belegnummer oder konnte Workist dem Dokument keine Kunden- bzw. Lieferantennummer aus den Stammdaten zuordnen, entfällt die Prüfung. Schickt ein Kunde dasselbe Dokument an zwei Postfächer, die zu verschiedenen Kanälen gehören, erkennt Workist die Dublette nicht. Die Prüfung gibt es für Bestellungen, Preisanfragen, Auftragsbestätigungen, Rechnungen und Lieferscheine. Bei Bestellungen und Preisanfragen vergleicht Workist die Kundennummer, bei Auftragsbestätigungen, Rechnungen und Lieferscheinen die Lieferantennummer. ### Aktivierung der Dubletten-Prüfung Die Einstellung gilt pro Kanal. Dafür benötigen Sie die Rolle Manager oder Admin. 1. Öffnen Sie den Kanal und klicken Sie rechts oben auf das Menü → „Kanal verwalten“. 2. Wählen Sie in der Navigation „Dokument“. 3. Aktivieren Sie im Bereich „Validierung“ unter „Validierungsprüfungen“ die Prüfung auf eindeutige Belegnummern. In der Oberfläche heißt sie derzeit auch auf Deutsch „Unique document number“. 4. Klicken Sie auf „Speichern“. --- Source: https://docs.workist.com/docs/faq/technical-configurations.md # Technische Konfigurationen ## Einrichten von SSO (Single Sign-On) {#sso} Mit Single Sign-On (SSO) melden sich Ihre Mitarbeitenden mit ihrem Firmenkonto bei Workist an statt mit einem Workist-Passwort. Workist unterstützt **Microsoft Entra ID** (ehemals Azure AD) und **SAML 2.0**. Die vollständige Anleitung finden Sie unter [Anmeldung & Sicherheit → Single Sign-On](/docs/administration/login-and-security.md#sso). Das Wichtigste in Kürze: - **Wer:** SSO richten nur Benutzer mit der Rolle **Admin** ein, siehe [Benutzer, Rollen & Teams](/docs/administration/users-and-roles.md#roles). - **Wo:** **Einstellungen** → **Organisation**, dann links **Single Sign-On** (Microsoft Entra ID) oder **SAML**. - **Konfigurationen:** Die Seite **Single Sign-On** listet Ihre Konfigurationen. Jede gilt für eine Domain. Admins legen Konfigurationen selbst an und tragen Tenant-ID, Client-ID und Client-Secret selbst ein. Als **Anbieternamen** geben Sie `azure` ein. - **Redirect-URL** für die App-Registrierung in Microsoft Entra ID: `https://wb.workist.com/login/providers/azure/authorized` - **Nur SSO erlauben:** Mit **SSO ist für jeden Mitarbeiter erforderlich** bzw. **SAML ist für jeden Mitarbeiter erforderlich** ist die Anmeldung mit Passwort nicht mehr möglich. - **Erste Anmeldung per Microsoft Entra ID:** Workist deaktiviert danach das Workist-Passwort des Benutzers. - **E-Mail-Adresse:** Die Adresse in Workist muss genau dem Benutzerprinzipalnamen (UPN) in Microsoft Entra ID entsprechen, sonst schlägt die Anmeldung fehl. - **Client-Secret:** Erneuern Sie es vor dem Ablaufdatum in Microsoft Entra ID und tragen Sie den neuen Wert in Workist ein. Sonst kann sich niemand mehr per SSO anmelden.