Update Notifications API to support AccountPage: Notifications

[ekraffmiller]

The current version of the API returns translated messages that are used in email notifications. We need to update the API (either by adding new properties or creating a new endpoint) that will support the SPA Account:Notifications UI, and other client apps.

To support the SPA, the API would return a key to the message, which will be used to translate in the client side. Also needed are dynamic properties to embed in the translated message.

For example, if a user has been granted a role in a collection, the API response would be:

{
  "id": "1",
  "messageKey": "assignedCollectionRole",
  "properties": [
    {
      "key": "role",
      "value": "Admin"
    },
    {
      "key": "collectionName",
      "value": "Scientific Research"
    },
    {
      "key": "collectionId",
      "value": "1234"
    }
  ],
  "displayAsRead": true,
  "sentTimestamp": "2025-07-17T13:27:33Z"
}

And then in the SPA, the translation file would be:
"notifications.assignedCollectionRole"="You have been granted the role of {{role}} in <1>{{collectionName}}</1>."

It would be the responsibility of the client app to use the id to generate the url.

This is keeping the key value pairs generic, to avoid having to defining class types for the different types of notifications, and make it easier to add new messages.

This is just a proposal, open to different ideas on how to implement this.

[ekraffmiller]

@pdurbin I went back and forth about whether to have the backend or frontend generate urls for the messages. Thinking about it more, since as Jim said the backend will be responsible for generating urls in email notifications, it can use the same logic to pass urls in the UI notifications. In which case, in the above example it can send:

{
  "id": "1",
  "messageKey": "assignedCollectionRole",
  "properties": [
    {
      "key": "role",
      "value": "Admin"
    },
    {
      "key": "collectionName",
      "value": "Scientific Research"
    },
    {
      "key": "collectionUrl",
      "value": "/spa/collections/scientificResearchAlias"
    }
  ],
  "displayAsRead": true,
  "sentTimestamp": "2025-07-17T13:27:33Z"
}

The backend can have templates for generating urls, that can be defined based on the configured UI. What do you think?

[pdurbin]

I started a thread on Zulip about the future of the Notifications API: https://dataverse.zulipchat.com/#narrow/channel/379673-dev/topic/Notifications.20API.20usage.20and.20future/near/530600862

In that thread I linked to a couple branches I'm been playing with:

• Python code to create the same HTML in-app notifications as JSF but with the SPA in mind: https://github.com/gdcc/dataverse-recipes/compare/notifications
• Backend code to expose the necessary data to a client: develop...11648-notification-patterns

I put "patterns" in the name of the backend branch because I was hoping for some patterns to emerge. I've gone through 8 of the 32 notifications and while there are some patterns, the notifications code needs a lot of work. There are lots of weird one-off notifications.

Also, when you perform certain actions via API, notifications are not generated! I originally reported this 10 years ago here:

• Notifications: user notifications not being generated by API calls #1342

@GPortas thinks we should fix this as part of this effort and I agree.

I spoke with @GPortas about all this just now and he's going to jump in the notifications code and hack around a bit. I'm looking forward to comparing notes with him when he emerges. 😄