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.
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 the required business object attributes listed in Table 8.
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.
If you use the default value for this attribute, you must also set the UseDefaults connector property to true. For more information on the UseDefaults property, see Table 5. |
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. |
ContentType |
The content type of the mail to be sent. Valid values are text/plain. |
DataEncoding |
Type of message-- either text or binary. |
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. |
ReplyTo |
ReplyTo address or addresses of e-mail header. For more information, see Specifying valid e-mail addresses. |
In addition to the attributes listed in Table 8, the top-level business object can contain the optional attributes listed in Table 9.
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.
By default, the Email adapter creates an attachment named after the business object sent to request processing and populates the email with information obtained from the required and optional attributes listed above. However, to create a custom attachment name or include a binary attachment, each business object should use a child business object to specify attachment-related information. See Table 10 for optional child business object attributes for attachment-related information.
When using a child business object to specify attatchment-related information, the name of the attribute which maps to the child business object must be mentioned in the business object-level ASI of the top-level business object. For example, cw_mo_conn=<child_bo_attr_name>.
The Inbound Wrapper BO functionality allows the connector to collate all of the business objects from e-Mail attachments and send them together to the integration broker. The InboundWrapperBO structure also has attributes such as FromAddress and ToAddress that are populated by the connector. See Table 11 for different attributes supported by the InboundWrapperBO structure.
Name | Type | Cardinality | Meaning | Required in BO structure |
---|---|---|---|---|
FromAddress | String | 1 | "From" header of the mail message | Yes |
ToAddress |
String | 1 | "To" header of the mail message | Yes |
CC | String | 1 | "CC" header of the mail message | Yes |
BCC | String | 1 | "BCC" header of mail message | Yes |
Subject | String | 1 | Mail subject | Yes |
ReplyTo | String | 1 | ReplyTo header of the mail message | Yes |
SentDate | String | 1 | Date and time the mail was sent | Yes |
ReceivedDate | String | 1 | Date and time the mail was received | Yes |
<actual_bo> | <bo_type> | <1/N> | Actual business object type Examples: Customer
Invoice PurchaseOrder |
Yes |
cw_mo_conn=<child_bo_attribute_name>
where child_bo_attribute_name is the name of the attribute which maps to the attachment metaobject. For a list of attributes supported by the attachment metaobject, see Table 12.
Name | Type | Cardinality | Meaning | Required in BO structure |
---|---|---|---|---|
AttachmentName | String | 1 | Attachment name | Yes |
Size* | String | 1 | Size of the attachment | Yes |
MimeType | String | 1 | MimeType of the attachment | Yes |
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 datahandler 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. By default, the adapter converts each attachment to a business object and sends them individually to the broker. However, if you configure the InboundWrapperBO property, the adapter will will collate all business objects from datahandler mail attachments and send them together to the broker.
To accomplish this, the adapter will create a wrapper business object. The wrapper business object will include information about the email as well as the actual business objects created by the datahandler (such as Customer or Invoice). In turn, each business object included in the wrapper business object will then have a child business object to store attachment-related information. For more information on attachment-related information, see Optional child business object structure for customizing attachment names or sending binary attachments.
The wrapper business object structure has attributes (such as FromAddress, ToAddress, and ReplyTo) that will be dynamically populated by the adapter when the InboundWrapperBO property is set. For the adapter to dynamically populate this information, the child business object name has to be identified in the business object ASI using the following format:
cw_mo_conn=<child_bo_attr_name>
<child_bo_attr_name> is the name of the attribute which maps to the attachment metaobject. For attributes supported by the attachment metaobject, see Table 13 .
Name | Type | Cardinality | Meaning | Required in BO structure |
---|---|---|---|---|
AttachmentName | String | 1 | Attachement name | Yes |
Size | String | 1 | Approximate size of the attachment (in bytes) | Yes |
MimeType | String | 1 | MimeType of the attachment | Yes |
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.
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.
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.
A 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.
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 attributes have properties that can affect how the adapter and integration broker treat those attributes. Table 14 describes how the e-Mail adapter uses these properties for the attributes in the top-level business object.
For event notification, the e-Mail adapter does not use business object attribute properties.