Monitoring for POP3 Email Account Connectivity Failures

[Tyler Herman]

Overview:

Connecting to and ingesting emails from mailboxes is a great way to start transitioning unstructured work into the ServiceNow platform. Unfortunately, there are a few challenges that you might experience using this functionality so in this short, to the point article, I'd like to help you solve one of them.

The Problem:

For one of several reasons, ServiceNow may lose the ability to connect to a mailbox such as a password expiring or an account becoming disabled. Identifying in a timely manner when a connection failure occurs requires you to visit the "Email Diagnostics" page (/nav_to.do?uri=%2Femail_diagnostics.do) at least daily. If you're like me, this is an additional task you can do without.

The Solution: 

The following script can be added to a scheduled job to run at whatever frequency you would like. In short, it will loop through all of your active POP3 email accounts and proceed to execute the OOTB connection test, the same one which runs when you visit the Email Diagnostics page. Log entries are created for each test regardless of success or failure, however, connection failures will result in a 'ticket' being created. You should modify lines 34 through lines 39 to tailor record creation to your needs.

Note - This script does not cover IMAP connections since that wasn't part of my requirement.

gs.log("POP3 Email Connectivity Check Started.");
var gr = new GlideRecord("sys_email_account");
gr.addQuery("type", "pop3");
gr.addQuery("active", "true");
gr.query();
while (gr.next()) {
    var id = gr.getUniqueValue();
    var progressName = "Testing POP3 connection";
    var name = 'TestPOP3ConnectionWorker';
    var worker = new GlideScriptedProgressWorker();
    worker.setProgressName(progressName);
    worker.setName(name);
    worker.addParameter(id);
    worker.start();

    var answer = worker.getProgressID() + "," + id;
    updatePOP3ConnectionDoctor(answer, 1000, gr.name);
}
gs.log("POP3 Email Connectivity Check Complete.");

function updatePOP3ConnectionDoctor(answer, timeout, idname) {
    timeout = maxTimeout(timeout);
    var ids = answer.split(",");
    var worker_id = ids[0];
    var progressWorker = getProgressWorker(worker_id);
    if (progressWorker.state == "running" && progressWorker.state == "starting") {
        setTimeout(function() {
            updatePOP3ConnectionDoctor(answer, timeout * 1.5);
        }, timeout);
    } else {
        if (progressWorker.state_code == "success") {
            gs.log("POP3 Email Connectivity Check for Mailbox '" + idname + "'. Result : Success.");
        } else {
            var gr = new GlideRecord("ticket");
            gr.initialize();
            gr.priority = '1';
            gr.assignment_group = 'INSERT YOUR ASSIGNMENT GROUP SYSID';
            gr.short_description = 'POP3 Email Test Failure for Mailbox : "' + idname + '"';
			gr.description = 'INSERT YOUR DESCRIPTION';
            gr.insert();
            gs.log("POP3 Email Connectivity Check for Mailbox '" + idname + "'. Result : Failure. Ticket " + gr.number + " generated.");

        }
    }
}

function maxTimeout(timeout) {
    if (!timeout)
        return 1000;

    if (timeout > 60000)
        return 60000;

    return timeout;
}

function getProgressWorker(id) {
    var gr = new GlideRecord("sys_progress_worker");
    gr.addQuery("sys_id", id);
    gr.query();
    gr.next();
    return gr;
}

I hope this short article is helpful in making your instance a bit easier to manage. 

Cheers!

[Manolis Sgouros]

Hello @Tyler Herman ,

I believe you used the script include "EmailDiagnostics" as an example. I can see that in this Script Include it also has the possibility to check for SMTP with the function:

checkSMTP: function() {
    var smtp_id = this._getSMTPAccountID();
    var worker = new GlideScriptedProgressWorker();
    if (smtp_id)
      worker.addParameter(smtp_id);
    worker.setProgressName("Testing SMTP connection");
    worker.setName('TestSMTPConnectionWorker');
    worker.setBackground(true);
    worker.start();

    return worker.getProgressID() + "," + smtp_id;
  }

And for the IMAP, there is a condition inside the POP3 check function:

checkPOP3: function() {
    var id = this.getParameter("sysparm_id");
    if(!this._isValidAccountId(id)) {
      gs.log('Missing or invalid account ID', 'EmailDiagnostics');
      return;
    }
    var progressName = "Testing POP3 connection";
    var name =  'TestPOP3ConnectionWorker';
    if (this._getInboundEmailType(id) == "imap") {
      progressName = "Testing IMAP connection";
      name = "TestIMAPConnectionWorker";
    }
    var worker = new GlideScriptedProgressWorker();
    worker.setProgressName(progressName);
    worker.setName(name);
    if (id)
      worker.addParameter(id);
    worker.setBackground(true);
    worker.start();

    return worker.getProgressID() + "," + this.getParameter("sysparm_id");
  },

Is there any specific reason you are not checking the other two types? Or is just not part of the requirements for you?

PS: Thanks a lot for your detailed explanation.