Overview of the Adapter Process

iWay Service Manager is designed for hosting adapters and for enabling messages received from one adapter to be sent to another adapter. In general, the messages arriving at the server have three main parts as illustrated below:

Payload. The actual content of the message to be processed.

Message headers. In HTTP, these are the HTTP headers. They may also include encoding such as multipart MIME headers. In SOAP, these are the SOAP headers and, in SOAP with attachments, the MIME headers. In MQ Series, these values are in the MQMD header.

Transport. For instance, in HTTP, this is TCP. In SOAP, this can be HTTP, SMTP, or FTP.

An adapter has to handle all three layers of the message and iWay Service Manager is set up to make it easy to configure each of these individually. The way these layers map onto functions in iWay Service Manager is shown in the diagram below.

The transport is handled by a listener (for incoming messages where iWay Service Manager is acting as a server) and an emitter (for outgoing messages where iWay Service Manager is acting as a client). This is the level where components (listeners and emitters) are written. In most cases, the transport components delivered with the product are sufficient; there is no need to create new listeners or emitters to set up an adapter.

The headers are handled by dispatching and routing. This is the middleware level where most of the added value of iWay Service Manager lies and where the iWay preparser exits are executed. Although a complete set of exits is provided with iWay, it may be necessary to create a new exit, for security or for formatting a message into XML. Although a non-XML message can be routed through the system and acted upon by later exits, iWay Service Manager operates most effectively with XML documents. If your incoming message is not natively in XML and if one of the standard iWay-provided preparsers does not suit your needs, you will want to write a preparser exit.

Finally, the message is handled by the application level. This is where iWay business agents are executed and the level where integration applications are written. iWay business agents are exposed as business services in the iSM console. Although a large number of business agents are provided with the product, it may be necessary to write a custom business agent for specific programming needs. In many cases, it may be enough to assemble the business agents provided into a process flow. For more information, see the iWay Designer User's Guide.

In implementation, this step is more conducive to application developers. There are various exits that can be used in dispatching and routing. If these are added, the diagram looks like:

This diagram illustrates the flow of a document as seen by a single adapter.

The first step after receiving the message is always to verify the security of the message – that is, to verify that the sender is authorized, to check that the message has not been changed, and to decrypt any part of the message that has been encrypted. iWay has security exits for many common security algorithms including W3C Digital Signature, ebXML, and PGP, among others. It is also possible from the exit to check credentials in an external security manager such as Netegrity, Active Directory, or an LDAP server.

As all incoming messages need to be changed to XML before their payloads can be handled, there is a dispatching step that is called for non-XML messages that encodes their contents as XML. This is called a preparser since it occurs before the message is parsed into the iWay document tree. Similarly, there is a step called preemitter that can encode an XML document into a non-XML format. iWay Service Manager supports many non-XML formats for preparsing and preemitting thereby eliminating the need to code a specific exit.

Finally, there is an exit to validate the contents of the payload. This validation can use iWay Service Manager rules described in iWay Service Manager Rules System or it can use an XML validator such as Apache XERCES. It is also possible to do both.

Because an integration application generally needs two adapters, a typical use of iWay Service Manager consists of two such adapters, one for handling the incoming message, for example, from SAP, and one for handling the outgoing message, for example, to PeopleSoft. This is illustrated below.

The arrow on the diagram shows the one-way message. This is a one-way adapter as the message can only come in on the left and go out on the right. This configuration would support two scenarios:

Although the previous diagram shows a single business agent, business agents can be chained or be part of a flow. In this case, there can be multiple outputs for a single input either to the same adapter or to different adapters. This is illustrated below.

Adapters can also be bi-directional as shown below.

This is a bi-directional adapter as there is a listener and emitter on both sides. Messages can come in on the right or the left and be emitted on the left or the right, respectively.

To accomplish its mission, iWay Service Manager executes a defined flow as the message travels from input to output. This flow is standard for all messages, but the execution steps selected and the processing at those steps varies by message type. The steps of the flow take the document from input, conversion to XML, parsing, transformations, rules validations, business processing, and then back through transformations, conversion from XML to the native transmission format, and then transmission through a port itself. Each of these steps is performed by an exit, a routine invoked to perform the specific action at that step.

In some respects, iWay Service Manager can be thought of as simply a platform for the execution of exits. No document processing is performed by the server itself. Instead, the server assembles the appropriate exits to accomplish the business purpose of the document.

Application programmers can assemble flows by using pre-built exits. These exits can be supplemented by application-specific code that can be intermixed with and scheduled along with exits offered by iWay.

The iWay Service Manager array of protocol handlers can also be supplemented by new protocols tailored to specific application situations. These protocol handlers, called listeners and emitters, service the input channels and output ports that represent the iWay Service Manager interface to the outside world.


iWay Software