Using Integration Controls

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Email Control

Note: The Email control is available in BEA Workshop for WebLogic Platform only if you are licensed to use WebLogic Integration.

The Email control enables WebLogic Integration business processes to send e-mail to a specific destination. To receive e-mail, you must use the Email Event Generator. Use the WebLogic Integration Administration Console to create and manage event generators. To learn about creating and managing event generators, see Event Generators in Managing WebLogic Integration Solutions at the following URL:

http://download.oracle.com/docs/cd/E13214_01/wli/docs92/adminhelp/evntgen.html

For information on how to add control instances to business processes, see Using Controls in Business Processes.

 


Topics Included in This Section

Overview: Email Control

Provides an overview of the Email control.

Configuring an Email Control

Describes how to configure an existing Email control.

Creating a New Email Control

Describes how to create and configure an Email control.

Sample Email Messages

Provides sample e-mail messages with different formats.

Overview: Email Control

The Email control enables BEA Workshop for WebLogic Platform web services and business processes to send e-mail to a specific destination. The body of the e-mail message can be text (plain, HTML, or XML) or can be an XML object. The control is customizable, allowing you to specify e-mail transmission properties in an annotation or to use dynamic properties passed as an XML variable.

The Email control is flexible, allowing you to send a variety of content types and various combinations of body and attachments. For examples of e-mail messages that can be sent using the Email control, see Sample Email Messages.

Related Topics

EmailControl Interface

Email Control Annotations

Configuring an Email Control

When you add an Email control to your business process, you can use an existing Email control extension file (.java) or create a new one. Depending on the data type of the message body you select, the .java file includes one of the following sendEmail utility methods. (Note the different body types in the two methods.) You can specify the values for the fields as class annotations in the .java file.

Message Body with Data Type Text
/**
* @EmailControl.send to="{to}"
* cc="{cc}"
* bcc="{bcc}"
* subject="{subject}"
* body="{body}"
* attachments="{attachments}"
* content-type="text/plain"
*/
void sendEmail(String to, String cc, String bcc, String subject,
String body, String attachments);
Message Body with Data Type XML Object
/**
* @EmailControl.send to="{to}"
* cc="{cc}"
* bcc="{bcc}"
* subject="{subject}"
* body="{body}"
* attachments="{attachments}"
* content-type="text/xml"
*/
void sendEmail(String to, String cc, String bcc, String subject,
XmlObject body, String attachments);

Customizing an Email Control

Depending on the needs of your application, you can customize the base control. When extending the base control, you can add a method that specifies e-mail transmission properties in the annotation. The customized method does not require the user to supply as many parameters.

/*
* A custom Email control.
* @EmailControl
* smtp-address = "smtp.myorg.com:25"
* from-address = "joe.user@myorg.com"
* from-name = "Joe User"
* reply-to-address = "reply@myorg.com"
* reply-to-name = "Customer Service"
* header-encoding=""
* username=""
* password=""
*/
public interface MyEmailControl extends EmailControl,com.bea.control.ControlExtension
{
/**
* @EmailControl.send to="{to}"
* subject="Thanks for your order"
* body="{body}"
* attachments="/weblogic/samples/order.txt"
*
*/
public void sendOrderConfirmation(String to,
String body);
}

Using Dynamic Properties for an Email Control

You can override class-level annotations for an Email control by using dynamic properties. To use dynamic properties, pass an XML variable that conforms to the control's dynamic-property schema to the control's setProperties() method. You can retrieve the current property settings using the getProperties() method.

The setProperties() method accepts an EmailControlPropertiesDocument parameter. The EmailControlPropertiesDocument type is an XML Beans class that is generated out of the corresponding schema element defined in DynamicProperties.xsd. The DynamicProperties.xsd file is located in the system folder of New Process Applications or in the system folder of the Schemas project.

The following is an example of an XML variable used to set dynamic properties:

<EmailControlProperties>
<smtp-address>myorg.mymailserver.com:25</smtp-address>
<from-name>Joe User</from-name>
<from-address>joe.user@myorg.com</from-address>
<reply-to-address>reply@myorg.com</reply-to-address>
<reply-to-name>Joe User</reply-to-name>
</EmailControlProperties>

Creating a New Email Control

This topic describes how to create a new Email control.

To learn about Email controls, see Email Control.

To learn about WebLogic Workshop controls, see Using Controls in Business Processes.

To create a new Email control:

  1. In the Package Explorer pane, double-click the business process (Process.java file) to which you want to add the Email control. The business process is displayed in the Design View.
  2. Click on the Data Palette and from the drop-down list choose Integration Controls to display the list of controls used for integrating applications.
Note: If the Data Palette view is not visible in BEA Workshop for WebLogic Platform, click
WindowArrow symbolShowArrow symbolViewArrow symbolData Palette from the menu bar.
  1. Select Email.
  2. The Insert control: Email dialog box appears.

  3. In the Insert control: Email dialog box enter the following details:
    • In the Field Name, type the variable name used to access the new Email control instance from your business process. The name you enter must be a valid Java identifier.
    • In the Insertion point: from the drop-down list select the point where you want the field name to be inserted in the process file.
    • Decide whether you want to make this a control factory and select or clear the Make this a control factory that can create multiple instances at runtime check box. For more information about control factories, see Control Factories: Managing Collections of Controls.
    • Click Next.
    • The Create Control dialog-box appears.

  4. In the Create Control dialog box enter the following details:
    • In the Name field, type the class name of your new control extension file.
    • Decide whether you want to add comments as configured in the properties of the current project and select or clear the Generate comments check box.
    • Click Next.
    • The Insert control- Email dialog-box appears.

  5. In the Insert control- Email dialog box enter the following name and address parameters:
    • SMTP host—The address of the SMTP server in host:port or host form. If the port is not specified, the standard SMTP port of 25 is used.
    • From address—The originating e-mail address
    • From name—The Display name for the originating e-mail address
    • Body Type—Select the type of data contained in the message body using the body-type menu.
  6. Click Finish.

If you need to specify reply information (name and address) or SMTP authentication parameters (username and password or password alias), assign values to the following optional parameters using the Annotation pane:

Note: If the Annotation pane is not visible in BEA Workshop for WebLogic Platform, choose
WindowArrow symbolShowArrow symbolViewArrow symbolAnnotations from the menu barArrow symbol

Email Control Methods

To learn about the methods available on the Email control, see the EmailControl Interface.

Sample Email Messages

The following samples show what types of messages can be sent using the Email control.

Example 1: HTML Body, No Attachments

If the supplied String body is an HTML document, you can set the content-type annotation attribute to generate the following e-mail.

To: user@myorg.com
Subject: Thanks for your order
Content-Type: text/html

<html>
<head>
<title>Thanks for your order</title>
...

Example 2: Body with Attachments

For a message body with attachments, the Email Control generates a multipart/mixed message with the message body as the first part. Attachments are added as MIME parts with content types in accordance with their file name suffix. Table 6-1 lists commonly used file suffixes.

Table 6-1 File Suffixes
Suffix
Content-Type
.doc
application/msword
.gif
image/gif
.html
text/html
.jar
application/java-archive
.jpg
image/jpeg
.pdf
application/pdf
.txt
text/plain
.xls
application/msexcel
.xml
application/xml or text/xml
.zip
application/x-zip-compressed

Attachments with unknown extensions receive the application/octet-stream MIME type. The Email control also base64 encodes attachments which include binary data, as shown in the following example:

To: user@myorg.com
Subject: Thanks for your order
Content-Type: multipart/mixed;
boundary="------------F141E40DDE2763DF92513DD4"

------------F141E40DDE2763DF92513DD4
Content-type: text/plain; charset=us-ascii

Dear Sir,

Please see the attached diagram and brochure.

Thanks,
Customer Service

------------F141E40DDE2763DF92513DD4
Content-type: image/jpeg;
name="picture.jpg"
Content-Disposition: attachment; filename="picture.jpg"
Content-transfer-encoding: base64

/9j/4AAQSkZJRgABAgAAZABkAAD/7AARRHVja3kAAQAEAAAAPAAA/+4ADkFkb2JlA
...

------------F141E40DDE2763DF92513DD4
Content-Type: application/pdf;
name="brochure.pdf"
Content-Transfer-Encoding: base64
Content-Disposition: inline;
filename="brochure.pdf"

JVBERi0xLjIgDSXi48/TDQogDTEwIDAgb2JqDTw8DS9MZW5ndGggMTEgMCBSDS9Ga
...

------------F141E40DDE2763DF92513DD4

Example 3: No Body, One Attachment

An Email control send action with no body and one attachment does not generate an multipart/mixed message. This supports interchange scenarios that require the XML document to be in the message body.

To: inbox@myorg.com
Subject: new XML order
Content-Type: application/xml

<?xml version="1.0" ?>
<PurchaseOrder>
...

Exceptions and Errors

You can use an exception handler to catch and deal with any exceptions that are thrown by the Email control.

If one or more of the To or cc recipients is determined to be invalid by the local mail server, an exception may be thrown immediately. However, if the invalid recipients can only be detected by the destination mail server, this is out of the scope of the Email control. We recommend that the From address be a mailbox for handling messages bounced back to the sender.

If one or more of the attachment file names is not found, an exception is thrown.


  Back to Top       Previous  Next