Producing dynamic email messages

You can produce an email where the SMTP server, list of recipients, subject, text, and multiple attachments are all determined at run time.

About this task

You can create a message flow that produces an email with multiple attachments. To configure an EmailOutput node to send an email with a single attachment, static subject, and static text to a static list of recipients, see Sending an email with an attachment.

The node properties that you set when sending an email can be optional, and can be overridden at run time by values that you specify in the local environment, email output header (EmailOutputHeader), or the body of the message. To use this method, previous nodes in the message flow must construct these overrides. Where a text value is not specified in the node properties for the main body of the email, the body of the message that is passed to the EmailOutput node is used.

The following examples show how to set up the recipient, sender, subject, SMTP server, and message body information in ESQL (with a Compute node) and Java™ (with a JavaCompute node).

Using a Compute node

About this task

The diagram shows a message flow that uses an MQInput node, Compute node, and EmailOutput node to produce a dynamic email message.
CREATE FUNCTION Main() RETURNS BOOLEAN
	BEGIN
		CALL CopyMessageHeaders();
		
		-- Add recipient information to the EmailOutputHeader
		SET OutputRoot.EmailOutputHeader.To = '<recipient email address>';
		SET OutputRoot.EmailOutputHeader.Cc = '<recipient email address>';
		SET OutputRoot.EmailOutputHeader.Bcc = '<recipient email address>';

		-- Add sender information to EmailOutputHeader
		SET OutputRoot.EmailOutputHeader.From = '<sender email address>';
		SET OutputRoot.EmailOutputHeader."Reply-To" = '<reply email address>';

		-- Add subject to EmailOutputHeader
		SET OutputRoot.EmailOutputHeader.Subject = 'Replaced by ESQL compute node.';

		-- Add SMTP server information to the LocalEnvironment
		SET OutputLocalEnvironment.Destination.Email.SMTPServer ='<smtp.server:port>';

		-- Create a new message body, which will be sent as the main text of the email.
		SET OutputRoot.BLOB.BLOB = CAST('This is the new text for the body of the email.' AS BLOB CCSID 1208);  		

		RETURN TRUE; 
	END;
Note: When using a BLOB parser on z/OS®, the CCSID of the message should be 500. In the previous example, the CAST would be:
SET OutputRoot.BLOB.BLOB = CAST('This is the new text for the body of the email.' AS BLOB CCSID 500);
To write white space characters (such as newline (NL), carriage return (CR), and line feed (LF ) characters) in the text string that is produced as the email body, you can add the following lines of code.
DECLARE crlf CHAR CAST(X'0D0A' AS CHAR CCSID 1208);
DECLARE myEmailBodyTxt CHAR;
SET myEmailBodyTxt [equals char] 'this is the first line' || crlf ||
    'this is the second line' || crlf ||
    'this is the third line';
SET OutputRoot.BLOB.BLOB = CAST(myEmailBodyTxt AS BLOB CCSID 1208);

Using a JavaCompute node

About this task

The diagram shows a message flow that uses an MQInput node, JavaCompute node, and EmailOutput node to produce a dynamic email message.
public void evaluate(MbMessageAssembly assembly) throws MbException {
		MbOutputTerminal out = getOutputTerminal("out");
		
		// Create a new assembly to propagate out of this node, as we want to update it
		MbMessage outMessage = new MbMessage();
		copyMessageHeaders(assembly.getMessage(), outMessage);
		MbMessage outLocalEnv = new MbMessage(assembly.getLocalEnvironment());
		MbMessage outExceptionList = new MbMessage(assembly.getExceptionList());
		MbMessageAssembly outAssembly = new MbMessageAssembly(assembly, outLocalEnv, outExceptionList, outMessage);
		MbElement localEnv = outAssembly.getLocalEnvironment().getRootElement();

		// Create the EmailOutputHeader parser. This is where we add recipient, sender and subject information.
		MbElement root = outMessage.getRootElement();
		MbElement SMTPOutput = root.createElementAsLastChild("EmailOutputHeader"); 

		// Add recipient information to EmailOutputHeader
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "To", "<recipient email address"); 		
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "Cc", "<recipient email address"); 		
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "Bcc", "<recipient email address");  		

		// Add sender information to EmailOutputHeader 		
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "From", "<sender email address>"); 		
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "Reply-To", "<reply email address>");  		

		// Add subject information to EmailOutputHeader 		
		SMTPOutput.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "Subject", "Replaced by Java compute node.");  		

		// Create Destination.Email. This is where we add SMTP server information 		
		MbElement Destination = localEnv.createElementAsLastChild(MbElement.TYPE_NAME, "Destination", null); 		
		MbElement destinationEmail = Destination.createElementAsLastChild(MbElement.TYPE_NAME, "Email", null); 		
		destinationEmail.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "SMTPServer", "<smtp.server:port>"); 		 		

		// Set last child of root (message body) 		
		MbElement BLOB = root.createElementAsLastChild(MbBLOB.PARSER_NAME);	 		
		String text = "This is the new text for the body of the email"; 		
		BLOB.createElementAsLastChild(MbElement.TYPE_NAME_VALUE, "BLOB", text.getBytes());  		
		
		outMessage.finalizeMessage(MbMessage.FINALIZE_VALIDATE); 	 		

		out.propagate(outAssembly); 	}

Using the local environment

About this task

Use the local environment to specify overrides to the SMTP server connection information and attachments.
Local environment Description
Destination.Email.SMTPServer The Server:Port of the SMTP server. Port is optional; if you do not specify it, the default value is 25.
Destination.Email.SecurityIdentity The security identity for authentication with the SMTP server, which can be the name of the userid and password pair that is defined using the mqsisetdbparms command, or it can reference an external resource that has a securityIdentity attribute that references a userid and password that are defined using the mqsisetdbparms command. In both cases, the value is appended after the string "smtp::". For example, if you use the mqsisetdbparms command to create a userid and password of smtp::myUseridPassword, the securityIdentity that is specified on the node, or indirectly in an external resource, is myUseridPassword.
Destination.Email.BodyContentType Identifies that the body of the email 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.
Destination.Email.MultiPartContentType The type of multipart, including related, mixed, and alternative. You can set any value here.
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.
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.
Destination.Email.Attachment.ContentName The name of the attachment.
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 most 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.

Using the email output header

About this task

Use the email output header to specify overrides to the SMTP server connection information and attachments. The EmailOutputHeader is a child of Root. Values that you specify in this header override equivalent properties that you set on the EmailOutput node. Use the SMTP output header to specify any of the email attributes, such as its recipients.
Location Description
Root.EmailOutputHeader.To A comma-separated list of email addresses.
Root.EmailOutputHeader.Cc A comma-separated list of email addresses.
Root.EmailOutputHeader.Bcc A comma-separated list of email addresses.
Root.EmailOutputHeader.From A comma-separated list of email addresses.
Root.EmailOutputHeader.Reply-To A comma-separated list of email addresses.
Root.EmailOutputHeader.Subject The subject of the email.
Root.EmailOutputHeader.Sender A single email address. This header is mandatory if multiple email addresses are specified in the Root.EmailOutputHeader.From field.

Any other children of the Root.EmailOutputHeader element are treated as custom headers and are also added to the outgoing email.