Handling documents with attachments

WebSphere Partner Gateway provides the Attachment data handler to process documents that are sent between WebSphere Partner Gateway and InterChange Server. The Attachment data handler converts a document within the XML transport envelope (with or without attachments) between its serialized format and its business-object representation. You should configure the Attachment data handler as the payload data handler in either of the following cases:

The Attachment data handler is called from a WebSphere Business Integration adapter.

When the adapter receives a document within an XML transport envelope, it calls the Attachment data handler to convert this document to its appropriate business-object representation. For example, Figure 22 shows the Adapter for JMS calling the Attachment data handler to convert the serialized format of the document to its business-object representation. Conversely, when the adapter receives a business-object representation for a document within an XML transport envelope, it calls the Attachment data handler to convert this business-object structure to its appropriate document format. For example, Figure 23 shows the Adapter for JMS calling the Attachment data handler to convert the business-object representation of the document to its serialized format.

This section provides the following information on the Attachment data handler:

How the Attachment data handler performs the conversion

The Attachment data handler can interpret the structure of the XML transport envelope and handle the conversion between the contained data and the corresponding business-object representation, as follows:

How documents are converted to business objects

Before WebSphere Partner Gateway sends a document to InterChange Server, it must determine whether to wrap the contents in an XML transport envelope. If WebSphere Partner Gateway creates the transport envelope, the payload and any attachments are Base64-encoded. WebSphere Partner Gateway then sends the XML transport envelope to the appropriate adapter with the appropriate transport-level headers. This adapter can be configured to call the Attachment data handler to handle the conversion of payload and any attachments in an XML-wrapped document into the corresponding business-object representation.

To convert a document wrapped in an XML transport envelope to its business-object representation, the calling entity instantiates the Attachment data handler, passing it the document (in its transport envelope). The Attachment data handler then takes the following steps:

  1. Loads the content-type maps defined in the data handler's child meta-object.

    The content-type maps are defined in the ContentTypeMap_x configuration properties of the child meta-object. The child meta-object is a business object that contains configuration information for the Attachment data handler. Attributes in this business object associate content-type maps with content types. For more information, see Creating the Attachment child meta-object.

  2. Checks the document to see whether it is wrapped in an XML transport envelope.
  3. Sets the resulting payload business object and returns this business object to the calling entity.
How documents without a transport envelope are processed

If the Attachment data handler determines that the document is not contained in an XML transport envelope, it does not need to extract the payload data from the envelope structure. Therefore, the data handler uses the PayloadDataHandlerMimeType configuration property (defined in its child meta-object) to obtain the MIME type that identifies the default payload data handler to instantiate for the document payload. This data handler converts the payload data to its corresponding payload business object and returns the resulting payload business object to its calling entity.

How documents in a transport envelope are processed

If the Attachment data handler determines that the document is contained in an XML transport envelope, it must extract the payload and any attachments from this envelope structure before it can process them. Therefore, the data handler takes the following steps to process and convert the document:

  1. Extracts the payload and any attachments from the transport envelope and decodes the payload data.

    The payload is contained in the <payload> XML tag. Each attachment is contained in an <attachment> XML tag.

  2. Searches the content-type maps for a content type that matches that of the payload.

    The Attachment data handler uses the MIME type specified in the matching content-type map to create an instance of a data handler. This data handler converts the payload data to its corresponding payload business object and returns the resulting business object to the Attachment data handler.

  3. Creates the content-information business object for the payload.

    The Attachment data handler examines the business-object-level application-specific information of the payload business object definition and determines the name of the content-information business object, whose attribute name is specified by the cw_mo_bcg_content_info tag. It then creates an instance of this content-information business object and sets the values for the payload content type and encoding.

  4. Creates the attachment-container business object for the payload.

    The Attachment data handler examines the business-object-level application-specific information of the payload business object and determines the name of the attachment-container business object, whose attribute name is specified by the cw_mo_bcg_attachment tag. It then creates an instance of the attachment-container business object and saves it in the appropriate attribute of the payload business object.

    If the cw_mo_bcg_attachment tag does not exist (or is empty), assume that the document does not contain any attachments. Therefore, no further processing steps are required. The Attachment data handler returns the converted payload business object.

  5. Creates the default attachment business object for the attachment container.

    The Attachment data handler examines the business-object-level application-specific information of the attachment-container business object and determines the name of the default attachment business object, whose attribute name is specified by the cw_mo_bcg_default_attribute tag. It then creates an instance of the default attachment business object and saves it in the appropriate attribute of the attachment-container business object.

  6. Determines whether the attachment needs to be converted to a business object by searching the content-type maps for a content type that matches that of the attachment.

    The Attachment data handler examines the content type and character-set encoding from the attachment and checks to see whether there is a corresponding entry in a content-type map.

How business objects are converted to documents

Before WebSphere Partner Gateway receives a document from InterChange Server, an adapter must determine whether to wrap the business-object representation of the payload and any attachments in the XML transport envelope. InterChange Server sends the business object to the appropriate data handler, which handles the actual conversion. This data handler can be configured to call the Attachment data handler to handle the conversion of payload and any attachment business objects into the corresponding payload and attachments as well as the creation of an XML transport envelope.

To convert a payload business object with attachments to its transport-envelope representation, the calling entity instantiates the Attachment data handler, passing it the payload business object. The Attachment data handler takes the following steps:

  1. Loads the content-type maps defined in its configuration meta-object.

    The content-type maps are defined in the ContentTypeMap_x configuration properties of the child meta-object. The child meta-object is a business object that contains configuration information for the Attachment data handler. Attributes in this business object associate content-type maps with content types. For more information, see Creating the Attachment child meta-object.

  2. Checks the business object to determine whether to create an XML transport envelope.
  3. Sets the resulting payload and any attachment tags in the WebSphere Partner Gateway document and returns this document to the calling entity.
How documents without a transport envelope are created

If the Attachment data handler determines that the payload business object does not require an XML transport envelope, it does not need to wrap the payload data in the envelope structure. Therefore, the data handler uses the default payload data handler to convert the payload business object to its corresponding payload document. The PayloadDataHandlerMimeType configuration property (defined in the Attachment data handler's child meta-object) contains the MIME type that identifies the default payload data handler to instantiate for the payload business object. This data handler receives the payload business object as an argument and returns the resulting payload document to its calling entity.

How documents with a transport envelope are created

If the Attachment data handler determines that the payload business object does require an XML transport envelope, it must wrap the payload and attachment documents in this envelope structure. Therefore, the data handler takes the following steps to process and convert the business object:

  1. Gets the content type and character-set encoding for the payload.

    The cw_mo_bcg_content_info tag in the business-object-level application-specific information of the payload business object specifies the name of the content-information attribute. This attribute contains the content type and encoding for the payload.

    Note: If the content-information attribute does not exist, use the default data handler (identified by the MIME type contained in the PayloadDataHandlerMimeType configuration property, in the Attachment data handler's child meta-object) to convert the payload business object.
  2. Searches the content-type maps for a content type that matches that of the payload.

    The Attachment data handler uses the MIME type specified in the matching content-type map to create an instance of a payload data handler. This data handler converts the payload business object to its corresponding payload document and returns the resulting document to the Attachment data handler. From the string that is returned by the payload data handler, the Attachment data handler encodes the bytes using Base64 and stores the result in the payload tag of the XML transport envelope.

  3. Gets the attachment container from the payload business object.

    The attachment container resides in the attachment-container attribute of the payload business object. The business-object-level application-specific information of the payload business object contains the cw_mo_bcg_attachment tag, which identifies the attachment-container attribute. This attribute contains the attachments.

    If the cw_mo_bcg_attachment tag does not exist (or is empty), assume that the document does not contain any attachments. Therefore, no further processing steps are required. The Attachment data handler returns the converted payload in its transport envelope.

  4. For each attachment, determines whether the attachment is represented as a business object or just data.

Setting up the environment for the Attachment data handler

Use of the WebSphere Partner Gateway-supplied Attachment data handler involves the following steps:

Specifying which schema to use

You have the option of using the default schema for the Attachment data handler or using a schema (wbipackaging_v1.1_ns.xsd) that lets you pass the contentId in the Backend Integration packaging.

To use the wbipackaging_v1.1_ns.xsd schema, configure the wbipackaging_version property in the bcg.properties file. (The bcg.properties file is described in the Administrator Guide.) This property is specified as:

 wbipackaging_version=1.n 

where n is 0 or 1. The default value of this property is 1.0.

The meta-object of the Attachment data handler has a wbipackaging_version attribute, which can have a value of 1.0 or 1.1. If you specify 1.1, the Attachment data handler parses and generates the XML messages containing the contentId of the attachment.

To specify the content ID of the attachment, the encoding business object uses the contentId attribute. When the Attachment Data Handler generates the XML from the business object, it uses this attribute to create the contentId tag for the attachment. When the Attachment Data Handler generates the business object from the XML, it sets this attribute, using the value specified in the contentId tag in the XML message.

Deploying the Attachment data handler

The Attachment data handler and associated repository file are available on the WebSphere Partner Gateway installation medium, in the locations listed in Table 35.

Table 35. Location of the components for Attachment data handler
Component Location
Attachment data handler
Integration/WBI/WICS/Attachment/
bcgwbiattachmentdh.jar
Repository file
Integration/WBI/WICS/Attachment/
MO_DataHandler_DefaultAttachmentConfigV1.0.in
or
Integration/WBI/WICS/Attachment/
MO_DataHandler_DefaultAttachmentConfigV1.1.in

Deploy the files into the Web server according to the documentation for the Web server.

Specifying the location of the Attachment data handler

WebSphere InterChange Server needs to know the location of the Attachment data handler, so that it can load it at run-time. To specify the location of the Attachment data handler, take the following steps:

  1. Edit the ICS startup script, start_server.bat, which is located in the bin subdirectory of the InterChange Server product directory (on the computer where InterChange Server resides).
  2. To the CLASSPATH variable in this file, add the jar file for the Attachment data handler: bcgwbiattachmentdh.jar

Configuring the Attachment data handler

Configuring the Attachment data handler consists of the following steps to create the configuration business objects:

Note: You must also create the attachment-related business object definitions for the Attachment data handler. For more information, see Creating attachment-related business object definitions.

Creating the Attachment child meta-object

To configure the Attachment data handler, you must create a child meta-object to provide the class name and configuration properties that the Attachment data handler needs. To create this meta-object, you create a business object definition that contains the attributes listed in Table 36. Use Business Object Designer, which is part of the WebSphere Business Integration Toolset, to create this business object definition

The child meta-object provides the class name and configuration properties that the Attachment data handler needs. In the Business Object Designer tool, create a child meta-object that includes MIME types for the payload and for the types of attachments you expect to receive.

The attributes of the child meta-object are shown in Table 36. An example of a child meta-object for the Attachment data handler is shown in Figure 15.

Note: The sample business objects shown in this chapter do not include the standard attributes (such as ObjectEventId) required by WebSphere InterChange Server but not used by the Attachment data handler.
Table 36. Configuration properties in the Attachment child meta-object
Attribute Name Description
ClassName

Class name (required), which points to the following data handler class:

com.ibm.bcg.DataHandlers.AttachmentDataHandler
ContentTypeMap_x

The content-type map for the payload and for each type of attachment you expect to receive in the XML wrapper.

For more information, see Content-type maps.

PayloadDataHandlerMimeType MIME type used to identify the default data handler, which processes a payload that does not have associated attachments.
wbipackaging_version This attribute can have a value of 1.0 or 1.1. If you specify 1.1, the Attachment data handler parses and generates the XML messages containing the contentId of the attachment.
Important: To assign a value to the attributes in Table 36, set the default value of the attribute. For example, if the Attachment data handler is to use the XML data handler for its default data handler, set the Default Value of the PayloadDataHandlerMimeType attribute to text/xml.
Content-type maps

The content-type map determines the data handler that the Attachment data handler calls to convert information formatted in the associated content type. For example, if the content type of the payload is application/xml, the Attachment data handler looks for a content-type map whose ContentType attribute contains the value application/xml. If no matching content type can be found, the data handler assumes that it should not convert the associated attachment to a business object.

You would create a content-type map for each of these content types, with the attribute-level application-specific information as shown in Table 38.

When you create an attribute in the child meta-object that represents a content-type map, keep the following in mind:

The content-type map can also specify the character set for encoding as well as whether an attachment should be converted to a business object. For a description of the child meta-object attributes and an example, see Creating the Attachment child meta-object.

For example, suppose you have the following content types in your document:

Table 38. Sample content-type maps
Content type Attribute name Default value
text/xml ContentType_1 ContentType=text/xml;MimeType=myxml; CharSet=UTF-8;ConvertAttachment=false;
application/xml ContentType_2 ContentType=application/xml; MimeType=mynewxml;CharSet=UTF-16; ConvertAttachment=true;
application/octet-stream ContentType_3 ContentType=application/octet-stream; MimeType=myoctet
Sample child meta-object

WebSphere Partner Gateway provides the following InterChange Server repository input files, which contains a sample child meta-object for the Attachment data handler:

ProductDir/Integration/WBI/WICS/Attachment/
   MO_DataHandler_DefaultAttachmentConfigV1.0.in

ProductDir/Integration/WBI/WICS/Attachment/
   MO_DataHandler_DefaultAttachmentConfigV1.1.in

where ProductDir is the directory of your installed WebSphere Partner Gateway product. The repository files define a single Attachment data handler whose associated child meta-object is MO_DataHandler_DefaultAttachmentConfig. Figure 15 shows the sample child meta-object for the Attachment data handler. This meta-object defines two content-type maps, ContentTypeMap_1 and ContentTypeMap_2.

Figure 15. Sample child meta-object for the Attachment data handler
This figure shows a sample child meta-object containing two content type maps.

MO_DataHandler_DefaultAttachmentConfigV1.1.in contains the additional attribute:

[Attribute]
    Name = WBIPackaging_Version
    Type = String
    MaxLength = 255
    IsKey = false
    IsForeignKey = false
    IsRequired = true
    DefaultValue = 1.0
    IsRequiredServerBound = false
    [End]

Updating the top-level data-handler meta-object

A WebSphere Business Integration Adapter (such as the Adapter for JMS) uses the MO_DataHandler_Default meta-object to identify the data handlers it can use. Add a reference to the Attachment data handler in the meta-object.

To the MO_DataHandler_Default meta-object, you make the following modifications:

  1. Add an attribute whose name identifies the MIME type associated with the Attachment data handler instance; that is, for a document that contains this MIME type, the associated data handler can handle its conversion to a business object.

    The attribute type of this attribute is the business object definition for the Attachment data handler's child meta-object (see Creating the Attachment child meta-object).

  2. Add an attribute for each of the supported attachment MIME types, if these do not already exist in the top-level data-handler meta-object.

    The attribute type of these attributes would be the child meta-object of the associated data handler.

For example, suppose you have the Attachment data handler as configured in Figure 15. Figure 16 shows the MO_DataHandler_Default meta-object with an attribute that associates the wbic_attachment MIME type with the instance of the Attachment data handler that is configured by the MO_DataHandler_DefaultAttachmentConfig child meta-object. This top-level data-handler meta-object also associates the document MIME type (text/xml) with the XML data handler's child meta-object.

Figure 16. Associating the wbic_attachment MIME type with the Attachment data handler
This figure shows how the MO_DataHandler_Default meta-object has an attribute that associates the MIME type with the instance of the Attachment Data Handler configured in the MO_DataHandler_DefaultAttachmentConfig child meta-object.

For each unique combination of supported content types that you need to support, repeat the process by adding an attribute in the appropriate top-level data-handler meta-object, whose attribute name is the MIME type associated with the Attachment data handler instance and whose type is the name of the associated child meta-object. Also ensure that the configured MIME types (and their child meta-objects) exist in the top-level meta-object.

Creating attachment-related business object definitions

If you are sending or receiving documents that are wrapped in an XML transport envelope, your payload business object needs to contain attachment information. In any document flow, there is one payload and, optionally, multiple attachments. The Attachment data handler expects this attachment information to be in attachment-related business objects. Therefore, you must create business object definitions to represent this information. A business object definition is the form of information that InterChange Server uses. You use the Business Object Designer tool to create business object definitions.

Figure 17 shows the business-object structure for a payload that is wrapped in an XML transport envelope.

Figure 17. Relationship of the payload business object to the attachment business objects
This figure shows the relationship of the payload business objects to the attachment business objects. The payload business object points to the attachContainer_BusObj, which in turn points to the defaultAttach_Bus Obj and the attachment1_BusObj. The attachment business objects point to a contentInfo_BusObj.

As Figure 17 shows, all the attachments are contained in the attachment-container business object. If there are attachments, the payload business object has an attribute that corresponds to the attachment-container business object.

Make sure your business-object structure includes attachment-required business objects by taking the following steps:

  1. Create a business object definition to hold the content-type-encoding properties required by the Backend Integration packaging.
  2. Create a business object definition for each type of attachment.
  3. Create a business object definition for the attachment-container business object.
  4. Modify the business object definition for your payload business object.

Each of these steps is described in the sections below.

Representing the content information

To store the content type and encoding of the associated payload or attachment, you create the content-information business object. To create a content-information business object definition, create the attributes shown in Table 39.

Table 39. Attributes of the content-information business object
Attribute Attribute type Description Is key attribute?
contentType String

The content type for the associated payload or attachment.

Yes
encoding String The character encoding for the associated payload or attachment No

In Figure 17, the contentInfo_BusObj business object definition contains attributes for the content type and encoding of the attachment. These attributes all have attribute-level application-specific information to specify the name of the related protocol header. For example, the x-aux-sender-id attribute has the application-specific information set as follows:

name=x-aux-sender-id

You can choose whatever name you want to identify the content-information business object definition. The application-specific information of the attachment business object determines if this is a Content Type Encoding business object type. Figure 17 shows an example of a content-type-encoding business object definition called contentType_BusObj.

Representing attachment data

For attachment data that is not to be converted into a business object, you create the default attachment business object. This business object is useful for containing base64-encoded data that comes from the transport envelope.

To create a default-attachment business object definition, take the following steps:

  1. Create the attributes shown in Table 40.
  2. If you create a content-information business object, in the application-specific information for the default attachment business object definition, add the cw_mo_bcg_content_info tag to identify the attribute that contains the content information.

    This cw_mo_bcg_content_info tag has the following format:

    cw_mo_bcg_content_info=contentInfoAttr

    where contentInfoAttr is the name of the attribute that contains the attachment-container business object.

Table 40. Attributes of the default attachment business object
Attribute Attribute type Description Is key attribute?
attachment String

The piece of attachment data.

Note: This attribute is the key attribute of the business object definition.
Yes

An attribute to hold the content information

Business object

An optional attribute to hold the content-information business object, which provides the content type and encoding for the attachment data. This attribute should have single cardinality.

Note: If this attribute does not exist, the Attachment data handler does not set the attachment data in the business object.

For more information on the format of the content-information business object, see Representing the content information.

No

In Figure 17, the defaultAttach_BusObj business object definition contains attributes for the piece of attachment data, including a content-information business object to hold its content type and encoding. The piece of attachment data that this default attachment business object represents does have a content-type encoding, represented by the contentType_attach attribute. Therefore, the default attachment business object definition includes the following tag in its business-object-level application-specific information:

cw_mo_bcg_content_info=contentType_attach

Representing the attachments

For each kind of attachment in your document that converts to a business object, you must create a separate attachment business object definition. The attachment business object definition represents the actual data in a document attachment. To create an attachment business object definition, take the following steps:

  1. Create an attribute for each piece of attachment data.

    Possible attribute types can include String (for simple pieces of data) or a business object definition (for complex data).

  2. If the attachment requires content-type encoding:
    1. Create a content-type-encoding attribute.

      The attribute type for this attribute is the content-type-encoding business object definition (see Representing the content information).

    2. Add to the business-object-level application-specific information of the attachment business object definition the cw_mo_bcg_content_info tag, to identify the attribute that contains the content-type encoding.

      This cw_mo_bcg_content_info tag has the following format:

      cw_mo_bcg_content_info=contentTypeEncodingAttr

      where contentTypeEncodingAttr is the name of the attribute that contains the content-type-encoding business object.

In Figure 17, the payload document has one attachment, represented by the attachment1_BusObj business object definition. This attachment does have a content-type encoding, represented by contentTypeEncoding attribute. Therefore, the attachment business object definition includes the following tag in its business-object-level application-specific information:

cw_mo_bcg_content_info=contentTypeEncoding

Representing the attachment container

The attachment container contains all document attachments in the transport envelope. To represent the attachment container for InterChange Server, you create the attachment-container business object. Each attribute in the attachment-container business object represents one attachment.

To create the attachment-container business object definition, take the following steps:

  1. Add an attribute for each attachment in the document that is to be converted to a business object.

    The attribute type for each of these attributes is the associated attachment business object (see Representing the attachments). Each attribute should have multiple cardinality.

  2. Add to the application-specific information for each attribute the wbic_type tag to identify the attribute as an attachment.

    The wbic_type tag has the following format:

    wbic_type=Attachment

    Note: An attachment attribute can have multiple cardinality.
  3. If the payload contains attachment data that should not be converted to a business object:
    1. Add an attribute for the default attachment business object.

      The attribute type for this attribute is the default attachment business object (see Representing attachment data). It is the key attribute for the attachment-container business object. This attribute does not require the wbic_type tag in its application-specific information.

      Note: The attachment-container business object can contain only one default attachment attribute. However, this attribute can have multiple cardinality.
    2. Add to the business-object-level application-specific information of the attachment business object definition the cw_mo_bcg_default_attribute tag, to identify the attribute that contains the attachment data.

      This cw_mo_bcg_default_attribute tag has the following format:

      cw_mo_bcg_content_info=defaultAttachmentAttr

      where defaultAttachmentAttr is the name of the attribute that contains the default attachment business object.

    Important: If no default-attachment attribute exists, the Attachment data handler cannot convert any attachments that do not have an associated content-type map or attachments that are not converted to business objects. These attachments will be lost during the conversion to business-object representation.

In Figure 17, the attachment container is represented by the attachContainer_BusObj business object definition. This attachment-container business object definition has the following attributes:

Modifying the payload business object definition

The payload business object definition represents the information in your document. It contains an attribute for each piece of information you are transferring between WebSphere Partner Gateway and InterChange Server. For information on the creation of the payload business object definition, see Business object for the document.

If you are sending or receiving documents that contain attachments, your payload business object needs to contain attachment information. In any document flow, there is one payload and, optionally, multiple attachments. If the payload of your document contains attachments, you must modify the payload business object definition as follows:

  1. Create an attribute to hold the payload data.

    You might find it easier to use if your actual payload data is stored in a separate payload business object definition. In this case, the top-level payload business object contains an attribute for the payload data whose attribute type is the business object definition of actual payload data.

  2. Add an attachment container:
    1. Add an attribute to hold the attachment container.

      The attribute type of this attribute is the attachment-container business object definition (see Representing the attachment container). This attribute should have single cardinality.

    2. In the application-specific information for the payload business object definition, add the cw_mo_bcg_attachment tag to identify the attribute that contains the attachment container.

      This cw_mo_bcg_attachment tag has the following format:

      cw_mo_bcg_attachment=attachContainerAttr

      where attachContainerAttr is the name of the attribute that contains the attachment-container business object.

  3. Optionally, you can specify the content type of the payload. The Attachment data handler uses this content type to determine which data handler to instantiate to convert the payload data. If it finds a matching content type in the content-type maps, it instantiates the data handler for this content type.
    1. Add a content-information attribute, which is an optional attribute to hold the content type and encoding for the payload. This attribute should have single cardinality.
      Note: If this attribute does not exist, the Attachment data handler obtains the data handler to convert the payload from the setting of the PayloadDataHandlerMimeType configuration property, in its child meta object.
    2. In the application-specific information for the payload business object definition, add the cw_mo_bcg_content_info tag to identify the attribute that contains the content information.

      This cw_mo_bcg_content_info tag has the following format:

      cw_mo_bcg_attachment=contentInfoAttr

      where contentInfoAttr is the name of the attribute that contains the content-information business object. For more information on the format of the content-information business object, see Representing the content information.

  4. Add any configuration attributes required for your transport protocol.

    For example, if you are using the JMS transport protocol, your payload business object definition must contain the JMS dynamic business object. For more information, see the section on how to create business object definitions in support of your transport protocol.

Copyright IBM Corp. 2003, 2005