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.

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