Specify the email account from which the email listener pulls emails, the number of times the email listener checks the inbox for messages, and which email service rules to use for routing.
- In the navigation pane of Dev Studio, click Records.
- Expand the Integration-Resources category, and then click Email Listener.
- Click Create.
- In the Short description field, enter a short description of the listener.
- 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.
- Click Create and open.
- 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.
- In the Startup option field, choose from the following
- To run the listener on all nodes, and 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, select Host based startup. If you select this
- 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.
Note: You can control when the email listener starts by using the initServices/initEmail dynamic system setting. When this setting is set to true, you can start and stop specific listeners on specific nodes from Admin Studio.
- Owning ruleset – Pega-Engine
- Purpose – initServices/initEmail
- Value – true (default)
You can also change the initServices/initEmail setting in the
- 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.
Note: For best performance, configure one email listener to monitor an email account. Configuring multiple listeners to monitor the same inbox can cause throttling.
- In the Listener properties section, in the Service
information subsection, in the Service package field,
configure the service parameters:
The listeners based on this data instance only process messages that identify this package; they ignore other messages.
- 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.
- In the Service class field, enter the service class:
The listeners process messages that identify this name (in addition to the package name) only.
- 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).
- In the Service method (text/XML only) field, identify the
- 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.
- In the Folder name field, enter the name of the email folder
that the listener monitors, typically,
- 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.
- 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.
- 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 one second.
Note: For all protocols except for POP3, the system continues to pull unread messages until the maximum number of messages that you specified in step 15 have been read, or until there are no more unread messages left in the folder.
- In the Concurrent threads field, identify the number of threads
per server node that this listener requestor creates on startup.
Note: For POP3 protocols, increasing the number of threads to more than one does not improve throughput.
- In the Message format field, select one of the following:
If you choose SOAP, the system processes incoming messages using Service SOAP rules. Otherwise, it uses Service Email rules. For more information, see Creating a Service Email rule.
- 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 of 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
- For IMAP and Microsoft Graph protocol messages only, activate keeping messages that are received by the listener on the server by selecting Keep messages on server (Not applicable for POP3).
- 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).
- If your service package requires authentication, in the Requestor
login section, enter the authentication information:
- 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.
- In the Password field, enter the password for the operator ID.
- 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.
- 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
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.By default, your workstation receives all messages for all processes running on the server.
- In the Remote host field, enter the name of your workstation.
- 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.
- Click Save.