From ffd5c3dba8b033cfbe5be258ff9fb9ce01c85d11 Mon Sep 17 00:00:00 2001
From: Maxim Vuets <maxim.vuets@booking.com>
Date: Tue, 17 Apr 2018 18:25:48 +0200
Subject: [PATCH] docs: Document json, makeSlice, and makeMap template
 functions

Presumably as part of the PR #2135 three new global template functions
were added: json, makeSlice, and makeMap. However they are not mentioned
nor documented at http://bosun.org/definitions. This commit attempts to
fill in the gap.
---
 docs/definitions.md | 63 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/docs/definitions.md b/docs/definitions.md
index 2ecf669a1c..afe1a535c6 100644
--- a/docs/definitions.md
+++ b/docs/definitions.md
@@ -1301,6 +1301,69 @@ alert htmlFunc {
 }
 ```
 
+##### json(value) (string)
+{: .func}
+
+`json` takes a value of any type (usualy a Golang's map) and returns its JSON encoding. It uses the Golang's [`json.Marshal` function](https://golang.org/pkg/encoding/json/#Marshal). Use this function when you need to make a JSON string to communicate to an HTTP API.
+
+Example:
+
+```
+$apiToken = s3cret
+
+alert json {
+    template = json
+    crit = 1
+}
+
+template json {
+    subject = `json example`
+    body = `
+        {{- $html_link := printf "<a href=\"%v\">#%v</a>" .Incident .Id -}}
+        {{- $text := printf "Alert %v is in %v state, see %v for details" .AlertKey .CurrentStatus $html_link -}}
+        {{- makeMap "key" (V "$apiToken") "incident" .Id "description" (makeSlice .Subject $text) | json -}}
+    `
+}
+```
+
+##### makeMap(values ...) (map[string]interface{})
+{: .func}
+
+`makeMap` takes a flat list of key-value pairs and turns them into a Golang's map. Keys (odd arguments) must be strings, values (even arguments) can be of any type. This function is useful only in a combination with other functions that help generating JSON, because a template cannot render Golang's map directly. See the [`json` function](definitions#jsonmapstringinterface-string) for a more advanced example.
+
+Example:
+
+```
+alert makeMap {
+    template = makeMap
+    crit = 1
+}
+
+template makeMap {
+    subject = `makeMap example`
+    body = `{{ makeMap "incident" .Id "description" .Subject | json }}`
+}
+```
+
+##### makeSlice(values ...) ([]interface{})
+{: .func}
+
+`makeSlice` creates a Golang's slice out a list of given arguments. This function is useful only in a combination with other functions that help generating JSON, because a template cannot render Golang's slice directly. See the [`json` function](definitions#jsonmapstringinterface-string) for a more advanced example.
+
+Example:
+
+```
+alert makeSlice {
+    template = makeSlice
+    crit = 1
+}
+
+template makeSlice {
+    subject = `makeSlice example`
+    body = `{{ makeSlice .Id .Subject | json }}`
+}
+```
+
 ##### notNil(value) (bool)
 {: .func}