Notification APIs

Details of APIs that facilitate notifications through HCX.

Key Design Considerations

In order to make notifications secure, lightweight and easily deliverable and actionable, following constraints are proposed:

  • Reuse existing protocol features wherever possible

  • Limit the Maximum size of notification payload

  • Templatized messages based on notification topic to encourage semantic interoperability

Following key APIs are envisioned to enable notifications in HCX. Full API specifications in OpenAPI 3.0 format are available here.

List of Supported Notifications

Get the list of notification types supported by the network along with their classification and access control parameters. Key attributes of notification type master data are:

Attribute/Property

DataType

Description

title

String

Title of the notification

description

String

Details about the notification

sender

List<String>

List of roles who can send this notification.

recipient

List<String>

List of roles who can subscribe to this notification.

topic_code

String

Unique code for the notification topic

category

String

Category of the notification as detailed above - network (broadcast & target), participant, use_case

priority

int

Default priority assigned to the topic. 0 means highest, positive integer would carry the respective relative priority. Negative would be that the topic is disabled. Relative order of category for different message categories is recommended to be use_case > participant > network

API details

/notification/list

As evident sanctity of the master list of notification is important for effective notification service on the network, hence it is recommended that master list of the notification is given the same treatment as an operator would give to its code for the switch.

Subscription to notifications

APIs to subscribe or unsubscribe to a notification type based on its subscribability. For Use case type notifications, this API is also expected to be implemented by the participating systems supporting such notifications. Key attributes of the subscription model are:

Column

DataType

Description

subscription_id

UUID

Unique identifier for the subscription.

participant_code

String

Identifier of the subscriber.

topic_code

String

Identifier of the notification topic.

status

Integer

Status of the notification. Values: 1 - active, 0 - inactive, -1 - pending for approval.

subscription_data

Object

Encrypted details subject of subscription for the use_case category

subscribed_on

timestamp

expires_on

timestamp

Timestamp when the notification expires. Can use a reasonably long period to indicate forever valid notifications, however it is recommended that subscriptions are periodically renewed.

API details

Input would be the topic_code and payloads containing use case related details wherever applicable. The final response would be returned asynchronously.

/notification/subscribe

/notification/unsubscribe

/notification/subscription/list

Trigger notifications

APIs to trigger the actual notification that would be used by the participants (including HCX switch) to notify the intended participants. This API would be used in two modes:

  1. by HCX switch on participants to deliver the final notification (of all categories)

  2. By participants on HCX to trigger delivery notifications of participants and use case categories on the intended recipients.

Proposed attributes of notification header and payload:

Column

DataType

Description

notificationId

String (UUID)

Unique id assigned by the initiator to the notification

sender

String

Participant code of the notification initiator

category

String

Category of the notification as defined by the specs - network, participant or use_case

topic

String

Topic of notification as defined in the master list of notifications

recipientCodes

String[]

Participant code of the recipient(s) of the notification. Could be one or more based on the need.

recipientRoles

String[]

Participant role of the recipient(s) of the notification. Could be one or more based on the need.

recipientCodes and/or recipientRoles can be used to send a notification (network or participant category) to a subset of participants defined in the notification master data for the corresponding topic.

subscriptions

String[]

Conditional mandatory: list of subscription_ids (at least one) is mandatory for use_case category notifications.

Locale

String

Placeholder if localisation needs to be supported in future

reference

String

Optional reference to the context for which the notification is meant. E.g. could be correlation_id or workflow_id for a use_case notification.

Maybe another notification that was sent earlier.

initiationTime

Timestamp

Protocol suggested format timestamp of when the notification was initiated by the sender

expiry

Timestamp

Expiry of the notification - should be later than initiationTime and currentTime.

message

String

Detailed message - usually picked from the template associated with the topic.

messageData

Key: Value dictionary

Key value pairs containing data for the replaceable attributes in the message template

API details

/notification/notify: return a synchronous acknowledgement of notification being received. Please note that no callback pair is defined for notify API.

Updating the notification subscriptions

APIs to track and expire the notification subscription that will be used by the notification initiating participants to stop sending notifications to the subscribed participants after the expiry trigger condition is satisfied.

There can be two type of subscription expiry conditions:

  1. Event based triggers

  2. Time based triggers

This API will be used by the initiating participants to revoke the subscription access of the receiving participants.

Subscription update alerts

Any change in the subscription from the sending participant would be notified to all the affected receiving participants using the proposed targeted network notification capability. This is proposed to ensure that receiving participants are not inadvertently affected by change in subscription and may trigger renewal workflows for cases when subscriptions are revoked by sending participants.

API Details

/notification/subscription/update

Last updated