User Profile app

Introduction

In this topic, you can find general information about the User Profile app and its scope of functions, as well as helpful knowledge for programming functions and customizing.

Scope of functions of the User Profile app

The User Profile app provides an overview page for the user who is currently logged in. It also lets the user manage his or her own absences. As the user, you can query and change your absence status and other associated information using a REST API. You also have the option to set a notification path for your app, which will be invoked when users' absences change, so you can react to the changes immediately.

Using the API functions

The User Profile app provides an API interface that you can use to carry out the following actions:

• Calling the absence status of a user and information about the absence
• Defining the absence status of a user and information about the absence
• Changing the absence status of a user and information about the absence
• Calling a list of users with the same delegate user
• Calling users that are currently absent

Calling the absence status of a user and information about the absence

To call the current absence status of a user and other information about the absence, your app must send a GET request to the User Profile app.

Request

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

Note about the parameter

Response

The response contains a JSON object with the following layout:

{
    "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"
}

Notes about the parameters

The following HTTP status codes can be returned:

Defining the absence status of a user and information about the absence

To change the current absence status of a user and other information about the absence, your app must send a POST request to the User Profile app.

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"
}

Notes about the parameters

The userId can be used to change the absence status of another user. This is only possible for the following persons (groups) for specific users:

• an administrator for each user
• the supervisor for his direct subordinates
• the supervisor's direct substitute for his direct subordinates, if the supervisor himself is absent

For optional parameters, note the following:

• If these parameters are transferred with the value null or not transferred at all, the values already defined are not changed.
• If you want to enter an empty value, you must transfer an empty string. Transferring empty values allows you to adapt individual parameters without having to call the current user parameters beforehand.
• If you want to set the absence status for a different user, the parameter userId is not optional.

info: The parameter isAbsent will no longer be available in future versions. Please use the parameters startDateTime and endDateTime instead. The parameter isAbsent overwrites the two date values. If you specify all three parameters, only the parameter isAbsent is evaluated.

Response

The following HTTP status codes can be returned as the response:

Examples

Below you can find several sample calls for defining the status and information and their resulting responses. Pay special attention to the obsolete parameter isAbsent in these examples.

First example: The value "true" is transferred for the parameter "isAbsent"

{
    "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>"
}   

If you then call the information, you receive the following response. Since the parameter isAbsent was transferred, the parameters startDateTime and endDateTime are ignored.

{
    "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
}

Second example: The value "false" is transferred for the parameter "isAbsent".

{
    "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>"
}

If you then call the information, you receive the following response. Since the parameter isAbsent was transferred, the parameters startDateTime and endDateTime are ignored.

{
    "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
}

Third example: No value is transferred for the parameter "isAbsent" and the time of the query is within the absence time period

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Fourth example: No value is transferred for the parameter "isAbsent" and the time of the query is not within the absence time period

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Fifth example: No value is transferred for the parameter "isAbsent" and only an absence end point is transferred

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Changing the absence status of a user and information about the absence

To change the current absence status of a user and other information about the absence, your app must send a PATCH request to the User Profile app.

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"
}

Notes about the parameters

The userId can be used to change the absence status of another user. This is only possible for the following persons (groups) for specific users:

• an administrator for each user
• the supervisor for his direct subordinates
• the supervisor's direct substitute for his direct subordinates, if the supervisor himself is absent

For optional parameters, note the following:

• If these parameters are transferred with the value null or not transferred at all, they are not changed.
• If you want to clear a value, you must transfer an empty string. Transferring empty values allows you to adapt individual parameters without having to call the current user parameters beforehand.
• If you want to change the absence status for a different user, the parameter userId is not optional.

info: The parameter isAbsent will no longer be available in future versions. Please use the parameters startDateTime and endDateTime instead.

Response

The following HTTP status codes can be returned as the response:

Examples

Below you can find several sample calls for changing the status and information and their resulting responses. Pay special attention to the obsolete parameter isAbsent in these examples.

First example: The value "true" is transferred for the parameter "isAbsent"

{
    "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>"
}   

If you then call the information, you receive the following response. Since the parameter isAbsent was transferred, the parameters startDateTime and endDateTime are ignored.

{
    "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
}

Second example: The value "false" is transferred for the parameter "isAbsent"

{
    "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>"
}

If you then call the information, you receive the following response. Since the parameter isAbsent was transferred, the parameters startDateTime and endDateTime are ignored.

{
    "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
}

Third example: No value is transferred for the parameter "isAbsent" and the current time is within the absence time period

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Fourth example: No value is transferred for the parameter "isAbsent" and the current time is not within the absence time period.

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Fifth example: No value is transferred for the parameter "isAbsent" and only an absence end point is transmitted.

{
    "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>"
}

If you then call the information, you receive the following response:

{
    "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>"
}

Calling a list of users with the same delegate user

To receive a list of all absent users for whom the given user is currently entered as the delegate, your app must send a GET request to the User Profile app.

Request

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

Response

The response contains a JSON object with the following layout:

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

Note about the parameter

The following HTTP status codes can be returned:

Calling users that are currently absent

To receive a list of all the users that are currently reported as absent, your app must send a GET request to the User Profile app.

Request

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

Response

The response contains a JSON object with the following layout:

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

Note about the parameter

The following HTTP status codes can be returned:

Automatic notification when users' absence changes

You can register your app at the User Profile app so that when users' absences change, your app is immediately notified of the change and can respond accordingly.

Your app must use an app session for authentication when managing its registry (see Inter-app communication with app sessions in the documentation of the Identityprovider-App).

Register

To register your app for notifications, it must send a PUT request to the User Profile app. Please note that a PUT request overwrites an already set path of your app.

Request

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

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

Notes about the parameters

Response

The following HTTP status codes can be returned:

Get registration

To check if your app is already registered, you can send a GET request to the User Profile app.

Request

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

Note about the parameter

Response

The response contains a JSON object with the following layout:

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

Note about the parameter

The following HTTP status codes can be returned:

Deregister

To deregister your app, your app must send a DELETE request to the User Profile app.

Request

DELETE /userprofile/api/subscriptions/{appName}

Note about the parameter

Response

The following HTTP status codes can be returned:

warning: Only one notification path is stored for your app. If you send multiple PUT requests in a row, the path will be updated each time. Thus, if you send a single DELETE request, your app will be deregistered immediately.

Receive notifications

If your app is registered at the User Profile app, it will be automatically notified of user absence changes. This is done by sending a POST request to the path of your app, which you specified when you registered your app.

Let's say you registered your app "MyGreatApp" with at User Profile app as in the example above. Now when a user's absence is changed, the following POST request is sent to your app:

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

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

Note about the parameter

Once you receive this request, please reply with a 2xx status code (for example, 200 or 202) so that the User Profile app knows that you received the notification. If you don't reply with a 2xx status code, for example because your app is currently unavailable, the User Profile app will store the UserIds for up to 24 hours. Every time absences are changed, the User Profile app will try to notify your app again. If the user absence data is no longer changed, the notification will be sent to your app again after one hour at the latest. Another attempt will be made after 24 hours. If your app still does not respond correctly after 24 hours, the User Profile app deletes the cached UserIds for your app and deregisters it.

warning: The User Profile app sends the POST request described above when a user's absence data changes. So, for example, as soon as the user selects a different deputy, or changes their absence text, and then saves, your app will be notified. The User Profile app does not send another notification when a scheduled absence occurs in the future. Thus, if a user sets the start time of their absence to a time in the future, and then saves that change, a notification is immediately sent to your app. When the start time is reached, no new notification is sent.