Alerter

Alerter

Master Branch Build Status

This is a ColdBox Module that makes receiving exception information (especially during development) pretty easy. It's handy when the application is an API, and putting full error information into the response isn't appropriate (or helpful).

Currently, the only supported alerting mechanism is email. This works well to communicate a lot of nicely formatted error information when connected to a development tool like MailDev. Perhaps in the future, other mechanisms will be implemented, such as Loggly and Papertrail.

Be alert. The world needs more lerts.

Requirements

  • Lucee 5.2+
  • ColdBox 4.3+
  • Java 8+

Installation

Install using CommandBox: box install alerter --save

Usage

MailAlerter

For a CFML engine that already has mail settings defined, just add the following to your moduleSettings in Coldbox.cfc:

alerter = {
    mail = {
        from = "[email protected]",
        to = "[email protected]",
        subject = "[app.localhost] Exception Alert"
    }
}

If you'd like to override existing mail settings (or if your CFML engine has no configured settings), specify the SMTP server information:

alerter = {
    mail = {
        from = "[email protected]",
        to = "[email protected]",
        subject = "[app.localhost] Exception Alert",
        server = {
            host = "127.0.0.1",
            port = 10025
        }
    }
}

If you'd like to use custom templates for generating the email message body, define them like so:

alerter = {
    mail = {
        from = "[email protected]",
        to = "[email protected]",
        subject = "[app.localhost] Exception Alert",
        templates = {
            default = "/MailStuff/ExceptionTemplate.cfm",
            special = "/MailStuff/ExceptionWithSpecialSauce.cfm"
        }
    }
}

Note that one of the templates must have the property name of 'default'.

Once the Alerter module is configured, get an instance of MailAlerter and use its exceptionAlert() method:

    property name="mailAlerter" inject="[email protected]";

...

    try {
        thingService.riskyCall("foo");
    } catch(any e) {
        variables.mailAlerter.exceptionAlert(e);
    }

If you have a custom template and want to pass extra information for the email, call the exceptionAlert() method like so:

        variables.mailAlerter.exceptionAlert(
            exception=e,
            template="special",
            extras={"sauce":"Szechuan Chicken McNugget Sauce"});

In your custom template, sauce will be available in the variables scope.

Tests

The package is configured such that tests can be executed within CommandBox using testbox run. The test specs expect an SMTP service at 127.0.0.1:10025. If you're using MailDev, start it for use with Alerter:

maildev --ip 127.0.0.1 --smtp 10025 --web 10080 --verbose

Mail received during the test execution will be visible using http://127.0.0.1:10080/

License

See the LICENSE file for license rights and limitations (MIT).

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Download
0.0.2 Dec 21 2018 04:03 PM Dec 21 2018 04:03 PM Joseph Lamoree (jlamoree)
0.0.1 Oct 13 2017 10:13 PM Oct 13 2017 10:13 PM Joseph Lamoree (jlamoree)

 

No collaborators yet.
     
  • Oct 13 2017 10:13 PM
  • Dec 21 2018 04:03 PM
  • 528
  • 0
  • 242