Zum Hauptinhalt springen

Middleware

Die Middleware stellt eine konfigurierbare Schnittstelle dar, mit der Clients mit dem diaLIMS lesend und schreibend kommunizieren können.

Die Kommunikation erfolgt verschlüsselt via JSON (JavaScript Object Notation). Die Middleware stellt hierfür allgemeine Methoden zur Verfügung, über die Daten geladen und aktualisiert werden können.

Einrichtung​

Für die Ausführung der Middleware werden ein Web-Application-Server und eine diaLIMS-Datenbank benötigt.

Server​

Als Server kann eine Tomcat-Installation verwendet werden. Es wird empfohlen den Server so zu konfigurieren, dass nur eine verschlüsselte Kommunikation erlaubt ist (HTTPS). Nach der Einrichtung des Servers kann die Middleware als eine .war-Datei in dem Web-Apps-Verzeichnis abgelegt werden.

Berechtigungen und Datenbank​

Damit die Middleware auf dem Server ausgeführt werden kann, muss diese eine Verbindung zu der LIMS-Datenbank herstellen können. Die Zugangsdaten werden in der Datei dbConnect.properties angegeben. Es können hier die Benutzerdaten der zentralen Benutzeranmeldung einer diaLIMS-Installation eingetragen werden.

Die Kommunikation mit der Middleware erfordert eine Authentifizierung. Hierfür können die Anmeldedaten eines diaLIMS-Benutzers verwendet werden, der über die Berechtigung "LOGIN_App" verfügt. Nach der Authentifizierung werden zwei Tokens generiert, die im weiteren Verlauf für die Authentifizierung bei der Kommunikation verwendet werden. Der erste Token (Access-Token) wird mit jeder Anfrage mitgeschickt und hat eine Gültigkeit von einem Tag. Läuft dieser ab, kann anhand des zweiten Tokens (Refresh-Token), der am Benutzer gespeichert wird und eine Gültigkeit von einem Monat hat, ein neuer Access-Token generiert werden. Damit wird die Benutzerauthentifizierung bis zum aktiven Abmelden aufrechterhalten und erfordert keine weitere Anmeldung während der Kommunikation mit der Middleware. Alternativ kann ein API-Key direkt als Bearer-Token im Authorization-Header verwendet werden.

Konfiguration der Middleware​

Durch die generische Umsetzung der Android-App wird eine flexible Konfiguration der Anwendung durch die Middleware möglich. Bei der Konfiguration kann zum einen die Darstellung einzelner Ansichten und zum anderen die Datenzuordnung (Data-Mapping) vorgegeben werden.

Die Middleware sollte vor der Inbetriebnahme zweckgebunden konfiguriert werden. Die Konfiguration erfolgt über zwei Einstellungsdateien, die im Weiteren erläutert werden:

  • application.properties(Enthält allgemeine Einstellungen zur Middleware)

    • com.dialog.middleware.language: Hiermit wird die Sprache für die Middleware angegeben (Standard "de")
    • com.dialog.middleware.country: Hiermit wird das Land für die Middleware angegeben (Standard "DE")
    • com.dialog.middleware.variant: Gibt das Variant für die Middleware an (kann auch leer gelassen werden)
    • com.dialog.middleware.benutzerrolle: Gibt die diaLIMS-Benutzerrolle an, die beim Anmelden verwendet werden soll (kann auch leer gelassen werden)
  • Option 'DokumentTypGallery' (ab Version 2024.5c1)

    Die Einstellung ist im Optionen-Modul im diaLIMS unter Probennahme App zu finden. Die Option gibt an welcher Typ am Dokument gesetzt wird, wenn ein Foto als Dokument aus der dialog Mobile App hochgeladen wird.

    In der App gibt es für diesen Dokumententyp eine Ausnahme. Der Probennehmer (Ersteller) des Dokuments kann das Foto trotz einschränkender Bedingungen immer sehen.

  • Option 'DokumentTypSignature' (ab Version 2024.5c1)

    Die Einstellung ist im Optionen-Modul im diaLIMS unter Probennahme App zu finden. Die Option gibt an welcher Typ am Dokument gesetzt wird, wenn eine Unterschrift als Dokument aus der dialog Mobile App hochgeladen wird.

    In der App gibt es für diesen Dokumententyp eine Ausnahme. Der Probennehmer (Ersteller) des Dokuments kann die Unterschrift trotz einschränkender Bedingungen immer sehen.

  • Option 'ProbenahmeTerminDataType'

    Die Einstellung ist im Optionen-Modul im diaLIMS unter Probennahme App zu finden. Sie bestimmt welche Datensätze als Termin dargestellt werden.

    Es gibt folgende Konfigurationsmöglichkeiten:

    • Order (Standard) Aufträge werden als Termine verwendet.
    • Routing Touren werden als Termine verwendet. Je nach Einstellung werden in der dialog Mobile App andere Informationen angezeigt. Diese werden im Folgenden erläutert.
  • Option 'SampleFinishEnforceable'

    Die Einstellung ist im Optionen-Modul im diaLIMS unter Probennahme App zu finden. Sie erlaubt es Probenahmen abzuschließen, auch wenn es Pflichtfelder an der Probe gibt, die noch nicht ausgefüllt sind.

    Es gibt folgende Konfigurationsmöglichkeiten:

    • true Es dürfen unausgefüllte Pflichtfelder existieren.
    • false (Standard) Es müssen alle Pflichtfelder ausgefüllt sein.
  • Option 'SampleFinishEnforcedLogField'

    Die Einstellung ist im Optionen-Modul im diaLIMS unter Probennahme App zu finden. Sie erlaubt es die generierte Abschlussbemerkung an ein existierenden Feld anzuhängen:

    • keine Angabe Es wird keine Abschluss-Bemerkung erstellt.
    • Ein Middleware-Feld Das konfigurierte Middleware-Feld, dem die Abschluss-Bemerkung angehängt wird. (Standard: $.bemerkungPN) Bei einem Middleware-Feld handelt es sich um ein fest programmiertes Feld aus der Middleware.

    Zum Beispiel ordnet der Wert "$.bemerkungPN" die Abschluss-Bemerkung dem Feld ProbeReducer.DataProvider.Bemerkung("bemerkungPN") hinzu, welches auf Probe.bemerkung gemappt ist.

    Es lassen sich auch kundenindividuellen Felder nutzen, dafür muss jedoch die Kunden-Middleware angepasst werden. Die Einstellung für das folgende Beispiel mit dem kundeninviduellem Middleware-Feld "abschlussBemerkung" wäre "$.abschlussBemerkung" und der Wert dafür würde auf Probe."interneBemerkung" gemappt werden.


    // 1. Kundenindividuellen Reducer mit indivuellem Middleware-Feld erstellen.
    public class [Kunde]ProbeReducer extends ProbeReducer {

    ...

    enum [Kunde]DataProperty implements DataClassProperty {

    AbschlussBemerkung("abschlussBemerkung");

    [Kunde]DataProperty(String propertyName) {
    this.propertyName = propertyName;
    }

    @Override
    public final String getPropertyName() {
    return propertyName;
    }

    }
    ...


    @Override
    protected void initDataProperties() {

    ...

    // 2. Das Middleware-Feld "abschlussBemerkung" dem gewünschten Business-Feld im init-Block mappen.
    initLIMSProperty([Kunde]DataProperty.AbschlussBemerkung, String.class) //
    .applyFromProperty("interneBemerkung") //
    .register(this);

    ...

    }
    ...
    }

  • dataProvider.properties(Enthält Referenzen auf Implementierungen)

    Für die Einstellungen der App bietet die Datenverwaltungsinstanz-Implementierung "com.dialog.dialims.middleware.data.MobileAppDataManager" (analog zur Benutzerführung in der App) drei Teilbereiche, für die einzelne Implementierungen (java-Klassen, "Reducer") angegeben werden können. In nachfolgenden Unterabschnitten wird jeder Teilbereich beschrieben. com.dialog.middleware.MobileAppDataManager.reducer.TERMIN

    • Standardwert: "com.dialog.dialims.middleware.data.reducer.impl.TerminReducer". Die Klasse gibt an, welche Datensätze (Aufträge, Aktivitäten, usw.) als Termine in der App angezeigt werden sollen und welche Attribute wo angezeigt bzw. wie diese geändert werden können (Methodeinit()). Neben der Zuordnung zwischen den Feldern der App und des diaLIMS kann auch bei änderbaren Attributen eine Validierung definiert werden um ungültige Eingaben zu vermeiden. Des Weiteren kann hier auch der Filter angepasst werden, der für das Laden der Daten verwendet wird (Methode getFilter(String)).

    • Die Konfiguration der Option 'ProbenahmeTerminDataType' erlaubt die Anzeige von Aufträgen bzw. Touren. Diese sind wie folgt:

      • Auftrag (Option 'Order')

        PositionBeschreibung
        oben, links
        • Termin Start/Ende
        • uftrag.terminbegin, Auftrag.terminende
        • Wenn kein Terminbegin gesetzt ist wird ein rotes Kalendar-Icon angezeigt.
        oben, rechts
        • n Proben
        • Anzahl der Proben für diesen Termin, Anzahl wird vom Server übermittelt, nicht von der App
        mitte, links
        • Adresse
        • Auftrag.laAstrasse, Auftrag.laAort
        unten, links
        • Auftraggeber Kunde
        • Auftrag.agKunde.beschreibung
        Feldname bzw. Anzeigename in der AppdiaLIMS-FeldBemerkung
        Standort auf der KarteAuftrag.laAstrasse, Auftrag.laAortEs wird Google-Maps benötigt
        Feldname bzw. Anzeigename in der AppdiaLIMS-FeldBemerkung
        Auftrag (Termin)Auftrag.kurzbezeichnungnicht änderbar
        BeschreibungAuftrag.beschreibungnicht änderbar
        Auftraggeber KundeAuftrag.agKundenicht änderbar
        OrtAuftrag.laAortnicht änderbar
        StraßeAuftrag.laAstrassenicht änderbar
        TerminbeginAuftrag.terminBeginänderbar
        TerminendeAuftrag.terminEndeänderbar
        Auftraggeber AnsprechpartnerAuftrag.agAnsprechpartnernicht änderbar
        Information ProbennehmerAuftrag.bemerkungnicht änderbar
        UnterschriftAuftrag.dokumentVectorWird als Bildergebnis an dem Auftrag gespeichert. Werden als Dokumente angefügt und müssen den Schalter "Veröffentlicht" aktiviert haben. Bei neuen Dateien aus der App wird der Schalter "Veröffentlicht" am Dokument automatisch gesetzt. Unterstützt werden die Datei-Formate: jpeg, jpg und png. Für die Zuordnung an den richtigen Benutzer wird nach dem Muster auftrag_[Benutzer.kurzbzeichnung]_*.[Dateiendung] gesucht.
      • Tour (Option 'Routing')

        PositionBeschreibung
        oben, links
        • Termin Start/Ende
        • Tour.tourDatum, Tour.tourDatumBis
        • Wenn kein Terminbegin gesetzt ist wird ein rotes Kalendar-Icon angezeigt.
        oben, rechts
        • n Proben
        • Anzahl der Proben für diesen Termin, Anzahl wird vom Server übermittelt, nicht von der App
        mitte, links
        • Tour Typ
        • Tour.typ
        unten, links
        • Tour Beschreibung
        • Tour.beschreibung
        Feldname bzw. Anzeigename in der AppdiaLIMS-FeldBemerkung
        Tour (Termin)Tour.kurzbezeichnungnicht änderbar
        BeschreibungTour.beschreibungnicht änderbar
        Tour-DatumTour.tourDatumnicht änderbar
        Tour-Datum bisTour.tourDatumBisnicht änderbar
        EntnahmestellenTour.entnahmestelleZuordnungVectornicht änderbar. Nummerierte Auflistung der in der Tour enthaltenen Entnahmestellen.
        Hinweis ProbennahmeTour.hinweisProbennahmenicht änderbar
        UnterschriftTour.dokumentVectorWird als Bildergebnis an der Tour gespeichert. Werden als Dokumente angefügt und müssen den Schalter "Veröffentlicht" aktiviert haben. Bei neuen Dateien aus der App wird der Schalter "Veröffentlicht" am Dokument automatisch gesetzt. Unterstützt werden die Datei-Formate: jpeg, jpg und png. Für die Zuordnung an den richtigen Benutzer wird nach dem Muster auftrag_[Benutzer.kurzbzeichnung]_*.[Dateiendung] gesucht.

    com.dialog.middleware.MobileAppDataManager.reducer.PROBENAHME

    • Standardwert: "com.dialog.dialims.middleware.data.reducer.impl.ProbeNahmenReducer". Gibt an, welche Attribute der Proben wo angezeigt bzw. wie diese geändert werden können (Methodeinit()). Des Weiteren kann hier auch der Filter angepasst werden, der für das Laden der Proben verwendet wird (Methode getFilter(String)). Standardmäßig werden nur Proben geladen, die min. ein Parameter für die Probennahme vor Ort haben und nicht storniert sind. Auch der angemeldete Benutzer ist relavant, da nur Proben geladen werden, die ihm über das Feld Probennehmer zugeordnet sind. Sollte dem Benutzer ein Standort zugeordnet sein (Kunde am Benutzer mit entsprechender Standortmarkierung), werden auch nur Proben geladen, die den gleichen Standort haben.

      hinweis

      Die Standortzugehörigkeit wird erst ab diaLIMS-Version 2026.1 berücksichtigt.

      PositionBeschreibung
      oben, links
      • Mieter oder Kurzbezeichnung
      • Probe.mieter oder Probe.kurzbezeichnung
      • Wenn ein Mieter gesetzt ist, dann wird dieser angezeigt, sonst die Kurzbzeichnung der Probe
      oben, rechts
      • Probe Art
      • Probe.art
      mitte, links
      • Etage und Wohnung
      • Probe.hauptstelle.adresse3, Probe.hauptstelle.beschreibung
      mitte, rechts
      • Produkt
      • Probe.produkt.beschreibung
      unten, links
      • Raum und Entnahmestelle
      • Probe.hauptstelle.kurzbezeichnung, Probe.hauptstelle.adresse2
      unten, rechts
      • Objekt und n Behälter
      • Probe.organisation.beschreibung , Probe.probeContainerZuordnungVector.size
      • Anzahl der benötigten Behälter für die Probennahme, Anzahl wird vom Server übermittelt, nicht von der App, Wird nur angezeigt, wenn auch Behälter der Probe zugeordnet sind.
      Feldname bzw. Anzeigename in der AppdiaLIMS-FeldBemerkung
      GefäßProbe.gefaessBarcode, durchs Einscannen änderbar
      ProduktProbe.produkt.beschreibungnicht änderbar
      ObjektProbe.organisation.beschreibungnicht änderbar
      EtageProbe.hauptstelle.adresse3nicht änderbar
      WohnungProbe.hauptstelle.beschreibungnicht änderbar
      MieterProbe.hauptstelle.ansprechpartnernicht änderbar
      RaumProbe.hauptstelle.kurzbezeichnungnicht änderbar
      EntnahmestelleProbe.hauptstelle.adresse2nicht änderbar
      ArtProbe.artnicht änderbar
      Probenahme amProbe.nahmedatum + Probe.nahmezeitwird automatisch durch die App gesetzt
      BemerkungProbe.bemerkungänderbar
      Kein ZugangProbe.entnahmeNichtMoeglichänderbar
      FotosProbe.dokumentVectorWerden als Dokumente angefügt und müssen den Schalter "Veröffentlicht" aktiviert haben. Bei neuen Dateien aus der App wird der Schalter "Veröffentlicht" am Dokument automatisch gesetzt. Unterstützt werden die Datei-Formate: jpeg, jpg und png.

    com.dialog.middleware.MobileAppDataManager.reducer.PROBENAHME_ERFASSUNG

    • Standardwert: "com.dialog.dialims.middleware.data.reducer.impl.ProbeNahmenErfassungReducer". Steuert die Datenzuordnung zwischen der App und der Probenergebnisse (Methodeinit()). Des Weiteren kann hier auch der Filter angepasst werden, der für das Laden der Ergebniszuordnungen verwendet wird (Methode getFilter(String)).

      Feldname bzw. Anzeigename in der AppdiaLIMS-FeldBemerkung
      Beschriftung (Bezeichnung des Parameters)ProbeErgebnisZuordnung.ergebnis.beschreibungnicht änderbar
      OrdnungProbeErgebnisZuordnung.aOrdnung + 10.000*ProbeErgebnisZuordnung.eOrdnungnicht änderbar und nicht sichtbar
      MesswertProbeErgebnisZuordnung.ergebnisWertVector.wertänderbar
      EinheitProbeErgebnisZuordnung.einheit.kurzbezeichnungnicht änderbar
      hinweis

      Nach jeder durchgeführten Konfiguration muss der Server neugestartet werden.

      Die Anpassung der Reducer-java-Dateien erfordert einer erneute Kompilierung dieser.

      Damit die Termine in der App angezeigt werden können, müssen diese bestimmte Bedingungen erfüllen.

diaLIMS-Objekt

Bedingung

Benutzer

Benutzer ist zugelassen und Berechtigung LOGIN_APP ist vorhanden. Dem Benutzer ist die Benutzergruppe App zugeordnet.

Auftrag

Terminende ist gesetzt, Terminende liegt zwischen -2 Monaten und +3 Monaten. Der Status des Auftrag ist nicht freigegeben oder storniert

Tour

Terminende ist gesetzt, der Status der Tour ist nicht fertiggestellt oder storniert.

Termin ende liegt zwischen -7 Tagen und +X Tagen gemäß Option 'IncludeNotAssignedTourenOfNextDays' für nicht zugeordnete Touren (ab Version 2024.5c1).

Terminende liegt zwischen -2 Monaten und +3 Monaten für zugeordnete Touren.

Probe

Probennehmer (Probe.betreuer) entspricht dem Benutzer der App für zugeordnete Aufträge/Proben oder ist leer an allen Proben einer nicht zugeordneten Tour. Nahmedatum & Nahmezeit sind leer. Der Status der Probe ist nicht storniert.

Ergebnis

Messung vor Ort ist ausgewählt

Konfigurationen für die App lassen sich über die Klasse com.dialog.dialims.middleware.data.service.AppConfigServiceImpl steuern.

Einstellung

Beschreibung

Gefäßnummer generieren

In der App lassen sich Gefäßnummern generieren. Das Pattern dafür lässt sich über die Middleware konfigurieren. Dieses setzt sich aus drei Teilen zusammen.

  • {kuerzel}: Ein Kürzel welches für die Gefäßnummer verwendet wird. Standard: Benutzer.kurzbezeichnung
  • {dateformat}: Das Datumsformat. Standard: yyMMdd
  • {increment}: Eine fortlaufende Nummer, die täglich zurückgesetzt wird. Das Standartformat ist {kuerzel}-{dateformat}{increment}. Dies entspricht für das zweite Inkrement bei einem Bentuzer mit dem Kürzel XY und dem Datum 01.03.2021 folgender Gefäßnummer: XY-2103012

Termin Konfigurationen

In der App lassen sich bestimme Funktionen für die Termine aktivieren:

  • Termin selbst zuordnen {TerminSelbstZuordnen} (ab Version 2024.5c1): Aktiviert die Verwaltung von nicht zugeordneten Terminen über die App. Der Anwender kann sich in der App Termine aus einem Pool von nicht zugeordneten Datensätzen Termine selbst zuordnen ("übernehmen") oder sich von noch nicht angefangene Terminen austragen ("lösen").
  • Termin abbrechen {CancelTermin}: Erlaubt es einem Probennehmer einen Termin (Auftrag oder Tour) abzubrechen.
  • Probe erstellen {CreateProbe}: Erlaubt es einem Probennehmer neue Proben zu erstellen.
  • Entnahmestelle bearbeiten {EditEntnahmestelle}: Erlaubt es einem Probennehmer die Entnahmestelle zu ändern.
  • Proben Abschluss erzwingen {SampleFinishEnforceable}: Erlaubt es einem Probennehmer Proben abzuschießen, auch wenn es nicht ausgefüllte Pflichtfelder gibt.

Proben Abschluss erzwingen

Mit dieser Option lassen sich in der App Probenahmen abschließen, auch wenn es nicht ausgefüllte Pflichtfelder gibt. Diese Funktion lässt sich über die "Termin Konfigurationen" auf der Middleware aktivieren.

Wenn die Option aktiviert ist, wird in der App beim Abschluss einer Probe, die noch offene Pflichtfelder hat, die Schaltfläche "Trotzdem abschließen" angezeigt.

Beim Ausführen von "Trotzdem abschließen" wird die Probe abgeschlossen, die nicht ausgefüllten Pflichtfelder werden in der Abschlussbemerkung gepflegt.

Im Standard wird die Abschlussbemerkung auf der Middleware in das Feld ProbeReducer.DataProperty.AbschlussBemerkung geschrieben. Es kann vorkommen, dass die Abschlussbemerkung auf ein bereits existierendes Feld gemappt werden soll. In diesem Fall lässt sich dies mit der Option "{LogField}" auf der Middleware einstellen.

  • {LogField}: Konfiguriert das Feld, an das die Abschluss-Bemerkung angehängt wird. Als Beispiel könnten wir den Wert "$.bemerkungPN" für LogField konfigurieren, die Abschluss-Bemerkung wird dann an das Feld ProbeReducer.DataProvider.Bemerkung (bemerkungPN) angehängt.
# Konfiguration der Eingabefelder

Um Fehler bei der Benutzereingabe zu minimieren, wird die Art der Eingabe über die Middleware konfiguriert. In der App werden für die unterschiedlichen Eingaben entsprechende Eingabefelder angeboten.

Nachkommastellen konfigurieren: Die Nachkommastellen werden von der Middleware über die Erweiterung "nks" angegeben. Dafür muss an einem Nummern-Feld die Erweiterung "nks" gepflegt werden.


initProperty(Property.Messwert, String.class) //
...
.putExtension(zpae -> Map.entry("nks", 2)) //
...
.register(this);

Diese Erweiterung greift aktuell nur für die Messwerte. (ZPAE)

Datumsfelder konfigurieren (ab 2026.3): Die Darstellung von Datumsfeldern wird von der Middleware über die Erweiterung "format" eingestellt. Dafür muss an einem Datums-Feld die Erweiterung "format" gepflegt werden. Zur Auswahl stehen hierfür "date"(Nur Datum), "time"(Nur Zeit) und "date_time"(Datum und Zeit). Die Erweiterung steuert neben der Darstellung auch den DateAndTimePicker bei der Bearbeitung der Felder.


initProperty(Property.ProbenahmeAm, Date.class) //
...
.putExtension(p -> Map.entry("format", "date")) //
...
.register(this);

Maximale Zeichenlänge konfigurieren: Die maximale Zeichenlänge wird von der Middleware über die Erweiterung "setMaxLength" angegeben. Dafür muss an einem Feld die Methode "setMaxLength" aufgerufen werden.


initProperty(Property.Messwert, String.class) //
...
.setMaxLength(zpae -> 20) //
...
.register(this);

  • Entnahmestelle-Felder

    Die Felder für die Entnahmestelle sind anders benannt als man diese vom Standard erwartet. Die Tabelle stellt das Mapping der Felder dar.

Middleware/App

diaLIMS

Objekt

Probe.Probenstelle.beschreibung

Straße

Probe.Haupstelle.adresse1

Etage

Probe.Haupstelle.adresse3

Wohnung

Probe.Haupstelle.beschreibung

Mieter

Probe.Haupstelle.ansprechpartner

Raum

Probe.Haupstelle.kurzbezeichnung

Entnahmestelle

Probe.Haupstelle.adresse2

- **Entnahmestellen ändern**
In der App lässt sich die Entnahmestelle ändern. In der Proben-Details-Ansicht lässt sich im Menu die Aktion "Entnahmestelle ändern" ausführen Zur Auswahl stehen dann alle Haupstellen der Probenstelle zur Verfügung.

Wird eine andere Entnahmestelle ausgewählt, dann wird die Auswahl im Feld "Wohnung" dargestellt.

Referenzen, die in Verbindung mit der Entnahmestelle stehen werden zurückgesetzt. Das betrifft die Felder Etage, Mieter, Raum und Entnahmestelle. Diese Felder werden nach einer Synchronisierung entsprechend wieder befüllt.

Client-Implementierungen

Für die Kommunikation mit der Middleware wird auf der anderen Seite eine passende Client-Implementierung benötigt. Eine mögliche Implementierung für die Datenverwaltungsinstanz "MobileAppDataManager" stellt die diaLIMS-App für die mobile Probenerfassung dar. Weitere Clients können individuell umgesetzt werden. So ist es auch denkbar eine Datenverwaltungsinstanz als Client zu implementieren um damit einen Datenaustausch zwischen zwei Middleware-Instanzen unterschiedlicher diaLIMS-Installationen zu ermöglichen.

Mobile Probenerfassung

Für die mobile Probenerfassung steht eine Android-App (Client-Implementierung) zur Verfügung, mit der Probenahmetermine eingesehen, geändert und durchgeführt werden können. Dazu unterstützt die App den Probennehmer von der Planung der Termine, über die Dokumentation und Erfassung von Vorortparametern bis zur Quittierung der durchgeführten Arbeiten mit einer Unterschrift auf dem Gerät. Die App kommuniziert bei Bedarf mit einer dafür eingerichteten Middleware und synchronisiert dabei die Probenahmeaufträge und die erfassten Daten mit dem Labor und dem mobilen Gerät automatisch und in Echtzeit.

Entwurf

Eine Probe ist ein Entwurf, wenn diese vom Probenehmer direkt aus der App erstellt wurde. Die Bedingung für einen Entwurf ist “Probe.haupstelle == null && Probe.erstellungsBenutzer == LoggedInUser()”.

Es können Proben aus der App herraus erstellt werden, hierfür ist eine Internetverbindung notwendig. Die Probe wird auf dem Server erstellt, dafür wird über Probe.auftrag.probeVector die erste Probe für die Duplizierung genutzt, d.h. die neue Probe erhält alle Eigenschaften der ersten Probe des Auftrags.

Die Duplizierung dieser Proben weicht vom Standard ab. Folgende Felder werden zusätzlich zurückgesetzt:

  • Probe.hauptstelle
  • Probe.gefaess
  • Probe.beschreibung
  • Probe.nahmedatum
  • Probe.nahmezeit

Nach der Duplizierung wird die Probe noch registiert, damit diese in der App angezeigt werden kann.

Eine Probe vom Typ Entwurf wird in der App mit einem Stift gekennzeichnet.

Alternative Entnahmestelle

In der App können alternative Entnahmestellen ausgewählt werden. Die alternativen Entnahmestellen werden über folgende Bedingung ermittelt: “HauptstelleController.getInstance().findByCriteria(eq("organisation", probe.getOrganisation())”

Wenn in der App auf der Probenahme-Seite eine alternative Entnahmstelle über "Entnahmestelle ändern" ausgewählt wurde, dann wird das Feld Bemerkung mit entsprechender Bemerkung ergänzt. Zusätzlich wird noch das Feld Probe.entnahmeAnErsatzstelle auf true gesetzt, dies ermöglicht es besser nachvollziehen zu können ob es eine Abweichung zur Planung gab.

Mehrere Gefäße scannen

Bei der Probenahme gibt es die Anforderung manchmal mehrere Gefäße einzuscannen, da eine größere Menge der Probe notwendig ist.

Für Proben, bei denen für eine Probennahme mehrere Gefäße eingescannt werden sollen, erfolgt die Konfiguration über die Middleware, dafür kann an einem Barcode-Feld die Erweiterung "isMultiple" konfiguriert werden.


initProperty(DataProperty.Gefaess, Barcode.class) //
...
.putExtension(p -> Map.entry("isMultiple", true)) //
...
.register(this);

Auftrag abschließen

Nachdem eine Probennahme abgeschlossen ist können Auftrage in der App abgeschlossen werden. Dafür wird auf der Probenübersicht ein Abschließen-Dialog angezeigt.

Hier hat man dann drei Optionen:

  • Abschließen indem eine Unterschriftberechtige Person, die Probenahme mit einer Unterschrift abschließt.
  • Abschließen ohne Unterschrift
  • Später abschließen

Der Abschließen-Dialog wird immer dann angezeigt, wenn keine Proben bearbeitet werden können. D.h. entwender alle Proben sind abgeschlossen oder haben den Schalter "kein Zugang" gesetzt.

Dokumente herunterladen (ab Version 2024.5c1)

Bei der Probenahme sind manchmal zusätzliche Informationen notwendig, die in Form von Dokumenten bereitgestellt werden. Die Dokumente können an der Probenstelle, Hauptstelle oder Unterstelle hinterlegt sein, diese müssen den Schalter "Veröffentlicht" gesetzt haben und dürfen nicht storniert sein.

Wenn die Bedingungen für die Dokumente erfüllt sind und der Probenehmer auf die Dokumente zugreifen darf, dann lassen sich diese auf der Proben-Übersichtseite unter dem Menüpunkt "Dokumente anzeigen" herunterladen. Das Herunterladen der Dokumente erfolgt in den Standard-Download-Ordner des Geräts.

Sollte das Herunterladen nicht funktioniert haben, dann wird eine Fehlermeldung mit entsprechender Anweisung angezeigt.

Datenbankabfragefilter für die diaLIMS-API

Um den Zugriff auf Datensätze eines bestimmten Typs durch die diaLIMS-API zu gewährleisten, müssen zusätzlich zu den SelectObject-Bedingungen auch korrespondierende SelectObject.CriterionFilter-Bedingungen erstellt werden. Werden keine solchen Bedingungen angelegt, kann kein Zugriff auf entsprechende Datensätze erfolgen.

Gegeben sei folgende SelectObject-Benutzerbedingung:

try {
// Dies ist das Businessobjekt, auf dem die Bedingung geprüft werden kann:
o = Objekt;
// Dies ist der Attributname des Datensatzes oder
// der Typ ("ReferenzKlasse:") des Teildatensatzes:
por = PropertyNameOderReferenzKlasse;

// Ab hier die Bedingung formulieren. Es muss "false" oder "true" zurückgegeben werden.
if (por == null || por.equals("null")){
// Zugriff auf den Datensatztyp ist generell erlaubt
return true;
}
if (o != null && "P2016000066".equals(o.getKurzbezeichnung())) {
// Zugriff auf die Probe mit der genannten Kurzbezeichnung wird unterbunden
return false;
}
if(List.of("kurzbezeichnung", "beschreibung", "erstellungszeit", "nahmedatum",
"nahmezeit", "status", "kunde").contains(por)) {
// der Zugriff auf die genannten Felder bzw. Referenzen ist erlaubt
return true;
}

// restliche Zugriff wird unterbunden
return false;
}
catch (Exception e) {
return false;
}

Die Bedingung lässt den Zugriff auf folgende Attribute zu:

  • kurzbezeichnung
  • beschreibung
  • erstellungszeit
  • nahmedatum
  • nahmezeit
  • status
  • kunde

Zusätzlich wird der Zugriff auf die Probe P2016000066 unterbunden. Um den Zugriff auf alle Proben außer der P2016000066 zuzulassen, muss zusätzlich eine SelectObject.CriterionFilter-Bedingung definiert werden:

import org.hibernate.criterion.*;
import static org.hibernate.criterion.Restrictions.*;
import com.dialog.dialims.business.db.CriteriaHelper;

// Dies ist der angemeldete Benutzer:
u = Benutzer;
// Dies ist der Alias für verschachtelte Abfragen
a = Alias;

return [

// Einschränkung auf Kurzbezeichnung
ne(a + "kurzbezeichnung", "P2016000066")

] as Criterion[];

Diese zusätzliche Bedingung definiert, dass auf alle Proben zugegriffen werden kann, die nicht die Kurzbezeichnung P2016000066 haben. Werden in einer Abfrage Proben gesucht, wird die Probe P2016000066 niemals für die weitere Verarbeitung der Anfrage berücksichtigt. So kann verhindert werden, dass aus den resultierenden Ergebnissen einer Anfrage Rückschlüsse auf die Existenz einer Probe P2016000066 getroffen werden können.

REST-API

Authorisierung​

Request​

  • URL: http(s)://[Server-Adresse]/auth/login
  • Methode: POST
  • Content-Type: application/json
  • Parameter: username, password
  • Antwort-Typ: JSON

Beispiel​


POST /auth/login HTTP/1.1
Host: myserver.de:8080
Content-Type: application/json

{
"username": "user",
"password": "pass"
}

Antwort​


{
"accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxNDkxLjYxOTcuMyIsInNjb3BlcyI6WyJVU0VSI
l0sImlzcyI6ImRpYWxvZyIsImlhdCI6MTY1MDg5MDQ1MSwiZXhwIjoxNjUwOTAxMjUxfQ.
APFDxazHiUv-bSK3QEKJPuI8uSlQ8guoVzxyaAkABJM8Nr-WjHvF1fdYUbUqtYOm1JujrT
V8TQWkJo64pYStQw",
"refreshToken": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxNDkxLjYxOTcuMyIsInNjb3BlcyI6WyJSRUZS
RVNIX1RPS0VOIl0sImlzcyI6ImRpYWxvZyIsImp0aSI6ImU4YjgxODFlLTkxYzEtNGU5M
C1hY2Y4LWM3MjQ5NjM3NmNjOCIsImlhdCI6MTY1MDg5MDQ1MCwiZXhwIjoxNjUwOTc2OD
UwfQ.CJCn_lbl3AsoB_UOZUUXVhW5yCBB6V-Akd1WOvgf3eGDHLhhsk-Scw4nV0T7bl3Y
H9NZMZXfgiVbFeifclL8uw"
}

hinweis

Der Benutzer muss der Gruppe App zugeordnet sein, eine Standardgruppe zugeordnet haben und über die Berechtigung LOGIN_App verfügen.

Alternative: API-Key als Bearer-Token​

Statt /auth/login kann ein API-Key direkt im Header Authorization: Bearer {apiKey} gesendet werden. Dieser API-Key wird gegen diaLIMS validiert und für den aktuellen Aufruf wie ein authentifizierter Benutzer verarbeitet. Für wiederholte Aufrufe mit demselben API-Key nutzt die Middleware einen internen Kurzzeit-Cache.

Suche​

Über den REST-API-Endpoint search können beliebige Daten im JSON-Format geladen werden. Voraussetzung für den Zugriff ist ein gültiges Bearer-Token sowie vorkonfigurierte Benutzerbedingungen.

Request​

  • URL: http(s)://[Server-Adresse]/search
  • Methode: POST
  • Autorisierung: Header Authorization: Bearer {bearerToken}
  • Body: JSON-Objekt SEARCH_PARAMETERS
  • Antwort-Typ: JSON
hinweis

{bearerToken}: Entweder {accessToken} aus /auth/login oder ein API-Key.

Such-Parameter​

Struktur des Objekts SEARCH_PARAMETERS:

  • type

    Typ des Datensatzes, z.B. Probe, Auftrag, etc. (ohne Unterscheidung der Groß-/Kleinschreibung)

  • properties

    Ein Array von angefragten Feldern, die zu jedem Datensatz zurückgegeben werden sollen. Es können auch referenzierte (nicht direkte) Felder sein, wie z.B. kunde.kurzbezeichnung. Wenn leer oder nicht angegeben, werden nur OIDs von gefundenen Datensätzen zurückgegeben. (optional)

  • limit

    Maximale Anzahl der Datensätze, die pro Anfrageergebnis zurückgegeben werden sollen. (Standard-Wert 50, optional)

  • startIndex

    Start-Index des ersten Datensatzes in der Anfrage. (Nummeriert ab 1, Standard-Wert 1, optional)

  • filter

    Ein Array von Suchkriterien der Form ["{FELD}", "{VERGLEICH}", "{WERTE}"]. Wenn keine Suchkriterien in der Anfrage definiert sind, wird ein Bad-Request-Fehler zurückgegeben.

Struktur des Suchkriteriums:

  • {FELD} - Name des Feldes, es kann auch ein referenziertes (nicht direktes) Feld sein wie z.B. kunde.kurzbezeichnung
  • {VERGLEICH} - Vergleich.
  • {WERTE} - Eine einzelne String-Darstellung des Wertes oder ein Array.

Unterstützte Typen von {VERGLEICH}:

Typ

Anzahl der Werte

Beschreibung

Anwendbarer Datensatztyp

eq

1

Gleich

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Boolean, Status, Enums

ne

1

Nicht gleich

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Boolean, Status, Enums

lt

1

Kleiner

Date, Time, Timestamp, Integer, Double

le

1

Kleiner oder gleich

Date, Time, Timestamp, Integer, Double

gt

1

Größer

Date, Time, Timestamp, Integer, Double

ge

1

Größer oder gleich

Date, Time, Timestamp, Integer, Double

like

1

Änlich wie

String

isNull

0

Ist NULL

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Boolean, Enums

isNotNull

0

Ist nicht NULL

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Boolean, Enums

in

1..N

In

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Status, Enums

notIn

1..N

Nicht in

1:1-Referenzen, String, Date, Time, Timestamp, Integer, Double, Status, Enums

between

2

Zwischen

Date, Time, Timestamp, Integer, Double

Voraussetzungen für `{WERTE}` abhängig vom Typ des `{FELD}`s:

Typ des Feldes

Beschreibung

Beispiel

1:1-Referenz

OID des referenzierten Objektes

"1491.10574.2"

String

Zeichenkette mit dem gesuchten Text

"Muster GmbH"

Date

Datum im Format dd.MM.yyyy

"01.01.2022"

Time

Zeit im Format HH:mm:ss

"12:00:00"

Timestamp

Timestamp im Format dd.MM.yyyy HH:mm:ss

"01.01.2022 12:00:00"

Integer

String-Darstellung des Wertes

"25"

Double

String-Darstellung des Wertes

"25.5"

Boolean (Schalter)

String-Darstellung des Wertes

"true" oder "false"

Status

Kurzbezeichnung des Status

Für Stammdaten: "Z" - zugelassen, "G" - gesperrt, "S" - storniert.

Für Bewegungsdaten: "G" - geplant, "R" - registriert, "A" - in Arbeit, "W" - wartet auf Fertigstellung, "F" - fertiggestellt, "S" - storniert.

Enum

String-Darstellung des Wertes

"CSW"

### Zugreifbarkeit
  • Für jeden Datensatztyp (type) wird eine aktive "*.SelectObject"-Benutzerbedingung vorausgesetzt, die dem angemeldeten Benuzer über die Standardgruppe zugeordnet wird. Mit der Bedingung wird der Zugriff auf den Datensatztyp (allgemein) und auf die einzelnen Felder der Instanzen gesteuert. Liegt keine Berechtigung für den Datensatztyp vor oder der Datensatztyp existiert nicht, wird ein “400 - Bad Request: Object type is not valid.” Fehler zurückgegeben.
  • Für jeden referenzierten Datensatz (falls als Feld in der Liste properties angegeben), wird ebenfalls eine aktive "*.SelectObject"-Benutzerbedingung für den jeweiligen Typ benötigt. Liegt keine Bedingung vor oder verbietet diese den Zugriff, wird für das Feld der Wert “ <Not authorized!> ” als OID zurückgegeben.
  • Für jeden Datensatz in filter, der als Suchkriterium verwendet wird, wird der Fehler “400 - Bad Request: One of the properties not authorized or not available.” zurückgegeben, falls keine entsprechende aktive "*.SelectObject"-Benutzerbedingung für diesen Typ vorliegt, diese den Zugriff verhindert oder das Feld nicht existiert.

Beispiel​

Anfrage: Suche nach Proben des Kunden mit Kurzbezeichnung Muster GmbH, mit dem Nahmedatum zwischen 01.01.2022 und 31.12.2022 und mit dem Status Geplant oder In Arbeit.

Zurückgegeben werden sollen die Felder: art, kurzbezeichnung, beschreibung, produkt, nahmedatum, nahmezeit, aktivitaetVector, erstellungszeit, status.


POST /search HTTP/1.1
Host: myserver.de:8080
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxNDkxLjYxOTcuMyIsInNjb3BlcyI6WyJVU0VSI
l0sImlzcyI6ImRpYWxvZyIsImlhdCI6MTY1MDg5MDQ1MSwiZXhwIjoxNjUwOTAxMjUxfQ.APFDxaz
HiUv-bSK3QEKJPuI8uSlQ8guoVzxyaAkABJM8Nr-WjHvF1fdYUbUqtYOm1JujrTV8TQWkJo64pYStQw
Content-Type: application/json

{
"type": "probe",
"properties": ["art", "kurzbezeichnung", "beschreibung", "produkt", "nahmedatum", "nahmezeit", "aktivitaetVector", "erstellungszeit", "status"],
"limit": 10,
"startIndex": 1,
"filter": [
{
"property": "kunde.kurzbezeichnung",
"operator": "eq",
"value": "Muster GmbH"
},
{
"property": "nahmedatum",
"operator": "between",
"value": ["01.01.2022", "31.12.2022"]
},
{
"property": "status",
"operator": "in",
"value": ["G", "A"]
}
]
}

Antwort​


{
"version": "v14r0u",
"data": {
"properties": [
"art",
"kurzbezeichnung",
"beschreibung",
"produkt",
"nahmedatum",
"nahmezeit",
"aktivitaetVector",
"erstellungszeit",
"status"
],
"startIndex": 0,
"limit": 10,
"totalItems": 4,
"items": [
{
"OID": "1491.83.142",
"art": " <Not authorized!> ",
"kurzbezeichnung": "P2022000020",
"beschreibung": "Beispielprobe Kreuztabelle",
"produkt": " <Not authorized!> ",
"nahmedatum": "09.05.2022",
"nahmezeit": "13:40:18",
"aktivitaetVector": " [Collection] ",
"erstellungszeit": "01.05.2022 13:40:31",
"status": "A"
},
{
"OID": " <Not authorized!> "
},
{
"OID": "1491.83.252",
"art": " <Not authorized!> ",
"kurzbezeichnung": "P2022000067",
"beschreibung": "Beispielprobe Kreuztabelle",
"produkt": " <Not authorized!> ",
"nahmedatum": "06.05.2022",
"nahmezeit": "13:59:23",
"aktivitaetVector": " [Collection] ",
"erstellungszeit": "01.05.2022 13:42:18",
"status": "G"
},
{
"OID": "1491.83.269",
"art": " <Not authorized!> ",
"kurzbezeichnung": "P2022000068",
"beschreibung": "",
"produkt": " <Not authorized!> ",
"nahmedatum": "06.05.2022",
"nahmezeit": "13:59:23",
"aktivitaetVector": " [Collection] ",
"erstellungszeit": "01.05.2022 13:59:49",
"status": "A"
}
]
}
}

Benutzerbedingung Probe.SelectObject:


try {
// Dies ist das Businessobjekt, auf dem die Bedingung geprüft werden kann:
o = Objekt;
// Dies ist der Attributname des Objekts oder der Typ ("ReferenzKlasse:") des Teilobjekts:
por = PropertyNameOderReferenzKlasse;
// Ab hier die Bedingung formulieren. Es muss "false" oder "true" zurückgegeben werden.

if (por == null || por.equals("null")){
// Zugriff auf den Datensatztyp ist generell erlaubt
return true;
}
if (o != null && "P2016000066".equals(o.getKurzbezeichnung())) {
// Zugriff auf die Probe mit der genannten Kurzbezeichnung wird unterbunden
return false;
}
if(List.of("kurzbezeichnung", "beschreibung", "erstellungszeit", "nahmedatum", "nahmezeit", "status", "kunde").contains(por)) {
// der Zugriff auf die genannten Felder bzw. Referenzen ist erlaubt
return true;
}

// restliche Zugriff wird unterbunden
return false;
}
catch (Exception e) {
return false;
}

Benutzerbedingung Kunde.SelectObject:


try {
// Dies ist das Businessobjekt, auf dem die Bedingung geprüft werden kann:
o = Objekt;
// Dies ist der Attributname des Objekts oder der Typ ("ReferenzKlasse:") des Teilobjekts:
por = PropertyNameOderReferenzKlasse;
// Ab hier die Bedingung formulieren. Es muss "false" oder "true" zurückgegeben werden.

if (por == null || por.equals("null")){
// Zugriff auf den Datensatztyp ist generell erlaubt
return true;
}

if(por.equals("kurzbezeichnung")) {
// der Zugriff auf die genannten Felder ist erlaubt
return true;
}

// restliche Zugriff wird unterbunden
return false;
}
catch (Exception e) {
return false;
}

Verwenden von Schnellfiltern als Filterkriterien​

Beim Laden von Datensätzen über den REST-API-Endpoint kann ein Schnellfilter statt der Filterkriterien übergeben werden.


POST /search HTTP/1.1
Host: myserver.de:8080
Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxNDkxLjYxOTcuMyIsInNjb3BlcyI6WyJVU0VSI
l0sImlzcyI6ImRpYWxvZyIsImlhdCI6MTY1MDg5MDQ1MSwiZXhwIjoxNjUwOTAxMjUxfQ.APFDxaz
HiUv-bSK3QEKJPuI8uSlQ8guoVzxyaAkABJM8Nr-WjHvF1fdYUbUqtYOm1JujrTV8TQWkJo64pYStQw
Content-Type: application/json

{
"type": "probe",
"properties": ["art", "kurzbezeichnung", "beschreibung", "produkt", "nahmedatum", "nahmezeit", "aktivitaetVector", "erstellungszeit", "status"],
"limit": 10,
"startIndex": 1,
"filterOid": "{FILTER-OID}"
}

hinweis
  • {FILTER-OID}: OID eines Schnellfilters (einer entsprechenden Einstellung-Kategorie).
  • Ergänzend zu allgemeinen Berechtigungen wird eine aktive "SelectObject"-Benutzerbedingung für den Datensatztyp EinstellungKategorie vorausgesetzt.
  • Der angegebene Schnellfilter (entsprechende Einstellung-Kategorie) muss dem aktuellen Benutzer (ggf. über die Gruppe) zugeordnet sein.
  • Wenn der Schnellfilter angegeben ist, dürfen keine Filterkriterien übergeben sein.
  • Die maximale Anzahl der Datensätze (limit), die pro Anfrageergebnis zurückgegeben werden sollen, ist auf 1000 begrenzt.

Datensatz aktualisieren​

Über den REST-API-Endpoint update können Felder an Datensätzen geändert werden. Voraussetzung für den Zugriff ist ein gültiges Bearer-Token sowie vorkonfigurierte Benutzerbedingungen.

Request​

  • URL: http(s)://[Server-Adresse]/update
  • Methode: POST
  • Autorisierung: Header Authorization: Bearer {bearerToken}
  • Body: JSON-Objekt Update-Parameter
  • Antwort-Typ: JSON
hinweis

{bearerToken}: Entweder {accessToken} aus /auth/login oder ein API-Key.

Update-Parameter​

Struktur des Objekts:

  • type

    Typ des Datensatzes, z.B. Probe, Auftrag, etc. (ohne Unterscheidung der Groß-/Kleinschreibung).

  • oid

    ID des Objekts, das aktualisiert wird.

  • data

    Ein Array von UpdateData-Objekten. Gibt an, welches Feld auf welchen Wert gesetzt wird.

Struktur des UpdateData-Objekts:

  • property

    Der Feld-Name, in das geschrieben werden soll.

  • value

    Der Wert, auf den das Feld gesetzt wird. Wird das Feld nicht angegeben, wird null als Wert angenommen.

Format für value, abhängig vom Typ des propertys:

Typ des Feldes

Beschreibung

Beispiel

1:1-Referenz

OID des referenzierten Objektes

"1491.10574.2" oder null

String

Zeichenkette

"Muster GmbH"

Date

Datum im Format dd.MM.yyyy

"01.01.2022" oder null

Time

Zeit im Format HH:mm:ss

"12:00:00" oder null

Timestamp

Timestamp im Format dd.MM.yyyy HH:mm:ss

"01.01.2022 12:00:00" oder null

Integer

JSON-Number

25 oder null

Double

JSON-Number

25.5 oder null

Boolean (Schalter)

JSON-Boolean

true oder false

Status

Kurzbezeichnung des Status

Für Stammdaten: "Z" - zugelassen, "G" - gesperrt, "S" - storniert.

Für Bewegungsdaten: "G" - geplant, "R" - registriert, "A" - in Arbeit, "W" - wartet auf Fertigstellung, "F" - fertiggestellt, "S" - storniert.

Enum

String-Darstellung des Wertes

"CSW"

### Zugreifbarkeit
  • Für jeden Datensatztyp (type) wird eine aktive "*.UpdateObject"-Benutzerbedingung vorausgesetzt, die dem angemeldeten Benuzer über die Standardgruppe zugeordnet wird. Mit der Bedingung wird der Zugriff auf den Datensatztyp (allgemein) und auf die einzelnen Felder der Instanzen gesteuert. Liegt keine Berechtigung für den Datensatztyp vor oder der Datensatztyp existiert nicht, wird ein “400 - Bad Request: Object type is not valid.” Fehler zurückgegeben.
  • Liegen nicht alle notwendigen Bedingungen für einen Request vor, werden keine Daten geschrieben.

Beispiel​

Anfrage: Aktualisiere die drei Felder nahmedatum, bemerkung und kunde an der Probe mit der OID 1491.4261.39.


POST /update HTTP/1.1
Host: myserver.de:8080
Authorization: Bearer
Content-Type: application/json

{
"type": "probe",
"oid": "1491.4261.39",
"data": [
{
"property": "nahmedatum",
"value": "09.05.2022"
},
{
"property": "bemerkung",
"value": "Aktualisierte Bemerknung"
},
{
"property": "kunde",
"value": "1491.605.1067"
}
]
}

Antwort​


All data was written successfully

Benutzerbedingung Probe.UpdateObject:


try {
// Dies ist das Businessobjekt, auf dem die Bedingung geprüft werden kann:
o = Objekt;
// Dies ist der Attributname des Objekts oder der Typ ("ReferenzKlasse:") des Teilobjekts:
por = PropertyNameOderReferenzKlasse;
// Ab hier die Bedingung formulieren. Es muss "false" oder "true" zurückgegeben werden.

if (por == null || por.equals("null")){
// Zugriff auf den Datensatztyp ist generell erlaubt
return true;
}
if(List.of("nahmedatum", "bemerkung", "kunde").contains(por)) {
return true; // der Zugriff auf die genannten Felder bzw. Referenzen ist erlaubt
}

return false;// restliche Zugriff wird unterbunden
}
catch (Exception e) {
return false;
}

Ausführen von Businesslogiken​

Über den REST-API-Endpoint invoke können Businesslogiken aufgerufen werden. Voraussetzung für den Zugriff ist ein gültiges Bearer-Token sowie vorkonfigurierte Benutzerbedingungen.

Request​

  • URL: http(s)://[Server-Adresse]/invoke
  • Methode: POST
  • Autorisierung: Header Authorization: Bearer {bearerToken}
  • Body: JSON-Objekt Aufruf-Parameter
  • Antwort-Typ: JSON
hinweis

{bearerToken}: Entweder {accessToken} aus /auth/login oder ein API-Key.

Aufruf-Parameter​

Struktur des Objekts:

  • type

    Typ des Datensatzes, z.B. Probe, Auftrag, etc. (ohne Unterscheidung der Groß-/Kleinschreibung).

  • action

    ID des Objekts, das aktualisiert wird.

  • parameters

    Ein Array von Parametern, die der Businesslogik übergeben werden.

Format für die Parameter:

Typ des Feldes

Beschreibung

Beispiel

1:1-Referenz

OID des referenzierten Objektes

"1491.10574.2"

String

Zeichenkette

"Muster GmbH"

Date

Datum im Format dd.MM.yyyy

"01.01.2022"

Time

Zeit im Format HH:mm:ss

"12:00:00"

Timestamp

Timestamp im Format dd.MM.yyyy HH:mm:ss

"01.01.2022 12:00:00"

Integer

JSON-Number

25

Double

JSON-Number

25.5

Boolean (Schalter)

JSON-Boolean

true oder false

Status

Kurzbezeichnung des Status

Für Stammdaten: "Z" - zugelassen, "G" - gesperrt, "S" - storniert.

Für Bewegungsdaten: "G" - geplant, "R" - registriert, "A" - in Arbeit, "W" - wartet auf Fertigstellung, "F" - fertiggestellt, "S" - storniert.

Enum

String-Darstellung des Wertes

"CSW"

List

Liste von Datensätzen bzw. sonstigen Werten

[id.des.Datensatzes1", "id.des.Datensatzes2", "id.des.Datensatzes3"] bzw. [10.0, 10.5, 25.75]

### Zugreifbarkeit
  • Für jede aufrufbare Logik (action) und Typ (type) wird eine aktive "API.Action.{type}.*"-Benutzerbedingung vorausgesetzt, die dem angemeldeten Benuzer zugeordnet wird. Mit der Bedingung wird der Zugriff auf die Aktion gesteuert. Liegt keine Berechtigung für die Aktion vor oder der Datensatztyp existiert nicht, wird ein “400 - Bad Request: Object type is not valid.” Fehler zurückgegeben.

Beispiel​

Anfrage: Führt die Aktion CancelObject für eine Charge aus. Die Charge soll storniert werden.


POST /invoke HTTP/1.1
Host: myserver.de:8080
Authorization: Bearer
Content-Type: application/json

{
"type": "charge",
"action": "CancelObject",
"parameters": [
["1491.1010.396"]
]
}

Antwort​


true (Der Rückgabewert ist von der Aktion abhängig. Hier bedeutet true, dass der Statuswechsel erfolgt ist.)

Benutzerbedingung API.Action.Charge.CancelObject:


return true;