Userprofile-App

User Profile-App

 Einleitung

In diesem Thema findest Du allgemeine Informationen zur User Profile-App, dem Funktionsumfang, sowie zu den Kenntnissen, die hilfreich beim Programmieren von Funktionen und Anpassungen sind.

 Funktionsumfang von User Profile-App

Die User Profile-App stellt eine Übersichtseite für den aktuellen Benutzer bereit. Außerdem wird die Verwaltung der eigenen Abwesenheit ermöglicht. Du kannst den Abwesenheitsstatus sowie zugehörige weitere Informationen mit einer REST-API abfragen und ändern. Außerdem hast du die Möglichkeit, einen Benachrichtigungspfad für deine App festzulegen, welcher bei Änderungen der Abwesenheit von Benutzern aufgerufen wird, sodass du sofort auf die Änderungen reagieren kann.

 Verwenden der API-Funktionen

Die User Profile-App stellt eine API-Schnittstelle zur Verfügung, mit der du folgende Aktionen ausführen kannst:

 Abrufen des Abwesenheitsstatus und der Abwesenheitsinformationen eines Benutzers

Um den aktuellen Abwesenheitsstatus sowie weitere Abwesenheitsinformationen eines Benutzers abzurufen, muss deine App eine GET-Abfrage an die User Profile-App senden.

Request


GET /userprofile/api/absence[?userId=11A5C79F-D9AB-498B-9158-D3034B7E45E5]
Accept: application/json

Hinweis zum Parameter

ParameterBeschreibung
userIdOptional. Ein Query-Parameter, den du zum Abrufen des Abwesenheitsstatus eines anderen Benutzers verwenden kannst. Wenn du den Parameter nicht verwendest, werden die Informationen des aktuell angemeldeten Benutzers abgerufen.

Response

Die Antwort enthält ein JSON-Objekt mit folgendem Aufbau:


{
    "userId" : "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent" : true,
    "absenceText" : "I'm not available.",
    "startDateTime": "2020-08-27T05:52:23.7269283Z",
    "endDateTime": "2020-08-28T17:02:23.9541682Z"
}

Hinweise zu den Parametern

ParameterTypBeschreibung
userIdstringDie ID des Benutzers, für den der Abwesenheitsstatus abgerufen wird.
deputyIdstringDie ID des aktuell ausgewählten Vertreters. Wenn der Benutzer keinen Vertreter ausgewählt hat, enthält dieser Parameter den Wert null. >info: Ein Benutzer kann seinen Vertreter auch definieren, wenn er selbst noch nicht abwesend ist.
nextPresentDeputyIdstringDie ID des nächsten anwesenden Vertreters. Wenn der ausgewählte Vertreter zum Zeitpunkt der Abfrage abwesend ist, wird die ID des Vertreters seines ausgewählten Vertreters angegeben. Die User Profile-App ermittelt solange einen Vertreter für den angegebenen Vertreter, bis ein Vertreter gefunden werden konnte, der nicht als abwesend gemeldet ist. Die Abfrage berücksichtigt die jeweils definierten Vertreter der jeweiligen Benutzer. Wenn kein anwesender Vertreter ermittelt werden kann, enthält der Parameter den Wert null. Wenn kein Vertreter definiert ist oder der abgerufene Benutzer anwesend ist, enthält dieser Parameter ebenfalls den Wert null.
isAbsentbooleanDieser Parameter gibt den aktuellen Abwesenheitsstatus an. Wenn der abgerufene Benutzer abwesend ist, enthält dieser Parameter den Wert true.
absenceTextstringDer Abwesenheitstext des Benutzers. Ein Benutzer kann den Abwesenheitstext unabhängig von seinem aktuellen Abwesenheitsstatus definieren.
startDateTimestringDer Anfangszeitpunkt der Abwesenheit im Format nach ISO 8061.
endDateTimestringDer Endzeitpunkt der Abwesenheit im Format nach ISO 8061.

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert des userId-Parameters ungültig.
401UnauthorizedEs wurde keine gültige AuthSessionId übergeben.

 Festlegen des Abwesenheitsstatus und der Abwesenheitsinformationen eines Benutzers

Um den aktuellen Abwesenheitsstatus sowie die weiteren Abwesenheitsinformationen eines Benutzers zu ändern, muss deine App eine POST-Abfrage an die User Profile-App senden.

Request


POST /userprofile/api/absence
Content-Type: application/json

{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "2020-08-27T05:52:23.7269283Z",
    "endDateTime": "2020-08-28T17:02:23.9541682Z"
}

Hinweise zu den Parametern

ParameterTypBeschreibung
userIdstringOptional. Die ID des Benutzers, dessen Abwesenheitsstatus und Abwesenheitsinformationen geändert werden sollen. Mithilfe dieses Parameters kann ein Administrator den Abwesenheitsstatus und alle weiteren Abwesenheitsinformationen für andere Benutzer definieren.
deputyIdstringOptional. Die ID des Benutzers, der als Vertreter definiert werden soll.
isAbsentbooleanOptional. Der festzulegende Abwesenheitsstatus (abwesend = true).
absenceTextstringOptional. Der festzulegende Abwesenheitstext (Beschränkt auf 32768 Zeichen).
startDateTimestringOptional. Der Anfangszeitpunkt der Abwesenheit im Format nach ISO 8061.
endDateTimestringDer Endzeitpunkt der Abwesenheit im Format nach ISO 8061.

Beachte für optionale Parameter folgende Hinweise:

  • Wenn diese Parameter mit dem Wert null oder gar nicht übergeben werden, werden die bereits definierten Werte nicht verändert.
  • Wenn du einen leeren Wert angeben möchtest, musst du einen leeren String übergeben. Leere Werte zu übergeben ermöglicht dir einzelne Parameter anzupassen, ohne vorher die aktuellen Parameter des Benutzers abrufen zu müssen.
  • Wenn du für einen anderen Benutzer den Abwesenheitsstatus einstellen willst, ist der Parameter userId nicht optional.

Hinweis

Der Parameter isAbsent wird in einer zukünftigen Version nicht mehr verfügbar sein. Bitte verwende stattdessen die Parameter startDateTime und endDateTime. Der Parameter isAbsent überschreibt die beiden Datumswerte. Wenn du alle drei Parameter angibst, wird nur der Parameter isAbsent ausgewertet.

Response

Als Antwort können folgende HTTP-Statuscodes zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Weitere Informationen werden protokolliert.
401UnauthorizedEs wurde keine gültige AuthSessionId übergeben.
403ForbiddenDie Anfrage konnte nicht verarbeitet werden, da der angemeldete Benutzer keine Änderungen für andere Benutzer vornehmen darf.

 Beispiele

Im folgenden findest du mehrere Beispielaufrufe zum Festlegen des Status und der Informationen und die daraus resultierenden Antworten. Beachte in diesen Beispielen speziell den veralteten Parameter isAbsent.

1. Beispiel: Für den Parameter "isAbsent" wird der Wert "true" übermittelt


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}	

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort. Da der Parameter isAbsent übergeben wurde, werden die Parameter startDateTime und endDateTime ignoriert.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<time of the 'out of office' message>",
    "endDateTime": null
}

2. Beispiel: Für den Parameter "isAbsent" wird der Wert "false" übermittelt.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort. Da der Parameter isAbsent übergeben wurde, werden die Parameter startDateTime und endDateTime ignoriert.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": null,
    "endDateTime": null
}

3. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und die Abfragezeit liegt im Abwesenheitszeitraum.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time - 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time - 1 day>",
    "endDateTime": "<current time + 3 days>"
}

4. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und die Abfragezeit liegt nicht im Abwesenheitszeitraum.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

5. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und es wird nur ein Abwesenheitsendzeitpunkt übermittelt.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": null,
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<time of the 'out of office' message>,
    "endDateTime": "<current time + 3 days>"
}

 Ändern des Abwesenheitsstatus und der Abwesenheitsinformationen eines Benutzers

Um den aktuellen Abwesenheitsstatus oder andere Abwesenheitsinformationen eines Benutzers zu ändern, muss deine App eine PATCH-Abfrage an die User Profile-App senden.

Request


PATCH /userprofile/api/absence
Content-Type: application/json

{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "absenceText": "I'm not available.",
    "startDateTime": "2020-08-27T05:52:23.7269283Z",
    "endDateTime": "2020-08-28T17:02:23.9541682Z"
}

Hinweise zu den Parametern

ParameterTypBeschreibung
userIdstringOptional. Die ID des Benutzers, dessen Abwesenheitsstatus und Abwesenheitsinformationen geändert werden sollen. Ein Administrator kann für diesen Parameter auch die ID eines anderen Benutzers angeben.
deputyIdstringOptional. Die ID des Benutzers, der als Vertreter definiert werden soll.
isAbsentbooleanOptional, veraltet. Der festzulegende Abwesenheitsstatus (abwesend = true).
absenceTextstringOptional. Der festzulegende Abwesenheitstext (Beschränkt auf 32768 Zeichen).
startDateTimestringOptional. Der festzulegende Anfangszeitpunkt der Abwesenheit im Format nach ISO 8061.
endDateTimestringOptional. Der festzulegende Endzeitpunkt der Abwesenheit im Format nach ISO 8061.

Beachte für optionale Parameter folgende Hinweise:

  • Wenn diese Parameter mit dem Wert null oder gar nicht übergeben werden, werden sie nicht verändert.
  • Wenn du einen Wert leeren möchtest, musst du einen leeren String übergeben. Leere Werte zu übergeben ermöglicht dir, einzelne Parameter anzupassen, ohne vorher die aktuellen Parameter des Benutzers abrufen zu müssen.
  • Wenn du für einen anderen Benutzer den Abwesenheitsstatus ändern willst, ist der Parameter userId nicht optional.

Hinweis

Der Parameter isAbsent wird in einer zukünftigen Version nicht mehr verfügbar sein. Bitte verwende stattdessen die Parameter startDateTime und endDateTime.

Response

Als Antwort können folgende HTTP-Statuscodes zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Weitere Informationen werden protokolliert.
401UnauthorizedEs wurde keine gültige AuthSessionId übergeben.
403ForbiddenDie Anfrage konnte nicht verarbeitet werden, da der angemeldete Benutzer keine Änderungen für andere Benutzer vornehmen darf.

 Beispiele

Im folgenden findest du mehrere Beispielaufrufe zum Ändern des Status und der Informationen und die daraus resultierenden Antworten. Beachte in diesen Beispielen speziell den veralteten Parameter isAbsent.

1. Beispiel: Für den Parameter "isAbsent" wird der Wert "true" übermittelt


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}	

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort. Da der Parameter isAbsent übergeben wurde, werden die Parameter startDateTime und endDateTime ignoriert.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<time of the 'out of office' message>",
    "endDateTime": null
}

2. Beispiel: Für den Parameter "isAbsent" wird der Wert "false" übermittelt


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort. Da der Parameter isAbsent übergeben wurde, werden die Parameter startDateTime und endDateTime ignoriert.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": null,
    "endDateTime": null
}

3. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und die aktuelle Zeit liegt im Abwesenheitszeitraum.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time - 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time - 1 day>",
    "endDateTime": "<current time + 3 days>"
}

4. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und die aktuelle Zeit liegt nicht im Abwesenheitszeitraum.


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": false,
    "absenceText": "I'm not available.",
    "startDateTime": "<current time + 1 day>",
    "endDateTime": "<current time + 3 days>"
}

5. Beispiel: Für den Parameter "isAbsent" wird kein Wert übermittelt und es wird nur ein Abwesenheitsendzeitpunkt übermittelt


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": null,
    "absenceText": "I'm not available.",
    "startDateTime": null,
    "endDateTime": "<current time + 3 days>"
}

Wenn du im folgenden die Informationen abrufst, bekommst du folgende Antwort:


{
    "userId": "11A5C79F-D9AB-498B-9158-D3034B7E45E5",
    "deputyId": "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "nextPresentDeputyId" : "3D789836-69DC-4C3C-8A0A-3D9D2B07B087",
    "isAbsent": true,
    "absenceText": "I'm not available.",
    "startDateTime": "<time of the 'out of office' message>,
    "endDateTime": "<current time + 3 days>"
}

 Abrufen einer Liste von Benutzern, die von demselben Benutzer vertreten werden

Um eine Liste aller Benutzer zu erhalten, bei denen der gleiche Benutzer aktuell als Vertreter eingetragen ist, muss deine App eine GET-Abfrage an die User Profile-App senden.

Request


GET /userprofile/api/usedasdeputyof[?userId=11A5C79F-D9AB-498B-9158-D3034B7E45E5]
Accept: application/json
ParameterBeschreibung
userIdOptional. ID des Benutzers, den Benutzer als ihren Vertreter definiert haben. Wenn du den Query-Parameter nicht verwendest, wird die ID des aktuell angemeldeten Benutzers verwendet.

Response

Die Antwort enthält ein JSON-Objekt mit folgendem Aufbau:


{
    "userIdList" : ["21A5C79F-D9AB-498B-9158-D3034B7E45E5","31A5C79F-D9AB-498B-9158-D3034B7E45E5"]
}

Hinweis zum Parameter

ParameterTypBeschreibung
userIdListstring[]Die Liste der IDs der ermittelten Benutzer.

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
400Bad RequestDie Anfrage konnte nicht verarbeitet werden. Möglicherweise ist der Wert des userId-Parameters ungültig.
401UnauthorizedEs wurde keine gültige AuthSessionId übergeben.
404Not FoundDie Anfrage konnte keine abwesenden Benutzer finden, bei denen der angegebene Benutzer als Vertreter eingesetzt wird.

 Abrufen der aktuell abwesenden Benutzer

Um eine Liste aller Benutzer zu erhalten, die aktuell abwesend gemeldet sind, muss deine App eine GET-Abfrage an die User Profile-App senden.

Request


GET /userprofile/api/absentusers
Accept: application/json

Response

Die Antwort enthält ein JSON-Objekt mit folgendem Aufbau:


{
    "userIdList" : ["21A5C79F-D9AB-498B-9158-D3034B7E45E5","31A5C79F-D9AB-498B-9158-D3034B7E45E5"]
}

Hinweis zum Parameter

ParameterTypBeschreibung
userIdListstring[]Die Liste der IDs der ermittelten Benutzer.

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
401UnauthorizedEs wurde keine gültige AuthSessionId übergeben.
404Not FoundDie Anfrage konnte keine abwesenden Benutzer finden.

 Automatische Benachrichtigung bei Änderung der Abwesenheit von Benutzern

Du kannst deine App bei der User Profile-App registrieren, sodass deine App bei Änderung der Abwesenheit von Benutzern sofort über diese Änderung informiert wird und entsprechend reagieren kann.

Beim Verwalten der Registrierung muss deine App zur Authentifizierung zwingend eine App-Session verwenden (siehe Abschnitt Inter-App-Kommunikation mit App-Sessions der Identityprovider-App).

 Registrieren

Um deine App für Benachrichtigungen zu registrieren, muss sie eine PUT-Anfrage an die User Profile-App senden. Bitte beachte, dass eine PUT-Anfrage einen bereits gesetzten Pfad deiner App überschreibt.

Request


PUT /userprofile/api/subscriptions/{appName}
Content-Type: application/json

{
    "path": "/MyGreatApp/myCallbackPath"
}

Hinweise zu den Parametern

ParameterTypBeschreibung
appNamestringDer Name deiner App.
pathstringDer Pfad, welcher bei Benachrichtigungen aufgerufen werden soll. Der Pfad muss mit deinem AppNamen beginnen.

Response

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
201CreatedDie Anfrage wurde erfolgreich verarbeitet und die Registrierung gespeichert.
400Bad RequestDer angegebene Pfad ist invalide. Bitte beachte, dass der Pfad mit einem Slash und deinem AppNamen beginnen muss.
403ForbiddenZur Authentifizierung bei der User Profile-App wurde keine App-Session verwendet. Ein weiterer Grund könnte sein, dass der angegebene AppName nicht dem Namen deiner App entspricht.

 Registrierung abrufen

Um zu überprüfen, ob deine App bereits registriert ist, kannst du eine GET-Anfrage an die User Profile-App senden.

Request


GET /userprofile/api/subscriptions/{appName}
Accept: application/json

Hinweis zum Parameter

ParameterTypBeschreibung
appNamestringDer Name deiner App.

Response

Die Antwort enthält ein JSON-Objekt mit folgendem Aufbau:


{
    "path": "/MyGreatApp/myCallbackPath"
}

Hinweis zum Parameter

ParameterTypBeschreibung
pathstringDer Benachrichtigungspfad deiner App inklusive Appname.

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
403ForbiddenZur Authentifizierung bei der User Profile-App wurde keine App-Session verwendet. Ein weiterer Grund könnte sein, dass du die Registrierung einer anderen App abfragen wolltest.
404Not FoundFür deine App gibt es bisher keine Registrierung.

 Deregistrieren

Um deine App zu deregistrieren, muss deine App eine DELETE-Anfrage an die User Profile-App senden.

Request


DELETE /userprofile/api/subscriptions/{appName}

Hinweis zum Parameter

ParameterTypBeschreibung
appNamestringDer Name deiner App.

Response

Folgende HTTP-Statuscodes können zurückgegeben werden:

StatuscodeNameBedeutung
200OKDie Anfrage wurde erfolgreich verarbeitet.
403ForbiddenZur Authentifizierung bei der User Profile-App wurde keine App-Session verwendet. Ein weiterer Grund könnte sein, dass du eine andere App deregistrieren wolltest.
404Not FoundFür deine App gibt es keine Registrierung.

Wichtig

Für deine App wird lediglich ein Benachrichtigungspfad gespeichert. Wenn du mehrere PUT-Anfragen hintereinander sendest, wird der Pfad jedes Mal aktualisiert. Somit wird deine App sofort deregistriert, wenn du eine einzige DELETE-Anfrage sendest.

 Benachrichtigungen empfangen

Wenn deine App bei der User Profile-App registriert ist, wird sie bei Änderungen der Abwesenheit von Benutzern automatisch benachrichtigt. Hierzu wird eine POST-Anfrage an den Pfad deiner App gesendet, welchen du bei der Registrierung deiner App hinterlegt hast.

Angenommen, du hast deine App "MyGreatApp" wie im Beispiel oben bei der User Profile-App registriert. Wenn nun die Abwesenheit eines Benutzers geändert wird, wird folgende POST-Anfrage an deine App gesendet:


POST /MyGreatApp/myCallbackPath
Content-Type: application/json

{
    "UserIdList": ["171a71fd-541d-4383-baf5-781e23c5ea66"]
}

Hinweis zum Parameter

ParameterTypBeschreibung
UserIdListstring[]Die Liste der IDs der Benutzer, deren Abwesenheit geändert wurde.

Sobald du diese Anfrage erhalten hast, antworte bitte mit einem 2xx-Statuscode (beispielsweise 200 oder 202), damit die User Profile-App weiß, dass du die Benachrichtigung erhalten hast. Falls du nicht mit einem 2xx-Statuscode antwortest, beispielsweise weil deine App gerade nicht erreichbar ist, speichert die User Profile-App die UserIds bis zu 24 Stunden. Bei jeder weiteren Änderung von Abwesenheiten versucht die User Profile-App deine App erneut zu benachrichtigen. Wenn die Abwesenheitsdaten der Benutzer nicht mehr geändert werden, wird die Benachrichtigung spätestens nach einer Stunde erneut an deine App gesendet. Ein weiterer Versuch wird nach 24 Stunden durchgeführt. Wenn deine App nach 24 Stunden immer noch nicht korrekt antwortet, löscht die User Profile-App die zwischengespeicherten UserIds für deine App und deregistriert sie.

Wichtig

Die User Profile-App sendet die oben beschriebene POST-Anfrage, wenn sich die Abwesenheitsdaten eines Benutzers ändern. Sobald der Benutzer also beispielsweise einen anderen Vertreter auswählt, oder seinen Abwesenheitstext ändert, und dann speichert, wird deine App benachrichtigt. Die User Profile-App sendet keine erneute Benachrichtigung, wenn eine geplante Abwesenheit in der Zukunft eintritt. Wenn ein Benutzer somit den Startzeitpunkt seiner Abwesenheit auf einen Zeitpunkt in der Zukunft setzt und diese Änderung dann speichert, wird sofort eine Benachrichtigung an deine App gesendet. Wenn der Startzeitpunkt erreicht ist, wird keine erneute Benachrichtigung gesendet.