PDJB-268: Add joint landlord invitation expiry scheduled task and notification email

src/main/kotlin/uk/gov/communities/prsdb/webapp/application/JointLandlordInvitationExpiryEmailTaskApplicationRunner.kt

@@ -0,0 +1,42 @@
+package uk.gov.communities.prsdb.webapp.application
+
+import org.springframework.boot.ApplicationArguments
+import org.springframework.boot.ApplicationRunner
+import org.springframework.boot.SpringApplication
+import org.springframework.context.ApplicationContext
+import uk.gov.communities.prsdb.webapp.annotations.taskAnnotations.PrsdbScheduledTask
+import uk.gov.communities.prsdb.webapp.services.JointLandlordInvitationExpiryEmailService
+import kotlin.system.exitProcess
+
+@PrsdbScheduledTask("jl-invitation-expiry-email-scheduled-task")
+class JointLandlordInvitationExpiryEmailTaskApplicationRunner(
+    private val context: ApplicationContext,
+    private val jointLandlordInvitationExpiryEmailService: JointLandlordInvitationExpiryEmailService,
+) : ApplicationRunner {
+    override fun run(args: ApplicationArguments?) {
+        println("Executing joint landlord invitation expiry email scheduled task")
+
+        // Separating into its own method to allow this to be tested without "exitProcess" being called
+        sendJointLandlordInvitationExpiryEmailsTaskLogic()
+
+        val code =
+            SpringApplication.exit(context, { 0 }).also {
+                println("Scheduled task executed. Application will exit now.")
+            }
+        exitProcess(code)
+    }
+
+    private fun sendJointLandlordInvitationExpiryEmailsTaskLogic() {
+        val processedIds = jointLandlordInvitationExpiryEmailService.sendExpiryEmailsForExpiredInvitations()
+
+        processedIds.forEach { id ->
+            println("Sent expiry email for joint landlord invitation with id: $id")
+        }
+
+        println("Sent expiry emails for ${processedIds.size} joint landlord invitations.")
+    }
+
+    companion object {
+        const val SEND_JOINT_LANDLORD_INVITATION_EXPIRY_EMAILS_TASK_METHOD_NAME = "sendJointLandlordInvitationExpiryEmailsTaskLogic"
+    }
+}

src/main/kotlin/uk/gov/communities/prsdb/webapp/constants/InvitationLifetimeConstants.kt

@@ -1,4 +1,4 @@
 package uk.gov.communities.prsdb.webapp.constants
 
 const val LOCAL_COUNCIL_INVITATION_LIFETIME_IN_HOURS: Int = 48
-const val JOINT_LANDLORD_INVITATION_LIFETIME_IN_DAYS = 28
+const val JOINT_LANDLORD_INVITATION_LIFETIME_IN_DAYS: Int = 28

src/main/kotlin/uk/gov/communities/prsdb/webapp/database/entity/JointLandlordInvitation.kt

@@ -39,6 +39,14 @@ class JointLandlordInvitation(
     lateinit var invitingLandlord: Landlord
         private set
 
+    @Column(nullable = false)
+    var invitationExpiredEmailSent: Boolean = false
+        private set
+
+    fun markAsExpiredEmailSent() {
+        invitationExpiredEmailSent = true
+    }
+
     constructor(
         token: UUID,
         email: String,

src/main/kotlin/uk/gov/communities/prsdb/webapp/database/repository/JointLandlordInvitationRepository.kt

@@ -2,8 +2,11 @@ package uk.gov.communities.prsdb.webapp.database.repository
 
 import org.springframework.data.jpa.repository.JpaRepository
 import uk.gov.communities.prsdb.webapp.database.entity.JointLandlordInvitation
+import java.time.Instant
 import java.util.UUID
 
 interface JointLandlordInvitationRepository : JpaRepository<JointLandlordInvitation, Long> {
     fun findByToken(token: UUID): JointLandlordInvitation?
+
+    fun findAllByInvitationExpiredEmailSentFalseAndCreatedDateBefore(cutoff: Instant): List<JointLandlordInvitation>
 }

src/main/kotlin/uk/gov/communities/prsdb/webapp/models/viewModels/emailModels/EmailTemplateModel.kt

@@ -29,4 +29,5 @@ enum class EmailTemplate {
     LOCAL_COUNCIL_USER_INVITATION_INFORM_ADMIN_EMAIL,
     INCOMPLETE_PROPERTY_REMINDER_EMAIL,
     JOINT_LANDLORD_INVITATION_EMAIL,
+    JOINT_LANDLORD_INVITATION_EXPIRY_EMAIL,
 }

src/main/kotlin/uk/gov/communities/prsdb/webapp/models/viewModels/emailModels/JointLandlordInvitationExpiryEmail.kt

@@ -0,0 +1,28 @@
+package uk.gov.communities.prsdb.webapp.models.viewModels.emailModels
+
+import java.net.URI
+
+data class JointLandlordInvitationExpiryEmail(
+    val recipientName: String,
+    val invitedEmail: String,
+    val propertyAddress: String,
+    val propertyRecordUri: URI,
+    val expiryDays: Int,
+) : EmailTemplateModel {
+    private val recipientNameKey = "recipientName"
+    private val invitedEmailKey = "invitedEmail"
+    private val propertyAddressKey = "propertyAddress"
+    private val propertyRecordUrlKey = "propertyRecordUrl"
+    private val expiryDaysKey = "expiryDays"
+
+    override val template = EmailTemplate.JOINT_LANDLORD_INVITATION_EXPIRY_EMAIL
+
+    override fun toHashMap(): HashMap<String, String> =
+        hashMapOf(
+            recipientNameKey to recipientName,
+            invitedEmailKey to invitedEmail,
+            propertyAddressKey to propertyAddress,
+            propertyRecordUrlKey to propertyRecordUri.toString(),
+            expiryDaysKey to expiryDays.toString(),
+        )
+}

src/main/kotlin/uk/gov/communities/prsdb/webapp/services/AbsoluteUrlProvider.kt

@@ -50,6 +50,9 @@ class AbsoluteUrlProvider(
             .toUri()
     }
 
+    fun buildLandlordPropertyDetailsUri(propertyOwnershipId: Long): URI =
+        uriFromMethodCall(on(PropertyDetailsController::class.java).getPropertyDetails(propertyOwnershipId))
+
     private fun uriFromMethodCall(info: Any): URI {
         val methodCallUriComponents =
             MvcUriComponentsBuilder

src/main/kotlin/uk/gov/communities/prsdb/webapp/services/JointLandlordInvitationExpiryEmailService.kt

@@ -0,0 +1,92 @@
+package uk.gov.communities.prsdb.webapp.services
+
+import org.springframework.context.annotation.Primary
+import uk.gov.communities.prsdb.webapp.annotations.taskAnnotations.PrsdbTaskService
+import uk.gov.communities.prsdb.webapp.annotations.webAnnotations.PrsdbFlip
+import uk.gov.communities.prsdb.webapp.constants.JOINT_LANDLORDS
+import uk.gov.communities.prsdb.webapp.constants.JOINT_LANDLORD_INVITATION_LIFETIME_IN_DAYS
+import uk.gov.communities.prsdb.webapp.database.entity.JointLandlordInvitation
+import uk.gov.communities.prsdb.webapp.database.entity.Landlord
+import uk.gov.communities.prsdb.webapp.database.entity.PropertyOwnership
+import uk.gov.communities.prsdb.webapp.database.repository.JointLandlordInvitationRepository
+import uk.gov.communities.prsdb.webapp.exceptions.PersistentEmailSendException
+import uk.gov.communities.prsdb.webapp.exceptions.TransientEmailSentException
+import uk.gov.communities.prsdb.webapp.models.viewModels.emailModels.JointLandlordInvitationExpiryEmail
+import java.time.Instant
+import java.time.temporal.ChronoUnit
+
+@PrsdbFlip(name = JOINT_LANDLORDS, alterBean = "joint-landlord-invitation-expiry-email-flag-on")
+interface JointLandlordInvitationExpiryEmailService {
+    fun sendExpiryEmailsForExpiredInvitations(): List<Long>
+}
+
+@Primary
+@PrsdbTaskService("joint-landlord-invitation-expiry-email-flag-off")
+class JointLandlordInvitationExpiryEmailServiceImplFlagOff : JointLandlordInvitationExpiryEmailService {
+    override fun sendExpiryEmailsForExpiredInvitations(): List<Long> {
+        // No-op: the joint-landlords feature is disabled, so we do not send expiry emails.
+        return emptyList()
+    }
+}
+
+@PrsdbTaskService("joint-landlord-invitation-expiry-email-flag-on")
+class JointLandlordInvitationExpiryEmailServiceImplFlagOn(
+    private val invitationRepository: JointLandlordInvitationRepository,
+    private val expiryEmailNotificationService: EmailNotificationService<JointLandlordInvitationExpiryEmail>,
+    private val absoluteUrlProvider: AbsoluteUrlProvider,
+) : JointLandlordInvitationExpiryEmailService {
+    override fun sendExpiryEmailsForExpiredInvitations(): List<Long> {
+        val cutoff = Instant.now().minus(JOINT_LANDLORD_INVITATION_LIFETIME_IN_DAYS.toLong(), ChronoUnit.DAYS)
+        val expiredInvitations =
+            invitationRepository
+                .findAllByInvitationExpiredEmailSentFalseAndCreatedDateBefore(cutoff)
+                .filter { it.isExpired } // to be safe
+        val expiredIds = mutableListOf<Long>()
+
+        expiredInvitations.forEach { invitation ->
+            try {
+                sendExpiryEmailsForInvitation(invitation)
+                invitation.markAsExpiredEmailSent()
+                invitationRepository.save(invitation)
+                expiredIds.add(invitation.id)
+            } catch (ex: PersistentEmailSendException) {
+                printFailureMessage(ex, invitation)
+            } catch (ex: TransientEmailSentException) {
+                printFailureMessage(ex, invitation)
+            }
+        }
+
+        return expiredIds
+    }
+
+    private fun sendExpiryEmailsForInvitation(invitation: JointLandlordInvitation) {
+        val propertyOwnership = invitation.registeredOwnership
+        val propertyAddress = propertyOwnership.address.toMultiLineAddress()
+        val propertyRecordUri = absoluteUrlProvider.buildLandlordPropertyDetailsUri(propertyOwnership.id)
+
+        getExpiryEmailRecipients(propertyOwnership).forEach { recipient ->
+            expiryEmailNotificationService.sendEmail(
+                recipient.email,
+                JointLandlordInvitationExpiryEmail(
+                    recipientName = recipient.name,
+                    invitedEmail = invitation.invitedEmail,
+                    propertyAddress = propertyAddress,
+                    propertyRecordUri = propertyRecordUri,
+                    expiryDays = JOINT_LANDLORD_INVITATION_LIFETIME_IN_DAYS,
+                ),
+            )
+        }
+    }
+
+    // TODO PDJB-432: include accepted joint landlords once that data model exists.
+    private fun getExpiryEmailRecipients(propertyOwnership: PropertyOwnership): List<Landlord> = listOf(propertyOwnership.primaryLandlord)
+
+    private fun printFailureMessage(
+        ex: Exception,
+        invitation: JointLandlordInvitation,
+    ) {
+        println("Failed to send expiry email for joint landlord invitation with id: ${invitation.id}")
+        println("Exception message: ${ex.message}")
+        println("Stack trace: ${ex.stackTraceToString()}")
+    }
+}

src/main/resources/db/migrations/V1_29_0__add_expired_flag_to_joint_landlord_invitation.sql

@@ -0,0 +1 @@
+ALTER TABLE joint_landlord_invitation ADD COLUMN invitation_expired_email_sent BOOLEAN NOT NULL DEFAULT FALSE;

src/main/resources/emails/JointLandlordInvitationExpiry.md

@@ -0,0 +1,21 @@
+Hello ((recipientName)),
+
+((invitedEmail)) was invited to be a joint landlord for:
+
+((propertyAddress))
+
+We sent them an invitation, but did not hear back. As it has been over ((expiryDays)) days, the invitation has now expired.
+
+# What to do next
+
+All joint landlords must be registered on the property.
+
+If this person is a landlord, invite them again. If you can, contact them and ask them to accept the invitation.
+
+[View property record](((propertyRecordUrl)))
+
+Keep this email so you can reference it later.
+
+---
+
+This is an automated email – do not reply.

src/main/resources/emails/emailTemplates.json

@@ -155,5 +155,12 @@
     "enumName": "JOINT_LANDLORD_INVITATION_EMAIL",
     "subject": "You've been invited to join a rental property registration",
     "bodyLocation": "/emails/JointLandlordInvitation.md"
+  },
+  {
+    "test_id": "829697a4-7432-4683-bb43-29f73da609d4",
+    "prod_id": "0bb9ffed-9319-4369-b9e1-2c7d54d11326",
+    "enumName": "JOINT_LANDLORD_INVITATION_EXPIRY_EMAIL",
+    "subject": "Your invitation to a joint landlord has expired",
+    "bodyLocation": "/emails/JointLandlordInvitationExpiry.md"
   }
 ]

src/test/kotlin/uk/gov/communities/prsdb/webapp/applications/PrsdbTaskApplicationTests.kt

@@ -79,6 +79,10 @@ class PrsdbTaskApplicationTests {
                 PropertyOwnershipSearchRepositoryImpl::class.simpleBeanName,
                 LandlordSearchRepositoryImpl::class.simpleBeanName,
                 IncompletePropertiesService::class.simpleBeanName,
+                // when the feature flagged variant is removed the name overrides from JointLandlordInvitationExpiryEmailService can be removed.
+                // then, this can be replaced by JointLandlordInvitationExpiryEmailService::class.simpleBeanName
+                "joint-landlord-invitation-expiry-email-flag-off",
+                "joint-landlord-invitation-expiry-email-flag-on",
             ).map { it.lowercase() }.toSet()
 
         val beanNames = ApplicationTestHelper.getAvailableBeanNames(context!!)

src/test/kotlin/uk/gov/communities/prsdb/webapp/models/viewModels/emailModels/EmailTemplateModelsTests.kt

@@ -172,6 +172,16 @@ class EmailTemplateModelsTests {
                     JointLandlordInvitationEmail("John Smith", "1 Fake Street, London", URI("invitationUrl")),
                     "/emails/JointLandlordInvitation.md",
                 ),
+                EmailTemplateTestData(
+                    JointLandlordInvitationExpiryEmail(
+                        recipientName = "Lois",
+                        invitedEmail = "invited@example.com",
+                        propertyAddress = "1 Fake Street\nLondon\nSW1A 1AA",
+                        propertyRecordUri = URI("propertyRecordUrl"),
+                        expiryDays = 28,
+                    ),
+                    "/emails/JointLandlordInvitationExpiry.md",
+                ),
             )
     }
 

src/test/kotlin/uk/gov/communities/prsdb/webapp/scheduledTaskRunners/JointLandlordInvitationExpiryEmailTaskApplicationRunnerTests.kt

@@ -0,0 +1,39 @@
+package uk.gov.communities.prsdb.webapp.scheduledTaskRunners
+
+import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.extension.ExtendWith
+import org.mockito.InjectMocks
+import org.mockito.Mock
+import org.mockito.junit.jupiter.MockitoExtension
+import org.mockito.kotlin.verify
+import org.springframework.context.ApplicationContext
+import uk.gov.communities.prsdb.webapp.application.JointLandlordInvitationExpiryEmailTaskApplicationRunner
+import uk.gov.communities.prsdb.webapp.application.JointLandlordInvitationExpiryEmailTaskApplicationRunner.Companion.SEND_JOINT_LANDLORD_INVITATION_EXPIRY_EMAILS_TASK_METHOD_NAME
+import uk.gov.communities.prsdb.webapp.services.JointLandlordInvitationExpiryEmailService
+
+@ExtendWith(MockitoExtension::class)
+class JointLandlordInvitationExpiryEmailTaskApplicationRunnerTests {
+    @Mock
+    private lateinit var context: ApplicationContext
+
+    @Mock
+    private lateinit var jointLandlordInvitationExpiryEmailService: JointLandlordInvitationExpiryEmailService
+
+    @InjectMocks
+    private lateinit var runner: JointLandlordInvitationExpiryEmailTaskApplicationRunner
+
+    @Test
+    fun `sendJointLandlordInvitationExpiryEmailsTaskLogic calls service to send expiry emails`() {
+        // Arrange
+        val method =
+            JointLandlordInvitationExpiryEmailTaskApplicationRunner::class.java
+                .getDeclaredMethod(SEND_JOINT_LANDLORD_INVITATION_EXPIRY_EMAILS_TASK_METHOD_NAME)
+        method.isAccessible = true
+
+        // Act
+        method.invoke(runner)
+
+        // Assert
+        verify(jointLandlordInvitationExpiryEmailService).sendExpiryEmailsForExpiredInvitations()
+    }
+}