Enhance per bucket, and per document monitor notification message ctx.

src/main/kotlin/org/opensearch/commons/alerting/model/AggregationResultBucket.kt

@@ -43,6 +43,14 @@
         return builder
     }
 
+    fun asTemplateArg(): Map<String, Any?> {
+        return mapOf(
+            PARENTS_BUCKET_PATH to parentBucketPath,
+            BUCKET_KEYS to bucketKeys,
+            BUCKET to bucket
+        )
+    }
+
     companion object {
         const val CONFIG_NAME = "agg_alert_content"
         const val PARENTS_BUCKET_PATH = "parent_bucket_path"

src/main/kotlin/org/opensearch/commons/alerting/model/Alert.kt

@@ -17,7 +17,7 @@ import org.opensearch.core.xcontent.XContentParserUtils.ensureExpectedToken
 import java.io.IOException
 import java.time.Instant
 
-data class Alert(
+open class Alert(
     val id: String = NO_ID,
     val version: Long = NO_VERSION,
     val schemaVersion: Int = NO_SCHEMA_VERSION,
@@ -591,7 +591,7 @@ data class Alert(
         return builder
     }
 
-    fun asTemplateArg(): Map<String, Any?> {
+    open fun asTemplateArg(): Map<String, Any?> {
         return mapOf(
             ACKNOWLEDGED_TIME_FIELD to acknowledgedTime?.toEpochMilli(),
             ALERT_ID_FIELD to id,
@@ -614,4 +614,101 @@ data class Alert(
             CLUSTERS_FIELD to clusters?.joinToString(",")
         )
     }
+
+    /**
+     * Creates a copy of an [Alert] with optionally modified properties
+     */
+    fun copy(
+        id: String = this.id,
+        version: Long = this.version,
+        schemaVersion: Int = this.schemaVersion,
+        monitorId: String = this.monitorId,
+        workflowId: String = this.workflowId,
+        workflowName: String = this.workflowName,
+        monitorName: String = this.monitorName,
+        monitorVersion: Long = this.monitorVersion,
+        monitorUser: User? = this.monitorUser,
+        triggerId: String = this.triggerId,
+        triggerName: String = this.triggerName,
+        findingIds: List<String> = this.findingIds,
+        relatedDocIds: List<String> = this.relatedDocIds,
+        state: State = this.state,
+        startTime: Instant = this.startTime,
+        endTime: Instant? = this.endTime,
+        lastNotificationTime: Instant? = this.lastNotificationTime,
+        acknowledgedTime: Instant? = this.acknowledgedTime,
+        errorMessage: String? = this.errorMessage,
+        errorHistory: List<AlertError> = this.errorHistory,
+        severity: String = this.severity,
+        actionExecutionResults: List<ActionExecutionResult> = this.actionExecutionResults,
+        aggregationResultBucket: AggregationResultBucket? = this.aggregationResultBucket,
+        executionId: String? = this.executionId,
+        associatedAlertIds: List<String> = this.associatedAlertIds,
+        clusters: List<String>? = this.clusters
+    ): Alert {
+        return Alert(
+            id = id,
+            version = version,
+            schemaVersion = schemaVersion,
+            monitorId = monitorId,
+            workflowId = workflowId,
+            workflowName = workflowName,
+            monitorName = monitorName,
+            monitorVersion = monitorVersion,
+            monitorUser = monitorUser,
+            triggerId = triggerId,
+            triggerName = triggerName,
+            findingIds = findingIds,
+            relatedDocIds = relatedDocIds,
+            state = state,
+            startTime = startTime,
+            endTime = endTime,
+            lastNotificationTime = lastNotificationTime,
+            acknowledgedTime = acknowledgedTime,
+            errorMessage = errorMessage,
+            errorHistory = errorHistory,
+            severity = severity,
+            actionExecutionResults = actionExecutionResults,
+            aggregationResultBucket = aggregationResultBucket,
+            executionId = executionId,
+            associatedAlertIds = associatedAlertIds,
+            clusters = clusters
+        )
+    }
+
+    override fun equals(other: Any?): Boolean {
+        if (this === other) return true
+        if (javaClass != other?.javaClass) return false
+
+        other as Alert
+
+        if (id != other.id) return false
+        if (version != other.version) return false
+        if (schemaVersion != other.schemaVersion) return false
+        if (monitorId != other.monitorId) return false
+        if (workflowId != other.workflowId) return false
+        if (workflowName != other.workflowName) return false
+        if (monitorName != other.monitorName) return false
+        if (monitorVersion != other.monitorVersion) return false
+        if (monitorUser != other.monitorUser) return false
+        if (triggerId != other.triggerId) return false
+        if (triggerName != other.triggerName) return false
+        if (findingIds != other.findingIds) return false
+        if (relatedDocIds != other.relatedDocIds) return false
+        if (state != other.state) return false
+        if (startTime != other.startTime) return false
+        if (endTime != other.endTime) return false
+        if (lastNotificationTime != other.lastNotificationTime) return false
+        if (acknowledgedTime != other.acknowledgedTime) return false
+        if (errorMessage != other.errorMessage) return false
+        if (errorHistory != other.errorHistory) return false
+        if (severity != other.severity) return false
+        if (actionExecutionResults != other.actionExecutionResults) return false
+        if (aggregationResultBucket != other.aggregationResultBucket) return false
+        if (executionId != other.executionId) return false
+        if (associatedAlertIds != other.associatedAlertIds) return false
+        if (clusters != other.clusters) return false
+
+        return true
+    }
 }

src/main/kotlin/org/opensearch/commons/alerting/model/AlertContext.kt

@@ -0,0 +1,74 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package org.opensearch.commons.alerting.model
+
+/**
+ * This model is a wrapper for [Alert] that should only be used to create a more
+ * informative alert object to enrich mustache template notification messages.
+ */
+data class AlertContext(
+    val alert: Alert,
+    val associatedQueries: List<DocLevelQuery>? = null,
+    val sampleDocs: List<Map<String, Any?>>? = null
+) : Alert(
+    id = alert.id,
+    version = alert.version,
+    schemaVersion = alert.schemaVersion,
+    monitorId = alert.monitorId,
+    monitorName = alert.monitorName,
+    monitorVersion = alert.monitorVersion,
+    monitorUser = alert.monitorUser,
+    triggerId = alert.triggerId,
+    triggerName = alert.triggerName,
+    state = alert.state,
+    startTime = alert.startTime,
+    endTime = alert.endTime,
+    lastNotificationTime = alert.lastNotificationTime,
+    acknowledgedTime = alert.acknowledgedTime,
+    errorMessage = alert.errorMessage,
+    errorHistory = alert.errorHistory,
+    severity = alert.severity,
+    actionExecutionResults = alert.actionExecutionResults,
+    aggregationResultBucket = alert.aggregationResultBucket,
+    findingIds = alert.findingIds,
+    relatedDocIds = alert.relatedDocIds,
+    executionId = alert.executionId,
+    workflowId = alert.workflowId,
+    workflowName = alert.workflowName,
+    associatedAlertIds = alert.associatedAlertIds,
+    clusters = alert.clusters
+) {
+
+    override fun asTemplateArg(): Map<String, Any?> {
+        val queriesContext = associatedQueries?.map {
+            mapOf(
+                DocLevelQuery.QUERY_ID_FIELD to it.id,
+                DocLevelQuery.NAME_FIELD to it.name,
+                DocLevelQuery.TAGS_FIELD to it.tags
+            )
+        }
+
+        // Compile the custom context fields.
+        val customContextFields = mapOf(
+            ASSOCIATED_QUERIES_FIELD to queriesContext,
+            SAMPLE_DOCS_FIELD to sampleDocs
+        )
+
+        // Get the alert template args
+        val templateArgs = super.asTemplateArg().toMutableMap()
+
+        // Add the non-null custom context fields to the alert templateArgs.
+        customContextFields.forEach { (key, value) ->
+            value?.let { templateArgs[key] = it }
+        }
+        return templateArgs
+    }
+
+    companion object {
+        const val ASSOCIATED_QUERIES_FIELD = "associated_queries"
+        const val SAMPLE_DOCS_FIELD = "sample_documents"
+    }
+}

src/test/kotlin/org/opensearch/commons/alerting/AlertTests.kt

@@ -2,6 +2,8 @@ package org.opensearch.commons.alerting
 
 import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertFalse
+import org.junit.jupiter.api.Assertions.assertTrue
 import org.junit.jupiter.api.Test
 import org.opensearch.commons.alerting.model.Alert
 import java.time.Instant
@@ -84,4 +86,128 @@ class AlertTests {
         assertEquals(alert.id, "")
         assertEquals(workflow.id, alert.workflowId)
     }
+
+    @Test
+    fun `test alert copy`() {
+        val alert = randomAlert()
+
+        val copiedAlert = alert.copy()
+
+        assertEquals(alert.id, copiedAlert.id)
+        assertEquals(alert.version, copiedAlert.version)
+        assertEquals(alert.schemaVersion, copiedAlert.schemaVersion)
+        assertEquals(alert.monitorId, copiedAlert.monitorId)
+        assertEquals(alert.workflowId, copiedAlert.workflowId)
+        assertEquals(alert.workflowName, copiedAlert.workflowName)
+        assertEquals(alert.monitorName, copiedAlert.monitorName)
+        assertEquals(alert.monitorVersion, copiedAlert.monitorVersion)
+        assertEquals(alert.monitorUser, copiedAlert.monitorUser)
+        assertEquals(alert.triggerId, copiedAlert.triggerId)
+        assertEquals(alert.triggerName, copiedAlert.triggerName)
+        assertEquals(alert.findingIds, copiedAlert.findingIds)
+        assertEquals(alert.relatedDocIds, copiedAlert.relatedDocIds)
+        assertEquals(alert.state, copiedAlert.state)
+        assertEquals(alert.startTime, copiedAlert.startTime)
+        assertEquals(alert.endTime, copiedAlert.endTime)
+        assertEquals(alert.lastNotificationTime, copiedAlert.lastNotificationTime)
+        assertEquals(alert.acknowledgedTime, copiedAlert.acknowledgedTime)
+        assertEquals(alert.errorMessage, copiedAlert.errorMessage)
+        assertEquals(alert.errorHistory, copiedAlert.errorHistory)
+        assertEquals(alert.severity, copiedAlert.severity)
+        assertEquals(alert.actionExecutionResults, copiedAlert.actionExecutionResults)
+        assertEquals(alert.aggregationResultBucket, copiedAlert.aggregationResultBucket)
+        assertEquals(alert.executionId, copiedAlert.executionId)
+        assertEquals(alert.associatedAlertIds, copiedAlert.associatedAlertIds)
+        assertEquals(alert.clusters, copiedAlert.clusters)
+    }
+
+    @Test
+    fun `test alert copy with modified properties`() {
+        val alert = randomAlert()
+        val newAlertValues = randomAlert()
+
+        val alertCopy = alert.copy(
+            id = newAlertValues.id,
+            triggerId = newAlertValues.triggerId,
+            triggerName = newAlertValues.triggerName,
+            actionExecutionResults = newAlertValues.actionExecutionResults,
+            clusters = newAlertValues.clusters
+        )
+
+        // Modified properties; compare to newAlertValues
+        assertEquals(newAlertValues.id, alertCopy.id)
+        assertEquals(newAlertValues.triggerId, alertCopy.triggerId)
+        assertEquals(newAlertValues.triggerName, alertCopy.triggerName)
+        assertEquals(newAlertValues.actionExecutionResults, alertCopy.actionExecutionResults)
+        assertEquals(newAlertValues.clusters, alertCopy.clusters)
+
+        // Retained values; compare to original alert
+        assertEquals(alert.version, alertCopy.version)
+        assertEquals(alert.schemaVersion, alertCopy.schemaVersion)
+        assertEquals(alert.monitorId, alertCopy.monitorId)
+        assertEquals(alert.workflowId, alertCopy.workflowId)
+        assertEquals(alert.workflowName, alertCopy.workflowName)
+        assertEquals(alert.monitorName, alertCopy.monitorName)
+        assertEquals(alert.monitorVersion, alertCopy.monitorVersion)
+        assertEquals(alert.monitorUser, alertCopy.monitorUser)
+        assertEquals(alert.findingIds, alertCopy.findingIds)
+        assertEquals(alert.relatedDocIds, alertCopy.relatedDocIds)
+        assertEquals(alert.state, alertCopy.state)
+        assertEquals(alert.startTime, alertCopy.startTime)
+        assertEquals(alert.endTime, alertCopy.endTime)
+        assertEquals(alert.lastNotificationTime, alertCopy.lastNotificationTime)
+        assertEquals(alert.acknowledgedTime, alertCopy.acknowledgedTime)
+        assertEquals(alert.errorMessage, alertCopy.errorMessage)
+        assertEquals(alert.errorHistory, alertCopy.errorHistory)
+        assertEquals(alert.severity, alertCopy.severity)
+        assertEquals(alert.aggregationResultBucket, alertCopy.aggregationResultBucket)
+        assertEquals(alert.executionId, alertCopy.executionId)
+        assertEquals(alert.associatedAlertIds, alertCopy.associatedAlertIds)
+    }
+
+    @Test
+    fun `test alert equals with duplicate alerts`() {
+        val alert = randomAlert()
+        val alertCopy = alert.copy()
+
+        val alertsMatch = alert.equals(alertCopy)
+
+        assertTrue(alertsMatch)
+    }
+
+    @Test
+    fun `test alert equals with different alerts`() {
+        val alert = randomAlert()
+        val newAlertValues = randomAlert()
+        val alertCopy = alert.copy(
+            id = newAlertValues.id,
+            triggerId = newAlertValues.triggerId,
+            triggerName = newAlertValues.triggerName,
+            actionExecutionResults = newAlertValues.actionExecutionResults,
+            clusters = newAlertValues.clusters
+        )
+
+        val alertsMatch = alert.equals(alertCopy)
+
+        assertFalse(alertsMatch)
+    }
+
+    @Test
+    fun `test alert equals with null alert`() {
+        val alert = randomAlert()
+
+        val alertsMatch = alert.equals(null)
+
+        assertFalse(alertsMatch)
+    }
+
+    @Test
+    fun `test alert equals with alertContext`() {
+        val alert = randomAlert()
+        val alertContext = randomAlertContext(alert = alert)
+
+        val alertsMatch = alert.equals(alertContext)
+
+        assertFalse(alertsMatch)
+    }
 }

src/test/kotlin/org/opensearch/commons/alerting/TestHelpers.kt

@@ -20,6 +20,7 @@ import org.opensearch.commons.alerting.aggregation.bucketselectorext.BucketSelec
 import org.opensearch.commons.alerting.model.ActionExecutionResult
 import org.opensearch.commons.alerting.model.AggregationResultBucket
 import org.opensearch.commons.alerting.model.Alert
+import org.opensearch.commons.alerting.model.AlertContext
 import org.opensearch.commons.alerting.model.BucketLevelTrigger
 import org.opensearch.commons.alerting.model.ChainedAlertTrigger
 import org.opensearch.commons.alerting.model.ChainedMonitorFindings
@@ -601,3 +602,22 @@ fun randomFinding(
         timestamp = timestamp
     )
 }
+
+fun randomAlertContext(
+    alert: Alert = randomAlert(),
+    associatedQueries: List<DocLevelQuery>? = (-1..2).random().takeIf { it != -1 }?.let {
+        (0..it).map { randomDocLevelQuery() }
+    },
+    sampleDocs: List<Map<String, Any?>>? = (-1..2).random().takeIf { it != -1 }?.let {
+        (0..it).map {
+            // Using 'randomFinding' to mimic documents in an index.
+            randomFinding().asTemplateArg()
+        }
+    }
+): AlertContext {
+    return AlertContext(
+        alert = alert,
+        associatedQueries = associatedQueries,
+        sampleDocs = sampleDocs
+    )
+}