Start of change
WebSphere Message Brokers
File: ac37400_
Writer: Karen Cameron

Reference topic

This build: July 31, 2007 21:20:51

EmailOutput node

Use the EmailOutput node to send e-mail messages to one or more recipients.

This topic contains the following sections:

Purpose

The EmailOutput node delivers an e-mail message from a message flow to an SMTP server. The node uses the JavaMail API to build and send the e-mail message to the SMTP server that you specify.

You can configure the EmailOutput node using the node properties in the Message Broker Toolkit, or dynamically from the LocalEnvironment and e-mail output header (EmailOutputHeader) that are associated with the message.

The EmailOutput node is contained in the Email drawer of the message flow node palette, and is represented in the workbench by the following icon:

EmailOutput node icon

Configuring the EmailOutput node

When you have put an instance of the EmailOutput node into a message flow, you can configure it. For more information, see Configuring a message flow node. To display its properties, either double-click the node, or right-click the node and click Properties. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The four levels of configuration of the EmailOutput node are described below.
  • Option 1: Configure the EmailOutput node using the node properties in the Message Broker Toolkit to send an e-mail with a statically-defined subject and text to a statically-defined list of recipients. The same e-mail is sent to the same recipients and it has no attachments. This method is useful when you want to test the EmailOutput node, or when notification alone is sufficient.
  • Option 2: This option is the same as Option 1 but with the inclusion of an attachment. This option causes the e-mail message to be constructed as a MIME message. The subject, text, and list of recipients remains static, but the content of the attachment is sought dynamically from the message that is passed to the EmailOutput node at run time. The location of the attachment in the message is defined statically.
  • Option 3: This option allows for those properties in Options 1 and 2 to be optional, and to be overridden at run time by values that are specified in the LocalEnvironment, the e-mail output header (EmailOutputHeader), or the body of the message. This option allows a dynamic e-mail message to be produced where the SMTP server, list of recipients, subject, text, and multiple attachments are all determined at run time. This option requires previous nodes in the message flow to construct these overrides. Where a text value is not specified in the node properties for the main body of the e-mail, the body of the message that is passed to the EmailOutput node is used.
  • Option 4: This option passes a MIME message to the EmailOutput node. The EmailOutput node uses the MIME parser to write the MIME message to a bit stream. This message is then passed directly to the JavaMail API, and it is sent to the list of recipients in the SMTP header. LocalEnvironment overrides are not taken into consideration when a MIME message is passed.

E-mail output header

The e-mail output header (EmailOutputHeader) is a child of root. Any values that you specify in this header override any properties that you set on the node. Use the SMTP output header specify any of the e-mail attributes, such as its recipients.
Location Description
Root.EmailOutputHeader.To A comma separated list of e-mail addresses.
Root.EmailOutputHeader.Cc A comma separated list of e-mail addresses.
Root.EmailOutputHeader.Bcc A comma separated list of e-mail addresses.
Root.EmailOutputHeader.From A comma separated list of e-mail addresses.
Root.EmailOutputHeader.Reply-To A comma separated list of e-mail addresses.
Root.EmailOutputHeader.Subject The subject of the e-mail.

LocalEnvironment

Use the LocalEnvironment to specify overrides to the SMTP server connection information and attachments.
LocalEnvironment Description
LocalEnvironment.Destination.Email.SMTPServer The Server:Port of the SMTP server. Port is optional; if you do not specify it, the default value is 25.
LocalEnvironment.Destination.Email.SecurityIdentity The security identity for authentication with the SMTP server.
LocalEnvironment.Destination.Email.BodyContentType Identifies that the body of the e-mail message contains HTML rather than plain text. You can set this property to text/plain, text/html, or text/xml; text/plain is the default value.
LocalEnvironment.Destination.Email.MultiPartContentType The type of multipart, including related, mixed, and alternative. You can set any value here.
LocalEnvironment.Destination.Email.Attachment.Content Either the actual attachment (BLOB/text), or an XPath or ESQL expression that references an element; for example, an element in the message tree or LocalEnvironment. The value of the referenced element is taken as the content of the attachment.
  • If the element is a BLOB, it is an attachment.
  • If the element is text, check to see if it can be resolved to another element in the message tree or LocalEnvironment. If it can be resolved, use that element. If it cannot be resolved, add this element as the attachment.
LocalEnvironment.Destination.Email.Attachment.ContentType The type of attachment (also known as Internet Media Type), including text/plain, text/html, and text/xml. You can set any value here.
LocalEnvironment.Destination.Email.Attachment.ContentName The name of the attachment.
LocalEnvironment.Destination.Email.Attachment.ContentEncoding The encoding of the attachment: 7bit, base64, or quoted-printable.
  • 7bit is the default value that is used for ASCII text.
  • Base64 is used for non ASCII, whether non English or binary data. This format can be difficult to read.
  • Quoted-printable is an alternative to Base64, and is appropriate when the majority of the data is ASCII with some non-ASCII parts. This format is more readable; it provides a more compact encoding because the ASCII parts are not encoded.

Broker properties

You can also configure the SMTP server, port number, and security identity as a broker external resource property. To do this, use an alias that is specified in the SMTPServer property on the EmailOutput node. The security identity references a user ID and password pair that is defined on the broker using the mqsisetdbparms command. Use the mqsicreateconfigurableservice command to create an SMTP broker external resource for the alias that is specified on the node. Then use the mqsichangeproperties command to create an SMTPServer property with the value in the form of server:port. The port value is optional; if you do not specify it, the default value is 25. You can also use the mqsichangeproperties command to create an SMTPSecurityIdentity property with a value that is the name of a security identity that can be resolved at run time to a user ID and password for authentication with the SMTP server. For example:
mqsicreateconfigurableservice MY_BROKER –c SMTP –o SMTP_MyAlias  
followed by:
 mqsichangeproperties MY_BROKER –c SMTP –o SMTP_MyAlias –n SMTPServer –v smtp.hursley.ibm.com:25 
These commands override the SMTP server and port values that are specified on any nodes that also specify an alias of SMTP_MyAlias. If the LocalEnvironment contains any overrides, they take preference over the broker external resource properties. See also the following example:
mqsichangeproperties MY_BROKER –c SMTP –o SMTP_MyAlias –n SMTPSecurityIdentity –v mySecurityIdentity  
You must also use the mqsisetdbparms command to define the security identity at the broker run time

Connecting the terminals

Connect the In terminal to the node from which outbound messages bound are routed.

Connect the Out or Failure terminal of this node to another node in this message flow to process the message further, process errors, or send the message to an additional destination.

If you connect one of these output terminals to another node in the message flow, the LocalEnvironment that is associated with the message is enhanced with the following information for each destination to which the message has been put by this node:
Location Description
WrittenDestinationEmail.smtpServer The Server:Port of the SMTP server.
WrittenDestinationEmail.messageId The ID of the e-mail sent message.

These values are written in WrittenDestination within the LocalEnvironment tree structure.

If you do not connect either terminal, the LocalEnvironment tree is unchanged.

Terminals and properties

The EmailOutput node terminals are described in the following table.

Terminal Description
In The input terminal that accepts a message for processing by the node.
Failure The output terminal to which the message is routed if a failure is detected when the message is put to the output queue.
Out The output terminal to which the message is routed if it has been successfully put to the output queue, and if further processing is required within this message flow.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined); the column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the bar file to deploy it).

The EmailOutput node Description properties are described in the following table.

Property M C Default Description
Node name No No The node type, EmailOutput The name of the node.
Short Description No No   A brief description of the node.
Long Description No No   Text that describes the purpose of the node in the message flow.

Use the EmailOutput node Basic properties are described in the following table.

Property M C Default Description
server No Yes   This property defines the SMTP server and port to which e-mails are sent from this node, and is in the format server:port; for example: my.smtp.server:25. The port value is optional, but if you do not specify a port value, the default value is 25.

You can specify an alias value for this property. If the alias exists at run time, the specified values are used. If the alias does not exist at run time, the broker assumes the value to be a valid SMTP host.

The EmailOutput node Email properties are described in the following table.

Property M C Default Description
ToAddresses No No   The main recipient or recipients of the e-mail. This property can include a single e-mail address or a comma-separated list of e-mail addresses.
CcAddresses No No   The carbon copy recipient or recipients of the e-mail. This property can include a single e-mail address or a comma-separated list of e-mail addresses.
BccAddresses No No   The blind carbon copy recipient or recipients of the e-mail. This property can include a single e-mail address or a comma-separated list of e-mail addresses.
FromAddress No No   The e-mail address of the sender of the e-mail.
Reply-ToAddress No No   The e-mail address to which recipients of the e-mail reply.
Subject No No   The subject of the e-mail.
MessageText No No   The main text of the e-mail. If you do not specify a value for the MessageText property, the text of the e-mail is the body of the message tree that is passed to the EmailOutput node.
BodyContentType No No text/plain You can use this property to force the content type for the body of the e-mail message. Valid values are:
  • None
  • text/plain
  • text/html
  • text/xml

The EmailOutput node Security properties are described in the following table.

Property M C Default Description
securityIdentity No Yes   A security identifier to retrieve a user ID and password that are configured at the broker run time.

The EmailOutput node Attachment properties are described in the following table.

Property M C Default Description
MultipartContentType No No None The type of multipart. Valid values are:
  • None
  • Alternative
  • Related
  • Mixed
AttachmentContent No No   An XPath or ESQL expression that references an element; for example, an element in the message tree, or LocalEnvironment. The content of the attachment is the value of the element that is referenced.
AttachmentContentType No No None The type of the attachment. This property is optional, even if you have specified an attachment. Valid values are:
  • None.
  • text/plain is simple text.
  • text/html is HTML.
  • text/xml is XML.
  • application/octet-stream is the default type for non-text and HTML (binary data).
AttachmentContentName No No   The name of the attachment that is seen by the recipient of the e-mail. This property is optional. If you do not specify a name, a default name is assigned.
AttachmentContentEncoding No No None The encoding of the attachment. This property is optional. If you do not specify a value, a default encoding is assigned. Valid values are:
  • None.
  • 7bit is the default value for ASCII text.
  • base64 is used for non-ASCII data, whether it is non-English or binary data.
  • quoted-printable is a more readable-alternative to base64. Use quoted-printable when the majority of the data is ASCII text with some non-ASCII parts. This option provides a more compact encoding because the ASCII parts are not encoded.

The Validation properties of the EmailOutput node are described in the following table.

Refer to Validation properties for a full description of these properties.

Property M C Default Description
Validate Yes Yes Inherit This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit.
Failure Action Yes No Exception This property controls what happens if validation fails. You can set this property only if you set Validate to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.
Include All Value Constraints Yes No Selected You cannot edit this property. If you select the check box, basic value constraint checks are included in Content and Value validation.
Fix Yes No None You cannot edit this property.
Related reference
MQInput node
Output node
Notices | Trademarks | Downloads | Library | Support | Feedback

Copyright IBM Corporation 1999, 2007Copyright IBM Corporation 1999, 2007. All Rights Reserved.
This build: July 31, 2007 21:20:52

ac37400_ This topic's URL is:
End of change