Notification API

The BPC has a notification functionality to inform users. This API contains endpoints to use this notification system, e.g. to send, update, delete and retrieve notifications.

Method Endpoint

POST

/cxf/bpc-core/notification

Description

To add a notification, send a JSON message with the following structure:

Minimal example
{
  "subject": "Replication problem",
  "message": "The database 'postgresql' is not reachable",
  "recipients": [ "bpcadmin" ],
  "recipientsType": "role"
}
More complex example
{
    "priority": 10,
    "subject": "API expires soon",
    "message": "API Key API-39e889a expires soon. Please contact your administrator.",
    "recipients": [ "bpcadmin" ],
    "recipientsType": "role",
    "validitySeconds": 3600,
    "icon": "fa-file-certificate",
    "type": "warning",
    "linkData": {
        "navigation": "/_nav/!-1&/module/_core/_core///_core/apiKeys/api/[\"API-39e889a\"]"
    },
    "topic": "TOPIC_APIKEY_EXPIRATION"
}

Fields

id (optional)

ID of the notification. A random UUID gets set when not given.

priority (optional)

Delivery priority of the notification. Can be one of the following values: 0 (Silent), 5 (Toast), 10 (Popup). 5 gets used when not given.

subject (required)

The subject of the notification.

message (optional)

The message of the notification.

recipients (required)

The recipients of the notification. Depends on the used recipientsType.

recipientsType (required)

The recipients type of the notification. Can be one of the following values: user, role or organisation.

originator (optional)

The originator of the notification. The login name of the user session gets used when not given.

validitySeconds

The number of seconds the notification is valid.

icon (optional)

The Font Awesome icon which should be used when showing the notification.

type (optional)

The type of the notification. The type 'info' gets used when not given. Other possibility are 'warn' and 'error'. Depending on the type, the notification is displayed accordingly in the GUI (see also Notifikationstypen und Darstellung in der Oberfläche).

linkData (optional)

Optionally specifies link information for navigation within BPC or to an external URL. You may provide either a url field for an external link or a navigation field containing the hash segment of a BPC URL.

topic (optional)

The notification topic

Consumes

  • application/json

Returns

The added notification as JSON. Contains additionally the 'date' and 'version' fields which get automatically set/updated.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_ADD

PUT

/cxf/bpc-core/notification/{notificationId}

Description

To update a notification, send a JSON message with the following structure:

Minimal example
{
  "subject": "Replication problem",
  "message": "The database 'postgresql' is not reachable",
  "recipients": [ "bpcadmin" ],
  "recipientsType": "role"
}
More complex example
{
    "priority": 10,
    "subject": "API expires soon",
    "message": "API Key API-39e889a expires soon. Please contact your administrator.",
    "recipients": [ "bpcadmin" ],
    "recipientsType": "role",
    "icon": "fa-file-certificate",
    "type": "warning",
    "linkData": {
        "navigation": "/_nav/!-1&/module/_core/_core///_core/apiKeys/api/[\"API-39e889a\"]"
    }
}

Fields

priority (optional)

Delivery priority of the notification. Can be one of the following values: 0 (Silent), 5 (Toast), 10 (Popup). 5 gets used when not given.

subject (required)

The subject of the notification.

message (optional)

The message of the notification.

recipients (required)

The recipients of the notification. Depends on the used recipientsType.

recipientsType (required)

The recipients type of the notification. Can be one of the following values: user, role or organisation.

originator (optional)

The originator of the notification. The login name of the user session gets used when not given.

icon (optional)

The Font Awesome icon which should be used when showing the notification.

type (optional)

The type of the notification. The type 'info' gets used when not given. Other possibility are 'warn' and 'error'. Depending on the type, the notification is displayed accordingly in the GUI (see also Notifikationstypen und Darstellung in der Oberfläche).

linkData (optional)

Optionally specifies link information for navigation within BPC or to an external URL. You may provide either a url field for an external link or a navigation field containing the hash segment of a BPC URL.

Consumes

  • application/json

Path Parameter

notificationId

the ID of the notification to update

Returns

The updated notification as JSON. Contains additionally the 'date' and 'version' fields which get automatically set/updated.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_UPDATE

DELETE

/cxf/bpc-core/notification/{notificationId}

Description

Delete a specific notification.

Path Parameter

notificationId

the ID of the notification to delete

Returns

The deleted notification as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Missing resource:

    • Required service was not found

    • Requested notification was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_DELETE

DELETE

/cxf/bpc-core/notification

Description

Delete notifications by topic.

Query Parameter

topic

the topic for notifications to delete

keepNewest

if true, the newest notification of this topic will be kept. Default is false.

Returns

HTTP Status Code

  • 204 : Deletion successful

  • 400 : Topic is not specified

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : NOTIFICATION_ADMIN

  • Right : NOTIFICATION_DELETE

GET

/cxf/bpc-core/notification/{notificationId}

Description

Get the data of a notification.

Path Parameter

notificationId

the ID of the notification to get the data for

Returns

The data of the requested notification as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Missing resource:

    • Required service was not found

    • Requested notification was not found or no access rights

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

GET

/cxf/bpc-core/notification

Description

Get the notification of the requesting user.

Query Parameter

start

paging start parameter. Default is 0.

limit

number of notifications to get. Default is 1000.

Returns

The requested notifications of the user as JSON.

HTTP Status Code

  • 200 : OK

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/notification/{notificationId}/read

Description

marks the notification as read by the user.

Path Parameter

notificationId

the ID of the notification to mark as read

Returns

HTTP Status Code

  • 204 : Mark as read was successful

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/notification/{notificationId}/unread

Description

marks the notification as unread by the user.

Path Parameter

notificationId

the ID of the notification to mark as unread

Returns

HTTP Status Code

  • 200 : Mark as unread was successful

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/notification/read

Description

Mark multiple notifications as read or unread by the user.

To do so, send a JSON message with the following fields:

notificationIds

List of IDs of the notifications to mark as read or unread.

isRead

Read status to set, either true or false

example
{
  "notificationIds": ["11111111-0000-9999-aaaa-bbbbccccdddd","22222222-0000-9999-aaaa-bbbbccccdddd"],
  "isRead": true
}

This marks the two notifications ("1111…​" and "2222…​") as read.

Returns

HTTP Status Code

  • 204 : Mark as read was successful

  • 404 : Required service was not found

  • 500 : Unexpected backend error

  • 503 : Maintenance mode is active

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen