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

[Ahmed-Ghanam]

The planning and implementation stages of this task took longer than expected because of the need to handle edge cases. I updated the size from L to XL

[Ahmed-Ghanam]

Test Outcome: 15.01.2025

Use Case Tested:

The following notification order was tested:

{
  "sendersReference": "order-email-with-keywords",
  "recipients": [
    {
      "organizationNumber": "313600947"
    },
    {
      "nationalIdentityNumber": "01124801679"
    },
    {
      "emailAddress": "[email protected]"
    }
  ],
  "ignoreReservation": true,
  "notificationChannel": "Email",
  "emailTemplate": {
    "fromAddress": "[email protected]",
    "subject": "Hello $recipientName$! Test Email",
    "body": "Hi $recipientName$, this Email is tailored for $recipientNumber$.",
    "contentType": "Plain"
  }
}

Expected Outcome:

Notifications should be sent via email with keywords $recipientName$ and $recipientNumber$ replaced with recipient-specific data.

Actual Outcome:

The results were as expected:

1. Recipient - organizationNumber: 313600947
   

2. Recipient - nationalIdentityNumber: 01124801679
   

3. Recipient - emailAddress: [email protected]
   

[SandGrainOne]

1. Tested lookup for person name and organization name for both email and sms. Looks good.
2. The keyword $recipientNumber$ is correctly replaced with empty.string when recipient is a person.
3. The keyword $recipientNumber$ is correctly replaced by the organization number when recipient is an organization.
4. The customized texts are correctly stored in the notification tables.

[Ahmed-Ghanam]

Test Outcome: 15.01.2025

Use Case Tested:

The following notification order was tested:

{
  "sendersReference": "order-sms-keywords",
  "recipients": [
    {
      "mobileNumber": "+4746269164"
    },
    {
      "organizationNumber": "313600947"
    },
    {
      "nationalIdentityNumber": "01124801679"
    }
  ],
  "ignoreReservation": true,
  "notificationChannel": "SMS",
  "smsTemplate": {
    "senderNumber": "+4746269164",
    "body": "Hi $recipientName$, this SMS is customized for $recipientNumber$."
  }
}

Expected Outcome:

Notifications should be sent via SMS with keywords $recipientName$ and $recipientNumber$ replaced with recipient-specific data.

Actual Outcome:

The results were as expected:

1. Recipient - organizationNumber: 313600947
2. Recipient - nationalIdentityNumber: 01124801679
3. Recipient - mobileNumber: +4746269164