Support for placeholder keywords for dynamic changes in texts based on recipient

[SandGrainOne]

Description

We want the Notifications service to have solid support for having multiple independent recipients in a single order. This means the texts needs to have some basic support for personalization based on recipient. Like addressing the recipient by name.

There needs to be way for service owners to make smaller recipient specific adjustments to the content of notifications. The feature here should be a search and replace in texts

Keywords copied from Altinn 2 and adjusted for Altinn 3:

Keyword	Description
$recipientFirstName$	The first name of a person *
$recipientMiddleName$	The middle name of a person *
$recipientLastName$	The surname of a person *
$recipientName$	The full name of the recipient, support both person and organization.
$recipientNumber$	The organization number when recipient is an organization. Left empty if recipient is a person.

• Support for first and middle name is postponed untill we have a propper data source.

Example

A simple request with personalized texts:

{
    "subject": "Happy birthday $recipientFirstName$!",
    "body": "Hi $recipientFirstName$, remember to never click any links in emails!",
    "recipients": [
        {
            "nationalIdentityNumber": "18874198354"
        }
    ]
}

There is a new specialized endpoint in Register that should provide what we need:
register/api/v1/parties/nameslookup
See issue: #593

Additional Information

The source of the keyword list above is inspired by Altinn 2 documentation: List of Varselmakroer. The list is curated down to a list of keywords actually being used in Altinn 2.

Refinement

• We can perform the lookup and macro replacements during the order processing. The final texts is added to the generated notifications being written to Kafka topics.
• It's difficult to validate that all keywords in texts are actual keywords for replacement. We'll assume that the application owners will test their texts and fix mistakes like missing $ symbols or typos.
• Investigate if there is a library we can use. Templating/macro.

Tasks

• Verify that the $recipientEmail$
$recipientMobileNumber$ are actually in use before implementing support
• Investigate available templating/macro libraries
  • Library needs to add value outside search and replace of text
  • Can we use the defined keywords or does the library require a different format
• Implement necessary clients for obtaining the Party/Person/Organization objects
  • Some data might already be available through existing clients
  • Add caching of the data where appropriate for easy reuse between lookup and keyword replacement
• Unit/integration tests
• Include a keyword in one of the existing use-case/regression tests
• Documentation
• Review
• Prepare and concuct demo (Altinn internal demo, Friday 13th)

Acceptance criteria

• Original texts is stored without changes including keywords
• Keywords in notification texts are being replaced by the correct values in the final notification(s)
• Documentation includes information about keywords and how they can be used

[olebhansen]

Pending a suitable endpoint to surce data from (#589 #593 )

[SandGrainOne]

Updated the list of keywords we're going to support after the #604 analysis.

[Ahmed-Ghanam]

26.11.2024
During a meeting to assess our requirements, we made the following decisions:

• Initially, we will support only the $recipientName$ and $recipientNumber$ placeholders. Other keywords can be implemented in the future if required.

Action points:

• Check with correspondence team if additional keywords must be supported. (@olebhansen )
• Altinn II documentation mention that an SMS notification can have 700 characters maximum. We need to address this in the current solution.

[olebhansen]

FYI, some tests from team "Melding og Formidling": https://digdir.atlassian.net/wiki/spaces/BF1/pages/2798256130/Melding+med+varsling

[Ahmed-Ghanam]

The documentation has been updated and here is the pull request Altinn/altinn-studio-docs#1951