Email Message Type

The Receive Message Event allows you to read messages that are sent to a process model via email. These messages are retrieved by selecting the Email message type on the Setup tab of the Edit Receive Message Event dialog box.

Required Configuration

Retrieving Data from an Email Message

The email that is sent can include data that you wish to store in process variables. The Retrieve Message node and the Start Event node allow you to parse values (key-value pairs) from the email and map them to new or existing process variables. For example, to populate a process variable called CaseId from the email text, use the following syntax.

 [CaseId=222100]

To map key-value pairs from an email to a process variable:

  • In the Edit Receive Event dialog box, click the Data tab.
  • Click the New Mapping button. A new row appears in the Save Message Content list.
  • Select Expression in the Value list. The Expression Editor is displayed with the Data tab selected.
  • Click the Message Properties category on the Data tab.
  • Select the Key message property. The following text is added to the expression field.
     'msg!properties'.'Key'

    Type over the word Key to enter the name of the key that will be sent in the email. Be careful to retain the single quotes before and after the key name. Click the Validate button to check your expression. Click Save and Close.

  • Click the Process Variable list and select an existing process variable to hold the key value. — or —
  • Click the Process Variable list and select New to create a new process variable.

  • If you configure a Receive Message event (or a Start Event with a Receive Message trigger) to read values (key-value pairs) from incoming email and map them to new or existing process variables, only those emails that include value pairs in the specified format are processed by the system.
    • All other emails are read from the inbox on the mail server, but processes do not store the information from the email message. Instead, a message states that cancellation of the message will be logged in the appropriate db_*.log file.
  • HTML messages sent to Appian in an email should be converted to plain text before saving the message into a process variable. To facilitate this conversion the expression editor includes a function called stripHtml(). This function can be used to convert all email messages to plain text before they are captured in process variables. The function is not required, but is recommended in case you need to display the text.

  • When an HTML email is sent with Unicode characters, each character is replaced in the HTML with &#xxxx; where xxxx is the Unicode value (in decimal) for that character. These characters cannot be handled by the stripHtml() function. In this case, process designers should use the replace() function in the Expression Editor to replace the Unicode with appropriate characters. See the replace() function for additional details.

Default Message Properties

When receiving messages using the Receive Message trigger in a Start or Intermediate event, you are given the option of obtaining message properties that are unique to the event.

  • If you need to use message properties in a report, you must save it in a process variable.

Message properties can be captured by creating a new mapping in the Edit Receive Message Event dialog box. By default, the receive message trigger can receive three types of messages: Process to Process, External to Process, and Email.

Depending on the message type selected, the following properties are displayed in the Message Properties group.

Events_ee.gif

Process to Process

Use To obtain the ...
Origin ProcessID This property returns the system assigned process ID for the process from which the message was received.
Origin ProcessModelID This property returns the system assigned process model ID for the Process Model that generated the process from which the message was received.
UserName This property returns the initiator of the process from which the message was sent.
Body This property returns the message entered in the text area within the Configure Send Message Event dialog box.

External to Process

Use To obtain the ...
Origin IP This property returns the IP address of the machine from which the message was received.
UserName This property returns the username of the user who sent the JMS message.
'msg!properties'.'<PROPERTY_NAME>' This returns the value of the JMS property with the name given as PROPERTY_NAME. Only properties that start with numbers or letters are considered valid. Invalid properties are not available.

Email

Use To obtain the ...

From

'msg!properties'.'From'

This property returns the name of the email account and email address from which the message was received.

  • To capture the output of this property in a process variable, the stripHtml() function should be used to parse the HTML.
  • For example: striphtml("msg!properties","From") removes the HTML code so that this value can be stored in a process variable with a Text data type.

FromEmail

'msg!properties'.'FromEmail'

This property returns the email address from which the message was received.

FromName

'msg!properties'.'FromName'

This property returns the name of the sender.

Subject

'msg!properties'.'Subject'

This property returns the subject of the email.

Recipients

'msg!properties'.'Recipients'

This property returns the name and email addresses of all users to whom the message was sent.

RecipientsEmails

'msg!properties'.'RecipientsEmails'

This property returns the email addresses of all users to whom the message was sent.

RecipientsNames

'msg!properties'.'RecipientsNames'

This property returns the names of all users to whom the message was sent.

To

'msg!properties'.'To'

This property returns the name and the email address to whom the message was sent.

ToEmails

'msg!properties'.'ToEmails'

This property returns all of the email addresses to whom the message was sent.

ToNames

'msg!properties'.'ToNames'

This property returns the names of the email accounts to whom the message was sent.

Cc

'msg!properties'.'Cc'

This property returns the name and email address of all users who were sent a copy (Cc) of the message.

CcEmails

'msg!properties'.'CcEmails'

This property returns the email addresses of all users who were sent a copy (Cc) of the message.

CcNames

'msg!properties'.'CcNames'

This property returns the names of all users who were sent a copy (Cc) of the message.

Bcc

'msg!properties'.'Bcc'

This property returns the name and email address of all users who were sent a blind copy (Bcc) of the message.

BccEmails

'msg!properties'.'BccEmails'

This property returns the email addresses of all users who were sent a blind copy (Bcc) of the message.

BccNames

'msg!properties'.'BccNames'

This property returns the names of all users who were sent a blind copy (Bcc) of the message.

Attachments

'msg!properties'.'Attachments'

This property returns all attachments sent with the email. All attachments, by default, are uploaded to a user-specified folder within Document Management. Selecting this property returns a list of document IDs for all attachments sent with the email.

AttachmentErrors

'msg!properties'.'AttachmentErrors'

This property records any errors that may occur when saving the attachment from an email. The following errors may be recorded.

  • Message Attachment Not Saved Due To Message Part Of 0 Size: <filename> - when the attachment cannot be saved because it is empty
  • Message Attachment Not Saved Due To Exception: <exceptionMessage> - when the attachment cannot be saved because an error occurred

Importance

'msg!properties'.'Importance'

This property returns the priority level configured for the email.

Key

'msg!properties'.'Key'

This property returns the entire text between the first set of brackets [] in the mail subject only (not body), including any equals sign

Body

msg!body

This returns the body of the email message. If available, the message body with the content type "text/plain" will be stored in this property.

BodyContentType

'msg!properties'.'BodyContentType'

This property returns the content type of the message body available in msg!body

Bodies

'msg!properties'.'Bodies'

When a single email message includes additional bodies, these are appended to the Bodies property.

  • This property stores this data within a multiple Text data type.
  • The message type of each additional body is stored in the BodyTypes property.
  • Any attachments included in the attached message are saved in the Attachments property.
  • When Microsoft Outlook embeds a (.msg file) message within a message, this file is appended to the Bodies property and is not treated as an attachment.
    • The BodyTypes property stored for an embedded message (.msg) is typically "text/plain".

BodyTypes

'msg!properties'.'BodyTypes'

This type stores the content types of each message body stored in the 'msg!properties'.'Bodies' property.

  • The index of each content type matches the index of an associated message in the Bodies property.

Attachments

Attachments sent within an email message are stored in a folder within Document Management.

To specify the folder used to store email attachments:

  • In the process modeler, click File > Properties. The General Tab of the Process Model Properties dialog box is displayed.
  • Click the Directory link next to the Email Attachments Folder field and browse to the folder you want to designate for any emailed attachments.
FEEDBACK