Guide to Custom Service Notifications

Introduction

You can create modules to send notifications to custom services. This creates notifications to an Internet Relay Chat (IRC) server, Slack, or a related service. The custom notification consists of two Perl modules. The following steps describe how to create and configure these modules.

Important:

This feature does not function with UTF-8 byte strings that the system must decode.

Modules

The Provider module must be a subclass of the Cpanel::iContact::Provider module. You do not need knowledge of the ancestor module.

To create a custom notification, you must create the following modules:

The Schema module — This module validates your configuration and determines how to display information in the interface.
The Provider module — This module defines how you communicate with the service. It uses the settings that the Schema module provides.

The `Schema` module

Create the Schema Perl module in the following location, where MODULE_NAME represents the custom notification module name:

/var/cpanel/perl/Cpanel/iContact/Provider/Schema/MODULE_NAME.pm

After you create this module, add your custom information to the get_settings() and get_config() subroutines. If your Schema module requires external modules, store them in the relevant checkval functions.

The contents of this module should resemble the following example:

package Cpanel::iContact::Provider::Schema::Example; # Change 'Example' to your Service name
use strict;
use warnings;

# Use any modules from our installed CPAN modules here.

sub get_settings {
    return {
        'EXAMPLEAUTHTOKEN' => {
            'shadow'   => 1, # Flag for saving to /etc/wwwacct.conf.shadow or /etc/wwwacct.conf
            'type'     => 'password', # This maps to an HTML input tag's "type" attribute. Perfect for things like passwords or API bearer tokens.
            'checkval' => sub {
                # Not really much to do here, since I'm not actually aware of a good validation regex for these tokens.
                my $value = shift();
                # Do some validation here to make sure $value is either a) a sanitized version of what was input via the UI OR
                # b) a blank string, as it failed to validate.
                # NOTE: Do not establish whether the parameter is *valid* for your service (in this example). Instead, this ensures that you format things the way you want them.
                # As an example, you can input non-resolving email addresses in for the email notification field in Basic Setup, it will just fail to send when we go to actually do that.
                # Generally we expect integrators to follow this model as well. To reject an email address because it does not follow the RFC for a valid address string for example, would make sense here though.
                ...
                return $value;
         },
            'label' => 'Example Service Auth Token',
            'help' => 'Some string that would tell people how to obtain this, what it should look like, etc.',
        },
        'EXAMPLESERVICEHOST' => {
            'shadow'   => 1,
            'type'     => 'text',
            'checkval' => sub {
                my $value = shift();
                ...
                return $value;
            },
            'label' => 'Example Service API URI',
            'help' => 'Some string that would tell people how to obtain this, what it should look like, etc.',
        },
        # NOTE to 3rd party integrator - Only have one property prefixed with CONTACT, as that one will be the 'triggering' property for notifications.
        # In the logs, the TYPE of the notification will show up as CONTACT<NAME> where <NAME> is your TYPE.
            'name'     => 'Example', # Needed to tell cPanel what provider module to load over in /var/cpanel/perl/Cpanel/iContact/Provider/
            'shadow'   => 1,
            'type'  'checkval' => sub {
                my $value = shift();
                ...
                return $value;
       },
            'label' => 'Example Service user to notify',
            'help' => 'Some string that would tell people how to obtain this, what it should look like, etc.',
        }
    };
}

sub get_config {
    return {
        'default_level'    => 'All', # Maps to what you'd see in the WHM >> Contact Manager UI as the default notification level. In /var/cpanel/clevels.conf, this would be translated to '3'.
        'display_name'     => 'Example', # Maps to what your provider shows up as in the WHM >> Contact Manager UI.
=> 'Example', # Maps to what your icon is named. Currently irrelevant, as it does nothing to help your icon load, and falls back to 'display_name' above if not set.
  => ... # A long Data URI (ex. "data:image/png;base64,$my_image_base64"). Thankfully these only display at 16x16px, so you can scale down the image first.
    };
}

1;           'CONTACTEXAMPLE' => {
     => 'text',
                       'icon_name'                'icon'

The `Provider` module

Create the Provider Perl module in the following location, where MODULE_NAME represents the custom notification module name:

/var/cpanel/perl/Cpanel/iContact/Provider/MODULE_NAME.pm

After you create this module, add your custom information to the send() subroutine.