Creating and Configuring email listener

 Use email listeners to provide the Pega Platform with the necessary information to route incoming email messages to an email service rule (Rule-Service-Email rule type). Email listeners identify the listener, the email account name, the name of the mail folder to monitor, the message format of the incoming messages, the email service rule to which to route messages, and so on.

Before you begin: Create the email account instance and email service rules.

When an email listener routes a message with file attachments, the listener creates the pyAttachmentPage page (of class Data-ServiceMessage) and puts the files on that page by using the pyAttachNames and pyAttachValues properties. When you configure inbound email, you set up a service activity that is generated to extract files from pyAttachmentPage and attach them to the work item as work item attachments.

The Data-Admin-Connect-EmailListener class contains email listener data instances. They are part of the Integration-Resources category.

  1. In the navigation panel of Dev Studio, click Records.
  2. Expand the Integration-Resources category, and then click Email Listener.
  3. Click Create.
  4. In the Short description field, enter a short description of the listener.
  5. In the Listener name field, specify a name for this listener.

The name is arbitrary and is only used to distinguish Email Listener instances from one another. Begin the name with a letter, and use only letters, numbers, the ampersand character, and hyphens.

  1. Click Create and open.

 Configuring email listener routing

Use the Properties tab to specify how to retrieve email messages and which email service rules to use for routing.

Note: If you make changes to an existing listener, stop and restart the service for the changes to take effect.

  1. On the Properties tab, in the Listener nodes section, configure the startup option for the listener:
    • To stop the listener from being started automatically in Pega Platform or manually in Admin Studio, select Block startup.
    • To start the listener automatically in Pega Platform and manually in Admin Studio, clear Block startup.
  2. In the Startup option field, choose from the following options:
    • To run the listener on all nodes, all servers in a cluster, select Run on all nodes.
    • To start the listener only on specified nodes, select Node based startup and in the Node ID field, enter the node ID of the server host node or nodes where this listener runs. When a Pega Platform server starts, it activates the listener on the current node if the current node matches any node in the list (and if other requirements are met). If you specify a node, the current node must match a name in the list to activate the listener. If you do not specify a node, the listener is not activated on any node.
    • To start the listener on a specified number of nodes on specific servers within the cluster, selectHost based startup. If you select this option:
      • In the Host name field, enter the network location name of the host server on which the listener starts.
      • In the Node count field, enter the number of nodes on each host server that start the listener.
    • To start the listener of specified node types, select NodeClassification based startup.
      • If you select this option, the Node Type field appears. Click the Plus icon to add another node type to the listener, then press the Down arrow key to select a node type from the list.
    • Click Reset startup to delete tracking data from the Log-Connect-AssignedNodes.
  3. In the Email Account section, enter the name of the Email Account rule that the listener references for incoming and outgoing email.

If you do not enter an account, the rule cannot be validated when you save your configuration. You can create the rule as needed for this action.

  1. In the Listener properties section, in the Service information subsection, in the Service package field, configure the service parameters:
    • For email messages, enter the service package name (first key part) of the Service Email rule.
    • For SOAP messages, select the Customer Package Name (first key part) of the Service SOAP rules process arriving email messages.

The listeners based on this data instance only process messages that identify this package; they ignore other messages.

  1. In the Service class field, enter the service class:
    • For email messages, enter the service class name (second key part) of the Service Email rule.
    • For SOAP messages, identify the second key part of the Service SOAP rules that process arriving email messages (Customer Class Name).

The listeners process messages that identify this name (in addition to the package name) only.

  1. In the Service method (text/XML only) field, identify the service method:
    • For text or XML email messages, identify the service method key part of a Rule-Service-Email rule.
    • For SOAP messages, leave blank. For SOAP messages, the third key part to the service rule is determined in the incoming message, by the first child of the SOAP body element.
  2. In the Folder name field, enter the name of the email folder that the listener monitors, typically, INBOX.
  3. In the Latency period field, enter the duration of this listener's rest period in seconds.

After the amount of time that you specify, the listener checks the email folder for messages. It processes all messages and then rests for this amount of time before waking up to check the inbox for messages again.

  1. In the Maximum number of messages field, enter the maximum number of messages this listener processes at run time before pausing for a rest period.

The minimum is one message.

  1. In the Maximum processing time field, enter the maximum duration in seconds for which this listener can process messages before the system forces a rest period.

The minimum is 1 second.

  1. In the Concurrent threads field, identify the number of threads per server node that this listener requestor creates on startup.
  2. In the Message format field, select one of the following:
    • Text
    • XML
    • SOAP

If you choose SOAP, the system processes incoming messages using Service SOAP rules. Otherwise, it uses Service Email rules. For more information, see Service Email rules.

  1. For incoming email messages that have more than one addressee in the To field, specify an email address to use as the From party in the Send email as field.

When an incoming email message has only one addressee in the email To field, that same value is used as the From party if the service rule that processes the messages to generate a response.

The value in this field overrides the value that you entered in the Send email as field in the email server data instance. This entry must be a valid email address based on your email host server settings. This field supports the Global Resource Settings syntax (=PageName.PropertyName). The default property name for this field is pyReplyAsEmail.

  1. For IMAP protocol messages only, activate keeping messages that are received by the listener on the server by selecting Keep messages on server (IMAP).
  2. Optional: To forward any incoming email messages that fail as an attachment to an administrator's email address, select Forward unprocessed messages.

If this field is selected, in the Forwarding email address for unprocessed emails field, enter the email address to which you want to forward the incoming email messages that fail. This field supports the Global Resource Settings syntax (=PageName.PropertyName).

  1. If your service package requires authentication, in the Requestor login section, enter the authentication information:

a.     In the Requestor user ID field, press the Down arrow key, and then select the operator ID that the email service rule is to use when processing the email message.

The operator ID instance for this user ID determines rulesets lists, organization, security, work queues, and so on.

b.     In the Password field, enter the password for the operator ID.

  1. If you want to view only those log messages that relate to the service rule that this listener listens for, in the Diagnostics section, enter the following information:

 .       In the Remote host field, enter the name of your workstation.

a.     In the Port field, enter the TCP/IP port number on which the log4j package on your computer listens.

By default, this port is 8887.

  1. The optional Remote Logging feature streams the contents of the Pega log file to the LogFactor5 application that is installed on your workstation. Use the Admin Studio Advanced logger settings to add your workstation as an active logger. For more information, see Debugging listeners by using remote logging.
  2. By default, your workstation receives all messages for all processes running on the server.
  3. Click Save.

 Configuring email listener processing

Specify how to process email messages at run time. When an email listener routes a message with file attachments (either as attachments or as images embedded into the body of the message), the listener creates a pyAttachmentPage (of class Data-ServiceMessage) and puts the files on that page.

  1. On the Process tab, in the Read Criteria section, define the following criteria:

a.     In the Maximum Email Size (KB) field, enter a maximum size, in KB, of an email message.

If you specify a value, the listener does not attempt to process email messages that are larger than this value. A value that you enter in this field overrides the value in the configuration setting prconfig/services/emailMaxSize/default. For more information, see Dynamic system settings.

b.     Specify that the listener processes email messages that are DSN messages by selecting Process delivery status notifications (DSNs).

When you clear this check box, the listener does not invoke the email service for messages with DSNs. For more information, see the Pega Community article Creating an email service that responds to AutoReply and Delivery Status Notification messages.

  1. In the Data options section, specify how to manage email attachments:
    • If you do not want the listener to process email attachments or to put them on the pyAttachmentPage page, select the No attachments check box.
    • If you want inbound email with inline images to render correctly when the email is processed as HTML, select Embed data for inline images into HTML.

By enabling this option, both base64-encodes the image as embedded HTML content, and does not attach inline images to the generated HTML message.

    • If you want the listener to save the original email, complete with any attachments or embedded images, as an attachment, select Save original email (in EML format). Use this option when email messages contain embedded images and users need to see them in their original context.
    • Use the Save original email (in EML format) option when email messages contain embedded images and users need to see them in their original context. In such a case, select the No attachments option so the attachments are not saved twice, both individually and as part of the original email attachments.
  1. In the Recovery section, in the Maximum number of recovery attempts field, specify the number of times that the listener attempts to recover email that is being processed during a server failure. By default, the listener attempts a recovery three times.
    • Enter a value for the number of times you want the listener to attempt a recovery.
    • If you do not want the listener to attempt a recovery, enter 0.
  2. Click Save.

Troubleshooting email listeners

Use the following guidelines to troubleshoot problems with email listeners.

Email listeners fail to start

The problem might be indicated by Authentication failed for listener or Failed to start listener messages in the log file.

  • Check the Startup option on the Properties tab, which contains the property that controls how the listener starts. If the Node based startup option is selected, ensure that the desired node is added to the list. If Host based startup is selected, ensure that the desired host is added to the list.

Pega Cloud customers should select NodeClassification based startup. Node based startup and Host based startup are not appropriate for Cloud-based startup because Pega Cloud defines the host name and node. For more information, see Configuring email listener routing.

  • If the Blocked option on the Properties tab of the listener is selected, the listener is disabled. Listeners with this setting do not start when the Pega Platform nodes start and you cannot start them from Admin Studio. For more information, see Configuring email listener routing.
  • If the service package configured for your email listener rule requires authentication, ensure that you provide a valid operator ID and password. For more information about service package authentication, see Service Package form – Completing the Context tab.
  • If you are using Microsoft SMA and your email listener does not respond to stop and restart commands, consider restarting the server.
  • Ensure that the prconfig.xml file value and the Pega-Engine prconfig/initServices/initEmail/default dynamic system setting value are set to true. This setting controls whether the Email service is initialized by default at system startup. For more information, see More about Service Email rules and Dynamic system settings.

Email listeners stop working

Email listeners take a long time to process very large attachments

  • Ensure that the email/partialfetch dynamic system setting is set to true. This setting controls whether to use the IMAP partial-fetch capability.
  • Set the email/fetchsize dynamic system setting to 102400. This setting controls the size of the fetch in bytes if the IMAP partial-fetch feature is enabled. The default is 16 KB.

For more information, see More about Service Email rules.

Email listeners process the same email repeatedly

Test connectivity of email account fails

  • Ensure that you are using the same password that you used when the email account rule was created. If the password has been changed, consider updating the password. For more information, see Creating an email account.
  • Ensure that the dynamic system settings values are correct.

The email loses its formatting after it is processed

  • Ensure that the HTML content in your email server is set to Inline - prefer text.

 

Comments

Post a Comment

Popular posts from this blog

Good to know things before attending Interviews

 Follow & Subscribe to this blog. A detailed End to End Project Explanation with each step will be posted in the 4th week of Jan 25. So be connected.   PEGA Project Implementation  steps involved are: - Requirements gathering  - Analysis - Prepare Test Case Documents - New  ( Scratch) -Existing Application ( Proposed Functionalities) - What are the Current Functionality &  What will be the Future Functionality. Prepare the Test Case Documents. Share these documents with TechLeads & BA (Business Analyst) - BA will Prepare the Requirements - BA will have complete idea about application functionality ( End users also have Functional knowledge) - BA will identify No of Requirements  ( 10), Duration ( 3 Months) , Decide the Release date. ( When the code will move to the Live Server) Methodology: Water Fall Methodology: (Present not using) - Requirements - No Deadlines ( Dead Lines can be extended) - Status Calls, but specific process to set...
Read more

Properties in Pega

Image
  Properties Ø   Data model refers to a set of rules that work together to populate the data in your application Ø   Property Definition: Is just like a variable that stores the data and gives a label to it (you will experience it when drag & drop) is an instance of Rule-Obj-Property Is created as an instance of Rule-Obj-Property & stored in rules.pr4_rule_property table in PegaRULES db Attributes of Property (like Variable ): Regularly used attributes (characteristics): à ID : Name of the Property ( Case sensitive ) – nothing but the Column name in db tables à Property modes (11): defines the structure of Property The property Modes are broadly categorized into 3 , these in turn categorized into 11 ·          Main modes are 3 : 1.       Value ( Single value , Value list & Value group) 2.       Page ( Single page , Page...
Read more

Learning Pega for Beginners

 This content is a simple way to learn and get your hands on pega tool. And as a beginners face lot of confusion to understand the pega tool and it's rules. My content is aimed to build the confidence in beginners to work on pega tool. So having lot of video dumps from different trainers is a useless effort. So it's a best practice if you stick with only one trainer if you are beginner.  And I'm pretty sure my content will help the pega aspirants to gain knowledge on subject in a very simple way and quick. And I will try my best to post the contents regularly. 
Read more