WID (Websphere Integration Development) Guide

WID Development Guide

WID Tutorials and Development Guide


INDEX

Chapter 1 Mediation flows overview

Chapter 2 Trace Primitive

Chapter 3 Custom Mediation Primitive

Chapter 4 Message Filter Primitive

Chapter 5 Message Logger Primitive

Chapter 6 Flow Order Primitive

Chapter 7 FanOut Primitive

Chapter 8 FlatFile Inbound Adapter

Chapter 9 JDBC Inbound Adapter

Chapter 10 Message Element Primitive

Chapter 11 Event Emitter Primitive

Chapter 12 Database Lookup Primitive

Chapter 13 WTx Primitive


Revision HistoryName Date Summary Of Changes Version

Ravi, Reddy 03/18/2011 Initial creation of document. 1.0


Chapter 1 Mediation flows overview

Mediation flows intercept and modify messages that are passed between existing services (providers) and clients (requesters) that want to use those services. They are most commonly used for transforming data and accessing header information, such as JMS, MQ

Introducing mediation flows between services enables you to process the messages that are being passed between these services. A message is a communication sent from one application or service to another application or service. Mediation flows provide the logic that processes the messages. For example, mediation flows can be used to find services with specific characteristics that a requester is seeking and to resolve interface differences between requesters and providers. For complex interactions, mediation primitives can be linked sequentially. Typical mediations include:

Transforming a message from one format to another so that the receiving service can accept the message

Conditionally routing a message to one or more target services based on the contents of the message

Augmenting a message by adding data from a data source

Development Steps

Create a mediation project in WID tool.

Create a MemberBO with the properties of 1) id 2) firstName 3) lastName

Create an input service interface with “memberRegister” operation and set the request parameters to the service operation.

Create an output service interface with “memberDetails” operation and set the request parameters to the service operation.

Drag and drop the java primitive in assembly diagram name and configure the primitive with output service interface and join the mediation and primitive boxes in assembly diagram.

Select java primitive and right click on primitive and implement the interface by selecting “Generate Implementation” in the panel.

Double click on mediation box in assembly diagram and go inside the mediation and join the input and output service partners.

* Note: See below images (figures) for above steps.



Once done with the above steps deploy and start the application on server (WPS/WESB)

Right click on mediation box in assembly diagram select the “Test Component” in the panel and pass the member information and see the output information by putting debug(system out) statements in *serviceImpl class.


Chapter 2 Trace PrimitiveTrace mediation primitive to develop and debug mediation flows, and to specify trace messages to be logged to the server logs or to a file. The trace messages can contain service message object (SMO) message content and other information about the mediation flow.

Trace mediation primitive has one input terminal (in), one output terminal (out) and one fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message. The input message triggers the writing of a trace message and if the tracing is successful, the out terminal propagates the original message. If an exception occurs during the processing of the input message, the fail terminal propagates the original message, together with any exception information.

UsageTrace mediation primitive to write your own trace messages to help with developing and debugging mediation flows.Trace can use the destination property to determine where a trace message is written to: either the server system logs, the User Trace log file, or to a specified file.

Development Steps







Drag the trace primitive from Trace palette into mediation flow and configure trace properties.



Trace primitive of member information writing into defined log file.


Chapter 3 Custom Mediation PrimitiveCustom Mediation primitive to implement your own mediation logic in Java code. The primitive combines the flexibility of a user-defined mediation primitive, with the simplicity of a pre-defined mediation primitive. You can add new terminals and create your own properties, and this allows you to create complex transformations and routing patterns.

UsageCustom Mediation primitive has one input terminal (in), one output terminal (out), and one fail terminal (fail).

The input terminals are wired to accept a message; the output and fail terminals are wired to propagate the message. The input message is passed as the input parameter to the Java code. If the operation returns successfully, the response from the Java code is propagated to an output terminal. If the operation returns unsuccessfully, the fail terminal propagates the original message,

Development Steps







Drag the custom mediation primitive from Transformation palette into mediation flow and configure primitive properties.



Mediation output.


Chapter 4 Message Filter PrimitiveThe Message Filter mediation primitive uses XPath expressions to allow you to direct messages, which meet certain criteria, down different paths of a flow. The Message Filter mediation primitive has one input terminal (in), one fail terminal (fail), and multiple output terminals, (one of which is the default terminal). The in terminal is wired to accept a message and the other terminals are wired to propagate a message.

UsageYou can use the message filter primitive to check that the inbound message meets some criterion. If the criterion is not met you can raise a fault using the Fail mediation primitive, or send an error response.

The message filter mediation primitive lets different messages take different paths. For example, a message might need forwarding to different service providers based on the request details.

Development Steps

Follow same steps from previous chapters for creating the mediation in WID tool.

Drag the message filter primitive from Routing palette into mediation flow and configure primitive properties.

Configure the properties for message filter primitive; under terminals create two new output terminals memberSuccess and memberFailure.

Under details (properties) configure the newly created terminals for example

1) memberSuccess used filter condition if input member id is >= 1001 it will route the message to SuccessTransformation.2) memberFailure used filter condition if input member id is < 1000 it will route the message to FailureMediation.




Chapter 5 Message Logger PrimitiveThe Message Logger mediation primitive can store messages in a relational database or in other storage mediums if you use the custom logging functionality. The Message Logger mediation primitive logs messages to a relational database using an IBM-defined database schema (table structure). It can write to other storage mediums, such as flat files, through the use of the custom logging facility.

The Message Logger mediation primitive logs an XML transcoded copy of the service message object (SMO). The default behavior is to log just the message payload but the mediation primitive can be configured to log the complete SMO, or a part of the SMO defined by an XPath expression. Along with the message contents the mediation primitive also logs a timestamp, the message identifier, the primitive instance name, the mediation module instance name and the SMO version number.

UsageYou can use the Message Logger mediation primitive to store messages that you process later. The logged messages can be used for various purposes. For example, you could use the logged messages for data mining, message replay or for auditing.

Because the data is logged as XML it can be processed by any XML-aware application. Many databases, including DB2, provide built-in capabilities to handle XML contained in a database column. Each Message Logger mediation primitive must have a Handler implementation class specified. If you have multiple Message Logger mediation primitives they can either use the same Handler implementation class or any number of appropriate Handler implementation classes. You can, optionally, provide Formatter implementation classes, Filter implementation classes, or both.

By default, the default Handler implementation class logs every message to a file stored in the system temporary directory as defined by the java.io.tmpdir system property The file will be called MessageLog.log

On a Unix system typically /tmp or /var/tmp On a Windows C:\Documents and Settings\<user>\Local Settings\Temp.

Development Steps


Drag the message logger primitive from tracing palette into mediation flow and configure primitive properties.




Chapter 6 Flow Order PrimitiveYou can use the Flow Order mediation primitive to customize the flow by specifying the output terminals to be fired. The Flow Order mediation primitive does not change the input message.

The Flow Order mediation primitive has one input terminal (in) and any number of output terminals. The in terminal is wired to accept a message and the other terminals are wired to propagate a message. The output terminals are fired in the order that they are defined on the primitive, with each branch completing before the next starts. Each output terminal is fired with an unmodified copy of the input message.

UsageYou can use the flow order mediation primitive anywhere that you want to branch a flow. A named output terminal is created for each branch. Each branch of the flow is completed before the next terminal is fired.

The only exception to this rule is that if an Asynchronous Service Invoke mediation primitive is reached, the service is called but the flow order does not wait for the service invocation to complete before moving on to the next branch.

If an exception is thrown by any of the down stream mediation primitives and they do not handle it themselves (for example, via their fail terminal), any remaining flow branches are not fired.

Development Steps


Drag the flow order primitive from routing palette into mediation flow and configure primitive properties.

Create custom mediation primitives for each output terminals of flow order primitive for logging to test the terminals are firing out or not.

You can verify the outputs in the console after running an integration test of the mediation with in WESB.




Chapter 7 FanOut PrimitiveThe Fan Out mediation primitive lets you iterate through a single input message, that contains a repeating element, and store each instance of the repeating element in the service message object (SMO) context. The Fan Out mediation primitive does not change the input message.

Default mode sends the entire input message once. Generally, the default mode is needed because a Fan In mediation primitive requires a preceding Fan Out mediation primitive.Iterate mode lets you iterate through a single input message that contains a repeating element. Every occurrence in the repeating element, which you specify using an XPath, is processed. The Fan Out mediation primitive has one input terminal (in), two output terminals (out and no Occurrences), and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message..

UsageFan Out to broadcast the responses (message) into different service paths i.e. into multiple output messages. For example, customer order information can broadcast into shipping and billing services.

Development Steps


Drag the fan-out primitive from routing palette into mediation flow and configure primitive properties.

Fan-out primitive broadcast the message to difference service (Member, Provider and Pharmacy services) callouts with in mediation flow.

You can verify the outputs in the console by placing debug statements in service *Impl classes after running an integration test of the mediation with in WESB.




Chapter 8 FlatFile Inbound Adapter

Flat File inbound adapter can create integrated processes that include the exchange of data with the local file system, without special coding.

UsageFlat File adapter to read data from a file in the local file system, use it in an application on websphere process server (WPS) or websphere enterprise service bus (WESB), and send it back to the local file system. You can also use the adapter to poll a directory in the local file system for new files and send them to an application for processing.

The adapter can be used to read and write to any type of file stored in the local file system. It can:

Create new files Append to or overwrite existing files

Retrieve the content of a given file, retrieve a list of file names in a directory, or delete a file

Check whether a particular file exists

Poll a directory for new files and send them to an application for processing

Development Steps


Drag the flat file inbound adapter into assembly diagram and set the following base properties like.

Event Directory Path,Archive Directory Path (It’s not mandatory),File Type Patterns.

Flat File inbound adapter uses the IBM FlatFile object.

Create a service partner to print the input file content.

Note: See below images (figures) for above steps.



Chapter 9 JDBC Inbound AdapterJDBC inbound adapter can create integrated applications that include the exchange of information with a database; it enables communication between an application running on Websphere Process Server or Websphere Enterprise Service Bus and a database. By using the adapter, an application can send requests (read, create, update, or delete) to the database, as well as receive events from the database, often without the need for SQL code.

UsageThe adapter provides a standard interface that integrates with diverse database software vendors and versions; it supports any database server with a Java™ Database Connectivity (JDBC) driver that supports the JDBC 2.0 or later specification. Examples of such servers include IBM® DB2®, Oracle, Microsoft® SQL Server, Sybase, Derby, and Informix®.

The adapter uses business objects to exchange data between the application and the database, so the application does not need to use the JDBC application programming interface (API). Business objects are containers for application data that represent business functions or elements, such as a database table or the result of an SQL query. The adapter understands the data format provided by the application, and can process the data, perform the operation, and send the results back in that format.

Development Steps


Drag the JDBC inbound adapter into assembly diagram and set the following base properties like JDBC Driver Type and Connection URL

IDE pops up to browse the schema to select the table or view to generate the business objects.

JDBC inbound adapter shows the options for the operations like CreateUpdateDelete

A service interface gets created based on the selected operations from above step.




Chapter 10 Message Element PrimitiveThe Message Element Setter mediation primitive provides a simple mechanism for setting message content; it does not change the type of the message. You can change, add or delete message elements by setting the mediation primitive properties. If you want multiple message changes you can set multiple targets. Multiple target elements are set sequentially, in the order in which they are specified; this means that elements can build on each other.

You can set target elements to a constant value, or to a value copied from somewhere in the input service message object (SMO). If a target element you specify does not exist, it is created in the SMO. You can also delete message elements, if they are optional or repeating elements.

UsageIt is often useful to combine the Message Element Setter mediation primitive with other mediation primitives. For example, you can use the Message Element Setter mediation primitive if you need to manipulate data, before or after the Database Lookup mediation primitive is invoked..

Development Steps


Drag the Message Element primitive from routing palette into mediation flow and configure primitive properties.







Chapter 11 Event Emitter Primitive

The Event Emitter mediation primitive sends out events, during a mediation flow. Because the events are generated in the form of Common Base Events (CBE) they have a standard XML-based format. The events are sent to a Common Event Infrastructure (CEI) server. For information on CEI resources and services refer to the runtime product documentation and runtime online help.You can decide whether generated events contain the message being processed, or not.

If you set the Root property, you can generate events that contain all or part of the message being processed. The Root property is an XPath expression that specifies the section of the Service Message Object (SMO) that is included in the CBE. The Root property can specify the complete SMO, a sub tree or a leaf element.

Note: at run time, if the Root value does not match any of the elements in the SMO, the message being processed is not included in the generated event. If you do not set the Root property; any generated events do not contain the message being processed.

Usage

Use the Event Emitter mediation primitive to emit significant business events from inside a mediation flow. The Event Emitter mediation primitive has one input terminal (in), one output terminal (out) and a fail terminal (fail). The in terminal is wired to accept a message and the other terminals are wired to propagate a message. The out terminal propagates the original message. If an exception occurs during the processing of the input message, the fail terminal propagates the original message, together with any exception information contained in the fail Info element.

Development Steps


Drag the Message Element primitive from routing palette into mediation flow and configure primitive properties.







Chapter 12 Database Lookup Primitive

The Database Lookup mediation primitive can add to, or change, messages. It does this using information from a user-supplied database. This mediation primitive looks up values from a database and stores them as elements in the message. The information obtained from the database might need converting to the correct type to be stored in the message. This is specified using the Message value type property. If the information obtained from the database cannot be converted into the type expected by the message, then an exception occurs.

If a message element already exists in the message then the old value is overwritten with the new value. If the new value is not compatible with the element type defined by property Message value type, then an exception occurs. The Database Lookup mediation primitive needs various database information, including a key. The key is found using a property called Key path. If the Key path key does not exist in the input message, then an exception occurs.

The Database Lookup mediation primitive has one input terminal and three output terminals. The input terminal is wired to accept a message and the output terminals are wired to propagate a message. One output terminal is used if the Key path key is located both in the message and the database. In this case, the information obtained from the database is stored in the message and the updated message is propagated. Another output terminal is used if the Key path key is found in the message but not in the database. In this case, the original message is propagated unchanged. The last output terminal is used for failure output. If an exception occurs during the processing of the input message, then the fail terminal propagates the original message, together with any exception information

Usage

You can use the Database Lookup mediation primitive to ensure information in a message is up-to-date. You can use the Database Lookup mediation primitive to add information to a message, using a key contained in a message. For example, the key could be an account number.

It is often useful to combine the Database Lookup mediation primitive with other mediation primitives. For example, you might use an XSLT mediation primitive to manipulate data, before or after the Database Lookup is invoked.

Development Steps



Drag the Database Lookup primitive from transformation palette into mediation flow and configure primitive properties.






Chapter 13 WTx Primitive

The WTx Map primitive is a component of the Websphere Transformation Extender for Websphere Enterprise Service Bus (Websphere ESB).Within a Websphere ESB mediation flow, a series of steps is used to process a message. A mediation flow node performs each step. The WTX Map primitive is a mediation flow primitive that you can use in mediation flows. It runs a Websphere Transformation Extender map within a mediation flow. The WTX Map primitive uses a service message object (SMO) as its input, runs a Websphere Transformation Extender map that you specify, and creates one or more service message objects as its output.

The map that the WTx Map primitive runs can either is a compiled map that is redeployed to the server, or a source map that is compiled when the mediation flow is built and deployed as part of project deployment. The map can have multiple input cards, but the WTx Map primitive only has a single input terminal.

The service message object, which arrives at the input terminal, might be complex. Specific data paths, both simple and complex, might be routed to specific input cards. You can specify /, /body,/headers, or browse for your own XPath expression. If a complex path is routed to an input card, the input card should contain the corresponding XML schema. If a simple path, such as the path to a single string element, is routed to an input card, the card should contain a standard Websphere Transformation Extender type tree; the type tree is used to parse the input data.

Any cards that did not receive a message obtain data from the adapter that is specified on them. The map can have multiple output cards. Select which output cards to connect to other primitives in the mediation flow. If the output terminal for an output card is connected, a service message object is built, and propagated down the mediation flow. The data produced by each connected output card is sent to a specific data path in the service message object its terminal generates. If the output terminal for an output card is not connected, the data is sent to the adapter that is specified on the card.

The WTx Map primitive is contained in the Websphere Transformation Extender drawer of the Websphere Integration Developer mediation flow palette. Use the mediation flow palette to add WTx Map primitives in the mediation flows you are creating in the Mediation Flow editor. Drag primitive objects from the palette onto the Mediation Flow editor, and create connections, also called wires, between two primitives.

The WTx Map primitive is not an SCA export, and can not be used to trigger the execution of the mediation flow.

Development Steps



Drag the wtx primitive from websphere wtx palette into mediation flow and configure primitive properties.

Configure the compiled maps in details properties.

Configure the input and output map cards to appropriate business objects.








Technology

WID (Websphere Integration Development) Guide