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.)

Configuration Options

This section contains tab configuration details specific to this smart service. For more information about common configurations see the Process Node Properties page.

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.

• 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 subprocess.
  • 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 subprocess 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.

1. 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.
   • External to Process Message Properties
   • Email Message Properties

2. 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

3. 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

To create 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.

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 the 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 select the Expression… option to use the Expression Editor.

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. For more information see Configure a process variable and custom data type.

To build an expression that combines each desired message property into the format of the custom data type, 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.

Process to Process

External to Process

Email

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'

Email Custom Properties

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.

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?

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 and 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.

Use Receive Message in a Start Event

A Start Event with a receive message trigger can be used to start a process. If there are multiple active receive message events listening for the same message in a process, it is possible for one message to trigger multiple events. This can be avoided by adding conditions under which an event should execute.

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

Apart from specifying a message type, you can include conditions under which the event executes. In other words, upon reception of a message, the event only executes when all specified conditions are met.

If any of the conditions evaluate to false, the event does not execute. The reception of a single message must meet all conditions for the event to execute.

See Also: Ways to Start a Process From a Process

Adding a Receive Message trigger to a Start Event

1. Right-click or double-click the Start Event on the designer canvas and select Triggers. The Configure Start Event dialog box is displayed.
2. Select the Triggers tab.
3. Click Receive Message. A new entry appears in the Start Event Triggers group box.
4. Click Configure. The Edit Receive Message Event dialog is displayed. This dialog box includes a series of tabbed property sheets.

Creating a New Start Event Condition

1. Right-click on the Start Event, select Triggers
2. Click Setup to view the Configure Start Event dialog box. To add a receive message trigger, click the corresponding icon.
3. Next, click Configure or Edit to open the Receive Message event configuration dialog box.
4. Click the Setup tab.
5. Click the New Condition button on the toolbar. A row is added to the Event Conditions list, containing three fields to configure.
6. Click the first list box. The items displayed vary according to the type of Receive Message Event selected: Process to Process, External to Process, or Email.

Process to Process Messages

In nearly all cases, it's better to use the Start Process smart service to start a process than to use process-to-process messaging. See Ways to Start a Process From a Process for more information on the advantages of the Start Process smart services over process-to-process messaging.

External to Process

Email

Email messages require that anonymous user access be enabled. Whenever a process is started using an email, the process initiator property (pp!initiator) is listed as the Guest user account.

In addition to these pre-defined conditions, you can also directly enter any property defined in an incoming message directly into the text-field. For example, if the incoming message contains a property called CaseId you can reference it as:

'msg!properties'.'CaseId'

In the second list box, select the operator you wish to use for the condition. The following options are available.

In the third list box, select the process variable you wish to use for comparison. If there are no process variables defined, type a comparison value in the field provided.

Creating a New Variable Mapping

On the Data tab, click New Mapping. A new row appears, with the following options.

In the first drop-down menu, specify a message property to save into a Process Variable (pv). The message property can either be entered directly in the text field, or select Expression… to use the Expression Editor. The message properties available for selection through the Expression Editor vary depending on the message type that is selected.

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:

'msg!properties'.'<PROPERTY_NAME>'

<PROPERTY_NAME> — represents the name of the custom property specified in the message.

You can provide a default value for all custom properties that you expect from incoming messages. This is accomplished using the property() Appian Scripting Function. This function allows you to provide a default value for a property, which is used should a property be missing from in 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 is not sent in the incoming message, it is assigned No Name was sent as its value.

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 entitled 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:

'msg!properties'.'CaseId'

Apart from creating new mappings, you can reuse mappings that have been configured in other Send or Receive message Events.

External to Process Message Type

The Receive Message Event allows you to read messages that are sent through the Java Messaging Service. These messages are retrieved by selecting the External to Process message type on the Setup tab of the Edit Receive Message Event dialog box.

Retrieving Data from an External Message

The message that is received can include data that you wish to store in process variables. The Retrieve Message node and the Start Event node allow you to retrieve properties from messages and map them to new or existing process variables.

Mapping Values from a JMS Message to a Process Variable

1. In the Edit Receive Event dialog box, click the Data tab.
2. Click the New Mapping button. A new row appears in the Save Message Content list.
3. Select Expression in the Value list. The Expression Editor is displayed.
   You can map data from the message using properties that you define yourself, or you can use the properties that Appian captures for each external message.
   

Retrieving Properties That You Have Defined in the Message

1. Click the Functions tab. Select the Scripting Functions category.
2. Select the Property() function. The Property function is displayed in the expression field.

3. Type the following text inside the brackets of the Property() function.
   Property(msg!properties,"myproperty","No property listed")
   NOTE: You do not have to use the Property() function, but it allows you to define default values that are displayed if the message is received with the expected value missing. In this case the "No property listed" value is inserted as a default, when the message is sent with a null value for "myproperty." Otherwise, if no default value is needed, simply type the following text in the Value field. 'msg!properties'.'myproperty'
   

4. Click the Validate button to check your expression. Click Save and Close.
   

Retrieving Message Properties Captured by Appian

1. Click the Message Properties category on the Data tab.
2. Select one of the following properties.
   • Select Origin IP to obtain the IP address of the machine from which the message was received.
   • Select UserName to obtain the username of the user who sent the JMS message.
   • Select Body to obtain the body of the JMS Message.
3. Click Save and Close.
   • Click the Process Variable list and select an existing process variable to contain mypropertyvalue.
     — or —
     
   • Click the Process Variable list and select New to create a new process variable.

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

• See Sending an Email Message to a Process for more information on how to configure the system to receive email.
  • When an email is sent to an Appian process, it must use the Anonymous user account.
  • Process model properties must be configured to allow processes to be started using email.

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:

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

    'msg!properties'.'Key'

6. 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.
7. Click the Process Variable list and select an existing process variable to hold the key value. — or —
   
8. Click the Process Variable list and select New to create a new process variable.

Notes

• 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.

Attachments

Attachments sent within an email message are stored within a document folder.

To specify the folder used to store email attachments:

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