notifications

« Previous section Next section »

UCloud Developer Guide / Core / Communication / Notifications

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

2. Remote Procedure Calls

3. Data Models

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 = 1704180845770, 
            type = "MY_NOTIFICATION_TYPE", 
        ), 
        user = "User#1234", 
    ),
    ucloud
).orThrow()

/*
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": 1704180845770,
        "read": false
    }
}'


# {
#     "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 = 1704180845774, 
    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 = 1704180845776, 
        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": 1704180845776,
#             "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

subscription

Request	Response	Error
Unit	Notification	CommonErrorMessage

create

Request	Response	Error
CreateNotification	FindByLongId	CommonErrorMessage

createBulk

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

delete

Request	Response	Error
FindByNotificationIdBulk	DeleteResponse	CommonErrorMessage

markAllAsRead

Request	Response	Error
Unit	Unit	CommonErrorMessage

markAsRead

Request	Response	Error
FindByNotificationIdBulk	MarkResponse	CommonErrorMessage

Data Models

CreateNotification

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

Properties

---

FindByNotificationIdBulk

data class FindByNotificationIdBulk(
    val ids: String,
)

Properties

---

Notification

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

Properties

---

InternalNotificationRequest

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

Properties

---

ListNotificationRequest

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

Properties

---

DeleteResponse

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

Properties

---

MarkResponse

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

Properties

---