Email


WebSphere Adapter for Email documentation

With WebSphere Adapter for Email, you can create integrated processes that include the exchange of information using email, without special coding.


Overview of WebSphere Adapter for Email

With WebSphere Adapter for Email, you can create integrated processes that can exchange information using email, without special coding.

For example, you can use the adapter to send general broadcast e-mails to a group of addresses or to send a notification email to a single address that an action has taken place, such as a customer record update in a database. The adapter can also forward information received in an email message to IBM Business Process Manager or WebSphere Enterprise Service Bus and use it to initiate a service ( to initiate a customer record update).

Suppose a company uses email as its principal communication tool for most of its business operations. A new product is coming out and the marketing team wants to notify all of their IBM Business Partners before information is made available to the public. You can use WebSphere Adapter for Email to send an email broadcasting the new release date to a large group of email addresses. Or, imagine that a customer sends an email to a company to notify it their address has changed. In this case, you can use the adapter to send the address change request to an application that tracks addresses, and then returns an email to the customer with notification the address change request is complete.

The adapter is imported and configured in a module created in IBM Integration Designer and deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus. After the configuration is completed, the adapter acts like a service provider in part of a service-oriented architecture (SOA) implementation, providing operations to send and receive emails. Client applications interact with the module instead of directly with the mail server. This configuration enables the authentication details (such as user name and password) that you provide when you set up a module to be shielded from the client applications and services outside of the module. The adapter exposes a service interface that hides the mechanics of how the data or operations are obtained or used.

The benefit of creating the module with the external service wizard in IBM Integration Designer is that it becomes a reusable unit that can perform a specific inbound or outbound service. Each module uses a consistent interface and standard business objects, so the applications consuming the service do not have to understand the lower-level details of the mail server.


Feedback


Hardware and software requirements

The hardware and software requirements for WebSphere Adapters are provided on the IBM Support website.

To view hardware and software requirements for WebSphere Adapters, see http://www.ibm.com/support/docview.wss?uid=swg27006249.


Additional information

The following links provide additional information you might need to configure and deploy your adapter:


Feedback


Technical overview of WebSphere Adapter for Email

WebSphere Adapter for Email enables email connectivity between IBM Business Process Manager or WebSphere Enterprise Service Bus and one or more mail servers. The adapter itself is housed within an adapter module that you create using the external service wizard in IBM Integration Designer. Each module performs an outbound or inbound service, such as retrieving emails from a mail server or sending emails to a group of recipients.

A module encapsulates the service in a reusable unit and consists of both a project in IBM Integration Designer and a unit of deployment which is an enterprise archive (EAR) file to IBM Business Process Manager or WebSphere Enterprise Service Bus. The module is packaged and deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus as an enterprise archive (EAR) file.

In the simplest implementation, you can use the adapter to send emails to one or more email addresses. This process is referred to as outbound communication because the adapter is part of a module designed to send emails out to a mail server. You can also use the adapter to poll a mail server for incoming emails, and then send the information found in the email to a service. The service consumes the information forwarded by the adapter to complete a task. This process is called inbound communication.

In more complicated implementations, you use a number of individual modules (designed for inbound and outbound communication) together to initiate an automated flow of operation, and then send an email notification to an email address to confirm that an action is completed. Similarly, you can create an inbound module that listens for incoming email events on the mail server that match certain criteria ( e-mails with a specific word in the subject field) and forwards only those email events to the service.

The adapter sends and receives emails to or from different mail servers by using the SMTP email protocol for all outbound communication and either the IMAP or POP3 email protocol for inbound communication. Depending on what inbound protocol your mail server supports, you can select between IMAP and POP3 when you create your inbound module.


Feedback


Outbound processing

WebSphere Adapter for Email supports outbound request processing. When the adapter receives a request in the form of a business object from a service, it processes the request and creates an email message. The adapter then sends the email message to a mail server.

Outbound processing begins with the adapter receiving a request in the form of a business object from a service. Business objects represent data the adapter needs to create an email and each one might include, among other things, attachments, and email addresses for where the email is to be sent. When a request is received by the adapter, the adapter takes the information stored in the business object and creates an email. This email is then forwarded to the mail server for distribution.

The following illustration shows how the adapter and module (which encapsulates the service in a reusable unit) function together as part of an outbound service. A module created for outbound processing receives the business object, the business object is turned into an email by the adapter, and then the adapter sends the email to the mail server for distribution.

Figure 1. Adapter as part of an outbound SOA implementation

Each outbound module contains components that form a service, including an import. An import is a component, but without an implementation used to identify the services outside the module, making them callable from within the module. To communicate with references (for calling interfaces), imports require enterprise information system (EIS) binding information, to specify how the data is to be transported from the module. The assembly editor in IBM Integration Designer sets up the import and the EIS binding.

The following illustration shows a more detailed view of the module in an outbound implementation. The I and R symbols within the illustration represent interfaces and references. Interfaces dictate to the users of a service, in this case the import, how the component can be used. Interfaces are specification of the operations performed by a component. The operations are createCustomer, createAddress, and createEmail for outbound communication. References declare the interface that your service component is going to call. Each component in your module has one or more references. When you write your implementation for your service component using the assembly editor in IBM Integration Designer, you call a reference instead of directly calling the component. This implementation allows you to reassemble components in the future because you have not built dependencies into the code.

Figure 2. Outbound communication showing the import

During outbound processing, the adapter itself does not create emails. Instead, it converts the information received in a business object to a message that mail servers supporting the RFC822 format can understand.

This process is not visible to you. It is only mentioned because the term "RFC822 format" appears in the reference section in regard to the email headers the adapter supports.

When a mail server receives an email message from the adapter, the mail server converts the message to an email and sends it to all email addresses listed in the To, Cc, and Bcc fields. If the adapter cannot send the message successfully to the server, it logs the following information:


Feedback


Outbound data transformation

During outbound communication, the adapter transforms business objects into multipart MIME email messages.

While the adapter uses an adapter-specific data binding and data handlers to accomplish it, the actual transformation is external to the adapter and performed by IBM Business Process Manager or WebSphere Enterprise Service Bus. The data bindings and data handlers the adapter uses to compose an email from the corresponding attributes in a business object are configured through the external service wizard in IBM Integration Designer.


Data bindings

Data bindings are essentially maps that define how a business object is to be formatted. Data bindings are responsible for reading the fields in a business object and filling the corresponding fields in an email.

During outbound communication, the data binding takes the following fields from a business object and populates the equivalent fields in an email with their values:

For data that does not require transformation, the adapter conducts the pass-through processing, where data such as attachments pass through the system without being altered.

The adapter uses one of the three data bindings during outbound communication. Each data binding corresponds to a business object structure or data type selected in the external service wizard. The following table lists these data bindings and describes their usage. A more detailed description of each data binding is provided in the sections that follow the table.

Outbound data bindings

Data binding Usage
Email simple data binding Used for the simple alert email data type
Email wrapper data binding Used for the generic email and the generic email with business graph data types
Email fixed structure data binding Used with the user-defined data type
Email data binding Used only with version 6.0.2 business objects for compatibility with earlier versions

Email simple data binding The email simple data binding is the default data binding for the simple alert email data type in the external service wizard. This data binding corresponds to the simple alert email business object structure that is described in this documentation.

Email wrapper data binding The email wrapper data binding is the default data binding for both the Generic email and Generic email with business graph data types in the external service wizard. This data binding corresponds to the email business object structure.

Email fixed structure data binding The email fixed structure data binding is the default data binding for the user-defined data type in the external service wizard. This data binding corresponds to a specific business object structure defined by a user. With this data binding, the order of the attachments is significant. The attachments must be in the same order as the attributes in the business object. This data binding retains the order.

Email data binding This data binding is used exclusively for compatibility with business objects created in version 6.0.2 or earlier. This data binding supports the five-level business object structure used in version 6.0.2 of the adapter.


Data handlers

In addition to the data bindings, data transformation requires the use of a data handler. Data handlers are converters of data from one format to another. Data handlers perform the conversions between a business object and a particular MIME format. Data handlers are provided by IBM Business Process Manager or WebSphere Enterprise Service Bus.

For data that does not need to be transformed, such as some attachments, the adapter can be configured to conduct what is called pass-through processing. In pass-through processing, data passes directly from the business object to the email without being altered.


Character encoding

To send globalized characters in email messages, you set encoding values for headers, mail content, and attachment business objects. For all data types except the simple alert email data type, you can set encoding values at two levels: in the Encoding attribute of the business object or in the Encoding property of the data binding in the data binding properties.

During pass-through processing, the adapter uses the encoding value that is set in the business object. When data transformation is required, the adapter uses the value that is set in the individual data binding.

In both pass-through and non pass-through scenarios, the headers are encoded with same encoding value such as the mailContent.



Related reference:

Interaction specification properties

Feedback


Inbound processing

WebSphere Adapter for Email supports inbound processing of email events. Inbound event processing means the adapter polls the mail server at specified intervals for new emails that are ready for processing. When the adapter detects an event that is ready to be processed, it converts the event data into a business object and sends it to the consuming service.

During inbound processing, the adapter polls the mail server for new emails, which are called events. When the adapter detects a new event, it reads the email and creates a business object to represent the email content. The adapter then forwards the business object to the export which is an exposed interface from a service component architecture (SCA) module that offers a business service to the outside world. Business objects carry the information the adapter takes from an email. By converting emails to business objects and forwarding them to a service, the services using your adapter module do not have to deal directly with the mail server. It is the adapter that polls for events, changes them to a format the consuming services can understand (business objects), and then forwards them to the export for delivery to the services that consume them.

The following illustration shows at a high level how the adapter functions as part of an inbound service in a service-oriented architecture (SOA) implementation. The adapter polls the mail server for incoming events, converts them into business objects, and then the adapter sends them to a consuming service.

Figure 1. Adapter as part of an inbound SOA implementation

Each inbound module contains components that form a service, including an export. An export is a component, but without an implementation. Exports allow components in a module to provide their services to external clients. Exports require an EIS binding, which specifies the means of transporting the data from the modules. The assembly editor in IBM Integration Designer sets up the export, lists the supported bindings, and simplifies its creation. For inbound requests, business objects are essentially the logical graphical representation of the content of an incoming email, that appears as output from the export that represents the module in the assembly diagram.

The following illustration shows a more detailed view of the module in an inbound implementation. The I and R symbols within the illustration represent interfaces and references. Interface is a specification of the operations performed by a component. For inbound communication, it is limited to the Read operation. The interface dictates to the users of a service component, in this case the export, how the component can be used. A reference declares the interface that your service component is going to call. Each component in your module has one or more references. When you write the implementation for your service component using the assembly editor in IBM Integration Designer, you call a reference instead of directly calling the component. This implementation allows you to reassemble components in the future because you have not built dependencies into the code.

Figure 2. Inbound communication showing the export


Supported inbound protocols

The adapter supports two different inbound email protocols: POP3 and IMAP. With each, the adapter polls the mail server at a specified interval for inbound events (emails) and when an email is detected on the mail server, the adapter converts it to a business object. The adapter considers any email in the specified inbox folder on the mail server that is ready for processing an event.

Depending on your mail server, you might be able to choose the inbound email protocol the adapter can use. Differences between the protocols and a description of how the adapter works with each protocol are noted in Table 1 and the sections that follow.

Differences between the IMAP and POP3 protocols

IMAP POP3
Supports the existence of multiple mail folders on a mailbox. Supports only one mailbox (named Inbox) per user.
Allows a copy of the email to remain on the mail server after the client receives the email. Supports a view-once-only feature on the server. The mail is deleted from the mail server after the client receives a copy of it.


Inbound communications with IMAP

If using the IMAP protocol for your inbound communication, the following steps are performed:

  1. The adapter polls the mail folders at regular intervals and logs any unread emails as events in the event store. You can use the activation specification PollFolders property to customize the list of folders that are searched by the adapter.

    If you specify multiple mail server folders for the mail server account in the PollFolders property, the adapter polls all mail server folders sequentially.

  2. Search criteria determines which events are picked up from the mail server. The adapter picks up all events that match the search criteria. If no search criteria is specified, the adapter picks up all unread emails.
  3. The adapter writes all polled events to the staging directory. After an event is written to the staging directory, it is deleted from the mail server.
  4. The adapter transforms each event into an email business object. The headers, email body content, and mail attachments are recorded within the business object.
  5. The email business object is sent to the export.

  6. After it has been processed, the adapter deletes processed emails from the staging directory and archives them (if archiving is selected).

    If the archive file naming pattern activation specification property is specified, the file names conform to the pattern.


Inbound communications with POP3

If using the POP3 protocol for your inbound communication, the adapter performs the following steps during inbound operations (from the mail server to the service):

  1. Polls the Inbox folder on the mail server for inbound events (new emails). When it finds an email, it logs it as a new event in the event table.

    If you specify search criteria, all unread emails that fit the search criteria are picked up by the adapter. If no search criteria are specified, the adapter picks up all unread emails.

  2. Writes new events to the staging directory as files and then deletes them from the mail server.
  3. Converts the email into a business object. Headers, email body content, and mail attachments are recorded within the business object.
  4. Sends the business object to the export.
  5. Deletes all processed email from the staging directory and archives them if the archiving property is configured.

    If the archive file naming pattern property is specified, the file names conform to the pattern. If it is not specified, the name remains the same as it is in the staging directory.



Related tasks:

Set deployment and runtime properties for inbound processing


Related reference:

Activation specification properties

Resource adapter properties

Connection properties for the external service wizard

Inbound configuration properties

Feedback


Inbound data transformation

During inbound communication, the adapter transforms multipart MIME email messages into business objects.


Data bindings

While the adapter uses an adapter-specific data binding and data handlers for inbound data transformation, this actual transformation is external to the adapter and provided by IBM Business Process Manager or WebSphere Enterprise Service Bus. The data bindings and data handlers the adapter uses to read the contents of an email and fill the corresponding attributes in a business object are configured using the external service wizard in IBM Integration Designer.

To take fields from an email and populate a business object, the adapter needs a data binding. Data bindings are maps that define how a business object is to be formatted. Data bindings are responsible for reading the fields in an email and populating the corresponding fields in a business object.

During inbound communication, the data binding takes the following fields from an email and populates the parent email business object attributes with their values:

For data that does not require transformation, the adapter conducts a pass-through processing, where data such as attachments pass through the system without being altered.

To transform data in the form of emails coming into the adapter, the adapter uses one of the three data bindings. The following table lists these data bindings and their usage. A more detailed description of each data binding is provided in the sections that follow the table.

Inbound data bindings

Data binding Usage
Email wrapper data binding Default data binding
Email fixed structure data binding Used with the user-defined type business objects
Email data binding Used with the version 6.0.2 business objects


Email wrapper data binding

The email wrapper data binding is the default data binding for both the Generic email and Generic email with Business Graph data types in the external service wizard. This data binding corresponds to the email business object structure.


Email fixed structure data binding

The email fixed structure data binding is the default data binding for the user-defined data type in the external service wizard. This data binding corresponds to a specific business object structure defined by a user. With this data binding, the order of the attachments is significant. The attachments must be in the same order as the attributes in the business object. This data binding retains the order.


Email data binding

This data binding is used exclusively for compatibility with business objects created in version 6.0.2 or earlier. This data binding supports the five-level business object structure used in version 6.0.2 of the adapter.


Data handlers

In addition to the data bindings, data transformation requires the use of a data handler. Data handlers change data from one format to another. Data handlers perform the conversions between a particular MIME format and a business object. Data handlers are provided by IBM Business Process Manager or WebSphere Enterprise Service Bus.

For data that does not need to be transformed, such as some attachments, the adapter can be configured to conduct a pass-through processing. During pass-through processing, data passes directly from the email to the business object without being altered.


Feedback


Event store

The event store is a persistent cache where event records are saved until the polling adapter can process them.

The adapter uses an event store to track the inbound events that come into the system. When a new email is found in the polling folder, the adapter updates the status of the corresponding event in the event store. For recovery purposes, the adapter continually maintains the status of the event in the event store until the event is delivered to IBM Business Process Manager or WebSphere Enterprise Service Bus. If the adapter is abruptly terminated, the adapter uses the event store to determine which events have and have not been processed.

An event store is not required for the adapter to process inbound requests. The adapter creates an event store:

Each event store created by the adapter is associated with a specific inbound module. The adapter does not support multiple adapter modules pointing to the same event store.



Related reference:

Event store structure

Feedback


Business objects

A business object is a structure that consists of data, the action to be performed on the data, and additional instructions, if any, for processing the data. The data can represent anything from a customer record to an email attachment. The adapter uses business objects to either obtain information from an email or to produce an email.


How the adapter uses business objects

The adapter during the outbound processing receives a business object from a service. It then creates an email from the details it finds in the business object and sends the email message to the mail server for distribution. For inbound processing, this process happens in reverse. The adapter takes information from an email, converts it to a business object, and forwards it to a service.


How data is represented in business objects

Business objects are created using either the business object editor or external service wizard in IBM Integration Designer. As shown in the following illustration, a business object consists of a set of fields and a type of data, such as a string or integer. The business object shown in the figure is a customer business object that records name, address, and telephone number information for a customer record. This example uses string values, but many other values are supported by the business object editor.

Figure 1. Customer business object

A field might, in turn, be another business object. For example, the following illustration shows a customer business object that contains another business object. Here, a company that sells pet-related items might want to keep a track of names and species information of the pets that belongs to its customers. The Pet business object stores the name and species information for one customer pet.

Figure 2. Customer business object with child Pet business object

Each business object is associated with an operation. The operation in turn is associated with the wrapper. The operation tells the adapter what to do with the wrapper business objects. The following operations are examples of Create operations used by the adapter to create emails during the outbound communication:

No matter what name you give an operation for your module, the adapter performs the CreateEmail operation.

For inbound communications, Emit is the only supported operation. This operation is used to take information from an email and convert it to business objects.

During adapter configuration, you can optionally choose to generate a business graph. In version 6.0.2, each top-level business object is contained in a business graph, which includes a verb that an application can use in version 6.0.2 to specify additional information about the operation to be performed. In version 7.5.0.2 and later releases, business graphs are optional; they are required only when you are adding business objects to a module created with a version of IBM Integration Designer earlier than version 7.5.0.2. If business graphs exist, they are processed, but the verb is ignored.


How business objects are created

Business objects and their wrapper objects are created by the external service wizard from XSD files either imported from another module or created with IBM Integration Designer business object editor. For any business object structure except the simple alert email structure, create or import the XSD files you want the adapter to make into business objects before you run the external service wizard. If transformation is needed, a business object that maps to the email body or an attachment that needs transformation must exist. A generic email business object is available for pass-through operations. Or, if only a simple alert email is needed (no attachments), the adapter provides a simple alert email structure with standard headers as another option.

You create business objects for your module with the external service wizard launched from IBM Integration Designer. If you define XSD files using the business object editor before starting the external service wizard, the adapter creates business objects from these schemas.


Custom wrapper business objects

Custom wrapper business objects are user-defined wrapper business objects that contain protocol-specific information and content. To use custom business objects, you must first create business object schema files (XSD files) by using the IBM Integration Designer business object editor. You can then use the external service wizard to generate business objects from the XSD files. A custom wrapper business object can be created from an existing business object or from XSD files.

Custom wrapper business objects are useful if you have an existing map or mediation that expects a business object to have a protocol-specific wrapper. The custom wrapper business object does not allow child objects of anyType. Using anyType objects restricts you from using maps and mediation wiring, because you must write programs or code to fetch business objects from the anyType field. You must write such code if child objects of anyType are allowed, because the business object type being set on the anyType field is unknown.



Related reference:

Supported operations

Business object information

Feedback


WAS environment variables

WebSphere Application Server environment variables can be used in the external service wizard to specify directory values. You can now change any string property values in inbound and outbound configuration by only changing the environment variables.

When you configure the adapter for inbound or outbound processing using the external service wizard, you set values for various required local files and directories. You can later change these values in the deployed application from the BPM or WebSphere Enterprise Service Bus administrative console.

Start with BPM or WebSphere Enterprise Service Bus Version 6.1.0, instead of hardcoding values for directories and files, you can declare them as WAS environment variables and specify the environment variable names when you run the external service wizard. When you deploy your application, the environment variable name is replaced with the actual value and used by the adapter.

To change the property value, you can change the environment variable in the BPM or WebSphere Enterprise Service Bus administrative console.

WAS environment variables can be used for all string property values (not Boolean or integer variables) that are set in inbound and outbound configurations.

When you create a WAS environment variable, you specify:



Related tasks:

Defining WAS environment variables


Related reference:

Managed connection factory properties

Activation specification properties

Feedback


The external service wizard

The external service wizard provides a blueprint to create services from existing elements like business objects.

Use the external service wizard to configure your adapter before it is deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus. Using the external service wizard, you can create business object schema files (XSD files), build service descriptions, define connection properties for the mail server and generate business objects that contain everything the adapter needs to conduct inbound and outbound communication.

You can use the external service wizard to generate business objects from the XSD files. The external service wizard builds the service descriptors that are adapter-specific artifacts used in import, export, and WSDL files. Also, you define the connection properties by typing the name or IP address of the mail server and the user ID and password needed to access it. The external service wizard then generates the business objects through which WebSphere Adapter for Email provides operations to send and receive emails.


Feedback


Plan for adapter implementation

You need to consider various factors before setting up and using the WebSphere Adapter for Email. For example, before you configure the adapter, consider whether to set up the adapter in a clustered environment, in which the workload of the server is distributed across multiple machines. Also, if you are migrating from an earlier version of WebSphere Adapter for Email, perform any migration tasks.

  1. Before you begin Before you begin to set up and use the adapter, you must possess a thorough understanding of business integration concepts, the capabilities, and requirements of the integration development tools and runtime environment that you are going to use, and the mail server environment where you build and use the solution.
  2. Security WebSphere Adapter for Email supports user name and password authentication methods of Java™ 2 as implemented in J2C. By supporting authentication, the adapter provides protection for sensitive user data in log and trace files. Java 2 has other security methods, such as Kerberos, which is not supported. The authentication details are configured using the external service wizard. SSL can be configured to protect the integrity of information being passed between the mail server and the adapter and, for users who require it, the adapter can be configured to run in support of the Federal Information Processing Standard (FIPS) 140.
  3. Required folders for inbound processing Several folders are required for activities such as archiving and storage before you run the adapter for inbound processing.
  4. User authentication The adapter supports several methods for supplying the user name and password needed to connect to the mail server. By understanding the features and limitations of each method, you can pick a method that provides the appropriate level of security and convenience for your application.
  5. Deployment options There are two ways to deploy the adapter. You can either embed it as part of the deployed application, or you can deploy it as a stand-alone RAR file. The requirements of the environment affect the type of deployment option you choose.
  6. WebSphere Adapters in clustered environments You can improve adapter performance and availability by deploying a module on a clustered server environment. Clusters are groups of servers that are managed together to balance workloads and to provide high availability and scalability.
  7. Migrate to version 7.5.0.3 of WebSphere Adapter for Email By migrating to version 7.5.0.3 of WebSphere Adapter for Email, you automatically upgrade from the previous version of the adapter. Additionally, you can migrate applications that embed an earlier version of the adapter, so the applications can use features and capabilities present in version 7.5.0.3.
  8. Migrate WebSphere Business Integration applications You need to migrate the WebSphere Business Integration applications so they become compatible with Version 7.5.0.3 of your adapter.



Next topic: Configure the module for deployment

Feedback


Before you begin

Before you begin to set up and use the adapter, you must possess a thorough understanding of business integration concepts, the capabilities, and requirements of the integration development tools and runtime environment that you are going to use, and the mail server environment where you build and use the solution.

To configure and deploy WebSphere Adapter for Email you must understand and be familiar with the following concepts, tools, and tasks:



Next topic: Security

Feedback


Security

WebSphere Adapter for Email supports user name and password authentication methods of Java™ 2 as implemented in J2C. By supporting authentication, the adapter provides protection for sensitive user data in log and trace files. Java 2 has other security methods, such as Kerberos, which is not supported. The authentication details are configured using the external service wizard. SSL can be configured to protect the integrity of information being passed between the mail server and the adapter and, for users who require it, the adapter can be configured to run in support of the Federal Information Processing Standard (FIPS) 140.


Antivirus software

If an antivirus program is running on your system (the system on which the adapter is deployed or the one that hosts the mail server), the adapter might fail to send outbound emails. It happens because some types of antivirus software have auto protection turned on for Internet email protection. When auto protection is turned on, the antivirus software might treat open connections to a mail server as malicious attacks and block all emails using that connection. Because the adapter maintains the connections to the mail server in the pool, it does not close any of the connections. It might result in the antivirus program blocking all email from the adapter.

By default, the Select when antivirus or firewall software is running check box in the connection properties window of the external service wizard is selected. This means the adapter will close the connection after each outbound request.



Previous topic: Before you begin


Next topic: Required folders for inbound processing

Feedback


Support for protecting sensitive user data in log and trace files

You can configure the adapter to prevent sensitive or confidential data, in the log and trace files, from being viewed by users without authorization.

Log and trace files for the adapter can contain data from your mail server, which might contain sensitive or confidential information. Sometimes these files might be seen by individuals without authorization to view sensitive data. For example, a support specialist must use the log and trace files to troubleshoot a problem.

To protect the data in such situations, the adapter lets you specify whether you want to prevent confidential user data from displaying in the adapter log and trace files. You can select this option in the external service wizard or change the HideConfidentialTrace property. When this property is enabled, the adapter replaces the sensitive data with XXX's.

See Managed connection factory properties for information about this optional property.

The following types of information are considered potentially sensitive data and are disguised:

The following types of information are not considered user data and are not hidden:


Feedback


Configure Secure Socket Layers

Data that travels across a network can be intercepted by third parties. When this data includes private information such as passwords or credit card numbers, steps must be taken to make this data unintelligible to unauthorized users. Using SSL, you protect the integrity of information passed between the mail server and the adapter.

To enable SSL, the following prerequisites must be satisfied:

E-mails passing through the mail server are vulnerable to third-party interference when SSL is not configured for use with the adapter. Using SSL prohibits data from being modified either intentionally or unintentionally during transport and protects data from being intercepted. It is effective because it uses several cryptographic processes, such as public key cryptography for authentication with the mail server and secret key cryptography and digital signatures for privacy and data integrity. SSL allows the adapter to authenticate the identity of the mail server and, when necessary, for the mail server to authenticate the identity of the mail client.

  1. Set the email client truststore. A truststore helps an email client decide what it can trust. When SSL is configured, IBM Business Process Manager or WebSphere Enterprise Service Bus sends its certificate to the email client for verification. The email client verifies the certificate to ascertain that it is communicating with the intended mail server. To enable this verification process, the certificate of the mail server must be present in the client's truststore. Use the following steps to set up the email client truststore.

    1. In IBM Integration Designer, right-click the server and click Run administrative console.

    2. Expand Security.

    3. Select SSL certificate and key management.

    4. Under Related items, select Key stores and certificates.

    5. Select NodeDefaultTrustStore.

      Figure 1. Selecting NodeDefaultTrustStore

    6. Under Additional properties, select Signer certificates.

    7. Click Add.

    8. In the Alias field, type the certificate name.

      Figure 2. Adding signer certificate properties for the mail server certificate

    9. In the File name field, type the full path of the mail server certificate.

    10. Click OK.

  2. Configure SSL properties for the adapter.

    1. In the external service wizard, set enableSSL to True. By default, enableSSL is set to False.
    2. When using SSL for inbound communication, set the port number to 993 if you are using the IMAP email protocol and 995 if you are using the POP3 email protocol. For outbound communication using the SMTP email protocol, set the port number to 465.


Feedback


Configure the module for federal information processing standard 140

The Federal Information Processing Standard 140 (FIPS) is a United States government standard for cryptographic features like encryption, decryption, hashing (message digests), Secure Sockets Layer, Transport Layer Security, Internet Protocol security, Secure Shell, signatures, key exchange, and key or certificate generation used in software products and modules. For users working with the United States government who must conform to the FIPS standard, the adapter can be configured to run in FIPS mode.

Configure the module to run in FIPS mode restricts the adapter to working with modules whose cryptographic features comply with FIPS approved methods and providers. From an adapter perspective, running in FIPS mode restricts the adapter to using the Transport Layer Security (TLS) security protocol based on SSL.

Restriction: WebSphere Adapter for Email cannot connect to Microsoft Exchange Server 2003 when FIPS (SSL 3.1 and TLS 1.0) is configured for inbound communication. The adapter generates exceptions during startup. Currently there are no known workaround to configure WebSphere Adapter for Email for use with Microsoft Exchange Server 2003 in the FIPS mode. Version 7.5.0.3 of the adapter was tested with SurgeMail 3.8 for FIPS.

To run the adapter in FIPS mode, you must instruct the adapter to use the IBM Java™ Secure Socket Extension (IBMJSSE2) provider package. The IBMJSSE2 provider is the preregistered Java Secure Socket Extension provider in the java.security file in IBM SDK, version 5.0. IBMJSSE2 uses FIPS-approved packages.

When in FIPS 140-2 mode, IBM WebSphere Adapter for Email uses the FIPS 140-2 approved cryptographic provider(s); IBMJCEFIPS (certificate 376) and IBMJSSEFIPS (certificate 409). The certificates are listed in the NIST website at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2011.htm

To run the adapter in FIPS mode.

  1. In the IBMJSSE2 provider, set the com.ibm.jsse2JSSEFIPS property to True.

  2. Set the following security properties so the IBMJSSE2 provider can handle all JSSE requests.

    1. Set the ssl.SocketFactory.provider property to com.ibm.jsse2SSLSocketFactoryImpl.

    2. Set the ssl.ServerSocketFactory.provider property to com.ibm.jsse2SSLServerSocketFactoryImpl.

  3. In the java.security properties file, add the IBMJCEFIPS provider com.ibm.crypto.fips.provider.IBMJCEFIPS to the provider list above the IBMJCE provider. Follow the security.provider.n=providername format where n denotes the order of the provider. The provider with a value of 1 is considered before the provider with a value of 2. Do not remove the IBMJCE provider.

  4. From the BPM or WebSphere Enterprise Service Bus administrative console, set the system properties which are listed under the Java virtual machine (JVM) properties. Follow the -Dpropertyname=propertyvalue format.

  5. Set security properties in the java.security file (in the BPM or WebSphere Enterprise Service Bus Java virtual machine/lib/security directory).


Feedback


Required folders for inbound processing

Several folders are required for activities such as archiving and storage before you run the adapter for inbound processing.


Required folders for inbound communication

Before running the adapter, create one or more poll folders on your mail server and a staging folder where the adapter saves all polled emails as files. These folders are required and neither type are created by the adapter. Also, to use the archiving functionality of the adapter to store successfully processed and failed email events create an archive folder and a failed event folder.

The adapter requires there be a folder on the local drive that holds emails marked in progress in the event store. This folder is called the staging directory in the external service wizard. Because the adapter does not create a staging directory, create it before starting the external service wizard.


Required folders for archiving

You can configure the adapter to save, or archive copies, of both successful and failed emails by using the ArchiveFolder property. To use this property, create both of the following folders before you run the adapter.

When the ArchiveFolder property is specified, all successfully processed mail is moved into the archive folder from the staging folder. If you leave this property blank all successfully processed mail is deleted from the staging folder.

If the FailedEventsFolder property is specified, all unsuccessfully processed mail is moved into the failed events folder from the staging folder. If you leave this property blank, all failed mail is deleted from the staging folder.

For more information about either of these folder properties, see the section on activation specification properties in the reference section of this documentation.


Use WAS environment variables

Instead of specifying the folder names when you run the external service wizard, you can use WebSphere Application Server environment variables. Refer more information about environment variables at: WAS environment variables.



Previous topic: Security


Next topic: User authentication


Related tasks:

Defining WAS environment variables


Related reference:

Managed connection factory properties

Activation specification properties

Feedback


User authentication

The adapter supports several methods for supplying the user name and password needed to connect to the mail server. By understanding the features and limitations of each method, you can pick a method that provides the appropriate level of security and convenience for your application.

To integrate an adapter into your application, you must provide the user name and password for the adapter to use at run time on IBM Business Process Manager or WebSphere Enterprise Service Bus to connect to mail server to process outbound requests and inbound events.

At run time, the adapter needs to provide the user name and password to connect to the mail server. To connect without user intervention, the adapter must access a saved copy of the user information. In a server environment, there are several methods for saving user information. You can configure the adapter to get your user information, through any of the following methods:

Saving the user name and password in adapter properties is a direct way to provide this information at run time. You provide this user name and password when use the external service wizard to configure your module. Although directly specifying the user name and password seems the most straightforward method, it has important limitations. Adapter properties are not encrypted; the password is stored as clear text in fields that are accessible to others on the server. Also, when the password changes, update the password in all instances of the adapter that access that mail server. This includes the adapters embedded in application EAR files and adapters that are separately installed on the server.

Use a data source allows you to use a connection already established for another application. For example, if multiple applications access the same database with the same user name and password, the applications can be deployed using the same data source. The user name and password can be known only to the first person who deploys an application to that data source or who defines a data source separately.

Use a J2C authentication data entry, or authentication alias, created with the Java™ Authentication and Authorization Service (JAAS) feature of Java EE security is a robust, secure way to deploy applications. An administrator creates the authentication alias used by one or more applications that need to access a system. The user name and password must be known only to that administrator, who can change the password in a single place, when a change is required.



Previous topic: Required folders for inbound processing


Next topic: Deployment options


Related tasks:

Create an authentication alias

Feedback


Deployment options

There are two ways to deploy the adapter. You can either embed it as part of the deployed application, or you can deploy it as a stand-alone RAR file. The requirements of the environment affect the type of deployment option you choose.

The following are the deployment options:

An embedded adapter is bundled within an enterprise archive (EAR) file and is available only to the application with which it is packaged and deployed.

A stand-alone adapter is represented by a stand-alone resource adapter archive (RAR) file, and when deployed, it is available to all deployed applications in the server instance.

While creating the project for your application using IBM Integration Designer, you can choose how to package the adapter [either bundled with the (EAR) file or as a stand-alone (RAR) file]. Your choice affects how the adapter is used in the run time environment and how the properties for the adapter are displayed on the administrative console.

Choosing either to embed an adapter with your application or to deploy the adapter as a stand-alone module depends on how you want to administer the adapter. For a single copy of the adapter and do not care about disruption to multiple applications when you upgrade the adapter, then you would be more likely to deploy the adapter as a stand-alone module.

If you plan to run multiple versions, and if you care more about potential disruption when you upgrade the adapter, you would be more likely to embed the adapter with the application. Embedding the adapter with the application allows you to associate an adapter version with an application version and administer it as a single module.


Considerations for embedding an adapter in the application

Consider the following items if you plan to embed the adapter with your application:


Considerations for using a stand-alone adapter

Consider the following items if you plan to use a stand-alone adapter:


Considerations while deploying adapters with different versions

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for Email version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for Email" as IBM WebSphere Adapter for Email loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. To overcome this conflict, you must migrate all adapters to the same version level.

There are occasions when you work with embedded adapters that do not need a client-server communication, stand-alone adapters that need a server connection, or a hybrid mix of adapter connections.

The following scenarios cover the different behaviors of AFC version conflict detection, when you are deploying two or more adapters and at least one of the adapter version is 7.5 or higher.

Deploy a stand-alone Adapter

  1. Install WebSphere Adapter for Flat Files version 7.0.1.0 through the BPM administrative console.
  2. Install WebSphere Adapter for SAP Software version 7.5.0.0 through the administrative console.

  3. Create ActivationSpec for an ALE pass-through inbound operation.

  4. Create an application in IBM Integration Designer for a stand-alone ALE pass-through inbound operation.
  5. Install and start the application through the administrative console.

  6. Verify the error.

An error message is generated in the log/trace area of IBM Business Process Manager, to indicate an AFC version conflict. Deploy an embedded Adapter

  1. Import a build of WebSphere Adapter for FTP version 7.0.1.0, using a RAR file.

  2. Create a FTP Inbound EMD operation.
  3. Import a build of WebSphere Adapter for Oracle E-Business Suite version 7.5.0.0, using a RAR file.

  4. Create an Oracle inbound EMD operation, in the same module where you have created the FTP Inbound EMD operation.
  5. Deploy the module to IBM Business Process Manager.
  6. Check the trace.

At step 5, the deployment fails. At step 6, you get an internal error message due to the AFC version conflict.

To avoid a name conflict between the business object generated by the two adapters, generate the artifacts into different folders.

Deploy a combination of stand-alone and embedded Adapters

  1. Install WebSphere Adapter for JDBC version 7.0.1.0 through theIBM Business Process Manager administrative console.

  2. Create an ActivationSpec for a JDBC inbound operation.

  3. Create an application in IBM Integration Designer for a JDBC inbound operation, for the stand-alone Adapter deployment.
  4. Deploy the JDBC inbound application and trigger your inbound events.

  5. Create an application in IBM Integration Designer for a WebSphere Adapter for SAP Software version 7.5.0.0 inbound embedded Adapter deployment.
  6. Deploy an SAP inbound application, and trigger your inbound events.

You can resolve the AFC version conflict by using different class loaders for the stand-alone and embedded deployments. With this approach, the migration process handles different CWYBS_AdapterFoundation.jar files and do not conflict with each other. You can start both JDBC and SAP inbound applications successfully, and process Inbound events without exception.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.



Previous topic: User authentication


Next topic: WebSphere Adapters in clustered environments

Feedback


WebSphere Adapters in clustered environments

You can improve adapter performance and availability by deploying a module on a clustered server environment. Clusters are groups of servers that are managed together to balance workloads and to provide high availability and scalability.

The module you deployed is replicated across all servers in a cluster, regardless of whether you deploy the module using a stand-alone or an embedded adapter. The following IBM products support WebSphere Adapters in a clustered environment:

To deploy and configure WebSphere Adapter for Email in a clustered environment, see: Deploy the module in a clustered environment. When you set up a server cluster, you create a Deployment Manager profile. The HAManager, a subcomponent of the Deployment Manager, notifies the Java™ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container to activate an adapter instance. For information about creating clustered environments, see the following link: http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.imuc.z.doc/topics/tins_zos_create_cluster.html.

Use WebSphere Extended Deployment, you can optionally enhance the performance of adapter instances in your clustered environment. WebSphere Extended Deployment extends the WAS ND capabilities by using a dynamic Workload Manager instance instead of a static Workload Manager. The dynamic Workload Manager instance can optimize the performance of adapter instances in the cluster by dynamically balancing the load of the requests. It means that application server instances can be automatically stopped and started based on the load variations, allowing systems with different capacities and configurations to handle load variations evenly. For information about the benefits of WebSphere Extended Deployment, see http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp.

In clustered environments, adapter instances can handle both inbound and outbound processes.

Restriction: During inbound communication WebSphere Adapter for Email is not able to switch polling between a IBM Business Process Manager or WebSphere Enterprise Service Bus cluster backup node and the cluster's primary node when each node is installed on a different operating system. For example, if the adapter starts polling on a primary Windows node, it cannot switch to a backup UNIX node because it cannot process the Windows path used for the directory storing in progress events.


High availability for inbound processes

Inbound processes are based on events triggered as a result of updates to data in the mail server. WebSphere Adapter for Email is configured to detect updates by polling an event table. The adapter then publishes the event to its endpoint.

In a clustered environment, the event directory must be on a shared file system and not local to any of the cluster machines.

When you deploy a module to a cluster, the Java Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container checks the enableHASupport resource adapter property. If the value for the enableHASupport property is true, which is the default setting, all of the adapter instances are registered with the HAManager with a policy 1 of N. This policy means that only one of the adapter instances starts polling for events. Although other adapter instances in the cluster are started, they remain dormant with respect to the active event until the active adapter instance finishes processing the event. If the server on which the polling thread was started shuts down for some reason, an adapter instance running on one of the backup servers is activated.

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events/messages even if the enableHASupport property is set to True. This is because the alwaysactivateAllMDBs property in the JMS activation specification is set to True. To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. See Disable end point applications of the passive adapter .

Do not change the setting of the enableHASupport property.


High availability for outbound processes

In clustered environments, multiple adapter instances are available to perform outbound process requests. So, if the environment has multiple applications that interact with WebSphere Adapter for Email for outbound requests, then you might improve performance by deploying the module to a clustered environment. In a clustered environment, multiple outbound requests can be processed simultaneously, so they are not attempting to process the same record.

If multiple outbound requests are attempting to process the same record, such as a Customer address, the workload management capability in WAS Network Deployment distributes the requests among the available adapter instances in the sequence they were received. As a result, these types of outbound requests in a clustered environment are processed in the same manner as in a single server environment: one adapter instance processes only one outbound request at a time. For more information about workload management, see the following link: http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html.



Previous topic: Deployment options


Next topic: Migrate to version 7.5.0.3 of WebSphere Adapter for Email

Feedback


Migrate to version 7.5.0.3 of WebSphere Adapter for Email

By migrating to version 7.5.0.3 of WebSphere Adapter for Email, you automatically upgrade from the previous version of the adapter. Additionally, you can migrate applications that embed an earlier version of the adapter, so the applications can use features and capabilities present in version 7.5.0.3.



Previous topic: WebSphere Adapters in clustered environments


Next topic: Migrate WebSphere Business Integration applications

Feedback


Migration considerations

WebSphere Adapter for Email version 7.5.0.3 may have some features and updates that might affect your existing adapter applications. Before migrating applications that use WebSphere Adapter for Email, you must consider some factors that might affect your existing applications.


Compatibility with earlier versions

WebSphere Adapter for Email version 7.5.0.3 is fully compatible with the custom business objects (XSD files) and data bindings that are created using the adapter version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 and enables the existing business objects and data bindings to work well in the latest version of the adapter.

Because version 7.5.0.3 of WebSphere Adapter for Email is fully compatible with version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2, any of applications that used previous versions of WebSphere Adapter for Email run unchanged when you upgrade to version 7.5.0.3. However, if you want applications to use features and functionality present in version 7.5.0.3 of the adapter, perform the migration of the artifacts as well as the upgrade of the adapter.

The migration wizard replaces (upgrades) version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 of the adapter with version 7.5.0.3 and enables version 7.5.0.3 features and functionality for use with applications.

The migration wizard does not create components or modify existing components, such as mappers and mediators to work with version 7.5.0.3 of the adapters. If any of applications embed an adapter that is version 7.5.0.2 or earlier and you are upgrading to version 7.5.0.3, and you want applications to take advantage of the features and functions in version 7.5.0.3, you might need to change those applications.

If the artifacts within a module have inconsistent versions, the entire module is marked as unavailable for migration and cannot be selected. Version inconsistencies are recorded in the workspace log, as they indicate that a project might be corrupted.

The adapter migration wizard in IBM Integration Designer Version 7.5.1 only supports the migration of adapters from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 to version 7.5.0.3. It does not support the adapter migration from lower versions to any of the versions before version 7.5.0.3.


Decide whether to upgrade or to upgrade and migrate

The default processing of the migration wizard is to perform an upgrade of the adapter and to migrate the application artifacts so the applications can use features and functions in version 7.5.0.3 of the adapter. When you choose to upgrade the adapter by selecting a project, the wizard automatically selects the associated artifacts for migration.

If you decide to upgrade the adapter from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 to version 7.5.0.3, but you do not want to migrate the adapter artifacts, you can do so by clearing the adapter artifacts from the appropriate area of the migration wizard.

Run the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.


Migrate multiple adapters referred within a project

When a module contains one or more connector projects, each of which references to different adapters ( a module project that contains connector projects referring to JDBC and SAP adapters), the migration wizard identifies the artifacts belonging to each adapter and migrates these artifacts without disrupting the artifacts of other adapters.

When you select the module project and launch the migration wizard:

If you select the connector project and launch the migration wizard:


Run the migration wizard in a test environment

Because adapter migration might require you to change those applications that use version 7.5.0.3 of WebSphere Adapter for Email, always perform the migration in a development environment first and test applications before deploying the application to a production environment.

The migration wizard is fully integrated with the development environment.


Fault processing when migrating to version 7.0

Fault processing in version 7.0 depends upon the type of fault configuration done in the previous version. If the user manually configures business faults in version 6.2 then the faults are automatically configured in version 7.5.0.3. In case no fault is configured in version 6.2, then the user needs to manually configure the faults after migrating to version 7.5.0.3, as per the steps described in the following section.


Feedback


Performing the migration

You can migrate a project or EAR file to version 7.5.0.3 using the adapter migration wizard. When the tool is finished, the migration is complete and you can work in the project or deploy the module.

Review the information in Migration considerations. To perform the migration in IBM Integration Designer.

After migration is complete, the module is no longer compatible with previous versions of the BPM or WebSphere Enterprise Service Bus runtimes or IBM Integration Designer.

The following steps describe how to run the adapter migration wizard from the connector project menu while in the Java™ EE perspective in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.

    Ensure that you do not modify the contents of the RAR or copy the adapter JAR file outside the connector project.

  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Java EE perspective.
  4. Right-click the module and select Migrate connector project. For example, the adapter RAR module.

    You can also launch the adapter migration wizard in the following ways:

    • Right-click the project in the Java EE perspective and select Migrate adapter artifacts.

    • From the Problems view, right-click a migration-specific message and select Quick Fix to correct the problem.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. If you are migrating a module project, this field lists all the connector projects in the module project. Select the source project from the list. See Migrate multiple adapters referred within a project.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector you want to migrate.
    3. The Target version field displays the version corresponding to the target connector that you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated. If you are migrating a module project, this area lists only the selected module project. If you are migrating a connector project within the module project, this area lists all projects which reference the selected connector project, including the module project. By default, all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated. You can migrate any project that you have not selected at a later time. Previously migrated projects, projects with a current version, and projects that contain errors are unavailable for migration and are not selected. See Upgrading but not migrating a project.

    5. Click Next. A warning window is displayed with the message, “Properties that are not supported in this version of the target adapter will be removed during the migration”.

    6. Click OK.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before running the migration process, the wizard performs a backup of all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

    Upon completing the migration successfully, all backed up projects are deleted.

  8. If you are migrating an EAR file, optionally create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For more information about exporting and deploying an EAR file, sees devoted to it in this documentation.

The project or EAR file is migrated to version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.


Feedback


Upgrading but not migrating a project

You can upgrade the adapter from an earlier version, to version 7.5.0.3 while choosing not to migrate the adapter project artifacts. Running the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.

  1. Import the PI (project interchange) file into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

  3. In the Java™ EE perspective, right-click the project name and click Migrate connector project. The Adapter Migration wizard is displayed.

  4. In the Select Projects window, clear the dependent artifact projects, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter will be removed during the migration.”

  5. Click OK.

  6. In the Review Changes window, review the migration changes that occur during updating the project. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

The project can now be used with WebSphere Adapter for Email, version 7.5.0.3.



Related tasks:

Export the module as an EAR file

Install the EAR file

Feedback


Migrate WebSphere Business Integration applications

You need to migrate the WebSphere Business Integration applications so they become compatible with Version 7.5.0.3 of your adapter.

Migrate WebSphere Business Integration applications for use with Version 7.5.0.3 of your WebSphere adapter is a multistep process. First, the artifacts from WebSphere InterChange Server are migrated and converted. A project is then created for the artifacts in IBM Integration Designer. In the remaining steps, the adapter-specific artifacts are migrated and converted into the JCA-compliant format supported by Version 7.5.0.3 of the adapter.


Example

The following diagram shows the wizards that you use to migrate WebSphere Business Integration solutions from WebSphere InterChange Server, so these applications can be used with Version 7.5.0.3 of your adapter.



Previous topic: Migrate to version 7.5.0.3 of WebSphere Adapter for Email

Feedback


Migrate applications from WebSphere InterChange Server

To use Version 7.5.0.3 of WebSphere Adapter for Email with applications from WebSphere InterChange Server, you need to migrate the application artifacts and convert them so they can be deployed and run on IBM Business Process Manager or WebSphere Enterprise Service Bus. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

The following figure illustrates the flow of the migration task. The steps that follow the figure describe this task at a high level only. See the topics following this roadmap for the details on how to perform each of these steps.

Figure 1. Roadmap for migrating applications from WebSphere InterChange Server

Migrate applications from WebSphere InterChange Server

This task consists of the following steps:

  1. Run the WebSphere InterChange Server migration wizard.

    The WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer. The migrated adapter artifacts are not fully JCA-compliant at the completion of this task.

  2. Verify the WebSphere InterChange Server migration is successful.

    Review all messages from the Migration results window and take action if required.

  3. Consider the implications of using Version 7.5.0.3 of WebSphere Adapter for Email.

    In addition to considerations for migrating WebSphere InterChange Server applications, you need to consider how Version 7.5.0.3 of WebSphere Adapter for Email works with the migrated applications. Some of the adapter operations supported by WebSphere InterChange Server applications might be supported and implemented differently with Version 7.5.0.3 of the adapter.

  4. Run the adapter migration wizard.

    Run the adapter migration wizard to update adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl files) for use with Version 7.5.0.3 of the adapter.



Related concepts:

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Migration considerations for WebSphere Business Integration adapters

By migrating to WebSphere Adapter for Email Version 7.5.0.3, you have an adapter that is compliant with the Java™ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) and designed specifically for service-oriented architecture.


Application artifacts

Before running the adapter migration wizard, use the WebSphere InterChange Server migration wizard to generate the application artifacts for the WebSphere Business Integration adapter, including the business objects, maps, and collaborations. Then you can run the adapter migration wizard to update the adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) so they are suitably converted into a format that is compliant with JCA.


Run the migration wizard in a test environment first

Because migrating from a WebSphere Business Integration adapter to WebSphere Adapter for Email might require changes to the applications that use Version 7.5.0.3 of WebSphere Adapter for Email, always perform the migration in a development environment first and test applications before deploying the application to a production environment.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts

Feedback


Migrate application artifacts from WebSphere InterChange Server

To migrate the application artifacts into IBM Integration Designer, run the WebSphere InterChange Server migration wizard. The wizard imports and converts most of the artifacts into a format that is compatible with BPM or WebSphere Enterprise Service Bus.

Launch the WebSphere InterChange Server migration wizard from within IBM Integration Designer to migrate the application artifacts from WebSphere InterChange Server format into artifacts that are compatible with BPM or WebSphere Enterprise Service Bus.

For information about how to prepare to migrate artifacts from WebSphere InterChange Server and for detailed instructions on performing the migration and verifying the migration was successful, see http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/index.jsp?topic=/com.ibm.wbpm.wid.imuc.doc/topics/twics.html. Running WebSphere InterChange Server migration wizard might not fully convert adapter-specific artifacts (such as service descriptors, service definitions, and business objects) into IBM Business Process Manager or WebSphere Enterprise Service Bus compatible artifacts. To complete the migration of adapter-specific artifacts, run the adapter migration wizard after you have successfully run the WebSphere InterChange Server migration wizard.

While you run the WebSphere InterChange Server migration wizard, ensure set each connector in the repository to the same adapter version.

The project and application artifacts are migrated and converted into IBM Business Process Manager compatible artifacts.


Run the adapter migration wizard to migrate the adapter-specific artifacts.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Migrate adapter-specific artifacts

After a project is created for the artifacts in IBM Integration Designer, you can migrate the project using the adapter migration wizard. The adapter migration wizard updates adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) for use with version 7.5.0.3 of the adapter. When you finish running the adapter migration wizard, the migration is complete and you can work in the project or deploy the module.

Before running the adapter migration wizard, do the following steps:

After migration is complete, the module will work only with Version 7.5.0.3 of your adapter.

To perform the migration in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Java™ EE perspective.
  4. Right-click the connector project and select Migrate connector project.

    You can also launch the adapter migration wizard by using the right-click option and selecting the module project in the Java EE perspective and selecting Migrate adapter artifacts.

    If the adapter type ( CICS/IMS adapter) is not supported by the migration wizard, the Migrate connector project and Migrate adapter artifacts menus are not available for selection. If the adapter project is of the latest version and the module projects referencing this adapter project are also of the latest version, these menus are disabled. When you launch the migration wizard from the connector project while in the Java EE perspective, by default all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. Select the source project from the list.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector to which you want to migrate.
    3. The Target version field displays the version corresponding to the target connector you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated.
    5. Review the tasks and warnings presented on the welcome page, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter are removed during the migration.”

    6. Click OK.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before performing the migration process, the wizard backs up all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

  8. Select Project > Clean, to refresh and rebuild the workspace for the changes to take effect.

    The inProgressFolder property in WebSphere Adapter for Email does not have an equivalent property in WebSphere Business Integration Adapter for e-Mail. Set the value for the inProgressFolder property manually after running the migration wizard.

  9. On successful migration, all backed up projects are deleted. Remove the Sync inbound flow manually as this flow is not used by the adapter. From the migrated project, select the Input_Sync inbound flow, right-click, and select Delete.

  10. If you are migrating an EAR file, create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For information about exporting and deploying an EAR file, see Deploy the module for production.

The project is migrated to Version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Changes to the import, export, and WSDL files after migration

When the WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer, changes made are reflected in the service definition files: the import, export, and WSDL files.

The migrated adapter artifacts are not fully JCA-compliant at the completion of this task. You can complete the migration of the adapter-specific artifacts (such as service descriptors, service definitions, and business objects) to a JCA compatible format by running the adapter migration wizard.


Changes to the import file

During migration, the affected module artifacts are migrated to an import file. The existing JMS Binding property is changed to the EIS Binding property in the import file. The other property details added in the import file include information about the data binding configuration, changes to the connection information in the Managed Connection Factory properties, and several new method bindings.


Changes to the export file

During migration, the affected module artifacts are migrated to an export file. The existing JMS Binding property is changed to the EIS Binding property in the export file. The other property details added in the export file include information about the data binding configuration, changes to the connection information in the Activation Specification properties, and several new method bindings.


Changes to the WSDL file after migration

During migration, the affected module artifacts are migrated to corresponding WSDL files that include EMail specific service description WSDL artifacts. The service description files become JCA compatible. The WSDL files have an input and output type for each operation. Both the inbound and outbound operations work on their specific input types to produce corresponding output types after the operations are performed.



Related concepts:

Migrate applications from WebSphere InterChange Server


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Samples and tutorials

To help you use WebSphere Adapters, samples and tutorials are available from the Business Process Management Samples and Tutorials website.

You can access the samples and tutorials in either of the following ways:


Feedback


Configure the module for deployment

To configure the adapter so that it can be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use IBM Integration Designer to create a module, which is exported as an EAR file when you deploy the adapter. You then specify the business objects you want to build and the system on which you want to build them.

  1. Roadmap for configuring the module Before you can use WebSphere Adapter for Email in a runtime environment, configure the module. Understanding this task at a high level helps you perform the steps needed to accomplish the task.
  2. Configure the mail server to work with the adapter Before working with the adapter, install and configure a mail server according to its user manual. The information about how to connect to the mail server (such as user names, passwords, and port) is required by the external service wizard in IBM Integration Designer when you create your adapter module.
  3. Create an authentication alias An authentication alias is a feature that encrypts the passwords used by the adapter to access the mail server. You can gain a greater level of security by using an authentication alias to configure the adapter, instead of typing the user ID and password directly.
  4. Create the module A module encapsulates the service in a reusable unit and consists of both a project in IBM Integration Designer and a unit of deployment to IBM Business Process Manager or WebSphere Enterprise Service Bus. The module is packaged and deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus as an enterprise archive (EAR) file.
  5. Defining WAS environment variables Use the administrative console of IBM Business Process Manager or WebSphere Enterprise Service Bus to define WAS environment variables.
  6. Defining business objects Create business objects or import predefined business objects that is to be used by the module. WebSphere Adapter for Email uses business objects to either obtain information from an email or to produce an email.
  7. Create a simple service with the adapter pattern wizard Adapter patterns provide a quick and easy way of creating a simple service with an adapter.
  8. Start the external service wizard To begin the process of creating and deploying a module, you start the external service wizard in IBM Integration Designer. The wizard creates a project used to organize the files associated with the module.
  9. Configure the module for outbound processing To configure a module to use the adapter for outbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate the business object definitions and related artifacts.
  10. Configure the module for inbound processing To configure a module to use the adapter for inbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.



Previous topic: Plan for adapter implementation


Next topic: Deploy the module for production

Feedback


Roadmap for configuring the module

Before you can use WebSphere Adapter for Email in a runtime environment, configure the module. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

You configure the module for WebSphere Adapter for Email by using IBM Integration Designer. The following figure illustrates the flow of the configuration task, and the steps that follow the figure describe this task at a high level only. For details about how to perform each of these steps, sees following this roadmap.

Figure 1. Roadmap for configuring the module

Configure the module

This task consists of the following steps.

These steps assume that you are using user-defined business objects that require data transformation. If you are using generic business objects, which do not require data transformation, some of the following steps are ignored. For example, you do not need to select a data binding and a data handler.

  1. Create an authentication alias to access the mail server. Perform this step using the administrative console.

  2. Create a module in IBM Integration Designer.

    You create business objects in the module.

  3. Define the business objects to be used by the project.

  4. Create a project, which is used to organize the files associated with the adapter by using the external service wizard in IBM Integration Designer.
  5. Build business services by running the external service wizard from IBM Integration Designer, then perform the following steps:

    1. Set the following deployment and runtime properties:

      • Connection properties
      • Security properties
      • Deployment options
      • Function selector - Inbound only

    2. Select a data type and name the operation associated with this data type. For each operation, specify the following information:

      • The operation kind, for example, Create, Append, Exists.

      • Specify whether the operation is pass-through or user defined.

    3. Select the data binding. Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file.

    4. Select the data handler that is going to perform the conversions between a business object and a native format.

    5. Specify interaction specification property values and generate artifacts. The output from running the external service wizard is saved to a business integration module, which contains the business object or objects, and the import or export file.



Next topic: Configure the mail server to work with the adapter

Feedback


Configure the mail server to work with the adapter

Before working with the adapter, install and configure a mail server according to its user manual. The information about how to connect to the mail server (such as user names, passwords, and port) is required by the external service wizard in IBM Integration Designer when you create your adapter module.



Previous topic: Roadmap for configuring the module


Next topic: Create an authentication alias

Feedback


Create an authentication alias

An authentication alias is a feature that encrypts the passwords used by the adapter to access the mail server. You can gain a greater level of security by using an authentication alias to configure the adapter, instead of typing the user ID and password directly.

To create an authentication alias, you must have access to the BPM or WebSphere Enterprise Service Bus administrative console.

Use the authentication alias is the default choice in the external service wizard.

The following procedure shows you how to gain access to the administrative console through IBM Integration Designer. If you are using the administrative console directly (without going through IBM Integration Designer), log in to the administrative console and skip to step 2

Use an authentication alias eliminates the need to store the password in clear text in an adapter configuration property, where it might be visible to others.

To create an authentication alias, use the following procedure.

  1. Start the administrative console.

    To start the administrative console through IBM Integration Designer.

    1. In the Business Integration perspective of IBM Integration Designer, click the Servers tab.

    2. If the server does not show a status of Started, right-click the name of the server ( WebSphere Process Server) and click Start.
    3. Right-click the name of the server and select Administration > Run administrative console.
    4. Log on to the administrative console. If your administrative console requires a user ID and password, type the ID and password and click Log in. If the user ID and password are not required, click Log in.

  2. In the administrative console, click Security > Secure administration, applications, and infrastructure.

  3. Under Authentication, click Java Authentication and Authorization Service > J2C authentication data.

  4. Create an authentication alias:

    1. In the list of J2C authentication aliases that is displayed, click New.

    2. In the Configuration tab, type the name of the authentication alias in the Alias field.

    3. User ID and password required to establish a connection to the mail server.

    4. Optionally type a description of the alias.

    5. Click OK.

      The newly created alias is displayed.

      The full name of the alias contains the node name and the authentication alias name you specified. For example, if you create an alias on the node widNode with the name ProductionServerAlias, then the full name is widNode/ProductionServerAlias. This full name is the one you use in subsequent configuration windows.

    6. Click Save.

You created an authentication alias, which you can use when you configure the adapter properties.



Previous topic: Configure the mail server to work with the adapter


Next topic: Create the module


Related concepts:

User authentication

Feedback


Create the module

A module encapsulates the service in a reusable unit and consists of both a project in IBM Integration Designer and a unit of deployment to IBM Business Process Manager or WebSphere Enterprise Service Bus. The module is packaged and deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus as an enterprise archive (EAR) file.

  1. If IBM Integration Designer is not currently running, start it now.

    1. Click Start > Programs > IBM > IBM Integration Designer > IBM Integration Designer version, where version is the version of the IBM Integration Designer.

    2. If you are prompted to specify a workspace, either accept the default value or select another workspace.

      The workspace is a directory where IBM Integration Designer stores your project.

    3. Optional: When the IBM Integration Designer window is displayed, click Go to the Business Integration perspective.

  2. Right-click in the Business Integration section of the IBM Integration Designer window.

    Figure 1. Business Integration section of the window

  3. In the New Module window, type a name for the module in the Module Name field. For example, to configure a module for outbound processing, type Outbound as the module name. Click Finish.

A new module is listed in the Business Integration window.


Define business objects for the module.



Previous topic: Create an authentication alias


Next topic: Defining WAS environment variables

Feedback


Defining WAS environment variables

Use the administrative console of IBM Business Process Manager or WebSphere Enterprise Service Bus to define WAS environment variables.

To define a WAS environment variable, use the following procedure:

  1. Start the administrative console.

  2. Select Environment > WebSphere Variables.

  3. Select the scope for the environment variable. The scope specifies the level at which the resource definition is visible on the administrative console panel. The possible values are server, node, and cell. In the following figure, the scope is defined at the cell level as Cell=Dmgr1Cell.

    Figure 1. Setting the scope for the environment variable

  4. Click New and provide a name and a value for the environment variable. The name is the symbolic name that represents a physical path. The value is the absolute path the variable represents. In this example, the name is ARCHIVE_FOLDER and the value is C:/email/ArchiveFolder. You can use the Description field, which is optional, to describe the purpose of the variable.

    Figure 2. Providing a name and a value for the environment variable

  5. Click OK to save the changes.

An environment variable called ARCHIVE_FOLDER is defined, with the value C:/email/ArchiveFolder and a scope of Cell=Dmgr1Cell. You can use it in the external service wizard whenever you specify the event directory.

Figure 3. The new environment variable ARCHIVE_FOLDER displayed in the WebSphere Variables window


Define business objects for the module.



Previous topic: Create the module


Next topic: Defining business objects


Related concepts:

WAS environment variables

Required folders for inbound processing


Related reference:

Managed connection factory properties

Activation specification properties

Feedback


Defining business objects

Create business objects or import predefined business objects that is to be used by the module. WebSphere Adapter for Email uses business objects to either obtain information from an email or to produce an email.

You use the business object editor to create new business objects or import predefined business objects.

These steps must only be used for payload business objects (such as Customer and Order) and not for top-level email business objects (wrappers). Wrapper business objects are created by the external service wizard.

The new business objects are defined.


Create a project, which is used to organize the files associated with the adapter.



Previous topic: Defining WAS environment variables


Next topic: Create a simple service with the adapter pattern wizard


Related concepts:

Business objects


Related reference:

Business object information

Feedback


Create a simple service with the adapter pattern wizard

Adapter patterns provide a quick and easy way of creating a simple service with an adapter.

To use the WebSphere Adapter for Email pattern wizard, create a module for the service. The following adapter pattern is available for WebSphere Adapter for Email:

Adapter pattern

Adapter pattern Description
Simple outbound email pattern The "create an outbound Email service to send mail" pattern creates a service that sends simple email messages using a mail server.

In this example, create an outbound service that creates simple alert emails and send them to a mail server for distribution.

To create this service with the adapter pattern wizard.

  1. Right-click the module within the Business Integration section of the IBM Integration Designer window and select New > External Service. The Select the Service Type or Registry window opens.

  2. Select Simple: Create an outbound e-mail service to send mail and click Next.

    Figure 1. Select the Service Type or Registry window

  3. In the E-mail service name window, change the name to something meaningful such as EmailOutboundInterface and click Next.

    Figure 2. E-mail service name window

  4. In the E-mail Server window, specify both the E-mail server host name and the Port fields. For example, connecting to local host on port 25. Click Next.

  5. In the E-mail server security credential window, select either No security, Using an existing JAAS alias or Using user name and password and click Next.

    Figure 3. E-mail server security credential window

The outbound service is created, which includes the following artifacts:

Artifacts for the outbound service

Artifact Name Description
Import EmailOutboundInterface The import exposes the module internally, in this case, to the mail server.
Interface EmailOutboundInterface This interface contains the operation that can be started.
Operation createEmail createEmail is the only operation in the interface.



Previous topic: Defining business objects


Next topic: Start the external service wizard

Feedback


Start the external service wizard

To begin the process of creating and deploying a module, you start the external service wizard in IBM Integration Designer. The wizard creates a project used to organize the files associated with the module.

Make sure that you gather the information to establish a connection to the mail server. For example, you need the name or IP address of the mail server and the user ID and password to access it.

Start the external service wizard to create a project for the adapter in IBM Integration Designer. If you have an existing project, you can select it instead of having the wizard create one.

To start the external service wizard and create a project, use the following procedure.

  1. To start the external service wizard, go to the Business Integration perspective of IBM Integration Designer, and then click File > New > External Service.

  2. In the External service window, expand Adapters and select Email, which is the type of adapter you want to create. Then click Next.

  3. In the Select an Adapter window, select the adapter name to create a project, or select an existing project to reuse it.

    • To create a project.

      1. Select IBM WebSphere Adapter for Email (IBM : version), where version is the version of the adapter you want to use and click Next.

      2. In the Adapter Import window, provide details about the project you want to create.

        1. In the Connector project field, optionally specify a different name for the project.

        2. In the Target runtime field, select the server ( IBM Business Process Manager).

        3. Click Next.

    • To select an existing project, select the project folder under IBM WebSphere Adapter for Email (IBM : version), where version is the version of the adapter you want to use and click Next.

For a new project, the project is created and is listed in the Business Integration perspective. The wizard creates the adapter artifacts in the specified project.



Previous topic: Create a simple service with the adapter pattern wizard


Next topic: Configure the module for outbound processing

Feedback


Configure the module for outbound processing

To configure a module to use the adapter for outbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate the business object definitions and related artifacts.

  1. Configure the module using the simple email data type To configure a module for outbound processing using the simple email data type, use the external service wizard in IBM Integration Designer to build business services and generate business object definitions and related artifacts.
  2. Configure the module using the generic email data type To configure a module for outbound processing using the generic email data type, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.
  3. Configure the module using the user-defined data type To configure a module for outbound processing using the user-defined data type, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.



Previous topic: Start the external service wizard


Next topic: Configure the module for inbound processing

Feedback


Configure the module using the simple email data type

To configure a module for outbound processing using the simple email data type, use the external service wizard in IBM Integration Designer to build business services and generate business object definitions and related artifacts.



Next topic: Configure the module using the generic email data type


Related concepts:

Outbound processing


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Feedback


Set deployment and runtime properties for simple email data type

To select and configure your module for outbound or inbound communication with the mail server, you specify the configuration properties using the external service wizard in IBM Integration Designer. Then, configure the managed connection factory properties. Managed connection factory properties are stored in the business object and contain the information the adapter needs to make the connection between the outbound module and the mail server.

To perform this task, create a module. The module name is displayed in the Project Explorer view of IBM Integration Designer.

To set connection properties, follow this procedure. See Managed connection factory properties.

  1. In the Select the Processing Direction window, select Outbound and click Next.

    Figure 1. Choosing inbound or outbound in the external service wizard

    The Set the Security and Configuration Properties window is displayed.

  2. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  3. Under the E-mail system connection information, type the Host name. The properties in this window correspond to the managed connection factory properties. For detailed information about these properties, see Managed connection factory properties.

    Figure 2. Security and configuration properties window

  4. Type the Port number. The default value for the SMTP protocol is 25. If your SMTP mail server is listening on a different port number, change this value.
  5. Clear the Select when antivirus or firewall software is running check box if you do not want the adapter to close the managed connection after each outbound request. If an antivirus program or firewall is running on your system (the machine on which the adapter is deployed or the one that hosts the mail server) and this check box is cleared, the adapter might fail to send outbound emails. Leaving this check box selected is recommended.

  6. Optional: Click Advanced and expand the Additional properties, Logging and tracing , or Bidi properties sections as needed.

    • Additional properties

      1. Select Enable transport security (SSL) check box to specify if secure socket layers are enabled for outbound communication. See Secure connection (SSL) (enableSSL).

      2. In the Alternate e-mail ID in case of delivery failure field, specify an alternate email address to receive undeliverable mail notifications. This email address can be a different email address than the one you specified in the From email address. For more details about this property, see Alternate email ID in case of delivery failure.

      3. In the Maximum retries in case of system connection failure field, type the number of times the adapter tries the connection before reporting a polling error. See Maximum retries on connection failure (connectionRetryLimit).

      4. In the Connection retry interval (in milliseconds) field, specify the time interval between the attempts to reconnect to the mail server if the connection fails. See Retry interval if connection fails (in milliseconds) entities.

    • Logging and tracing

      1. If you have multiple instances of the adapter, expand Logging and tracing and enter a value in the Adapter ID field that is unique for this instance. For more information about this property, see Resource adapter properties.

      2. To mask certain information so the information is not displayed in the logs or traces, select Disguise user data as "XXX" in log and trace files. See Disguise user data as "XXX" in log and trace files (HideConfidentialTrace).

    • Bidi properties

      1. Select the Bidi transformation check box to specify bidirectional format. For more information about setting the Bidi properties, refer to the Globalization section.

  7. In Service properties, specify how you want the adapter to connect to the mail server by selecting any one of these authentication methods.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and type the name of the alias in the J2C Authentication data entry field. You can either specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the security properties from the managed connection specification, click Using security properties from the managed connection factory and enter the following information:

      • In the User name field, type the user name for the mail server.

      • In the Password field, type the password for the mail server.

        The security properties are not encrypted and stored as plain text. If you are using an authentication alias, a user name and password are not necessary. During outbound communication, you do not need to enter a user name and password because a mail server uses an anonymous user name and password to send the emails.

    • To administer the user name and password from another mechanism, click Other.

  8. Optional: Select the Change logging properties for wizard check box, to define the level of logging for this module.

  9. For Data format, select Specify a data binding for each operation. Although the default value is Use a data binding configuration for all operations, select Specify a data binding for each operation, because the adapter has a different data binding for each supported business object. These data bindings have different properties, and are configured differently.

    Do not click Next in this window until you complete the steps to create a data binding or browse for an existing one.


Select the data type and operation name.



Related concepts:

Outbound processing

User authentication


Related tasks:

Set deployment and runtime properties for generic email data type

Set deployment and runtime properties for user-defined data type


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Globalization

Managed connection factory properties

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and name the operation associated with this data type. For outbound communication, the external service wizard gives you the choice of four different data types: simple email, generic email, generic email with business graph, and user-defined type. Each data type corresponds to a business object structure.

You must have specified the connection properties for the adapter to connect to the mail server before you can specify the operation and data type for the module.

To select a data type and name the operation associated with it, follow this procedure.

  1. In the Add, Edit, or Remove Operations window, click Add to create an operation.

  2. In the Set the I/O Properties window, select the simple e-mail from The data type for the input operation list and click Next. For more information about data types and the types of emails they create, see the business object structures section in this documentation.

    You can select the Enable response on delivery check box to configure the outbound response from the mail server.

  3. In the Set the I/O Properties window, type an Operation name.

    Figure 1. Naming the operation

    Type a meaningful name for the operation, for example, sendSimpleAlertEmail. For more information about the types of operations the adapter can perform, see on Supported Operations in this documentation.

    Names cannot contain spaces.

  4. The external service wizard defaults to the correct data binding, EmailSimpleDataBinding.

  5. Click Finish.

A data type is defined for the module and the operation associated with this data type is named.


Specify interaction specification properties and generate artifacts for the module.



Related concepts:

Business objects

The external service wizard

Feedback


Set interaction specification properties and generating the service

Interaction properties are optional. If you choose to set them, the values you specify are displayed in the import file. The import file is generated when the adapter creates artifacts for the module and contains the operation for the top-level business object.

To set interaction specification properties and generate artifacts for your module, you must have specified the data type and operation name.

Interaction specification properties do not take precedence over request business object attributes, except for the user name and password properties. User name and password values specified in the interaction specification properties take precedence over values set in the managed connection factory properties. To set interaction specification properties and generate artifacts, follow this procedure. See Interaction specification properties.

  1. To set interaction specification properties, complete these steps:

    1. Click Advanced.

      Figure 1. Setting interaction specification properties

    2. Type values for any fields you want to set as defaults.

    3. Optional: In the EnvelopeForm field, type an email address to receive undeliverable mail notifications on a different email address than the Form email address. For more details about this property, see Interaction specification properties.

    4. Click Next.

  2. In the Set the Name and Location window, select the Module from the list. For example, Outbound for outbound processing.

  3. Optional: Name the Folder to store the artifacts.
  4. Type a Name for the interface. This name displays in the IBM Integration Designer assembly diagram.

  5. Optional: Type a Description.

  6. Click Finish. The interface is displayed in IBM Integration Designer assembly diagram.

    Figure 2. Interface in IBM Integration Designer

    The business object you created is also displayed in a different tab.

IBM Integration Designer generates the artifacts and an import. The outbound artifacts that are created are visible in the IBM Integration Designer Project Explorer under your module.


Deploy the module for either testing or production.



Related reference:

Interaction specification properties

Feedback


Configure the module using the generic email data type

To configure a module for outbound processing using the generic email data type, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.



Previous topic: Configure the module using the simple email data type


Next topic: Configure the module using the user-defined data type


Related concepts:

Outbound processing


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Feedback


Set deployment and runtime properties for generic email data type

To select and configure your module for outbound or inbound communication with the mail server, you specify the configuration properties using the external service wizard in IBM Integration Designer. Then, configure the managed connection factory properties. Managed connection factory properties are stored in the business object and contain the information the adapter needs to make the connection between the outbound module and the mail server.

To perform this task, create a module. The module name appears in the Project Explorer view of IBM Integration Designer.

To set connection properties, follow this procedure. See Managed connection factory properties.

  1. In the Select the Processing Direction window, select Outbound and click Next.

    Figure 1. Choosing inbound or outbound in the external service wizard

    The Set the Security and Configuration Properties window is displayed.

  2. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  3. Under the E-mail system connection information, type the Host name. The properties in this window correspond to the managed connection factory properties. For detailed information about these properties, see Managed connection factory properties.

    Figure 2. Security and configuration properties window

  4. Type the Port number. The default value for the SMTP protocol is 25. If your SMTP mail server is listening on a different port number, change this value.
  5. Clear the Select when antivirus or firewall software is running check box if you do not want the adapter to close the managed connection after each outbound request. If an antivirus program or firewall is running on your system (the machine on which the adapter is deployed or the one that hosts the mail server) and this check box is cleared, the adapter might fail to send outbound emails. Leaving this check box selected is recommended.

  6. Optional: Click Advanced and expand the Additional properties, Logging and tracing , or Bidi properties sections as needed.

    • Additional configuration

      1. Select Enable transport security (SSL) check box to specify if secure socket layers are enabled for outbound communication. See Secure connection (SSL) (enableSSL).

      2. In the Alternate e-mail ID in case of delivery failure field, specify an alternate email address to receive undeliverable mail notifications. This email address can be a different email address than the one you specified in the From email address. For more details about this property, see Alternate email ID in case of delivery failure.

      3. In the Maximum retries in case of system connection failure field, type the number of times the adapter tries the connection before reporting a polling error. See Maximum retries on connection failure (connectionRetryLimit).

      4. In the Connection retry interval (in milliseconds) field, specify the time interval between the attempts to reconnect to the mail server if the connection fails. See Retry interval if connection fails (in milliseconds) entities.

    • Logging and tracing

      1. If you have multiple instances of the adapter, expand Logging and tracing and enter a value in the Adapter ID field that is unique for this instance. For more information about this property, see Resource adapter properties.

      2. To mask certain information so the information is not displayed in the logs or traces, select Disguise user data as "XXX" in log and trace files. See Disguise user data as "XXX" in log and trace files (HideConfidentialTrace).

    • Bidi properties

      1. Select the Bidi transformation check box to specify bidirectional format. For more information about setting the Bidi properties, refer to the Globalization section.

  7. In Service properties, specify how you want the adapter to connect to the mail server by selecting any one of these authentication methods.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and type the name of the alias in the J2C Authentication data entry field. You can either specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the security properties from the managed connection specification, click Using security properties from the managed connection factory enter the following information:

      • In the User name field, type the user name for the mail server.

      • In the Password field, type the password for the mail server.

        The security properties are not encrypted and stored as plain text. If you are using an authentication alias, a user name and password are not necessary. During outbound communication, you do not need to enter a user name and password because a mail server uses an anonymous user name and password to send the emails.

    • To administer the user name and password from another mechanism, click Other.

  8. Optional: Select the Change logging properties for wizard check box, to define the level of logging for this module.

  9. For Data format, select Specify a data binding for each operation. Although the default value is Use a data binding configuration for all operations, select Specify a data binding for each operation, because the adapter has a different data binding for each supported business object. These data bindings have different properties, and are configured differently.

    Do not click Next in this window until you complete the steps to create a data binding or browse for an existing one.


Select the data type and operation name.



Related concepts:

Outbound processing


Related tasks:

Set deployment and runtime properties for simple email data type

Set deployment and runtime properties for user-defined data type


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Managed connection factory properties

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and name the operation associated with this data type. For outbound communication, the external service wizard gives you the choice of four different data types: simple email, generic email, generic email with business graph, and user-defined type. Each data type corresponds to a business object structure.

Set the connection properties for the adapter to connect to the mail server. You have chosen to specify a data binding for each operation.

To select a data type and name the operation associated with it, follow this procedure.

  1. In the Add, Edit, or Remove Operations window, click Add to create an operation.

  2. In the Set the I/O Properties window, select a data type from The data type for the input operation list. The Generic e-mail business object and Generic e-mail business object with business graph are the available generic email data types. Click Next. For more information about data types and the types of emails they create, see the business object structures section in this documentation.

    You can select the Enable response on delivery check box to configure the outbound response from the mail server.

  3. In the Set the I/O Properties window, type an Operation name.

    Figure 1. Naming the operation

    Type a meaningful name for the operation. To use this module to create and send e-mails constructed using information supplied in customer business objects, name it something like sendEmailBG. For more information about the types of operations the adapter can perform, see on Supported Operations in this documentation.

    Names cannot contain spaces.

A data type is defined for the module and the operation associated with this data type is named.


Browse for or create a data binding for the module.


Feedback


Configure the data binding

Data bindings read the fields in a business object and fill the corresponding fields in an email. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in an email with information it receives in the business object.

You must enter service configuration properties for the connection to the mail server. You have defined the data type for the module and named the operation associated with this data type. You have chosen to specify a data binding for each operation.

To browse for or create a data binding for the module, follow this procedure.

You can configure the data bindings before running the external service wizard using IBM Integration Designer. To configure the data bindings, select New > Configure Binding Resource in IBM Integration Designer and complete the data binding windows described in this documentation.

  1. In the Set the I/O Properties window, click Select next to the Data format field.

  2. In the Select a Data Format Transformation window, select the Use existing data format transformation from the list option. From the list, select EmailWrapperDataBinding. To configure a custom data binding, select the Select your custom data format transformation from the workspace option. Click Next.

    Figure 1. Selecting the data binding

  3. In Set the Data Transformation Properties window, click Next.

    This window is used for configuring the data handlers.

  4. In Configure a New Data Transformation window, provide the data binding configuration details.

    1. In the Configure a New Data Transformation window, the Module defaults to the module name you typed earlier in the wizard. To use a different module to create a data binding for, select New to create a module.

      Figure 2. Naming the data binding configuration

    2. To select a new folder for the artifact, click Browse and select a new folder location. If you do not browse for a new folder location, the artifacts are created in the root directory for the module.
    3. Type a Name for the data binding configuration and click Finish.

A data binding is configured for use with the module.


Specify data binding properties.


Feedback


Configure business object properties and data handlers

When you intend to use a data type that contains business objects, you must specify properties for those business objects. Completing this step does not add child business objects to the email parent object. Rather, it tells the adapter how to process particular types of business objects. Data handlers perform the conversions between a business object and a particular MIME format.

Create a data binding before specifying business object properties and data handlers for the module. Also, you must predefine business objects using IBM Integration Designer Business Object Editor. If you stop the wizard here to create business objects, you must start the wizard steps from the beginning and your work is not saved.

Data handlers can be configured before running the external service wizard using IBM Integration Designer. To do this configuration, select New > Configure Binding Resource in IBM Integration Designer and complete the data handler windows described in this documentation.

To specify business object properties and data handlers, follow this procedure.

For operations that do not require data transformation (pass-through operations), you do not need to fill out this window. Click Finish and complete the data binding configuration wizard.

  1. In Set the Data Transformation Properties window, click Add to add business object types to the data binding description.

  2. In the Add/Edit properties window, ensure that DataHandler is selected in the Binding type field.

  3. In the Business object type field, click Browse for existing business objects or New to create a business object. These business objects must be imported to IBM Integration Designer before starting the external service wizard. Selecting business objects here does not physically add child business objects. Adding business objects at this stage in the wizard tells the adapter that you are going to use certain business object types with your module. It enables the adapter to know what data binding to apply to any child business objects it processes.

    Figure 1. Adding or editing business object data binding properties

    The encoding specified for configuring the XML data handler for mime type (text/xml) must have the same value specified for Encoding in the EmailWrapperDataBinding properties.

  4. If you selected Browse for the Business object type field, select a data type from the Data Type Selection window and click OK.

  5. If you selected New for the Business object type field.

    Figure 2. Specifying business object properties for the module

    1. Select the Module from the list. If the correct module is not shown, Browse for it or click New to create a module.

    2. Optional: Type a Folder name or Browse for the folder on your local drive where business object schema files (XSD files) generated by the external service wizard are stored.
    3. Type a Name for the business object.

    4. If you do not want to populate the business object with fields from one or more existing business objects, click Finish.

    5. To populate the business object with fields from one or more existing business objects, click Next.

      Figure 3. Deriving business object fields from an existing business object

    6. Select the correct business object and click Finish. The Business object type in the Add/Edit properties window is populated.

  6. In the Add/Edit properties window, select a Mime type such as text/xml or text/html for your business object. The mime type corresponds to the data handler used by the adapter to perform data transformation from one format to another. This step enables the adapter to decide which format it must convert the content to when it encounters the business object.

  7. In the Encoding field, click Select to choose a different encoding value.

  8. In the Data handler configuration field, click Select. To create and configure a data handler.

    1. In the Select a Data Format Transformation window, click Use existing data format transformation from the list option. Select XML data handler from the list and click Next.

      Figure 4. Selecting the data handler configuration type

      The Select your custom data format transformation from the workspace option is available for advanced users who want to use a custom data handler. A custom data handler placed in the class path, shows when this option is selected.

  9. In the Set the Data Transformation Properties window, select the Encoding value, and click Next. This value indicates the type of character encoding the adapter uses during data transformation. For more information about the encoding property, see Email business object properties.

  10. In the Configure a New Data Transformation window, select the Module from the list. If the correct module is not appearing, click New to create a new one.

    1. Optional: Type a Folder name to specify a folder for the artifacts.
    2. Leave the default data handler Name or type a new one and click Next.

      Figure 5. Creating a data handler

    3. Click Finish.

  11. In the Add/Edit Properties window, click Finish.

  12. To add another business object type to the module, click Add in the Set the Data Transformation Properties window. Repeat the steps in this topic to specify business object properties and a data handler for each business object.

Business object properties and their data handlers are created.


Set interaction specification properties and generate artifacts for your module.


Feedback


Set interaction specification properties and generating the service

Interaction properties are optional. If you choose to set them, the values you specify are displayed in the import file. The import file is generated when the adapter creates artifacts for the module and contains the operation for the top-level business object.

To set interaction specification properties and generate artifacts for your module, configure data bindings and selected business objects.

Interaction specification properties do not take precedence over request business object attributes, except for the user name and password properties. User name and password values specified in the interaction specification properties take more precedence over values set in the managed connection factory properties. To set interaction specification properties and generate artifacts, follow this procedure. See Interaction specification properties.

  1. To set interaction specification properties complete these steps:

    1. Click Advanced.

      Figure 1. Setting interaction specification properties

    2. Type values for any fields you want to set as defaults.

    3. Click Next.

  2. In the Set the Name and Location window, select the Module from the list. For example, EmailModule for outbound processing.

    Figure 2. Naming the artifact

  3. Optional: Name the Folder used to store the artifacts.
  4. Type a Name for the interface. This name appears in the IBM Integration Designer assembly diagram.

  5. Optional: Type a Description.

  6. Click Finish. The interface is displayed in IBM Integration Designer assembly diagram.

    Figure 3. Interface in IBM Integration Designer

    The business object you created is also displayed in a different tab.

IBM Integration Designer generates the artifacts and an import. The outbound artifacts that are created are visible in the IBM Integration Designer Project Explorer under your module.


Deploy the module for either testing or production.


Feedback


Configure the module using the user-defined data type

To configure a module for outbound processing using the user-defined data type, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.

You can create a custom data type and specify the required mail content and attachment business object information for the data type. To do this configuration, you need to create an inbound module with the user-defined data type using the EmailFixedStructureDataBinding data binding.



Previous topic: Configure the module using the generic email data type


Related concepts:

Outbound processing


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Feedback


Set deployment and runtime properties for user-defined data type

To select and configure your module for outbound or inbound communication with the mail server, you specify the configuration properties using the external service wizard in IBM Integration Designer. Then, configure the managed connection factory properties. Managed connection factory properties are stored in the business object and contain the information the adapter needs to make the connection between the outbound module and the mail server.

To perform this task, create a module. The module name is displayed in the Project Explorer view of IBM Integration Designer.

To set connection properties, follow this procedure. See Managed connection factory properties.

  1. In the Select the Processing Direction window, select Outbound and click Next.

    Figure 1. Selecting inbound or outbound in the external service wizard

    The Set the Security and Configuration Properties window is displayed.

  2. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  3. Under the E-mail system connection information, type the Host name. The properties on this window correspond to the managed connection factory properties. For detailed information about these properties, see Managed connection factory properties.

    Figure 2. Security and configuration properties window

  4. Type the Port number. The default value for the SMTP protocol is 25. If your SMTP mail server is listening on a different port number, change this value.
  5. Clear the Select when antivirus or firewall software is running check box if you do not want the adapter to close the managed connection after each outbound request. If an antivirus program or firewall is running on your system (the machine on which the adapter is deployed or the one that hosts the mail server) and this check box is cleared, the adapter might fail to send outbound emails. Leaving this check box selected is recommended.

  6. Optional: Click Advanced and expand the Additional properties, Logging and tracing , or Bidi properties sections as needed.

    • Additional configuration

      1. Select Enable transport security (SSL) check box to specify if secure socket layers are enabled for outbound communication. See Secure connection (SSL) (enableSSL).

      2. In the Alternate e-mail ID in case of delivery failure field, specify an alternate email address to receive undeliverable mail notifications. This email address can be a different email address than the one you specified in the From email address. For more details about this property, see Alternate email ID in case of delivery failure.

      3. In the Maximum retries in case of system connection failure field, type the number of times the adapter tries the connection before reporting a polling error. See Maximum retries on connection failure (connectionRetryLimit).

      4. In the Connection retry interval (in milliseconds) field, specify the time interval between the attempts to reconnect to the mail server if the connection fails. See Retry interval if connection fails (in milliseconds) entities.

    • Logging and tracing

      1. If you have multiple instances of the adapter, expand Logging and tracing and enter a value in the Adapter ID field that is unique for this instance. For more information about this property, see Resource adapter properties.

      2. To mask certain information so the information is not displayed in the logs or traces, select Disguise user data as "XXX" in log and trace files. See Disguise user data as "XXX" in log and trace files (HideConfidentialTrace).

    • Bidi properties

      1. Select the Bidi transformation check box to specify bidirectional format. For more information about setting the Bidi properties, see Globalization.

  7. In Service properties, specify how you want the adapter to connect to the mail server by selecting any one of these authentication methods.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and type the name of the alias in the J2C Authentication data entry field. You can either specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the security properties from the managed connection specification, click Using security properties from the managed connection factory enter the following information:

      • In the User name field, type the user name for the mail server.

      • In the Password field, type the password for the mail server.

        The security properties are not encrypted and stored as plain text. If you are using an authentication alias, a user name and password are not necessary. Also, for outbound communication you do not need to enter a user name and password because a mail server uses an anonymous user name and password to send the emails.

    • To administer the user name and password from another mechanism, click Other.

  8. Optional: Select the Change logging properties for wizard check box, to define the level of logging for this module.

  9. For Data format, select Specify a data binding for each operation. Although the default value is Use a data binding configuration for all operations, select Specify a data binding for each operation, because the adapter has a different data binding for each supported business object. These data bindings have different properties, and are configured differently.

    Do not click Next in this window until you complete the steps to create a data binding or browse for an existing one.


Select the data type and operation name.



Related concepts:

Outbound processing


Related tasks:

Set deployment and runtime properties for simple email data type

Set deployment and runtime properties for generic email data type


Related reference:

Managed connection factory properties

Resource adapter properties

Interaction specification properties

Connection properties for the external service wizard

Managed connection factory properties

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and name the operation associated with this data type. For outbound communication, the external service wizard gives you the choice of four different data types: simple email, generic email, generic email with business graph, and user-defined type. Each data type corresponds to a business object structure. Use the user-defined data type to configure your own business object wrapper instead of using the generic email business object.

Set the connection properties for the adapter to connect to the mail server. You have chosen to specify a data binding for each operation.

To select the user-defined data type, name the operation associated with it, create a wrapper business object, and specify child business objects, follow this procedure.

  1. In the Add, Edit, or Remove Operations window, click Add to create an operation.

  2. In the Set the I/O Properties window, select the User defined email business object from The data type for the input operation list and click Next. For more information about data types and the types of emails they create, see the business object structures section in this documentation.

    You can select the Enable response on delivery check box to configure the outbound response from the mail server.

  3. In the Set the I/O Properties window, type an Operation name.

  4. Click New for the Input type.

    Figure 1. Selecting the input type

  5. In Set the Location window, provide the module name and the name of the folder where the wrapper business object (the input type) is to be generated. Click Next.
  6. In Set the Properties window, provide the wrapper Business object name.

    1. Optional: Select the Generate a business graph for the business object check box.

    2. Set the properties for the email type. Click Add to add child business objects to the table.

    You can generate the wrapper business object and specify the child business objects that are used inside the wrapper business object and specify which parts of the email you want to use (such as mailContent or attachment1).

    Figure 2. Set the properties for the new business object

    In the Add/Edit Properties window, select either the mailContent or the Attachment1 as the email part. If you select the attachment1 part of the email, then you can also specify the default attachment name used with this business object.

    You can have a wrapper business object without having a mailContent business object, for example, if you are not sending any content in the email or if the email polled by the adapter does not have any content.

  7. When you finish adding child business objects to the table, click Finish. For each business object you add, a row is created in the table. The following figure shows the generated wrapper business object.

    Figure 3. The generated wrapper business object

  8. In the Set the Properties window, click Finish.

A data type is defined for the module and the operation associated with this data type is named. A wrapper business object is created, and the child business objects that are used inside the wrapper business object are specified.


Generate the data binding configuration for the module.



Related concepts:

Business objects

The external service wizard

Feedback


Configure the data binding

Data bindings read the fields in a business object and fill the corresponding fields in an email. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in an email with information it receives in the business object.

You must enter service configuration properties for the connection to the mail server. You have defined the data type for the module and named the operation associated with this data type. You have chosen to specify a data binding for each operation.

To browse for or create a data binding for the module, follow this procedure.

The user-defined data type can only be used in a data transformation (non pass-through) mode. You cannot use the unstructured content business object.

Data bindings can be configured before running the external service wizard using IBM Integration Designer. To do this configuration, select New > Configure Binding Resource in IBM Integration Designer and complete the data binding windows described in this documentation.

  1. In the Set the I/O Properties window, click Select next to the Data format field.

  2. In the Select a Data Format Transformation window, select the Use existing data format transformation from the list option. From the list, select EmailFixedStructuredDataBinding. To configure a custom data binding, select the Select your custom data format transformation from the workspace option. A custom data binding, placed in the class path, shows when this option is selected. Click Next.

    Figure 1. Selecting the data binding

    When you configure the EmailFixedStructuredDataBinding, you create a custom data type with the required mail content and the attachment business objects.

  3. In Set the Data Transformation Properties window, click Next.

    This window is used for configuring the data handlers.

  4. In Configure a New Data Transformation window, provide the data binding configuration details.

    1. In the Configure a New Data Transformation window, the Module defaults to the module name you typed earlier in the wizard. If you do not want to create a data binding for this module, select New to create a module.

      Figure 2. Naming the data binding configuration

    2. To select a new folder for the artifact, click Browse and select a new folder location. If you do not browse for a new folder location, the artifacts are created in the root directory for the module.
    3. Type a Name for the data binding configuration and click Finish.

A data binding is configured for use with the module.


Configure business object properties and data handlers.


Feedback


Configure business object properties and data handlers

When you intend to use a data type that contains business objects, you must specify properties for those business objects. Completing this step does not add child business objects to the email parent object. Rather, it tells the adapter how to process particular types of business objects. Data handlers perform the conversions between a business object and a particular MIME format.

Create a data binding before specifying business object properties and data handlers for the module. Also, you must predefine business objects using IBM Integration Designer Business Object Editor. If you stop the wizard here to create business objects, you must start the wizard steps from the beginning and your work is not saved.

Data handlers can be configured before running the external service wizard using IBM Integration Designer. To do this configuration, select New > Configure Binding Resource in IBM Integration Designer and complete the data handler windows described in this documentation.

To specify business object properties and data handlers, follow this procedure.

  1. In Set the Data Transformation Properties window, select a row and click Edit.

    For the user-defined type, the following warning message displays if you click Add in this window. The User cannot add new row to the table. Adapter has parsed your Input type and filled the table. This warning appears because the adapter determines which business objects the data binding must know about and pre-filled the table. To provide values for the rest of the properties, select individual rows and click Edit.

    If you are repeating these steps to configure a child data binding for the user-defined data type, you cannot select between data handler and data binding when you click Edit. The binding type option (to select between data binding and data handler) does not function correctly for the EmailFixedStructuredDataBinding. To configure a child data binding for EmailFixedStructuredDataBinding, click the Binding type field and select DataBinding.

  2. In the Add/Edit properties window, ensure that DataHandler is selected in the Binding type field.

  3. In the Business object type field, click Browse for existing business objects or New to create a business object. Selecting business objects here does not physically add child business objects. Adding business objects at this stage in the wizard tells the adapter that you are going to use certain business object types with your module. It enables the adapter to know what data binding to apply to any child business objects it processes.

    1. If you selected Browse for the Business object type field, select a data type from the Data type selection window and click OK.

    2. If you selected New for the Business object type field.

      Figure 1. Specifying business object properties for the module

    3. Select the Module. If the correct module is not shown, Browse for it or click New to create a module.

    4. Optional: Type a Folder name or Browse for the folder on your local drive where business object schema files (XSD files) generated by the external service wizard are stored.
    5. Type a Name for the business object.

    6. If you do not want to populate the business object with fields from one or more existing business objects, click Finish.

    7. To populate the business object with fields from one or more existing business objects, click Next.

      Figure 2. Deriving business object fields from an existing business object

    8. Select the correct business object and click Finish. The Business object type in the Add/Edit properties window is populated.

  4. In the Add/Edit properties window, select a Mime type such as text/xml or text/html for your business object. The mime type corresponds to the data handler used by the adapter to perform data transformation from one format to another. This step enables the adapter to decide which format it must convert the content to when it encounters the business object.

    Figure 3. Adding or editing business object data binding properties

    The encoding specified for configuring the XML data handler for Mime type (text/xml) must have the same value specified for Encoding in the EmailFixedStructuredDataBinding properties.

  5. In the Encoding field, click Select to choose a different encoding value.

  6. In the Data handler configuration field, click Select. To create and configure a data handler.

    1. From the Use existing data format transformation from the list option, select the XML data handler. Click Next.

      Figure 4. Selecting the data handler configuration type

      The Select your custom data format transformation from the workspace option is available for advanced users who want to use a custom data handler. A custom data handler, placed in the class path, shows when this option is selected.

    2. In the Set the Data Transformation Properties window, select an Encoding value. Click Next.

      This value indicates the type of character encoding the adapter uses during data transformation. For more information about the encoding property, see Email business object properties.

    3. In the Configure a New Data Transformation window, select the module. If the correct module is not appearing, click New to create a new one.

    4. Optional: Type a Folder name to specify a folder for the artifacts.
    5. Leave the default data handler Name or type a new one.

      Figure 5. Creating a data handler

    6. Click Finish.

  7. In the Add/Edit properties window, click Finish.

Business object properties and their data handlers are created.


Set interaction specification properties and generate artifacts for your module.



Related concepts:

Business objects

The external service wizard

Feedback


Set interaction specification properties and generating the service

Interaction properties are optional. If you choose to set them, the values you specify are displayed in the import file. The import file is generated when the adapter creates artifacts for the module and contains the operation for the top-level business object.

To set interaction specification properties and generate artifacts for your module, configure data bindings and selected business objects.

Interaction specification properties do not take precedence over request business object attributes, except for the user name and password properties. User name and password values specified in the interaction specification properties take more precedence over values set in the managed connection factory properties. To set interaction specification properties and generate artifacts, follow this procedure. See Interaction specification properties.

  1. To set interaction specification properties complete these steps:

    1. Click Advanced.

      Figure 1. Setting interaction specification properties

    2. Type values for any fields you want to set as defaults.

    3. Click Next.

  2. In the Set the Name and Location window, select the Module.

    Figure 2. Naming the artifact

  3. Optional: Name the Folder to store the artifacts.
  4. Type a Name for the interface. This name displays in the IBM Integration Designer assembly diagram.

  5. Optional: Type a Description.

  6. Click Finish. The interface is displayed in IBM Integration Designer assembly diagram.

    Figure 3. Interface in IBM Integration Designer

    The business object you created is also displayed in a different tab.

IBM Integration Designer generates the artifacts and an import. The outbound artifacts that are created are visible in the IBM Integration Designer Project Explorer under your module.


Deploy the module for either testing or production.


Feedback


Configure the module for inbound processing

To configure a module to use the adapter for inbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.

  1. Set deployment and runtime properties for inbound processing Using the external service wizard in IBM Integration Designer, select whether the module is used for outbound or inbound communication with the mail server. Then configure the connection properties. The connection properties are stored in the business object and contain the information the adapter needs to make the connection between the inbound module and service.
  2. Selecting a data type and operation name Use the external service wizard to select a data type and name the operation associated with this data type. For inbound communication, the external service wizard gives you the choice of three different data types: generic email, generic email with business graph, and user-defined type. Each data type corresponds to a business object structure.
  3. Configure the data binding Data bindings read the fields in a business object and fill the corresponding fields in an email. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in an email with information it receives in the business object.
  4. Configure business object properties and data handlers When you select a data type that contains business objects, you must specify properties for those business objects. However, this step does not add child business object to the email parent object. Rather, they tell the adapter how to process particular types of business objects. Data handlers perform the conversions between a business object and a particular MIME format.
  5. Set deployment properties and generating the service The export file is generated when the adapter creates artifacts for the module and contains the operation for the top-level business object.



Previous topic: Configure the module for outbound processing

Feedback


Set deployment and runtime properties for inbound processing

Use the external service wizard in IBM Integration Designer, select whether the module is used for outbound or inbound communication with the mail server. Then configure the connection properties. The connection properties are stored in the business object and contain the information the adapter needs to make the connection between the inbound module and service.

Before you can set the connection properties in this section, create your module in IBM Integration Designer. It is displayed in the Business Integration pane below the adapter project. Also, create a staging directory on your local system for storing emails that is polled by the adapter but which are yet to be turned into business objects.

To set connection properties, follow this procedure. See Activation specification properties.

  1. In the Select the Processing Direction window, select Inbound and click Next.

    Figure 1. Choosing inbound or outbound in the external service wizard

    The Set the Security and Configuration Properties window opens.

  2. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

    Figure 2. Specifying inbound connection properties

  3. Browse for the Staging Directory you created on your local system. If you have not created a staging directory, create one and then restart the external service wizard.
  4. Define the Connection properties for your module. For more details about these properties, see Activation specification properties.

    1. Under the E-mail system connection information, type the Host name.
    2. Type the Port number.

    3. Optional: Select the email Protocol. For more information about the POP3 and IMAP email protocols, see Supported inbound protocols.

  5. Click Advanced and specify values as needed. These include activation specification properties designed to alter the default behavior of the adapter during inbound communication. For more information about any of the Advanced properties for event polling, event delivery, event persistence, archiving, or setting search criteria, see Activation specification properties.

    Figure 3. Advanced properties

    • Event delivery configuration

      1. In the Type of delivery field, select the delivery method. The methods are described in Delivery type (DeliveryType).

      2. To ensure that events are delivered only once and to only one export, select the Ensure assured-once event delivery check box. This option might reduce performance but does not result in duplicate or missing event delivery. See Ensure once-only event delivery (AssuredOnceDelivery).

      3. In the Retry limit for failed events field, specify the number of times to try to deliver an event after a delivery failure. See Retry limit for failed events (FailedEventRetryLimit).

    • Event polling configuration

      • In the Interval between polling periods (milliseconds) field, type the time in milliseconds, the adapter waits between polling periods. For more information about the property, see Interval between polling periods (PollPeriod).

      • In the Maximum events in polling period field, type the number of events to deliver in each polling period. For more information about the property, see Maximum events in polling period (PollQuantity).
      • To specify the time interval between attempts to connect to the mail server if a connection fails, set Time between retries in case of system connection failure (in milliseconds) to a value in milliseconds. See Time between retries in case of system connection failure (RetryInterval).
      • To specify the number of connection exceptions during the inbound operation, set Maximum number of retries in case of system connection failure to a value greater than or equal to 0. See Maximum number of retries in case of system connection failure (RetryLimit).

      • To have the adapter to stop if polling errors occur, select the Stop the adapter when an error is encountered while polling check box. If you do not select this option, the adapter logs an exception but continues to run. See Stop the adapter when an error is encountered while polling (StopPollingOnError).

      • Select the Retry EIS connection on startup check box, if you want the adapter to try a failed connection when starting. See Retry EIS connection on startup (RetryConnectionOnStartup).

      • Select the calendar based scheduling option to create calendar based polling for inbound activities. You can schedule your business activities, when you create a new calendar in IBM Integration Designer. The option of working with the calendar based scheduling feature is only possible with IBM Integration Designer as the tooling environment. The following figure helps you to schedule a calendar polling option.

        Figure 4. Polling based on business calendar

        You can either select a blank calendar or create a new calendar for a module or library.

        When you select a blank calendar, you will not be able to set predefined time intervals. You have to define your time intervals. When you create a calendar using a predefined template, you can define time intervals for each template.

        • To select an existing calendar for a module or library, click Browse. In the Select a Business Calendar window, you can search for existing calendar files (*cal) in the IBM Integration Designer workspace.

          1. In the Filter by name field, type the calendar name or name pattern. The calenders matching the pattern are displayed in the Matching business calendars area.

          2. Select a calendar and click OK to return to the external service wizard.

        • To create a new calendar entry for a module or library, click New. The Create a business calendar window is displayed.

          1. In the Module or library field, click Browse to select an existing calendar module or click New to create a module for the new calendar.

          2. In the Folder field, click Browse to select an existing folder or create a new folder for the calendar.

          3. In the Name field, enter a name for the new calendar.

            • To create a non template calendar, click Finish. Or
            • To generate the calendar based on a predefined template, click Next. In the Use a template window, select the Create a calendar using one of the templates check box and click Finish.

            The new business calendar is created and available in the Business Integration view. Once you complete the wizard, you can view or modify the calendar schedules in the Business Integration view using the Business Calendar Editor. You can modify the intervals and exceptions, or add new entries for these elements. For more details about working with business calendars, see Business calendars.

        You must deploy the Business Calendar module to the same IBM Business Process Manager or WebSphere Enterprise Service Bus instance, along with the inbound application. If you do not map these two connections to the same server instance, the inbound application using the business calendar will by default, poll as there is no calendar configured.

    • Event persistence configuration

      1. Select Auto create event table check box if you want the adapter to create the Event Persistence table. See Auto create event table property (EP_CreateTable).

      2. In the Event recovery table name field, specify the name of the table the adapter uses for event persistence. See Event recovery table name property (EP_TableName).

      3. In the Event recovery data source (JNDI) name field, specify the JNDI name of the data source that event persistence uses to connect to the JDBC database. See Event recovery data source (JNDI) name property (EP_DataSource_JNDIName).

      4. In the User name used to connect to event data source field, specify the user name the event persistence uses to connect to the database from the data source. See User name used to connect to event data source property (EP_UserName).

      5. In the Password used to connect to event data source field, specify the password the event persistence uses to connect to the database from the data source. See Password used to connect to event data source property (EP_Password).

      6. In the Database schema name field, specify the schema name of the database the event persistence uses. See Database schema name (EP_SchemaName).

    • Additional configuration

      1. Select the Enable transport security (SSL) check box to enable SSL. See Enable transport security (SecureConnectionProperty).

      2. Select the Emit individual business objects from a multipart e-mail check box, to specify if the adapter creates individual business objects for each part of a multipart email. See Emit individual business objects from a multipart email (EmitIndividualBOs).

      3. In the Match all search criteria field, specify the search criteria to filter which events are polled from the mail server. The events that meet the ANDed conditions are polled. See Match all search criteria (MatchAllCriteria).

      4. In the Match some search criteria field, specify the search criteria to filter which events are polled from the mail server. The events that meet the ORed conditions are polled. See Match some search criteria (MatchSomeCriteria).

      5. In the Archive file naming pattern field, you can specify a comma-delimited pattern of header names which are used to name archived files stored in the archive folder. See Archive file naming pattern (ArchiveFile).

    • Bidi properties

      1. Select the Bidi transformation check box to specify bidirectional format. For more information about setting the Bidi properties, see Globalization.

    • Logging and tracing

      1. If you have multiple instances of the adapter, enter a value in the Adapter ID that is unique for this instance. See Adapter ID (AdapterID).

      2. You can select the Disguise user data as 'XXX' in log and trace files check box to prevent sensitive user data from being written to log and trace files.

  6. In Service properties, specify how you want the adapter to connect to the mail server by selecting any one of these authentication methods.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and type the name of the alias in the J2C Authentication data entry field. You can either specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the security properties from the activation specification, click Using security properties from the activation specification enter the following information:

      • In the User name field, type the user name for the mail server.

      • In the Password field, type the password for the mail server.

        The security properties are not encrypted and stored as plain text. If you are using an authentication alias, a user name and password are not necessary. Also, for outbound communication you do not need to enter a user name and password because a mail server uses an anonymous user name and password to send the emails.

    • To administer the user name and password from another mechanism, click Other.

  7. To use an existing function selector configuration, use the default value (EmailFunctionSelector). To configure a custom function selector, click Select. Clicking Select allows you to select a pre-configured function selector. You can configure a function selector to implement a custom function selector. This configuration is an advanced concept. By default, the email function selector is used, which does not require any configuration.

  8. Optional: Select the Change logging properties for wizard check box to define the level of logging for this module.


Browse for or create a data binding for the module.



Next topic: Selecting a data type and operation name


Related concepts:

Inbound processing

User authentication


Related reference:

Activation specification properties

Resource adapter properties

Connection properties for the external service wizard

Inbound configuration properties

Globalization

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and name the operation associated with this data type. For inbound communication, the external service wizard gives you the choice of three different data types: generic email, generic email with business graph, and user-defined type. Each data type corresponds to a business object structure.

You must have specified the connection properties for the adapter to connect to the mail server, data bindings, and data handlers before you can specify the operation and data type for the module.

To select a data type and name the operation associated with it, follow this procedure.

  1. In the Add, Edit, or Remove Operations window, click Add.

  2. In the Set the I/O Properties window, type an Operation name.

    Figure 1. Naming the operation

    Type a meaningful name for the operation. If this module is going to be used to convert a simple email business object, name it something like SendEmail. Or, if it is going to be used to create a parent email business object with a customer child business object, name it something like SendCustomerEmail. For more information about the types of operations the adapter can perform, see Supported operations.

    Names cannot contain spaces.

  3. The external service wizard defaults to the correct data binding for the data type you selected in the Operation window. To use a different data binding, click Browse for a data binding or create a new one using the instructions in the sections "Configuring the data binding" and "Configuring business object properties and data handlers."

  4. In the Set the I/O Properties window, click Finish.

  5. In the Add, Edit, or Remove Operations window, click Next.

A data type is defined for the module and the operation associated with this data type is named.


Generate artifacts for the module.



Previous topic: Set deployment and runtime properties for inbound processing


Next topic: Configure the data binding


Related concepts:

Business objects

The external service wizard

Feedback


Configure the data binding

Data bindings read the fields in a business object and fill the corresponding fields in an email. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in an email with information it receives in the business object.

You must have entered service configuration properties for the connection to the mail server.

To add and configure a data binding for the module, follow this procedure.

You can configure data bindings before running the external service wizard by using IBM Integration Designer. To do this configuration, select New > Configure Binding Resource in IBM Integration Designer and complete the data binding windows described in this documentation.

  1. In the Set the Security and Configuration Properties window, select a value for the Data format options from the list. You can choose to use the data binding configuration for all operations or you can choose to specify a data binding for each operation. If using the data binding configuration for all operations, then the data binding configured here is used as the default data binding configuration for all the operations. If you choose to specify a data binding for each operation, then configure a data binding for each operation. In these steps, the Use a data format configuration for all operations option is selected.

    If associate your inbound module with a particular user-defined business object type, the steps for defining your data binding in this section dictates which events the adapter processes at run time. At run time, inbound events that are symmetric to the custom data type are processed by the adapter. Those events that are not symmetric to the custom data type are not processed. For these events, the adapter throws an exception and logs an error message.

  2. In the Data format field, click Select.

  3. In the Select a Data Format Transformation window, select the Use existing data format transformation from the list option to use one of the data bindings included with IBM Integration Designer. Click Next. The Select your custom data format transformation from the workspace option is available for advanced users who want to use a custom data binding. A custom data binding, once placed in the class path, shows when this option is selected.

    Figure 1. Selecting a data binding

    The following data types are matched with the following data bindings.

    Data types and their data binding equivalents

    Data type Data binding
    Generic email Email Wrapper Data Binding
    Generic email with business graph Email Wrapper Data Binding
    User-defined email business object EmailFixedStructureDataBinding

  4. In Set the Data Transformation Properties window, click Next.

    This window is used for configuring the data handlers.

  5. In Configure a New Data Transformation window, provide the data binding configuration details.

    1. In the New Data Binding Configuration window, the Module defaults to the module name you typed earlier in the wizard. To create a data binding for a different module, select New to create a module.

      Figure 2. Naming the data binding configuration

    2. To select a new folder for the artifact, click Browse and select a new folder location. If you do not browse for a new folder location, the artifacts are created in the root directory for the module.
    3. Type a Name for the data binding configuration and click Finish.

    The data binding class name populates in the Set the Security and Configuration Properties window.

A data binding is configured for use with the module.


Specify data binding properties.



Previous topic: Selecting a data type and operation name


Next topic: Configure business object properties and data handlers

Feedback


Configure business object properties and data handlers

When you select a data type that contains business objects, you must specify properties for those business objects. However, this step does not add child business object to the email parent object. Rather, they tell the adapter how to process particular types of business objects. Data handlers perform the conversions between a business object and a particular MIME format.

You must have created a data binding before specifying business object properties and data handlers for the module. Also, you must have predefined business objects using IBM Integration Designer Business Object Editor. If you stop the wizard here to create business objects, you must start the wizard steps from the beginning.

Data handlers can be configured before running the external service wizard using IBM Integration Designer. To do this configuration, select New > Configure Binding Resource in IBM Integration Designer and complete the data handler windows described in this documentation.

Define business object properties and data handlers if you have selected the generic email, email with business graph, or user-defined type as the data type. The simple alert email data type does not have properties that need to be configured. To specify business object properties and data handlers, follow this procedure.

  1. If you chose the email with business object or email with business graph data types, click Add to add the business object types to the data binding description in the Add/Edit properties window.

    For the user-defined type, the following warning message is displayed if you click Add in this window. The User cannot add new row to the table. Adapter has parsed your Input type and filled the table. This warning appears because the adapter has determined which business objects the data binding must know about and pre-filled the table. To provide values for the rest of the properties, select individual rows and click Edit.

    If you are repeating these steps to configure a child data binding for the user-defined data type, note that you cannot select between data handler and data binding when you click Edit. The binding type option (to select between data binding and data handler) does not function correctly for the EmailFixedStructuredDataBinding data binding. To configure a child data binding for EmailFixedStructuredDataBinding, click the Binding type field and select DataBinding.

  2. In the Add/Edit properties window, ensure that DataHandler is selected in the Binding type field.

  3. In the Business object type field, click Browse for existing business objects or New to create a business object. Selecting business objects here does not physically add child business objects. Adding business objects at this stage in the wizard tells the adapter that you are going to use certain business object types with your module. It enables the adapter to know what data binding to apply to any child business objects it processes.

    1. If you selected Browse for the Business object type field, select a data type from the Data Type Selection window and click OK.

    2. If you selected New for the Business object type field.

      Figure 1. Specifying business object properties for the module

    3. Select the Module. If the correct module is not shown, Browse for it or click New to create a module.

    4. Optional: Type a Folder name or Browse for the folder on your local drive where business object schema files (XSD files) generated by the external service wizard are stored.
    5. Type a Name for the business object.

    6. If you do not want to populate the business object with fields from one or more existing business objects, click Finish.

    7. To populate the business object with fields from one or more existing business objects, click Next.

      Figure 2. Deriving business object fields from an existing business object

    8. Select the correct business object and click Finish. The Business object type in the Add/Edit properties window is populated.

  4. In the Add/Edit properties window, select a Mime type such as text/xml for your business object. The mime type corresponds to the data handler used by the adapter to perform data transformation from one format to another. This step enables the adapter to decide which format it has to convert the content to when it encounters the business object.

    Figure 3. Adding or editing business object data binding properties

  5. In the Encoding field, click Select to choose a different encoding value.

  6. In the Data handler configuration field, click Select. To create and configure a data handler.

    1. From the Use existing data format transformation from the list option, select the XML data handler. Click Next.

      Figure 4. Creating a data handler

    2. In the Set the Data Transformation Properties window, select an Encoding value. Click Next.

    3. In the Configure a New Data Transformation window, select the module. If the correct module is not displayed, click New to create a new one.

    4. Optional: Type a Folder name to specify a folder for the artifacts.
    5. Leave the default data handler Name or type a new one.

      Figure 5. Creating a data handler

    6. Click Finish.

  7. In the Add/Edit properties window, click Finish.

Business object properties and their data handlers are created.


Specify interaction specification properties and generate artifacts for the module.



Previous topic: Configure the data binding


Next topic: Set deployment properties and generating the service


Related concepts:

Business objects

The external service wizard

Feedback


Set deployment properties and generating the service

The export file is generated when the adapter creates artifacts for the module and contains the operation for the top-level business object.

To generate artifacts for your module you must have already configured data bindings and selected business objects.

To generate artifacts for your module, follow this procedure.

  1. In the Set the Name and Location window, select the Module.

    Figure 1. Naming the artifact

  2. Optional: Name the Folder to store the artifacts.
  3. Type a Name for the interface. This name displays in the IBM Integration Designer assembly diagram.

  4. Optional: Type a Description.

  5. Click Finish. The IBM Integration Designer assembly diagram opens and the interface you created is displayed.

    Figure 2. Interface in IBM Integration Designer

    The business object you created is also displayed in a different tab.

The IBM Integration Designer generates the artifacts and an export. The inbound artifacts that are created are visible in the IBM Integration Designer Project Explorer under your module.


Deploy the module for either testing or production.



Previous topic: Configure business object properties and data handlers


Related reference:

Interaction specification properties

Feedback


Change interaction specification properties

To change interaction specification properties for your adapter module after generating the service, use the assembly editor in IBM Integration Designer.

You must have used the external service wizard to generate a service for the adapter.

You might want to change interaction specification properties after you have generated a service for the adapter. Interaction specification properties, which are optional, are set at the method level, for a specific operation on a specific business object. The values you specify appear as defaults in all parent business objects generated by the external service wizard. You can change these properties before you export the EAR file. You cannot change these properties after you deploy the application.

To change the interaction specification properties, use the following procedure:

  1. From the Business Integration perspective of IBM Integration Designer, expand the module name.

  2. Expand Assembly Diagram and double-click the interface.

  3. Click the interface in the assembly editor. The module properties are displayed.

  4. Click the Properties tab. You can also right-click the interface in the assembly diagram and click Show in Properties.

  5. Under Binding, click Method bindings. The methods for the interface are displayed, one for each combination of business object and operation.

  6. Select the method whose interaction specification property you want to change.

  7. Click Advanced and change the property in the Generic tab. Repeat this step for each method whose interaction specification property you want to change.

The interaction specification properties associated with your adapter module are changed.


Deploy the module.



Related reference:

Interaction specification properties

Feedback


Deploy the module

Deploy a module to place the files that make up your module and adapter into an operational environment for production or testing. In IBM Integration Designer, the integrated test environment features runtime support for BPM or WebSphere Enterprise Service Bus, or both, depending on the test environment profiles that you selected during installation.


Feedback


Deployment environments

There are test and production environments into which you can deploy modules and adapters.

In IBM Integration Designer, you can deploy your modules to one or more servers in the test environment. This is typically the most common practice for running and testing business integration modules. However, you can also export modules for server deployment on IBM Business Process Manager or WebSphere Enterprise Service Bus as EAR files using the administrative console or command-line tools.


Feedback


Deploy the module for testing

In IBM Integration Designer, you can deploy a module that includes an embedded adapter to the test environment and work with server tools that enable you to perform such tasks as editing server configurations, starting, and stopping servers and testing the module code for errors. The testing is generally performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Generating and wiring a target component for testing inbound processing Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.
  2. Add the module to the server In IBM Integration Designer, you can add modules to one or more servers in the test environment.
  3. Testing the module for outbound processing using the test client Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.


Feedback


Generating and wiring a target component for testing inbound processing

Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.

You must have generated an export module, using the external service wizard.

Generating and wiring a target component for inbound processing is required in a testing environment only. It is not necessary when deploying the adapter in a production environment.

The target component receives events. You wire the export to the target component (connecting the two components) using the assembly editor in IBM Integration Designer. The adapter uses the wire to pass event data (from the export to the target component).

  1. Create the target component.

    1. From the Business Integration perspective of IBM Integration Designer, expand Assembly Diagram and double-click the export component. If you did not change the default value, the name of the export component is the name of your adapter + InboundInterface.

      An interface specifies the operations that can be called and the data that is passed, such as input arguments, returned values, and exceptions. The InboundInterface contains the operations required by the adapter to support inbound processing and is created when you run the external service wizard.

    2. Create a new component by expanding Components, selecting Untyped Component, and dragging the component to the Assembly Diagram.

      The cursor changes to the placement icon.

    3. Click the component to have it displayed in the Assembly Diagram.

  2. Wire the components.

    1. Click and drag the export component to the new component.

      Save the assembly diagram. Click File > Save.

  3. Generate an implementation for the new component.

    1. Right-click on the new component and select Generate Implementation > Java.

    2. Select (default package) and click OK. This creates an endpoint for the inbound module.

      The Java™ implementation is displayed in a separate tab.

    3. Optional: Add print statements to print the data object received at the endpoint for each of the endpoint methods.

    4. Click File > Save to save the changes.


Continue deploying the module for testing.



Next topic: Add the module to the server

Feedback


Add the module to the server

In IBM Integration Designer, you can add modules to one or more servers in the test environment.

If the module you are testing uses an adapter to perform inbound processing, generate and wire a target component to which the adapter sends the events.

In order to test your module and its use of the adapter, you need to add the module to the server.

  1. Conditional: If there are no servers in the Servers view, add and define a new server by performing the following steps:

    1. Place your cursor in the Servers view, right-click, and select New > Server.

    2. From the Define a New Server window, select the server type.

    3. Configure servers settings.

    4. Click Finish to publish the server.

  2. Add the module to the server.

    1. Switch to the servers view. In IBM Integration Designer, select Windows > Show View > Servers.

    1. Start the server. In the Servers tab in the lower-right pane of the IBM Integration Designer screen, right-click the server and then select Start.

  3. When the server status is Started, right-click the server and select Add and Remove Projects.

  4. In the Add and Remove Projects screen, select your project and click Add. The project moves from the Available projects list to the Configured projects list.

  5. Click Finish. This deploys the module on the server.

    The Console tab in the lower-right pane displays a log while the module is being added to the server.


Test the functionality of your module and the adapter.



Previous topic: Generating and wiring a target component for testing inbound processing


Next topic: Testing the module for outbound processing using the test client

Feedback


Testing the module for outbound processing using the test client

Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.

You need to add the module to the server first.

Testing a module is performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Select the module you want to test, right-click on it, and select Test > Test Module.
  2. Follow the instructions for Testing modules and components at the Related tasks link of this topic.


If you are satisfied with the results of testing your module and adapter, you can deploy the module and adapter to the production environment.



Previous topic: Add the module to the server


Related tasks:

Testing modules and components in WebSphere Integration Developer

Feedback


Deploy the module for production

Deploy a module created with the external service wizard to IBM Business Process Manager or WebSphere Enterprise Service Bus in a production environment is a two-step process. First, you export the module in IBM Integration Designer as an enterprise archive (EAR) file. Second, you deploy the EAR file using the BPM or WebSphere Enterprise Service Bus administrative console.

  1. Install the RAR file (for modules using stand-alone adapters only) If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Java™ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).
  2. Export the module as an EAR file Using IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.
  3. Install the EAR file Installing the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.



Previous topic: Configure the module for deployment


Next topic: Configure logging and tracing

Feedback


Install the RAR file (for modules using stand-alone adapters only)

If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Java™ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).

You must set Deploy connector project to On server for use by multiple adapters in the Set the Service Generation and Deployment Properties window of the external service wizard.

Install the adapter in the form of a RAR file results in the adapter being available to all Java EE application components running in the server run time.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click Install RAR.

    Figure 1. The Install RAR button on the Resource adapters page

  6. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  7. Click Next.

  8. Optional: In the Resource adapters page, change the name of the adapter and add a description.

  9. Click OK.

  10. Click Save in the Messages box at the top of the page.


The next step is to export the module as an EAR file that you can deploy on the server.



Next topic: Export the module as an EAR file

Feedback


Export the module as an EAR file

Use IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Before you can export a module as an EAR file, you must have created a module to communicate with your service. The module should be displayed in the IBM Integration Designer Business Integration perspective.

To export the module as an EAR file, perform the following procedure.

  1. Right-click the module and select Export.

  2. In the Select window, expand Java EE.

  3. Select EAR file and click Next.

  4. Optional: Select the correct EAR application. The EAR application is named after your module, but with "App" added to the end of the name.
  5. Browse for the folder on the local file system where the EAR file will be placed.

  6. To export the source files, select the Export source files check box. This option is provided in case you want to export the source files in addition to the EAR file. Source files include files associated with Java™ components, data maps, and so on.

  7. To overwrite an existing file, click Overwrite existing file.

  8. Click Finish.

The contents of the module are exported as an EAR file.


Install the module in the administrative console. This deploys the module to IBM Business Process Manager or WebSphere Enterprise Service Bus.



Previous topic: Install the RAR file (for modules using stand-alone adapters only)


Next topic: Install the EAR file


Related tasks:

Install the EAR file

Feedback


Install the EAR file

Install the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.

You must have exported your module as an EAR file before you can install it on IBM Business Process Manager or WebSphere Enterprise Service Bus.

To install the EAR file, perform the following procedure. For more information about clustering adapter module applications, see the http://www.ibm.com/software/webservers/appserv/was/library/.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > New Application > New Enterprise Application.

    Figure 1. Preparing for the application installation window

  5. Click Browse to locate your EAR file and click Next. The EAR file name is the name of the module followed by "App."

  6. If you are deploying to a clustered environment.

    1. On the Step 2: Map modules to servers window, select the module and click Next.

    2. Select the name of the server cluster.

    3. Click Apply.

  7. Click Next. In the Summary page, verify the settings and click Finish.

  8. If you are using an authentication alias:

    1. Expand Security and select Business Integration Security.

    2. Select the authentication alias to configure. You must have administrator or operator rights to change the authentication alias configurations.

    3. If it is not already specified, type the User name.

    4. If it is not already specified, type the Password.

    5. If it is not already specified, type the password again in the Confirm Password field.

    6. Click OK.

The project is now deployed and the Enterprise Applications window is displayed.


To set or reset any properties or you would like to cluster adapter project applications, make those changes using the administrative console before configuring troubleshooting tools.



Previous topic: Export the module as an EAR file


Related tasks:

Export the module as an EAR file

Feedback

Deploy the module in a clustered environment

In IBM Integration Designer, you can deploy the IBM WebSphere Adapter for Email in a clustered environment.

To deploy the module in a clustered environment, use any of the following approaches.


Feedback


Deploy module embedded in the application

The adapter is deployed embedded in the application and specific to it. The adapter cannot be shared between multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the embedded adapter, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select With module for use by single application.

  2. Create the module as described in the Business process management samples for WebSphere Adapters.

  3. In the Dependencies option for the module, after the module is created, ensure the Deploy with module option is selected for the adapter.

  4. If the server is not running, right-click your server in the Servers view and select Start.
  5. When the server status changes to Started, right-click the server and select Administration > Run administrative console.

  6. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  7. On the Step 2: Map modules to servers window, select the module and click Next. For the embedded adapter option, the adapter is deployed as part of the application.

  8. In the Enterprise Applications view, select the new application <adapter_name>EmbeddedModuleApp. The new application is displayed after the application is deployed at the deployment manager level.

  9. Select the node and click Installed applications to view the deployed application on each individual node.

The resource adapter is embedded and deployed as part of the application.


Feedback


Deploy module at node level with embedded activation specification

The adapter is deployed at the node level, with the activation specification created during module creation. The adapter can be shared across multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use properties below.

  3. Create the module as described in the Business process management samples for WebSphere Adapters.

  4. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter. Here, the adapter is not part of the module, therefore you must deploy the adapter before deploying the application.

  5. If the server is not running, right-click your server in the Servers view and select Start.
  6. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  7. To deploy the adapter at individual nodes, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  8. In the Resource adapters page, click Install RAR.

  9. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  10. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  11. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  12. Click Save in the Messages box at the top of the page.

  13. For node level deployment, check if the adapter RAR is deployed at the node level.
  14. To deploy the adapter at the cluster level, click Resources > Resource Adapters > Resource adapters.

  15. In the Resource adapters window, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level.
  17. Check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  18. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  19. On the Step 2: Map modules to servers window, select the module and click Next. The adapter is not part of the deployed application.

  20. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for Email > J2C activation specifications to view the activation specification from the adapter deployed at the cluster level.

The resource adapter is deployed at the node level, with the activation specification.


Feedback


Deploy module at node level with JNDI activation specification

The adapter is deployed at the node level, and the application provides a JNDI reference to the activation specification. Create the activation specification with the same JNDI name at the cluster scope from the administrative console. The adapter can be shared across multiple applications

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use JNDI lookup name configured on server.

  3. In the JNDI lookup name property field, specify the JNDI name. Use this same JNDI name when you create the activation specification from the Admin Console.

  4. Create the module as described in the Business process management samples for WebSphere Adapters.

  5. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter.

  6. If the server is not running, right-click your server in the Servers view and select Start.
  7. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  8. To install the adapter at the node level, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  9. In the Resource adapters page, click Install RAR.

  10. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  11. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  12. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  13. Click Save in the Messages box at the top of the page.
  14. To install the RAR at the cluster level, click Resources > Resource Adapters > Resource adapters

  15. In the Resource adapters page, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level, and then check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  17. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  18. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for Email > J2C activation specifications > New to create the activation specification from the adapter deployed at the cluster level.
  19. When installing the adapter, in the Name field, enter the same name as defined in the RAR.

  20. In the JNDI name field, enter the same name as given during the module creation.

  21. Click Resources > Resource Adapters > IBM WebSphere Adapter for Email > J2C activation specifications to check if the JNDI reference on the adapter is same as the one specified for the module.

  22. Click Resources > Resource Adapters > IBM WebSphere Adapter for Email > J2C activation specifications > Custom properties to set values for the activation specification in the Admin Console.

  23. From the Deployment Manager Admin console, click Install applications to deploy the application after you deploy the RAR and create the activation specification.

  24. On the Step 2: Map modules to servers page, select the module and click Next. The adapter is not part of the deployed application.

The resource adapter is deployed at the node level, with the JNDI activation specification reference.


Feedback


Administer the adapter module

When you are running the adapter in a stand-alone deployment, use the administrative console of the server to start, stop, monitor, and troubleshoot the adapter module. In an application that uses an embedded adapter, the adapter module starts or stops when the application is started or stopped.


Feedback


Configure logging and tracing

Configure logging and tracing to suit your requirements. Enable logging for the adapter to control the status of event processing. Change the adapter log and trace file names to separate them from other log and trace files.



Previous topic: Deploy the module for production


Next topic: Start the application that uses the adapter


Related tasks:

Troubleshooting and support

Feedback


Configure logging properties

Use the administrative console to enable logging and to set the output properties for a log, including the location, level of detail, and output format of the log. Before the adapters can log monitored events, you must specify the service component event points to monitor, what level of detail you require for each event, and format of the output used to publish the events to the logs. Use the administrative console to perform the following tasks:

For more information about monitoring on a Process Server, including service components and event points, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.admin.doc/topics/welcome_wps_mon.html.

You can change the log configuration statically or dynamically. Static configuration takes effect when you start or restart the application server. Dynamic or run time configuration changes apply immediately.

When a log is created, the detail level for that log is set from the configuration data. If no configuration data is available for a particular log name, the level for that log is obtained from the parent of the log. If no configuration data exists for the parent log, the parent of that log is checked, and so on, up the tree, until a log with a non-null level value is found. When you change the level of a log, the change is propagated to the child logs, which recursively propagate the change to their child log, as necessary.

To enable logging and set the output properties for a log, use the following procedure.

  1. In the navigation pane of the administrative console, select Servers > WebSphere application servers.

  2. Click the name of the server to work with.

  3. Under Troubleshooting, click Logging and tracing.

  4. Click Change log detail levels.

  5. Specify when you want the change to take effect:

    • For a static change to the configuration, click the Configuration tab.

    • For a dynamic change to the configuration, click the Runtime tab.

  6. Click the names of the packages whose logging level you want to modify. The package names for WebSphere Adapters start with com.ibm.j2ca.*:

    • For the adapter base component, select com.ibm.j2ca.base.*.

    • For the adapter base component and all deployed adapters, select com.ibm.j2ca.*.

    • For the WebSphere Adapter for Email only, select the com.ibm.j2ca.email.* package.

  7. Select the logging level.

    Logging Level Description
    Fatal The task cannot continue or the component cannot function.
    Severe The task cannot continue, but the component can still function. This logging level also includes conditions that indicate an impending fatal error, that is, situations that strongly suggest that resources are on the verge of being depleted.
    Warning A potential error has occurred or a severe error is impending. This logging level also includes conditions that indicate a progressive failure, for example, the potential leaking of resources.
    Audit A significant event has occurred that affects the server state or resources.
    Info The task is running. This logging level includes general information outlining the overall progress of a task.
    Config The status of a configuration is reported or a configuration change has occurred.
    Detail The subtask is running. This logging level includes general information detailing the progress of a subtask.

  8. Click Apply.

  9. Click OK.

  10. To have static configuration changes take effect, stop and then restart the Process Server.

Log entries from this point forward contain the specified level of information for the selected adapter components.


Feedback


Change the log and trace file names

To keep the adapter log and trace information separate from other processes, use the administrative console to change the file names. By default, log and trace information for processes and applications on a Process Server is written to the SystemOut.log and trace.log files.

You can change the log and trace file names at any time after the adapter module has been deployed to an application server. You can change the log and trace file names statically or dynamically. Static changes take effect when you start or restart the application server. Dynamic or run time changes apply immediately.

Log and trace files are in the install_root/profiles/profile_name/logs/server_name folder.

To set or change the log and trace file names, use the following procedure.

  1. In the navigation pane of the administrative console, select Applications >Application Types>WebSphere enterprise applications.

  2. In the Enterprise Applications list, click the name of the adapter application. This is the name of the EAR file for the adapter, but without the ear file extension. For example, if the EAR file is named Accounting_OutboundApp.ear, then click Accounting_OutboundApp.

  3. In the Configuration tab, select Modules>Manage Modules.

  4. In the list of modules, click IBM WebSphere Adapter for Email.

  5. In the Configuration tab, under Additional Properties, click Resource Adapter.

  6. In the Configuration tab, under Additional Properties, click Custom properties.

  7. In the Custom Properties table, change the file names.

    1. Click either logFilename to change the name of the log file or traceFilename to change the name of the trace file.

    2. In the Configuration tab, type the new name in the Value field. By default, the log file is called SystemOut.log and the trace file is called trace.log.

    3. Click Apply or OK. Your changes are saved on your local machine.
    4. To save your changes to the master configuration on the server, use one of the following procedures:

      • Static change: Stop and restart the server. This method allows you to make changes, but those changes do not take effect until you stop and start the server.
      • Dynamic change: Click the Save link in the Messages box above the Custom properties table. Click Save again when prompted.


Feedback


Change configuration properties for embedded adapters

To change the configuration properties after you deploy the adapter as part of a module, use the administrative console of the runtime environment. You can update resource adapter properties (used for general adapter operation), managed connection factory properties (used for outbound processing), and activation specification properties (used for inbound processing). For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.



Related reference:

Configuration properties

Feedback


Set resource adapter properties for embedded adapters

To set resource adapter properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change. The Configuration page is displayed.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Email.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click Custom properties.

  10. For each property you want to change.

    See Resource adapter properties for more information about these properties.

    1. Click the name of the property.

      The Configuration page for the selected property is displayed.

    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. In the Messages area, click Save.

The resource adapter properties associated with your adapter module are changed.



Related tasks:

Set managed (J2C) connection factory properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for embedded adapters

To set managed connection factory properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target mail server instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. In the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Email.

  8. In the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C connection factories.

  10. Click the name of the connection factory associated with your adapter module.

  11. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to IBM WebSphere Adapter for Email. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  12. For each property you want to change.

    See Managed connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The managed connection factory properties associated with your adapter module are changed.



Related tasks:

Set resource adapter properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Managed connection factory properties

Feedback


Set activation specification properties for embedded adapters

To set activation specification properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Email.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C activation specifications.

  10. Click the name of the activation specification associated with the adapter module.

  11. From the Additional Properties list, click J2C activation specification custom properties.

  12. For each property you want to change.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The activation specification properties associated with your adapter module are changed.



Related tasks:

Set resource adapter properties for embedded adapters

Set managed (J2C) connection factory properties for embedded adapters


Related reference:

Activation specification properties

Feedback


Change configuration properties for stand-alone adapters

To set configuration properties after you install a stand-alone adapter, use the administrative console of the runtime environment. Provide the general information about the adapter and then set the resource adapter properties (which are used for general adapter operation). If the adapter is used for outbound operations, create a connection factory and then set the properties for it. If the adapter is used for inbound operations, create an activation specification and then set the properties for it. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.


Feedback


Set resource adapter properties for stand-alone adapters

To set resource adapter properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Email.

  6. In the Additional Properties list, click Custom properties.

  7. For each property you want to change.

    See Resource adapter properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  8. In the Messages area, click Save.

The resource adapter properties associated with your adapter are changed.



Related reference:

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for stand-alone adapters

To set managed connection factory properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target mail server instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Email.

  6. In the Additional Properties list, click J2C connection factories.

  7. To use an existing connection factory, skip ahead to select from the list of existing connection factories.

    If you have selected Specify connection properties when use the external service wizard to configure the adapter module, you do not need to create a connection factory.

    If you are creating a connection factory, perform the following steps:

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the connection factory. For example, you can type AdapterCF.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterCF.

    4. Optional: Select an authentication alias from the Component-managed authentication alias list.

    5. Click OK.

    6. In the Messages area, click Save.

      The newly created connection factory is displayed.

      Figure 1. User-defined connection factories for use with the resource adapter

  8. In the list of connection factories, click the one you want to use.

  9. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to WebSphere Adapter for Email. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  10. For each property you want to change.

    See Managed connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The managed connection factory properties associated with your adapter are set.



Related reference:

Managed connection factory properties

Feedback


Set activation specification properties for stand-alone adapters

To set activation specification properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Email.

  6. In the Additional Properties list, click J2C activation specifications.

  7. To use an existing activation specification, skip ahead to select from an existing list of activation specifications.

    If you have selected Use predefined connection properties when use the external service wizard to configure the adapter module, create an activation specification.

    If you are creating an activation specification.

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the activation specification. For example, you can type AdapterAS.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterAS.

    4. Optional: Select an authentication alias from the Authentication alias list.

    5. Select a message listener type.

    6. Click OK.

    7. Click Save in the Messages box at the top of the page.

      The newly created activation specification is displayed.

  8. In the list of activation specifications, click the one you want to use.

  9. In the Additional Properties list, click J2C activation specification custom properties.

  10. For each property you want to set.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The activation specification properties associated with your adapter are set.



Related reference:

Activation specification properties

Feedback


Start the application that uses the adapter

Use the administrative console of the server to start an application that uses the adapter. By default, the application starts automatically when the server starts.

Use this procedure to start the application, whether it is using an embedded or a stand-alone adapter. For an application that uses an embedded adapter, the adapter starts when the application starts. For an application that uses a stand-alone adapter, the adapter starts when the application server starts.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to start. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Start.

The status of the application changes to Started, and a message stating the application has started displays at the top of the administrative console.



Previous topic: Configure logging and tracing


Related tasks:

Stop the application that uses the adapter

Feedback


Stop the application that uses the adapter

Use the administrative console of the server to stop an application that uses the adapter. By default, the application stops automatically when the server stops.

Use this procedure to stop the application, whether it is using an embedded or a stand-alone adapter. For an application with an embedded adapter, the adapter stops when the application stops. For an application that uses a stand-alone adapter, the adapter stops when the application server stops.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to stop. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Stop.

The status of the application changes to Stopped, and a message stating the application has stopped is displayed at the top of the administrative console.



Related tasks:

Start the application that uses the adapter

Feedback


Monitor performance using Performance Monitoring Infrastructure

Performance Monitoring Infrastructure (PMI) is a feature of the administrative console that allows you to dynamically monitor the performance of components in the production environment, including IBM WebSphere Adapter for Email. PMI collects adapter performance data, such as average response time and total number of requests, from various components in the server and organizes the data into a tree structure. You can view the data through the Tivoli Performance Viewer, a graphical monitoring tool that is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus. You can monitor the performance of your adapter by having PMI collect data at the following points:

Before you enable and configure PMI for your adapter, you must first set the level of tracing detail and run some events from which to gather performance data.

To learn more about how PMI can help you monitor and improve the overall performance of your adapter environment, search for PMI on the BPM or WebSphere Enterprise Service Bus website: http://www.ibm.com/software/webservers/appserv/was/library/.

  1. Configure Performance Monitoring Infrastructure You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.
  2. View performance statistics You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.


Feedback


Configure Performance Monitoring Infrastructure

You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.

Before you can configure PMI for your adapter, you must first set the level of tracing detail and run some events to gather the performance data.

  1. To enable tracing and to receive event data, the trace level must be set to either fine, finer, finest, or all. After *=info, add a colon and a string, for example: 
    *=info: WBILocationMonitor.CEI.ResourceAdapter.
*=finest: WBILocationMonitor.LOG.ResourceAdapter.*=finest:
    For instructions on setting the trace level, see Enable tracing with the Common Event Infrastructure.
  2. Generate at least one outbound request or inbound event to produce performance data that you can configure.

  1. Enable PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select the Configuration tab, and then select the Enable Performance Monitoring (PMI) check box.

    4. Select Custom to selectively enable or disable statistics.

      Figure 1. Enabling Performance Monitoring Infrastructure

    5. Click Apply or OK.

    6. Click Save. PMI is now enabled.

  2. Configure PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select Custom.

    4. Select the Runtime tab. The following figure shows the Runtime tab.

      Figure 2. Runtime tab used for configuring PMI

    5. Click WBIStats.RootGroup. This is a PMI sub module for data collected in the root group. This example uses the name WBIStats for the root group.

    6. Click ResourceAdapter. This is a sub module for the data collected for the JCA adapters.

    7. Click the name of your adapter, and select the processes you want to monitor.

    8. In the right pane, select the check boxes for the statistics you want to gather, and then click Enable.

PMI is configured for your adapter.


Now you can view the performance statistics for your adapter.



Next topic: View performance statistics

Feedback Infrastructure (PMI), Tivoli Performance Viewer, IBM WebSphere Adapter for Email


View performance statistics

You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.

Configure Performance Monitoring Infrastructure for your adapter.

  1. In the administrative console, expand Monitoring and Tuning, expand Performance Viewer, then select Current Activity.

  2. In the list of servers, click the name of your server.

  3. Under your server name, expand Performance Modules.

  4. Click WBIStatsRootGroup.

  5. Click ResourceAdapter and the name of your adapter module.

  6. If there is more than one process, select the check boxes for the processes whose statistics you want to view.

The statistics are displayed in the right panel. You can click View Graph to view a graph of the data, or View Table to see the statistics in a table format.

The following figure shows adapter performance statistics.

Figure 1. Adapter performance statistics, using graph view



Previous topic: Configure Performance Monitoring Infrastructure

Feedback


Enable tracing with the Common Event Infrastructure

The adapter can use the Common Event Infrastructure (CEI), a component embedded in the server, to report data about critical business events such as the starting or stopping of a poll cycle. Event data can be written to a database or a trace log file depending on configuration settings.

Use this procedure to report CEI entries in the trace log file by using the Common Base Event Browser within the administrative console.

  1. In the administrative console, click Troubleshooting.

  2. Click Logs and Trace.

  3. From the list of servers, click the name of your server.

  4. In the Change Log Detail Levels box, click the name of the CEI database ( WBIEventMonitor.CEI.ResourceAdapter.*) or the trace log file ( WBIEventMonitor.LOG.ResourceAdapter.*) to which you want the adapter to write event data.

  5. Select the level of detail about business events that you want the adapter to write to the database or trace log file, and (optionally) adjust the granularity of detail associated with messages and traces.

    • No Logging. Turns off event logging.
    • Messages Only. The adapter reports an event.
    • All Messages and Traces. The adapter reports details about an event.
    • Message and Trace Levels. Settings for controlling the degree of detail the adapter reports about the business object payload associated with an event. To create adjust the detail level, select one of the following options:

      Fine. The adapter reports the event but none of the business object payload.

      Finer. The adapter reports the event and the business object payload description.

      Finest. The adapter reports the event and the entire business object payload.

      The WebSphere Adapter for Email also provides the following logging information.

      • Logs all the SMTP, POP, and IMAP commands issued to the mail server and their responses in the trace log file.
      • Logs the adapter foundation class (AFC) version, Java™ Mail API version, and third-party version artifacts in the trace file.

  6. Click OK.

Event logging is enabled. You can view CEI entries in the trace log file or by using the Common Base Event Browser within the administrative console.


Feedback


Troubleshooting and support

Common troubleshooting techniques and self-help information help you identify and solve problems quickly. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.



Related tasks:

Configure logging and tracing


Related reference:

Messages

Adapter messages

Feedback


Techniques for troubleshooting problems

Certain common techniques can help with the task of troubleshooting.

The first step in the troubleshooting process is to describe the problem completely. Without a problem description, neither you or IBM can know where to start to find the cause of the problem. This step includes asking yourself basic questions, such as:

The answers to these questions typically lead to a good description of the problem, and that is the best way to start down the path of problem resolution.


What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is the problem?" Which might seem like a straightforward question; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:


Where does the problem occur?

Determining where the problem originates is not always simple, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few components to be considered when you are investigating problems.

The following questions can help you to focus on where the problem occurs in order to isolate the problem layer.

Remember that if one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software not intended to run together or have not been fully tested together.


When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for those cases that are one-time occurrences. You can most simply do this by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log; however, this is not always simple to do and takes practice. Knowing when to stop looking is especially difficult when multiple layers of technology are involved, and when each has its own diagnostic information.

To develop a detailed timeline of events, answer the following questions:

Responding to these types of questions can provide you with a frame of reference in which to investigate the problem.


Under which conditions does the problem occur?

Knowing what other systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These and other questions about the environment can help you to identify the root cause of the problem:

Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might have occurred around the same time, the problems are not necessarily related.


Can the problem be reproduced?

From a troubleshooting standpoint, the "ideal" problem is one that can be reproduced. Typically with problems that can be reproduced, you have a larger set of tools or procedures at your disposal to help you investigate. Consequently, problems that you can reproduce are often simpler to debug and solve. However, problems that you can reproduce can have a disadvantage: If the problem is of significant business impact, you do not want it to recur! If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation.

Tip: Simplify the scenario to isolate the problem to a suspected component.

The following questions can help you with reproducing the problem:


Feedback


Adapter returns version conflict exception message


Adapter returns version conflict exception message

Problem

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for Email version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for Email" as IBM WebSphere Adapter for Email loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. To overcome this conflict, you must migrate all adapters to the same version level.

Solution

Migrate all adapters to the same version level.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


Feedback


Log and Trace Analyzer

The adapter creates log and trace files that can be viewed with the Log and Trace Analyzer.

The Log and Trace Analyzer can filter log and trace files to isolate the messages and trace information for the adapter. It can also highlight the adapter's messages and trace information in the log viewer.

The adapter's component ID for filtering and highlighting is a string composed of the characters EMARA plus the value of the adapter ID property. For example, if the adapter ID property is set to 001, the component ID is EMARA001.

If you run multiple instances of the same adapter, ensure the first eight characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter. For example, when you set the adapter ID property of two instances of WebSphere Adapter for Email to 001 and 002. The component IDs for those instances, EMARA001 and EMARA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to EMARAInstanc.

For outbound processing, the adapter ID property is located in both the resource adapter and managed connection factory property groups. If you update the adapter ID property after using the external service wizard to configure the adapter for outbound processing, be sure to set the resource adapter and managed connection factory properties consistently. It prevents inconsistent marking of the log and trace entries. For inbound processing, the adapter ID property is located only in the resource adapter properties, so this consideration does not apply.

The data binding component, which converts between business objects and the native data formats in e-mail text and attachments, does not use the adapter component ID when generating log and trace messages. Instead, it uses a string that indicates which data binding generated the message. Table 1 lists the component ID used by each adapter-specific data binding for WebSphere Adapter for Email. For custom data bindings, the data binding must set the component ID.

Component IDs for adapter-specific data bindings

Data binding Component ID
EmailSimpleDataBinding EMARASEDB
EmailWrapperDataBinding EMARAEWDB
EmailFixedStructureDataBinding EMARAFSDB

See the Adapter ID (AdapterID) property.


Feedback


First-failure data capture (FFDC) support

The adapter supports first-failure data capture (FFDC), which provides persistent records of failures and significant software incidents that occur during run time in BPM or WebSphere Enterprise Service Bus.

The FFDC feature runs in the background and collects events and errors that occur at run time. The feature provides a means for associating failures to one another, allowing software to link the effects of a failure to their causes, and facilitate the quick location of the root cause of a failure. The data that is captured can be used to identify exception processing that occurred during the adapter run time.

When a problem occurs, the adapter writes exception messages and context data to a log file, which is in the install_root/profiles/profile/logs/ffdc directory.

For more information about first-failure data capture (FFDC), see the BPM or WebSphere Enterprise Service Bus documentation.


Feedback


Disable end point applications of the passive adapter

Problem

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events or messages even if the enableHASupport property is set to True.

Cause

By default, in WebSphere Application Server, the alwaysactivateAllMDBs property in the JMS activation specification is set to True. This enables the endpoint application of all the adapter (active or passive) instances to listen to the events.

Solution

To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. The JMS activation specification is associated with one or more MDBs and provides the necessary configuration to receive events. If the alwaysActivateAllMDBs property is set to False, then the endpoint application of only the active adapter instance receives the events.

Perform the following procedure, to set the alwaysActivateAllMDBs property to False.

  1. Log on to the administrative console.
  2. Go to Resources> JMS > Activation specifications.

  3. Click the activation specification corresponding to the application from the list.

  4. Click Custom properties under Additional properties.

  5. Click alwaysActivateAllMDBs.
  6. Change the value to False.

  7. Click Apply and OK.

Result

The endpoint application of only the active adapter instance listens to the events.


Feedback


Solutions to common problems

Some of the problems you might encounter while running WebSphere Adapter for Email with the database are described along with solutions and workaround. These problems and solutions are in addition to those documented as technotes on the software support website.

For a complete list of technotes about WebSphere Adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.


Adapter returns version conflict exception message

Problem

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for Email version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for Email" as IBM WebSphere Adapter for Email loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. To overcome this conflict, you must migrate all adapters to the same version level.

Solution

Migrate all adapters to the same version level.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


Unable to start adapter through webservices

Problem

After configuring the adapter, you might note that:

  1. the webservices client based on the WSDL is not getting generated properly in IBM Integration Designer.
  2. you may not be able to invoke the WSDL using certain webservices client, such as RESTUI firefox plugin and soapUI tool.

Solution

Perform the following steps to enable the adapter module to load the ASI file.

  1. Create a library project.
  2. Change to the Enterprise Explorer view in IBM Integration Designer.

  3. Locate the ASI file of the adapter in connector project -> connectorModule.
  4. Copy the ASI file of the adapter and paste it in the library project.

  5. Add the library project to the list of dependencies for the adapter module.
  6. Clean project.


Feedback

Support

This section provides information about how to troubleshoot a problem with your IBM software, including instructions for searching knowledge bases, downloading fixes, and obtaining support.


Feedback


Searching knowledge bases (Web search)

You can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.

You can find useful information by searching the information center for Product X. However, sometimes you need to look beyond the information center to answer your questions or resolve problems.

To search knowledge bases for information that you need, use one or more of the following approaches:

Tip: Include "IBM" and the name of the product in your search if you are looking for information about an IBM product.


Feedback


Getting Fixes

A product fix might be available to resolve your problem.

To get product fixes.

  1. Determine which fix you need. Check the list of IBM WebSphere Adapter for Email recommended fixes to confirm that your software is at the latest maintenance level. Check the list of problems fixed in the IBM WebSphere Adapter for Email fix readme documentation that is available for each listed fix pack to see if IBM has already published an individual fix to resolve your problem. To determine what fixes are available using IBM Support Assistant, run a query on fix from the search page.

    Individual fixes are published as often as necessary to resolve defects in BPM or WebSphere Enterprise Service Bus IBM WebSphere Adapter for Email. In addition, two kinds of cumulative collections of fixes, called fix packs and refresh packs, are published periodically for IBM WebSphere Adapter for Email, in order to bring users up to the latest maintenance level. You should install these update packages as early as possible in order to prevent problems.

    A list of recommended, generally available (GA) fixes for the WebSphere Java™ Connector Architecture (JCA) and WebSphere Business Integration adapters are available here. If a Fix Pack is not available for an adapter, it implies the GA version is the recommended version and details about that version of the adapter can be found in the Release notes.

  2. Download the fix. Open the download document and follow the link in the Download package section. When downloading the file, ensure the name of the maintenance file is not changed. This includes both intentional changes and inadvertent changes caused by certain web browsers or download utilities.
  3. Apply the fix. Follow the instructions in the Installation Instructions section of the download document.

  4. To receive weekly notification of fixes and updates, subscribe to My Support e-mail updates.


Feedback


Self-help resources

Use the resources of IBM software support to get the most current support information, obtain technical documentation, download support tools and fixes, and avoid problems with WebSphere Adapters. The self-help resources also help you diagnose problems with the adapter and provide information about how to contact IBM software support.


Support website

The WebSphere Adapters software support website at http://www.ibm.com/support/docview.wss?uid=swg27006249 provides links to many resources to help you learn about, use, and troubleshoot WebSphere Adapters, including:


Recommended fixes

A list of recommended fixes apply is available at the following location: http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397.


Technotes

Technotes provide the most current documentation about WebSphere Adapter for Email, including the following topics:

For a list of technotes for WebSphere Adapter for Email, see http://www-01.ibm.com/support/docview.wss?uid=swg27024034.

For a list of technotes for all adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.


Feedback


Reference information

To support you in your tasks, reference information includes details about business objects that are generated by the external service wizard and information about adapter properties, including those that support bidirectional transformation. It also includes pointers to adapter messages and related product information.


Feedback


Business object information

A business object is a structure that contains specific information about an email being processed by an inbound or outbound module. Business objects contain information about how the adapter processes the email content and attachments, and also how the business objects are associated with an operation (such as Create). Business object names are generated by the external service wizard and are named according to their contents.


Feedback


Business object structures

The adapter supports three different types of business object structures: simple alert email, email business object, and a user-defined type business object. The simple alert email structure sends text-only messages without attachments, the email business object sends and receives all types of messages both for transformed and non-transformed types, and the user-defined type sends and receives your own fixed structure transformed type messages only.

All the business object structures include standard headers such as To and From in the wrapper business object. For more information about the headers supported by the adapter, see Header business object properties.


Simple alert email business object structure

The simple alert email business object structure (SimpleAlertEmail) sends a single string email message to the mail server. This structure is supported only during the outbound communication. With the SimpleAlertEmail structure, the email message does not undergo any formatting or transformation. The intended recipient is a human and the body mime type is text/plain. As shown in the following illustration, it is composed of a single business object.

Figure 1. SimpleAlertEmail business object structure

With this business object structure, the only required values are the From and To fields. For more information about the values of the SimpleAlertEmail business object structure, see the section on the SimpleAlertEmail business object structure in the reference section of this documentation.


Email business object structure

The email business object structure is used both during inbound and outbound communication. The adapter always creates an email business object for its specific use. The email business object is a parent business object consisting of attributes that directly relate to the fields in an email message. If you choose, it can also contain child business objects for email mailContent business object and attachments. The following illustration shows the email business object with two child business objects: header and mailAttachments.

Figure 2. Email business object with mail attachment and header child objects

The header child business object shown in Figure 2 stores header information for an email. The headerList attribute in the email wrapper object is an array of header business objects. The headerList attribute might contain all the headers for an email, each represented by a header business object. However, the standard headers present in the email wrapper business object takes precedence over the headers in the headerList attribute.

Bcc and Resent-bcc headers, cannot be retrieved from an inbound email, but they can be set for outbound emails.

For each attachment on an inbound email, the adapter creates a separate mail attachment business object. For every mail attachment business object the adapter receives during outbound communications, the adapter creates a separate email attachment. As noted in the illustration, the mail attachment business object consists of an attachment name and the data in the attachment.

The data in an attachment can be of any type. Business objects such as Customer or PurchaseOrder, which is defined in the business object editor before being processed by the external service wizard and have a specific structure outlined by you, are called structured content business objects. Similarly, you can specify a structured business object for the mailContent attribute of the email wrapper business object.

Structured content business objects are decomposed by the data binding and their content is recorded into individual logical fields within the business object structure. Unstructured content business objects are provided by the adapter and allow a user to send string (AsText) or bytes (AsBinary) through the adapter. Unstructured content business objects are used for pass-through processing during outbound communication.

Because the adapter is expected to decompose each business object added to the module, you must define a data binding mime type and a data handler during the data binding configuration portion of the external service wizard. The adapter does not automatically associate a data binding mime type and data handler type with your business object because it has no way of knowing what type of conversion is necessary for the import objects.

The following illustration shows a mail attachment business object with a customer child object.

Figure 3. Mail attachment business object with structured content child object

Unstructured content business objects are used to store unstructured data, such as rich text, PDF, or images (as binary content). They are not decomposed by the data binding because their content is not placed into specific fields in the business object. Instead, unstructured content is supplied as a single string or binary field in the business object structure. The following illustration shows a mail attachment business object with an unstructured content child object.

Figure 4. Mail attachment business object with unstructured content

Unstructured business objects have the following attributes:

Unstructured business object attributes

Attribute name Value
Content type Type of content sent. For example, text/xml, application/binary, or image/jpeg.
AsText Value to be sent as email text
AsBinary Value to be sent as binary data


User-defined business object structure

Like the email business object structure, the user-defined business object structure consists of attributes that directly relate to the fields in an email message and child business objects for email attachments and headers. While the email business object structure can contain child objects of any type, the user-defined business object structure requires that you know the structure of all emails being sent or received by the adapter in advance. For example, if all incoming and outgoing emails contain mail content of customer type, attachment1 of account type, and attachment2 of account type, as shown in User-defined business object structure with child objects.

By selecting the user-defined data type in the external service wizard, you can define your own fixed structure wrapper business object. This configuration enables you to use ordinary mapping tools to consume and work with your business objects without having to determine the business object type at run time.

The following illustration shows an example of a user-defined business object with Order, Customer, and Account child business objects.

Figure 5. User-defined business object structure with child objects

If you select user-defined email business object in the external service wizard when creating your inbound module, the adapter only processes events symmetric to the user-defined email business object you define in the EmailFixedStructureDataBinding data binding. If the adapter receives an event that is not symmetric to the specified custom data type, it does not process the event. Instead, the adapter throws an exception with the appropriate error message.

The adapter logs an error if an event:



Related reference:

Supported operations

Interaction specification properties

Feedback


Supported operations

Each business object is associated with an operation, such as create. Operations might be stored in a business graph, which is like an enhanced business object, if you choose to use business graphs. Each operation tells the adapter what to do with the business object. For outbound communication, there are three different create operations used to create an email from the contents of a business object. For inbound communication, only the emit email operation is supported.


Create email

In the external service wizard, you specify a name for the operation. This name can be anything meaningful to you, such as SendEmail or SendEmailwithBO. The operations listed here represent the three examples of types of outbound create options the adapter can start. The emit operation is always used for inbound communication, as it is the only supported inbound operation.

The create email operation is used with the email business object. When started, the create email operation creates an email message from the attributes in the email business object.


Create address

The address operation is used when the adapter creates an email from a fixed structure business object that includes an address business object.


Create customer

The create customer operation is used when the adapter creates an email from a fixed structure business object that includes a customer business object.


Emit email

For inbound communication, emit email is the only supported operation. When started, this operation instructs the adapter to take information from an email and convert it to representative business objects.



Related concepts:

Business objects

Business object structures

Feedback


Naming conventions

When the external service wizard generates a business object, it provides a name for the business object based on the business object schema file (XSD file) name.

When the external service wizard provides the business object name, it converts the name of the object to mixed case, which means that it removes any separators, such as spaces or underscores, and then capitalizes the first letter of each word. For example, if the external service wizard uses a mail server object called CUSTOMER_ADDRESS to generate a business object, it generates a business object called CustomerAddress.

The generated business object name can indicate the structure of the business object. Names are derived during the metadata import process and are the same as the name given by the user to the pre-generated XSD files. Business objects names have no semantic value to the adapter. It means that if you change the business object name, the behavior of the business object remains the same.

If you choose to rename a business object, use the refactoring functionality in IBM Integration Designer to ensure that you update all the business object dependencies. For instructions on using refactoring to rename business objects, refer to the following link: http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.bpel.doc/selector/topics/trefacts.html.

Business graphs take the name of the business object followed by "BG". For example, a business graph for a customer business object would be called CustomerBG.

Business graph generation is optional.


Feedback


Email business object properties

During external service discovery, the adapter generates the email business object. This parent business object includes all the header, encoding, and mail content details the adapter needs to process both inbound and outbound requests.

The following table lists the attributes of the email business object. For the simple alert email business object structure, a number of header fields (such as To and From) are part of the email wrapper business object. These header fields are not part of the email wrapper business object with other business object structures (such as the generic email data type). For this reason, all the header values available in the simple alert email wrapper business object are not listed in this topic. For a list and description for each of the properties available in the simple alert email version of the wrapper business object, see Header business object properties.

Each property available with all versions of the email business object is described completely in the sections that follow the table.

In business object attributes, the use of the [] symbol denotes an array of values.

Email business object attributes

Business object attribute name Description
Encode Contains outbound data encoding information when you do not use data transformation.
File references Contains the list of files that must be attached to an outbound email.
Header list Contains header details for all the headers listed in an inbound email request.
Mail attachments Stores the content for the attachments of an email.
Mail content Stores the content for the body of an email. This attribute does not include email attachments.


Encode

This attribute is set during outbound communications to indicate the type of character encoding the adapter will use.

Encoding details

Required No
Default No default value
Attribute type String
Usage Encode is used for headers, mail content, and attachment business objects.
Example The following are the examples of the encoding attribute:

  • ASCII for character encoding based on the English alphabet
  • Big5 for character encoding based on traditional Chinese characters
  • GB18030 for globalized characters in a business graph

Globalized No
Bidi supported No


File references

This attribute contains a list of files that must be attached to an outbound email. This attribute is not used during inbound processing.

File references details

Required No
Default No default value
Attribute type String []
Usage During outbound communication, the run time specifies absolute paths for the referenced files listed in this field. The adapter reads these files, which are on the local system with the adapter, and includes them as attachments to the outbound email.
Globalized Yes
Bidi supported No


Header List

This attribute is populated with the header details for all the headers listed in a polled email request.

Header list details

Required No
Default No default value
Attribute type Header[]
Usage Headers are the fields in an email, such as To, From, Cc, Bcc, and Subject.
Globalized Yes
Bidi supported Yes


Mail attachments

This attribute stores the content details for an attachment in an inbound email request.

Mail attachments details

Required No
Default No default value
Attribute type MailAttachment[]
Usage Stores the content details for an attachment in an inbound email request.
Globalized Yes
Bidi supported No


Mail content

During inbound communication, this attribute stores any content found in the body of the email request. During outbound communication, this attribute contains the data that becomes the body of the email being sent to the mail server. This attribute does not include email attachments.

Mail content details

Required Yes
Default No default value
Attribute type anyType
Usage Contains body content of an email.
Globalized Yes
Bidi supported No


Feedback


Header business object properties

Header business object properties are used to store standard (RFC822) email headers and headers customized by you. They are populated dynamically by the adapter and comprise a name and value pair. Customized headers and their related information are tracked by the adapter with the help of the headerList entries in the email business object.

The adapter picks up the header name from the HeaderList property in the email business object. Each header can have multiple values, but Bcc and Resent-bcc headers cannot be retrieved from an email. However, they can be sent on an email.

All headers are encoded by the adapter in the specified character set. Because To and From header values are required, the adapter ends the outbound Create operation, if the encoding of either of those header values fails. The Java™ Mail API does not provide enough information to decipher the character set and encoding information for the header content; hence header content might not be globalized

The following table provides example header business object name and value pairs.

Examples of header business object name and value pairs

Name Value
HeaderName = to HeaderValue = abc@xyz.com
HeaderName = cc HeaderValue = def@xyz.com
HeaderName = mimetype HeaderValue = text/plain

The following table lists the Standard email Headers supported by the adapter. A more detailed description of each property is provided in the sections that follow the table. For more information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

Standard email Headers supported by the adapter

Property name Description
Bcc The blind carbon copy addresses for the email
Cc The email addresses for secondary recipients of the email
Comments Specifies whether text comments can be added to the message body
Date The date the email was created
Encrypted Specifies whether the body of a message was encrypted by the sender
From The address the email was sent from
In reply to Subject line of previous correspondence the email message is responding to
Keywords Keywords or phrases contained in the email separated by commas
Message identifier The unique identifier (local-part address unit) referring to the particular version of a particular message
References Other pieces of email correspondence referenced by this email
Reply to Addresses to which the responses to the email is sent
Resent - bcc Blind carbon copy addresses for the email
Resent - cc Email addresses for secondary or informational recipients of the email
Resent - date The date the email was forwarded
Resent - from The address the email was resent from
Resent - message identifier The unique identifier (local-part address unit) that refers explicitly to a particular version of a particular message
Resent - reply to Addresses to which the responses to the email is sent
Resent - sender Authenticated identity of the agent (person, system, or process) sending the email message
Resent - to Addresses of the primary recipients of the email
Sender Authenticated identity of the agent (person, system, or process) sending the email message
Subject Summary of what the email is about
To Addresses of the primary recipients of the email


Blind carbon copy (Bcc)

This property specifies blind carbon copy addresses for the email. The addresses listed in this field are not included in copies of the message sent to the primary and secondary recipients.

Blind carbon copy details

Required No
Default No default value
Property type String
Usage

This header is only supported for outbound communication. Some systems choose to include the text of the Bcc field only in the copy of the author, while some systems include these addresses to all those recipients listed in the Bcc field.

Globalized Yes
Bidi supported Yes


Carbon copy (Cc)

This property specifies the email addresses of secondary recipients of the email.

Carbon copy details

Required No
Default No default value
Property type String
Usage Specifies email addresses of secondary recipients of the email. All recipients listed in this field are visible to anyone receiving the email.
Globalized Yes
Bidi supported Yes


Comments

This property allows the addition of text comments to the message body without disturbing the message body content.

Comments details

Required No
Default No default value
Property type String
Usage Allows the addition of text comments to the message body without disturbing the message body content.
Bidi supported No


Date

The date set by the mail server of the sender during inbound processing. The date the email is created during outbound processing.

Date details

Required No
Default No default value
Property type String
Usage The date set by the mail server of the sender during inbound processing. The date the email is created during outbound processing.
Globalized Yes
Bidi supported Yes


Encrypted

This property indicates whether the body of a message was encrypted by the sender. If set to True, the message was encrypted.

Encrypted details

Required No
Default No default value
Property type String
Usage Set the encrypted header value to True does not enable encryption. This property only notes whether the message has been encrypted for informational purposes.
Bidi supported No


From

This property specifies the address the email was sent from.

From details

Required Yes
Default No default value
Property type String
Usage Specifies the address the email was sent from.
Globalized Yes
Bidi supported Yes


In reply to

The contents of this field identify which piece of previous correspondence is being answered with a new email message.

In reply to details

Required No
Default No default value
Property type String
Usage Identifies which piece of previous correspondence is being answered with a new email message.
Bidi supported No


Keywords

This property specifies keywords or phrases contained in the email, which are separated by commas.

Keywords details

Required No
Default No default value
Property type String
Usage Keywords specified using this field are used during selective polling.
Bidi supported No


Message Identifier (Message ID)

This property specifies the unique identifier (local-part address unit) that refers explicitly to a particular version of a particular message.

Message ID details

Required No
Default No default value
Property type String
Usage Each revision of an email message is assigned a new message ID. The uniqueness of the message ID is guaranteed by the host system that generates it. It is machine readable and does not include any meaningful syntax for users.
Bidi supported No


References

The contents of this field identify other pieces of email correspondence referenced by the email.

References details

Required No
Default No default value
Property type String
Usage Identifies other pieces of email correspondence referenced by the email.
Bidi supported No


Reply to

This property specifies the addresses where responses to the email are to be sent.

Reply to details

Required No
Default No default value
Property type String
Usage Specifies the addresses to which the response emails are to be sent.
Bidi supported No


Resent - blind carbon copy (Resent-bcc)

This property specifies the blind carbon copy addresses for the email.

Resent-blind carbon copy details

Required No
Default No default value
Property type String
Usage

This value is only supported during outbound communication. The addresses listed in this field are not included in copies of the message sent to the primary and secondary recipients. Some systems choose to include the text of the Bcc field only in the copy of the author, while some systems include these addresses to all those recipients listed in the Bcc field.

Bidi supported No


Resent - carbon copy (Resent-cc)

This property specifies the email addresses for secondary recipients of the email.

Resent-carbon copy details

Required No
Default No default value
Property type String
Usage Specifies the email addresses for secondary recipients of the email.
Bidi supported No


Resent - date

This property specifies the date the email was forwarded.

Resent - date details

Required No
Default No default value
Property type String
Usage Specifies the date the email was forwarded.
Bidi supported No


Resent - from

This property specifies the address the email was resent from.

Resent - from details

Required No
Default No default value
Property type String
Usage Specifies the address the email was resent from.
Bidi supported No


Resent message identifier (Resent-message-ID)

This property specifies the unique identifier (local-part address unit) that refers explicitly to a particular version of a particular message.

Resent-message-ID details

Required No
Default No default value
Property type String
Usage Each revised email message is assigned a new message ID. The uniqueness of the message ID is guaranteed by the host system that generates it. It is machine readable and does not include any meaningful syntax for users.
Bidi supported No


Resent - reply to

This property specifies the addresses where responses to the email are to be sent.

Resent reply to details

Required No
Default No default value
Property type String
Usage Specifies the addresses where responses to the email are to be sent.
Bidi supported No


Resent - sender

This property specifies the authenticated identity of the agent (person, system, or process) that is sending the email message.

Resent sender details

Required No
Default No default value
Property type String
Usage Specifies the authenticated identity of the agent (person, system, or process) that is sending the email message.
Bidi supported No


Resent - to

This field contains the addresses for the primary recipients of the email.

Resent - to details

Required No
Default No default value
Property type String
Usage Contains the addresses for the primary recipients of the email.
Bidi supported No


Sender

This property specifies the authenticated identity of the agent the (person, system, or process) that is sending the email message.

Sender details

Required No
Default No default value
Property type String
Usage Specifies the authenticated identity of the agent the (person, system, or process) that is sending the email message.
Bidi supported No


Subject

This property contains a summary of what the email is about.

Subject details

Required No
Default No default value
Property type String
Usage Contains a summary of what the email is about.
Globalized Yes
Bidi supported Yes


To

This field contains the addresses for the primary recipients of the email.

To details

Required No
Default No default value
Property type String
Usage Contains the addresses for the primary recipients of the email.
Globalized Yes
Bidi supported Yes


Feedback


Mail attachment business object properties

Each email attachment is stored in its own Mail Attachment object. Mail Attachment business objects consist of an attachment name and data worth of one email attachment.

During inbound processing, the attachments are parsed and the contents sent out as business objects. By default, each attachment is parsed into one MailAttachment business object. However, you can select to emit the entire email as a single email business object by setting the activation specification property Emit individual business objects from a multipart email to false in the external service wizard.

During outbound processing, IBM Business Process Manager or WebSphere Enterprise Service Bus sets the data within the MailAttachment business object. The data in this business object then becomes an email attachment when the email message is created by the adapter.

MailAttachment objects can store email attachments of any user-defined type (such as Customer or PurchaseOrder).

The following table describes the attribute values for the mail attachment business object. A more detailed description of each property is provided in the sections that follow the table. For more information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

MailAattachment business object attribute values

Attribute name Purpose
Attachment name The name of the email attachment
Application business object data (AppBOData) Data contained in the email attachment.


Attachment name

This attribute value specifies the name of the file attached to the email.

Attachment name attribute characteristics

Required Yes
Default No default value
Attribute type String
Usage The fully qualified path of the email attachment
Globalized Yes
Bidi supported No


Application business object data (AppBOData)

This attribute comprises the data in the file attached to the email.

Application business object data attribute characteristics

Required Yes
Default No default value
Attribute type

anyType

Usage

The anyType attribute type can hold hexBinary content or a child business-object.

For hexBinary type, the data binding deciphers the data and converts it to an unstructured content business object.

Globalized Yes
Bidi supported No


Feedback


Email outbound response business object properties

To support business faults, the WebSphere Adapter for Email must be configured to receive the outbound responses from the mail server. The response from the mail server contains recipient IDs to which the email is successfully delivered, the recipient IDs to which the email is not delivered, the delivery status, and the message ID of the email. The adapter then builds a response business object from the response received from the mail server.

You can configure the time period for which the adapter waits to receive a response from the mail server by setting the Response set timeout (ResponseSetTimeout) property.

The following table describes the attribute values for the email outbound response business object. A more detailed description of each property is provided in the sections that follow the table. For more information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

In the business object attributes description, the use of the [] symbol denotes an array of values.

Email outbound response business object attributes

Business object attribute name Description
DeliveredTo Contains the recipient addresses to which the email is delivered
UndeliveredTo Contains the recipient addresses to which the email is not delivered
Status Contains information about the delivery status of the email
MessageID Contains the message ID of the email


DeliveredTo

This attribute contains information about delivered recipient addresses.

Delivered email attribute details

Required No
Default No default value
Attribute type String []
Usage This attribute contains the list of all the email addresses to which the email is successfully delivered.
Globalized Yes
Bidi supported Yes


UndeliveredTo

This attribute contains information about undelivered recipient addresses.

Undelivered email attribute details

Required No
Default Null
Attribute type String []
Usage This attribute contains list of all the email addresses to which the email is not delivered and displays null if the email is delivered to all addresses.
Globalized Yes
Bidi supported Yes


Status

This attribute stores the delivery status of the email.

Status attribute details

Required No


+

Search Tips   |   Advanced Search