v2.11 updates

Amended README with context and background while cleaning up historical items.

README.md

@@ -1,3 +1,22 @@
+## Introduction ##
+Over the years I've been using Zabbix as both personal and business solution for monitoring. One of the missing features in Zabbix itself was the ability to have graphs generated and associated to monitoring messages as well as an easy way to jump back into Zabbix when searching for monitoring information for specific events, problems or to have a direct link to the associated Zabbix item or host.
+
+This initiated the development of mailGraph v1 in Zabbix 5.4 delivering an elementary solution for sending HTML enriched messages from Zabbix including graphs.
+To facilitate in a very flexible way to setup and format messages including the graphs, Twig made its introduction towards mailGraph v2, the current release branch of mailGraph.
+
+The below message is just an example of what MailGraph is capable of. The template engine in Twig allows for a fully customized message creation to your needs! It is also possible to add more Zabbix fields as any field is passed to Twig when accessible in Zabbix through the macro mechanism. Example: "{ITEM.ID}".
+
+Example message:
+[![](images/Example-mail-message-v122.png?raw=true)](images/Example-mail-message-v122.png)
+
+mailGraph is capable of adding several series of graphs into a single message delivering a unique experience when and how groups of graph images per the requested periods of time are added.
+Currently mailGraph supports hosts, (one or more related) items and screens (applicable to Zabbix 5.4 only).
+
+More information can be found in the Wiki.
+
+## Installation ##
+Please refer to the Wiki how to get mailGraph installed and configured on your system.
+
 ## mailGraph v2.11 release ##
 _(2023/07/01)_
 
@@ -23,7 +42,7 @@ Changes are in effect immediately, no need to restart any services.
 ## mailGraph v2.10 release ##
 _(2023/06/30)_
 
-_This version has been verified with Zabbix 5.4, 6.0 LTS and 6.4._
+_This version has been verified with Zabbix 5.4, 6.0 LTS and 6.4, PHP 7.4 and 8.2 and recent versions of libraries used via composer._
 
 Minor updates to the mailGraph code
 - When not defining zabbix_api_user and zabbix_api_pwd in the configuration file the zbx_user and zbx_user_pwd wll be used
@@ -44,22 +63,8 @@ _(2023/06/29)_
 Zabbix 6.4.x verification is in progress. Required intermediate release to fix one major issue (Zabbix login parameters deprecation) and some minor coding updates.
 Expect to continue with automatic configuration within the next 2 months.
 
-## Zabbix 6.2.x testing ##
-_(2022/10/10)_
-
-Testing completed. No immediate issues found.
-
-_(2022/08/22)_
-
-Zabbix 6.2.x testing is in progress. Once completed the next effort will be to deliver on automatic configuration detection and automatic updates.
-
-## IMPORTANT NOTE ##
+## IMPORTANT NOTE for users of mailGraph and Zabbix versions under 5.4 ##
 As a result of a major functional change in Zabbix 5.4 (Screens no longer exist and are all moved into Dashboards) the mailGraph.screen macro no longer functions under Zabbix 5.4+. A code rewrite is in progress to deal with detecting the Zabbix version and to pick dashboard.get instead of screen.get as a source list for the graphs that should be included in the mail message.
 
 **v1.x is no longer supported; please upgrade to the current v2 release**
 **Please use the Wiki for information on how to install, configure and use MailGraph in Zabbix**
-
-## Example message
-The below message is just an example of what MailGraph is capable of. The template engine ("Twig") allows for a fully customized message creation to your needs! It is also possible to add more Zabbix fields. If you need additional fields just raise an issue ticket and ask and I'll see what I can do.
-
-[![](images/Example-mail-message-v122.png?raw=true)](images/Example-mail-message-v122.png)

mailGraph.xml

@@ -1,198 +1,215 @@
-zabbix_export:
-  version: '5.4'
-  date: '2023-07-01T10:54:39Z'
-  media_types:
-    -
-      name: MailGraph
-      type: WEBHOOK
-      parameters:
-        -
-          name: baseURL
-          value: 'https://myzabbix.example.com/'
-        -
-          name: duration
-          value: '{EVENT.DURATION}'
-        -
-          name: eventId
-          value: '{EVENT.ID}'
-        -
-          name: graphHeight
-          value: '120'
-        -
-          name: graphWidth
-          value: '300'
-        -
-          name: HTTPProxy
-          value: ''
-        -
-          name: infoTest
-          value: Test
-        -
-          name: itemId
-          value: '{ITEM.ID}'
-        -
-          name: periods
-          value: '10m,4h,1d,7d'
-        -
-          name: periods_headers
-          value: 'Last 10 minutes,Last 4 hours,Last day,Last 7 days'
-        -
-          name: recipient
-          value: '{ALERT.SENDTO}'
-        -
-          name: showLegend
-          value: '0'
-        -
-          name: subject
-          value: '{{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}'
-        -
-          name: URL
-          value: 'https://myzabbix.example.com/mailGraph.php'
-      script: |
-        // mailGraph v2.11
-        try {
-            // Pickup parameters
-            params = JSON.parse(value),
-                req = new HttpRequest(),
-                fields = {},
-                resp = '',
-                result = { tags: {} };
-        
-            // Set HTTP proxy if required
-            if (typeof params.HTTPProxy === 'string' && params.HTTPProxy.trim() !== '') {
-                req.setProxy(params.HTTPProxy);
-                fields.HTTPProxy = params.HTTPProxy;
-            }
-        
-            // Declare output type
-            req.addHeader('Content-Type: application/json');
-        
-            // Must have fields
-            fields.itemId = params.itemId * 1;
-            fields.eventId = params.eventId * 1;
-            fields.recipient = params.recipient;
-            fields.baseURL = params.baseURL;
-            fields.duration = params.duration * 1;
-        
-            if (isNaN(fields.eventId)) {
-              throw '[MailGraph Webhook] Invalid event ID? Integer required (use actual event ID from Zabbix!)';
-            }
-        
-            if (isNaN(fields.duration)) {
-              throw '[MailGraph Webhook] Invalid duration? Integer required (set to zero if unknown)!';
-            }
-        
-            if (fields.recipient.charAt(0) == '{') {
-              throw '[MailGraph Webhook] Please define recipient for the test message!';
-            }
-        
-            // Optional fields
-            if (typeof params.graphWidth === 'string') { fields.graphWidth = params.graphWidth; }
-            if (typeof params.graphHeight === 'string') { fields.graphHeight = params.graphHeight; }
-            if (typeof params.subject === 'string') { fields.subject = params.subject; }
-            if (typeof params.showLegend === 'string') { fields.showLegend = params.showLegend; }
-            if (typeof params.periods === 'string') { fields.periods = params.periods; }
-            if (typeof params.periods_headers === 'string') { fields.periods_headers = params.periods_headers; }
-            if (typeof params.debug === 'string') { fields.debug = params.debug; }
-        
-            // Add generic fields
-            Object.keys(params).forEach(function(key) {
-                if (key.substring(0, 4) == 'info') {
-                    fields[key] = params[key];
-                }
-            });
-        
-            // Post information to the processing script
-            Zabbix.Log(4, '[MailGraph Webhook] Sending request: ' + params.URL + '?' + JSON.stringify(fields));
-            var resp = req.post(params.URL,JSON.stringify(fields));
-            Zabbix.Log(4, '[Mailgraph Webhook] Received response:' + resp);
-        
-            // If blank the email address is likely incorrect
-            if (resp==null) {
-              throw '[MailGraph Webhook] No data received from mailGraph! Likely the email processing failed? Check mailGraph logging';
-            }
-        
-            // If there was an error, report it and stop
-            if (req.getStatus() != 200) { throw JSON.parse(resp).errors[0]; }
-        
-            // If no datas returned, report it and stop
-            if (resp.charAt(0) == "!") {
-              throw '[MailGraph Webhook] No data received from mailGraph! Likely the event ID provided does not exist? Check mailGraph logging';
-            }
-        
-            // We expect the message id back from the processing script
-            msg = JSON.parse(resp);
-        
-            result.tags.__message_id = msg.messageId;
-            Zabbix.Log(4, '[MailGraph Webhook] Message sent with identification "' + msg.messageId + '"');
-        
-            // Pass the result back to Zabbix
-            return JSON.stringify(result);
-        }
-        catch (error)
-        {
-            // In case something went wrong in the processing, pass the error back to Zabbix
-            Zabbix.Log(127, 'MailGraph notification failed: '+error);
-            throw 'MailGraph notification failed : '+error;
-        }
-      process_tags: 'YES'
-      description: |
-        The "URL" must point to the location of the processing script. If a proxy is required, define "HTTPProxy" for the proxy address.
-        
-        Customization:
-        - "graphWidth" and "graphWidth" can be defined for the image size
-        - "showLegend" can be defined to show or hide the legend of the graph
-        - "subject" can be defined for a customized subject for the mail message
-        - "periods" and "periods_headers" can be defined for displaying multiple periods of the same graph, or
-        - "period" and "period_header" can be defined to display a single graph
-        
-        The html.template and plain.template files can be adjusted (TWIG format).
-        
-        More details are available at https://github.com/moudsen/mailGraph
-      message_templates:
-        -
-          event_source: TRIGGERS
-          operation_mode: PROBLEM
-          subject: 'Problem: {EVENT.NAME}'
-          message: |
-            Problem started at {EVENT.TIME} on {EVENT.DATE}
-            Problem name: {EVENT.NAME}
-            Host: {HOST.NAME}
-            Severity: {EVENT.SEVERITY}
-            Operational data: {EVENT.OPDATA}
-            Original problem ID: {EVENT.ID}
-            {TRIGGER.URL}
-            
-            eventId: {EVENT.ID}
-            TriggerId: {TRIGGER.ID}
-            itemId: {ITEM.ID]
-        -
-          event_source: TRIGGERS
-          operation_mode: RECOVERY
-          subject: 'Resolved in {EVENT.DURATION}: {EVENT.RECOVERY.NAME}'
-          message: |
-            Problem has been resolved at {EVENT.RECOVERY.TIME} on {EVENT.RECOVERY.DATE}
-            Problem name: {EVENT.RECOVERY.NAME}
-            Problem duration: {EVENT.DURATION}
-            Host: {HOST.NAME}
-            Severity: {EVENT.SEVERITY}
-            Original problem ID: {EVENT.ID}
-            {TRIGGER.URL}
-            
-            eventId: {EVENT.ID}
-            TriggerId: {TRIGGER.ID}
-            itemId: {ITEM.ID]
-        -
-          event_source: TRIGGERS
-          operation_mode: UPDATE
-          subject: 'Updated problem in {EVENT.AGE}: {EVENT.NAME}'
-          message: |
-            {USER.FULLNAME} {EVENT.UPDATE.ACTION} problem at {EVENT.UPDATE.DATE} {EVENT.UPDATE.TIME}.
-            {EVENT.UPDATE.MESSAGE}
-            
-            Current problem status is {EVENT.STATUS}, age is {EVENT.AGE}, acknowledged: {EVENT.ACK.STATUS}.
-            
-            eventId: {EVENT.ID}
-            TriggerId: {TRIGGER.ID}
-            itemId: {ITEM.ID]
+<?xml version="1.0" encoding="UTF-8"?>
+<zabbix_export>
+    <version>5.4</version>
+    <date>2023-07-02T10:34:30Z</date>
+    <media_types>
+        <media_type>
+            <name>MailGraph</name>
+            <type>WEBHOOK</type>
+            <parameters>
+                <parameter>
+                    <name>baseURL</name>
+                    <value>https://myzabbix.example.com/</value>
+                </parameter>
+                <parameter>
+                    <name>duration</name>
+                    <value>{EVENT.DURATION}</value>
+                </parameter>
+                <parameter>
+                    <name>eventId</name>
+                    <value>{EVENT.ID}</value>
+                </parameter>
+                <parameter>
+                    <name>graphHeight</name>
+                    <value>120</value>
+                </parameter>
+                <parameter>
+                    <name>graphWidth</name>
+                    <value>300</value>
+                </parameter>
+                <parameter>
+                    <name>HTTPProxy</name>
+                    <value/>
+                </parameter>
+                <parameter>
+                    <name>infoTest</name>
+                    <value>Test</value>
+                </parameter>
+                <parameter>
+                    <name>itemId</name>
+                    <value>{ITEM.ID}</value>
+                </parameter>
+                <parameter>
+                    <name>periods</name>
+                    <value>10m,4h,1d,7d</value>
+                </parameter>
+                <parameter>
+                    <name>periods_headers</name>
+                    <value>Last 10 minutes,Last 4 hours,Last day,Last 7 days</value>
+                </parameter>
+                <parameter>
+                    <name>recipient</name>
+                    <value>{ALERT.SENDTO}</value>
+                </parameter>
+                <parameter>
+                    <name>showLegend</name>
+                    <value>0</value>
+                </parameter>
+                <parameter>
+                    <name>subject</name>
+                    <value>{{ HOST_NAME|raw }}: ({{ EVENT_SEVERITY }}) {{ EVENT_NAME|raw }}</value>
+                </parameter>
+                <parameter>
+                    <name>URL</name>
+                    <value>https://myzabbix.example.com/mailGraph.php</value>
+                </parameter>
+            </parameters>
+            <script>// mailGraph v2.11
+try {
+    // Pickup parameters
+    params = JSON.parse(value),
+        req = new HttpRequest(),
+        fields = {},
+        resp = '',
+        result = { tags: {} };
 
+    // Set HTTP proxy if required
+    if (typeof params.HTTPProxy === 'string' &amp;&amp; params.HTTPProxy.trim() !== '') {
+        req.setProxy(params.HTTPProxy);
+        fields.HTTPProxy = params.HTTPProxy;
+    }
+
+    // Declare output type
+    req.addHeader('Content-Type: application/json');
+
+    // Must have fields
+    fields.itemId = params.itemId * 1;
+    fields.eventId = params.eventId * 1;
+    fields.recipient = params.recipient;
+    fields.baseURL = params.baseURL;
+    fields.duration = params.duration * 1;
+
+    if (isNaN(fields.eventId)) {
+      throw '[MailGraph Webhook] Invalid event ID? Integer required (use actual event ID from Zabbix!)';
+    }
+
+    if (isNaN(fields.duration)) {
+      throw '[MailGraph Webhook] Invalid duration? Integer required (set to zero if unknown)!';
+    }
+
+    if (fields.recipient.charAt(0) == '{') {
+      throw '[MailGraph Webhook] Please define recipient for the test message!';
+    }
+
+    // Optional fields
+    if (typeof params.graphWidth === 'string') { fields.graphWidth = params.graphWidth; }
+    if (typeof params.graphHeight === 'string') { fields.graphHeight = params.graphHeight; }
+    if (typeof params.subject === 'string') { fields.subject = params.subject; }
+    if (typeof params.showLegend === 'string') { fields.showLegend = params.showLegend; }
+    if (typeof params.periods === 'string') { fields.periods = params.periods; }
+    if (typeof params.periods_headers === 'string') { fields.periods_headers = params.periods_headers; }
+    if (typeof params.debug === 'string') { fields.debug = params.debug; }
+
+    // Add generic fields
+    Object.keys(params).forEach(function(key) {
+        if (key.substring(0, 4) == 'info') {
+            fields[key] = params[key];
+        }
+    });
+
+    // Post information to the processing script
+    Zabbix.Log(4, '[MailGraph Webhook] Sending request: ' + params.URL + '?' + JSON.stringify(fields));
+    var resp = req.post(params.URL,JSON.stringify(fields));
+    Zabbix.Log(4, '[Mailgraph Webhook] Received response:' + resp);
+
+    // If blank the email address is likely incorrect
+    if (resp==null) {
+      throw '[MailGraph Webhook] No data received from mailGraph! Likely the email processing failed? Check mailGraph logging';
+    }
+
+    // If there was an error, report it and stop
+    if (req.getStatus() != 200) { throw JSON.parse(resp).errors[0]; }
+
+    // If no datas returned, report it and stop
+    if (resp.charAt(0) == &quot;!&quot;) {
+      throw '[MailGraph Webhook] No data received from mailGraph! Likely the event ID provided does not exist? Check mailGraph logging';
+    }
+
+    // We expect the message id back from the processing script
+    msg = JSON.parse(resp);
+
+    result.tags.__message_id = msg.messageId;
+    Zabbix.Log(4, '[MailGraph Webhook] Message sent with identification &quot;' + msg.messageId + '&quot;');
+
+    // Pass the result back to Zabbix
+    return JSON.stringify(result);
+}
+catch (error)
+{
+    // In case something went wrong in the processing, pass the error back to Zabbix
+    Zabbix.Log(127, 'MailGraph notification failed: '+error);
+    throw 'MailGraph notification failed : '+error;
+}</script>
+            <process_tags>YES</process_tags>
+            <description>The &quot;URL&quot; must point to the location of the processing script. If a proxy is required, define &quot;HTTPProxy&quot; for the proxy address.
+
+Customization:
+- &quot;graphWidth&quot; and &quot;graphWidth&quot; can be defined for the image size
+- &quot;showLegend&quot; can be defined to show or hide the legend of the graph
+- &quot;subject&quot; can be defined for a customized subject for the mail message
+- &quot;periods&quot; and &quot;periods_headers&quot; can be defined for displaying multiple periods of the same graph, or
+- &quot;period&quot; and &quot;period_header&quot; can be defined to display a single graph
+
+The html.template and plain.template files can be adjusted (TWIG format).
+
+More details are available at https://github.com/moudsen/mailGraph</description>
+            <message_templates>
+                <message_template>
+                    <event_source>TRIGGERS</event_source>
+                    <operation_mode>PROBLEM</operation_mode>
+                    <subject>Problem: {EVENT.NAME}</subject>
+                    <message>Problem started at {EVENT.TIME} on {EVENT.DATE}
+Problem name: {EVENT.NAME}
+Host: {HOST.NAME}
+Severity: {EVENT.SEVERITY}
+Operational data: {EVENT.OPDATA}
+Original problem ID: {EVENT.ID}
+{TRIGGER.URL}
+
+eventId: {EVENT.ID}
+TriggerId: {TRIGGER.ID}
+itemId: {ITEM.ID]</message>
+                </message_template>
+                <message_template>
+                    <event_source>TRIGGERS</event_source>
+                    <operation_mode>RECOVERY</operation_mode>
+                    <subject>Resolved in {EVENT.DURATION}: {EVENT.RECOVERY.NAME}</subject>
+                    <message>Problem has been resolved at {EVENT.RECOVERY.TIME} on {EVENT.RECOVERY.DATE}
+Problem name: {EVENT.RECOVERY.NAME}
+Problem duration: {EVENT.DURATION}
+Host: {HOST.NAME}
+Severity: {EVENT.SEVERITY}
+Original problem ID: {EVENT.ID}
+{TRIGGER.URL}
+
+eventId: {EVENT.ID}
+TriggerId: {TRIGGER.ID}
+itemId: {ITEM.ID]</message>
+                </message_template>
+                <message_template>
+                    <event_source>TRIGGERS</event_source>
+                    <operation_mode>UPDATE</operation_mode>
+                    <subject>Updated problem in {EVENT.AGE}: {EVENT.NAME}</subject>
+                    <message>{USER.FULLNAME} {EVENT.UPDATE.ACTION} problem at {EVENT.UPDATE.DATE} {EVENT.UPDATE.TIME}.
+{EVENT.UPDATE.MESSAGE}
+
+Current problem status is {EVENT.STATUS}, age is {EVENT.AGE}, acknowledged: {EVENT.ACK.STATUS}.
+
+eventId: {EVENT.ID}
+TriggerId: {TRIGGER.ID}
+itemId: {ITEM.ID]</message>
+                </message_template>
+            </message_templates>
+        </media_type>
+    </media_types>
+</zabbix_export>