Notifications

Notifications help users stay up-to-date with events in UCloud.

Rationale

Powers the notification feature of UCloud. Other services can call this service to create a new notification for users. Notifications are automatically delivered to any connected frontend via websockets.

Table of Contents

1. Examples

Description
Creating a notification
Listening to notifications
List and Clear notifications

2. Remote Procedure Calls

Name	Description
internalNotification	Notifies an instance of this service that it should notify an end-user
list	No description
retrieveSettings	Retrieve notification settings/preferences for end-user
subscription	No description
create	No description
createBulk	No description
delete	No description
markAllAsRead	No description
markAsRead	No description
updateSettings	Update notification settings/preferences for end-user

3. Data Models

Name	Description
CreateNotification	No description
FindByNotificationIdBulk	No description
Notification	No description
NotificationSettings	No description
InternalNotificationRequest	No description
ListNotificationRequest	No description
RetrieveSettingsRequest	No description
CreateNotificationResponse	No description
DeleteResponse	No description
MarkResponse	No description
RetrieveSettingsResponse	No description

Example: Creating a notification

Frequency of use	Common
Actors	The UCloud/Core service user (ucloud)

Communication Flow: Kotlin

NotificationDescriptions.create.call(
    CreateNotification(
        notification = Notification(
            id = null, 
            message = "Something has happened", 
            meta = JsonObject(mapOf("myParameter" to JsonLiteral(
                coerceToInlineType = null, 
                content = "42", 
                isString = false, 
            )),)), 
            read = false, 
            ts = 1717663228605, 
            type = "MY_NOTIFICATION_TYPE", 
        ), 
        user = "User#1234", 
    ),
    ucloud
).orThrow()

/*
CreateNotificationResponse(
    id = FindByLongId(
        id = 56123, 
    ), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as ucloud
curl -XPUT -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/notifications" -d '{
    "user": "User#1234",
    "notification": {
        "type": "MY_NOTIFICATION_TYPE",
        "message": "Something has happened",
        "id": null,
        "meta": {
            "myParameter": 42
        },
        "ts": 1717663228605,
        "read": false
    }
}'


# {
#     "id": {
#         "id": 56123
#     }
# }

Communication Flow: Visual

Example: Listening to notifications

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

NotificationDescriptions.subscription.subscribe(
    Unit,
    user,
    handler = { /* will receive messages listed below */ }
)

/*
Notification(
    id = 56123, 
    message = "Something has happened", 
    meta = JsonObject(mapOf("myParameter" to JsonLiteral(
        coerceToInlineType = null, 
        content = "42", 
        isString = false, 
    )),)), 
    read = false, 
    ts = 1717663228605, 
    type = "MY_NOTIFICATION_TYPE", 
)
*/

NotificationDescriptions.markAsRead.call(
    FindByNotificationIdBulk(
        ids = "56123", 
    ),
    user
).orThrow()

/*
MarkResponse(
    failures = emptyList(), 
)
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XPOST -H "Authorization: Bearer $accessToken" -H "Content-Type: content-type: application/json; charset=utf-8" "$host/api/notifications/read" -d '{
    "ids": "56123"
}'


# {
#     "failures": [
#     ]
# }

Communication Flow: Visual

Example: List and Clear notifications

Frequency of use	Common
Actors	An authenticated user (user)

Communication Flow: Kotlin

NotificationDescriptions.list.call(
    ListNotificationRequest(
        itemsPerPage = null, 
        page = null, 
        since = null, 
        type = null, 
    ),
    user
).orThrow()

/*
Page(
    items = listOf(Notification(
        id = 56123, 
        message = "Something has happened", 
        meta = JsonObject(mapOf("myParameter" to JsonLiteral(
            coerceToInlineType = null, 
            content = "42", 
            isString = false, 
        )),)), 
        read = false, 
        ts = 1717663228606, 
        type = "MY_NOTIFICATION_TYPE", 
    )), 
    itemsInTotal = 1, 
    itemsPerPage = 50, 
    pageNumber = 0, 
)
*/
NotificationDescriptions.markAllAsRead.call(
    Unit,
    user
).orThrow()

/*
Unit
*/

Communication Flow: Curl

# ------------------------------------------------------------------------------------------------------
# $host is the UCloud instance to contact. Example: 'http://localhost:8080' or 'https://cloud.sdu.dk'
# $accessToken is a valid access-token issued by UCloud
# ------------------------------------------------------------------------------------------------------

# Authenticated as user
curl -XGET -H "Authorization: Bearer $accessToken" "$host/api/notifications?" 

# {
#     "itemsInTotal": 1,
#     "itemsPerPage": 50,
#     "pageNumber": 0,
#     "items": [
#         {
#             "type": "MY_NOTIFICATION_TYPE",
#             "message": "Something has happened",
#             "id": 56123,
#             "meta": {
#                 "myParameter": 42
#             },
#             "ts": 1717663228606,
#             "read": false
#         }
#     ]
# }

curl -XPOST -H "Authorization: Bearer $accessToken" "$host/api/notifications/read/all" 

# {
# }

Communication Flow: Visual

Remote Procedure Calls

internalNotification

Notifies an instance of this service that it should notify an end-user

Request	Response	Error
InternalNotificationRequest	Unit	CommonErrorMessage

list

Request	Response	Error
ListNotificationRequest	Page<Notification>	CommonErrorMessage

retrieveSettings

Retrieve notification settings/preferences for end-user

Request	Response	Error
RetrieveSettingsRequest	RetrieveSettingsResponse	CommonErrorMessage

subscription

Request	Response	Error
Unit	Notification	CommonErrorMessage

create

Request	Response	Error
CreateNotification	CreateNotificationResponse	CommonErrorMessage

createBulk

Request	Response	Error
BulkRequest<CreateNotification>	BulkResponse<CreateNotificationResponse>	CommonErrorMessage

delete

Request	Response	Error
FindByNotificationIdBulk	DeleteResponse	CommonErrorMessage

markAllAsRead

Request	Response	Error
Unit	Unit	CommonErrorMessage

markAsRead

Request	Response	Error
FindByNotificationIdBulk	MarkResponse	CommonErrorMessage

updateSettings

Update notification settings/preferences for end-user

Request	Response	Error
NotificationSettings	Unit	CommonErrorMessage

Data Models

CreateNotification

data class CreateNotification(
    val user: String,
    val notification: Notification,
)

Properties

user: String

notification: Notification

---

FindByNotificationIdBulk

data class FindByNotificationIdBulk(
    val ids: String,
)

Properties

ids: String

---

Notification

data class Notification(
    val type: String,
    val message: String,
    val id: Long?,
    val meta: JsonObject?,
    val ts: Long?,
    val read: Boolean?,
)

Properties

type: String

message: String

id: Long?

meta: JsonObject?

ts: Long?

read: Boolean?

---

NotificationSettings

data class NotificationSettings(
    val jobStarted: Boolean?,
    val jobStopped: Boolean?,
)

Properties

jobStarted: Boolean?

jobStopped: Boolean?

---

InternalNotificationRequest

data class InternalNotificationRequest(
    val user: String,
    val notification: Notification,
)

Properties

user: String

notification: Notification

---

ListNotificationRequest

data class ListNotificationRequest(
    val type: String?,
    val since: Long?,
    val itemsPerPage: Int?,
    val page: Int?,
)

Properties

type: String?

since: Long?

itemsPerPage: Int?

page: Int?

---

RetrieveSettingsRequest

data class RetrieveSettingsRequest(
    val username: String?,
)

Properties

username: String?

---

CreateNotificationResponse

data class CreateNotificationResponse(
    val id: FindByLongId?,
)

Properties

id: FindByLongId?

---

DeleteResponse

data class DeleteResponse(
    val failures: List<Long>,
)

Properties

failures: List<Long>

---

MarkResponse

data class MarkResponse(
    val failures: List<Long>,
)

Properties

failures: List<Long>

---

RetrieveSettingsResponse

data class RetrieveSettingsResponse(
    val settings: NotificationSettings,
)

Properties

settings: NotificationSettings

---