First see here how to make an "Action Config to run one instance of a task". This couples a log event code to an action config. When a log message with the configured event code is logged and reaches the central database, the action config is triggered. The tag in the action config has to refer to a MC_SystemAlerter task that can send emails.

Then use the info here to create a new MC_SystemAlerter task. For the new task use the tag from the action config and make it a one-off task. The xml file that needs to be uploaded contains the settings for the emails (see mcSystemAlerter.xsd schema). In here it is possible to use the tag %LOG% in the body of the email. This tag will then be replaced by the logmessage(s) that triggered sending the email. The smtp configuration has the tls attribute since 2023.02. This is required for modern SMTP servers that require TLS. Set this attribute to true to support tls.

Basic example

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<mc-system-alerter xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/mcSystemAlerter.xsd">
    <alerts>
        <emailalert>
            <recipients>
                <recipient email="Some.body@somewhere.org"/>
				<recipient email="%FEWS_MC_SYSTEM_ALERTER_RECIPIENTS%"/>
             </recipients>
            <configuration>
                 <!-- requires OS System Environment Property FEWS_MCSYSTEMALERTER_PASSWORD to be present. --> 
                <smtp tls="true" fromaddress="Some.body@somewhere.org" host="smtp.mailhost.nl" user="fewsuser" passwordEnvironmentVariableKey="FEWS_MCSYSTEMALERTER_PASSWORD"/>
            </configuration>
            <subject>
                <subjectline content="The subject line of the email to send"/>
                <substitutions/>
            </subject>
            <body value="%LOG%"/>
            <attachments/>
        </emailalert>
    </alerts>
</mc-system-alerter>

When scheduling the task, set the start time somewhere in the future, otherwise the task runs immediately. Then search the new task in "scheduled tasks" and set it to suspend. When the action config is triggered, then it copies the suspended task and runs the copy once. The example shows that it is supported to specify a variable, e.g. FEWS_MC_SYSTEM_ALERTER_RECIPIENTS. This has then to be available as an environment variable on the master controller machine. Multiple names are supported "dummy_user1@dummyhost.nl;dummy_user2@dummyhost.nl" using semi colon as a separator. NB. Settting environment variables containing a semi colon may require surrounding quotes.

Example sending emails to multiple recipients with logentries and reports

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<mc-system-alerter xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/mcSystemAlerter.xsd">
    <alerts>
        <emailalert>
            <recipients>
                <recipient email="Some.body1@somewhere.org;Some.body2@somewhere.org"/>
            </recipients>
            <configuration>
                <smtp fromaddress="fromaddress@somewhere.org" host="smtp.somewhere.org" port="25"/>
            </configuration>
            <subject>
                <subjectline content="This is my subject line DATE_TIME MC_ID"/>
                <substitutions>
                    <tag tagid="MC_ID"/>
                    <tag tagid="DATE_TIME"/>
                </substitutions>
            </subject>
            <body value="This is the message body"/>
            <attachments>
                <attachment eventcodefilter="MyEvent.Code" loglevelthreshold="LOG_ALL" maxentrycount="100" maxlogage="15" maxsize="10" sortorder="LOCAL_AVAILABLE_TIME" xsi:type="logentriesattachmentType">
                    <filename includedatestamp="true" prefix="logentries"/>
                </attachment>
                <attachment maxsize="10" xsi:type="reportsattachmentType">
                    <filename includedatestamp="true" prefix="report"/>
                    <reportcontents>
                        <latestreportsselection includeselection="true">
                            <includes/>
                        </latestreportsselection>
                        <currentreportsselection includeselection="true">
                            <excludes/>
                        </currentreportsselection>
                    </reportcontents>
                </attachment>
            </attachments>
        </emailalert>
    </alerts>
</mc-system-alerter>

The result will be that a CSV file is attached containing the relevant logentries.

taskRunId,logEntryId,creationTime,logLevel,synchLevel,logMessage,expiryTime,eventCode,moduleInstanceId,localModificationTime,eventAcknowledged,eventProcessed
MC00:000009387,32,2020-01-08T10:42:22.000+00:00,20000,5,message1,2020-01-13T10:42:22.000+00:00,MyEvent.Code,none,2020-01-08T10:42:32.000+00:00,1
MC00:000009387,20,2020-01-08T09:49:46.000+00:00,20000,5,message2,2020-01-13T09:49:46.000+00:00,MyEvent.Code,none,2020-01-08T09:49:58.000+00:00,1
MC00:000009387,1,2020-01-08T09:43:34.000+00:00,20000,5,message3,2020-01-13T09:43:34.000+00:00,MyEvent.Code,none,2020-01-08T09:43:42.000+00:00,1

Sending log messages in xlsx format

The log messages can also be sent as attachment in xlsx format.

It has been designed to work in combination with secondary validation. For instance by using a comma separated tags in a log message of the series comparison check: <logMessage>%LOCATION_ID%;%LOCATION_NAME%;%VALUE%;@attributeIdA@;@attributeIdB@</logMessage>

This can be useful to give recipients a clear overview of abnormalities occurring in the data. 

In the email alerter this can be enabled by using the log content element specifying the column separator and the xlsx format in combination with body column header elements for each column.

An example can be seen below:

Example sending log entries in xlsx format
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<mc-system-alerter xmlns="http://www.wldelft.nl/fews" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.wldelft.nl/fews http://fews.wldelft.nl/schemas/version1.0/mcSystemAlerter.xsd">
    <alerts>
        <emailalert>
            <recipients>
                <recipient email="Some.body1@somewhere.org;Some.body2@somewhere.org"/>
            </recipients>
            <configuration>
                <smtp fromaddress="fromaddress@somewhere.org" host="smtp.somewhere.org" port="25"/>
            </configuration>
            <subject>
                <subjectline content="This is my subject line DATE_TIME MC_ID"/>
                <substitutions>
                    <tag tagid="MC_ID"/>
                    <tag tagid="DATE_TIME"/>
                </substitutions>
            </subject>
            <body value="See log entries in xlsx attachment"/>
            <attachments>							
                 <attachment maxsize="10000" xsi:type="logentriesattachmentType" sortorder="LOCAL_AVAILABLE_TIME" maxentrycount="1000">
					<filename includedatestamp="true" prefix="validated_timeSeries_"/>
					<logContent columnSeparator=";" format="xlsx"/>
                    <bodyColumnHeader>Location Id</bodyColumnHeader>
                    <bodyColumnHeader>Location Name</bodyColumnHeader>
                    <bodyColumnHeader>Value</bodyColumnHeader>
                    <bodyColumnHeader>Attribute A Value</bodyColumnHeader>
                    <bodyColumnHeader>Attribute B Value</bodyColumnHeader>
				</attachment>
             </attachments>
        </emailalert>
    </alerts>
</mc-system-alerter>

NB. Note that the fromaddress field is an optional field that will fallback to InternetAddress.getLocalAddress() which is according to specification but in rare cases will fail to provide a suitable fromaddress and will cause errors in the master controler log file (where the MCSystemAlerter logs its errors). Including the correct fromaddress will resolve this matter. Also when the Master Controller DNS is not configured properly this may result into slowness in the System Alerter.

 


  • No labels

Disclaimer