|
|
| Note: | The Email control is available in BEA WorkSpace Studio 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 Using the WebLogic Integration Administration Console.
For information on how to add control instances to business processes, see Using Controls in Business Processes.
The Email control enables BEA WorkSpace Studio 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.
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.
@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);
@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);
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);
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>
This topic describes how to create a new Email control.
To learn about WorkSpace Studio controls, see Using Controls in Business Processes.
To create a new Email control:
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 WorkSpace Studio, click Window > Show View > Data Palette from the menu bar. |
The Insert control: Email dialog box appears.
host:port or host form. If the port is not specified, the standard SMTP port of 25 is used.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 Properties pane:
from-name, reply-to-name, to, bc, bcc, subject, and attachments. If no header encoding is specified, the system default encoding is used.smtp-username.smtp-username. The alias is used to look up the password in the password store. This attribute is mutually exclusive with the smtp-password attribute.| Note: | If the Properties pane is not visible in BEA WorkSpace Studio, choose Window > Show View > Properties from the menu bar  |
To learn about the methods available on the Email control, see the EmailControl Interface.
The following samples show what types of messages can be sent using the Email control.
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>
...
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 5-1 lists commonly used file suffixes.
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
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>
...
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.
|