Email Listener – Usage and Configurations in Pega

This blog article will be the continuation of my previous article on email wizard.

In this blog article, we will see in detail about all the configuration points in the email listener.

What is email listener?

The email listener monitors the email account on the configured folder and routes the email message to email service rule for processing.

Now imagine I am asking you to create a new email listener to perform the above tasks. What are the questions you will ask?

1. On which account and which folder I need to monitor?
2. To which service email rule, should the email be routed to?
3. How frequent should the email listener check the email folder?
4. If the frequency interval is specified, then what should be the load – on maximum messages as well as on maximum time?
5. Do we need to do parallel processing?
6. Should I need to control the maximum email size?
7. What is the error handling for failed email messages?
8. How to handle delivery status notification messages?
9. How to process the email attachments?

Good, we got 9 questions to answer. All these questions can be answered by configuring the email listener rule form.

What are the configuration points in the email listener?

Open the already created email listener from the previous post on email wizard.

Always you can open the existing rules from the records

Records -> Integration resources -> Email listener

Click and open the email listener rule form.

The email listener rule contains 2 main tabs.

• Properties
• Process

Let’s start with the first question!

1. On which account and which folder I need to monitor?

Both the configuration stays with the property tab.

Email account

The wizard populated the specified email account.

In this field, you can specify the email account name.

Note: The email address will be configured in the email account rule form.

For more details, please visit my previous article on outbound email

Folder name

You can specify the folder name, on which the email listener monitors. It’s always INBOX.

I like this way of questioning answering so that I know when the post will be completed.

2. To which service email rule, should the email be routed to?

Service information

You can specify the unique identifiers (package name, class and method) of the corresponding service email rule.

Since this is created via the wizard, all the details are pre-populated based on the details we provided at the wizard creation time.

You can click and open the service email rule.

We will see about this in the service email blog article.

Now, let’s get back to email listener rule

I hope you noticed something in the service method field.

The label says, text / XML only!

This opens up an extra question, so what are the formats of the email message?

The configuration stays in the properties tab.

We know that most of the email clients support text format.  You can generate emails in XML as well as SOAP formats.

Some interesting articles below will explain in detail about email format

https://webhelp.episerver.com/Ektron/documentation/documentation/wwwroot/cms400/v802/webhelp/managing%20content/HTML%20Forms/Forms_send_data_XML.htm

https://www.w3.org/TR/soap12-email/

So what will be the service method when we use Service-SOAP?

You should use Service-SOAP rule instead of Service-Email rule!!

Service configurations are done. Next question

3. How frequent should the email listener check the email folder?

This again stays with the properties tab. Actually, the answers for the first 6 questions stay with the properties tab. Sneak peak.

Latency period

Specify in seconds

This is the resting time for the email listener. So the email listener first checks the mail box and complete the routing process then waits for 100 seconds before checking again. I am keeping it defaults to 100 seconds

4. If the frequency interval is specified, then what should be the load – on maximum messages as well as on maximum time?

Maximum number of messages

Again this configuration is there to reduce the load on the email listener. Say for example, you have received 500 emails all at once. So email listener will start routing all the 500 emails to the email service and then only it can go sleep for 100 seconds… now how about 1000 emails at a time?!.

This maximum number of messages will specify how many can be processed before sleep.

Maximum processing time

Same like above, but the metrics is on time instead of messages. So the email listener can start route the emails continuously for maximum 500 seconds, then it rests for latency period, 100 seconds and then go to work again.

5. Do we need to do parallel processing to improve performance?

Listener nodes

In a real production environment, you may have multiple nodes in a cluster.

In some projects, they may have some specific node for batch processing to improve performance. Some projects, they may have a single node.

You can decide all these configurations in the properties tab.

Block startup

Always keep this unselected. If selected, listener will be blocked when system restarted

Startup option – you get 4 options

Run on all nodes – you know what it means. The listener runs on all nodes in the cluster

Node-based startup – Here you can specify to start the listener only on specific nodes, using node id.

You can specify multiple node id in the array

Host-based startup – Similar to node based startup, we can start the listener only on specific nodes, using hostnames.

Here you can specify hostnames. There may be some situation, where nodes can share the same hostname, you can specify the count

Node classification

What is node classification?

This is a new concept introduced in Pega 7.3. You can classify nodes based on its usage.

Imagine, your application has some long running batch. If the batch or agent runs on the same node, where the end users log in and work, then it MAY have some impact on the performance. Batches can eat up the system resources. Already there are some ways to make the batch or agent to run on specific nodes.

With the node classification, you can distinguish the nodes based on its usage.

More details in a separate blog article –

So with the node classification, you can map the agents and listeners to run on the specific node type

You have a button to reset startup. You can use it, when you want to change the assigned nodes.

You got one more option to improve the performance via concurrent threads.

If the load is high you can use multithreading option.  Multithreading we will see in some other post. For now make it 1.

Next question

6) Should I need to control the maximum email size?

For example, Some email can contain large attachments and may need to discard those emails.

Pega provides a configuration point in the process tab under read criteria.

Maximum email size (KB)

You can specify the maximum email size in KB. Once the limit is crossed, the email will be unprocessed.

7. What is the error handling for failed email messages?

Exactly the above scenario, can end up in unprocessed error handling. In such a situation, we can forward the mail to some maintenance mail address for debugging purpose.

Forward unprocessed messages

You can specify an email address to forward the unprocessed emails.

Remember the mail stays in the email account. Noooo.. not always.

We will touch one more configuration point.

Keep messages on server (IMAP)

This will be default enabled and applicable only for IMAP protocol

Lets’ talk about the email receiving protocols – IMAP and POP3.

What is the difference between IMAP & POP3 protocol?

Say you have synced your mail ID s in both mobile and laptop.

POP3

– When you access the Gmail to check the emails from the laptop, the mail gets downloaded in the laptop and gets deleted from the email server. So when you try syncing from mobile, you will not find the mail.

– It uses 110 (unsecured), 995 (secured) port numbers

IMAP

– When you access the Gmail to check the emails from the laptop, the mail still resides in the mail server and will not be deleted.

– It use 143 (unsecured) , 993 (secured) port numbers

Always try to use IMAP protocol to receive the email.

So when using IMAP protocol and if you disable the Keep messages on server option, then the mail will be deleted once processed.

I will show it in the demo at the end !

8. How to handle delivery status notification messages?

Delivery status notification messages

These are the email messages that get auto-triggered from the email server regarding the delivery status. Say for example, if one left the company or the email address is invalid or mailbox is full, then the email server sends a delivery status message as failed.

DSN messages can be identified with some header values. Now the question is should we process the DSN messages or discard it.

I will keep it uncheck to not process the DSN messages

Why do we need to process DSN messages?

In some case, where the email address is wrong, we need to fall back and take the correct action. So this can be decided based on business requirement.

I will plan a separate post only on DSN messages soon.

So one last question, before the tutorial

9) How to process the email attachments?

In the process tab, you have 3 configuration points under Data options.

Note: File listeners usually saves the attachment details under pyAttachmentPage.  

We will see more in a service email post.

No attachments 

If yes, then the file listener just discards the attachments and pyAttachmentPage will be empty

Embed data for inline images into HTML

Sometimes, the email message can contain inline images between the text messages. Use this option to render the message rightly into HTML stream

Save original email (in EML format)

This will save the original email in EML format and can be attached with the case. EML means email message stored as a file.

I will select the EML option to show it on the demo

We have configured all the answers for the 9 questions.

Only one configuration is left out.

Under properties tab – Send email as

– This field is used, when you want to send a reply message for the incoming mail.

– By default, if the incoming message contains a single To address, then the reply mail will be from the email address which received the mail. But if the incoming message gets addressed to more than 1 To address, then you can configure here the generic email address from which the reply will be sent out.

– This field accepts dynamic referencing and can be populated dynamically

So we successfully configured the file listener rule.

Let’s do some testing

How to test file listener rule?

Step 1: Make sure the listener is up and running

Designer studio -> system -> operations -> Listener management

Note: Don’t use SMA.  SMA application went to permanent sleep with pega 8.1 release

Status should be sleeping/running

Step 2: check on how many service cases were created

Because I ****** up S-141 cases were already created!!

Step 3: Send out a mail to pegaknowledgesharing@gmail.com

I am just sending with subject MyKnowPega check.

Let’s see the magic

Step 4: Check on the pegaknowledgesharing@gmail.com account

Step 5: Wait for the next run and check the cases.

Created just now.

Step 6: Open the case and check the attachments.

You see the original email is attached with the case.

Step 7: Let’ go back and check the email account mailbox

You can see the mail is read and still stays.

Step 8: Verify the reply email you received from the customer the email account.

COOL 🙂

We will not check it in the tutorial of deleting the email messages from the server after processing.

Just uncheck the below option.

Save the file listener and restart the listener.

Note: whenever changes were made to the file listener, restart the listener for the changes to be effective.