Start Event - Receive Message



After a process has been published, a new process can be started by receiving a message by using the Receive Message trigger within a Start Event.

See Also: Ways to Start a Process From a Process

Adding a Receive Message trigger to a Start Event

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

Setup Tab

Appian supports three different message event types: Process to Process, External to Process, and Email.

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.

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


Creating a New Expression

  • Click New Expression.


A new row is displayed. Click the Expression Editor button. The Expression Editor opens. Create an expression that filters the event. All expressions that are created as a rule should always evaluate to true or false.

Creating expressions to determine the conditions under which an event executes can cause a loss in application performance. Therefore, we strongly recommend creating conditions instead of expressions when configuring Event Conditions.

See: Messaging Best Practices

Importing Custom Properties

All mappings that have been configured using events, in process models to which you have at least "editor" level access, can be reused.

To import mappings from a previously-configured event

  1. Click Import Custom Properties. The Message Properties dialog is displayed.
  2. Select a Process Model. The events configured within that Process Model are displayed.
  3. Select an event. The mappings created for that event are imported.

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.

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

Select To obtain the ...
Origin ProcessID system assigned process id for the process from which the message was received
Origin ProcessModelID system assigned process model id for the process model from which the message was received
UserName initiator of the process from which the message was sent
Body message entered in the text area within the Configure Send Message Event dialog box.

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

Select To obtain the ...
Origin IP IP address of the machine from which the message was received
UserName username of the user who sent the JMS message

Email

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

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.

Select To obtain the ...
From name of the email account and email address from which the message was received.TIP: To capture the output of this property to a process variable, the striphtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') parses the HTML. This value can then be stored into a text process variable.
FromEmail email address from which the message was received.
FromName name of the sender.
Subject the subject of the email.
Recipients

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

  • To capture the output of this property to a process variable, the striphtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') parses the HTML. This value can then be stored into a text process variable.
RecipientsEmails email addresses of all users to whom the message was sent.
RecipientsNames names of all users to whom the message was sent.
To name and the email address to which the message was sent.TIP: To capture the output of this property to a process variable, the striphtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') parses the HTML. This value can then be stored in a text process variable.
ToEmails all of the email addresses to which the message was sent.
ToNames names of the email accounts to which the message was sent.
Cc name and email address of all users who were sent a carbon copy (Cc) of the message. TIP: To capture the output of this property to a process variable, the striphtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') parses the HTML. This value can then be stored in a text process variable.
CcEmails email addresses of all users who were sent a carbon copy (i.e., Cc) of the message.
CcNames names of all users who were sent a carbon copy (i.e., Cc) of the message.
Bcc

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

  • To capture the output of this property to a process variable, the striphtml() function should be used to parse the HTML. For example, striphtml('msg!properties'.'From') parses the HTML. This value can then be stored in a text process variable.
BccEmails email addresses of all users who were sent a blind carbon copy (i.e., Bcc) of the message.
BccNames names of all users who were sent a blind carbon copy (i.e., Bcc) of the message.
Attachments all attachments sent with the email. All attachments, by default, are uploaded to a user specified folder within Appian Collaboration. Therefore, selecting this property returns a list of document id's for all attachments sent with the email.
Importance priority level configured for the email.
Key value of the first key value pair listed within the email.
AttachmentErrors any error messages while attempting to store attachments from the email message
BodyContentType entire body of the email.

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.
Selecting means ...
= equals to
<> not equal to
< less than
> greater than
<= less than or equal to
>= greater than or equal to
  • In the third list box:
    • Select the process variable you wish to use for comparison.— or —
    • 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.

Importing Mappings from Previously Configured Message Events

  1. Click Import Custom Properties. The "Message Properties" dialog box is displayed.
  2. Select a Process Model. The send or receive message events configured within the Process Model appear.
  3. Select an event. The mappings from the selected event are imported.

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

With email messages, key-value pairs are treated as custom properties. To obtain the value of a key specified in the message, the name of the key should be included in the definition of a mapping. For example, if [CaseId=222100] is sent as an email message, you can capture CaseId in a receive message event by creating a mapping with the following definition:

'msg!properties'.'CaseId'

To capture the entire body of the email, you can use msg!body as the definition of the mapping. Similarly, you can also capture all information entered within the text area of a Send Message Event using the msg!body definition.

All attachments sent via email are stored in a folder within Appian. This folder can be specified through the Process Model Properties dialog box for the underlying process model. Email attachments can be then captured by defining the following mapping: 'msg!properties'.'Attachments'. This mapping returns an array of document IDs, one for each attachment in the email.

In the case of 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 or queue, has a property called my property, it can be obtained by creating a new mapping with the following definition:

'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 data type of the process variable. 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 (deprecated)
  • is appended to
  • is stored as

When the process variable used has a Number or Decimal data type, all of the options shown above are available. Otherwise, is appended to and is stored as are the only operators.

In the third drop-down menu, specify a process variable to store the content. Either select an existing process variable, or select New to create a new process variable.

Receive Message events that are configured on a Start Event only listen for messages once the process model has been published. When messages target an active receive message event, it only executes when all conditions are met. If not, the message is lost.

Changing message types after configuring a Start Event with a Receive Message Event clears all rules and output expressions for the Start Event.

When designing process models, configure Receive Message events before Send Message events. Send Message events require you to specify a message destination.

FEEDBACK