# Vorgänge für externe Bearbeitung per GraphQL sperren und entsperren Gen. 24 Enterprise ## Übersicht Vorgänge können über das Kennzeichen "Vorgang in externer Bearbeitung" (`fldInExtBeaKz`) für die externe Bearbeitung gesperrt werden. Dies verhindert, dass andere Benutzer oder Programmfunktionen den Vorgang gleichzeitig in microtech büro+ bearbeiten können. Zusätzlich kann über das Feld `fldInExtBeaInfo` eine Information hinterlegt werden, die angibt, welche Anwendung oder welcher Prozess den Vorgang gerade bearbeitet. !!! info "Info" Die Funktion "Vorgang in externer Bearbeitung", die Sie über GraphQL steuern können, befindet sich in der Software im Bereich: VERKAUF - VORGÄNGE - Register: VORGÄNGE - WEITERE → Vorgang in externer Bearbeitung. Infos zum Aufruf der Funktion innerhalb der Software: [Schaltflächen der Vorgangsübersicht - Schaltfläche: WEITERE - Vorgang in externer Bearbeitung](../05_wawi/vorgangsbearbeitung/schaltflaechen%20der%20vorgangsuebersicht/index.md#schaltflache-weitere-vorgang-in-externer-bearbeitung) ## Inhaltsverzeichnis 1. [In welchen Szenarien macht das Sperren von Vorgängen Sinn?](#1-in-welchen-szenarien-macht-das-sperren-von-vorgangen-sinn) 2. [Konsequenzen des Sperrens](#2-konsequenzen-des-sperrens) 3. [Vorgang für externe Bearbeitung sperren](#3-vorgang-fur-externe-bearbeitung-sperren) 4. [Vorgang entsperren](#4-vorgang-entsperren) 5. [Vollständiger Workflow: Sperren, Externe Bearbeitung, Entsperren](#5-vollstandiger-workflow-sperren-externe-bearbeitung-entsperren) 6. [Best Practices](#6-best-practices) ## 1. In welchen Szenarien macht das Sperren von Vorgängen Sinn? Das Setzen des Kennzeichens "Vorgang in externer Bearbeitung" sollte **nur in speziellen Szenarien** verwendet werden! ### Geeignete Anwendungsfälle Das Sperren ist sinnvoll, wenn: - Ein **externer Prozess** (z.B. externe Software, Schnittstelle) den Vorgang bearbeitet - Die Bearbeitung **außerhalb von microtech ERP** erfolgt (z.B. in einem Drittanbieter-System) - Sie **sicherstellen** müssen, dass während der externen Bearbeitung keine Änderungen im microtech ERP vorgenommen werden - Der Vorgang für einen **definierten Zeitraum** exklusiv von Ihrer Anwendung gesteuert wird ### In welchen Szenarien sollten Sie das Sperren von Vorgängen NICHT verwenden? Verwenden Sie das Sperren **nicht**, wenn: - Sie nur einen Vorgang **lesen** möchten - Die Bearbeitung **innerhalb von microtech ERP** erfolgen soll - Mehrere Benutzer **parallel** am Vorgang arbeiten sollen - Sie **keine exklusive Kontrolle** über den Vorgang benötigen ## 2. Konsequenzen des Sperrens Wenn ein Vorgang auf "Vorgang in externer Bearbeitung" gesetzt ist über `fldInExtBeaKz(set: { boolean: true })`: - ❌ Der Vorgang kann **nicht mehr im microtech ERP** bearbeitet werden - ❌ Benutzer im microtech ERP Client können **keine Änderungen** vornehmen - ❌ Andere Systeme und Prozesse sind **blockiert** - ⚠️ Die Sperre bleibt bestehen, bis sie explizit entfernt wird ## 3. Vorgang für externe Bearbeitung sperren ### Warum im Kontext einer Änderung? Das Setzen des Kennzeichens "Vorgang in externer Bearbeitung" über `fldInExtBeaKz(set: { boolean: true })` muss **immer im Kontext einer Änderungsoperation** (`rowModify`) erfolgen. Der Grund: Das Sperren ist eine Zustandsänderung des Vorgangs. Nur über eine exklusive Sperre kann der Client sicher sein, dieses Kennzeichen auch gesetzt zu haben. ### Beispiel: Vorgang sperren Sie können sowohl `rowModify` (einzelner Datensatz) als auch `rowsModify` (mehrere Datensätze) verwenden: ```graphql mutation VorgangFuerExterneBearbeitungSperren { tblTransactions { rowModify( exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } } ) { fldBelegNr fldArt # Info hinterlegen, welche Anwendung den Vorgang sperrt (empfohlen) fldInExtBeaInfo(set: { string: "Bearbeitung in externer App 123" }) # Kennzeichen "Vorgang in externer Bearbeitung" setzen fldInExtBeaKz(set: { boolean: true }) # Erst nach rowSave ist sicher, dass die Sperre gesetzt wurde rowSave { fldInExtBeaKz # true = Sperre erfolgreich gesetzt } } } } ``` !!! tip "Tipp" Nutzen Sie `fldInExtBeaInfo`, um zu dokumentieren, welche Anwendung oder welcher Prozess den Vorgang gesperrt hat. Dies erleichtert die Nachvollziehbarkeit und das Monitoring erheblich. !!! info "Berechtigung" Das Setzen von `fldInExtBeaKz` erfordert die Berechtigung **"Kennzeichen 'Vorgang in externer Bearbeitung' ändern"**. **Ergebnis:** Das Kennzeichen "Vorgang in externer Bearbeitung" ist nun gesetzt. Andere Clients können den Vorgang nicht mehr ändern. ## 4. Vorgang entsperren ### Entsperren mit fnUnlockFromExternalProcessing Das Entsperren erfolgt über die dedizierte Funktion `fnUnlockFromExternalProcessing` innerhalb einer `rowRead`-Operation. Sie können sowohl `rowRead` (einzelner Datensatz) als auch `rowsRead` (mehrere Datensätze) verwenden: !!! warning "Beachten Sie" `fnUnlockFromExternalProcessing` ist **nur in einer mutation** verfügbar und erfordert die Berechtigung **"Kennzeichen 'Vorgang in externer Bearbeitung' ändern"**. ```graphql mutation VorgangExterneBearbeitungAufheben { tblTransactions { rowRead( exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } } ) { fldBelegNr fldArt fldInExtBeaKz # Aktuellen Status des Kennzeichens lesen # Sperre aufheben fnUnlockFromExternalProcessing { fldBelegNr # Belegnummer prüfen! (leer = Entsperren fehlgeschlagen) } } } } ``` ### Wichtig: Belegnummernprüfung Nach dem Entsperren **muss** die zurückgegebene Belegnummer geprüft werden: ```graphql { "data": { "tblTransactions": { "rowRead": { "fldBelegNr": "GS2500001", "fnUnlockFromExternalProcessing": { "fldBelegNr": "GS2500001" // ← Diese Nummer prüfen! } } } } } ``` ### Warum ist diese Prüfung der Belegnummer notwendig? Die Belegnummernprüfung stellt sicher, dass Ihr Client den Vorgang **exklusiv entsperrt** hat: | Ergebnis | Bedeutung | |----------|-----------| | ✅ Belegnummern stimmen überein | Das Entsperren war erfolgreich. Ihr Client kann sicher mit der Bearbeitung fortfahren. | | ❌ Belegnummer ist leer | Der Vorgang konnte nicht exklusiv entsperrt werden. Ein anderer Prozess hat möglicherweise zwischenzeitlich auf den Vorgang zugegriffen und ihn entsperrt. | **Nur bei erfolgreicher Prüfung dürfen Sie mit der Bearbeitung fortfahren.** ## 5. Vollständiger Workflow: Sperren, Externe Bearbeitung, Entsperren Der korrekte Workflow besteht aus **drei separaten Schritten**, die nacheinander ausgeführt werden müssen: ### Schritt 1: Vorgang sperren und speichern Sperren Sie den Vorgang über `rowModify` mit `fldInExtBeaKz` (siehe Abschnitt 3 [Vorgang für externe Bearbeitung sperren](#3-vorgang-fur-externe-bearbeitung-sperren)) ```graphql mutation Schritt1_VorgangSperren { tblTransactions { rowModify( exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } } ) { fldBelegNr fldArt # Info hinterlegen, welche Anwendung den Vorgang sperrt fldInExtBeaInfo(set: { string: "Bearbeitung in externer App 123" }) # Kennzeichen setzen fldInExtBeaKz(set: { boolean: true }) # Erst nach rowSave ist sicher, dass die Sperre gesetzt wurde rowSave { fldInExtBeaKz # true = Sperre erfolgreich gesetzt } } } } ``` !!! warning "Beachten Sie" Prüfen Sie die Antwort auf Fehler! Nur wenn `rowSave` erfolgreich war und keine Fehler zurückgegeben wurden, fahren Sie mit Schritt 2 fort. ### Schritt 2: Externe Bearbeitung durchführen Nachdem der Vorgang erfolgreich gesperrt wurde, können Sie Ihre externe Bearbeitung durchführen: * Daten an Drittsystem übermitteln * Externe Verarbeitung ausführen * Ergebnisse verarbeiten **Während dieser Zeit ist der Vorgang im microtech ERP für andere Benutzer gesperrt.** ### Schritt 3: Vorgang entsperren Nach Abschluss der externen Bearbeitung muss der Vorgang über `fnUnlockFromExternalProcessing` wieder entsperrt werden (siehe Abschnitt 4 [Vorgang entsperren](#4-vorgang-entsperren)). ```graphql mutation Schritt3_VorgangEntsperren { tblTransactions { rowRead( exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } } ) { fldBelegNr fldArt fldInExtBeaKz # Aktuellen Status lesen # Sperre aufheben fnUnlockFromExternalProcessing { fldBelegNr # Belegnummer prüfen! (leer = Entsperren fehlgeschlagen) } } } } ``` !!! warning "Beachten Sie" Prüfen Sie, ob die zurückgegebene Belegnummer mit der erwarteten übereinstimmt (siehe [Belegnummernprüfung](#belegnummernprüfung)) ## 6. Best Practices 1. **Nutzen Sie fldInExtBeaInfo:** Dokumentieren Sie in `fldInExtBeaInfo`, welche Anwendung den Vorgang gesperrt hat. Dies erleichtert Monitoring erheblich. 2. **Sperren Sie nur wenn notwendig:** Verwenden Sie das Kennzeichen "Vorgang in externer Bearbeitung" nur für echte externe Bearbeitungen, bei denen das microtech ERP nicht eingreifen darf. 3. **Immer zeitnah entsperren:** Halten Sie die Sperre so kurz wie möglich, um Blockierungen zu vermeiden. Gesperrte Vorgänge können nicht im microtech ERP bearbeitet werden! 4. **Belegnummer immer prüfen:** Verlassen Sie sich nicht darauf, dass das Entsperren erfolgreich war – prüfen Sie die Belegnummer! 5. **Fehlerbehandlung implementieren:** Planen Sie ein, was passiert, wenn die Belegnummernprüfung fehlschlägt. 6. **Monitoring einrichten:** Überwachen Sie, ob Vorgänge versehentlich dauerhaft gesperrt bleiben. ## Zusammenfassung Das Setzen des Kennzeichens "Vorgang in externer Bearbeitung" ist ein mächtiges Werkzeug, das **mit Bedacht** eingesetzt werden sollte. Bedenken Sie immer: * Gesperrte Vorgänge können in microtech ERP **nicht bearbeitet** werden! * Die Sperre muss **aktiv entsperrt** werden * Die **Belegnummernprüfung** ist zwingend erforderlich * Verwenden Sie die Sperre nur für **tatsächliche externe Bearbeitungen**