Getting connected with WebSphere Integration Developer adapters : Part 1, An introduction to connecting with adapters

In the Guided Tour of WebSphere® Integration Developer series, we covered the fundamentals of creating a service-oriented application using WebSphere Integration Developer. In the this series, we will explore how to integrate your application with enterprise information systems, e-mail systems and databases by treating them as reusable services that use resource adapters. In this article you learn what resource adapters are, how they can solve common business problems, and how to use them in your applications. In subsequent articles you will learn about specific adapters and build your own applications that use them. This content is part of the IBM WebSphere Developer Technical Journal.


John Green (, Advisory Staff Member , IBM Toronto Laboratory

Author photoJohn Green is a Senior Advisory Development Manager and technical team lead for WebSphere Integration Developer Adapter tooling. He is an expert on J2EE Connector Architecture, Enterprise Metadata Discovery Specification and accessing Enterprise Information Systems. John joined IBM in 1987, and worked on several other projects prior to working with adapters in VisualAge for Java, WebSphere Studio Application Developer Integration Edition, Rational Application Developer, and WebSphere Integration Developer. He received his B.Sc. in Computer Science from Queen's University in Kingston in 1987

Greg Adams (, Distinguished Engineer, IBM

Photo of Greg AdamsGreg Adams was the lead architect for the user interface in the award-winning Eclipse platform, and more recently, has been the lead architect and development lead in the core WebSphere Business Integration Tools, including WebSphere Studio Application Developer Integration Edition and WebSphere Integration Developer. Greg led the delivery of IBM's first complete services oriented architecture (SOA) tools stack and the first BPEL4WS standards supporting Business Process Editor; both critical deliverables in support of IBM's On Demand strategy.

Randy Giffen (, Senior Software Developer, IBM

Photo of Randy Giffen Randy Giffen is a senior software developer is the usability lead for WebSphere Integration Developer and WebSphere Message Broker Toolkit. He was responsible for WebSphere Integration Developer's business state machine tools and the visual snippet editor. Prior to to this he was a member of user interface teams for WebSphere Studio Application Developer Integration Edition, Eclipse, and VisualAge for Java.

Richard Gregory (, Staff Software Developer, IBM

Photo of Richard GregoryRichard Gregory is a software developer at the IBM Toronto Lab on the WebSphere Integration Developer team. His responsibilities include working on the evolution and delivery of test tools for WebSphere Integration Developer.

04 April 2007

Also available in Chinese Russian

Introduction – enterprise information systems as service implementations

In the Guided Tour of WebSphere Integration Developer series, we introduced you to the concepts needed to build a service-oriented architecture (SOA) application using WebSphere Integration Developer. We showed you each of the component types that you can use to implement your application. Components are black box services that you connect to form your application. The term black box stems from the fact that one component has no knowledge about the inner workings of another component. You can implement components using business state machines, business processes, human tasks, business rules, and much more.

Right now, you are probably getting that strange feeling that everything seems to be a component. Well you are absolutely correct. In the land of SOA, everything is a service and in WebSphere Integration Developer services are implemented using components. If we apply this golden rule to our enterprise information system (EIS), we realize that we want to treat our EIS like a black box too. In other words, we want to call our information system the same way that we call any other component; so we don't have to deal with the detailed EIS logic. In the end, we would like our business logic to live in blissful ignorance of the scary magic in the EIS.

For example, if our back-end system has a delete function that requires special code in our business logic when it calls the EIS, and it requires data in a very specific encoding, then we would like the EIS component to give us a simple, straightforward delete operation to which to can pass our business objects. We want the EIS component to deal with the encoding and the right way to call the EIS.

The EIS component handles the encoding using a specialized adapter that allows the component to talk to a specific EIS. Adapters come in all shapes and sizes (but not colors); some talk to databases, others to flat files in your file system, others to databases, and still others to the functions in your EIS.

You use adapters to call out (outbound) to a back-end system (for example, to delete a patient record from the patient system) or to call in (inbound) to your business application (for example, to let you know a new shiny hammer was added to the hammer database).

Connecting to an EIS is straightforward: you choose the adapter for your particular EIS, and then tell the adapter about the system you want to talk to. Then WebSphere Integration Developer guides you through the steps to create the EIS component, which will be in your module as an import or export, using that adapter. WebSphere Integration Developer will even create business objects that correspond to the data you are working with in the EIS.

As you might recall from the Guided Tour of WebSphere Integration Developer series, because the EIS component is not implemented in your module (the resource adapter implements the EIS component), you access it using imports or exports. An import is a component with an implementation that resides outside the module. It has a binding, such as a Web service binding, to connect to Web services or an SCA binding to connect to other modules. An export is the part of the module that makes a component visible to other modules or applications.

Whether an import or export will be created depends on whether you want to create an inbound or outbound service. If you want to create an inbound service, a resource adapter will notify your application that the information system has changed. It does the notification by calling an export in your module. If you want to create an outbound service, your application will use a resource adapter to connect to an information system and will access data using an import in your application.

Figure 1 illustrates the fundamental adapter concepts. Suppose you are integrating customer information where some of the information is in XML files (flat files as opposed to a structured database) and the same information is in a database. You would probably want to keep that information synchronized in both systems. Now, say an event occurrs where a flat file has been updated with new customer information. The resource adapter uses the export of the module to invoke an operation in the SyncCustomerData component, which is an inbound service request to the module.

This example is rather simple. In other scenarios, you would likely have more components in the module used by the business process component to do its work, and an interface map to transform any data transformations needed for the different back-end systems. Finally, after the process has done the work, it calls a CustomerEISImport operation. The import uses the resource adapter to write the updated information to the database, which is an outbound service request from the module.

Figure 1. Using resource adapters to connect to information systems
Using resource adapters to connect to information systems

In this series, we will introduce you to creating components from existing enterprise information systems, starting by covering the basics of resource adapters.

What is a resource adapter?

Let's look closer at what adapters are. An adapter is a device that enables incompatible things, such as garden hoses or electrical connections, to connect and work together. In the world of business integration, you use a resource adapter to connect your business applications to diverse enterprise information systems so that they can send or retrieve information in a consistent manner. EISs include databases, enterprise resource planning systems, and mainframe transaction processing systems.

A resource adapter is useful in two ways:

  • First, when you author your business applications, the resource adapter automatically discovers what is available in your back-end system and exposes it as services and business objects. The resource adapter defines a common interface that WebSphere Integration Developer uses to talk to your back-end system and discover the services and business objects.
  • Second, at runtime, the component that WebSphere Integration Developer created (with the help of the discovery capability) does all the tricky work of storing and retrieving business data to and from the EIS.

Without adapters, each EIS or application server would have to provide proprietary connection utilities, or worse, developers would have to write custom connection utilities for each EIS and application server. Plus, tools like WebSphere Integration Developer would have to write discovery code that is aware of the vast set of EISs. Fortunately, we have adapters! When a new back-end system comes along, you can rapidly make use of it if you have an adapter for it. With that adapter, WebSphere Integration Developer can discover services and create imports or exports for them, and then your application can talk to the system just like it talks to any other component.

And now a brief word from our standards sponsor

For an adapter to be useful across various platforms, it must adhere to a common specification. WebSphere resource adapters conform to the J2EE Connector Architecture (JCA) 1.5 specification. This specification defines the set of contracts for both the application server and the EIS. Therefore, you can use a SAP resource adapter that conforms to the JCA 1.5 specification on WebSphere Process Server or any other J2EE-compliant server. This is really important because it means a back-end system vendor can provide a single adapter for his system and that different author-time tools and different J2EE-compliant servers can use one adapter.

Wait! Don't run away. You do not have to learn the JCA specification—honest. As an application developer or integration specialist, you do not need to know the specification; you just need to know how to talk to a resource adapter from your application. And, as we saw above, that simply means connecting your component (for example, a BPEL business process) to the import that is set up to use the adapter.

Adapters included with WebSphere Integration Developer

Now let's take a quick look at which adapters are included with WebSphere Integration Developer, and then we'll discuss how to use them.

Previous versions of WebSphere Integration Developer contained only the CICS® and IMS™ resource adapters, but WebSphere Integration Developer version 6.0.2 provides many resource adapters so you can connect to various popular EISs and more basic information systems, such as text files. The following IBM® WebSphere adapters are supported and included in WebSphere Integration Developer. Each adapter in this list complies with the J2EE Connector Architecture 1.5 specification. The first few adapters support only outbound service as noted; all the rest support both inbound and outbound.

  • IBM CICS ECI Resource Adapter Version 6.0.2: CICS (Customer Information Control System) is a transaction processing system used in critical business systems, such as ATMs and airline reservation systems. This adapter supports outbound mode only.
  • IBM IMS Connector for Java™ Version IMS (Information Management System) is a transactional and hierarchal database management system used on mainframes for decades. This adapter supports outbound mode only.
  • IBM WebSphere Adapter for JD Edwards EnterpriseOne Version 6.0.2: JD Edwards EnterpriseOne (now owned by Oracle corporation) is a suite of business applications for customer relationship, management, supply chain management, and financial management for small and medium enterprises. This adapter supports outbound mode only.
  • IBM WebSphere Adapter for Oracle® E-Business Suite Version 6.0.2: Oracle E-Business Suite is a suite of enterprise resource planning (ERP) applications used in areas such as financial management, purchasing, manufacturing, logistics, human resources, and sales.
  • IBM WebSphere Adapter for PeopleSoft Version PeopleSoft products (now owned by the Oracle corporation) are another suite of ERP applications that can be customized to fit specific business needs.
  • IBM WebSphere Adapter for SAP® Software Version 6.0.2: SAP is yet another ERP application provider (but not currently owned by Oracle corporation.) This adapter enables integration through various SAP interfaces to the SAP Web Application Server.
  • IBM WebSphere Adapter for Siebel Business Applications Version 6.0.2: Siebel Business Applications (also owned by the Oracle corporation) is a customer resource planning system. This adapter connects to Siebel applications by calling the Siebel native interfaces to exchange business objects with the Siebel application.
  • IBM WebSphere Adapter for JDBC Version 6.0.2: An EIS can also be a database. You use this adapter to exchange business objects with any database that you can connect to using JDBC.
  • IBM WebSphere Adapter for Flat Files Version 6.0.2: Enterprise information systems are not necessarily behemoth programs running on a mainframe. A small business might be able run smoothly with applications that just store their business data in plain text files. You use the flat file resource adapter to access files, such as comma delimited or XML, in the same way you access another EIS or database.
  • IBM WebSphere Adapter for E-mail Version 6.0.2: As the name suggests, this adapter allows you to use e-mail to exchange business objects with various applications that do not provide programmable or service interfaces. It checks the mailboxes on mail servers for e-mail messages, or sends e-mail messages to a mail server, and converts between e-mail messages and business objects.
  • IBM WebSphere Adapter for FTP Version 6.0.2: Like the WebSphere Adapter for E-mail, the FTP (File Transfer Protocol) adapter helps you communicate with applications that have data that is not easily integrated. It uses FTP get and put commands to exchange business objects with applications. This adapter is useful when you use text files to store your enterprise information, but the files are scattered across locations.

Keep in mind that the CICS, IMS, JD Edwards, Oracle, PeopleSoft, SAP and Siebel adapters included with WebSphere Integration Developer are licensed only for development purposes. This means that you can use them with your WebSphere Process Server local test server. However, before you can use these adapters on a production server you have to obtain a full license. You can use the JDBC, flat file, e-mail, and FTP adapters for both development and production right away.

You can find license information at Software license agreements search ; enter any adapter name from the list above to find the license information. Additional licensing information is available on the IBM WebSphere Adapters V6.0.2 announcement letter. For more information on IBM WebSphere adapters, see the references section at the end of this article.

Importing and configuring the resource adapter

Before you begin using an adapter, you first need to import it as a project into your application. Resource adapters are bundled into Resource Adapter Archive (RAR) files. RAR files are a type of ZIP file that contain the adapter and a set of additional files that help WebSphere Integration Developer (or any other tool) give you options on configuring the adapter. For example, if the system that the adapter communicates with requires a user name, then the information in the RAR file advises WebSphere Integration Developer to display fields for configuring the user name. (You don't really need to know this little tidbit because all you have to do is find the RAR and import it.)

To import the adapter:

  1. Open the resource adapter import wizard by choosing Import - RAR file from the Business Integration view menu. When the resource adapter import wizard opens, don't panic when you see the term connector. The terms adapter and connector are often used interchangeably because you use an adapter to connect to a back-end system. Figure 2 shows the Import wizard.
    Figure 2. Importing a resource adapter
    Importing a resource adapter
  2. In the Import wizard, locate the appropriate RAR file by clicking Browse. For adapters included with WebSphere Integration Developer, you can find them in the Resource Adapters directory located in the root of your WID installation.

In the Resource Adapters directory, you see a directory for each of the adapters. The .rar file is in each adapter directory or a deploy directory in the adapter directory. In Figure 2, we're importing the e-mail adapter and we selected CWYEM_EMail.rar as the connector file. The CW* prefix denotes WebSphere components, and CWY* denotes WebSphere adapter components.

If you browse through the adapter directories, you'll notice a few extra choices of adapters that you can import. Both CICS and IMS have two versions of resource adapters. Usually, you would choose the version in the cics15 or ims15 directories, which contain JCA 1.5-compliant adapters. The adapters in the cics and ims directories are not JCA 1.5 compliant, so you would choose those adapters when your application will run on earlier versions of WebSphere Process Server (don't forget that server versions prior to WebSphere Integration Developer version 6.0 do not support SCA modules). Under the SAP\deploy directory, there are two connector files: CWYAP_SAPAdapter.rar and CWYAP_SAPAdapter_Tx.rar. If you require two-phase commit transaction support, choose the CWYAP_SAPAdapter_Tx version. CWYAP_SAPAdapter just commits data as it is added or modified.

After you have imported the resource adapter, you might need to do additional configuration. The SAP, Seibel, PeopleSoft, JD Edwards, JDBC, and Oracle EBS adapters require additional configuration to complete the setup. You can find the necessary information in the adapter documentation located at For example, PeopleSoft requires a version-specific .jar file to be copied to the adapter project. The .jar file contains the interfaces for the data that you plan to access.

Using the Enterprise Service Discovery wizard

At this point, you are sipping your coffee and admiring your freshly imported adapter. Now the fun begins. The next step in creating services from your EIS is to use the Enterprise Service Discovery wizard. Recall that the discovery wizard uses the adapter to examine the back-end system, and accesses all of the adapters by using imports or exports, and by communicating in a common way defined by the Enterprise Metadata Discovery (EMD) specification.

The EMD specification defines a common interface that resource adapters can use to present available EIS services and business objects to the tools that will use those services and business objects in applications. Any business integration development environment that complies with this specification can discover services using a resource adapter for any EIS in the same way. WebSphere Integration Developer and the WebSphere Adapters listed earlier comply with this specification, with the exception of IBM CICS ECI Resource Adapter 6.0.1 and IBM IMS Connector for Java For a link to this specification, see the references section at the end of this article. Once again though, you do not need to know the details of the EMD specification to use these adapters.

So, using the EMD specification, the Enterprise Service Discovery wizard uses a resource adapter to connect to the EIS and find potential services and business objects. To open the wizard, select File - New - Enterprise Service Discovery. The first page of the wizard gives you the choice of importing the resource adapter, as we described in the previous section. However, before it connects to the EIS, the second page of the wizard asks for connection information like a username and password as Figure 3 shows. This page of the wizard varies depending on the EIS type. For example, when you use the EnterpriseOne adapter, the connection configuration settings do not have the miscellaneous section and the machine credential fields are Environment and Role.

Figure 3. Enterprise information system connection properties
Enterprise information system connection

Some adapters have many configurable options. Keep your eyes open for the ones marked with an asterisk (*) because these are mandatory. You should also consult your resource adapter documentation and your EIS system administrator who has the connection information for your particular system.

After you have connected to the EIS, you are ready to let the wizard find potential services to use in your application. The wizard browses the metadata information of your EIS system and creates service interfaces based on the information in the EIS. For example, Figure 4 shows services that are on a PeopleSoft server. The objects that the wizard finds depend on which EIS type you are using, and what exists in your particular EIS. The E-mail, FTP, Flat File, CICS, and IMS adapters work with local business object definitions, rather than building them by querying your EIS.

Figure 4. Service discovery
Service discovery

Figure 5 shows the next page in the Enterprise Service Discovery wizard. Here you can specify whether you are creating an inbound or outbound service, and what operations will be available for that service. Again, the operations depend on the EIS you are using. Typical available operations include: add new business data to your EIS, modify data, and obtain data. You can specify other operations, such as existsFlatFile or createFlatFile to check if the flat file exists, or to create it in for flat file-based information systems.

Figure 5. Selecting the service type and operations
Selecting the service type and operations

On the last pages of the wizard, you specify which integration module to place the import or export into, whether the resource adapter project should be deployed with your module (you can also install a resource adapter on the server using the administrative console), and various EIS connection properties, such as the database name, user ID, and password.

For CICS and IMS, the wizard builds their services. The wizard pages look a little different for them because they require a specialized enterprise service discovery method. The concept is the same, though: the wizard guides you through the process of creating an EIS import. Enterprise service discovery happens by pointing the wizard to a COBOL or C file that contains definitions of business data that the CICS program or IMS transaction expect. Based on what is in the file, it creates a business object that you can use as input or output to the service operation.

Now that you know how to get connected to an enterprise information system, be sure to read our upcoming articles that give you experience using the enterprise service discovery wizard with different adapters.

Using EIS services

When you finish with the service discovery wizard, you have an import or export that you can use in your module to call your new EIS service in the same way that you call any other service. In this section, we look at how to use the import and export created by the wizard.

Imports and exports

In the enterprise service discovery wizard, you specified or created a module that will use the EIS service. If you open the assembly diagram for that module, you see an import or export, depending on whether you created an outbound or inbound service such as the one in Figure 6.

Figure 6. An import for an outbound EIS service
An import for an outbound EIS service

As we mentioned earlier, when you create an outbound service, the wizard also creates an import. You can now wire any our your components to the import, which allows those components to call the service without having to know anything about the underlying EIS. The import binding created by the wizard contains all the information that the adapter needs to do its work and get your business data to the back-end system.

Conversely, when you create an inbound service, the wizard creates an export. Yes, that sounds a bit confusing. Think of it this way: you are trying to provide a way for the adapter to call your application. The only parts of a module that are visible from outside of the module are exports. An export gets configured with information about the adapter that calls it. The adapter polls for events in the EIS. When an event occurs, the adapter calls your module and passes the business data related to that event to your module using the export.

Imports and exports require an interface, which is the contract between your business application and the EIS service that your module is calling, or that is calling your module. When the wizard finishes, it creates an interface for the import or export based on what it found in the EIS. For example, look back at the operations shown in the wizard in Figure 5. Figure 7 shows the resulting interface:

Figure 7. The PurchaseOrder interface created by the Enterprise Service Discovery wizard
The PurchaseOrder interface

As you know, an interface operation requires parameters that describe the business data that is sent from or returned to the operation. You already know about business objects from the previous series, but the resource adapter requires some additional information when it communicates with the EIS. If you look closely at Figure 7, you'll notice each parameter type ends with "BG". The parameter for each operation that the wizard creates is actually a business graph (hence the BG suffix) which you can think of as an enhanced business object. A business graph is a container that includes a standard business object plus a verb and change summary information. A verb, such as create, update, or delete, specifies how you'll use the data in the business object. The change summary is a snapshot of what changed in the business object since it came out of the information system. Figure 8 shows an example business graph from the interface shown in Figure 7.

Figure 8. The PurchaseOrder business graph
The PurchaseOrder business graph

When you specify a verb in a business graph, it tells the resource adapter what to do with the information in the business object. Because each adapter for a particular EIS knows how to work with information in that system, the adapter also knows how to create or update the system with the business data.

When you do not specify a verb, the resource adapter uses the change summary information to change the information system. The change summary also contains a verb that describes what to do with the changed data. Not all resource adapters work with a change summary; so you need to consult your adapter documentation to find out what your resource adapter expects. A change summary reduces the overhead of processing a very large amount of information that could be in a business object. After all, you could have a business object that contains thousands of attributes, and yet you might have just updated, say, a customer phone number. With the change summary, the resource adapter knows just to perform an update of the customer phone number attribute.

Java Connector Architecture flyover

If you are curious about Java Connector Architecture (JCA), we'll give you a quick overview to get you started. Each type of enterprise information system uses its own non-standard, vendor-specific architecture to connect to an application server. At one time, each application server had to provide its own tools and frameworks to assist with integrating EIS connectivity into applications that were deployed on the server, which meant that applications that used the EIS were not portable between application servers.

Now JCA defines a standard architecture for connecting between applications and each type of EIS. As long as an EIS has a resource adapter that conforms to the specification, any application deployed to a J2EE application server can connect with that EIS. The specification enables a resource adapter to be provided for each EIS in a standary way. As Figure 9 shows, you can then connect the resource adapter to an application server using a standard system contract. This technique decouples each EIS from the server, because only the resource adapter needs to understand the EIS interface and connectivity issues. So applications access different EIS in the same way using a standard application contract. Although Figure 9 shows one resource adapter for simplicity, you would connect additional resource adapters to the server and used them in applications in the same way.

The system contract defines how the adapter handles transactions and security. It also defines how to handle lifecycle, connection and work management, and inflow transactions and messages (inbound service). The application contract defines a standard application programming interface that enables applications to use each resource adapter consistently.

Figure 9. Java Component Architecture
Java Component Architecture

For more information on JCA, see the references section at the end of this article.


This concludes our introduction to adapters. Hopefully, you have learned that the adapter space, despite its scary terminology, is actually straightforward, and that getting connected to your enterprise information system, database, flat files, and e-mail systems is fast and easy. When you find the right adapter for that system, WebSphere Integration Developer uses that adapter to determine what you can do with the back-end system, and then creates services, operations, and business objects that your business logic can use. This means that, using a couple of wizards, you have services that you can call from your business logic exactly the same way that you would call any other reusable service. Your business logic code does not need to know the details of what happens behind the adapter curtain.



Get products and technologies



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Business process management on developerWorks

Zone=Business process management, WebSphere, SOA and web services
ArticleTitle= Getting connected with WebSphere Integration Developer adapters : Part 1, An introduction to connecting with adapters