Index Changes
This is version 52. It is not the current version, and thus it cannot be edited.
[Back to current version]   [Restore this version]

THIS DOCUMENT IS WORK IN PROGRESS


Return to Email BC Page

Using Email BC

Sending Email using Email BC (SMTP protocol)

The Email BC uses JavaMail API to send email message using the SMTP protocol. As with email clients (like Eudora, Thunderbird, Outlook Express etc), the Email BC needs some configuration to be able to send emails successfully. All the configuration for the email bc is specified in the WSDL. The netbeans binding wizard (or the WSDL wizard) can be used to create a wsdl file with most common of the configuration.

The netbeans binding wizard is available under "New File Wizard (Ctrl+N) > ESB > Binding".

The netbeans wsdl wizard is available under "New File Wizard (Ctrl+N) > XML > WSDL Document". In both cases, select the following values:

  1. Binding = Email
  2. Type = Send Email (using SMTP)

Click on Next, the SMTP Settings screen will show up.

Configuration:

The important fields/attributes in this screen are the SMTP Server and the Port, for example smtp.gmail.com and 465.
You can refer to your email client's SMTP server settings to set the values here (or ask an administrator).

In case the SMTP server requires authentication, you need to provide the User Name and Password. For secure authentication, just select the checkbox "Use SSL".

Sending Email with attachments using Email BC

The Email BC allows you to send attachments along with the email message. After the configuration for the email bc is specified in the WSDL, do the following
  1. Open the defined WSDL
  2. Go to the attribute "email:smtpInput"
  3. Right click and select "Add SMTP attachment" option

Multiple attachments can be added to the email message in this manner.

Receiving Email using Email BC (IMAP protocol)

The Email BC uses JavaMail API to receive email message using the IMAP protocol. As with email clients (like Eudora, Thunderbird, Outlook Express etc), the Email BC needs some configuration to be able to receive emails successfully. All the configuration for the email bc is specified in the WSDL. The netbeans binding wizard (or the WSDL wizard) can be used to create a wsdl file with most common of the configuration.

The netbeans binding wizard is available under "New File Wizard (Ctrl+N) > ESB > Binding".

The netbeans wsdl wizard is available under "New File Wizard (Ctrl+N) > XML > WSDL Document". In both cases, select the following values:
  1. Binding = Email
  2. Type = Read Email (using IMAP)

Click on Next, the IMAP Settings screen will show up.

Configuration:

The important fields/attributes in this screen are the Email Server and the Port, for example imap.gmail.com and 995.
You can refer to your email client's IMAP server settings to set the values here (or ask an administrator).

In case the IMAP server requires authentication, you need to provide the User Name and Password. For secure authentication, just select the checkbox "Use SSL".

Receiving Email using Email BC (POP3 protocol)

The Email BC uses JavaMail API to receive email message using the POP3 protocol. As with email clients (like Eudora, Thunderbird, Outlook Express etc), the Email BC needs some configuration to be able to receive emails successfully. All the configuration for the email bc is specified in the WSDL. The netbeans binding wizard (or the WSDL wizard) can be used to create a wsdl file with most common of the configuration.

The netbeans binding wizard is available under "New File Wizard (Ctrl+N) > ESB > Binding".

The netbeans wsdl wizard is available under "New File Wizard (Ctrl+N) > XML > WSDL Document". In both cases, select the following values:
  1. Binding = Email
  2. Type = Read Email (using POP3)

Click on Next, the IMAP Settings screen will show up.

Configuration:

The important fields/attributes in this screen are the Email Server and the Port, for example pop.gmail.com and 995.
You can refer to your email client's POP3 server settings to set the values here (or ask an administrator).

In case the POP3 server requires authentication, you need to provide the User Name and Password. For secure authentication, just select the checkbox "Use SSL".

Attachment support

How to use NM Properties

Normalized Message properties are commonly used to specify metadata that is associated with message content. javax.jbi.security.subject and javax.jbi.message.protocol.type are two examples of standard normalized Message properties defined in the JBI Specification.

Normalized Message properties are used to provide additional capabilities in Open ESB, such as:
  • Getting and Setting transport context properties. For example, HTTP headers in the incoming HTTP request, or file names read by the File Binding Component
  • Getting and Setting protocol specific headers or context properties (SOAP headers)
  • Getting and Setting additional message metadata. For example. a unique message identifier, or an endpoint name associated with a message
  • Dynamic configurations. For example, to dynamically overwrite the statically configured destination file name at runtime

Some of the use cases mentioned above require protocol/binding specific properties, typically used by a particular binding component. Other properties are considered common or general purpose properties that all participating JBI components make use of, for example, the message ID property, which can be utilized to uniquely identify or track a given message in the integration.

Normalized Message Properties Defined by the Email Binding Component


The following table describes the Inbound NM properties defined by the Email Binding Component
Property Description Type
org.glassfish.openesb.email.inbound.emailserver The email server host used for sending/receiving emails. String
org.glassfish.openesb.email.inbound.port The email server port number. String
org.glassfish.openesb.email.inbound.username The user name used for authentication. String
org.glassfish.openesb.email.inbound.password The password used for authentication. String
org.glassfish.openesb.email.inbound.usessl Whether to use SSL for connection, "true" or "false". String
org.glassfish.openesb.email.inbound.maxmessagecount The maximum number of messages for each poll interval. String
org.glassfish.openesb.email.inbound.ackmode Message Acknowledgement Mode on the response, "manual" or "automatic". String
org.glassfish.openesb.email.inbound.ackoperation Operation used to acknowledge the message, when message acknowledgement mode is "automatic". String
org.glassfish.openesb.email.inbound.pollinginterval Interval between each poll activity for new emails on email server in seconds. String
org.glassfish.openesb.email.inbound.saveattachmentstodir When specified, the email attachments will be saved as files in your local file system. It is the local directory name where the email attachments will be saved to. The base file name will come from the attachment name. String
org.glassfish.openesb.email.inbound.mailfolder The folder on the email server to poll for new emails. String
org.glassfish.openesb.email.inbound.attachments Specifies the attachments file path's. String
org.glassfish.openesb.email.inbound.attachments.count Specifies the number of attachments. int

The following table describes the Outbound NM properties defined by the Email Binding Component
Property Description Type
org.glassfish.openesb.email.outbound.emailserver The email server host used for sending/receiving emails. String
org.glassfish.openesb.email.outbound.port The email server port number. String
org.glassfish.openesb.email.outbound.username The user name used for authentication. String
org.glassfish.openesb.email.outbound.password The password used for authentication. String
org.glassfish.openesb.email.outbound.usessl Whether to use SSL for connection, "true" or "false". String
org.glassfish.openesb.email.outbound.location The standard "mailto" URL Scheme (RFC 2368). String
org.glassfish.openesb.email.outbound.sendoption To specify the email content is in "Text Only", "HTML Only", "XML Only", "Both Text and HTML", "Both Text and XML". The default is "Text Only". String
org.glassfish.openesb.email.outbound.embedimagesinhtml When "true", the html image is embedded into the html document. String
org.glassfish.openesb.email.outbound.attachmentFilePaths Specifies the attachments file path's. String

General Normalized Message Properties


Normalized Message properties are either General, available to all participating JBI components, or protocol/binding specific, used by a particular binding component.

The following General NM properties are available to all binding components.
Property Description Type
org.glassfish.openesb.messaging.groupid Uniquely identifies a message with the group to which a message belongs. For example, it applies the RM sequence group number for SOAP messages, or a time stamped file name (where the file record message comes from). This property is optional. String
org.glassfish.openesb.messaging.messageid Uniquely identifies a message. For batch processing this might be a record number (for example, a particular record in a file), or a GUID. This property is mandatory. String
org.glassfish.openesb.messaging.lastrecord The value is a string representation of boolean ("true" or "false"). This property can be used to signal the last record in a group, e.g. the last record in a RM sequence for SOAP messages, or the last record in a file when multiple record processing is turned on for File BC. This property is optional. String
org.glassfish.openesb.exchange.endpointname The value a string representation of the endpoint name set on the exchange. This represents the endpoint name of the "owner" of the message, and could be made available by JBI runtime. String

How to use Application Variables

The binding component Application Variables property allows you to define a list of name:value pairs for a given stated type. The application variable name can be used as a token for a WSDL extensibility element attribute in a corresponding binding. For example, if you were defining an application variable for the hostname as FOO, then the WSDL attribute would be ${FOO}. In the Application Variables property you would enter a String value of FOO for the name, and the desired attribute as the value. When you deploy an application that uses application variables, any variable that is referenced in the application's WSDL is loaded automatically.

The Application Variables configuration property offers four variable types:
  • String: Specifies a string value, such as a path or directory
  • Number: Specifies a number value
  • Boolean: Specifies a Boolean value. The VALUE field provides a checkbox (checked = true)
  • Password: Specifies a password value. The password is masked and displays only asterisks

Variables also allow greater flexibility for your WSDL files. For example, you can use the same WSDL for different runtime environments by using application variables to specify system specific information. These values can then be changed from the binding component runtime properties as needed, for any specific environment.

When you deploy an application that uses Application Variables, all of the Application Variables that are referenced in the application's WSDL files are loaded automatically. If you attempt to start an application and an Application Variables value is not defined (no value is specified for the Application Variable) an exception is thrown.

To change a property when the application is running, change your Application Variable property value, then right-click your application in the Services window under Servers > GlassFish V2> JBI > Service Assemblies, and click Stop in the pop-up menu. When you restart your project, your new settings will take effect.


Using Application Variables



  • Use variable references in WSDL
userName references variable "username"

  • Define variable values in BC run-time properties
Specifying the runtime values for "username"

  • Deploy application Service Assembly
Now when the application is deployed, SMTP Server authentication should be using the userName value "abc123"

Using Application Variables for password protection

To protect passwords that would otherwise appear as clear text in your WSDL file, you can enter a Password application variable as a token. In the following example, a password application variable is created that uses the name HIDE and the password PROTECT.

  • From the Binding Components directory, under Servers > GlassFish V2 > JBI in the Servers window, select the sun-email-binding. The sun-email-binding Properties appear in the Properties window.
  • Click-on the Application Variables property ellipsis (...) button. The Application Variables editor appears.
  • Click Add, select Password as your variable type, and click OK. A new row is added to the Application Variables editor.
  • Enter HIDE as the name, and enter PROTECT as the value. Because this is a password type, the characters of your password are displayed as asterisks.

Use the application variable name ${HIDE} as your WSDL password attribute, using the dollar sign and curly braces as shown.

How to use Application Configuration

The Application Configuration property allows you to configure the external connectivity parameters for an application that you have created, such as a service assembly, and without changing or rebuilding the application, deploy the same application into a different system. For example, you could take an application that is running in a test environment, and deploy it to a production environment without rebuilding the application.

From the Application Configuration property, you can specify values for a Composite Application's external connectivity parameters, which are normally defined in the WSDL service extensibility elements. You can then apply these values to a user-named endpoint ConfigExtension Property. The Application Configuration property editor includes fields for all of the connectivity parameters that apply to that component's binding protocol. When you enter the name of a saved ConfigExtension and define the connectivity parameters in the Application Configuration editor, these values override the WSDL defined connectivity attributes when your project is deployed. To change these connectivity parameters again, you simply change the values in the Application Configuration editor, then shutdown and start your Service Assembly to apply the new values.

The Application Configuration property editor allows you to create several application configurations referenced by their own user-defined names. Note that different binding component protocols will have different attributes. The Email binding attributes are not the same as the File or FTP binding attributes, and therefore, the Application Configuration property editors for each of these binding components will contain different attributes.

To change a property when the application is running, change your Application Configuration property value, then right-click your application in the Services window under Servers > GlassFish > JBI > Service Assemblies, and click Stop in the popup menu. When you restart your project, your new settings will take effect.


The Email Binding Component's Application Configuration property contains 6 parameters:
  • Host
  • SMTP Location
  • Password
  • Port
  • Use SSL
  • UserName

Using Application Configuration

  • Define a Application Configuration object in Email BC
UserName and Password values are defined for a Application Configuration object named "TestAppConfig1"

  • Specify the reference to the Application Configuration object in the Service Assembly
In the Case Editor, specify the Application Configuration name "TestAppConfig1" under "Config Extension" header

  • Deploy the Service Assembly
Build and deploy the application. It should now use email:SMTPaddress values defined in "TestAppConfig1" Application Configuration object instead of those defined in the corresponding WSDL.

Sending emails with Non-english content (using charset property)




Return to the top
Return to Email BC Page

JSPWiki v2.4.100
[RSS]
« Home Index Changes Prefs
This particular version was published on 04-Dec-09 10:22 AM, -0800 by GautamiK