Event View Model Details schema for validation and documentation (#13)

* Define EVM detail reference schema for MD and validation

* Put minor updates to templates stuff

* Add built EVM details ref

* Refer to EVM docs in other doc parts

* Update EVM schema for synthetics and NMS

* Fix columns order for markdown refs

.github/workflows/ci.yml

@@ -21,4 +21,4 @@ jobs:
         with:
           go-version: 1.18
       - name: Run tests
-        run: go test ./...
+        run: make test

Makefile

@@ -0,0 +1,10 @@
+.PHONY: all docs test
+
+all: test docs
+
+docs:
+	go run ./cmd/docs
+
+test:
+	go test ./...
+

README.md

@@ -12,7 +12,7 @@ Within the [Templates](templates/) directory you can find ready, baseline custom
 
 ## Using Custom Webhook Templating
 
-[Using Custom Webhook Templating](docs/TEMPLATING_REFERENCE.md) provides comprehensive details on how notifications are being rendered and what syntax, variables, methods and functions are available. It can help you get familiar with how to develop new templates and how to customize your existing ones.
+[Using Custom Webhook Templating](docs/TEMPLATING_REFERENCE.md) provides comprehensive details on how notifications are being rendered and what syntax, variables, methods and functions are available. Additionally, refer to [EventViewModel Details reference](docs/EVENT_VIEW_MODEL_DETAILS_REFERENCE.md) to learn what kind of information is provided within the notifications. It can help you get familiar with how to develop new templates and how to customize your existing ones.
 
 ## How to Develop and Test New Template
 

cmd/docs/main.go

@@ -0,0 +1,21 @@
+package main
+
+import (
+	"flag"
+	"log"
+	"os"
+
+	"github.com/kentik/custom-notification-templates/schemas"
+)
+
+func main() {
+	outputPath := flag.String("output", "./docs/EVENT_VIEW_MODEL_DETAILS_REFERENCE.md", "Markdown output file path")
+
+	details := schemas.Details()
+	md := schemas.IntoMarkdown(details)
+
+	err := os.WriteFile(*outputPath, []byte(md), 0644)
+	if err != nil {
+		log.Fatalf("Error writing to %s: %s", *outputPath, err)
+	}
+}

docs/TEMPLATING_REFERENCE.md

@@ -151,11 +151,12 @@ This will result in the following JSON payload on render:
 - `IsActive` *boolean* - Indicates whether the event is considered active (the trigger causing the event to be propagated is ongoing).
 - `StartTime` *string* - RFC-3339-formatted timestamp displays when the trigger first occurred.
 - `EndTime` *string* - RFC-3339-formatted timestamp displays when the trigger stopped occurring, or displays the string `ongoing` if it is still active.
-- `CurrentState` *string* - Current state of the trigger (depends on the type of state).
-- `PreviousState` *string* - Previous state of the trigger (depends on the type of state).
+- `CurrentState` *string* - Current state of the notification trigger (depends on the type of state, hence it is only descriptive).
+- `PreviousState` *string* - Previous state of the notification trigger (depends on the type of state, hence it is only descriptive).
 - `StartTimestamp` *integer* - Unix timestamp of when the trigger first occurred.
 - `EndTimestamp` *integer* - Unix timestamp of when the trigger stopped occurring.
-- `Details` *array of objects* - Type-specific properties collection grouped by tags.
+- `Details` *array of objects* - Type-specific properties collection grouped by tags. [Details reference](EVENT_VIEW_MODEL_DETAILS_REFERENCE.md)
+- `Importance`
 
 **Example - JSON template for immediate notifications with a custom header:**
 
@@ -221,6 +222,8 @@ The following filtering methods return a details object, so that other Detail me
 - `Details.WithTag tag` - Filter the details to show those with the given tag.
 - `Details.WithNames ...names` - Filter the details to display only those with the given names.
 
+Comprehensive [details reference here](EVENT_VIEW_MODEL_DETAILS_REFERENCE.md).
+
 **Example - Template rendering all event URLs and metrics:**
 
 ```go-template

go.mod

@@ -1,3 +1,13 @@
 module github.com/kentik/custom-notification-templates
 
-go 1.17
+go 1.21
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	github.com/stretchr/testify v1.9.0 // indirect
+	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
+	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
+	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,18 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
+github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
+github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

pkg/samples.go

@@ -1,6 +1,8 @@
 package main
 
-import "time"
+import (
+	"time"
+)
 
 var TestingViewModels = map[string]*NotificationViewModel{
 	"insight":    TestInsight,
@@ -226,7 +228,7 @@ var TestAlarm = &NotificationViewModel{
 			IsActive:       true,
 			StartTime:      "2021-11-17 10:29:32 UTC",
 			EndTime:        "ongoing",
-			CurrentState:   "alarm",
+			CurrentState:   "active",
 			PreviousState:  "new",
 			StartTimestamp: 1637144972,
 			EndTimestamp:   0,
@@ -251,6 +253,12 @@ var TestAlarm = &NotificationViewModel{
 					Value: "UDP Fragments Attack",
 					Tag:   "",
 				},
+				&EventViewModelDetail{
+					Name:  "AlarmPolicyLabels",
+					Label: "Policy Labels",
+					Value: "foo, bar, baz",
+					Tag:   "",
+				},
 				&EventViewModelDetail{
 					Name:  "AlarmPolicyID",
 					Label: "Policy ID",
@@ -381,7 +389,7 @@ var TestSynth = &NotificationViewModel{
 			Description:    "Synthetics Test My DNS Server Grid Critical",
 			IsActive:       true,
 			StartTime:      "2021-11-29 11:43:31 UTC",
-			CurrentState:   "alarm",
+			CurrentState:   "active",
 			PreviousState:  "new",
 			StartTimestamp: 1638186211,
 			Importance:     ViewModelImportance(7),