added documentation

README.md

@@ -49,6 +49,7 @@ Read the documentation below for more options.
             - [reportSyslog](docs/configuration.md#reportsyslog)
             - [reportAlerta](docs/configuration.md#reportalerta)
             - [reportWebex](docs/configuration.md#reportwebex)
+            - [reportHTTP](docs/configuration.md#reporthttp)
     - [Process/Uptime monitoring](docs/process-monitors.md)
     - [Notification user groups](docs/usergroups.md)
 - [More information for developers](docs/develop.md)

config.yml.example

@@ -125,7 +125,7 @@ reports:
 #    params:
 #      host: localhost
 #      port: 514
-#      templates:
+#      templates: # See here how to write a template https://github.com/nttgin/BGPalerter/blob/master/docs/context.md
 #        default: "++BGPalerter-3-${type}: ${summary}|${earliest}|${latest}"
 #        hijack: "++BGPalerter-5-${type}: ${summary}|${prefix}|${description}|${asn}|${newprefix}|${neworigin}|${earliest}|${latest}|${peers}"
 #        newprefix: "++BGPalerter-4-${type}: ${summary}|${prefix}|${description}|${asn}|${newprefix}|${neworigin}|${earliest}|${latest}|${peers}"
@@ -145,7 +145,7 @@ reports:
 #        newprefix: informational
 #        visibility: debug
 #        path: trace
-#      resourceTemplates:
+#      resourceTemplates: # See here how to write a template https://github.com/nttgin/BGPalerter/blob/master/docs/context.md
 #        default: "${type}"
 #        hijack: "hijack::${prefix}@@${asn}"
 #        newprefix: "newprefix::${prefix}@@${asn}"
@@ -171,7 +171,7 @@ reports:
 #      - path
 #      - misconfiguration
 #    params:
-#      templates:
+#      templates: # See here how to write a template https://github.com/nttgin/BGPalerter/blob/master/docs/context.md
 #        default: '{"text": "${summary}"}'
 #      headers:
 #      isTemplateJSON: true

docs/configuration.md

@@ -342,7 +342,7 @@ Parameters for this report module:
 |environment| The Alerta environment name. If not specified, it'll use the BGPalerter environment name. |
 |key| Optional, the Alerta API key to use for authenticated requests. |
 |token| Optional value used when executing HTTP requests to the Alerta API with bearer authentication. |
-|resource_templates| A dictionary of string templates for each BGPalerter channels to generate the content of the `resource` field for the alert. If a channel doesn't have a template defined, the `default` template will be used (see `config.yml.example` for more details). |
+|resourceTemplates| A dictionary of string templates for each channels to generate the content of the `resource` field for the alert. If a channel doesn't have a template defined, the `default` template will be used (see `config.yml.example` for more details). Read [here](context.md) how to write a template.|
 |urls| A dictionary containing Alerta API URLs grouped by user group (key: group, value: API URL). |
 |urls.default| The Alerta API URL of the default user group. |
 
@@ -360,3 +360,19 @@ Parameters for this report module:
 |hooks| A dictionary containing Webex Teams WebHooks grouped by user group (key: group, value: WebHook).| 
 |hooks.default| The WebHook (URL) of the default user group.| 
 
+#### reportHTTP
+
+This report module sends alerts on a generic HTTP end-point.
+
+Parameters for this report module:
+
+|Parameter| Description| 
+|---|---|
+|hooks| A dictionary containing API URLs grouped by user group (key: group, value: URL).| 
+|hooks.default| The URL of the default user group.| 
+|templates| A dictionary containing string templates for each channels. If a channel doesn't have a template defined, the `default` template will be used (see `config.yml.example` for more details). Read [here](context.md) how to write a template. |
+|isTemplateJSON| A boolean defining if the template provided above are JSON or plain string |
+|headers| Additional headers to use in the GET request. For example for authentication.|
+|showPaths| Amount of AS_PATHs to report in the alert (0 to disable). | 
+
+

docs/context.md

@@ -0,0 +1,24 @@
+# Report context      
+
+All the report modules inherit the method `getContext` from the super class `Report`. This method returns a dictionary with some pre-computed tags useful for composing textual reports.
+Such tags are reported in the table below.
+
+| Tag | Description | 
+|---|---|
+| summary | The summary of the alert |
+| earliest | The date of the earliest event that triggered the alert (format YYYY-MM-DD hh:mm:ss)|
+| latest | The date of the last event that triggered the alert (format YYYY-MM-DD hh:mm:ss)|
+| channel | The channel where the alert is coming from |
+| type | The name of the monitor that triggered the alert |
+| prefix | The monitored prefix involved in the alert |
+| description | The description of the prefix involved in the alert |
+| asn | The monitored AS involved in the alert |
+| peers | The number of peers that were able to see the issue |
+| neworigin | The AS announcing the monitored prefix (e.g. in case of a hijack, `neworigin` will contain the hijacker, `asn` will contain the usual origin) |
+| newprefix | The prefix announced (e.g. in case of a hijack, `newprefix` will contain the more specific prefix used for the hijack, `prefix` will contain the usual prefix) |
+| bgplay | The link to BGPlay on RIPEstat |
+
+
+Usage example: `The alert involves ${prefix} in ${earliest}` will be translated in something like `The alert involves 1.2.3.4/24 in 2020-04-14 04:02:13`.
+
+> The same approach must be used to populate the templates available in config.yml. If you are writing a template for an API call, convert the JSON to string (e.g. '{"text": "${summary}"}').