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.

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

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

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

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 {
  tblTransactions {
    rowModify(
      exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } }
    ) {
      fldBelegNr
      fldArt

      fldInExtBeaInfo(set: { string: "Bearbeitung in externer App 123" })
      fldInExtBeaKz(set: { boolean: true })
      rowSave {  
        fldInExtBeaKz # erst hier ist sicher das der Vorgang gesperrt wurde
      }
    }  
  }
}

Tipp

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

Ergebnis: Das Kennzeichen "Vorgang in externer Bearbeitung" ist nun gesetzt. Andere Clients können den Vorgang nicht mehr ändern.

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 {
  tblTransactions {
    rowRead(
      exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } }
    ) {
      fldBelegNr
      fldArt
      fldInExtBeaKz

      fnUnlockFromExternalProcessing {
        fldBelegNr # Wenn BelegNr nicht leer, dann hat entsperren geklappt
      }
    }
  }
}

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:

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

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

Zunächst muss der Vorgang gesperrt und diese Änderung gespeichert werden:

mutation {
  tblTransactions {
    rowModify(
      exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } }
    ) {
      fldBelegNr
      fldArt

      fldInExtBeaInfo(set: { string: "Bearbeitung in externer App 123" })
      fldInExtBeaKz(set: { boolean: true })
      rowSave {  
        fldInExtBeaKz # erst hier ist sicher das der Vorgang gesperrt wurde
      }
    }  
  }
}

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 wieder entsperrt werden:

mutation {
  tblTransactions {
    rowRead(
      exactMatch: { byBelegNr: { kf1BelegNr: { string: "GS2500001" } } }
    ) {
      fldBelegNr
      fldArt
      fldInExtBeaKz

      fnUnlockFromExternalProcessing {
        fldBelegNr # Wenn BelegNr nicht leer, dann hat entsperren geklappt
      }
    }
  }
}

Beachten Sie

Prüfen Sie, ob die zurückgegebene Belegnummer mit der erwarteten übereinstimmt!

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

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.

Infos zum Aufruf der Funktion innerhalb der Software: Schaltflächen der Vorgangsübersicht - Schaltfläche: WEITERE - Vorgang in externer Bearbeitung