Receive Message Event



In a process, a Java message or an email can be used to send information to your process flow. The Receive Message event can consume an action, or it can be configured to act within a smart service activity (to trigger an Exception Flow).

When an exception flow contains a receive message event, the event is only activated when the process flow reaches the process activity that contains the event.

  • Any other logic in an activity is skipped if a receive message event triggers the exception flow for that activity.

When a receive message event is configured as a process node on the designer canvas, the event is activated when the process flow reaches the event. The process flow only proceeds once the event has completed execution.

(Email message triggers on start nodes require that anonymous user access be enabled.)

Configuring a Receive Message Event

Right-clicking a Receive Message event on the designer canvas and selecting Message Properties from the list displays the Edit Receive Message Event dialog box.

General Tab

Through this tab you can specify a name and description for the event.

Setup Tab

Receive message events are activated as soon as a process flow reaches the corresponding event or activity.

You can configure the event to continue listening for messages until the process completes by selecting the Activate Message Event checkbox (which displays the inline explanation: Once activated, listen for messages for the life of the process).

  • When this checkbox is cleared, the event no longer listens for messages that could cause the event to execute again, once a message is received.
  • For optimal performance, keep this option cleared.
  • As an alternative to keeping the event active throughout the life of the process, you can configure Receive Message events in a sub-process.
    • Use the alternative option when your process needs to receive more than one message, but does not need to remain active at all times when the process is running.
    • An Exception flow should be used to terminate the sub-process once it no longer needs to listen for message events.
  • This checkbox option is only displayed when a receive message event is configured using a stand alone event process flow object. It is not displayed when configuring an exception or a start event trigger.

Select one of the following supported message types.

  • Process to Process
  • External to Process
  • Email

Apart from specifying a message type, you can include execution conditions. When a message is received, the event only executes when all conditions are met. If any of the conditions evaluate to false, the event does not execute. Messages received when the conditions evaluate to false are not retained.

To create a new condition, click New Condition or New Expression.


Creating a New Condition

Each message, depending on its type, has some properties that make it unique. Conditions can be created using these properties to filter messages that can be consumed by the event.

  • Creating a new condition creates a new row with three lists of options.


  • Select a message property. The message properties available for selection through the Expression Editor vary depending on the message type that is selected. The following message properties are available for selection for each message type.
  • Specify one of the following operators to evaluate the condition.

    Selecting Means …
    = equal to
    <> not equal to
    < less than
    > greater than
    <= less than or equal to
    >= greater than or equal to
  • Select a process variable to evaluate the condition, or enter a value to use for matching.

  • To delete a row, click the X button that corresponds to that row.

Creating a New Expression

  • Click New Expression.


  • A new row and field from which the expression editor can be used are displayed. Expressions that are created as a rule must evaluate to true or false.
  • Message properties are available for selection through the Expression Editor or using the following syntax:
1
    'msg!properties'.'<PROPERTY_NAME>'
  • Message properties vary depending on the message type that is selected. The following message properties are available for selection for each message type.
  • Creating expressions to determine the conditions under which an event executes can cause a loss in application performance. We recommend creating conditions instead of expressions when configuring Event Conditions.

Importing Custom Properties

If you have Editor or Administrator rights for a process model, you can import data mappings that have been configured for other events. Among other uses, this feature allows you to easily connect a Receive Message event with a Send Message event that you have configured in another process model. Or, it allows you to quickly build conditions for executing an event.

To import mappings from a previously configured event:

  1. Open the Edit Receive Message Event dialog box.
    • Right-click the event (which has already been configured to listen for emails using a Receive Message Event). Point to Triggers > Event Name. Click the name of the Receive Message Event listed. The Edit Receive Message Event dialog box is displayed. — or —
    • Double-click a Receive Message event.
  2. Decide whether to import existing event mappings to build a condition (which restricts the event from acting on every message) or to map data from a received message into process variables.
    • Click the Setup tab to import an event to be used in building a Receive Message condition. — or —
    • Click the Data tab to import an event to be reused when mapping message data to process variables.
  3. Click the Import Custom Properties button. The Message Properties dialog box is displayed.
  4. Browse to the process model that contains the event data you wish to import, and select it. The events configured within that process model appear in the browse window.
  5. Select an event from the list provided. The data mappings from the event are added as conditions on the Setup tab, or as new data mappings on the Data tab.
  6. In each new row, configure the process variables by clicking the variable list and selecting a process variable.

Notes

  • A Start Event can use a Receive Message trigger to start a process. If you add multiple active Receive Message events, it is possible for one message to launch multiple instances of a process. Avoid this problem by creating a Receive Message condition.

  • Messages sent to a process that is paused are lost and are not available for consumption when the process resumes.

  • In process-to-process messaging, we recommended configuring receive message events before send message events. Send message events require a message destination that may not exist until the process model with a receive message event is saved and published.

Data Tab

  • The content of message that is received can be stored into process variables by creating new mappings. Like the Send Message event, mappings allow you to capture all data within the message and store them in process variables, making the data accessible throughout the process model. To create a new mapping, click New Mapping. This creates a row with the following options.


  • On the first list, specify a message property that you would like to save into a process variable. The message property can either be entered directly onto the text field, or you can select the Expression… option to use the Expression Editor.
    • The message properties available for selection through the Expression Editor vary depending on the message type that is selected.
    • See message properties for additional details.
  • The information in each message can be captured by creating mappings for its properties and saving the corresponding values into process variables.
  • You can use process variables with custom data types to store received message properties.
    • Configure a process variable with the desired custom data type.
    • Build an expression that combines each desired message property into the format of the custom data type.
    • For example, given the following CDT:
      • You can save message properties from an email message into a process variable with the Email data type by using the following expression in the Value field.
        • {From:'msg!properties'.'From',Subject:'msg!properties'.'Subject',Body:msg!body}
      • If you need to use an expression function on your message properties (such as using the stripHtml function to remove tags from fields in an HTML email) map each property to its own variable and use a Script Task to combine the separate properties into a single CDT variable.
  • To view any of the above message properties, click the Data tab in the expression editor and expand Message Properties. In addition to these message properties, administrators with access to the file system are able to add additional properties that can be made available for selection.

  • Apart from the above properties, you can also retrieve custom properties from a message. To retrieve a custom property, the following syntax should be specified under the first drop-down menu:

    1
    2
    3
    
     'msg!properties'.'<PROPERTY_NAME>'
    
     <PROPERTY_NAME> - represents the name of the custom property specified in the message.
    
  • When capturing the output of a property sent using an HTML email, the stripHtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') cleans any HTML tags from the specified message property so that its value can then be stored in a text process variable.

Default Message Properties

  • You can provide a default value for all custom properties that you expect from incoming messages using the property() function.
  • This function allows you to provide a default value for a property, which is used instead if one is missing from the incoming message.
  • For example, adding the following definition for a mapping: property(msg!properties,"Name", "No Name was sent") ensures that if the custom property called Name does not arrive in the incoming message, it is assigned No Name was sent as its value.

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.

Process to Process Messages

  • When a receive message event is configured to accept Process to Process messages, any mapping created in a Send Message event is treated as a custom property.
  • For example, a mapping called CaseId can be created in a Send Message event, which is targeted at a particular process model. A receive message event that listens for this message can capture the CaseId, through a mapping with the following definition:
1
 'msg!properties'.'CaseId'

Importing Custom Properties

  • Apart from creating new mappings, you can reuse mappings that have been configured in other Send or Receive message events.
  • To import mappings from previously configured message events, click Import Custom Properties. The Message Properties dialog box is displayed, which allows you to browse through Process Model folders and models, you have the right to view.
  • Select a process model. All send or receive message events configured within the process model are displayed.
  • When one of these events is selected, all mappings from that event are imported.
  • Once an event has been selected, click OK to import all mappings from that event.

In receive message events that are configured to receive process to process messages, we recommend that you import all custom properties. This ensures that all mappings defined in a Send Message event are imported accurately.

Email Custom Properties

Appian Cloud users should review cloud considerations to properly setup incoming emails.

  • With email messages, key-value pairs are treated as custom properties.
    • To obtain the value of a key specified in a message, the name of the key should be included in the definition of a mapping.
    • For example, if the key value pair [CaseId=222100] is sent in an email message, you can capture CaseId in a receive message event by creating a mapping with the following definition:
1
'msg!properties'.'CaseId'
  • To capture the entire body of the mail, use msg!body as the definition of the mapping.
  • You can capture all information entered within the text area of a Send Message Event using the msg!body definition.

  • With messages from external applications that are being sent to Appian (External to Process), you can capture properties associated with each message by creating a mapping within a receive message event. For example, if a JMS message, posted to the Process topic, has a property called my property, it can be obtained by creating a new mapping with the following definition:
1
'msg!properties'.'myproperty'
  • Once a mapping definition has been configured through the first drop-down menu, the second drop-down menu allows you to specify an operator such that you can either perform data manipulation on the content, or you can simply store the value into a process variable. The options presented through this drop-down menu are dependent on the type of the process variable, the content is being saved into. The different options presented through this drop-down menu are:
    • is added to
    • is subtracted from
    • is multiplied by
    • is divided into
    • is the power to exponentiate
    • is appended to
    • is stored as
  • The process variable used to store this data must be either an integer or a decimal for these options to appear. If the process variable holds a different data type, is appended to, and is stored as are the only operators that are available for selection.

  • In the third drop-down menu, specify a process variable for storing the content. Through this drop-down menu you can either select a process variable, or you can select New… and create a new process variable that is used to store the content.

  • Once you have configured the Receive Message Intermediate event, click OK to save all changes.

Event Activation

  • Intermediate Receive Message events only listen for messages when they are activated. Moreover, when messages are targeted at an active receive message event, the event only executes if all conditions configured for the event are met. Otherwise, the event does not execute and the message is lost.

  • Changing message types after configuring an Intermediate Receive Message Event displays the following warning: Changing the message type will clear all rules and output expressions. Are you sure you want to do this?

FEEDBACK