Sormas integration

[rennrennrenn]

https://www.dropbox.com/scl/fi/hbq12qb7ynz9r0hkl32nf/Recover-App-%E2%86%92-SORMAS-%C3%96GD-Integration.paper?dl=0&noDesktopRedirect=1&open_id=server-69e9291d-70ae-4b4e-83fc-2d3a5445f7c9&parent_frame_referrer=&rlkey=iqzpklf1o9eqt4h6yjt67owbv

[hey-johnnypark]

@rennrennrenn Update from my side.

I am trying to build the project based on https://github.com/hzi-braunschweig/SORMAS-Project/blob/development/DEVELOPMENT_ENVIRONMENT.md. However it is a complex project that uses Java Vaadin, EAP, Glassfish (Enterprise stack).

My idea is now to focus on trying the integration with a running test system:

https://demoversion.sormas-oegd.de/

My first tries failed so I reached out to the developer chat again which was quite useful the last time.

https://gitter.im/SORMAS-Project/sormas-questions?source=orgpage

[hey-johnnypark]

Hi,

quick update. I got access to the REST API of https://demoversion.sormas-oegd.de.

However, the documentation is not 100% clear so I am trying to reverse engineer the REST calls.

Stay tuned.
Andi

[hey-johnnypark]

SORMAS Rest API

SORMAS Datenmodell

FALL: Ein bestätigter Fall von Coronavirus, der über ein positives Testergebnis an das GA weitergeleitet wurde.
KONTAKT: Ein Kontakt einer anderen Person mit der Person aus dem FALL.
PERSON: Eine Person die zum KONTAKT gehört.

Dabei ist die Relation folgende:

FALL 1 -> n KONTAKT 1 -> 1 PERSON

Beispiel Recover:

Die Person aus einem Fall war in Gastronomie A am Tag X zwischen Y und Z.

In diesem Fall muss Recover folgende Daten erstellen:

n = Anzahl der Checkins in Restaurant (oder Bereich) am Tag X zwischen Y und Z

n * PERSON
n * KONTAKT

Jedem KONTAKT ist dabei eine PERSON zugewiesen.

Review Rest API

Positiv:

• Es gibt eine REST Schnittstelle für die Integration von Recover App Daten. Ein Testlauf mit Testdaten und Test Credentials hat funktioniert.

Optimierungsbedarf:

• Die IDs von neuen KONTAKT und PERSON muss auf Client Seite (Recover App) erzeugt werden. Das ist nicht RESTful.
• Das Feedback im Fehlerfall ist unzureichend. In den meisten Fällen bekommt man einen 500er Server Error zurück.
• Beim jedem API call muss die UUID des aktuellen Benutzers (Beispiel: SurvOff) mit angegeben werden. Das erhöht den Aufwand beim Client.

Anleitung zum erstellen eines Kontaktes über die API.

Wir starten mit dem Anlegen eines Falles (das würd das GA machen)

1. Log dich auf der SORMAS Testseite ein.

https://demoversion.sormas-oegd.de/sormas-ui/login

Username: SurvOff
Password: SurvOff

2. Erstelle einen neuen Fall.

Fälle -> + Neuer Fall

Melde Datum: Aktuelles Datum über DateTimePicker
Vorname: Foo
Nachname: Foo
Geschlecht: Divers
Einrichtung: Zu Hause

3. Copy dir die Fall ID

Jetzt kommen wir zum API call (das würde Recover App machen)

4. Erstelle erst mal eine Person. Dafür brauchst du frische UUID (https://www.uuidgenerator.net/)

curl --location --request POST 'https://demoversion.sormas-oegd.de/sormas-rest/persons/push' \
--header 'Authorization: Basic U3Vydk9mZjpTdXJ2T2Zm' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "uuid": "<DEINE frische UUID>",   # Das ist die eindeutige ID der PERSON. Diese kann über https://www.uuidgenerator.net/ generiert werden. Setzt man sie nicht oder benutzt man die selbe ID noch einmal, bekommt man einen 500er Server Fehler
        "firstName": "Kontakt",
        "lastName": "von Recover",
        "sex": "OTHER"
    }
]'

5. Erstelle jetzt einen Kontakt. Dafür brauchst du zwei frische UUIDs (https://www.uuidgenerator.net/)

curl --location --request POST 'https://demoversion.sormas-oegd.de/sormas-rest/contacts/push' \
--header 'Authorization: Basic U3Vydk9mZjpTdXJ2T2Zm' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "uuid": "<DEINE erste frische UUID>", # Das ist die eindeutige ID des KONTAKTes. Diese kann über https://www.uuidgenerator.net/ generiert werden. Setzt man sie nicht oder benutzt man die selbe ID noch einmal, bekommt man einen 500er Server Fehler
        "caze": {
            "uuid": "<DIE Fall UUID aus Step 3) >" # Das ist die eindeutige ID des Falles die wir vorher im Webinterface kopiert haben. Später können wie diese ID über Recover ermitteln, indem der GA Mitarbeiter die ersten 6 Stellen mitteilt. 
        },
        "disease": "CORONAVIRUS",
        "reportDateTime": 1611232518,
        "reportingUser": {
            "uuid": "TN2E4T-2OUTRL-FUFFX2-BMACKCDU".   # Siehe oben, die UUID sollte sich eigentlich aus den User credentials ableiten. 
        },
        "contactClassification": "UNCONFIRMED",
        "person": {
            "uuid": "<Die Person UUID aus Step 4)>"           # Das ist die eindeutige ID der Person die wir vorher angelegt haben.   
        },        
        "healthConditions": {
            "creationDate": 1611232518,            
            "uuid": "<DEINE zweite frische UUID>"            # Muss generiert werden über https://www.uuidgenerator.net/ . Sollte man die nicht setzen, bekommt man einen 500er Fehler. 
        },
        "contactProximity": "SAME_ROOM",
        "contactProximityDetails": "Besuch der selben Einrichtung am 20.01. zwischen 14:00 und 16:00",
        "contactCategory": "LOW_RISK",
        "followUpStatus": "FOLLOW_UP",
        "followUpComment": "Telefon Nummer aus Recover App 03012312312213"        
    }
]'

Jetzt können wir den Kontakt im Web Interface sehen

Postman

Eine Postman collection gibt es hier https://github.com/railslove/recover-backlog/blob/main/SORMAS.postman_collection.json.

Diese kann man in Postman importieren und step by step ausführen.

Postman hat den Vorteil, dass es UUIDs generieren kann.

[koos]

Pics for the Blogpost

[koos]

Kommentar von Sormas selbst:

Zwei Anmerkungen:
6:29
SORMAS-Foundation/SORMAS-Project#4086 (edited)
6:29
Das fixed das Problem mit den UUIDs 🙂
6:31
Under der 500 Server Error ist behoben und sollte auch mit einer brauchbaren Fehlermeldung antworten. Ich habe den PR gereviewt finde ihn aber nicht mehr gerade 😄
6:31
Also in der neuen 1.55 version sollte das gegessen sein 🙂 (edited)
6:32
ah hier SORMAS-Foundation/SORMAS-Project#4000 (edited)
6:32
super hilfreich auf jeden Fall euer Post!
6:33
Wir sind eh gerade dran einiges besser zu machen, also falls du sonst noch Anmerkungen hast gerne melden und dann können wir telefonieren 🙂
white_check_mark
eyes
raised_hands

6:35
Und da jetzt auch bald SORMAS Angular kommt, kann man auch bald BEARER tokens nehmen statt UUID and http standard auth (edited)