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

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

Inhaltsverzeichnis

In welchen Szenarien macht das Sperren von Vorgängen Sinn?
Konsequenzen des Sperrens
Vorgang für externe Bearbeitung sperren
Vorgang entsperren
Vollständiger Workflow: Sperren, Externe Bearbeitung, Entsperren
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:

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
      }
    }  
  }
}

Tipp

Nutzen Sie fldInExtBeaInfo, um zu dokumentieren, welche Anwendung oder welcher Prozess den Vorgang gesperrt hat. Dies erleichtert die Nachvollziehbarkeit und das Monitoring erheblich.

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:

Beachten Sie

fnUnlockFromExternalProcessing ist nur in einer mutation verfügbar und erfordert die Berechtigung "Kennzeichen 'Vorgang in externer Bearbeitung' ändern".

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:

{
  "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)

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
      }
    }  
  }
}

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).

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)
      }
    }
  }
}

Beachten Sie

Prüfen Sie, ob die zurückgegebene Belegnummer mit der erwarteten übereinstimmt (siehe Belegnummernprüfung)

6. Best Practices

Nutzen Sie fldInExtBeaInfo: Dokumentieren Sie in fldInExtBeaInfo, welche Anwendung den Vorgang gesperrt hat. Dies erleichtert Monitoring erheblich.
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.
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!
Belegnummer immer prüfen: Verlassen Sie sich nicht darauf, dass das Entsperren erfolgreich war – prüfen Sie die Belegnummer!
Fehlerbehandlung implementieren: Planen Sie ein, was passiert, wenn die Belegnummernprüfung fehlschlägt.
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