Email Listener form – Completing the Properties tab

Listener nodes

• Block startup - When selected, stops the listener from being started automatically or manually.
• Startup option - Select to control how listeners start. These options are displayed when Block startup is not selected:
  • Run on all nodes – The listener is run on all nodes — all servers in a cluster.
  • Node based startup – The listener is started only on specified nodes.
  • Host based startup – The listener is started on a specified number of nodes on specific servers within the cluster.
  • NodeClassification based startup – The listener is started on the specified node types.
• Node ID - Appears when the Node based startup option is selected. In a multinode cluster, using the SmartPrompt, enter the node ID of the server host node or nodes where this listener is to run. 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 a node is specified, the current node must match a name in the list to activate the listener.
  • If a node is not specified, the listener is not activated on any node.

• Host name – Appears when the Host based startup option is selected. Enter the network location name of the host server on which the listener is to start.
• Node count – Appears when the Host based startup option is selected. Enter the number of nodes on each host server that are to start the listener.
• Node type – Appears when the NodeClassification based startup option is selected. Select a node type from the list or click the Plus icon to add another node type to the listener.
• Reset startup – Deletes tracking data from the class Log-Connect-AssignedNodes.

Email account

• Enter the name of the Email Account rule that the listener references for incoming and outgoing email. You must enter an account or the rule will not validate when you save. You can create the rule as needed for this action.

Listener properties

Service information

• Service package – 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 that are to process arriving email messages. The listeners based on this data instance only process messages that identify this package; they ignore other messages.
• 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 are to process arriving email messages (Customer Class Name). The listeners process messages that identify this name (in addition to the package name) only.
• Service method (text/XML only) – 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.
• Folder name – Enter the name of the email folder that the listener is to monitor, typically INBOX.
• Latency period – Enter the duration of this listener's rest period in seconds. After the amount of time specified, the listener checks the email folder specified for messages. It processes all messages and then rests for this amount of time before waking up to check the inbox for messages again.
• Maximum number of messages – Enter the maximum number of messages this listener processes at runtime before it pauses for a rest period. The minimum is one message.
• Maximum processing time – Enter the maximum duration in seconds for which this listener can process messages before the system forces it to start a rest period. The minimum is 1 second.
• Concurrent threads – Identify the number of threads per server node that this listener requestor creates when it starts.
• Message format – Select Text, XML, or SOAP to identify the expected format of the messages. If you choose SOAP, the system processes arriving messages using Service SOAP rules. Otherwise, it uses Service Email rules.
• Send email as – 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 generates a response. If incoming email messages may more than one addressee in the To field, specify an email address to use as the From party in this field. The value in this field overrides the value specified 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.
• Keep messages on server (IMAP) – Select to indicate that you want to keep messages received by the listener on the server, for IMAP protocol messages only.
• Forward unprocessed emails – Select to forward any failed incoming email messages as an attachment to an administrator's email address. Scenarios that may cause an incoming message to fail include:
  • The incoming message size is larger than the value set in the Maximum Email Size (KB) field of the Email Listener data instance.
  • The incoming message cannot be decrypted.
• Forwarding email address for unprocessed emails – If the previous field is selected, enter the email address to which failed incoming email messages are forwarded. This field supports the Global Resource Settings syntax (=PageName.PropertyName).

Requestor login

• Requestor user ID – If the service package requires authentication, select the Pega 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 list, organization, security, work queues, and so on.
• Password – Enter the password for the Operator ID.

Diagnostics

The optional Remote Logging feature streams the contents of the Pega log file to the LogFactor5 application installed on your workstation.

After you add your workstation as an active logger by selecting Logging and Tracing > Remote Logging from the menu in the System Management application, your workstation receives all messages for all processes running on the server. If you want to view only those log messages that are about the service rule this listener listens for, complete the fields in this section. Remember to start the LogFactor5 window on your workstation before updating this form to identify your workstation as a logger.

• Remote host – Enter the name of your workstation.
• Port – Enter the TCP/IP port number on which the log4j package on your computer listens. By default, this port is 8887.

Startup status

• Blocked – Select to disable the listener. When selected, the listener does not start when the Pega Platform starts and you cannot start it from the System Management application. When cleared, the listener starts when the Pega Platform starts and you can start it manually from the Listener Management page of the System Management application.