Using e-Mail adapter business objects

Using the e-Mail adapter, an integration broker can e-mail a message and include business objects or files as attachments to the e-mail. The business objects or files are wrapped in a top-level hierarchical business object that contains routing information for the adapter. The business objects to be sent are defined as children of the top-level business object. If the e-Mail adapter will be used for business object request processing, you must define these wrapper business object definitions.

Note that wrapper business objects need only be designed for request processing. No wrapper business objects are needed for polling. In polling, the adapter looks at the MIME type of each of the e-mail message attachments, instantiates the appropriate data handler, and passes the attachment to the data handler. The data handler determines the name of the business object from the attachment, finds the corresponding business object definition in the list of supported business objects for the adapter, and converts the contents of the attachment into a business object.

Business object structures

The e-Mail adapter top-level business object must contain a set of attributes that describe the content and routing information for an e-mail message. The adapter composes the e-mail message using these attributes. These attributes are listed in Table 6.

Table 6. Required attributes in a top-level e-mail business object
Name Description
RecipientName
 
Recipient e-mail address or addresses. For more information, see "Specifying valid e-mail addresses".
MessageSubject
 
Description of the e-mail message. This value is set in the business object by the integration broker.
MessageContent
 
Content of the e-mail message. This value is set in the business object by the integration broker.
FromAddress
 
Sender's e-mail address. The sender receives any undelivered messages. For more information, see "Specifying valid e-mail addresses".
MimeType
 
Mime type of the attachments. If not specified, the adapter does not process child business objects.
AttachmentExtension
 
Set the Default Value property of this attribute to the extension that should be given to files that represent business objects contained in the e-mail. For instance, if a business object is sent as an attachment in an e-mail and the Default Value property of this attribute is set to the value txt then the attachment that represents the business object will have an extension of .txt.
BusinessObjectMimeCharset
 
The character set for business objects contained in the e-mail. For more information about this property, see the description for the identical property at the level of the adapter definition in BusinessObjectMimeCharset.
BusinessObjectMimeEncoding
 
The encoding for business objects contained in the e-mail. For more information about this property, see the description for the identical property at the level of the adapter definition in BusinessObjectMimeEncoding.
MessageContentMimeCharset
 
The character set for the message content. For more information about this property, see the description for the identical property at the level of the adapter definition in MessageContentMimeCharset.
MessageContentMimeEncoding
 
The encoding for the message content. For more information about this property, see the description for the identical property at the level of the adapter definition in MessageContentMimeEncoding.
MessageHeaderMimeCharset
 
The character set for the message header. For more information about this property, see the description for the identical property at the level of the adapter definition in MessageHeaderMimeCharset.
MessageHeaderMimeEncoding
 
The encoding for the message header. For more information about this property, see the description for the identical property at the level of the adapter definition in MessageHeaderMimeEncoding.

In addition to the attributes listed in Table 6, the top-level business object can contain the optional attributes listed in Table 7.

Table 7. Optional attributes in a top-Level e-mail business object
Name Description
PriorityLevel
 
Valid values include Normal, High, and Low. The adapter uses this value to set the priority of outgoing mail.
attributes that represent hierarchical business objects The adapter converts the child business objects into attachments in the e-mail message.
attributes that specify the names of files The adapter includes the files as attachments in the e-mail message.

Figure 4 illustrates the basic structure of a top-level business object named Email_TLO_Customer_Wrapper for the e-Mail adapter. This business object contains a hierarchical Customer business object as a child and includes an attribute pointing to a file. The Customer business object and the file are added to the e-mail as attachments.

Figure 4. Example e-Mail adapter business object

Diagram of an sample e-Mail adapter business object.

Attributes specifying business objects

Any business object can be included in the top-level Email business object, as long as the contained business object conforms to the requirements imposed by the configured data handler. If an attribute is a business object, its cardinality must be 1.

When creating business object definitions for the e-Mail adapter, keep in mind that a data handler for the e-Mail adapter must place each business object contained in a top-level business object for the e-Mail adapter in a single attachment. This contained business object may be a large hierarchical business object containing many child business objects of its own, and these children are typically included in the serialized business object in the attachment.

There may be instances when you want to place multiple hierarchical business objects in a single attachment in the top-level e-Mail adapter business object. To do this, wrap the business objects in a parent business object, and define a complex attribute for that parent in the e-Mail adapter top-level business object.

Attributes specifying files

To include a file attachment with an e-mail message, specify the complete filename including the path name. If the file resides on another machine, specify the file name using the UNC naming convention. For example, if the file resides on a machine named Ernesto, specify the path name as: \\Ernesto\Email\EmailMessage.txt. You can also map a network drive to the machine and specify the file name as F:\Email\EmailMessage.txt.

How business objects and files are processed

When the adapter has processed the basic set of attributes in the top-level business object, it looks for additional attributes. These can be either of type String or type business object. If an attribute is of any other type, the adapter ignores it. The adapter processes each additional non-null attribute as follows:

After processing all the non-null attributes of the top-level business object successfully, the adapter sends the e-mail.

Business object conformance with data handler requirements

Although you can include any business object in the top-level wrapper business object for the e-Mail adapter, the contained business objects must deliver data in a form that conforms with the requirements of the data handler used to convert the data.

For example, for the BySize data handler, a business object definition must specify a value for the MaxLength attribute property for each business object attribute. For the XML data handler, the business object definition must include application-specific text that enables the data handler to generate an XML document.

It is good practice, therefore, is to create your own business object definitions for each type of data to be processed. In the business object definition, provide only the data required by the application and the information required by the data handler. You can then include these business objects in the top-level e-Mail adapter business object.

See the Data Handler Guide for information specific to each data handler.

Business object verb processing

When processing business object requests, the e-Mail adapter processes only the Create verb. It returns failure for any other verb. The adapter retains the verb of the child business objects.

For event notification, each e-mail can result in multiple business objects. The application sending the e-mail message is responsible for setting the verb of each business object. The data handler does not process the verbs of these business objects, but sets them in the business objects that it generates.

Business object attribute properties

Business object attributes have properties that can affect how the adapter and integration broker treat those attributes. Table 8 describes how the e-Mail adapter uses these properties for the attributes in the top-level business object.

Table 8. Business object attribute properties
Attribute property Description
Required For business object requests, the e-Mail adapter checks whether the Required property is set to True.
Default Values If the business object does not provide a value for a Required attribute and a default value is specified, the adapter uses the default value.
Max Length Not used
Type Not used
Key Not used
Foreign Key Not used
Application-Specific Information Not used

For event notification, the e-Mail adapter does not use business object attribute properties.

Copyright IBM Corp. 1997, 2003