17. August 2017

synTechTalk: Ergänzen der comuny-API um weitere Funktionen

synTechTalk: Ergänzen der comuny-API um weitere Funktionen (pixabay.com / simplu27)

Im ersten Teil dieses Artikels haben wir begonnen, das Grundgerüst für eine Applikation, die die comuny API nutzt, zu erstellen. Über diese API können Anbieter aus verschiedenen Bereichen des Gesundheitswesens ihre eigenen Lösungen mit geringem Aufwand an die comuny Plattform „anschließen“ und so die Vorteile der comuny-Plattform Infrastruktur, wie sicheren Zugang und Datenschutzkonformität, nutzen.

Mit dem bisherigen Grundgerüst lassen sich Daten ablegen und abrufen; in diesem Teil werden wir Funktionen zum Ändern, Löschen und Teilen hinzufügen und unsere CRUD-Anwendung somit fertig stellen.

Bearbeitung eines Payloads

Daten, die in comuny abgelegt wurden, können natürlich auch wieder verändert werden. Da wir bereits einen Payload abgelegt haben und dessen RegistryEntry-ID kennen, können wir ganz einfach einen neuen Inhalt für diesen hinterlegen:

function editPayload(payloadId, content) {
    comunyPut('payloads/' + payloadId, {
        payload: content
    });
}

Als neuen Inhalt nehmen wir hier das auf die ersten zwei Worte gekürzte Lorem Ipsum in umgekehrter Reihenfolge.

Die Antwort gleicht der von der Erstellung des Payloads im ersten Teil dieser Dokumentation:

{
    "id": 65099,
    "contextId": 65097,
    "mimeType": null,
    "parent": null,
    "externalInfo": null,
    "orgId": null,
    "url": "/payloads/65099/dad62c9c-2b58-4326-8a3c-0e1f853f12e8/jackrabbit-jndi",
    "creationTime": "2017-07-18T19:14:43+02:00",
    "ownerId": 51884
}

Wenn wir den Payload über die URL aus der Antwort jedoch erneut anfragen, dann ist auch unser neuer Inhalt vorhanden:

{
    "payload": "Ipsum lorem."
}

Löschen eines RegistryEntrys

Da der jeweilige Benutzer bei comuny zu jeder Zeit die volle Kontrolle über seine Daten hat, können einzelne RegistryEntrys nach Belieben gelöscht werden. Dazu wird lediglich die ID benötigt:

function deleteRegistryEntry(registryEntryId) {
    comunyDelete('registryEntry/' + registryEntryId);
}

Die Antwort teilt uns nur mit, dass die Aktion wie gewünscht ausgeführt wurde:

{
    "message": "Successfully deleted RegistryEntry."
}

Listen wir nun noch einmal alle Payloads des Contexts auf, so sehen wir, dass der Eintrag wirklich verschwunden ist. In diesem Fall war er der einzige vorhandene Eintrag, dementsprechend erhalten wir ein leeres Array:

[]

Löschen eines Contexts

Selbstverständlich kann auch ein ganzer Context auf einmal gelöscht werden. Dabei ist jedoch Vorsicht geboten, da so auch alle darin enthaltenen Payloads entfernt werden. Der Aufruf funktioniert analog zum RegistryEntry:

function deleteContext(contextId) {
    comunyDelete('contexts/' + contextId);
}

In der Antwort wird ebenfalls nur mitgeteilt, dass das Löschen erfolgreich war:

{
    "message": "Context with id '65097' was removed successfully."
}

Teilen von Daten

Nachdem wir jetzt die grundlegenden CRUD-Funktionalitäten kennen, nun ein weiteres wichtiges Element der Anwendung: Das Teilen von Daten. Hierbei kann der Benutzer individuell entscheiden, welche Daten er mit wem teilen möchte, und welche Rechte der Gast haben soll. Soll beispielsweise ein Context zum Sammeln von verschiedensten Fitnessdaten eingerichtet werden, so kann den entsprechenden Accounts der Fitnesstracker die Depositor-Rolle zugewiesen werden. Diese erlaubt das Erstellen von neuen Payloads, nicht jedoch das Lesen oder Ändern von bestehenden Payloads.

Hinzufügen einer Person

Um einem anderen Nutzer Zugriff auf einen Context zu geben, muss er zu diesem hinzugefügt werden. Dazu wird die Context-ID sowie die comuny-ID (also die E-Mail-Adresse) des Gastes benötigt:

function addPersonToContext(contextId, emailAddress) {
    comunyPost('contexts/' + contextId + '/persons', {
        email: emailAddress
    });
}

Antwort:

{
    "id": 65239,
    "personId": 64078,
    "organizationId": null,
    "contextId": 65097,
    "ewsRoleId": null,
    "status": "OK",
    "authority": "EwsContextGuest"
}

Hier sehen wir, dass ein Gast zu Beginn automatisch die Rolle EwsContextGuest besitzt. In der Dokumentation gibt es dazu auch eine Rollen-Rechte-Matrix (Kapitel 7).

Grundsätzlich können wir unseren Context nur mit Benutzern teilen, die ebenfalls über einen aktiven comuny Account verfügen. Wenn wir eine E-Mail-Adresse, die keine comuny-ID ist, zu unserem Context einladen, so wird comuny an die betreffende E-Mail-Adresse eine Einladung zur Registrierung schicken. In diesem Fall hat der Status in der Antwort den Wert „PLACEHOLDER“.

Ändern der Rolle einer Person

Möchten wir nun wie im oben genannten Beispiel dem Gast lediglich Rechte zum Erstellen von neuen Dateien geben, so müssen wir seine Rolle ändern. Dazu benötigen wir die Context-ID, die Participant-ID (aus der letzten Antwort) und den Namen der Rollen (in unserem Beispiel EWSDepositor):

function setRole(contextId, participantId, role) {
    comunyPut('contexts/participants/role', {
        id: participantId,
        contextId: contextId,
        authority: role
    });
}

Die Antwort gleicht der aus dem letzten Schritt, wir können jedoch sehen, dass unsere Rolle korrekt gesetzt wurde:

{
    "id": 65239,
    "personId": 64078,
    "organizationId": null,
    "contextId": 65097,
    "ewsRoleId": null,
    "status": "OK",
    "authority": "EWSDepositor"
}

Entfernen von Personen

Für den Fall, dass wir wieder alleinigen Zugriff auf unsere Daten haben möchten, entfernen wir die eingeladene Person ganz einfach. Dazu brauchen wir die gleichen Daten wie bei der Einladung:

function removePersonFromContext(contextId, emailAddress) {
    comunyDelete('contexts/' + contextId + '/persons', {
       email: emailAddress
    });
}

In der Antwort ist auch hier nur eine Bestätigung enthalten:

{
    "message": "Removing guest with email workshop@comuny.de from context with id: 65097 was successfull."
}

Wie geht es weiter?

Mit diesen Beispielen und der Dokumentation bewaffnet stehen uns nun alle Möglichkeiten offen. Ein paar Ideen gefällig?

Wie wäre es mit einer simplen To-do-App? Dabei könnte eine Liste ein Context und die einzelnen Einträge jeweils ein RegistryEntry sein. So würde ein Eintrag nicht nur aus Text bestehen, sondern auch aus einem Bild, da ein RegistryEntry einen MIME-Type besitzt.

Eine etwas anspruchsvollere Anwendung wäre ein Kollaborationstool, das Ärzte bei komplizierten Fällen für gegenseitige Hilfestellung nutzen können. Hier kann der Patient über die Weitergabe seiner Daten entscheiden, da er die Ärzte zum entsprechenden Context einladen muss.

Haben Sie Fragen oder Anregungen zu comuny, der comuny API oder der weiteren Nutzung der CRUD-Anwendung? Wir freuen uns auf einen Austausch und auf kreative Ideen, die mit comuny umgesetzt werden!

(Paul Gerste)

In unserer Reihe synTechTalk geben unsere DEV und OPS Teams Einblicke in ihr Technologie- und Architektur-KnowHow zur Umsetzung erfolgreicher digitaler Geschäftsmodelle.

Keine Kommentare


Dein Kommentar:

* Pflichtfelder

Time limit is exhausted. Please reload CAPTCHA.