Get Email activity

The Get Email activity is a starter activity. When an orchestration that starts with an Get Email activity is deployed to the Integration Appliance, the Integration Appliance polls the POP3 server for email message or messages for the specified account at the specified interval.

Note: The Get Email activity requires the POP3 server to support the TOP and UIDL commands. While these are optional in the POP3 protocol, most servers will support these.

The polled POP3 server and email account is defined in the email endpoint associated with the Get Email activity.

During run time, the Get Email activity polls a POP3 server for incoming email messages of a particular email account, as shown in the following diagram.

Figure 1.

If any email messages are found the following action occurs for each email message: The regular expression defined for the Subject field is checked against the subject of the incoming mail message and the regular expression defined for the From field is checked against the sender email account of the incoming mail message. If both regular expressions match, an orchestration job is created to process the email, and the mail is marked for deletion on POP3 Server. When the process is completed, the email is deleted from the POP3 server. For more information about regular expression matching, see the Configuring the activity procedure.
Note: Two Get Email activities should not poll from the same POP3 server at the same time using the same email account even if the regular expressions specified in the Configure task of the activity are different. If two Get Email activities are attempting to get email using the same email account, when the first Get Email activity process the email from the POP3 server and removes the email from the server, the second Get Email activity keeps retrying to retrieve the email from the POP3 server and the following exception may be thrown:
Protocol exception: com.jscape.inet.pop.PopException: 
Error in TOP 671 0: -ERR The requested message is no 
longer available; it may have been deleted.

Accessing an email message attachment

To access the attachment of a incoming email message, you must add a Read MIME activity in the orchestration after the Get Email activity as shown in the preceding figure. In addition, you must map the two output parameters of the Get Email activity to variables in the orchestration and then map those variables to the input parameters of the Read MIME activity. During run time, the Read MIME activity reads the MIME Header and the body of the message and then breaks up the attachments contained in the body of the message and places the result into the parts XML output parameter. For more information, see Read MIME Activity.

Adding a Get Email activity to the orchestration

  1. Create or open an orchestration. A graphical representation of the orchestration is displayed.
  2. Select the Activities tab and expand the Email folder.
  3. Drag the Get Email activity onto the orchestration.
  4. Select the activity. The Checklist is displayed.

Creating, selecting, or editing an email endpoint

  1. Click Pick Endpoint task from the Checklist and choose from one of the following actions:
    • Select an existing endpoint:
      1. Select Browse. The Project Explorer is displayed.
      2. Select an existing endpoint and click OK. Complete theConfiguring the activity steps.
    • Select an existing endpoint and edit the endpoint:
      1. Select Browse. The Project Explorer is displayed.
      2. Select an existing endpoint and click OK.
      3. Click Edit. The Edit Endpoint pane is displayed.
    • Create a new endpoint: Select New. The Create Endpoint pane is displayed.
  2. Create or edit an email endpoint. For more information, see Creating or editing an email endpoint.

Configuring the activity

  1. Select the Configure task from the Checklist. The Configure pane is displayed.
  2. Configure all the fields in this pane as described in the following table. In this task, you specify the regular expressions used to match against the Subject and From fields of polled email messages. A regular expression must be specified for both of these fields, even if the regular expression is equal to *, which means that all strings match. In order for a incoming mail to be processed, both the Subject and the From strings of the mail must match their respective regular expressions. In each of the regular expression fields, the following wildcards are supported:
    • * (asterisk) - for zero or more characters
    • ? (question mark) - for zero or one character
    Table 1.
    Field Description
    Subject matches Enter a regular expression that matches the subjects of email messages that start an orchestration job to process the email message. In the regular expression,  you can specify a combination of characters and wildcards.
    From matches   Enter a regular expression defines the sender email address of the email messages that start an orchestration job to process the email message. In the regular expression,  you can specify a combination of characters and wildcards.
    The following table shows some example regular expressions and the result of matching the regular expressions to sample text.
    Table 2.
    Regular Expression Sample Text Result
    *test* test matches
    *test* ttttesttt matches
    test test matches
    test ttttesttt does not match, has to exactly match the regular expression string: test
    test est does not match, has to exactly match the regular expression string: test
    ?est test matches
    ?est best matches
    ?est est matches

Specifying the delivery rules

  1. Select the Delivery Rules task from the Checklist. The Delivery Rules pane is displayed.
  2. Specify the time interval to poll the POP3 server for new email messages:
    1. Select a time unit from the menu: seconds, minutes, hours, or days.
    2. Specify the amount of time using one of the following input options:
      • By clicking in the Poll for changes every field and entering a new value.
      • Using the up and down arrows.
For more information, see Polling interval behavior.

Specifying the retry options

  1. Select the Retry task from the Checklist. The Retry pane is displayed.
  2. Configure the retry options for connecting to a POP3 server. The following table defines the retry options for a connection to an POP3 server:
    Table 3.
    Field Description
    Retry  
    1) Wait __ second(s) between each retry. Specifies the number of seconds that the Integration Appliance waits before trying to establish a connection to the POP3 server.
    2) Try to connect __ times before failing. Specifies the retry count - the maximum number of times the Integration Appliance attempts to establish a connection to the POP3 server before issuing an error.

    If an orchestration that starts with a Get Email activity is deployed and the Integration Appliance cannot connect to the specified POP3 server, the Integration Appliance logs the connections errors as warnings in the system log until the retry count value is reached. When the retry count is reached, the Integration Appliance logs an error in the system log, resets the connection error count to zero, and continues to attempt to establish a connection to the POP3 server.

    For example, you set the retry count to 3. The first, second, and third connection errors appear in the system log as Warnings. The Integration Appliance logs the fourth connection error as an error and resets the connection error count to zero. Therefore, the fifth connection error generates a warning in the system log. The Integration Appliance continues to attempt to establish a connection to the POP3 server.

Mapping the output of the activity

  1. Select the Map Outputs task in the Checklist. The output parameters of the activity are displayed in the From Activity pane.
  2. In this task, you map the mailheader (of type XML) and body (of type string) output parameters to variables. You must map the output parameters of the activity in order for the orchestration to be valid. See Creating a map for general instructions on mapping. The mailheader output parameter contains meta information about the email message, for example the email addresses that the message is being sent to and the MIME header of the message itself. The body output parameter contains the body of the email message and associated attachments.
    CAUTION:
    The order of the attachments and the body in the body output depend on the email client that sent the message and the type of message (plain text or HTML.).
Note: When using a non-English payload, the mailheader, mimeHeader and otherheaders need to be mapped into the orchestration in the getEmail activity, and mapped from the orchestration back into the sendMail activity.



Feedback | Notices


Timestamp icon Last updated: Wednesday, 15 June 2016


http://pic.dhe.ibm.com/infocenter/wci/v7r0m0/topic/com.ibm.wci.doc/email_get_activity.html