Configuring Custom Email Senders

The Send Email Smart Service in the process modeler can be used to send email messages. This topic describes how to configure the email address listed in the From field.

Setting Up Outgoing Email

Setting the Prefix and Domain for Emails from Processes and Process Models

Adding a Custom From Address

Custom From Address Examples

See also: Send Email Smart Service

Setting Up Outgoing Email

The outgoing mail server address can be configured by following the documentation for Mail Server Setup. If no outgoing email server is configured, no emails are sent.

See also: Mail Server Setup

Setting the Prefix and Domain for Emails from Processes and Process Models

The domain and the prefix of the email address used when the From field is set to Process or Process Model can be configured by using the following properties in custom.properties:

1
2
3
resources.appian.process.email-expressions.email.domain=your-appian-instance.com
resources.appian.process.email-expressions.email.prefix.process=process
resources.appian.process.email-expressions.email.prefix.processmodel=processmodel

email.domain - Refers to the domain part of the email address (the part after the @).

email.prefix.process - Refers to the prefix prepended to the ID of the process from which the email is sent.

email.prefix.processmodel - Refers to the prefix prepended to the ID of the process model from which the email is sent.

See also: Custom Configurations

Adding a Custom From Address

In the Send Email Smart Service, there are four predefined senders to select on the From dropdown: Process, Process Model, Process Initiator, and Process Designer.

Senders are listed in <APPIAN_HOME>/deployment/web.war/WEB-INF/conf/process/email-address-config-custom.xml. Any custom settings must be stored in a new custom XML file (such as email-address-config-custom.xml) residing in the same directory or in a new directory within <APPIAN_HOME>/ear/suite.ear/web.war/WEB-INF/conf/.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<?xml version="1.0" encoding="UTF-8"?>
<emailConfig>
  <addresses>
    <address name="process"> <!-- This name is a key which needs to be specified in the collection to which it belongs --> 
      <expression>=getProcessEmail(pp!id)</expression> <!-- Either emailAddress or expression -->
    </address>
    <address name="processModel">
      <expression>=getProcessModelEmail(pm!id)</expression>
    </address>
    <address name="processInitiator" sender="#site">
      <expression>=toemailaddress(user(pp!initiator,"email"))</expression>
    </address>
    <address name="processDesigner" sender="#site">
      <expression>=toemailaddress(user(pp!designer,"email"))</expression>
    </address>
  </addresses>
  <collections>
    <collection name="from">
      <items>
        <item>process</item>
        <item>processModel</item>
        <item>processInitiator</item>
        <item>processDesigner</item>
      </items>
    </collection>
    <collection name="send-errors-to">
      <items>
        <item>process</item>
        <item>processModel</item>
      </items>
    </collection>
  </collections>
</emailConfig>

See also: Custom Configurations

The following table describes the elements used in this XML configuration file.

Name Description
emailConfig Configuration settings for email addresses
addresses Email addresses
address A single address
  • the name attribute identifies the address so that it can be referenced in a collection or as the sender for another address
  • the optional sender attribute indicates which address will be used for the Sender and Return-Path headers in the email that is sent. If not provided, there will be no Sender header and the Return-Path will be set to the same value as the email address. The special value #site indicates that the site-wide email address configured in conf.mailhandler.ntf_sndr_addr will be used as the Sender and Return-Path headers. The address in the Return-Path header is used by email systems to return bounced emails when the destiation address does not accept the email.
expression An expression that yields an email address, such as =getProcessEmail(pp!id)
emailAddress A literal email address that can be specified instead of an expression (as described above).
collections An element that contains a number of email address <collection> sub-elements.
collection Collection of addresses for a particular purpose, such as the email sender displayed on the from list of email addresses in the Send Email smart service. name="from"
items An element that contains a number of <items> within a particular collection.
item An address to be included in the collection, referenced by the name attribute.

Note: In the default configuration, bounced emails sent from processInitiator and processDesigner will be returned to the site-wide email address. Bounced emails sent from an address with no sender attribute will be returned to that address.

Custom From Address Examples

Literal Email Address

The following example describes how to add an additional sender to the From dropdown on the Setup tab of the Send Email Smart Service.

We assume here that the custom email address you want to add is john.doe@xyz.com. Also, you want the new sender to appear as John Doe on the From dropdown when configuring the smart service and have the same email display name in the From header of the email that is sent. To comply with the recommendations of the Sender Policy Framework when sending email on behalf of a user, set the sender attribute to an address that does not represent a user of the system. The Sender and Return-Path email headers will be set to the address referenced in the sender attribute, and bounced emails will be returned to that address.

See also: Sender Policy Framework: Best Practices/Webgenerated

To configure this, perform the following steps:

  1. Create a new file named email-address-config-custom.xml that lists new <address> subelements within the <addresses> element as shown below.
    • We recommend that you select a custom suffix for the filename that is meaningful in some manner to other developers, such as the name of your current development project.
  2. Add an <item> tag in the from collection for the new address that should appear in the From dropdown. Do not add the new "admin" address to the from collection. It is only used as the value for the sender attribute for johnDoe. Your custom configuration file should appear as follows:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    
     <?xml version="1.0" encoding="UTF-8"?>
       <emailConfig>
         <addresses>
           <address name="admin">
             <emailAddress>site-admin@xyz.com</emailAddress>
           </address>
           <address name="johnDoe" sender="admin">
             <emailAddress>john.doe@xyz.com</emailAddress>
           </address>
         </addresses>
         <collections>
           <collection name="from">
             <items>
               <item>johnDoe</item>
               <item>process</item>
               <item>processModel</item>
               <item>processInitiator</item>
               <item>processDesigner</item>
             </items>
           </collection>
         </collections>
       </emailConfig>
    
  3. In the above snippet, johnDoe is also the key for the value to be displayed on the From dropdown.
  4. Translate this key into your instance's supported languages in new resource files.
    • The language resource files must be named according to the filename you assign to your customized email-address-config.xml file.
    • For example, if your custom XML file is named email-address-config-custom.xml then you must list the key and its translated value in resource files named email-address-config-custom_xx_YY.properties, where xx_YY stands for the locale code (such as en_US for US English).
    • Only list key=translation value pairs for your new custom sender properties in these new resource files. The following snippet shows the key-value pair to be added in the file:

      1
      2
      
        address.johnDoe.displayName = John Doe
        address.johnDoe.emailDisplayName = John Doe
      
  5. Save your resource bundles in the following file location: <APPIAN_HOME>/deployment/web.war/WEB-INF/resources/text/jsp/WEB-INF/conf/process/
  6. Restart your application server for the changes to take effect.

When the application server is restarted, your new custom sender appears in the From dropdown in the Setup tab of the Send Email smart service. When you send an email using this smart service, the email display name is used.

Expression Email Address

The following sample configuration shows how to configure an expression that uses a constant as the custom email sender using a custom configuration file named email-address-config-custom.xml. This example does not use the sender attribute, so the Return-Path header will be set to the same email address as the From header and bounced emails will be returned to the email address from the expression.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?xml version="1.0" encoding="UTF-8"?>
<emailConfig>
  <addresses>
    <address name="customUser">
      <expression>=toemailaddress(user(cons!CUSTOM_USER, "email"))</expression>
    </address>
  </addresses>
  <collections>
    <collection name="from">
      <items>
        <item>customUser</item>
      </items>
    </collection>
  </collections>
</emailConfig>

As in the previous example, a key-value pair must be added to the resource files for customUser.

Having made these changes, restart your application server for the changes to take effect. When the application server is restarted, your new custom sender appears in the From dropdown in the Setup tab of the Send Email smart service. When you send an email using this smart service, the email display name appears as configured in the resource file.

FEEDBACK